The IORB is the main control block for all direct call commands. To accommodate varying command-specific data, there are eight types of IORBs, one per CommandCode, as shown in the following table.
┌──────────────────────────────┬──────────────────────────────┐ │IORB Type │CommandCode │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_CONFIGURATION │IOCC_CONFIGURATION │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_UNIT_CONTROL │IOCC_UNIT_CONTROL │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_GEOMETRY │IOCC_GEOMETRY │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_EXECUTE_IO │IOCC_EXECUTE_IO │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_FORMAT │IOCC_FORMAT │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_UNIT_STATUS │IOCC_UNIT_STATUS │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_DEVICE_CONTROL │IOCC_DEVICE_CONTROL │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_ADAPTER_PASSTHRU │IOCC_ADAPTER_PASSTHRU │ └──────────────────────────────┴──────────────────────────────┘
Each IORB consists of a common I/O Request Block Header (IORBH data structure), followed by unique command-specific data, as shown in the following table.
┌──────────────────────┬──────────┬─────────┬───────────────────┐ │Field Name │C Type │Length │Description │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Length │USHORT │DW │Length of IORB │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │UnitHandle │USHORT │DW │Unit handle │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │CommandCode │USHORT │DW │Command code │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │CommandModifier │USHORT │DW │Command modifier │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │RequestControl │USHORT │DW │Flags │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Status │USHORT │DW │Status │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │ErrorCode │USHORT │DW │Error code │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Timeout │ULONG │DD │Completion timeout │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │StatusBlockLen │USHORT │DW │Length of status │ │ │ │ │info │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │pStatusBlock │NPBYTE │DW │Pointer to status │ │ │ │ │info │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Reserved_1 │USHORT │DW │Reserved │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │pNxtIORB │PIORB │DD │Pointer to next │ │ │ │ │IORB │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │NotifyAddress │(*PFN)( ) │DD │Notification │ │ │ │ │address │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │DMWorkSpace[20] │UCHAR │DB(20) │Reserved │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │ADDWorkSpace[16] │UCHAR │DB(16) │adapter device │ │ │ │ │driver work area │ └──────────────────────┴──────────┴─────────┴───────────────────┘
On entry to the driver:
Length
is set to the total length of the IORB (IORBH plus Command-Specific Data)
in bytes.
UnitHandle
identifies the adapter device driver's unit for which the request is intended.
The adapter device driver must assign a unique UnitHandle in the
DEVICETABLE UNITINFO structure for each of the units it manages. Refer
to the IOCC_CONFIGURATION CommandCode section for additional information.
CommandCode/CommandModifier
contains the direct call commands. These commands are grouped by CommandCode
as shown in the following table. The CommandCode field defines
the IORB; the CommandModifier field selects the actual operation
within a specified CommandCode. For details on each of the commands,
refer to their corresponding CommandCode sections.
┌────────────────────────┬────────────────────────────────────┐ │CommandCode │CommandModifier │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_CONFIGURATION │ │ │ │IOCM_GET_DEVICE_TABLE │ │ │IOCM_COMPLETE_INIT │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_UNIT_CONTROL │ │ │ │IOCM_ALLOCATE_UNIT │ │ │IOCM_DEALLOCATE_UNIT │ │ │IOCM_CHANGE_UNITINFO │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_GEOMETRY │ │ │ │IOCM_GET_MEDIA_GEOMETRY │ │ │IOCM_SET_MEDIA_GEOMETRY │ │ │IOCM_GET_DEVICE_GEOMETRY │ │ │IOCM_SET_LOGICAL_GEOMETRY │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_EXECUTE_IO │ │ │ │IOCM_READ │ │ │IOCM_READ_VERIFY │ │ │IOCM_READ_PREFETCH │ │ │IOCM_WRITE │ │ │IOCM_WRITE_VERIFY │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_FORMAT │ │ │ │IOCM_FORMAT_MEDIA │ │ │IOCM_FORMAT_TRACK │ │ │IOCM_FORMAT_PROGRESS │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_UNIT_STATUS │ │ │ │IOCM_GET_UNIT_STATUS │ │ │IOCM_GET_CHANGELINE_STATE │ │ │IOCM_GET_MEDIA_SENSE │ │ │IOCM_GET_LOCK_SENSE │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_DEVICE_CONTROL │ │ │ │IOCM_ABORT │ │ │IOCM_RESET │ │ │IOCM_SUSPEND │ │ │IOCM_RESUME │ │ │IOCM_LOCK_MEDIA │ │ │IOCM_UNLOCK_MEDIA │ │ │IOCM_EJECT_MEDIA │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_ADAPTER_PASSTHRU │ │ │ │IOCM_EXECUTE_SCB │ │ │IOCM_EXECUTE_CDB │ └────────────────────────┴────────────────────────────────────┘
RequestControl
contains flags which control the processing of the IORB, as shown in the
following table.
┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │IORB_ASYNC_POST │Command-completion protocol. This │ │ │ADD will always return immediately, │ │ │as this is an asynchronous protocol │ │ │requiring ASYNC_NOTIFY to be set. If│ │ │set, this flag indicates that the │ │ │NotifyAddress field is valid and │ │ │that the adapter device driver │ │ │should call this routine when the │ │ │IORB request is completed. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_CHAIN │IORB chaining. If set, this flag │ │ │indicates that the pNxtIORB field is│ │ │valid and that there is a chained │ │ │IORB command to service. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_CHS_ADDRESSING │I/O addressing format. If set, this│ │ │flag indicates that the command's │ │ │RBA field is in the format defined │ │ │by the CHS_ADDR structure. This bit│ │ │should be set only for diskette │ │ │controllers. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_REQ_STATUSBLOCK │Request for status information. If │ │ │set, this flag indicates that the │ │ │StatusBlockLen and pStatusBlock │ │ │fields are valid and that the │ │ │adapter device driver should return │ │ │the command's associated status │ │ │information. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_DISABLE_RETRY │No error retry. If set, this flag │ │ │indicates that the adapter device │ │ │driver should not retry the request │ │ │if a processing error occurs. │ └────────────────────────┴────────────────────────────────────┘
For more information about chained IORBs (IORB_CHAIN), see Adapter Device Driver Interface Questions and Answers.
Status
equals 0 on entry. Upon exit from the adapter device driver, Status
contains flags to indicate the command's completion status. (See the
following table.)
┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │IORB_DONE │Processing complete. If set, this │ │ │flag indicates that the adapter │ │ │device driver has completed │ │ │processing the request. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_ERROR │Error encountered. If set, this │ │ │flag indicates that an error │ │ │occurred while processing the │ │ │request. This flag should not be │ │ │set if the error was successfully │ │ │recovered by the adapter device │ │ │driver. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_RECOV_ERROR │Recoverable error. If set, this │ │ │flag indicates that, although an │ │ │error occurred, the adapter device │ │ │driver successfully recovered │ │ │through retries. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_STATUSBLOCK_AVAIL │Status information returned. If │ │ │set, this flag indicates that the │ │ │adapter device driver has returned │ │ │status information in the buffer │ │ │defined by pStatusBlock. │ └────────────────────────┴────────────────────────────────────┘
ErrorCode
equals 0, on entry. On exit from the driver, it contains the command's
completion error code. This field is valid only if the IORB_ERROR flag
in the Status field is set. The error codes are summarized in Error
Handling.
Timeout
contains the maximum number of seconds the driver will permit for command
completion before timing out. If this field is set to 0, the timeout value
assigned is the default set by the driver If this field is set to -1, the
timeout value assigned is infinite. The timeout period is measured from
the last valid contact (interrupt) with the target device. Therefore, if
the device interrupts periodically within the timeout interval, the interval
is reset after each interrupt.
StatusBlockLen
contains the size of the block of storage, in bytes, for the driver to return
status information (pStatusBlock). This field is valid only if the
IORB_REQ_STATUSBLOCK flag is set in the RequestControl field.
pStatusBlock
contains a near pointer to a block of storage (length = StatusBlockLength),
allocated by the caller, for the driver to return status information. On
exit from the driver, the storage area contains status information. This
field is valid only if the IORB_REQ_STATUSBLOCK flag is set in the RequestControl
field. The format of information in the status block depends on the
class of adapters the driver supports. For SCSI devices, see IORB
Status Block for more information.
Note: The pointer to the status block is a 16-bit near pointer. The status block must reside in the same segment as the IORB.
Reserved_1
is reserved for use by the device manager and must not be modified by the
adapter device driver.
pNxtIORB
contains a far pointer to the next IORB for chained commands. This field
is valid only if the IORB_CHAIN flag is set in the RequestControl field.
NotifyAddress
contains a far pointer to the notification routine to be called when the
request has completed successfully or aborted due to error conditions. This
field is valid only if the IORB_ASYNC_POST flag is set in the RequestControl
field. The notification routine should be called with a far pointer
to the command's IORB.
C Language Syntax
──────────────────────────────────────────────────────────────────────────
(FAR *piorb->NotifyAddress) (piorb);
──────────────────────────────────────────────────────────────────────────
Assembly Language Syntax
──────────────────────────────────────────────────────────────────────────
; ** ES:BX = IORB Pointer PUSH es ; IORB segment PUSH bx ; IORB offset CALL dword ptr es:[bx+IOH_NotifyAddress] ; Call notify routine add sp, 4 ; Cleanup stack
──────────────────────────────────────────────────────────────────────────
Note: The Notify routine will preserve only the DS, ES, SI, and DI registers.
DMWorkSpace[20]
defines a workspace, for use by the device manager, that must not be modified
by the device driver.
ADDWorkSpace[16]
defines a workspace for the adapter device driver that is ignored by the
device manager.
Command-Specific Data
contains the command-unique parameters. The commands and actual formats
of the corresponding IORBs are described in the following sections.