DASD, SCSI, and CD-ROM Device Manager Interface Specification
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
The IBM OS/2 2.0 (and later) DASD and SCSI device manager interface consists of direct call commands and Device Helper (DevHlp) services.
Contents
Direct Call Command Interface
All direct call commands are issued by the device managers (OS2DASD.DMD and OS2SCSI.DMD) or filter device drivers to an adapter device driver's registered entry point, with a global pointer to the Input/Output Request Block (IORB), as follows:
- C Language Syntax
#include <iorb.h> VOID (FAR * ADDEntryPoint) (piorb); PIORB piorb; /* Far pointer to the IORB control block */
- Assembly Language Syntax
#include <iorb.inc> ; ** ES:BX = IORB Pointer PUSH es ; IORB Segment PUSH bx ; IORB Offset CALL dword ptr AddEntryPoint ; Call adapter device driver ADD sp, 4 ; Clean-up stack
- Results
The results of the command are returned in the IORB.
The following table categorizes and lists the direct call commands used for the DASD and SCSI device manager interface:
Command Type | Commands |
---|---|
CONFIGURATION | GET_DEVICE_TABLE COMPLETE_INIT |
UNIT_CONTROL | ALLOCATE_UNIT DEALLOCATE_UNIT CHANGE_UNITINFO |
GEOMETRY | GET_MEDIA_GEOMETRY SET_MEDIA_GEOMETRY GET_DEVICE_GEOMETRY SET_LOGICAL_GEOMETRY |
EXECUTE_IO | READ READ_VERIFY READ_PREFETCH WRITE WRITE_VERIFY |
FORMAT | FORMAT_MEDIA FORMAT_TRACK FORMAT_PROGRESS |
UNIT_STATUS | GET_UNIT_STATUS CHANGELINE_STATE GET_MEDIA_SENSE GET_LOCK_STATUS |
DEVICE_CONTROL | ABORT RESET SUSPEND RESUME LOCK_MEDIA UNLOCK_MEDIA EJECT_MEDIA |
ADAPTER_PASSTHRU | EXECUTE_SCB EXECUTE_CDB |
DevHlp services introduced with the OS/2 2.0 operating system to support this strategy include:
- RegisterDeviceClass
- GetDOSVar
IORB Control Blocks
All direct call command control blocks are defined in the IBM-supplied IORB.H and IORB.INC Include files. (See #I/O Request Block - C Definitions.) The following sections, which describe the commands and their associated control blocks, are written from both C and assembler programmer's points of view, with references to the actual Include files and field names.
IORB General Format
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 Statusfield 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.
IORB CommandCode Format
The IORB CommandCode format is defined in the following section.
IOCC Configuration
The IOCC_CONFIGURATION CommandCode consists of all the CommandModifiers responsible for returning information about the characteristics of the devices supported by the driver, as follows:
IOCM_COMPLETE_INIT
Indicates that the driver can complete its initialization phase.
In the interval between driver initialization and receipt of this IORB, the device driver must not disable its INT 13h BIOS support because this support is needed to load other components of the operating system.
IOCM_GET_DEVICE_TABLE
Returns the DEVICETABLE structure in the buffer supplied by the caller. DEVICETABLE contains detailed information on each adapter and the associated units supported by the adapter device driver.
Remarks
Support: Mandatory
Called By: OS2DASD.DMD, other device manager, or filter device driver
Context of Call: TASK
Note: Any adapter device driver that registers by way of the RegisterDeviceClass DevHlp must process this IORB and return a valid DEVICETABLE, even if the driver supports 0 adapters.
Format of IORB
- IORB Type
- IORB_CONFIGURATION
- IORBH Fields
- CommandCode
- IOCC_CONFIGURATION
- CommandModifiers
- IOCM_COMPLETE_INIT
- IOCM_GET_DEVICE_TABLE
- Valid RequestControl Flags
- IORB_ASYNC_POST
- CommandCode
IORB_CONFIGURATION Description
This section defines the IORB_CONFIGURATION control block and the following associated structures:
DEVICETABLE Table of supported devices
ADAPTERINFO Adapter characteristics
UNITINFO Unit characteristics
DEVICETABLE Structure Overview
┌──────────────┐ │ pDeviceTable ├───►DEVICETABLE └──────────────┘ ┌─────────────────┐ ┌───┤ pAdapter[0] │ │ ├─────────────────┤ │┌──┤ pAdapter[1] │ ││ ├─────────────────┤ ││ │ . . . │ ││ ├─────────────────┤ ││┌─┤ pAdapter[N] │ │││ ├─────────────────┤ ┌───────────┐ └┼┼►│ ADAPTERINFO 0 ├────┤ ADAPTER 0 ├┐ ┌────────┐ ││ ├─────────────────┤ └───────────┘├─┤ UNIT 0 │ ││ │ UNITINFO[0] │ │ └────────┘ ││ │ UNITINFO[1] │ │ . . . ││ │ . . . │ │ ┌────────┐ ││ │ UNITINFO[N] │ └─┤ UNIT N │ ││ ├─────────────────┤ └────────┘ ││ ├─────────────────┤ ││ ├─────────────────┤ ┌───────────┐ └┼►│ ADAPTERINFO 1 ├────┤ ADAPTER 1 ├┐ ┌────────┐ │ ├─────────────────┤ └───────────┘├─┤ UNIT 0 │ │ │ UNITINFO[0] │ │ └────────┘ │ │ UNITINFO[1] │ │ . . . │ │ . . . │ │ ┌────────┐ │ │ UNITINFO[N] │ └─┤ UNIT N │ │ ├─────────────────┤ └────────┘ │ ├─────────────────┤ │ ├─────────────────┤ ┌───────────┐ └►│ ADAPTERINFO N ├────┤ ADAPTER N ├┐ ┌────────┐ ├─────────────────┤ └───────────┘├─┤ UNIT 0 │ │ UNITINFO[0] │ │ └────────┘ │ UNITINFO[1] │ │ . . . │ . . . │ │ ┌────────┐ │ UNITINFO[N] │ └─┤ UNIT N │ └─────────────────┘ └────────┘
IORB_CONFIGURATION
Field Name | C Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
pDeviceTable | FAR *PDEVICETABLE | DD | Device table |
DeviceTableLen | USHORT | DW | Length of table |
On entry to the driver:
iorbh
See IORB General Format.
pDeviceTable
contains a far pointer to a block of storage (length = DeviceTableLen), allocated by the caller, for the driver to return the DEVICETABLE.
DeviceTableLen
contains the length of the block of storage, in bytes, for the driver to return the DEVICETABLE (pDeviceTable).
DEVICETABLE
Field Name | C Type | Length | Description |
---|---|---|---|
ADDLevelMajor | UCHAR | DB | ADD major level |
ADDLevelMinor | UCHAR | DB | ADD minor level |
ADDHandle | USHORT | DW | ADD index |
TotalAdapters | USHORT | DW | Number of adapters |
pAdapter[N] | NPADAPTERINFO | DW(N) | AdapterInfo pointers |
On exit from the driver:
- ADDLevelMajor/ADDLevelMinor
- defines the level of support the adapter device driver is written to. A driver written to this specification (IBM 0S/2 2.0 Support Level), should set the fields as follows:
Field Name Value ADD_Level_Major ADD_LEVEL_MAJOR ADD_Level_Minor ADD_LEVEL_MINOR
- ADDHandle
- contains the adapter device driver's index returned by the RegisterDeviceClass DevHlp.
- TotalAdapters
- defines the number of adapters the device driver supports.
- pAdapter[N]
- contains an array of near ADAPTERINFO pointers. The number of elements in the array is determined by the TotalAdapters field.
AdapterInfo
Field Name | C Type | Length | Description |
---|---|---|---|
AdapterName[17] | UCHAR | DB(17) | ASCIIZ name |
Reserved | UCHAR | DB | Reserved. Must be 0. |
AdapterUnits | USHORT | DW | Number of units |
AdapterDevBus | USHORT | DW | Device bus types |
AdapterIOAccess | UCHAR | DB | Host I/O type |
AdapterHostBus | UCHAR | DB | Host bus type |
AdapterSCSITargetID | UCHAR | DB | Target ID |
AdapterSCSILUN | UCHAR | DB | Logical unit number |
AdapterFlags | USHORT | DW | Flags |
MaxHWSGList | USHORT | DW | Max HW s/g elements |
MaxCDBTransferLength | ULONG | DD | Max CDB data transfer length |
UnitInfo[N] | UNITINFO | DD(N) | Unit information |
On exit from the driver:
- AdapterName[17]
- contains the ASCIIZ name string of the adapter. This name is used by the caller for diagnostic purposes.
- Reserved
- contains a 0. This is a 16-bit alignment byte.
- AdapterUnits
- contains the number of units supported by this adapter.
- AdapterDevBus
- defines the adapter-to-device bus protocol used, as shown in the following table.
Protocol | Description |
---|---|
AI_DEVBUS_ST506 | DASD - ST506 CAM-I |
AI_DEVBUS_ST506_II | DASD - ST506 CAM-II |
AI_DEVBUS_ESDI | DASD - ESDI |
AI_DEVBUS_FLOPPY | DASD - Diskette |
AI_DEVBUS_SCSI_1 | SCSI - Version-I |
AI_DEVBUS_SCSI_2 | SCSI - Version-II |
AI_DEVBUS_SCSI_3 | SCSI - Version-III |
AI_DEVBUS_OTHER | Protocol not listed. |
AI_DEVBUS_NONSCSI_CDROM | non-SCSI CD-ROM interface |
One protocol should be elected. The AdapterDevBus protocol values can be OR'd with one or more modifier bits as listed in the following table.
Modifier | Description |
---|---|
AI_DEVBUS_FAST_SCSI | Fast SCSI bus timings |
AI_DEVBUS_8BIT | 8-bit bus width |
AI_DEVBUS_16BIT | 16-bit bus width |
AI_DEVBUS_32BIT | 32-bit bus width |
AdapterIOAccess
defines the adapter-to-host I/O data transfer capabilities, as shown in the following table.
Flag | Description |
---|---|
AI_IOACCESS_BUS_MASTER | 1st-party DMA adapter |
AI_IOACCESS_PIO | Programmed INs/OUTs |
AI_IOACCESS_DMA_SLAVE | 2nd-party DMA adapter |
AI_IOACCESS_MEMORY_MAP | Memory-mapped I/O |
AI_IOACCESS_OTHER | I/O access not listed. |
AdapterHostBus
defines the adapter-to-host bus type used, as shown in the following table.
Type | Device Connection |
---|---|
AI_HOSTBUS_ISA | ISA |
AI_HOSTBUS_EISA | Extended ISA |
AI_HOSTBUS_uCHNL | Micro-channel |
AI_HOSTBUS_OTHER | Bus type not listed. |
AI_HOSTBUS_UNKNOWN | Bus type unknown. |
Width | Description |
---|---|
AI_HOSTBUS_8BIT | 8-bit bus |
AI_HOSTBUS_16BIT | 16-bit bus |
AI_HOSTBUS_32BIT | 32-bit bus |
AI_HOSTBUS_64BIT | 64-bit bus |
AI_HOSTBUS_UNKNOWN | Bus width unknown. |
Note: One bus type should be set with one bus width OR'd in.
AdapterSCSITargetID
contains the target ID for the SCSI adapter. For non-SCSI devices, this field should be set to 0.
AdapterSCSILUN
contains the logical unit number for the SCSI adapter. For non-SCSI devices, this field should be set to 0.
AdapterFlags
defines the adapter's characteristics, as shown in the following table.
Flag | Description |
---|---|
AF_16M | >16M addresses supported. If set, this flag indicates that the adapter supports >16M addresses. |
AF_IBM_SCB | IBM SCB support. If set, this flag indicates that the adapter supports IBM SCB-formatted IOCC_ADAPTER_PASSTHRU requests. |
AF_HW_SCATGAT | Hardware scatter/gather. If set, this flag indicates that hardware supports scatter/gather. If this flag is not set, it indicates that the device driver is emulating the s/g function in software. |
AF_CHS_ADDRESSING | I/O addressing. If set, this flag indicates that the adapter supports cylinder/head/sector addressing. This flag should be set only for diskette controllers. |
AF_ASSOCIATED_DEVBUS | Multiple bus adapter. If set, this flag indicates that the adapter supports more than one device bus. An ADAPTERINFO and UNITINFO structure(s) should be created to describe each device bus. This flag must be set in each ADAPTERINFO structure for the adapter, except the first. |
MaxHWSGList
contains the maximum number of elements supported in a single hardware scatter/gather list. This field should be set to 0 if the adapter hardware supports an unlimited s/g list length.
Note: This is not a limit on the number of s/g elements an adapter device driver can receive in a scatter/gather list for an Execute_IO IORB.
See Adapter Device Driver Interface Questions and Answers for more information.
MaxCDBTransferLength
contains the maximum number of bytes supported by this adapter on a CDB- data transfer request.
This field is set in cases where a device driver needs to emulate s/g support in software and requires a fixed-size buffer to do so. This field should be set to 0 if an driver does not need to emulate its s/g function using an in-memory buffer.
See Adapter Device Driver Interface Questions and Answers for more information.
UnitInfo[N]
contains an array of UNITINFO structures as shown in the following table. The number of elements in the array is determined by the AdapterUnits field.
UNITINFO Structure
Element | C Type | Length | Description |
---|---|---|---|
AdapterIndex | USHORT | DW | Associated AdapterIndex |
UnitIndex | USHORT | DW | Unit tag |
UnitFlags | USHORT | DW | Unit flags |
Reserved | USHORT | DW | Reserved. Must be 0. |
UnitHandle | USHORT | DW | Assigned by adapter device driver |
FilterADDHandle | USHORT | DW | Filter device driver handle |
UnitType | USHORT | DW | Unit type |
QueuingCount | USHORT | DW | IORB queue length |
UnitSCSITargetID | UCHAR | DB | SCSI target ID |
UnitSCSILUN | UCHAR | DB | SCSI logical unit number |
On exit from the driver:
- AdapterIndex
- contains the unit's corresponding adapter's index in the pAdapter[N] array.
- UnitIndex
- contains the unit's index in the UnitInfo[N] array.
- UnitFlags
- defines the unit's characteristics, as shown in the following table.
Flag | Description |
---|---|
UF_REMOVABLE | Media can be removed. If set, this flag indicates that the unit's media is removable. |
UF_CHANGELINE | Changeline supported. If set, this flag indicates that the unit can detect media removal. |
UF_PREFETCH | Read Prefetch supported. If set, this flag indicates the unit supports read prefetch. |
UF_A_DRIVE | Manages drive A. If set, this flag indicates that the unit manages drive A. |
UF_B_DRIVE | Manages drive B. If set, this flag indicates that the unit manages drive B. |
UF_NODASD_SUPT | Suppress DASD device manager. If set, this flag indicates that the driver does not want this unit to be managed by the OS2DASD.DMD device manager. |
UF_NOSCSI_SUPT | Suppress SCSI device manager. If set, this flag indicates that the driver does not want this unit to be managed by the OS2SCSI.DMD device manager. |
UF_DEFECTIVE | Device is defective. If set, this flag indicates that the unit is not operational. Defective units are ignored by the DASD and SCSI device managers. However, the driver should accept allocation requests for the unit and pass commands to the unit for other device managers. The information returned by the IOCM_UNIT_STATUS command reflects this flag's current setting. |
- Reserved
- is reserved for future growth. Must be set to 0 by the adapter device driver.
- UnitHandle
- defines the unit's handle. This handle is a unique ID, assigned by either the filter device driver or the adapter device driver. A unit is fully identified by the UnitHandlefield and its associated ADD's handle, defined by either the FilterADDHandleor ADDHandlefields.
- FilterADDHandle
- contains the handle of the filter device driver. If a filter device driver does not exist, this field must be 0. See Using Filter Device Drivers for more information on filter device drivers.
- UnitType
- defines the unit's device type. Unit types and their supported devices are shown in the following table.
UnitType | Devices Supported |
---|---|
UIB_TYPE_DISK | Direct access (DASD) |
UIB_TYPE_TAPE | Tape |
UIB_TYPE_PRINTER | Printer |
UIB_TYPE_PROCESSOR | Processor |
UIB_TYPE_WORM | Write Once/Read Many |
UIB_TYPE_CDROM | CD ROM |
UIB_TYPE_SCANNER | Scanner |
UIB_TYPE_OPTICAL_MEMORY | Optical disk |
UIB_TYPE_CHANGER | Changer (example, jukebox) |
UIB_TYPE_COMM | Communication |
Note: One unit type must be set.
QueuingCount
defines the recommended number of commands to queue for this unit.
Note: Do not design drivers assuming a fixed length queue.
This field provides to the device manager the recommended queue length for optimum performance.
UnitSCSITargetID
contains the target ID for SCSI devices. For all other devices, this field equals 0.
UnitSCSILUN
contains the logical unit number for SCSI devices. For all other devices, this field equals 0.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_CONFIGURATION request.
Return Codes
Following is a list of the IOCC_CONFIGURATION error codes:
- IOERR_CMD_SYNTAX
- IOERR_CMD_SW_RESOURCE.
For a detailed description of all the return codes, see Error Handling.
IOCC_UNIT_CONTROL
The IOCC_UNIT_CONTROL CommandCode consists of all the CommandModifiers responsible for controlling the ownership of a unit. The following table describes the CommandModifiers.
CommandModifier | Description |
---|---|
IOCM_ALLOCATE_UNIT | Assigns ownership of the specified unit to the caller. A unit must be allocated prior to accepting any other direct call commands. Once allocated, a unit cannot be assigned to another owner until that unit is deallocated. It is the responsibility of the owner to coordinate sharing of a unit. |
IOCM_DEALLOCATE_UNIT | Removes the caller's ownership of the specified unit. Once deallocated, a unit can be assigned to another owner. |
IOCM_CHANGE_UNITINFO | Modifies the specified unit's UNITINFO portion of the DEVICETABLE structure with the information passed by the caller. |
Remarks
Support: Mandatory
- Called By: OS2DASD.DMD, other device manager, or filter device driver
- Context of Call: TASK
- Format of IORB
- IORB Type
- IORB_UNIT_CONTROL
- IORBH Fields
- CommandCode
- IOCC_CONFIGURATION
- CommandModifiers
- IOCM_ALLOCATE_UNIT
- IOCM_DEALLOCATE_UNIT
- IOCM_CHANGE_UNITINFO
- Valid RequestControlFlags
- IORB_ASYNC_POST
- CommandCode
IORB_UNIT_CONTROL Description
This section defines the IORB_UNIT_CONTROL control block. (See the table below.)
Field Name | C Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
Flags | USHORT | DW | Flags |
pUnitInfo | PUNITINFO | DD | Pointer to UnitInfo |
UnitInfoLen | USHORT | DW | Length of UnitInfo |
On entry to the driver:
- iorbh
- See IORB General Format.
- Flags
- contains a 0.
- pUnitInfo
- contains a far pointer to a buffer containing modified unit characteristics, in the format defined by the UNITINFO structure. The adapter device driver uses this information to update the unit's UNITINFO structure in the DEVICETABLE. This field is valid only for the IOCM_CHANGE_UNITINFO CommandModifier.
- Note
- A device driver can access the UNITINFO structure provided by the IOCM_CHANGE_UNITINFO IORB at any time. The caller, therefore, must not invalidate or release the passed UNITINFO structure on successful completion of this IORB request.
- UnitInfoLen
- contains the length, in bytes, of the UNITINFO buffer (pUnitInfo) passed to the driver. This field is valid only for the IOCM_CHANGE_UNITINFO CommandModifier.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_UNIT_CONTROL request.
Return Codes
Following is a list of the IOCC_UNIT_CONTROL error codes:
- IOERR_CMD_SYNTAX
- IOERR_CMD_SW_RESOURCE
- IOERR_UNIT_ALLOCATED
- IOERR_UNIT_NOT_ALLOCATED
For a detailed description of all the return codes, see Error Handling.
IOCC_GEOMETRY
The IOCC_GEOMETRY CommandCode consists of all the CommandModifiers responsible for setting and returning information about the capacity of a unit.
The CommandModifiers are described in the following table:
CommandModifier | Description |
---|---|
IOCM_GET_MEDIA_GEOMETRY | Returns the geometry of the current media in a drive.
For non-removable media devices, the geometry returned must be identical to the geometry returned by IOCM_GET_DEVICE_GEOMETRY. |
IOCM_SET_MEDIA_GEOMETRY | Informs the adapter device driver of the required media geometry in preparation for formatting. This command is mandatory only for standard diskette media. |
IOCM_GET_DEVICE_GEOMETRY | Returns the device geometry compatible with INT 13h BIOS function 08h.
If the INT 13h support for a device provides translation, the INT 13h geometry of the device must be returned with the BIOS translation performed within the driver. That is, the driver must emulate any INT 13h translation performed by BIOS. |
IOCM_SET_LOGICAL_GEOMETRY | Indicates that the geometry recorded in the file system tables on the media does not match the physical media geometry reported by the device driver.
The driver should convert RBA to CHS addresses according to the geometry passed in this IORB, rather than using the media geometry the driver is reporting. The device driver should stop performing this translation if a media change indication is detected. Support of this command is mandatory only for standard diskette media. |
Remarks
Support: Mandatory (See CommandModifiers for exceptions.)
Called By: OS2DASD.DMD, other device manager, or filter device driver
Context of Call:TASK, INTERRUPT
Format of IORB
- IORB Type
- IORB_GEOMETRY
- IORBH Fields
- CommandCode
- IOCC_GEOMETRY
- CommandModifiers
- IOCM_GET_MEDIA_GEOMETRY
- IOCM_SET_MEDIA_GEOMETRY
- IOCM_GET_DEVICE_GEOMETRY
- IOCM_SET_LOGICAL_GEOMETRY
- Valid RequestControlFlags
- IORB_ASYNC_POST
- IORB_REQ_STATUSBLOCK
- IORB_DISABLE_RETRY
- CommandCode
IOCC_GEOMETRY Description
This section defines the IORB_GEOMETRY and GEOMETRY control blocks. (See the table below.)
Field Name | C Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
pGeometry | PGEOMETRY | DD | Pointer to GEOMETRY |
GeometryLen | USHORT | DW | Length of GEOMETRY data |
On entry to the driver:
- iorbh
- See IORB General Format.
- pGeometry
- contains a far pointer to the block of storage (length = GeometryLen) allocated by the caller for the GEOMETRY.
- GeometryLen
- contains the size of the block of storage, in bytes, for the GEOMETRY structure (pGeometry).
GEOMETRY Description
Field Name | C Type | Length | Description |
---|---|---|---|
TotalSectors | ULONG | DD | Number of sectors |
BytesPerSector | USHORT | DW | Bytes per sector |
Reserved | USHORT | DW | Reserved |
NumHeads | USHORT | DW | Number of heads |
TotalCylinders | ULONG | DD | Number of cylinders |
SectorsPerTrack | USHORT | DW | Number of sectors per track |
On entry to the driver for SET CommandModifiers, and on exit from the driver for GET CommandModifiers, the following apply:
TotalSectors
contains the total number of sectors.
BytesPerSector
contains the number of bytes per sector. The IBM OS/2 2.0 File System supports only a value of 512.
Reserved
contains a 0. This alignment field ensures that the GEOMETRY structure aligns with SCSI Read Capacity output.
NumHeads
contains the number of heads.
TotalCylinders
contains the number of cylinders.
SectorsPerTrack
contains the number of sectors per track.
Note: SCSI devices normally do not support cylinder/head/sector (CHS) addressing. However, to maintain INT 13h BIOS compatibility, most controllers create CHS mapping for the devices they support. For non-boot devices, which do not provide INT 13h support, NumHeads, TotalCylinders, and SectorsPerTrack can be set to 0, and the device manager will select appropriate CHS values.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_GEOMETRY request.
Return Codes
Following is a list of the IOCC_GEOMETRY error codes:
- IOERR_CMD_NOT_SUPPORTED
- IOERR_CMD_SYNTAX
- IOERR_CMD_SW_RESOURCE
- IOERR_UNIT_NOT_ALLOCATED
- IOERR_UNIT_NOT_READY
- IOERR_UNIT_PWR_OFF
- IOERR_MEDIA_NOT_FORMATTED
- IOERR_MEDIA_NOT_SUPPORTED
- IOERR_MEDIA_CHANGED
- IOERR_MEDIA_NOT_PRESENT
- IOERR_ADAPTER_HOSTBUSCHECK
- IOERR_ADAPTER_DEVICEBUSCHECK
- IOERR_ADAPTER_OVERRUN
- IOERR_ADAPTER_UNDERRUN
- IOERR_ADAPTER_DIAGFAIL
- IOERR_ADAPTER_TIMEOUT
- IOERR_ADAPTER_DEVICE_TIMEOUT
- IOERR_ADAPTER_REQ_NOT_SUPPORTED
- IOERR_ADAPTER_REFER_TO_STATUS
- IOERR_DEVICE_DEVICEBUSCHECK
- IOERR_DEVICE_REQ_NOT_SUPPORTED
- IOERR_DEVICE_DIAGFAIL
- IOERR_DEVICE_BUSY
- IOERR_DEVICE_OVERRUN
- IOERR_DEVICE_UNDERRUN
For a detailed description of all the return codes, see Error Handling.
IOCC_EXECUTE_IO
The IOCC_EXECUTE_IO CommandCode consists of all CommandModifiers responsible for issuing a Read or Write to a unit. The following table describes the IOCC_EXECUTE_IO CommandModifiers:
CommandModifier | Description |
---|---|
IOCM_READ | Reads a unit's data into the scatter/gather list buffers. |
IOCM_READ_VERIFY | Verifies that the recorded data at the requested I/O address is readable. No data is transferred. |
IOCM_READ_PREFETCH | Reads data from the device into the adapter's hardware
cache. Support of this command is optional. |
IOCM_WRITE | Writes data from the scatter/gather list buffers to the unit's
specified I/O address. |
IOCM_WRITE_VERIFY |
- Remarks
- Support: Mandatory
- Called By: OS2DASD.DMD, other device manager, or filter device driver
- Context of Call: TASK, INTERRUPT
- Format of IORB
- IORB Type
- IORB_EXECUTEIO
- IORBH Fields
- CommandCode
- IOCC_EXECUTE_IO
- CommandModifiers
- IOCM_READ
- IOCM_READ_VERIFY
- IOCM_READ_PREFETCH
- IOCM_WRITE
- IOCM_WRITE_VERIFY
- Valid RequestControlFlags
- IORB_ASYNC_POST
- IORB_CHAIN
- IORB_CHS_ADDRESSING
- (Diskette only, see AF_CHS_ADDRESSING)
- IORB_REQ_STATUSBLOCK
- IORB_DISABLE_RETRY
- CommandCode
IORB_EXECUTEIO Description
This section defines the IORB_EXECUTEIO control block. (See the following table.)
Field Name | C Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
cSGLIST | USHORT | DW | Number of elements |
pSGLIST | PSCATGATENTRY | DD | Far pointer to s/g list |
ppSGLIST | ULONG | DD | Physical address of s/g list |
RBA | ULONG | DD | I/O starting address |
BlockCount | USHORT | DW | Sector count |
BlocksXferred | USHORT | DW | Number of sectors transferred |
BlockSize | USHORT | DW | Number of bytes per sector |
Flags | USHORT | DW | I/O-specific flags |
On entry to the driver:
iorbh
See IORB General Format.
cSGList
contains the number of scatter/gather elements in the scatter/gather list ( pSGLIST).
pSGLIST
contains a far pointer to the scatter/gather list, supplied by the caller. The scatter/gather list consists of an array of cSGList elements, each pointing to a physically contiguous area of real memory in a format defined by the SCATGATENTRY structure. (See the following table.)
Field Name | C Type | Length | Description |
---|---|---|---|
ppXferBuf | ULONG | DD | Physical pointer to buffer |
XferBufLen | ULONG | DD | Length of buffer |
ppSGLIST
contains a 32-bit physical address of the scatter/gather list.
RBA
contains the starting relative block address for the data transfer operation. If the IORB_CHS_ADDRESSING flag is set in the IORBH RequestControl field, then the format of the RBA field is defined by the CHS_ADDR structure. (See the following table.)
Field Name | C Type | Length | Description |
Cylinder | USHORT | DW | Starting cylinder |
Head | UCHAR | DB | Starting head |
Sector | UCHAR | DB | Starting sector |
BlockCount
contains the number of sectors (length = BlockSize) to transfer.
Note:If this value exceeds the adapter's maximum transfer size, the driver is responsible for issuing multiple operations to the unit to complete the caller's request.
BlocksXferred
equals 0 on entry. On exit from the driver BlocksXferred contains the number of sectors successfully transferred.
BlockSize
contains the number of bytes in a block or sector. The IBM OS/2 2.0 File System supports only a value of 512.
Flags
defines Execute I/O cache control flags, as shown in the table below.
Flag | Description |
---|---|
XIO_DISABLE_HW_WRITE_CACHE | Disable-deferred Write.
Indicates the driver should ensure that the requested data is written to the media prior to doing a notification callout. |
XIO_DISABLE_HW_READ_CACHE | Disable Read caching.
Indicates to the driver that the data being read is of a transient nature and does not need to be retained in the adapter's hardware cache. |
Note: The scatter/gather list-related fields (cSGLIST, pSGLIST, and ppSGLIST) are at the same offset as their equivalent pointers in the IOCC_ ADAPTER_PASSTHRU and IOCC_FORMAT CommandCodes.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_EXECUTE_IO request.
Return Codes
Following is a list of the IOCC_EXECUTE_IO error codes:
- IOERR_CMD_NOT_SUPPORTED
- IOERR_CMD_SYNTAX
- IOERR_CMD_SGLIST_BAD
- IOERR_CMD_SW_RESOURCE
- IOERR_CMD_ABORTED
- IOERR_UNIT_NOT_ALLOCATED
- IOERR_UNIT_NOT_READY
- IOERR_UNIT_PWR_OFF
- IOERR_RBA_ADDRESSING_ERROR
- IOERR_RBA_LIMIT
- IOERR_RBA_CRC_ERROR
- IOERR_MEDIA_NOT_FORMATTED
- IOERR_MEDIA_NOT_SUPPORTED
- IOERR_MEDIA_WRITE_PROTECT
- IOERR_MEDIA_CHANGED
- IOERR_MEDIA_NOT_PRESENT
- IOERR_ADAPTER_HOSTBUSCHECK
- IOERR_ADAPTER_DEVICEBUSCHECK
- IOERR_ADAPTER_OVERRUN
- IOERR_ADAPTER_UNDERRUN
- IOERR_ADAPTER_DIAGFAIL
- IOERR_ADAPTER_TIMEOUT
- IOERR_ADAPTER_DEVICE_TIMEOUT
- IOERR_ADAPTER_REQ_NOT_SUPPORTED
- IOERR_ADAPTER_REFER_TO_STATUS
- IOERR_DEVICE_DEVICEBUSCHECK
- IOERR_DEVICE_REQ_NOT_SUPPORTED
- IOERR_DEVICE_DIAGFAIL
- IOERR_DEVICE_BUSY
- IOERR_DEVICE_OVERRUN
- IOERR_DEVICE_UNDERRUN
For a detailed description of all the return codes, see Error Handling.
IOCC_FORMAT
The IOCC_FORMAT CommandCode consists of all CommandModifiers responsible for unit format requests. The following table describes the IOCC_FORMAT CommandModifiers:
CommandModifier | Description |
---|---|
IOCM_FORMAT_MEDIA | Formats the entire media in the unit. Support of this
command is mandatory for SCSI devices that require low-level formatting. |
IOCM_FORMAT_TRACK | Formats the specified track on the
unit. Support of this command is mandatory for standard diskette media. |
IOCM_FORMAT_PROGRESS | Reports the progress of the formatting. Support of this command is mandatory for standard diskette
media. |
Remarks
Support: See CommandModifiers.
Called By: OS2DASD.DMD, other device manager, or filter device driver
Context of Call: TASK, INTERRUPT
Format of IORB
- IORB Type
- IORB_FORMAT
- IORBH Fields
- RequestControl: Flags can be enabled or disabled.
- CommandCode
- IOCC_FORMAT
- CommandModifiers
- IOCM_FORMAT_MEDIA
- IOCM_FORMAT_TRACK
- IOCM_FORMAT_PROGRESS
- Valid RequestControl Flags
- IORB_ASYNC_POST
- IORB_CHS_ADDRESSING
- (Diskette only, see AF_CHS_ADDRESSING)
- IORB_REQ_STATUSBLOCK
- IORB_DISABLE_RETRY
IORB_FORMAT Description:
This section defines the IORB_FORMAT control block. (See the following table.)
Field Name | C Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
cSGLIST | USHORT | DW | Number of elements |
pSGLIST | PSCATGATENTRY | DD | Far pointer to s/g list |
ppSGLIST | ULONG | DD | Physical address of s/g list |
FormatCmdLen | USHORT | DW | Length of Format command |
pFormatCmd | PBYTE | DD | Pointer to Format command |
Reserved_1 | UCHAR | DB(8) | Reserved. |
On entry to the driver:
iorbh
See IORB General Format.
cSGList
contains the number of scatter/gather elements in the scatter/gather list ( pSGLIST).
pSGLIST
contains a far pointer to the scatter/gather list, supplied by the caller. The scatter/gather list consists of an array of cSGList elements, each pointing to a physically contiguous area of real memory in a format defined by the SCATGATENTRY structure. (See the following table.)
Field Name | C Type | Length | Description |
---|---|---|---|
ppXferBuf | ULONG | DD | Physical pointer to buffer |
XferBufLen | ULONG | DD | Length of buffer |
ppSGLIST
contains a 32-bit physical address of the scatter/gather list.
RBA
contains the starting relative block address for the data transfer operation. If the IORB_CHS_ADDRESSING flag is set in the IORBH RequestControl field, then the format of the RBA field is defined by the CHS_ADDR structure. (See the following table.)
Field Name | C Type | Length | Description |
---|---|---|---|
Cylinder | USHORT | DW | Starting cylinder |
Head | UCHAR | DB | Starting head |
Sector | UCHAR | DB | Starting sector |
BlockCount
contains the number of sectors (length = BlockSize) to transfer.
Note:If this value exceeds the adapter's maximum transfer size, the driver is responsible for issuing multiple operations to the unit to complete the caller's request.
BlocksXferred
equals 0 on entry. On exit from the driver BlocksXferred contains the number of sectors successfully transferred.
BlockSize
contains the number of bytes in a block or sector. The IBM OS/2 2.0 File System supports only a value of 512.
Flags
defines Execute I/O cache control flags, as shown in the table below.
Flag | Description |
---|---|
XIO_DISABLE_HW_WRITE_CACHE | Disable-deferred Write. Indicates the driver should ensure that the requested data is written to the media prior to doing a notification callout. |
XIO_DISABLE_HW_READ_CACHE | Disable Read caching. Indicates to the driver that the data being read is of a transient nature and does not need to be retained in the adapter's hardware cache. |
Note: The scatter/gather list-related fields (cSGLIST, pSGLIST, and ppSGLIST) are at the same offset as their equivalent pointers in the IOCC_ ADAPTER_PASSTHRU and IOCC_FORMAT CommandCodes.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_EXECUTE_IO request.
Return Codes
Following is a list of the IOCC_EXECUTE_IO error codes:
IOERR_CMD_NOT_SUPPORTED
IOERR_CMD_SYNTAX
IOERR_CMD_SGLIST_BAD
IOERR_CMD_SW_RESOURCE
IOERR_CMD_ABORTED
IOERR_UNIT_NOT_ALLOCATED
IOERR_UNIT_NOT_READY
IOERR_UNIT_PWR_OFF
IOERR_RBA_ADDRESSING_ERROR
IOERR_RBA_LIMIT
IOERR_RBA_CRC_ERROR
IOERR_MEDIA_NOT_FORMATTED
IOERR_MEDIA_NOT_SUPPORTED
IOERR_MEDIA_WRITE_PROTECT
IOERR_MEDIA_CHANGED
IOERR_MEDIA_NOT_PRESENT
IOERR_ADAPTER_HOSTBUSCHECK
IOERR_ADAPTER_DEVICEBUSCHECK
IOERR_ADAPTER_OVERRUN
IOERR_ADAPTER_UNDERRUN
IOERR_ADAPTER_DIAGFAIL
IOERR_ADAPTER_TIMEOUT
IOERR_ADAPTER_DEVICE_TIMEOUT
IOERR_ADAPTER_REQ_NOT_SUPPORTED
IOERR_ADAPTER_REFER_TO_STATUS
IOERR_DEVICE_DEVICEBUSCHECK
IOERR_DEVICE_REQ_NOT_SUPPORTED
IOERR_DEVICE_DIAGFAIL
IOERR_DEVICE_BUSY
IOERR_DEVICE_OVERRUN
IOERR_DEVICE_UNDERRUN
For a detailed description of all the return codes, see Error Handling.
IOCC_FORMAT
The IOCC_FORMAT CommandCode consists of all CommandModifiers responsible for unit format requests. The following table describes the IOCC_FORMAT CommandModifiers:
CommandModifier | Description |
---|---|
IOCM_FORMAT_MEDIA | Formats the entire media in the unit. Support of this command is mandatory for SCSI devices that require low-level formatting. |
IOCM_FORMAT_TRACK | Formats the specified track on the unit. Support of this command is mandatory for standard diskette media. |
IOCM_FORMAT_PROGRESS | Reports the progress of the formatting. Support of this command is mandatory for standard diskette media. |
Remarks
Support: See CommandModifiers.
Called By: OS2DASD.DMD, other device manager, or filter device driver
Context of Call: TASK, INTERRUPT
Format of IORB
- IORB Type
- -IORB_FORMAT
- IORBH Fields
- -RequestControl: Flags can be enabled or disabled.
- -CommandCode
- --IOCC_FORMAT
- -CommandModifiers
- --IOCM_FORMAT_MEDIA
- --IOCM_FORMAT_TRACK
- --IOCM_FORMAT_PROGRESS
- -Valid RequestControlFlags
- --IORB_ASYNC_POST
- --IORB_CHS_ADDRESSING
- (Diskette only, see AF_CHS_ADDRESSING)
- --IORB_REQ_STATUSBLOCK
- --IORB_DISABLE_RETRY
IORB_FORMAT Description:
This section defines the IORB_FORMAT control block. (See the following table.)
Field Name | C Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
cSGLIST | USHORT | DW | Number of elements |
pSGLIST | PSCATGATENTRY | DD | Far pointer to s/g list |
ppSGLIST | ULONG | DD | Physical address of s/g list |
FormatCmdLen | USHORT | DW | Length of Format command |
pFormatCmd | PBYTE | DD | Pointer to Format command |
Reserved_1 | UCHAR | DB(8) | Reserved. |
On entry to the driver:
iorbh
See IORB General Format.
cSGList
contains the number of scatter/gather elements in the scatter/gather list ( pSGLIST).
pSGLIST
contains a far pointer to the scatter/gather list supplied by the caller. The scatter/gather list consists of an array of cSGList elements, each pointing to a physically contiguous area of real memory in a format defined by the SCATGATENTRY structure. (See the following table.)
Field Name | C Type | Length | Description |
---|---|---|---|
ppXferBuf | ULONG | DD | Physical pointer to buffer |
XferBufLen | ULONG | DD | Length of buffer |
ppSGLIST
contains a 32-bit physical address of the scatter/gather list.
Note: For IOCM_FORMAT_MEDIA, the s/g pointers will point to a Format Unit Parameter List as defined by the SCSI-2 specification.
If the SCSI Format Unit CDB does not require a parameter list and other command modifiers, the s/g pointers must be 0.
FormatCmdLen
contains the length of the format command (pFormatCmd), in bytes.
pFormatCmd
contains a pointer to device-specific formatting information. For diskette controllers, this points to the FORMAT_CMD_TRACK structure (see the table below). For SCSI devices, this points to a SCSI Format Unit CDB.
Field Name | C Type | Length | Description |
---|---|---|---|
Flags | USHORT | DW | Flags |
RBA | ULONG | DD | Starting RBA |
cTrackEntries | USHORT | DW | Number of track entries |
On entry to the driver:
Flags
contains flags to define the request, as shown in the following table.
Flag | Description |
---|---|
FF_VERIFY | Verify after format. If set, this flag indicates that the driver should verify the sectors after formatting. |
RBA
contains the starting relative block address for an IOCM_FORMAT_TRACK request. For IOCM_FORMAT_MEDIA and IOCM_FORMAT_PROGRESS requests, this field equals 0. If the IORB_CHS_ADDRESSING flag is set in the IORBH-> RequestControl field, then the format of the RBA field is defined by the CHS_ADDR structure, shown in the following table.
Field Name | C Type | Length | Description |
---|---|---|---|
Cylinder | USHORT | DW | Starting cylinder |
Head | UCHAR | DB | Starting head |
Sector | UCHAR | DB | Starting sector |
Note: The scatter/gather list-related fields (cSGLIST, pSGLIST, and ppSGLIST) are at the same offset as its equivalent pointers in the IOCC_ EXECUTE_IO and IOCC_ADAPTER_PASSTHRU CommandCodes.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_FORMAT request.
Return Codes
Following is a list of the IOCC_FORMAT error codes:
- IOERR_CMD_NOT_SUPPORTED
- IOERR_CMD_SYNTAX
- IOERR_CMD_SW_RESOURCE
IOERR_CMD_ABORTED
IOERR_UNIT_NOT_ALLOCATED
IOERR_UNIT_NOT_READY
IOERR_UNIT_PWR_OFF
IOERR_RBA_ADDRESSING_ERROR
IOERR_RBA_LIMIT
IOERR_RBA_CRC_ERROR
IOERR_MEDIA_NOT_SUPPORTED
IOERR_MEDIA_WRITE_PROTECT
IOERR_MEDIA_CHANGED
IOERR_MEDIA_NOT_PRESENT
IOERR_ADAPTER_HOSTBUSCHECK
IOERR_ADAPTER_DEVICEBUSCHECK
IOERR_ADAPTER_OVERRUN
IOERR_ADAPTER_UNDERRUN
IOERR_ADAPTER_DIAGFAIL
IOERR_ADAPTER_TIMEOUT
IOERR_ADAPTER_DEVICE_TIMEOUT
IOERR_ADAPTER_REQ_NOT_SUPPORTED
IOERR_ADAPTER_REFER_TO_STATUS
IOERR_DEVICE_DEVICEBUSCHECK
IOERR_DEVICE_REQ_NOT_SUPPORTED
IOERR_DEVICE_DIAGFAIL
IOERR_DEVICE_BUSY
IOERR_DEVICE_OVERRUN
IOERR_DEVICE_UNDERRUN
For a detailed description of all the return codes, see Error Handling.
IOCC_UNIT_STATUS
The IOCC_UNIT_STATUS CommandCode consists of all the CommandModifiers responsible for returning a unit's current status. The following table describes these CommandModifiers:
CommandModifier | Description |
---|---|
IOCM_GET_UNIT_STATUS | Returns flags indicating the unit's current Ready, Power On, and Defective status. For SCSI devices, if a SCSI Target is detected, the driver must issue a SCSI Test Unit Ready command to obtain the current unit status. |
IOCM_GET_CHANGELINE_STATE | Returns the unit's current changeline state. This command is mandatory for standard diskette devices. |
IOCM_GET_MEDIA_SENSE | Returns the unit's current media storage capacity. This command is mandatory for standard diskette devices. |
IOCM_GET_LOCK_STATUS | Returns media sense information This command is mandatory for standard diskette devices. |
Remarks
Support: Mandatory (See CommmandModifiers for exceptions.)
Called By: OS2DASD.DMD, other device manager, or filter device driver
Context of Call: TASK, INTERRUPT
Format of IORB
- IORB Type
-IORB_UNIT_STATUS
*IORBH Fields
-CommandCode
--IOCC_UNIT_STATUS
-CommandModifiers
--IOCM_GET_UNIT_STATUS
--IOCM_GET_CHANGELINE_STATE
--IOCM_GET_MEDIA_SENSE
--IOCM_GET_LOCK_STATUS
-Valid RequestControlFlags
--IORB_ASYNC_POST
--IORB_REQ_STATUSBLOCK
IORB_UNIT_STATUS Description
This section defines the IORB_UNIT_STATUS control block.
IORB_UNIT_STATUS
Field Name | C-Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
UnitStatus | USHORT | DW | Unit status |
On entry to the driver:
iorbh
See IORB General Format.
UnitStatus
equals 0, on entry. On exit from the driver, this field contains the status information request, based on the CommandModifier field, as shown in the following table.
CommandModifier | Description |
---|---|
IOCM_GET_UNIT_STATUS US_READY US_POWER US_DEFECTIVE |
Unit in Ready state Unit Powered On Unit Defective |
Changeline occurred | |
IOCM_GET_MEDIA_SENSE US_MEDIA_144MB US_MEDIA_288MB US_MEDIA_720KB US_MEDIA_UNKNOWN |
144KB media capacity 288KB media capacity 720KB media capacity Media capacity unknown |
IOCM_GET_LOCK_STATUS US_LOCKED |
Unit Locked |
Remarks
- The UnitStatus field reports the general status of the unit. If the adapter device driver encounters a SCSI Check condition, it must convert any retrieved sense data into IOERR_* error codes and report these in the IORBH->ErrorCode field in addition to setting the UnitStatus field.
- The reporting of units that are powered-off is optional. The driver possibly might be able to determine powered-off units from configuration data stored in non-volatile memory.
- The detection of defective units is optional.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_UNIT_STATUS request.
Return Codes
For a detailed description of all the return codes, see IORB General Format.
IOCC_DEVICE_CONTROL
The IOCC_DEVICE_CONTROL CommandCode consists of all the CommmandModifiers responsible for device control.
The following table describes the IOCC_DEVICE_CONTROL CommandModifiers:
CommandModifier | Description |
---|---|
IOCM_ABORT | Aborts the unit's current operation and causes the driver to return any pending work in its queues. Support is mandatory for SCSI devices. |
IOCM_RESET | Resets the unit to its default operating parameters. Support is mandatory for SCSI devices. |
IOCM_SUSPEND | Suspends the unit's current operation. This command provides for sharing disk controller hardware with other device drivers. Support is mandatory for diskette controllers. |
IOCM_RESUME | Resumes the unit's suspended operation. This command provides for the sharing of the diskette controller with other device drivers. Support is mandatory for diskette controllers. |
IOCM_LOCK_MEDIA | Locks the current media in the unit. Support is mandatory for SCSI adapter device drivers and for other devices that support a media-locking function. |
IOCM_UNLOCK_MEDIA | Unlocks the current media from the unit. Mandatory for SCSI adapter device drivers and for other devices that support a media-locking function. |
IOCM_EJECT_MEDIA | Ejects the current media from the unit. Mandatory for SCSI adapter device drivers and for other devices that support a media-locking function. |
Remarks
Support: See the command descriptions.
Called By: OS2DASD.DMD, other device manager, or filter device driver
Context of Call:TASK, INTERRUPT
Format of IORB
- IORB Type
- IORB_DEVICE_CONTROL
- IORBH Fields
- CommandCode
- IOCC_DEVICE_CONTROL
- CommandModifiers
- IOCM_ABORT
- IOCM_RESET
- IOCM_SUSPEND
- IOCM_RESUME
- IOCM_LOCK_MEDIA
- IOCM_UNLOCK_MEDIA
- IOCM_EJECT_MEDIA
- Valid RequestControl Flags
- IORB_ASYNC_POST
- IORB_REQ_STATUSBLOCK
- IORB_DISABLE_RETRY
- CommandCode
IORB_DEVICE_CONTROL Description
This section defines the IORB_DEVICE_CONTROL control block. (See the following table.)
Field Name | C-Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
Flags | USHORT | DW | Flags |
Reserved | USHORT | DW | Reserved |
On entry to the driver:
- iorbh
- See IORB General Format.
- Flags
- contains flags defined only for IOCM_SUSPEND requests. For all other requests, this field equals 0.
The following table describes the IOCM_SUSPEND flags.
Flag | Description |
---|---|
DC_SUSPEND_DEFERRED | Suspend on idle. If set, this flag indicates that the suspend should occur once the unit is idle. |
DC_SUSPEND_IMMEDIATE | Suspend immediate. If set this flag indicates that the suspend should occur once the current request is complete. |
- Reserved
- contains a 0.
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_DEVICE_CONTROL request.
Return Codes
Following is a list of the IOCC_DEVICE_CONTROL error codes:
- IOERR_CMD_NOT_SUPPORTED
- IOERR_CMD_SYNTAX
- IOERR_CMD_SW_RESOURCE
- IOERR_UNIT_NOT_ALLOCATED
- IOERR_UNIT_NOT_READY
- IOERR_UNIT_PWR_OFF
For a detailed description of all the return codes, see Error Handling.
IOCC_ADAPTER_PASSTHRU
The IOCC_ADAPTER_PASSTHRU CommandCode consists of all the CommandModifiers responsible for issuing SCSI-formatted requests to a unit. The following table describes the CommandModifiers:
CommandModifier | Description |
---|---|
IOCM_EXECUTE_SCB | Issues an IBM Subsystem Control Block (SCB) request to the specified unit.
Support of this command is optional. |
IOCM_EXECUTE_CDB | Issues a SCSI Command Descriptor Block (CDB) request to the specified unit.
This command is mandatory for all SCSI units. |
Remarks
- Support: Mandatory for SCSI units
- (See CommmandModifiers for exceptions.)
- Called By: OS2DASD.DMD, other device manager, or filter device driver
- Context of Call: TASK, INTERRUPT
Format of IORB
- IORB Type
- IORB_ADAPTER_PASSTHRU
- IORBH Fields
- CommandCode
- --IOCC_ADAPTER_PASSTHRU
- -CommandModifiers
- --IOCM_EXECUTE_SCB
- --IOCM_EXECUTE_CDB
- -Valid RequestControlFlags
- --IORB_ASYNC_POST
- --IORB_REQ_STATUSBLOCK
- --IORB_DISABLE_RETRY
IORB_ADAPTER_PASSTHRU Description
This section defines the IORB_ADAPTER_PASSTHRU control block. (See the following table.)
Field Name | C-Type | Length | Description |
---|---|---|---|
iorbh | IORBH | DB(68) | IORB header |
cSGLIST | USHORT | DW | Number of elements |
pSGLIST | PSCATGATENTRY | DD | Far pointer to s/g list |
ppSGLIST | ULONG | DD | Physical address of s/g list |
ControllerCmdLen | USHORT | DW | Length |
pControllerCmd | PBYTE | DD | Controller command pointer |
ppSCB | ULONG | DD | Physical SCB pointer |
Flags | USHORT | DW | Flags |
On entry to the driver:
iorbh
See IORB General Format.
cSGList
contains the number of scatter/gather elements in the scatter/gather list ( pSGLIST), for IOCM_EXECUTE_CDB requests. For all other requests this field contains a 0. pSGLIST
contains a far pointer to the scatter/gather list, supplied by the caller, for IOCM_EXECUTE_CDB requests. For all other requests this field contains a 0. The scatter/gather list consists of an array of cSGList elements, each pointing to a physically contiguous area of real memory in a format defined by the SCATGATENTRY structure, shown in the following table.
Field Name | C-Type | Length | Description |
---|---|---|---|
ppXferBuf | ULONG | DD | Physical pointer to buffer |
XferBufLen | ULONG | DD | Length of buffer |
ppSGLIST
contains a 32-bit physical address of the scatter/gather list for IOCM_ EXECUTE_CDB requests. For all other requests, this field contains a 0.
ControllerCmdLen
contains the length, in bytes, of the command controller buffer.
pControllerCmd
contains a pointer to the controller command buffer in either SCB or CDB format, based on the CommandModifierfield.
ppSCB
contains a 32-bit physical address of the Subsystem Control Block (SCB) for IOCM_EXECUTE_SCB requests. For all other requests, this field contains a 0 .
Flags
contains flags to define the request, as shown in the following table.
Flag | Description |
---|---|
PT_DIRECTION_IN | Data transfer direction. This flag defines the direction of the data transfer for IOCM_EXECUTE_CDB requests. If set, the data transfer is from the target device to the host adapter. For all other requests, this flag is ignored. |
On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_ADAPTER_PASSTHRU request.
Return Codes
Following is a list of the IOCC_ADAPTER_PASSTHRU error codes:
- IOERR_CMD_NOT_SUPPORTED
- IOERR_CMD_SYNTAX
- IOERR_CMD_SGLIST_BAD
- IOERR_CMD_SW_RESOURCE
- IOERR_CMD_ABORTED
- IOERR_UNIT_NOT_ALLOCATED
- IOERR_UNIT_NOT_READY
- IOERR_UNIT_PWR_OFF
- IOERR_ADAPTER_HOSTBUSCHECK
- IOERR_ADAPTER_DEVICEBUSCHECK
- IOERR_ADAPTER_OVERRUN
- IOERR_ADAPTER_UNDERRUN
- IOERR_ADAPTER_DIAGFAIL
- IOERR_ADAPTER_TIMEOUT
- IOERR_ADAPTER_DEVICE_TIMEOUT
- IOERR_ADAPTER_REQ_NOT_SUPPORTED
- IOERR_ADAPTER_REFER_TO_STATUS
- IOERR_DEVICE_DEVICEBUSCHECK
- IOERR_DEVICE_REQ_NOT_SUPPORTED
- IOERR_DEVICE_DIAGFAIL
- IOERR_DEVICE_BUSY
- IOERR_DEVICE_OVERRUN
- IOERR_DEVICE_UNDERRUN
For a detailed description of all the return codes, see Error Handling.
Device Helpers (DevHlp)
In this specification, device helpers are a set of C or assembler callable routines that provide operating system services for OS/2 device drivers. These DevHlp services are #RegisterDeviceClass and #GetDOSVar.
RegisterDeviceClass
At initialization, the driver calls the RegisterDeviceClass DevHlp to register its direct call command handler entry point with the kernel.
Processing
LDS SI, ADD_Name ; DS:SI = Ptr device driver to ASCIIZ name ; maximum of 16 chars MOV AX,SEGMENT ADD_Function ; AX:BX = Ptr to driver's DirectCall LEA BX,ADD_Function ; Command Handler MOV DI,Device_Flags ; Must be 0 for adapter device drivers MOV CX,Device_Class ; Must be 1 for adapter device drivers MOV DL,DevHlp_RegisterADD CALL [Device_Help]
Results
'C' Cleared if successful AX = ADDHandle 'C' Set if error AX = ERROR_NOT_ENOUGH_MEMORY if CX out of range if table is full
GetDOSVar
The existing GetDOSVar DevHlp has been modified to return a pointer to the device class table for a specified device class. This pointer is valid at initialization, task, and interrupt times, and is used by the device managers or filter device drivers to obtain the adapter device driver entry points from the kernel.
Processing
MOV AL,DHGETDOSV_DEVICECLASSTABLE ; Device Class table index MOV CX,Device_Class ; Must be 1 for DISK adapter device drivers MOV DL,DevHlp_GetDOSVar CALL [Device_Help]
Results
'C' Cleared if successful AX:BX = global pointer to a table of registered adapter device driver entry points 'C' Set if error
Remarks
- Adapter Device Driver Entry Point Table format
Note: MAX DCTableEntries can be different for each device class, as follows:
Device_Class = 1 (disk) has a maximum of 32 entries
Device_Class = 2 (mouse) has a maximum of 3 entries
struct DevClassTableEntry { USHORT DCOffset; USHORT DCSelector; USHORT DCFlags; UCHAR DCName[16]; }; struct DevClassTableStruc { USHORT DCCount; USHORT DCMaxCount; struct DevClassTableEntry DCTableEntries[MAX]; };
Note: The location of the entry point for an adapter device driver can be derived from its adapter device driver handle, as follows:
{ USHORT i = ADDHandle - 1; AddSelector = pDevClassTable->DCTableEntries[i].DCSelector ; AddOffset = pDevClassTable->DCTableEntries[i].DCOffset ; };