NSD Device Specifics

Revision

Version 1.4 (2013-04-11)

Device specific requirements

Depending on the type returned by NSCMD_DEVICEQUERY, a device may support device specific commands in the $C000-$FFFF range.

There may also be a minimum list of requirements for some types of devices.

If an NSD device type is not listed below, no device specific commands are defined for it at this time. The device might still support special custom 3rd party commands outside the reserved ranges, though. If an NSD device type is listed below, the device driver must conform to the mentioned specifications. V40 device commands from devices that are part of the group of an NSD device type may not be redefined in their meaning. A new style device specific command may possibly match an old style extended command exactly to avoid future identification troubles or code misunderstanding.

Device specific commands and behaviour

NSDEVTYPE_TRACKDISK

   May support all V40 trackdisk.device commands unmodified and
   possibly HD_SCSICMD as scsidisk.device is obviously a trackdisk
   like driver. Also the V40 commands for mfm.device or cd.device
   may be implemented with their original meaning only.

   As always, if the device doesn't support a command, IOERR_NOCMD
   must be returned for the respective command. 3rd party commands
   may be added in slots that don't conflict with the V40 command
   sets listed for NSDEVTYPE_TRACKDISK or the reserved areas.

   A new style trackdisk like device written according to a
   revision of NSD predating revision 1.4 may also return this new
   identifier for TD_GETDRIVETYPE.

       #define DRIVE_NEWSTYLE  (0x4E535459L)   /* 'NSTY' */

   It used to be a requirement to return the DRIVE_NEWSTYLE
   identifier. This requirement has been removed, and in fact it
   is recommended to *not* change the original specification of
   TD_GETDRIVETYPE anymore for an NSD device.

   You should use TD_GETGEOMETRY on a new style driver to obtain
   geometry hints if needed.

   At the moment, only four new style commands and their ETD
   counterparts in the device specific range may be implemented.

   #define NSCMD_TD_READ64     0xC000
   #define NSCMD_TD_WRITE64    0xC001
   #define NSCMD_TD_SEEK64     0xC002
   #define NSCMD_TD_FORMAT64   0xC003

       These commands behave almost like the trackdisk commands
       CMD_READ, CMD_WRITE, TD_FORMAT, respectively, but support 64
       bit handling for large storage devices. The upper 32 bits,
       bit 32 to 63, need to be put into io_Actual before the
       commands are executed. io_Actual can be named io_HighOffset
       in that case.

   To implement ETD functionality for new style commands, an
   internal bit has been defined to get the correct command
   values, which may be useful as mask for device implementors.

       #define NSCMD_TDF_EXTCOM (1<<13) /* for internal use only! */

   Similar to the original trackdisk.device specification, this
   bit splits the reserved NSD range for trackdisk like NSD
   commands in half and allows for an easy extension of the NSD
   command set for trackdisk like devices in the future.

   So for e.g. NSDCMD_TD_READ64, the corresponding
   NSCMD_ETD_READ64 would use the command value 0xE000, as the bit
   needs to be set for the ETD versions of all device specific NSD
   commands if they are defined. Currently these ETD commands are
   defined and may be implemented:

   #define NSCMD_ETD_READ64     (NSCMD_TD_READ64|NSCMD_TDF_EXTCOM)
   #define NSCMD_ETD_WRITE64    (NSCMD_TD_WRITE64|NSCMD_TDF_EXTCOM)
   #define NSCMD_ETD_SEEK64     (NSCMD_TD_SEEK64|NSCMD_TDF_EXTCOM)
   #define NSCMD_ETD_FORMAT64   (NSCMD_TD_FORMAT64|NSCMD_TDF_EXTCOM)

   If you choose to implement the basic four 64 bit commands, you
   must implement all four of them, even if some of them would
   possibly return dummy results. The ETD counterparts may only be
   implemented if the basic four 64 bit commands are implemented.
   If the ETD counterparts are implemented, all of them must be
   implemented. A partial implementation with some 64 bit commands
   returning IOERR_NOCMD is not acceptable.

   A detailed description of the 64 bit commands can be found
   in the document "trackdisk64", which can be found in the
   directory "DevInfo/TrackDisk64" on the Amiga Developer CD 1.1.
   Implementors are required to read this document.

   IMPORTANT NOTE: mfm.device is considered to be a trackdisk like
   device, too. It implements a private command 29 "(twentynine")
   which may not be redefined for any 3rd party purpose! While
   this command won't be documented, it is a standard V40 command
   number!

NSDEVTYPE_SANA2

   The device should be at least SANA-IIR2 conformant. If at all
   feasible, it should support multiple protocol stacks.
   An NSD SANA device should not fail on OpenDevice() if it gets a
   NULL ios2_BufferManagement pointer. Otherwise a general query
   would not be possible according to NSD. As the original NSD
   specification allowed for a small request when doing a query,
   an NSD SANA-II device may also accept requests that don't
   contain buffer management tags on OpenDevice() if suitable
   mn_Length checks are added to the commands. It may be wise to
   set up "dummy" callbacks in the device code for missing buffer
   management tags that return failure, to make safe use of the
   device even for broken SW. As a future NSD revision may
   introduce a general command to set up device specific
   configurations in a general way after OpenDevice() succeeded,
   setting up buffer management should be set up appropriately by
   implementors, so that a device may easily be adapted to support
   an improved NSD specification.