This convenience procedure creates an I/O request item.
When you create an I/O request, you must decide how the device will notify you when an I/O operation completes. There are two choices:
Notification by signal
Notification by message
With notification by signal, the device will send your task the SIGF_IODONE signal whenever an I/O operation completes. This is a low-overhead mechanism, which is also low on information. When you get the signal, all you know is that an I/O operation has completed. You do not know which operation has completed. This has to be determined by looking at the state of all outstanding I/O requests.
Notification by message involves slightly more overhead, but provides much more information. When you create the I/O request, you indicate a message port. Whenever an I/O operation completes, the device will send a message to that message port. The message will contain the following information:
msg_Result Contains the io_Error value from the I/O request. This indicates the state of the I/O operation, whether it worked or failed.
msg_DataPtr Contains the item number of the I/O request that completed.
msg_DataSize Contains the value of the ioi_User field taken from the IOInfo structure used when initiating the I/O operation.
Arguments
name
The name of the I/O request (see "Notes").
pri
The priority of the I/O request. For some device drivers, this value determines the order in which I/O requests are processed. When in doubt about what value to use, use 0.
dev
The item number of the device to which to send the I/O request.
mp
If a task wants to receive a message when an I/O request is finished, this argument must be the item number of the message port to receive the message. If the task wants to receive a signal when an I/O request is finished instead of a message, this argument must be 0.
Return Value
The procedure returns the item number of the new I/O request or one of the following error codes if an error occurs:
BADITEM
The mp argument was not zero but did not specify a valid message port.
ER_Kr_ItemNotOpen
The device specified by the dev argument is not open.
NOMEM
There was not enough memory to complete the operation.
Implementation
Convenience call implemented in clib.lib V20.
Associated Files
io.h
ANSI C Prototype
clib.lib
ARM Link Library
Notes
When you no longer need an I/O request, use DeleteIOReq() to delete it.
You can use FindNamedItem() to find a I/O request by name. When creating I/O requests, you should assign unique names whenever possible.
The kernel may change the priority of an I/O request to help optimize throughput.