Exec Device I/O - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:28:59Z

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

← Older revision		Revision as of 19:28, 26 January 2025
Line 63:		Line 63:
	The device is opened by calling the OpenDevice() function. In addition to establishing the link to the device, OpenDevice() also initializes fields in the I/O request. OpenDevice() has this format:		The device is opened by calling the OpenDevice() function. In addition to establishing the link to the device, OpenDevice() also initializes fields in the I/O request. OpenDevice() has this format:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	result = IExec->OpenDevice(device_name,unit_number,(struct IORequest *)IORequest,flags)		result = IExec->OpenDevice(device_name,unit_number,(struct IORequest *)IORequest,flags)
	</syntaxhighlight>		</syntaxhighlight>
Line 106:		Line 106:
	An I/O request typically has three fields set for every command sent to a device. You set the command itself in the '''io_Command''' field, a pointer to the data for the command in the '''io_Data''' field, and the length of the data in the '''io_Length''' field.		An I/O request typically has three fields set for every command sent to a device. You set the command itself in the '''io_Command''' field, a pointer to the data for the command in the '''io_Data''' field, and the length of the data in the '''io_Length''' field.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	SerialIO->IOSer.io_Length = sizeof(ReadBuffer);		SerialIO->IOSer.io_Length = sizeof(ReadBuffer);
	SerialIO->IOSer.io_Data = ReadBuffer;		SerialIO->IOSer.io_Data = ReadBuffer;
Line 236:		Line 236:
	The exact method for checking '''io_Error''' can depend on whether you use '''DoIO()''' or '''SendIO()'''. In both cases, '''io_Error''' will be set when the I/O request is returned, but in the case of '''DoIO()''', the '''DoIO()''' function itself returns the same value as '''io_Error'''. This gives you the option of checking the function return value:		The exact method for checking '''io_Error''' can depend on whether you use '''DoIO()''' or '''SendIO()'''. In both cases, '''io_Error''' will be set when the I/O request is returned, but in the case of '''DoIO()''', the '''DoIO()''' function itself returns the same value as '''io_Error'''. This gives you the option of checking the function return value:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	SerialIO->IOSer.io_Length = sizeof(ReadBuffer);		SerialIO->IOSer.io_Length = sizeof(ReadBuffer);
	SerialIO->IOSer.io_Data = ReadBuffer;		SerialIO->IOSer.io_Data = ReadBuffer;
Line 246:		Line 246:
	Or you can check io_Error directly:		Or you can check io_Error directly:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	SerialIO->IOSer.io_Length = sizeof(ReadBuffer);		SerialIO->IOSer.io_Length = sizeof(ReadBuffer);
	SerialIO->IOSer.io_Data = ReadBuffer;		SerialIO->IOSer.io_Data = ReadBuffer;
Line 269:		Line 269:
	A device is closed by calling the '''CloseDevice()''' function. The '''CloseDevice()''' function does not return a value. It has this format:		A device is closed by calling the '''CloseDevice()''' function. The '''CloseDevice()''' function does not return a value. It has this format:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IExec->CloseDevice(IORequest);		IExec->CloseDevice(IORequest);
	</syntaxhighlight>		</syntaxhighlight>
Line 297:		Line 297:
	A device can be deleted from the system using this function:		A device can be deleted from the system using this function:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	error = IExec->RemDevice(device);		error = IExec->RemDevice(device);
	</syntaxhighlight>		</syntaxhighlight>
Line 329:		Line 329:
	We will use the timer device to illustrate the above method. The name of the timer device base address is listed in its proto file as TimerBase.		We will use the timer device to illustrate the above method. The name of the timer device base address is listed in its proto file as TimerBase.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <devices/timer.h>		#include <devices/timer.h>

