home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / DevInfo / DeviceDevelopment / NSD-DeviceSpecifics < prev    next >
Encoding:
Text File  |  1996-10-13  |  5.8 KB  |  140 lines
  1.  
  2.     $Id: NSD-DeviceSpecifics 1.3 1996/10/13 21:30:02 heinz Exp $
  3.  
  4.  
  5. Device specific requirements
  6. ============================
  7.  
  8. Depending on the type returned by NSCMD_DEVICEQUERY, a device may
  9. support device specific commands in the $C000-$FFFF range.
  10.  
  11. There may also be a minimum list of requirements for some types of
  12. devices.
  13.  
  14. If an NSD device type is not listed below, no device specific
  15. commands are defined for it at this time. The device might still
  16. support special custom 3rd party commands outside the reserved
  17. ranges, though. If an NSD device type is listed below, the device
  18. driver must conform to the mentioned specifications. V40 device
  19. commands from devices that are part of the group of an NSD device
  20. type may not be redefined in their meaning. A new style device
  21. specific command may possibly match an old style extended command
  22. exactly to avoid future identification troubles or code
  23. misunderstanding.
  24.  
  25.  
  26. Device specific commands and behaviour
  27. ======================================
  28.  
  29.  
  30. NSDEVTYPE_TRACKDISK
  31. -------------------
  32.  
  33.     May support all V40 trackdisk.device commands unmodified and
  34.     possibly HD_SCSICMD as scsidisk.device is obviously a trackdisk
  35.     like driver. Also the V40 commands for mfm.device or cd.device
  36.     may be implemented with their original meaning only.
  37.  
  38.     As always, if the device doesn't support a command, IOERR_NOCMD
  39.     must be returned for the respective command. 3rd party commands
  40.     may be added in slots that don't conflict with the V40 command
  41.     sets listed for NSDEVTYPE_TRACKDISK or the reserved areas.
  42.  
  43.     A new style trackdisk like device written according to a
  44.     revision of NSD predating revision 1.4 may also return this new
  45.     identifier for TD_GETDRIVETYPE.
  46.  
  47.         #define DRIVE_NEWSTYLE  (0x4E535459L)   /* 'NSTY' */
  48.  
  49.     It used to be a requirement to return the DRIVE_NEWSTYLE
  50.     identifier. This requirement has been removed, and in fact it
  51.     is recommended to *not* change the original specification of
  52.     TD_GETDRIVETYPE anymore for an NSD device.
  53.  
  54.     You should use TD_GETGEOMETRY on a new style driver to obtain
  55.     geometry hints if needed.
  56.  
  57.     At the moment, only four new style commands and their ETD
  58.     counterparts in the device specific range may be implemented.
  59.  
  60.     #define NSCMD_TD_READ64     0xC000
  61.     #define NSCMD_TD_WRITE64    0xC001
  62.     #define NSCMD_TD_SEEK64     0xC002
  63.     #define NSCMD_TD_FORMAT64   0xC003
  64.  
  65.         These commands behave almost like the trackdisk commands
  66.         CMD_READ, CMD_WRITE, TD_FORMAT, respectively, but support 64
  67.         bit handling for large storage devices. The upper 32 bits,
  68.         bit 32 to 63, need to be put into io_Actual before the
  69.         commands are executed. io_Actual can be named io_HighOffset
  70.         in that case.
  71.  
  72.     To implement ETD functionality for new style commands, an
  73.     internal bit has been defined to get the correct command
  74.     values, which may be useful as mask for device implementors.
  75.  
  76.         #define NSCMD_TDF_EXTCOM (1<<13) /* for internal use only! */
  77.  
  78.  
  79.     Similar to the original trackdisk.device specification, this
  80.     bit splits the reserved NSD range for trackdisk like NSD
  81.     commands in half and allows for an easy extension of the NSD
  82.     command set for trackdisk like devices in the future.
  83.  
  84.     So for e.g. NSDCMD_TD_READ64, the corresponding
  85.     NSCMD_ETD_READ64 would use the command value 0xE000, as the bit
  86.     needs to be set for the ETD versions of all device specific NSD
  87.     commands if they are defined. Currently these ETD commands are
  88.     defined and may be implemented:
  89.  
  90.     #define NSCMD_ETD_READ64     (NSCMD_TD_READ64|NSCMD_TDF_EXTCOM)
  91.     #define NSCMD_ETD_WRITE64    (NSCMD_TD_WRITE64|NSCMD_TDF_EXTCOM)
  92.     #define NSCMD_ETD_SEEK64     (NSCMD_TD_SEEK64|NSCMD_TDF_EXTCOM)
  93.     #define NSCMD_ETD_FORMAT64   (NSCMD_TD_FORMAT64|NSCMD_TDF_EXTCOM)
  94.  
  95.     If you choose to implement the basic four 64 bit commands, you
  96.     must implement all four of them, even if some of them would
  97.     possibly return dummy results. The ETD counterparts may only be
  98.     implemented if the basic four 64 bit commands are implemented.
  99.     If the ETD counterparts are implemented, all of them must be
  100.     implemented. A partial implementation with some 64 bit commands
  101.     returning IOERR_NOCMD is not acceptable.
  102.  
  103.     A detailed description of the 64 bit commands can be found
  104.     in the document "trackdisk64", which can be found in the
  105.     directory "DevInfo/TrackDisk64" on the Amiga Developer CD 1.1.
  106.     Implementors are required to read this document.
  107.  
  108.     IMPORTANT NOTE: mfm.device is considered to be a trackdisk like
  109.     device, too. It implements a private command 29 "(twentynine")
  110.     which may not be redefined for any 3rd party purpose! While
  111.     this command won't be documented, it is a standard V40 command
  112.     number!
  113.  
  114.  
  115.  
  116. NSDEVTYPE_SANA2
  117. ---------------
  118.  
  119.     The device should be at least SANA-IIR2 conformant. If at all
  120.     feasible, it should support multiple protocol stacks.
  121.     An NSD SANA device should not fail on OpenDevice() if it gets a
  122.     NULL ios2_BufferManagement pointer. Otherwise a general query
  123.     would not be possible according to NSD. As the original NSD
  124.     specification allowed for a small request when doing a query,
  125.     an NSD SANA-II device may also accept requests that don't
  126.     contain buffer management tags on OpenDevice() if suitable
  127.     mn_Length checks are added to the commands. It may be wise to
  128.     set up "dummy" callbacks in the device code for missing buffer
  129.     management tags that return failure, to make safe use of the
  130.     device even for broken SW. As a future NSD revision may
  131.     introduce a general command to set up device specific
  132.     configurations in a general way after OpenDevice() succeeded,
  133.     setting up buffer management should be set up appropriately by
  134.     implementors, so that a device may easily be adapted to support
  135.     an improved NSD specification.
  136.  
  137.  
  138.  
  139. *** EOT ***
  140.