View source for 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.

<syntaxhighlight>
#define DRIVE_NEWSTYLE  (0x4E535459L)   /* 'NSTY' */
</syntaxhighlight>

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.

<syntaxhighlight>
#define NSCMD_TD_READ64     0xC000
#define NSCMD_TD_WRITE64    0xC001
#define NSCMD_TD_SEEK64     0xC002
#define NSCMD_TD_FORMAT64   0xC003
</syntaxhighlight>

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.

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

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:

<syntaxhighlight>
#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)
</syntaxhighlight>

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 [[TrackDisk64_Standard|TrackDisk64 Standard]]. Implementers are required to read this document.

{{Note|text=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 implementers, so that a device may easily be adapted to support an improved NSD specification.