NSD Device Specifics - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:18:23Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:18, 26 January 2025
Line 21:		Line 21:
	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.		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>		<syntaxhighlight lang="C" line>
	#define DRIVE_NEWSTYLE (0x4E535459L) /* 'NSTY' */		#define DRIVE_NEWSTYLE (0x4E535459L) /* 'NSTY' */
	</syntaxhighlight>		</syntaxhighlight>
Line 31:		Line 31:
	At the moment, only four new style commands and their ETD counterparts in the device specific range may be implemented.		At the moment, only four new style commands and their ETD counterparts in the device specific range may be implemented.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#define NSCMD_TD_READ64 0xC000		#define NSCMD_TD_READ64 0xC000
	#define NSCMD_TD_WRITE64 0xC001		#define NSCMD_TD_WRITE64 0xC001
Line 42:		Line 42:
	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.		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>		<syntaxhighlight lang="C" line>
	#define NSCMD_TDF_EXTCOM (1<<13) /* for internal use only! */		#define NSCMD_TDF_EXTCOM (1<<13) /* for internal use only! */
	</syntaxhighlight>		</syntaxhighlight>
Line 50:		Line 50:
	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:		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>		<syntaxhighlight lang="C" line>
	#define NSCMD_ETD_READ64 (NSCMD_TD_READ64\|NSCMD_TDF_EXTCOM)		#define NSCMD_ETD_READ64 (NSCMD_TD_READ64\|NSCMD_TDF_EXTCOM)
	#define NSCMD_ETD_WRITE64 (NSCMD_TD_WRITE64\|NSCMD_TDF_EXTCOM)		#define NSCMD_ETD_WRITE64 (NSCMD_TD_WRITE64\|NSCMD_TDF_EXTCOM)

Steven Solie: /* NSDEVTYPE_TRACKDISK */

2013-04-11T19:36:41Z

NSDEVTYPE_TRACKDISK

← Older revision		Revision as of 19:36, 11 April 2013
Line 59:		Line 59:
	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.		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~~. Implementers are required to read this document.		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!		{{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 ==		== NSDEVTYPE_SANA2 ==

Steven Solie: /* NSDEVTYPE_SANA2 */

2013-04-11T19:01:04Z

NSDEVTYPE_SANA2

← Older revision		Revision as of 19:01, 11 April 2013
Line 65:		Line 65:
	== NSDEVTYPE_SANA2 ==		== 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.
	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.

Steven Solie: /* NSDEVTYPE_TRACKDISK */

2013-04-11T18:59:58Z

NSDEVTYPE_TRACKDISK

@@ Line 15: / Line 15: @@
 == NSDEVTYPE_TRACKDISK ==
-    May support all V40 trackdisk.device commands unmodified and
+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
+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
+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' */
+#define DRIVE_NEWSTYLE  (0x4E535459L)   /* 'NSTY' */
-    It used to be a requirement to return the DRIVE_NEWSTYLE
+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
+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
+At the moment, only four new style commands and their ETD counterparts in the device specific range may be implemented.
-    #define NSCMD_TD_WRITE64    0xC001
+#define NSCMD_TD_READ64     0xC000
-    #define NSCMD_TD_SEEK64     0xC002
+#define NSCMD_TD_WRITE64    0xC001
-    #define NSCMD_TD_FORMAT64   0xC003
+#define NSCMD_TD_FORMAT64   0xC003
-    To implement ETD functionality for new style commands, an
+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! */
+#define NSCMD_TDF_EXTCOM (1<<13) /* for internal use only! */
-    NSCMD_ETD_READ64 would use the command value 0xE000, as the bit
+#define NSCMD_ETD_READ64     (NSCMD_TD_READ64|NSCMD_TDF_EXTCOM)
 == NSDEVTYPE_SANA2 ==

Steven Solie: /* Revision */

2013-04-11T18:54:44Z

Revision

← Older revision		Revision as of 18:54, 11 April 2013
Line 1:		Line 1:
	= Revision =		= Revision =

	Version 1.3 (~~1996~~-10-13)		Version 1.4 (2013-04-11)

	= Device specific requirements =		= Device specific requirements =

Steven Solie: Created page with "= Revision = Version 1.3 (1996-10-13) = Device specific requirements = Depending on the type returned by NSCMD_DEVICEQUERY, a device may support device specific commands in..."

2013-04-11T16:42:47Z

Created page with "= Revision = Version 1.3 (1996-10-13) = Device specific requirements = Depending on the type returned by NSCMD_DEVICEQUERY, a device may support device specific commands in..."

New page

= Revision =

Version 1.3 (1996-10-13)

= 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.