home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Workbench / dosdrivers / A!FF4313.LHA / FFS43_13 / CommandHandling next >
Encoding:
Text File  |  1996-07-15  |  3.8 KB  |  101 lines
  1.  
  2.     $Id: CommandHandling,v 1.2 1996/07/15 18:40:09 heinz Exp $
  3.  
  4. Command Sets for Devices
  5. ========================
  6.  
  7. There has always been the problem that people made incompatible
  8. extensions to the device command set. Doing a low level format on a
  9. TD_GETGEOMETRY trackdisk command is probably the worst example for
  10. this that anyone can think of.
  11.  
  12. Amiga Technologies intends to solve this problem now by specifing
  13. new rules that EVERY device has to adhere if it wants to be
  14. compatible to any OS release beyond OS 3.1 (V40).
  15.  
  16. WARNING!
  17. ========
  18.  
  19. If you don't follow these rules when writing or updating a device
  20. driver, we will have to list your device publically as violating the
  21. Amiga Technologies programming standards! And it will most likely
  22. cause a system crash, which most likely isn't satisfactory for your
  23. customers!
  24.  
  25.  
  26. The four golden Rules for Device development
  27. ============================================
  28.  
  29. Rule #1: Support IOERR_NOCMD
  30. ----------------------------
  31.  
  32. In 1991, Commodore specified publically and in writing that any
  33. Exec style device must return IOERR_NOCMD on any unknown command
  34. value [RKM Libraries, 3rd Edition, page 924]. Note that this
  35. specification was for compatibility to OS 2.0 and that five years
  36. have gone by in the meantime. There was enough time to adapt.
  37.  
  38.     Returning IOERR_NOCMD on any unknown command value is a *MUST*!
  39.     If you don't do this, you break things!
  40.  
  41. Remember, this is an old rule. We can no longer tolerate violations
  42. of this rule!
  43.  
  44.  
  45. Rule #2: Don't modify Reserved Command Semantics
  46. ------------------------------------------------
  47.  
  48. Up to and including OS 3.1 (V40), custom device commands usually
  49. started at CMD_NONSTD. Each developer added commands for custom
  50. device features at will. This lead to messy and incompatible
  51. devices and strange compatibility tricks to identify device
  52. capabilities.
  53.  
  54. As of January 1st, 1996, Amiga Technologies reserves two ranges in
  55. the set of command values for future enhancements. Only commands as
  56. specified by Amiga Technologies may be used here. It is illegal for
  57. a device developer to randomly "add" custom commands or
  58. command features within these reserved areas!
  59.  
  60. There are 65536 command values posisble with io_Command:
  61.  
  62.     $0000 - $3fff       old style and 3rd party commands
  63.     $4000 - $7fff       RESERVED AREA!
  64.     $8000 - $bfff       old style and 3rd party commands
  65.     $c000 - $ffff       RESERVED AREA!
  66.  
  67. To say it again: Commands in the reserved areas may only be
  68. assigned and specified by Amiga Technologies. Any "custom"
  69. implementation of these commands or other commands in these
  70. reserved areas is illegal and violates programming standards!
  71.  
  72. As of this writing, not that many new style commands have been
  73. defined. The interface to new style commands is described in a
  74. separate document "NewStyleCommands".
  75.  
  76.  
  77. Rule #3: Check for new style commands before using them
  78. -------------------------------------------------------
  79.  
  80. Have you read "NewStyleCommands" yet? Yes? Then you know that you
  81. may only use new style commands after checking the device type and
  82. capabilities via the new style NSCMD_DEVICEQUERY.
  83.  
  84.  
  85. Rule #4: Check the IORequest you get in OpenDevice
  86. --------------------------------------------------
  87.  
  88. Some devices like SANA-II devices need an IORequest that is larger
  89. than a minium IORequest or a standard IOStdReq. All devices should
  90. check in their OpenDevice code if the mn_Length field of the passed
  91. in request structure is of at least the needed minimum size before
  92. accepting it. A good device will fail to open if the request is
  93. "too short". Do not check for an exact size as the caller might
  94. have added some private extensions for convenience. This check need
  95. not and should not be present in the BeginIO code, just in the
  96. OpenDevice code of the device. You can't safely handle commands for
  97. the wrong type of request structure!
  98.  
  99. Heinz Wrobel
  100. <heinz@amiga.de>
  101.