Line 376:		Line 376:
	The following short example demonstrates use of an Amiga device. The example opens the serial.device and then demonstrates both synchronous (DoIO()) and asynchronous (SendIO()) use of the serial command SDCMD_QUERY. This command is used to determine the status of the serial device lines and registers.		The following short example demonstrates use of an Amiga device. The example opens the serial.device and then demonstrates both synchronous (DoIO()) and asynchronous (SendIO()) use of the serial command SDCMD_QUERY. This command is used to determine the status of the serial device lines and registers.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* DeviceUse.c - an example of using an Amiga device (here, serial device) */		/* DeviceUse.c - an example of using an Amiga device (here, serial device) */
	/* */		/* */
Line 491:		Line 491:
	Many device drivers manage more than one functional unit. For example, the trackdisk driver can handle up to four floppy drives. The preferred approach is to use a separate "Unit" structure for each functional unit (e.g. drive). Normally, a unit structure consists of at least the following:		Many device drivers manage more than one functional unit. For example, the trackdisk driver can handle up to four floppy drives. The preferred approach is to use a separate "Unit" structure for each functional unit (e.g. drive). Normally, a unit structure consists of at least the following:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Unit {		struct Unit {
	struct MsgPort unit_MsgPort;		struct MsgPort unit_MsgPort;

Steven Solie: /* Using An Exec Device */

2016-10-03T16:30:05Z

Using An Exec Device

← Older revision		Revision as of 16:30, 3 October 2016
Line 412:		Line 412:
	{		{
	/* Open the serial device (non-zero return value means failure here). */		/* Open the serial device (non-zero return value means failure here). */
	if (OpenDevice( SERIALNAME, 0, (struct IORequest *)serialIO, 0L))		if (IExec->OpenDevice( SERIALNAME, 0, (struct IORequest *)serialIO, 0))
	IDOS->Printf("Error: %s did not open\n", SERIALNAME);		IDOS->Printf("Error: %s did not open\n", SERIALNAME);
	else		else
Line 425:		Line 425:
	IDOS->Printf("Serial device status: $%x\n\n", serialIO->io_Status);		IDOS->Printf("Serial device status: $%x\n\n", serialIO->io_Status);

	serialIO->IOSer.io_Command = SDCMD_QUERY; /* SendIO - demonstrates asynchronous */		serialIO->IOSer.io_Command = SDCMD_QUERY; /* SendIO - demonstrates asynchronous */
	~~IDOS~~->SendIO((struct IORequest )serialIO); / device use (returns immediately). */		IExec->SendIO((struct IORequest )serialIO); / device use (returns immediately). */

	/* We could do other things here while the query is being done. */		/* We could do other things here while the query is being done. */

Steven Solie: /* Devices With Functions */

2015-11-03T23:06:24Z

Devices With Functions

← Older revision		Revision as of 23:06, 3 November 2015
Line 311:		Line 311:
	Some devices, in addition to their commands, provide library-style functions which can be directly called by applications. These functions are documented by each device.		Some devices, in addition to their commands, provide library-style functions which can be directly called by applications. These functions are documented by each device.

	Devices with functions behave much like Amiga libraries, i.e., you set up a base address pointer and call the functions as offsets from the pointer. See ~~the~~ [[Exec_Libraries\|Exec Libraries]] ~~chapter~~ for more information.		Devices with functions behave much like Amiga libraries, i.e., you set up a base address pointer and call the functions as offsets from the pointer. See [[Exec_Libraries\|Exec Libraries]] for more information.

	The procedure for accessing a device's functions is as follows:		The procedure for accessing a device's functions is as follows:

Steven Solie: /* Function Reference */

2013-04-16T16:17:53Z

Function Reference

← Older revision		Revision as of 16:17, 16 April 2013
Line 542:		Line 542:
	\| Initiate an asynchronous device I/O request.		\| Initiate an asynchronous device I/O request.
	\|}		\|}

			== Credits ==

			Special thanks to [http://wandel.ca Markus Wandel] for allowing us to use material from his [http://wandel.ca/homepage/execdis/devices_doc.txt Amiga Device Driver Guide].

Steven Solie: /* Standard Exec Commands */

2013-04-16T16:04:48Z

Standard Exec Commands

← Older revision		Revision as of 16:04, 16 April 2013
Line 141:		Line 141:

	Commands in the reserved areas may only be assigned and specified by the AmigaOS Development Team. Any "custom" implementation of these commands or other commands in these reserved areas is illegal and violates the [[NSD_Standard\|New Style Device (NSD) Standard]].		Commands in the reserved areas may only be assigned and specified by the AmigaOS Development Team. Any "custom" implementation of these commands or other commands in these reserved areas is illegal and violates the [[NSD_Standard\|New Style Device (NSD) Standard]].

			==== CMD_RESET ====

			This resets the device to a known initial state. Pending I/O requests not processed at the time of this command should be returned with an error.

			==== CMD_READ ====

			This requests that "io_Length" items of data be read from location "io_Offset" on the unit, and stored at "io_Data" in the caller's memory. The actual amount of data transferred is returned in "io_Actual". The specifics depend on the device type.

			==== CMD_WRITE ====

			This requests that data be transferred from the caller's memory to the I/O unit. The arguments are the same as for CMD_READ.

			==== CMD_UPDATE ====

			This requests that all buffered, but unwritten data be forced out to the I/O unit. It might write out the track buffer in a disk device, for example.

			==== CMD_CLEAR ====

			This requests that all data buffered by the device for the given unit be invalidated. Thus, for example, it would throw away data waiting in a serial input buffer.

			==== CMD_STOP ====

			This requests that the unit stop processing commands. I/O requests not processed at the time of the CMD_STOP will wait until a CMD_START or CMD_RESET is received or they are aborted.

			==== CMD_START ====

			This requests that the unit clear a CMD_STOP condition and resume processing commands. Only one CMD_START is required, regardless of how many CMD_STOPs have been received.

			==== CMD_FLUSH ====

			This requests that the unit flush all pending commands. All I/O requests queued but not yet processed should be sent back with an error.

			==== Error Numbers ====

			The include file "exec/errors.h" lists the following standard error numbers.

			{\| class="wikitable"
			! Constant !! Description
			\|-
			\| IOERR_SUCCESS \|\| not an error (success)
			\|-
			\| IOERR_OPENFAIL \|\| device/unit failed to open
			\|-
			\| IOERR_ABORTED \|\| request aborted
			\|-
			\| IOERR_NOCMD \|\| command not supported
			\|-
			\| IOERR_BADLENGTH \|\| not a valid length
			\|-
			\| IOERR_BADADDRESS \|\| invalid address (misaligned or bad range)
			\|-
			\| IOERR_UNITBUSY \|\| device opens ok, but requested unit is busy
			\|-
			\| IOERR_SELFTEST \|\| device is currently performing a self-test
			\|}

	=== Synchronous vs. Asynchronous Requests ===		=== Synchronous vs. Asynchronous Requests ===

Steven Solie: /* Standard Exec Commands */

2013-04-16T15:55:11Z

Standard Exec Commands

← Older revision		Revision as of 15:55, 16 April 2013
Line 117:		Line 117:
	=== Standard Exec Commands ===		=== Standard Exec Commands ===

			This section lists the command and error numbers which are predefined in the Amiga system for all types of device drivers.
	{\| class="wikitable"

	\| CMD_CLEAR \|\| CMD_READ \|\| CMD_STOP
			The following commands are reserved for all devices:
	\|-
			* CMD_INVALID
	\| CMD_FLUSH \|\| CMD_RESET \|\| CMD_WRITE
			* CMD_RESET
	\|-
			* CMD_READ
	\| CMD_INVALID \|\| CMD_START \|\| CMD_UPDATE
			* CMD_WRITE
	\|}
			* CMD_UPDATE
			* CMD_CLEAR
			* CMD_STOP
			* CMD_START
			* CMD_FLUSH
			* CMD_NONSTD

			It is seen that command number zero is invalid, and command numbers greater than 9 are custom defined.

	There are 65536 command values possible with io_Command:		There are 65536 command values possible with io_Command:

Steven Solie: /* Synchronous vs. Asynchronous Requests */

2013-04-16T15:48:55Z

Synchronous vs. Asynchronous Requests

← Older revision		Revision as of 15:48, 16 April 2013
Line 163:		Line 163:

	The second method to detect when the request is complete involves using the '''CheckIO()''' function. '''CheckIO()''' takes an I/O request as its argument and returns an indication of whether or not it has been completed. When '''CheckIO()''' returns the completed indication, you will still have to remove the I/O request from the message port.		The second method to detect when the request is complete involves using the '''CheckIO()''' function. '''CheckIO()''' takes an I/O request as its argument and returns an indication of whether or not it has been completed. When '''CheckIO()''' returns the completed indication, you will still have to remove the I/O request from the message port.

			{{Note\|text=WaitIO() and CheckIO() know about the IOF_QUICK flag and will behave accordingly.}}

	=== I/O Request Completion ===		=== I/O Request Completion ===

Steven Solie: /* Using A Device */

2013-04-16T15:46:48Z

Using A Device

← Older revision		Revision as of 15:46, 16 April 2013
Line 89:		Line 89:

	;DoIO()		;DoIO()
	:is a synchronous function. It will not return until the device has responded to the I/O request.		:DoIO() is a synchronous function. It will not return until the device has responded to the I/O request.
	:This function calls the BeginIO() entry point in the device driver with IOF_QUICK set. If the device driver leaves IOF_QUICK set, it returns to the caller immediately. The return value is the extended value of the "io_Error" field in the I/O request. If the IOF_QUICK bit is cleared, it falls through to WaitIO().		:This function calls the BeginIO() entry point in the device driver with IOF_QUICK set. If the device driver leaves IOF_QUICK set, it returns to the caller immediately. The return value is the extended value of the "io_Error" field in the I/O request. If the IOF_QUICK bit is cleared, it falls through to WaitIO().

	;SendIO()		;SendIO()
	:is an asynchronous function. It can return immediately, but the I/O operation it initiates may take a short or long time. Using '''SendIO()''' requires you to monitor the message port for a return message from the device. In addition, some devices do not actually respond asynchronously even though you called '''SendIO()'''; they will return when the I/O operation is finished.		:SendIO() is an asynchronous function. It can return immediately, but the I/O operation it initiates may take a short or long time. Using '''SendIO()''' requires you to monitor the message port for a return message from the device. In addition, some devices do not actually respond asynchronously even though you called '''SendIO()'''; they will return when the I/O operation is finished.
	:This function calls the BeginIO() entry point in the device driver with IOF_QUICK clear. This means that the device driver should return the I/O request with ReplyMsg().		:This function calls the BeginIO() entry point in the device driver with IOF_QUICK clear. This means that the device driver should return the I/O request with ReplyMsg().

	;BeginIO()		;BeginIO()
			:There is one operation which DoIO() and SendIO() cannot handle, and that is sending an I/O request with the IOF_QUICK flag set, but not waiting for it to complete. That is "run this as quickly as possible but if it's going to take a while, don't wait for it". For this operation, the user must set IOF_QUICK manually, then call the device driver directly through its BeginIO() entry point.
	:~~is commonly used to control the quick I/O bit when sending an I/O request to a device.~~ When the quick I/O flag (IOF_QUICK) is set in the I/O request, a device is allowed to take certain shortcuts in performing and completing a request. If the request can complete immediately, the device will not return a reply message and the quick I/O flag will remain set. If the request cannot be completed immediately, the QUICK_IO flag will be clear. '''DoIO()''' normally requests quick I/O; '''SendIO()''' does not.		:When the quick I/O flag (IOF_QUICK) is set in the I/O request, a device is allowed to take certain shortcuts in performing and completing a request. If the request can complete immediately, the device will not return a reply message and the quick I/O flag will remain set. If the request cannot be completed immediately, the QUICK_IO flag will be clear. '''DoIO()''' normally requests quick I/O; '''SendIO()''' does not.

	'''DoIO()''' and '''SendIO()''' are most commonly used.		'''DoIO()''' and '''SendIO()''' are most commonly used.

Steven Solie: /* Synchronous vs. Asynchronous Requests */

2013-04-16T15:43:44Z

Synchronous vs. Asynchronous Requests

← Older revision		Revision as of 15:43, 16 April 2013
Line 144:		Line 144:

	{{Note\|title=''Do Not Touch!''\|text=When you use '''SendIO()''' or '''BeginIO()''', the I/O request you pass to the device and any associated data buffers should be considered read-only. Once you send it to the device, you must ''not'' modify it in any way until you receive the reply message from the device or abort the request (though you must still wait for a reply). Any exceptions to this rule are documented in the autodoc for the device.}}		{{Note\|title=''Do Not Touch!''\|text=When you use '''SendIO()''' or '''BeginIO()''', the I/O request you pass to the device and any associated data buffers should be considered read-only. Once you send it to the device, you must ''not'' modify it in any way until you receive the reply message from the device or abort the request (though you must still wait for a reply). Any exceptions to this rule are documented in the autodoc for the device.}}

	Sending multiple asynchronous I/O requests to a device can be tricky because devices require them to be unique and initialized. This means you can't use an I/O request that's still in the queue, but you need the fields which were initialized in it when you opened the device. The solution is to copy the initialized I/O request to another I/O request(s) before sending anything to the device.		Sending multiple asynchronous I/O requests to a device can be tricky because devices require them to be unique and initialized. This means you can't use an I/O request that's still in the queue, but you need the fields which were initialized in it when you opened the device. The solution is to copy the initialized I/O request to another I/O request(s) before sending anything to the device.

Line 152:		Line 153:
	; WaitIO()		; WaitIO()
	: not only waits for the return of the I/O request, it also takes care of all the message handling functions. This is very convenient, but you can pay for this convenience: your application will hang in the unlikely event that the I/O request does not return.		: not only waits for the return of the I/O request, it also takes care of all the message handling functions. This is very convenient, but you can pay for this convenience: your application will hang in the unlikely event that the I/O request does not return.
			: If the I/O request has the IOF_QUICK flag set, it cannot possibly be in progress, so it returns immediately.

	; Wait()		; Wait()

Steven Solie: /* The AbortIO Function Vector */

2013-04-16T15:41:27Z

The AbortIO Function Vector

← Older revision		Revision as of 15:41, 16 April 2013
Line 412:		Line 412:
	The BeginIO() function operates on the command and parameters in the I/O request, and sets the "io_Error" field to indicate the result. Exec I/O functions return the value of this field to the caller; BeginIO() itself does not return a value. "io_Error" set to zero means that no error has occurred.		The BeginIO() function operates on the command and parameters in the I/O request, and sets the "io_Error" field to indicate the result. Exec I/O functions return the value of this field to the caller; BeginIO() itself does not return a value. "io_Error" set to zero means that no error has occurred.

	=== The AbortIO ~~Function~~ ~~Vector~~ ===		=== The AbortIO Entry Point ===

	Some device driver operations, such as waiting for a timeout or input on a serial port, may need to be aborted before they complete. The AbortIO() function is provided for this. The device driver is entered through its AbortIO() ~~function~~ ~~vector~~ with the address of the I/O request to be aborted and the device node pointer. If the device driver determines		Some device driver operations, such as waiting for a timeout or input on a serial port, may need to be aborted before they complete. The AbortIO() function is provided for this. The device driver is entered through its AbortIO() entry point with the address of the I/O request to be aborted and the device node pointer. If the device driver determines that the I/O request is indeed in progress and can successfully abort it, it returns zero, otherwise it returns a non-zero error code.
	that the I/O request is indeed in progress and can successfully abort it, it returns zero, otherwise it returns a non-zero error code.

	A successfully aborted I/O request is returned by the normal method, i.e. ReplyMsg(). The "io_Error" field should indicate that it did not complete normally.		A successfully aborted I/O request is returned by the normal method, i.e. ReplyMsg(). The "io_Error" field should indicate that it did not complete normally.