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

From EDM2
Jump to: navigation, search
Storage Device Driver Reference
  1. About This Book
  2. Introduction to DASD, SCSI, and CD-ROM Programming Interfaces
  3. Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers
  4. Adapter Device Driver Development Considerations
  5. DASD, SCSI, and CD-ROM Device Manager Interface Specification
  6. Error Handling
  7. Adapter Device Driver Command-Line Parameters
  8. DASD IOCtl Device Driver Test Tool
  9. Optical IOCtl Device Driver Test Tool
  10. Using Filter Device Drivers
  11. Library and Services
  12. CD-ROM Device Manager Interface Specification
  13. CD-ROM Device Driver Test Tool
  14. Building an OS/2 Virtual Disk Driver
  15. OS2DASD.DMD - Technical Reference
  16. Boot Record Architecture
  17. Extended Device Driver Interface Specification
  18. I/O Request Block - C Definitions
  19. OS/2 SCSI Device Driver Interface Specification
  20. Advanced SCSI Programming Interface (ASPI) OS/2 Specification
  21. Adapter Device Driver Interface Questions and Answers
  22. Device Driver Test Tool (DDTT)
  23. Glossary

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.

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

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

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

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

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.

IOCM_GET_CHANGELINE_STATE US_CHANGELINE_ACTIVE
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 RequestControlFlags
    --IORB_ASYNC_POST
    --IORB_REQ_STATUSBLOCK
    --IORB_DISABLE_RETRY

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