┌──────────────┐
│ 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 UnitHandle field and its associated ADD's handle, defined
by either the FilterADDHandle or ADDHandle fields.
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.