NSD Command Specifications - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:05:52Z

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

← Older revision		Revision as of 19:05, 26 January 2025
Line 116:		Line 116:
	At the moment there is just a single new style general command:		At the moment there is just a single new style general command:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#define NSCMD_DEVICEQUERY 0x4000		#define NSCMD_DEVICEQUERY 0x4000
	</syntaxhighlight>		</syntaxhighlight>
Line 124:		Line 124:
	You set up io_Data and io_Length pointing to a struct NSDeviceQueryResult below. You must clear SizeAvailable and set up DevQueryFormat before sending the command to the device. A new style device will set up the data in the buffer appropriately. If the command executed successfully the returned io_Actual value must be greater than zero and equal to the SizeAvailable value that has been set by the device. As with device usage in general, an io_Actual value that is alrger than the passed in io_Length value should be considered an error. The device may only be considered a new style device if these conditions are met. And only in this case the results of the query may be considered valid.		You set up io_Data and io_Length pointing to a struct NSDeviceQueryResult below. You must clear SizeAvailable and set up DevQueryFormat before sending the command to the device. A new style device will set up the data in the buffer appropriately. If the command executed successfully the returned io_Actual value must be greater than zero and equal to the SizeAvailable value that has been set by the device. As with device usage in general, an io_Actual value that is alrger than the passed in io_Length value should be considered an error. The device may only be considered a new style device if these conditions are met. And only in this case the results of the query may be considered valid.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct NSDeviceQueryResult		struct NSDeviceQueryResult
	{		{
Line 180:		Line 180:
	A code fragment that could help you set up a new device query follows.		A code fragment that could help you set up a new device query follows.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct IOStdReq *io;		struct IOStdReq *io;
	struct NSDeviceQueryResult nsdqr;		struct NSDeviceQueryResult nsdqr;

Steven Solie: /* Recommended use */

2013-04-11T18:42:37Z

Recommended use

← Older revision		Revision as of 18:42, 11 April 2013
Line 274:		Line 274:
	Anyone who wants to take advantage of the new style device interface should do this:		Anyone who wants to take advantage of the new style device interface should do this:

	- OpenDevice() as described above		# OpenDevice() as described above
	- Try a NSCMD_DEVICEQUERY as described above		# Try a NSCMD_DEVICEQUERY as described above
	- If successful according to the rules mentioned above,		# If successful according to the rules mentioned above, use the commands as listed in "SupportedCommands".
		⚫	# Otherwise it must be an old style device. Hope and pray that you got what you wanted.
	use the commands as listed in "SupportedCommands".
⚫	- Otherwise it must be an old style device. Hope and pray that
	you got what you wanted.

	Note: The above description and the code fragment shown assumes that you use OpenDevice() with a freshly created and appropriately initialised request structure. If you intend to reuse a previously used request structure for another OpenDevice() to make a general query, you should set at least the following fields to zero before calling OpenDevice(): io_Actual, io_Length, io_Data, io_Offset. It is strongly recommended to always do a query with a freshly set up request structure.		Note: The above description and the code fragment shown assumes that you use OpenDevice() with a freshly created and appropriately initialised request structure. If you intend to reuse a previously used request structure for another OpenDevice() to make a general query, you should set at least the following fields to zero before calling OpenDevice(): io_Actual, io_Length, io_Data, io_Offset. It is strongly recommended to always do a query with a freshly set up request structure.

Steven Solie: /* New Style Check in C */

2013-04-11T18:41:56Z

New Style Check in C

@@ Line 180: / Line 180: @@
 A code fragment that could help you set up a new device query follows.
     struct IOStdReq *io;
     struct NSDeviceQueryResult nsdqr;
@@ Line 191: / Line 192: @@
     ...
     /* See important *CAVEAT* below! */
     /* Add error checking in production code! */
@@ Line 202: / Line 206: @@
     io->io_Length  = sizeof(nsdqr);
     io->io_Data    = (APTR)&nsdqr;
-    error = DoIO((struct IORequest *)io);
+    error = IExec->DoIO((struct IORequest *)io);
     if((!error) &&
        (io->io_Actual >= 16) &&
@@ Line 240: / Line 244: @@
         } /* if */
     } /* if */
-*** CAVEAT ***: There are some noteworthy points about this code fragment:
+There are some noteworthy points about this code fragment:
 The check of io_Actual filters out anything that is obviously wrong. An NSD device may not return less than the minimum query structure and of course it may not try to return more than the buffer space available.
@@ Line 248: / Line 254: @@
 Error checking for request allocation has been left out for brevity. Obviously, production code should contain decent error checking code.
-This code fragment uses a pointer to a struct IOStdReq to do the checks. Unfortunately, using a request of this size may result in severe problems with certain devices like SANA-II devices, which need a larger request structure. A current device should at minimum check in its OpenDevice() code if the passed in request is of at
+This code fragment uses a pointer to a struct IOStdReq to do the checks. Unfortunately, using a request of this size may result in severe problems with certain devices like SANA-II devices, which need a larger request structure. A current device should at minimum check in its OpenDevice() code if the passed in request is of at least the minimum required size to work with via its mn_Length field and fail to open if it isn't. This is a simple but effective paranoia check with the effect that surely broken request structures will be rejected right away. Unfortunately most devices don't do that check. Two basic assumptions can be relevant here:
-. The trusting assumption
+: 2. The safer assumption
 Obviously we cannot approve of the trusting assumption, because device access should be as safe as possible. So we require you to implement the safer assumption. Again, the basic idea behind this is that you should always strive to make device access as safe as possible. Some little things like validating the request structure on OpenDevice() will increase stability of the device system a lot at hardly any extra cost. Play it as safe as you can. The user might have some messed up code accessing the device!

Steven Solie: /* General commands */

2013-04-11T18:28:14Z

General commands

← Older revision		Revision as of 18:28, 11 April 2013
Line 164:		Line 164:
	: More types will be defined by the AmigaOS Development Team as necessary and requested. Each NSD device type represents a certain command set that the device must handle. If the type does not match a device that does exist in OS V40, the exact requirements are defined below or in [[NSD_Device_Specifics\|NSD Device Specifics]]. Note that some DeviceType entries may cover multiple types of devices, so you have to check the documentation carefully, when considering the standard command set for a specific type.		: More types will be defined by the AmigaOS Development Team as necessary and requested. Each NSD device type represents a certain command set that the device must handle. If the type does not match a device that does exist in OS V40, the exact requirements are defined below or in [[NSD_Device_Specifics\|NSD Device Specifics]]. Note that some DeviceType entries may cover multiple types of devices, so you have to check the documentation carefully, when considering the standard command set for a specific type.

	DeviceSubType		; DeviceSubType

			: There might be special incarnations of a device with special capabilities beyond the standard set. At the moment none are defined and a device is required to return 0 here. As extensions that are marked by this field have to be upwards compatible, this field need not be tested by users who don't need any special capabilities beyond the standard set. Otherwise it must be tested first.
	There might be special incarnations of a device with
	special capabilities beyond the standard set. At the moment
	none are defined and a device is required to return 0 here.
	As extensions that are marked by this field have to be
	upwards compatible, this field need not be tested by users
	who don't need any special capabilities beyond the standard
	set. Otherwise it must be tested first.

	SupportedCommands		; SupportedCommands

	This points to a 0 terminated list of io_Command values
	that are supported by the device. This list must contain
	all legal command values, old style, new style, and special
	3rd party commands that are understood by the device and do
	not cause an IOERR_NOCMD right away.

			: This points to a 0 terminated list of io_Command values that are supported by the device. This list must contain all legal command values, old style, new style, and special 3rd party commands that are understood by the device and do not cause an IOERR_NOCMD right away.

	You might notice the similarity to the SANA2-R2 (S2R2) S2_DEVICEQUERY command. It is intentional.		You might notice the similarity to the SANA2-R2 (S2R2) S2_DEVICEQUERY command. It is intentional.

	If you are developing software that needs to use 3rd party commands, you must try an exact 3rd party device identification via the lib_IdString in the device base and reject all devices that you don't know for a new style device.		If you are developing software that needs to use 3rd party commands, you must try an '''exact''' 3rd party device identification via the lib_IdString in the device base and reject all devices that you don't know for a new style device.

	= New Style Check in C =		= New Style Check in C =

Steven Solie: /* General commands */

2013-04-11T18:26:54Z

General commands

@@ Line 150: / Line 150: @@
 ; DeviceType
-: This tells you about the NSD type of device you are accessing. The type names often match existing devices in
+: This tells you about the NSD type of device you are accessing. The type names often match existing devices in AmigaOS. If a device returns such a type, the device must be able to at least handle all the documented features for V40 of the operating system that the respective original device has. If the NSD device type refers to a group of V40 devices, at least the basic command subset as for the device named by the NSD device type shall be handled.
-        Note well that while all the documented features for an
+: Note well that while all the documented features for an implemented command shall be handled, it is permissible to return error codes or appropriate dummy returns for non existing features in the NSD device as long as the handling conforms to the original specification.
-        If an old style or new style command cannot be supported in
+: If an old style or new style command cannot be supported in a compatible manner, the device is required to return IOERR_NOCMD for safety reasons. Modification of the specification is not allowed. Add a 3rd party command if needed.
-        It is also illegal to use the results of an
+: It is also illegal to use the results of an NSCMD_DEVICEQUERY without testing DeviceType first.
-        The NSD device types are listed and explained above in the
+: The NSD device types are listed and explained above in the section "Device Types".
     DeviceSubType

Steven Solie: /* General commands */

2013-04-11T17:30:10Z

General commands

← Older revision		Revision as of 17:30, 11 April 2013
Line 116:		Line 116:
	At the moment there is just a single new style general command:		At the moment there is just a single new style general command:

			<syntaxhighlight>
	#define NSCMD_DEVICEQUERY 0x4000		#define NSCMD_DEVICEQUERY 0x4000
			</syntaxhighlight>

	It is required for all new style devices.		It is required for all new style devices.

	You set up io_Data and io_Length pointing to a struct NSDeviceQueryResult below. You must clear SizeAvailable and set up DevQueryFormat before sending the command to the device. A new style device will set up the data in the buffer appropriately. If the command executed successfully the returned io_Actual value must be greater than zero and equal to the SizeAvailable value that has been set by the device. As with device usage in general, an		You set up io_Data and io_Length pointing to a struct NSDeviceQueryResult below. You must clear SizeAvailable and set up DevQueryFormat before sending the command to the device. A new style device will set up the data in the buffer appropriately. If the command executed successfully the returned io_Actual value must be greater than zero and equal to the SizeAvailable value that has been set by the device. As with device usage in general, an io_Actual value that is alrger than the passed in io_Length value should be considered an error. The device may only be considered a new style device if these conditions are met. And only in this case the results of the query may be considered valid.
	io_Actual value that is alrger than the passed in io_Length value should be considered an error. The device may only be considered a new style device if these conditions are met. And only in this case the results of the query may be considered valid.

			<syntaxhighlight>
	struct NSDeviceQueryResult		struct NSDeviceQueryResult
	{		{
Line 140:		Line 142:
	/* May be extended in the future! Check SizeAvailable! */		/* May be extended in the future! Check SizeAvailable! */
	};		};
			</syntaxhighlight>

	The device will fill in the struct NSDeviceQueryResult with read only data for the caller. All data must remain constant and valid as long as the device is open. After CloseDevice(), all bets are off.		The device will fill in the struct NSDeviceQueryResult with read only data for the caller. All data must remain constant and valid as long as the device is open. After CloseDevice(), all bets are off.

	SizeAvailable		; SizeAvailable
			: Tells you how much of the structure contains valid data. It is measured in bytes. Do not try to use fields in the structure that are not fully included in the SizeAvailable range. SizeAvailable must include SupportedCommands for any successful query. So the minimum valid value is 16.

		⚫	; DeviceType
	Tells you how much of the structure contains valid data. It
		⚫	: This tells you about the NSD type of device you are accessing. The type names often match existing devices in
	is measured in bytes. Do not try to use fields in the
	structure that are not fully included in the SizeAvailable
	range. SizeAvailable must include SupportedCommands for any
	successful query. So the minimum valid value is 16.

⚫	DeviceType

	This tells you about the NSD type of device you are
⚫	accessing. The type names often match existing devices in
	AmigaOS. If a device returns such a type, the device must		AmigaOS. If a device returns such a type, the device must
	be able to at least handle all the documented features for		be able to at least handle all the documented features for
Line 219:		Line 215:

	If you are developing software that needs to use 3rd party commands, you must try an exact 3rd party device identification via the lib_IdString in the device base and reject all devices that you don't know for a new style device.		If you are developing software that needs to use 3rd party commands, you must try an exact 3rd party device identification via the lib_IdString in the device base and reject all devices that you don't know for a new style device.


	= New Style Check in C =		= New Style Check in C =

Steven Solie: /* The meaning of "No Command Redefinition" */

2013-04-11T17:25:29Z

The meaning of "No Command Redefinition"

← Older revision		Revision as of 17:25, 11 April 2013
Line 108:		Line 108:
	An NSD device of a certain type is not allowed to redefine any V40 command or any command from the NSD reserved ranges. Each NSD device type as described above groups the corresponding V40 devices with similar command sets. Each of these devices has an established, documented, and implemented set of commands with documented meaning. An NSD device must always handle all these commands, if implemented, like the respective V40 device or like the set of V40 devices for that NSD device type. It is not acceptable if a CMD_READ suddenly turns into functionality of CMD_WRITE or if HD_SCSICMD will suddenly be like a TD_EJECT. If you find, e.g., HD_SCSICMD or CD_INFO in the supported command list of a NSDEVTYPE_TRACKDISK device, you shall be sure that these commands behave like the V40 commands of the respective devices would behave. Note that if you find one command supported for an NSD device type, this does not mean that other commands for that NSD device type are necessarily supported. Check for the command set that you need.		An NSD device of a certain type is not allowed to redefine any V40 command or any command from the NSD reserved ranges. Each NSD device type as described above groups the corresponding V40 devices with similar command sets. Each of these devices has an established, documented, and implemented set of commands with documented meaning. An NSD device must always handle all these commands, if implemented, like the respective V40 device or like the set of V40 devices for that NSD device type. It is not acceptable if a CMD_READ suddenly turns into functionality of CMD_WRITE or if HD_SCSICMD will suddenly be like a TD_EJECT. If you find, e.g., HD_SCSICMD or CD_INFO in the supported command list of a NSDEVTYPE_TRACKDISK device, you shall be sure that these commands behave like the V40 commands of the respective devices would behave. Note that if you find one command supported for an NSD device type, this does not mean that other commands for that NSD device type are necessarily supported. Check for the command set that you need.

	For the common eight usable Exec standard commands, intentionally no distinction is made between different V40 devices which may fall under the same NSD device type. The device I/O operations should be consistent and uniform according to the RKM and NSD does not try to differentiate between possible execution differences for the Exec standard commands. Because of this requirement for consistency and uniformity, the standard Exec commands obviously may not be redefined arbitrarily either. If an Exec standard command is implemented in a device, the implementation must not deviate from the specification for that device type or common usage for that		For the common eight usable Exec standard commands, intentionally no distinction is made between different V40 devices which may fall under the same NSD device type. The device I/O operations should be consistent and uniform according to the RKM and NSD does not try to differentiate between possible execution differences for the Exec standard commands. Because of this requirement for consistency and uniformity, the standard Exec commands obviously may not be redefined arbitrarily either. If an Exec standard command is implemented in a device, the implementation must not deviate from the specification for that device type or common usage for that command.
	command.

	All command slots that are not part of the V40 command set for the respective devices under the NSD device types or of the reserved NSD areas are free to be used for 3rd party extensions. NSD neither defines nor restricts their usage. From the NSD perspective, the meaning of any implemented 3rd party command is undefined. The user		All command slots that are not part of the V40 command set for the respective devices under the NSD device types or of the reserved NSD areas are free to be used for 3rd party extensions. NSD neither defines nor restricts their usage. From the NSD perspective, the meaning of any implemented 3rd party command is undefined. The user software is responsible for an exact device identification then to use 3rd party commands safely via the device's lib_IDString as described below.
	software is responsible for an exact device identification then to use 3rd party commands safely via the device's lib_IDString as described below.

	= General commands =		= General commands =

Steven Solie: /* Device Types */

2013-04-11T17:24:20Z

Device Types

Show changes

Steven Solie: /* Basic requirements */

2013-04-11T17:15:20Z

Basic requirements

← Older revision		Revision as of 17:15, 11 April 2013
Line 34:		Line 34:
	Let's make a quick list about the most basic requirements for any new style device. Keep it in mind when reading on.		Let's make a quick list about the most basic requirements for any new style device. Keep it in mind when reading on.

	- IOERR_NOCMD support		# IOERR_NOCMD support
	~~- no~~ redefinition of standard V40 or reserved commands		# No redefinition of standard V40 or reserved commands
	~~- no~~ 3rd party commands in reserved areas		# No 3rd party commands in reserved areas
	- NSCMD_DEVICEQUERY is supported		# NSCMD_DEVICEQUERY is supported
	- lib_IdString must contain the name, version, and creation		# lib_IdString must contain the name, version, and creation date of the device and any other readable information to make unique identification of a device for 3rd party command use possible.
		⚫	# Check mn_Length of the request on OpenDevice() for the minimum required length
	date of the device and any other readable information to make
	unique identification of a device for 3rd party command use
	possible.
⚫	- Check mn_Length of the request on OpenDevice() for the minimum
	required length

⚫	Some devices may have additional requirements. These will be listed in ~~the~~ ~~sub~~ ~~document "NSD-DeviceSpecifics"~~.

		⚫	Some devices may have additional requirements. These will be listed in [[NSD_Device_Specifics\|NSD Device Specifics]].

	= Device Types =		= Device Types =

Steven Solie: /* What will new style commands do for you? */

2013-04-11T17:13:48Z

What will new style commands do for you?

← Older revision		Revision as of 17:13, 11 April 2013
Line 29:		Line 29:

	With a new style device, you can be sure that no 3rd party command will interact with the standard meaning of all the device's commands as documented for V40 of the OS.		With a new style device, you can be sure that no 3rd party command will interact with the standard meaning of all the device's commands as documented for V40 of the OS.


	= Basic requirements =		= Basic requirements =