DASD, SCSI, and CD-ROM Device Manager Interface Specification

The IBM OS/2 2.0 (and later) DASD and SCSI device manager interface consists of direct call commands and Device Helper (DevHlp) services.

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:

VOID (FAR * ADDEntryPoint) (piorb); PIORB  piorb;        /* Far pointer to the IORB control block */
 * C Language Syntax
 * 1) include 

; ** 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
 * Assembly Language Syntax
 * 1) include 

The results of the command are returned in the IORB.
 * Results

The following table categorizes and lists the direct call commands used for the DASD and SCSI device manager interface:

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 .) 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. 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. 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.

RequestControl contains flags which control the processing of the IORB, as shown in the following table.

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.) 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 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.
 * ** ES:BX = IORB Pointer

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

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 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

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: 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 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.

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.

AdapterIOAccess defines the adapter-to-host I/O data transfer capabilities, as shown in the following table.

AdapterHostBus defines the adapter-to-host bus type used, as shown in the following table.

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. 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 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.

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. 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.

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

IORB_UNIT_CONTROL Description

This section defines the IORB_UNIT_CONTROL control block. (See the table below.) 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: 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

IOCC_GEOMETRY Description

This section defines the IORB_GEOMETRY and GEOMETRY control blocks. (See the table below.)

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 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:
 * 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

IORB_EXECUTEIO Description

This section defines the IORB_EXECUTEIO control block. (See the following table.) 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.) 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.) 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. 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: For a detailed description of all the return codes, see Error Handling.
 * 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

IOCC_FORMAT
The IOCC_FORMAT CommandCode consists of all CommandModifiers responsible for unit format requests. The following table describes the IOCC_FORMAT CommandModifiers: 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.) 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.)

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.) 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. 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: 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.) 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.) 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. On entry to the driver:

Flags contains flags to define the request, as shown in the following table.

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. 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_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
 * IOERR_CMD_NOT_SUPPORTED
 * IOERR_CMD_SYNTAX
 * IOERR_CMD_SW_RESOURCE

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: 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_UNIT_STATUS -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 Type
 * IORBH Fields

IORB_UNIT_STATUS Description

This section defines the IORB_UNIT_STATUS control block.

IORB_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. 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:

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_DEVICE_CONTROL -CommandCode --IOCC_DEVICE_CONTROL -CommandModifiers --IOCM_ABORT --IOCM_RESET --IOCM_SUSPEND --IOCM_RESUME --IOCM_LOCK_MEDIA --IOCM_UNLOCK_MEDIA --IOCM_EJECT_MEDIA -Valid RequestControlFlags --IORB_ASYNC_POST --IORB_REQ_STATUSBLOCK --IORB_DISABLE_RETRY
 * IORB Type
 * IORBH Fields

IORB_DEVICE_CONTROL Description

This section defines the IORB_DEVICE_CONTROL control block. (See the following table.) 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.
 * 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: For a detailed description of all the return codes, see Error Handling.
 * IOERR_CMD_NOT_SUPPORTED
 * IOERR_CMD_SYNTAX
 * IOERR_CMD_SW_RESOURCE
 * IOERR_UNIT_NOT_ALLOCATED
 * IOERR_UNIT_NOT_READY
 * IOERR_UNIT_PWR_OFF

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: 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.) 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. 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.

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 and.

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   ; };