
    $Id: NSD-DeviceSpecifics 1.3 1996/10/13 21:30:02 heinz Exp $


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.



*** EOT ***
