Jump to content

Storage Device Driver Reference: Difference between revisions

From EDM2
← Older edit
Ak120 (talk | contribs)
35,819 edits
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
By [[IBM]]
{{SDDRef}}
 
{{IBM-Reprint}}
'''Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'''
==About This Book==
 
== About This Book ==
The ''Storage Device Driver Reference'' provides a simplified programming interface to expedite the development of DASD, SCSI, and CD-ROM device driver support for the IBM OS/2 product.
The ''Storage Device Driver Reference'' provides a simplified programming interface to expedite the development of DASD, SCSI, and CD-ROM device driver support for the IBM OS/2 product.


Line 15: Line 13:


=== How This Book is Organized ===
=== How This Book is Organized ===
* [[#Notices]] contains trademark and service mark notices and information.
*[[#Notices|Notices]] contains trademark and service mark notices and information.
* [[Introduction to DASD, SCSI, and CD-ROM Programming Interfaces]] introduces the OS/2 DASD,SCSI, and CD-ROM programming interfaces for OEM device support, and describes what they are and what they are not. It shows the organization of the code, and presents various types of device drivers, device managers, adapter device drivers, and filter device drivers.
*[[Introduction to DASD, SCSI, and CD-ROM Programming Interfaces]] introduces the OS/2 DASD, SCSI, and CD-ROM programming interfaces for OEM device support, and describes what they are and what they are not. It shows the organization of the code, and presents various types of device drivers, device managers, adapter device drivers, and filter device drivers.
* [[Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers]] describes key design points and the strategies for addressing them. The BASEDEV keyword, introduced in OS/2 2.0, is described. This chapter describes system and adapter device driver installations along with the ''presence-check'' function.
*[[Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers]] describes key design points and the strategies for addressing them. The BASEDEV keyword, introduced in OS/2 2.0, is described. This chapter describes system and adapter device driver installations along with the ''presence-check'' function.
* [[Adapter Device Driver Development Considerations]] covers pertinent considerations when developing adapter device drivers, such as loading, initialization, and operation.
*[[Adapter Device Driver Development Considerations]] covers pertinent considerations when developing adapter device drivers, such as loading, initialization, and operation.
* [[DASD, SCSI, and CD-ROM Device Manager Interface Specification]] presents the Direct Call Commands used with the DASD, SCSI, and CD-ROM device manager interface specification and the available device helpers (DevHlps). It covers I/O request blocks (IORBs) and their configuration, along with detailed descriptions of command codes, command modifiers, control blocks, and data structures.
*[[DASD, SCSI, and CD-ROM Device Manager Interface Specification]] presents the Direct Call Commands used with the DASD, SCSI, and CD-ROM device manager interface specification and the available device helpers (DevHlps). It covers I/O request blocks (IORBs) and their configuration, along with detailed descriptions of command codes, command modifiers, control blocks, and data structures.
* [[Error Handling]] contains a summary of all the adapter device driver error codes and guidelines for their usage.
*[[Error Handling]] contains a summary of all the adapter device driver error codes and guidelines for their usage.
* [[Adapter Device Driver Command-Line Parameters]] presents the adapter device driver command-line parameters and structures, including syntax conventions and specific parameter information for the various bus interfaces.
*[[Adapter Device Driver Command-Line Parameters]] presents the adapter device driver command-line parameters and structures, including syntax conventions and specific parameter information for the various bus interfaces.
* [[DASD IOCtl Device Driver Test Tool]] discusses the DASD IOCtl Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of DASD drivers. These tests are implemented with the Device Driver Test Tool.
*[[DASD IOCtl Device Driver Test Tool]] discusses the DASD IOCtl Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of DASD drivers. These tests are implemented with the Device Driver Test Tool.
* [[Optical IOCtl Device Driver Test Tool]] discusses the optical IOCtl Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for optical device drivers. The tests are implemented with the Device Driver Test Tool.
*[[Optical IOCtl Device Driver Test Tool]] discusses the optical IOCtl Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for optical device drivers. The tests are implemented with the Device Driver Test Tool.
* [[Using Filter Device Drivers]] presents filter device drivers and the strategies for providing filter functions.
*[[Using Filter Device Drivers]] presents filter device drivers and the strategies for providing filter functions.
* [[Library and Services]] provides a complement of library services for common adapter device driver tasks.
*[[Library and Services]] provides a complement of library services for common adapter device driver tasks.
* [[CD-ROM Device Manager Interface Specification]] provides CD-ROM specific device driver support information.
*[[CD-ROM Device Manager Interface Specification]] provides CD-ROM specific device driver support information.
* [[CD-ROM Device Driver Test Tool]] discusses the Application Program Interfaces (APIs) defined for the interface of CD-ROM drivers.
*[[CD-ROM Device Driver Test Tool]] discusses the Application Program Interfaces (APIs) defined for the interface of CD-ROM drivers.
* [[Building an OS/2 Virtual Disk Driver]] describes how to program and build an OS/2 virtual disk driver.
*[[Building an OS/2 Virtual Disk Driver]] describes how to program and build an OS/2 virtual disk driver.
* [[OS2DASD.DMD - Technical Reference]] describes how the OS2DASD Manager provides support for fixed and removable magnetic disks.
*[[OS2DASD.DMD - Technical Reference]] describes how the OS2DASD Manager provides support for fixed and removable magnetic disks.
* [[Boot Record Architecture]] describes how to install, create, and delete block devices in the Extended DOS partition. This appendix also discuss BIOS Parameter Blocks and Get Device Parameters for Extended Volumes.
*[[Boot Record Architecture]] describes how to install, create, and delete block devices in the Extended DOS partition. This appendix also discuss BIOS Parameter Blocks and Get Device Parameters for Extended Volumes.
* [[Extended Device Driver Interface Specification]] describes the supports for servicing fixed disk devices.
*[[Extended Device Driver Interface Specification]] describes the supports for servicing fixed disk devices.
* [[I/O Request Block - C Definitions]]lists the I/O request block C language definitions for adapter device driver device support.
*[[I/O Request Block - C Definitions]]lists the I/O request block C language definitions for adapter device driver device support.
* [[OS/2 SCSI Device Driver Interface Specification]] describes the high-level interface for the SCSI device driver for OS/2. All functions are listed.
*[[OS/2 SCSI Device Driver Interface Specification]] describes the high-level interface for the SCSI device driver for OS/2. All functions are listed.
* [[Advanced SCSI Programming Interface (ASPI) OS/2 Specification]] describes the advanced SCSI programming interface (ASPI) OS/2 specification. The information was provided by Adaptec Corporation.
*[[Advanced SCSI Programming Interface (ASPI) OS/2 Specification]] describes the advanced SCSI programming interface (ASPI) OS/2 specification. The information was provided by Adaptec Corporation.
* '''Adapter Device Driver Interface Questions and Answers''' covers the most commonly asked questions about adapter device driver interfaces. The answers are presented in detail.
*[[Adapter Device Driver Interface Questions and Answers]] covers the most commonly asked questions about adapter device driver interfaces. The answers are presented in detail.
* '''Device Driver Test Tool (DDTT)''' describes how to use the Device Driver Test Tool in different environments.
*[[Device Driver Test Tool (DDTT)]] describes how to use the Device Driver Test Tool in different environments.


A glossary and an index appear at the back of the book.
A glossary and an index appear at the back of the book.
Line 51: Line 49:
:International Fax: 770-835-9444
:International Fax: 770-835-9444


== Introduction to DASD, SCSI, and CD-ROM Programming Interfaces ==
This reference defines the OS/2* 2.0 (and later) programming interfaces to support original equipment manufacturer (OEM) direct access storage devices (DASD), small computer system interface (SCSI) devices, and compact disc read only memory (CD-ROM) devices.
The programming interfaces described in this reference provide the following benefits:
*Device drivers can be written in the C programming language.
*The development of new DASD, SCSI, and CD-ROM support for unique device interfaces is expedited by reducing the amount of new code required and the complexity of that code.
*Facilitate development of a new DASD, SCSI, or CD-ROM driver for a specific bus interface.
*Relatively complex OS/2 kernel interfaces are replaced with a single interface.
*Independent development organizations are better able to reuse existing DASD device driver code.
*OS/2 2.0 (and later) is better equipped for installing, starting, and operating on a broad range of Intel** 80386SX-compatible workstations.
The following figure illustrates the organization of the new code:
[[Image:Storage-img0.gif]]
The following types of device drivers are included in this reference:
*Device managers
*Adapter device drivers
*Filter device drivers
A ''device manager (DM)'' is a hardware-independent module that services the standard OS/2 request packet interface. An ''adapter device driver'' is a hardware-dependent module and is a member of the lowest layer in the device-driver hierarchy. The adapter device driver to device manager interface is designed such that an adapter device driver is little more than a ''state machine'' responsible for moving blocks of I/O between system memory and a target device.
A ''filter device driver'' differs from an adapter device driver in that it normally does not manage hardware directly. See [[#Filter Device Drivers]] and [[#Using Filter Device Drivers]] for details about filter device drivers.
=== Device Managers ===
Device managers provide a uniform interface between their clients and adapter device drivers. Device manager clients normally are an OS/2 installable file system or the OS/2 kernel but can be other device drivers.
The interface between a device manager and the adapter device drivers managed is defined in this reference. The interface between device managers and the clients they service is defined by the client's interface specification.
IBM provides the devices managers shown in the following table:
{| class="wikitable"
!Device Manager
!Client
!Client Specification
|-
|[[OS2DASD.DMD]]
|OS/2 File Systems
|OS/2 Physical Device Driver Reference
|-
|[[OS2SCSI.DMD]]
|SCSI.SYS option drivers
|OS/2 SCSI Device Driver Specification
|-
|[[OS2ASPI.DMD]]
|ASPI option drivers
|Advanced SCSI Programming Interface
|-
|[[OS2CDROM.DMD]]
|CD-ROM File System
|OS/2 CD-ROM Interface
|}
=== Adapter Device Drivers ===
Adapter device drivers provide a uniform software interface to the hardware devices they manage. A device driver's external interface is defined in this reference.
Adapter device drivers for the following industry-standard interfaces are included in the OS/2 2.0 (and later) product:
{| class="wikitable"
!Device Driver
!Supported Devices 
|-
|[[IBM1S506.ADD]]||
|-
|[[IBM1FLPY.ADD]]||ISA removable media drives     
|-
||[[IBM2ADSK.ADD]]||ABIOS fixed drives
|-
||[[IBM2SCSI.ADD]]||ABIOS SCSI adapters
|-
||[[IBM2FLPY.ADD]]||ABIOS removable media drives 
|-
||[[IBMINT13.I13]]||INT 13H BIOS DASD devices
|}
Additional adapter device drivers for other OEM interfaces might be included in the OS/2 operating system.
=== Filter Device Drivers ===
Filter device drivers are a special class of device drivers that provide the following:
*Generic value-added services, such as data stripping or encryption
*Device-specific services, such as adjusting and altering the command stream between a device manager and an adapter device driver to support a particular type of device
The interfaces between device managers and filter device drivers are identical to the interfaces between device managers and ordinary adapter device drivers. Filter drivers differ from ordinary drivers in that they normally do not manage hardware directly; instead, they monitor the stream of commands between a device manager and regular adapter device drivers.
Filter device drivers to support the following devices are included in the OS/2 2.0 (and later) product:
{| class="wikitable"
!Filter
!Supported Devices 
|-
|[[HITCDS1.FLT]] ||
|-
|[[TOSHCDS1.FLT]] ||       
|-
|[[NECCDS1.FLT]] ||
|-
|[[SONYCDS1.FLT]] ||
|}
== Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers ==
The key design points of this OEM DASD, SCSI, and CD-ROM device support package include:
*The ability to install and, subsequently, start up from a DASD device that requires an OEM-specific adapter device driver interface
*An installation process that is transparent to the end-user (that is, it requires no interaction on the part of the end-user)
This chapter describes the strategy developed to address these design points and the responsibilities of a device driver supplier in order to participate in this strategy.
=== Using the BASEDEV Keyword ===
A ''base device driver'' performs I/O during the OS/2 kernel initial load sequence. There are a number of operational differences between base device drivers and installable device drivers. See [[Adapter Device Driver Development Considerations]] for a description of how this affects adapter device driver development.
The ''BASEDEV'' keyword new with the OS/2 2.0 operating system, loads a base device driver into the operating system. Its syntax is as follows:
<pre>
    BASEDEV= ---- filename ---------------------|
                            \-- arguments --/
</pre>
Unlike the DEVICE= statement, the BASEDEV= statement must not contain either drive or path information. The root directory of the startup partition is searched first for the specified file name, followed by the \OS2 directory of the startup partition. (In the startup sequence, the OS/2 operating system cannot process drive or path information at the point where BASEDEV= statements are processed. If drive or path information is included there, an error is generated.)
Also, unlike the DEVICE= statement, the file-name extension of the file being loaded has a special meaning. BASEDEV= statements are not necessarily processed in the order in which they appear in your CONFIG.SYS file. The extension of each BASEDEV= file name is examined; then, BASEDEV= statements are processed in the order indicated by the following figure.
<pre>
(BASEDEV= Load Ordering by File Extension)
.SYS (processed first)
.BID
.VSD        |
.TSD        |
.ADD        |
.I13
.FLT
.DMD  (processed last)
</pre>
Files with other file-name extensions are not loaded.
If several BASEDEV= statements load file names with the same extension, those files are loaded in the order in which they are encountered in the CONFIG.SYS file.
=== OS/2 System Installation ===
When the OS/2 operating system is first loaded from the installation diskettes, the following adapter device drivers and device managers are loaded:
{|class="wikitable"
!Adapter Device Driver||Supported Device Managers
|-
|OS2DASD.DMD||OS/2 DASD manager
|-
|OS2CDROM.DMD||OS/2 CD-ROM manager
|-
|IBM1FLPY.ADD||ISA removable media driver
|-
|IBM1S506.ADD||ISA ST-506 driver
|-
|IBM2FLPY.ADD||ABIOS removable media driver
|-
|IBM2ADSK.ADD||ABIOS DASD driver
|-
|IBM2SCSI.ADD||ABIOS SCB driver
|-
|IBMINT13.I13||Generic INT 13h driver
|}
Additional drivers supporting other OEM interfaces also can be present.
When each device driver initializes, it attempts to determine whether its target hardware adapter is present. If the hardware interface is recognized, the driver completes its initialization and, subsequently, is ready to manage I/O operations during OS/2 system installation. If the hardware interface is not recognized, the device driver will fail the initialization with the ''Quiet Fail'' flags set. ''Quiet failure'' prevents the generation of failure messages on the workstation display.
Hardware interfaces that are not recognized by any of the drivers on the OS /2 initialization diskette are driven by the generic INT 13h adapter device (IBMINT13.I13) during installation. The IBMINT13 driver determines whether the previously loaded adapter device drivers have claimed at least as many fixed disks as indicated by the BIOS fixed disk count (0:475). The IBMINT13 driver will attempt to manage the remaining fixed disks. Consequently, to install and initially load the OS/2 operating system from an OEM adapter, it is important for the OEM to ensure that the IBMINT13 adapter device driver works properly with the OEM's adapter BIOS.
The OS/2 operating system can be installed and loaded on drives with BIOS IDs hex 80 or higher, provided that the OEM BIOS supplies INT 13h support for these drives.
==== OEM Adapter Device Driver Installation ====
OEM adapter device drivers are installed within the framework of the OS/2 DDINSTAL utility. The driver developer is responsible for supplying two modules (in addition to the adapter device driver) used by DDINSTAL - an adapter ''presence-check function'' and a ''device driver profile''. DDINSTAL uses these modules to automatically detect the presence of OEM hardware interfaces and to install the corresponding drivers without user intervention.
==== Presence-Check Function ====
A ''presence-check function'' is a Ring 3 (nonprivileged) EXE program that determines whether a given hardware interface is present on a workstation. The module returns '''0''' when the specific interface is detected and '''1''' when the interface is not detected. For these modules to identify installed OEM adapters, Ring 0 services are provided by the device driver TESTCFG.SYS. TESTCFG provides the following IOCtl services for OEM adapter presence-check modules:
*Determines CPU host bus type
*Reads adapter ROM space
*Executes ''IN/OUT'' instruction
*Reads EISA adapter IDs
Refer to the ''OS/2 Physical Device Driver Reference'' for details on the TESTCFG device driver services.
'''Note:''' Be sure to write adapter presence-check modules to avoid disruption or conflicts with other installed host adapters.
==== Device Driver Profiles ====
A ''device driver profile'' is a file with a DDP extension containing a script that is interpreted by the OS/2 DDINSTAL utility. The device driver profile defines which files to copy from the installation diskettes to the target directories and specifies how the CONFIG.SYS file will be updated.
Refer to the ''Physical Device Driver Reference'' for specification of the DDINSTAL utility and the device driver profile language.
The DDINSTAL utility has been extended to support execution of the presence-check function and to conditionally process the DDP file, based on the return code from the presence check. To enable this support, the DDINSTAL utility now interprets the PRESENCECHECK keyword.
To use this new DDINSTAL feature, create a DDP file for the installation of your adapter driver, using the existing TITLE, CONFIG, and FILES keywords. Then, add a line to the DDP of the form:
:PRESENCECHECK
<filename>
where <filename> is the name of the presence-check function.
When the DDP is interpreted by DDINSTAL, that utility first scans the DDP for the PRESENCECHECK keyword. If the keyword is found, the corresponding EXE module is executed. Then, the entire DDP file is either processed or ignored, based on the outcome of the presence-check function.
A device driver profile for a hypothetical OEM-323x SCSI adapter could look like the following example. The file name would be OEM323x.DDP and the contents would be as follows:
<pre>
*******************************************************************
*                                                                *
* This is a device driver profile for a SCSI adapter.            *
* DDINSTAL would use this profile to automatically install the    *
* target device support.  The complete profile is processed only  *
* when the OEM323x.EXE program returns 0, indicating that the    *
* OEM-323x adapter is actually installed in the workstation.      *
*                                                                *
*******************************************************************
:PRESENCECHECK        * Check for the presence of an OEM-323x.
OEM323x.EXE          * This might query POS IDs using TESTCFG.
  ***********************************************************
  * The remainder of this file is processed only if        *
  * OEM323x.EXE indicates detection of the OEM-323x adapter.*
  ***********************************************************
:TITLE
Device driver profile for the OemTec OEM-323x OS/2 2.0 Adapter Device
Driver
:CONFIG              * Add this line to CONFIG.SYS
BASEDEV=OEM323x.ADD
:FILES
OEM323x.ADD \OS2\OEM323x.ADD
                      * Move this file from the installation
                      * diskette to the \OS2 directory on the
                      * target partition.
</pre>
==== Processing Presence-Check Functions and DDP Files ====
OEM adapter device drivers that are packaged in the OS/2 product are installed near the end of the OS/2 system installation. At this point in the installation process, the DDP files for each OEM adapter device driver are evaluated by the DDINSTAL interpreter. This processing is completely automatic and transparent to the end user.
Use the same DDINSTAL framework for adapter device drivers that you distribute directly. Include the driver file, presence-check function, and DDP file on a reference diskette for the OEM adapter. The end user can install the adapter device support from the reference diskette, after the OS/2 operating system is loaded, by selecting ''Device Driver Install'' from the OS/2 System Setup folder. The installation of the device support will proceed automatically.
== Adapter Device Driver Development Considerations ==
Adapter device drivers are packaged as 16-bit OS/2 device drivers. This chapter describes how adapter device drivers differ from installable OS/2 device drivers.
=== Loading and Initialization ===
Adapter device drivers are loaded using the BASEDEV= statement in CONFIG.SYS. The processing of these statements occurs before the operating system is fully initialized. The adapter device driver writer must be aware of the following differences between installable device drivers and adapter device drivers:
*'''Adapter device drivers initialize at Ring 0 rather than Ring 3.'''<br />Generally, this does not cause any problems. However, adapter device drivers cannot use the DOS''xxx'' APIs available to installable device drivers during initialization. To display a message, an adapter device driver must use the DevHlp_Save_Message service.
*'''INIT request packet command code'''<br />The INIT request packet command code for all base device drivers (which include all adapter device drivers) is hex 1B rather than hex 0.
*'''Device Driver Header'''<br />An adapter device driver must identify itself as a participant in the adapter device driver strategy by setting the following bits to '''1''' in the device driver header. The bit-numbering convention is that bit 15 is the most significant bit in a WORD, and bit 31 is the most significant bit in a DWORD.
**Device attribute field - Bits 15, 8, 7<br />Bit 15 indicates CHARACTER device driver. Bits 8 and 7 define ''driver'' as a Level 3 device driver, which indicates usage of the ''DWORD capabilities bit strip'' in the header file.
**Capabilities Bit Strip - Bit 3<br />Bit 3 indicates that the driver is participating in the adapter device driver strategy which, in turn, selects an alternate INIT request packet format from the kernel.
*'''INIT request packet format'''<br />The INIT request packet for a driver that has identified itself as an adapter device driver (through bits set in the device driver header as just described) corresponds to the RPINITIN structure defined in REQPKT.H, supplied with the ''IBM Developer Connection Device Driver Kit for OS/2''. The ''InitArgs'' member of the RPINITIN structure points to the following structure , defined in DSKINIT.H in the kit.
<code>
typedef struct _DDD_PARM_List {    /* DDPL                        */
  USHORT    reserved1;              /* Reserved                    */
  USHORT    disk_config_table;      /* Address of config table      */
  USHORT    reserved2;              /* Reserved                    */
  USHORT    cmd_line_args;          /* Address of command line parm */
  USHORT    machine_config_table;  /* Address of config info      */
} DDD_Parm_List, FAR *PDD_Parm_List;
</code>
By following the appropriate pointers in the DDD_Parm_List, the driver writer can obtain BASEDEV= command-line parameters, as well as information collected during system initialization.
*'''Adapter device drivers process a limited set of OS/2 kernel request packets.'''<br />With the exception of the OS/2 system kernel initialization request packet just described and vendor-defined IOCtls, adapter device drivers must reject all other kernel request packets. The primary interface to adapter device drivers is defined in this reference.
*'''Adapter device drivers register their entry points using the DevHlp service.'''<br />Adapter device drivers register their main entry points with the the OS/2 kernel using the DevHlp_RegisterDeviceClass service. See [[DASD, SCSI, and CD-ROM Device Manager Interface Specification]] for details. The table of registered entry points is available to other adapter device drivers and device managers that can call an adapter device driver directly.
*'''Adapter device drivers must declare a valid character device name in their headers'''.<br />The OS/2 kernel treats the name in the adapter device driver header as a valid character device name. Adapter device drivers must end their device names with a dollar sign ($) to avoid conflict with valid file names.
*'''Adapter device drivers must fail''' '''''quietly''''' '''when hardware is not found'''.<br />Adapter device drivers should check for the presence of their hardware interface at initialization time. If it is not found, the adapter device driver must set the ERROR_I24_QUIET_INIT_FAIL flags (as defined in BSEERR.H) in the ''Status'' field of the request packet.
=== Operation ===
Adapter device drivers receive commands through an I/O request block (IORB) entry point. The format of IORB commands received by an adapter device driver is defined in this reference.
Adapter device drivers have full use of both the 16-bit and 32-bit DevHlp services defined in OS/2 operating system. Although the adapter device driver to DM interface is 16-bit, adapter device drivers can manipulate 32-bit objects with assembly subroutines.
The service request entry point of an adapter device driver can be called in either kernel (also known as ''task'') or interrupt contexts. Consequently, ''an adapter device driver must never block while servicing a request after it has completed initialization''. (An adapter device driver ''can'' block at initialization.)
Service requests that involve time delays normally are initiated by the adapter device driver; then, the adapter device driver immediately returns to its caller. Service request completion is indicated to the caller using asynchronous callback notification.
=== Command-Line Parameters ===
To facilitate the parsing of command-line parameters, and to help encourage uniformity in command-line syntax, a ''parser/tokenizer'' is provided in the ''IBM Developer Connection Device Driver Kit for OS/2''. In addition, a command-line syntax definition is provided in [[Adapter Device Driver Command-Line Parameters]].
The output of the parser/tokenizer is a stream of tokens that represents the contents of the command line. The parser/tokenizer performs preliminary syntactical checks on the command line and indicates the results of these checks by the return code. However, the adapter device driver must ensure that the tokenized parameters' values are acceptable. The adapter device driver is responsible for displaying error messages as appropriate.
OEMs can modify the parser and included tables to add their own adapter-unique flags and parameters.
== 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:
;C Language Syntax
<pre>
#include <iorb.h>
VOID (FAR * ADDEntryPoint) (piorb);
PIORB  piorb;        /* Far pointer to the IORB control block */
</pre>
;Assembly Language Syntax
<pre>
#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
</pre>
;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:
{|class="wikitable"
!Command Type !!Commands
|-
|CONFIGURATION ||GET_DEVICE_TABLE<br />COMPLETE_INIT
|-
|UNIT_CONTROL ||ALLOCATE_UNIT<br />DEALLOCATE_UNIT<br />CHANGE_UNITINFO
|-
|GEOMETRY||GET_MEDIA_GEOMETRY<br />SET_MEDIA_GEOMETRY<br />GET_DEVICE_GEOMETRY<br />SET_LOGICAL_GEOMETRY
|-
|EXECUTE_IO||READ<br />READ_VERIFY<br />READ_PREFETCH<br />WRITE<br />WRITE_VERIFY
|-
|FORMAT||FORMAT_MEDIA<br />FORMAT_TRACK<br />FORMAT_PROGRESS
|-
|UNIT_STATUS||GET_UNIT_STATUS<br />CHANGELINE_STATE<br />GET_MEDIA_SENSE<br />GET_LOCK_STATUS
|-
|DEVICE_CONTROL||ABORT<br />RESET<br />SUSPEND<br />RESUME<br />LOCK_MEDIA<br />UNLOCK_MEDIA<br />EJECT_MEDIA
|-
|ADAPTER_PASSTHRU||EXECUTE_SCB<br />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.
{|class="wikitable"
!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.
{|class="wikitable"
!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.
{| class="wikitable"
!CommandCode!!CommandModifier
|-
|IOCC_CONFIGURATION||IOCM_GET_DEVICE_TABLE<br />IOCM_COMPLETE_INIT
|-
|IOCC_UNIT_CONTROL||IOCM_ALLOCATE_UNIT<br />IOCM_DEALLOCATE_UNIT<br />IOCM_CHANGE_UNITINFO
|-
|IOCC_GEOMETRY||IOCM_GET_MEDIA_GEOMETRY<br />IOCM_SET_MEDIA_GEOMETRY<br />IOCM_GET_DEVICE_GEOMETRY<br />IOCM_SET_LOGICAL_GEOMETRY
|-
|IOCC_EXECUTE_IO||IOCM_READ<br />IOCM_READ_VERIFY<br />IOCM_READ_PREFETCH<br />IOCM_WRITE<br />IOCM_WRITE_VERIFY
|-
|IOCC_FORMAT||IOCM_FORMAT_MEDIA<br />IOCM_FORMAT_TRACK<br />IOCM_FORMAT_PROGRESS
|-
|IOCC_UNIT_STATUS||IOCM_GET_UNIT_STATUS<br />IOCM_GET_CHANGELINE_STATE<br />IOCM_GET_MEDIA_SENSE<br />IOCM_GET_LOCK_SENSE
|-
|IOCC_DEVICE_CONTROL||IOCM_ABORT<br />IOCM_RESET<br />IOCM_SUSPEND<br />IOCM_RESUME<br />IOCM_LOCK_MEDIA<br />IOCM_UNLOCK_MEDIA<br />IOCM_EJECT_MEDIA
|-
|IOCC_ADAPTER_PASSTHRU||IOCM_EXECUTE_SCB<br />IOCM_EXECUTE_CDB
|}
'''RequestControl'''<br />contains flags which control the processing of the IORB, as shown in the following table.
{|class="wikitable"
!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'''<br />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.)
{|class="wikitable"
!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'''<br />equals 0, on entry. On exit from the driver, it contains the command's completion error code. This field is valid only if the IORB_ERROR flag in the ''Status''field is set. The error codes are summarized in [[Error Handling]].
'''Timeout'''<br />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'''<br />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'''<br />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'''<br />is reserved for use by the device manager and must not be modified by the adapter device driver.
'''pNxtIORB'''<br />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'''<br />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'''''
<pre class="western">
(FAR *piorb->NotifyAddress) (piorb);
</pre>
'''''Assembly Language Syntax'''''
<pre>
; ** 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
</pre>
'''Note:''' The ''Notify'' routine will preserve only the DS, ES, SI, and DI registers.
'''DMWorkSpace[20]'''<br />defines a workspace, for use by the device manager, that must not be modified by the device driver.
'''ADDWorkSpace[16]'''<br />defines a workspace for the adapter device driver that is ignored by the device manager.
'''''Command-Specific Data'''''<br />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 <br />Called By: OS2DASD.DMD, other device manager, or filter device driver <br />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<br />
ADAPTERINFO Adapter characteristics<br />
UNITINFO Unit characteristics
==== DEVICETABLE Structure Overview ====
<pre>
┌──────────────┐
│ 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 │
          └─────────────────┘                  └────────┘
</pre>
'''IORB_CONFIGURATION'''
{| class="wikitable"
!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'''<br />See [[IORB General Format]].
'''pDeviceTable'''<br />contains a far pointer to a block of storage (length = ''DeviceTableLen''), allocated by the caller, for the driver to return the DEVICETABLE.
'''DeviceTableLen'''<br />contains the length of the block of storage, in bytes, for the driver to return the DEVICETABLE (''pDeviceTable'').
'''DEVICETABLE'''
{|class="wikitable"
!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'''<br />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:
{|class="wikitable"
!Field Name
!Value
|-
|ADD_Level_Major
|ADD_LEVEL_MAJOR
|-
|ADD_Level_Minor
|ADD_LEVEL_MINOR
|}
'''ADDHandle'''<br />contains the adapter device driver's index returned by the ''RegisterDeviceClass'' DevHlp.
'''TotalAdapters'''<br />defines the number of adapters the device driver supports.
'''pAdapter[N]'''<br />contains an array of near ADAPTERINFO pointers. The number of elements in the array is determined by the ''TotalAdapters'' field.
'''AdapterInfo'''
{|class="wikitable"
!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]'''<br />contains the ASCIIZ name string of the adapter. This name is used by the caller for diagnostic purposes.
'''Reserved'''<br />contains a 0. This is a 16-bit alignment byte.
'''AdapterUnits'''<br />contains the number of units supported by this adapter.
'''AdapterDevBus'''<br />defines the adapter-to-device bus protocol used, as shown in the following table.
{|class="wikitable"
!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.
{|class="wikitable"
!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'''<br />defines the adapter-to-host I/O data transfer capabilities, as shown in the following table.
{|class="wikitable"
!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'''<br />defines the adapter-to-host bus type used, as shown in the following table.
{|class="wikitable"
!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.
|}
{|class="wikitable"
!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'''<br />contains the target ID for the SCSI adapter. For non-SCSI devices, this field should be set to 0.
'''AdapterSCSILUN'''<br />contains the logical unit number for the SCSI adapter. For non-SCSI devices, this field should be set to 0.
'''AdapterFlags'''<br />defines the adapter's characteristics, as shown in the following table.
{|class="wikitable"
!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'''<br />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'''<br />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]'''<br />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'''
{|class="wikitable"
!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'''<br />contains the unit's corresponding adapter's index in the ''pAdapter[N]''array.
'''UnitIndex'''<br />contains the unit's index in the ''UnitInfo[N]''array.
'''UnitFlags'''<br />defines the unit's characteristics, as shown in the following table.
{|class="wikitable"
!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'''<br />is reserved for future growth. Must be set to 0 by the adapter device driver.
'''UnitHandle'''<br />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'''<br />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'''<br />defines the unit's device type. Unit types and their supported devices are shown in the following table.
{|class="wikitable"
!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'''<br />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'''<br />contains the target ID for SCSI devices. For all other devices, this field equals 0.
'''UnitSCSILUN'''<br />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''.
{|class="wikitable"
!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 ''RequestControl''Flags
***IORB_ASYNC_POST
'''IORB_UNIT_CONTROL Description'''
This section defines the IORB_UNIT_CONTROL control block. (See the table below.)
{|class="wikitable"
!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:
{|class="wikitable"
!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.) <br />Called By: OS2DASD.DMD, other device manager, or filter device driver <br />Context of Call:TASK, INTERRUPT
'''Format of IORB'''
*IORB Type <br />-IORB_GEOMETRY <br />*IORBH Fields <br />-''CommandCode''<br />--IOCC_GEOMETRY <br />-''CommandModifiers''<br />--IOCM_GET_MEDIA_GEOMETRY <br />--IOCM_SET_MEDIA_GEOMETRY <br />--IOCM_GET_DEVICE_GEOMETRY <br />--IOCM_SET_LOGICAL_GEOMETRY <br />-Valid ''RequestControl''Flags <br />--IORB_ASYNC_POST <br />--IORB_REQ_STATUSBLOCK <br />--IORB_DISABLE_RETRY
'''IOCC_GEOMETRY Description'''
This section defines the IORB_GEOMETRY and GEOMETRY control blocks. (See the table below.)
{|class="wikitable"
!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'''<br />See [[IORB General Format]].
'''pGeometry'''<br />contains a far pointer to the block of storage (length = ''GeometryLen'') allocated by the caller for the GEOMETRY.
'''GeometryLen'''<br />contains the size of the block of storage, in bytes, for the GEOMETRY structure (''pGeometry'').
'''GEOMETRY Description'''
{|class="wikitable"
!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'''<br />contains the total number of sectors.
'''BytesPerSector'''<br />contains the number of bytes per sector. The IBM OS/2 2.0 File System supports only a value of 512.
'''Reserved'''<br />contains a 0. This alignment field ensures that the GEOMETRY structure aligns with SCSI Read Capacity output.
'''NumHeads'''<br />contains the number of heads.
'''TotalCylinders'''<br />contains the number of cylinders.
'''SectorsPerTrack'''<br />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 <br />IOERR_CMD_SYNTAX <br />IOERR_CMD_SW_RESOURCE <br />IOERR_UNIT_NOT_ALLOCATED <br />IOERR_UNIT_NOT_READY <br />IOERR_UNIT_PWR_OFF <br />IOERR_MEDIA_NOT_FORMATTED <br />IOERR_MEDIA_NOT_SUPPORTED <br />IOERR_MEDIA_CHANGED <br />IOERR_MEDIA_NOT_PRESENT <br />IOERR_ADAPTER_HOSTBUSCHECK <br />IOERR_ADAPTER_DEVICEBUSCHECK <br />IOERR_ADAPTER_OVERRUN <br />IOERR_ADAPTER_UNDERRUN <br />IOERR_ADAPTER_DIAGFAIL <br />IOERR_ADAPTER_TIMEOUT <br />IOERR_ADAPTER_DEVICE_TIMEOUT <br />IOERR_ADAPTER_REQ_NOT_SUPPORTED <br />IOERR_ADAPTER_REFER_TO_STATUS <br />IOERR_DEVICE_DEVICEBUSCHECK <br />IOERR_DEVICE_REQ_NOT_SUPPORTED <br />IOERR_DEVICE_DIAGFAIL <br />IOERR_DEVICE_BUSY <br />IOERR_DEVICE_OVERRUN <br />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'':
{|class="wikitable"
!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||Writes data from the scatter/gather list buffers to the unit's specified I/O address, then verifies that the data can be read (Write/Read Verify combination).                      |
|}
;Remarks
:Support: Mandatory
:Called By: [[OS2DASD.DMD]], other device manager, or filter device driver
:Context of Call: TASK, INTERRUPT
;Format of IORB
*IORB Type <br />-IORB_EXECUTEIO
*IORBH Fields <br />-''CommandCode''<br />--IOCC_EXECUTE_IO <br />-''CommandModifiers''<br />--IOCM_READ <br />--IOCM_READ_VERIFY <br />--IOCM_READ_PREFETCH <br />--IOCM_WRITE <br />--IOCM_WRITE_VERIFY <br />-Valid ''RequestControl''Flags <br />--IORB_ASYNC_POST <br />--IORB_CHAIN <br />--IORB_CHS_ADDRESSING <br />(Diskette only, see AF_CHS_ADDRESSING) <br />--IORB_REQ_STATUSBLOCK <br />--IORB_DISABLE_RETRY
'''IORB_EXECUTEIO Description'''
This section defines the IORB_EXECUTEIO control block. (See the following table.)
{|class="wikitable"
!|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'''<br />See [[IORB General Format]].
'''cSGList'''<br />contains the number of scatter/gather elements in the scatter/gather list ( ''pSGLIST'').
'''pSGLIST'''<br />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.)
{|class="wikitable"
!Field Name||C Type||Length||Description
|-
|ppXferBuf||ULONG||DD||Physical pointer to buffer
|-
|XferBufLen||ULONG||DD||Length of buffer
|}
'''ppSGLIST'''<br />contains a 32-bit physical address of the scatter/gather list.
'''RBA'''<br />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.)
{|class="wikitable"
|Field Name||C Type||Length||Description
|-
|Cylinder||USHORT||DW||Starting cylinder
|-
|Head||UCHAR||DB||Starting head
|-
|Sector||UCHAR||DB||Starting sector
|}
'''BlockCount'''<br />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'''<br />equals 0 on entry. On exit from the driver ''BlocksXferred'' contains the number of sectors successfully transferred.
'''BlockSize'''<br />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'''<br />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 <br />IOERR_CMD_SYNTAX <br />IOERR_CMD_SGLIST_BAD <br />IOERR_CMD_SW_RESOURCE <br />IOERR_CMD_ABORTED <br />IOERR_UNIT_NOT_ALLOCATED <br />IOERR_UNIT_NOT_READY <br />IOERR_UNIT_PWR_OFF <br />IOERR_RBA_ADDRESSING_ERROR <br />IOERR_RBA_LIMIT <br />IOERR_RBA_CRC_ERROR <br />IOERR_MEDIA_NOT_FORMATTED <br />IOERR_MEDIA_NOT_SUPPORTED <br />IOERR_MEDIA_WRITE_PROTECT <br />IOERR_MEDIA_CHANGED <br />IOERR_MEDIA_NOT_PRESENT <br />IOERR_ADAPTER_HOSTBUSCHECK <br />IOERR_ADAPTER_DEVICEBUSCHECK <br />IOERR_ADAPTER_OVERRUN <br />IOERR_ADAPTER_UNDERRUN <br />IOERR_ADAPTER_DIAGFAIL <br />IOERR_ADAPTER_TIMEOUT <br />IOERR_ADAPTER_DEVICE_TIMEOUT <br />IOERR_ADAPTER_REQ_NOT_SUPPORTED <br />IOERR_ADAPTER_REFER_TO_STATUS <br />IOERR_DEVICE_DEVICEBUSCHECK <br />IOERR_DEVICE_REQ_NOT_SUPPORTED <br />IOERR_DEVICE_DIAGFAIL <br />IOERR_DEVICE_BUSY <br />IOERR_DEVICE_OVERRUN <br />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''. <br />Called By: OS2DASD.DMD, other device manager, or filter device driver <br />Context of Call: TASK, INTERRUPT
'''Format of IORB'''
*IORB Type <br />-IORB_FORMAT <br />*IORBH Fields <br />-''RequestControl'': Flags can be enabled or disabled. <br />-''CommandCode''<br />--IOCC_FORMAT <br />-''CommandModifiers''<br />--IOCM_FORMAT_MEDIA <br />--IOCM_FORMAT_TRACK <br />--IOCM_FORMAT_PROGRESS <br />-Valid ''RequestControl''Flags <br />--IORB_ASYNC_POST <br />--IORB_CHS_ADDRESSING <br />(Diskette only, see AF_CHS_ADDRESSING) <br />--IORB_REQ_STATUSBLOCK <br />--IORB_DISABLE_RETRY
'''IORB_FORMAT Description:'''
This section defines the IORB_FORMAT control block. (See the following table.)
{|class="wikitable"
!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'''<br />See [[IORB General Format]].
'''cSGList'''<br />contains the number of scatter/gather elements in the scatter/gather list ( ''pSGLIST'').
'''pSGLIST'''<br />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.)
<pre>
|Field Name      |C Type          |Length  |Description      |
|-----------------+-----------------+---------+-----------------|
|ppXferBuf        |ULONG            |DD      |Physical pointer |
|                |                |        |to buffer        |
|-----------------+-----------------+---------+-----------------|
|XferBufLen      |ULONG            |DD      |Length of buffer |
</pre>
'''ppSGLIST'''<br />contains a 32-bit physical address of the scatter/gather list.
'''RBA'''<br />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.)
<pre>
|Field Name      |C Type          |Length  |Description      |
|-----------------+-----------------+---------+-----------------|
|Cylinder        |USHORT          |DW      |Starting cylinder|
|-----------------+-----------------+---------+-----------------|
|Head            |UCHAR            |DB      |Starting head    |
|-----------------+-----------------+---------+-----------------|
|Sector          |UCHAR            |DB      |Starting sector  |
</pre>
'''BlockCount'''<br />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'''<br />equals 0 on entry. On exit from the driver ''BlocksXferred'' contains the number of sectors successfully transferred.
'''BlockSize'''<br />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'''<br />defines Execute I/O cache control flags, as shown in the table below.
<pre>
|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.    |
</pre>
'''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 <br />IOERR_CMD_SYNTAX <br />IOERR_CMD_SGLIST_BAD <br />IOERR_CMD_SW_RESOURCE <br />IOERR_CMD_ABORTED <br />IOERR_UNIT_NOT_ALLOCATED <br />IOERR_UNIT_NOT_READY <br />IOERR_UNIT_PWR_OFF <br />IOERR_RBA_ADDRESSING_ERROR <br />IOERR_RBA_LIMIT <br />IOERR_RBA_CRC_ERROR <br />IOERR_MEDIA_NOT_FORMATTED <br />IOERR_MEDIA_NOT_SUPPORTED <br />IOERR_MEDIA_WRITE_PROTECT <br />IOERR_MEDIA_CHANGED <br />IOERR_MEDIA_NOT_PRESENT <br />IOERR_ADAPTER_HOSTBUSCHECK <br />IOERR_ADAPTER_DEVICEBUSCHECK <br />IOERR_ADAPTER_OVERRUN <br />IOERR_ADAPTER_UNDERRUN <br />IOERR_ADAPTER_DIAGFAIL <br />IOERR_ADAPTER_TIMEOUT <br />IOERR_ADAPTER_DEVICE_TIMEOUT <br />IOERR_ADAPTER_REQ_NOT_SUPPORTED <br />IOERR_ADAPTER_REFER_TO_STATUS <br />IOERR_DEVICE_DEVICEBUSCHECK <br />IOERR_DEVICE_REQ_NOT_SUPPORTED <br />IOERR_DEVICE_DIAGFAIL <br />IOERR_DEVICE_BUSY <br />IOERR_DEVICE_OVERRUN <br />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'':
<pre>
|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.                              |
</pre>
'''Remarks'''
Support: See ''CommandModifiers''. <br />Called By: OS2DASD.DMD, other device manager, or filter device driver <br />Context of Call: TASK, INTERRUPT
'''Format of IORB'''
*IORB Type <br />-IORB_FORMAT <br />*IORBH Fields <br />-''RequestControl'': Flags can be enabled or disabled. <br />-''CommandCode''<br />--IOCC_FORMAT <br />-''CommandModifiers''<br />--IOCM_FORMAT_MEDIA <br />--IOCM_FORMAT_TRACK <br />--IOCM_FORMAT_PROGRESS <br />-Valid ''RequestControl''Flags <br />--IORB_ASYNC_POST <br />--IORB_CHS_ADDRESSING <br />(Diskette only, see AF_CHS_ADDRESSING) <br />--IORB_REQ_STATUSBLOCK <br />--IORB_DISABLE_RETRY
'''IORB_FORMAT Description:'''
This section defines the IORB_FORMAT control block. (See the following table.)
<pre>
|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.        |
</pre>
On entry to the driver:
'''iorbh'''<br />See [[IORB General Format]].
'''cSGList'''<br />contains the number of scatter/gather elements in the scatter/gather list ( ''pSGLIST'').
'''pSGLIST'''<br />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.)
<pre>
|Field Name      |C Type          |Length  |Description      |
|-----------------+-----------------+---------+-----------------|
|ppXferBuf        |ULONG            |DD      |Physical pointer |
|                |                |        |to buffer        |
|-----------------+-----------------+---------+-----------------|
|XferBufLen      |ULONG            |DD      |Length of buffer |
</pre>
'''ppSGLIST'''<br />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'''<br />contains the length of the format command (''pFormatCmd''), in bytes.
'''pFormatCmd'''<br />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.
<pre>
|Field Name      |C Type          |Length  |Description      |
|-----------------+-----------------+---------+-----------------|
|Flags            |USHORT          |DW      |Flags            |
|-----------------+-----------------+---------+-----------------|
|RBA              |ULONG            |DD      |Starting RBA    |
|-----------------+-----------------+---------+-----------------|
|cTrackEntries    |USHORT          |DW      |Number of track  |
|                |                |        |entries          |
</pre>
On entry to the driver:
'''Flags'''<br />contains flags to define the request, as shown in the following table.
<pre>
|Flag          |Description                                  |
|---------------+---------------------------------------------|
|FF_VERIFY      |Verify after format.  If set, this flag      |
|              |indicates that the driver should verify the  |
|              |sectors after formatting.                    |
</pre>
'''RBA'''<br />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.
<pre>
|Field Name      |C Type          |Length  |Description      |
|-----------------+-----------------+---------+-----------------|
|Cylinder        |USHORT          |DW      |Starting cylinder|
|-----------------+-----------------+---------+-----------------|
|Head            |UCHAR            |DB      |Starting head    |
|-----------------+-----------------+---------+-----------------|
|Sector          |UCHAR            |DB      |Starting sector  |
</pre>
'''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 <br />IOERR_CMD_SYNTAX <br />IOERR_CMD_SW_RESOURCE <br />IOERR_CMD_ABORTED <br />IOERR_UNIT_NOT_ALLOCATED <br />IOERR_UNIT_NOT_READY <br />IOERR_UNIT_PWR_OFF <br />IOERR_RBA_ADDRESSING_ERROR <br />IOERR_RBA_LIMIT <br />IOERR_RBA_CRC_ERROR <br />IOERR_MEDIA_NOT_SUPPORTED <br />IOERR_MEDIA_WRITE_PROTECT <br />IOERR_MEDIA_CHANGED <br />IOERR_MEDIA_NOT_PRESENT <br />IOERR_ADAPTER_HOSTBUSCHECK <br />IOERR_ADAPTER_DEVICEBUSCHECK <br />IOERR_ADAPTER_OVERRUN <br />IOERR_ADAPTER_UNDERRUN <br />IOERR_ADAPTER_DIAGFAIL <br />IOERR_ADAPTER_TIMEOUT <br />IOERR_ADAPTER_DEVICE_TIMEOUT <br />IOERR_ADAPTER_REQ_NOT_SUPPORTED <br />IOERR_ADAPTER_REFER_TO_STATUS <br />IOERR_DEVICE_DEVICEBUSCHECK <br />IOERR_DEVICE_REQ_NOT_SUPPORTED <br />IOERR_DEVICE_DIAGFAIL <br />IOERR_DEVICE_BUSY <br />IOERR_DEVICE_OVERRUN <br />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'':
<pre>
|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.            |
</pre>
'''Remarks'''
Support: Mandatory (See ''CommmandModifiers'' for exceptions.) <br />Called By: OS2DASD.DMD, other device manager, or filter device driver <br />Context of Call: TASK, INTERRUPT
'''Format of IORB'''
*IORB Type <br />-IORB_UNIT_STATUS <br />*IORBH Fields <br />-''CommandCode''<br />--IOCC_UNIT_STATUS <br />-''CommandModifiers''<br />--IOCM_GET_UNIT_STATUS <br />--IOCM_GET_CHANGELINE_STATE <br />--IOCM_GET_MEDIA_SENSE <br />--IOCM_GET_LOCK_STATUS <br />-Valid ''RequestControl''Flags <br />--IORB_ASYNC_POST <br />--IORB_REQ_STATUSBLOCK
'''IORB_UNIT_STATUS Description'''
This section defines the IORB_UNIT_STATUS control block.
'''IORB_UNIT_STATUS'''
<pre>
|Field Name      |C-Type          |Length  |Description      |
|-----------------+-----------------+---------+-----------------|
|iorbh            |IORBH            |DB(68)  |IORB header      |
|-----------------+-----------------+---------+-----------------|
|UnitStatus      |USHORT          |DW      |Unit status      |
</pre>
On entry to the driver:
'''iorbh'''<br />See [[IORB General Format]].
'''UnitStatus'''<br />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.
<pre>
|CommandModifier              |Description                  |
|------------------------------+------------------------------|
|IOCM_GET_UNIT_STATUS          |                              |
|US_READY                      |Unit in Ready state          |
|US_POWER                      |Unit Powered On              |
|US_DEFECTIVE                  |Unit Defective                |
|------------------------------+------------------------------|
|IOCM_GET_CHANGELINE_STATE    |                              |
|US_CHANGELINE_ACTIVE          |Changeline occurred          |
|------------------------------+------------------------------|
|IOCM_GET_MEDIA_SENSE          |                              |
|US_MEDIA_144MB                |144KB media capacity          |
|US_MEDIA_288MB                |288KB media capacity          |
|US_MEDIA_720KB                |720KB media capacity          |
|US_MEDIA_UNKNOWN              |Media capacity unknown        |
|------------------------------+------------------------------|
|IOCM_GET_LOCK_STATUS          |                              |
|US_LOCKED                    |Unit Locked                  |
</pre>
'''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'':
<pre>
|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.  |
</pre>
'''Remarks'''
Support:See the command descriptions. <br />Called By: OS2DASD.DMD, other device manager, or filter device driver <br />Context of Call:TASK, INTERRUPT
'''Format of IORB'''
*IORB Type <br />-IORB_DEVICE_CONTROL <br />*IORBH Fields <br />-''CommandCode''<br />--IOCC_DEVICE_CONTROL <br />-''CommandModifiers''<br />--IOCM_ABORT <br />--IOCM_RESET <br />--IOCM_SUSPEND <br />--IOCM_RESUME <br />--IOCM_LOCK_MEDIA <br />--IOCM_UNLOCK_MEDIA <br />--IOCM_EJECT_MEDIA <br />-Valid ''RequestControl''Flags <br />--IORB_ASYNC_POST <br />--IORB_REQ_STATUSBLOCK <br />--IORB_DISABLE_RETRY
'''IORB_DEVICE_CONTROL Description'''
This section defines the IORB_DEVICE_CONTROL control block. (See the following table.)
<pre>
|Field Name      |C-Type          |Length  |Description      |
|-----------------+-----------------+---------+-----------------|
|iorbh            |IORBH            |DB(68)  |IORB header      |
|-----------------+-----------------+---------+-----------------|
|Flags            |USHORT          |DW      |Flags            |
|-----------------+-----------------+---------+-----------------|
|Reserved        |USHORT          |DW      |Reserved        |
</pre>
On entry to the driver:
'''iorbh'''<br />See [[IORB General Format]].
'''Flags'''<br />contains flags defined only for IOCM_SUSPEND requests. For all other requests, this field equals 0.
The following table describes the IOCM_SUSPEND flags.
<pre>
|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.                          |
</pre>
;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 <br />IOERR_CMD_SYNTAX <br />IOERR_CMD_SW_RESOURCE <br />IOERR_UNIT_NOT_ALLOCATED <br />IOERR_UNIT_NOT_READY <br />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'':
{|class="wikitable"
!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 ''RequestControl''Flags
:--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.)
{|class="wikitable"
!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'''<br />See [[#IORB General Format|IORB General Format]].
'''cSGList'''<br />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'''<br />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.
{|class="wikitable"
!Field Name||C-Type||Length||Description
|-
|ppXferBuf||ULONG||DD||Physical pointer to buffer
|-
|XferBufLen||ULONG||DD||Length of buffer
|}
'''ppSGLIST'''<br />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'''<br />contains the length, in bytes, of the command controller buffer.
'''pControllerCmd'''<br />contains a pointer to the controller command buffer in either SCB or CDB format, based on the ''CommandModifier''field.
'''ppSCB'''<br />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'''<br />contains flags to define the request, as shown in the following table.
<pre>
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.
</pre>
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 <br />IOERR_CMD_SYNTAX <br />IOERR_CMD_SGLIST_BAD <br />IOERR_CMD_SW_RESOURCE <br />IOERR_CMD_ABORTED <br />IOERR_UNIT_NOT_ALLOCATED <br />IOERR_UNIT_NOT_READY <br />IOERR_UNIT_PWR_OFF <br />IOERR_ADAPTER_HOSTBUSCHECK <br />IOERR_ADAPTER_DEVICEBUSCHECK <br />IOERR_ADAPTER_OVERRUN <br />IOERR_ADAPTER_UNDERRUN <br />IOERR_ADAPTER_DIAGFAIL <br />IOERR_ADAPTER_TIMEOUT <br />IOERR_ADAPTER_DEVICE_TIMEOUT <br />IOERR_ADAPTER_REQ_NOT_SUPPORTED <br />IOERR_ADAPTER_REFER_TO_STATUS <br />IOERR_DEVICE_DEVICEBUSCHECK <br />IOERR_DEVICE_REQ_NOT_SUPPORTED <br />IOERR_DEVICE_DIAGFAIL <br />IOERR_DEVICE_BUSY <br />IOERR_DEVICE_OVERRUN <br />IOERR_DEVICE_UNDERRUN
For a detailed description of all the return codes, see [[#Error Handling|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'''''
<pre>
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]
</pre>
'''''Results'''''
<pre>
'C' Cleared if successful
AX = ADDHandle
'C' Set if error
AX = ERROR_NOT_ENOUGH_MEMORY
                if CX out of range
                if table is full
</pre>
==== 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'''''
<pre>
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]
</pre>
'''''Results'''''
<pre>
'C' Cleared if successful
AX:BX = global pointer to a table of registered adapter device driver entry points
'C' Set if error
</pre>
'''''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
<pre>
struct DevClassTableEntry {
      USHORT  DCOffset;
      USHORT  DCSelector;
      USHORT  DCFlags;
      UCHAR    DCName[16];
};
struct DevClassTableStruc {
      USHORT                    DCCount;
      USHORT                    DCMaxCount;
      struct DevClassTableEntry  DCTableEntries[MAX];
};
</pre>
'''Note:''' The location of the entry point for an adapter device driver can be derived from its adapter device driver handle, as follows:
<pre>
{
      USHORT i = ADDHandle - 1;
      AddSelector = pDevClassTable->DCTableEntries[i].DCSelector ;
      AddOffset  = pDevClassTable->DCTableEntries[i].DCOffset  ;
};
</pre>
== Error Handling ==
To facilitate the use of device managers across a variety of adapter device drivers this specification defines a set of error codes that should be supplied in the ''ErrorCode'' field of the IORB in the event of a failed operation. The adapter device driver is responsible for translating device error data into these error codes.
Use the following guidelines:
*Do not program an adapter device driver ''defensively''; that is, an adapter device driver should use the services of the device manager and not implement ''excessive'' safeguards. On the other hand, an adapter device driver must be protected against commands outside of its implemented command set to permit upward compatibility.
*Program an adapter device driver to protect against timeouts and ''hung'' devices, transient environmental factors, noise, and so forth.
*Ensure that the adapter device driver has the capability to properly process any scatter/gather list it receives.
*Device error information must be translated into the error codes listed in [[Summary of Error Codes]] for the OS/2 Device Manager.<br /><br />Errors must be fully processed by the adapter device driver, as required by the DASD Device Manager. For example, using the IOERR_ADAPTER_REFER_TO_STATUS error code will result in incorrect operation.
*For other device managers, the same error translation is recommended. If this translation does not produce a reliable error indication, the IOERR_ADAPTER_REFER_TO_STATUS code can be used.
*An IOERR_RETRY flag is included on commands that must be retried by the adapter device driver. Device managers will ignore this flag because retries must be performed at the adapter device driver level. This flag must be ignored also if the device manager has set the IORB_DISABLE_RETRY bit in the IORB.
*An IOCM_GET_UNIT_STATUS command is not expected to fail, regardless of the condition of the underlying devices.
*The IOCM_GET_DEVICE_TABLE command addresses the entire adapter device driver rather than a specific unit; ALLOCATION checks should not be performed.
=== Summary of Error Codes ===
This section describes all the adapter device driver error codes. Upon abnormal termination of a direct call command, the adapter device driver sets the IORB_ERROR flag in the IORBH ''Status'' field, and sets the ''ErrorCode'' field in the IORBH with one of the error codes listed below. The error codes are grouped by ''error category''. Where stated below, the adapter device driver is required to retry the function prior to returning the error code to the caller.
*'''IOERR_CMD'''
This error category maps errors related to the IORB command an adapter device driver receives.
'''IOERR_CMD_NOT_SUPPORTED'''<br />This error indicates that the adapter device driver has not implemented the requested function, including commands that the adapter device driver does not ''understand''.
'''IOERR_CMD_SYNTAX'''<br />This error indicates that the ADD has detected an inconsistency in the IORB that prevents successful execution of the requested function.
'''IOERR_CMD_SGLIST_BAD'''<br />This error indicates that the adapter device driver cannot accept the scatter/gather list passed, due to either a defect in the scatter/gather list (0-length segment) or an underlying hardware limitation.
'''IOERR_CMD_SW_RESOURCE''' (''retry required'')<br />This error indicates that the adapter device driver could not perform the requested function due to the lack of a software resource (for example, buffer, selector, and so forth).
'''Note:'''The adapter device driver should attempt to recover from this condition (using a smaller buffer, for example) even if degraded performance results.
'''IOERR_CMD_ABORTED'''<br />This error is returned when an IOCM_ABORT is received for a device that is currently processing a command. This error code should be set regardless of SCSI ''sense data''that indicates a successful command completion.
'''IOERR_CMD_ADD_SOFTWARE_FAILURE'''<br />This error indicates that the adapter device driver has detected an internal consistency check that prevents it from executing the requested IORB.
'''IOERR_CMD_OS_SOFTWARE_FAILURE'''<br />This error indicates that the adapter device driver received an unexpected error return code from an operating system service. The adapter device driver might retry the operation, depending on the nature of the error.
*'''IOERR_UNIT'''
This error category maps errors related to the condition of an addressed unit.
'''IOERR_UNIT_NOT_ALLOCATED'''<br />This error indicates that the unit has received an IORB command prior to being allocated. This error should be returned to all commands directed to a unit prior to its receiving an IOCM_ALLOCATE_UNIT command.
'''IOERR_UNIT_ALLOCATED'''<br />This error indicates that an attempt was made to allocate a unit that had been allocated previously. Normally, this error would be returned in response to IOCM_ALLOCATE_UNIT.
'''IOERR_UNIT_NOT_READY'''<br />This error indicates that a unit is unable to perform an otherwise valid operation, usually due to an unusual condition on a unit, such as incorrect spindle speed.
'''Note:'''The adapter device driver should not return this error as the result of normal start-up delays on devices.
'''IOERR_UNIT_PWR_OFF'''<br />As an option, the adapter device driver can return this error if it has access to backup configuration data (CMOS) indicating that a previously configured device is not available. If backup configuration data is not available, a powered-off unit normally would not appear in the Adapter Device Driver DEVICETABLE; thus, this error condition would not be possible .
*'''IOERR_RBA'''
This error category pertains to problems accessing a relative block address (RBA) on a particular unit.
'''IOERR_RBA_ADDRESSING_ERROR'''(''retry required'') <br />This error indicates that the requested RBA could not be located. This could be due to a failure to find the appropriate address marks on a particular device.
'''IOERR_RBA_LIMIT'''<br />This error indicates that the specified RBA exceeded the allowable maximum for the media currently in the device.
'''IOERR_RBA_CRC_ERROR'''(''retry required'') <br />This error indicates that the RBA was found; however, the data requested could not be read successfully.
*'''IOERR_MEDIA'''
This error category pertains to problems relating to the media in a drive.
'''IOERR_MEDIA_NOT_FORMATTED'''<br />This error indicates that the requested operation could not be performed since the media in the drive requires low-level formatting. This includes requests to determine media capacity (IOCM_GET_MEDIA_GEOMETRY), if such requests require formatted media.
'''IOERR_MEDIA_NOT_SUPPORTED'''<br />This error indicates that the drive detected media that it cannot support. If the adapter device driver or device cannot make this determination directly, an I/O error can be returned in lieu of this error.
'''IOERR_MEDIA_WRITE_PROTECT'''<br />This error indicates that either the media or the drive is Write protected or that the media is not writable.
'''IOERR_MEDIA_CHANGED'''<br />This error indicates that the media in the drive might have been changed ( for example, removal and/or insertion of the media has been detected since the last operation on the device).
'''IOERR_MEDIA_NOT_PRESENT'''<br />This error indicates that the requested operation, requiring media in the drive, failed because media was not in the drive.
*'''IOERR_ADAPTER'''
This error category pertains to errors that are related to or detected by the host adapter.
'''IOERR_ADAPTER_HOSTBUSCHECK'''<br />This error pertains to problems caused by the adapter's inability to communicate with the host CPU. These errors can include incorrect parity on data received from the host. Frequently these errors are of a severe enough nature to cause shutdown of the host system. In such cases, normal host bus management procedures take precedence over the reporting of this error.
'''IOERR_ADAPTER_DEVICEBUSCHECK'''(''retry required'') <br />This error pertains to problems caused by the adapter's inability to communicate with an attached device. These errors include incorrect parity on data received from the attached device or incorrect bus protocols. These errors are recoverable and should be retried.
'''IOERR_ADAPTER_OVERRUN'''(''retry required'') <br />This error indicates either that the host adapter has lost data from a device due to its buffers being filled faster than they can be emptied by the host CPU or that a device attempted to supply more data than was expected by the host adapter.
'''IOERR_ADAPTER_UNDERRUN'''(''retry required'') <br />This error indicates either that the host adapter was unable to supply data on demand to a device, which caused device operation to fail, or that a device was expecting more data than the adapter was programmed to supply.
'''IOERR_ADAPTER_DIAGFAIL'''<br />This error indicates that the host adapter detected an internal consistency check, preventing its continued operation. Based on the severity of the error, the adapter device driver may or may not retry the requested operation.
'''IOERR_ADAPTER_TIMEOUT'''(''retry required'') <br />This error indicates that the adapter device driver timeout for an adapter to respond has been exceeded. Normally, the device initiates a retry sequence if this error occurs.
'''IOERR_ADAPTER_DEVICE_TIMEOUT'''(''retry required'') <br />This error indicates the failure of a device to respond to the host adapter .
'''IOERR_ADAPTER_REQ_NOT_SUPPORTED'''<br />This error indicates that the requested operation or function is not supported by this adapter.
'''IOERR_ADAPTER_REFER_TO_STATUS'''<br />This error indicates that the reported error could not be classified. Additional information can be provided in the IORB ''StatusBlock''field if requested by the device manager. The ADD should retry the operation unless the IORB_DISABLE_RETRY bit is set.
'''IOERR_ADAPTER_NONSPECIFIC'''(''retry required'') <br />This error should be reported when an ADD cannot classify an adapter- related error condition and an IORB ''StatusBlock''value is not provided. If an IORB ''StatusBlock''value is provided, IOERR_ADAPTER_REFER_TO_STATUS should be returned.
*'''IOERR_DEVICE'''
This error category pertains to errors detected by and relating to devices connected to a host adapter.
'''IOERR_DEVICE_DEVICEBUSCHECK'''(''retry required'') <br />This error pertains to a problem in communications between a host adapter and a device that was detected by the device. This would include incorrect parity on data received by the host adapter or a breakdown in bus protocols between the device and the host adapter.
'''IOERR_DEVICE_REQ_NOT_SUPPORTED'''<br />This error indicates that the requested operation or function is not supported by this device.
'''IOERR_DEVICE_DIAGFAIL'''<br />This error indicates that the device detected an internal consistency check that prevents its correct operation. Depending on the severity of the problem, the ADD might or might not retry the operation.
'''IOERR_DEVICE_BUSY'''(''retry required'') <br />This error indicates that the device is busy and cannot accept the requested operation. This error includes, but is not limited to, SCSI ''Contingent Allegiance''conditions.
'''IOERR_DEVICE_OVERRUN'''(''retry required'') <br />This error indicates either that the device has lost data due to its buffers being filled faster than they can be emptied by the host adapter or that the device attempted to supply more data than the host adapter could accept.
'''IOERR_DEVICE_UNDERRUN'''(''retry required'') <br />This error indicates either that the device was unable to obtain data on demand, which caused device operation to fail, or that device operation required more data than was supplied by the host adapter.
'''IOERR_DEVICE_RESET'''(''retry required'') <br />This error indicates that an unexpected device reset occurred that caused device operation to fail. The ADD should retry the failed operation and report this condition as a ''recovered error''.
'''IOERR_DEVICE_NONSPECIFIC'''(''retry required'') <br />This error should be returned when the ADD cannot classify a device-related error and an IORB ''StatusBlock''value was not supplied. If an IORB ''StatusBlock''value is supplied, IOERR_ADAPTER_REFER_TO_STATUS should be returned.
=== IORB Status Block ===
The IORB Status Block allows an .ADD driver to provide additional information describing an error condition reported in the IORB ErrorCode field.
Currently, only ADD drivers controlling SCSI devices are required to return a StatusBlock when requested to do so. When an ADD driver does return a StatusBlock, it must set the IORB_REQ_STATUSBLOCK bit in the RequestControl flags to indicate that the StatusBlock has been updated.
=== SCSI Status Block Format (SCSI_STATUS_BLOCK) ===
<pre>
|Field Name      |C Type            |Length|Description        |
|----------------+-------------------+------+--------------------|
|Flags          |USHORT            |DW    |Flags              |
|----------------+-------------------+------+--------------------|
|AdapterErrorCode|USHORT            |DW    |Adapter related    |
|                |                  |      |error code          |
|----------------+-------------------+------+--------------------|
|TargetStatus    |UCHAR              |DB    |SCSI Target status  |
|----------------+-------------------+------+--------------------|
|ResidualLength  |ULONG              |DD    |Residual byte count |
|----------------+-------------------+------+--------------------|
|AdapterDiagInfo |UCHAR              |DB(8) |Adapter specific    |
|                |                  |      |info                |
|----------------+-------------------+------+--------------------|
|ReqSenseLen    |USHORT            |DW    |Request Sense Data  |
|                |                  |      |allocation          |
|----------------+-------------------+------+--------------------|
|SenseData      |PSCSI_REQSENSE_DATA|DD    |Request Sense Buffer|
|                |                  |      |pointer            |
</pre>
==== Flags ====
Flags contain bit flags indicating the validity of other fields within the SCSI Status Block.
<pre>
|Flag                          |Description
|------------------------------+------------------------------|
|STATUS_SENSEDATA_VALID        |Set by the ADD driver to      |
|                              |indicate that SCSI Sense Data |
|                              |was recovered from the target |
|                              |and placed in the buffer      |
|                              |indicated by SenseData.      |
|------------------------------+------------------------------|
|STATUS_RESIDUAL_VALID        |Set by the ADD driver to      |
|                              |indicate that the target did  |
|                              |not transfer the number of    |
|                              |bytes requested. If set the  |
|                              |ADD driver is required to    |
|                              |return a correct              |
|                              |ResidualCount.                |
|------------------------------+------------------------------|
|STATUS_DIAGINFO_VALID        |Set by the ADD driver if it  |
|                              |returned adapter specific    |
|                              |diagnostic information.      |
|------------------------------+------------------------------|
|STATUS_DISABLE_REQEST_SENSE  |Set by the client to indicate |
|                              |that the ADD driver must not  |
|                              |issue a Request Sense Command |
|                              |to the target regardless of  |
|                              |the SCSI status reported.    |
</pre>
'''Note: (SCSI_DISABLE_REQUEST_SENSE 0x0008)'''
This is a proposed addition to the current ADD/DM specification to simplify the implementation of Device Managers which have clients that explicitly issue their own Request Sense operation. When this bit is set, the ADD driver will not be able to accurately determine an IORB ErrorCode. In this case, the ADD driver must return IOERR_DEVICE_NON_SPECIFIC in the ''IORB ErrorCode'' field if the target reports other than &quot;GOOD&quot; status.
==== AdapterErrorCode ====
An AdapterErrorCode indicates that an adapter related error condition occurred. For example, a SCSI operation which completed successfully but resulted in an adapter detected underrun/overrun would report this condition in this field. The error codes used are defined by the IOERR_* codes in the previous section. If no adapter error condition was detected, then this field must be cleared by the ADD driver.
'''Note:''' It is possible for a SCSI operation to fail, but this field would be zero. This would be the usual case for target generated error conditions.
Conversely, it is possible for a SCSI operation to succeed at the IORB level, for example, no IORB Error code reported, but this field would non- zero. This would be the case when the SCSI adapter detected an overrun/ underrun on an otherwise successful SCSI operation.
==== TargetStatus ====
TargetStatus indicates the SCSI status byte returned by the target during the SCSI status bus phase.
==== ResidualLength ====
ResidualLength indicates the difference between the requested data transfer length in the IORB and the actual number of bytes transferred by the target. This field must always be set to as a non-negative number. The specific error condition Overrun vs Underrun should be indicated by setting the appropriate error code in AdapterErrorCode. If the ADD driver is able to return an accurate ResidualLength, it must set the STATUS_RESIDUAL_VALID bit in the ''Flags'' field.
==== AdapterDiagInfo ====
The AdapterDiagInfo field consists of eight bytes the ADD supplier may use to report vendor specific information to assist in local problem determination. If this information is returned the ADD driver must set the bit STATUS_DIAGINFO_VALID in the Flags field.
==== ReqSenseLen ====
The ReqSenseLen field indicates the size of the SenseData buffer available. If the target indicates a SCSI status of CHECK_CONDITION then the ADD driver should issue a SCSI Request_Sense command with a data transfer length indicate by ReqSenseLen.
'''Note:''' ADD drivers are required to obtain Sense Data whether or not a Status Block is present. In the absence of a StatusBlock, this would usually be done using internal storage of the ADD driver.
However, if a status block is present, then the ADD driver must transfer no less than the number of bytes indicated by the ''ReqSenseLen'' field and provide this data in the SenseData buffer.
==== SenseData ====
The SenseData field points to a data buffer to receive SenseData returned by the SCSI target as a result of a REQUEST SENSE operation issued by the ADD driver.
== Adapter Device Driver Command-Line Parameters ==
Following is a diagram of an adapter device driver command-line structure:
<pre>
BASEDEV=AddName.ADD──►
──►Driver-Parameters──►Adapter-Parameters──►Unit-Parameters─┬┐
                    ▲                    ▲                ││
                    │                    └─────────────────┘│
                    └───────────────────────────────────────┘</pre>
=== Syntax Conventions ===
Following are the adapter device driver syntax conventions:
*Command-line contents are case-insensitive.
*All command-line options begin with the slash character (/).
*The exclamation character (!) is a negation operator; that is, it negates the option that follows it. The colon character (:) indicates that a list of one or more unit IDs follows the option. <br />*The alphabetic ''d''character (&lt;d>) indicates a decimal digit. <br />*The alphabetic ''h''character (&lt;h>) indicates a hexadecimal digit.
=== Command-Line Parameter Classes ===
An adapter device driver command line contains three classes of parameters:
*'''Adapter Device Driver Parameters'''<br />''Adapter device driver parameters''apply to all adapters and units managed by an adapter device driver unless overridden by adapter parameters or unit parameters.
*'''Adapter Parameters'''<br />''Adapter parameters''begin with the (/A) switch and identify a specific adapter card. Parameters following the (/A) switch apply only to the adapter card indicated.
*'''Unit Parameters'''<br />''Unit parameters''apply specific units on an adapter.
'''Note:''' In some cases, a parameter may appear as both an Adapter parameter and a Unit parameter. If the host adapter hardware supports specifying a parameter on a per-unit basis, then it is recommended that the adapter device driver support both the per-Adapter and per-Unit forms of the parameter.
=== SCSI-Specific Parameters ===
The following diagram illustrates a SCSI adapter device driver parameter structure:
<pre>
SCSI-Driver-Parameters::= ─┬── /<!>SN ───────────────────►
                          ├── /<!>ET ─►▲
                          ├── /V    ─►│
                          └────────────┘
SCSI-Adapter-Parameters::=
        ───► /A:d ─┬── /S:d  ────┬── /<!>DM ─────►
                    ├── /P:hhhh─►▲ ├── /<!>SN ─►▲
                    └────────────┘ ├── /<!>SN ─►│
                                  ├── /<!>ET ─►│
                                  ├── /I    ─►│
                                  └────────────┘
SCSI-Unit-Parameters::= ──┬── /<!>DM  ────────────┬─────►
                        ▲├── /<!>SM  ─►▲        │
                        │├── /<!>SN  ─►│        │
                        │├── /<!>ET  ─►│        │
                        │├── /<!>HCR ─►│        │
                        │├── /<!>HCW ─►│        │
                        │└─────────────┘        │
                        └────────────────────────┘
SCSI-Target-IDs::=      ─┬┬── d    ──┬┬────────► (d=0-7)
                        │└── (d,d) ──┘│
                        └─── ,    ───┘
</pre>
'''Note:''' All SCSI adapter device drivers must support the following parameters:
/V Verbose <br />/A Adapter Identification <br />/DM Enable/Disable DASD Manager Support <br />/SM Enable/Disable SCSI Manager Support
To insure support of various CD-ROM drives the implementation of the following parameters is recommended:
/SN Enable/Disable Synchronous Negotiation <br />/ET Enable/Disable Embedded Target Support
Support of the remaining parameters is optional.
'''SCSI Adapter Device Driver Parameters'''
/SNSynchronous Negotiation
This parameter indicates a SCSI Host Adapter should attempt to initiate synchronous data transfers. Negating this parameter (/!SN) indicates that the SCSI Host Adapter must not attempt to initiate synchronous data transfers.
/ETEmbedded Targets
This parameter indicates that the adapter device driver must search each SCSI Target for logical units. Negating this parameter (/!ET) indicates that the adapter device driver should only check LUN 0 on each SCSI Target regardless of whether additional Logical Units are present.
/VVerbose
This parameter indicates that the adapter device driver must display diagnostic information during the OS/2 system initialization. The DevHlp_Save_Message device help routine should be used to display this information.
The following format for the displayed information is recommended:
<pre>
XYZ-2010 OS/2 2.0 Driver (yymmdd)
Copyright (c) 1993 XYZ Inc. All Rights Reserved
Adapter: 0 Base Port: 0123  IRQ: 10
  Target: 0 LUN: 0  SCSI_Inquiry_Data (Bytes 8-35)
  Target: 1 LUN: 0  SCSI_Inquiry_Data
  Target: 2 LUN: 0  SCSI_Inquiry_Data
</pre>
/A:dAdapter Index
This parameter specifies the ordering of adapters in the DEVICETABLE returned by the adapter device driver. Normally, adapters are numbered consecutively, starting at 0.
/S:dAdapter Slot ID
For host systems with individually addressable slots, the adapter device driver can designate the location of a host adapter by its slot number, according to the host system's slot addressing scheme. Typically &lt;d> is a small 0-based number specifying the host system slot.
/P::hhhhAdapter Base I/O Port Address
For host systems with non-addressable slots, the adapter device driver can designate the location of a host adapter by its base I/O port address. Typically, &lt;hhhh> is a 3-4 digit hexadecimal number.
'''Note:''' In cases where a specific adapter designation is not made, the adapter device driver can apply its own ordering, based on either the base I/O port address or the physical slot address.
'''Note:''' In general, an adapter device driver should choose to support only one of the above addressing methods. If an adapter device driver supports more than one addressing method, it must not permit a mix of addressing methods on a single line.
/DMDASD Manager Support
This parameter indicates that this unit must be supported by the IBM-supplied DASD device manager (OS2DASD.DMD). If this parameter is not specified, the default is to permit DASD device manager support. If this parameter is negated, the adapter device driver must set the UF_NODASD_SUPT flag in the ''UnitFlags'' field of the DEVICETABLE entry for the device. This parameter is used in conjunction with an OEM-supplied device manager to permit control of specific DASD and SCSI targets.
/SMSCSI Manager Support
This parameter indicates that this unit must be supported by the IBM-supplied SCSI device manager (OS2SCSI.DMD). If this parameter is not specified, the default setting is to permit SCSI device manager support. If this parameter is negated, the adapter device driver must set the UF_NOSCSI_SUPT flag in the ''UnitFlags'' field of the DEVICETABLE entry for the device. This parameter is used in conjunction with an OEM-supplied device manager to permit control of specific non-DASD and non-SCSI targets.
/IIgnore Adapter
This parameter indicates that adapter device driver should treat the indicated adapter as an uninstalled adapter. The purpose of this parameter is to allow third party software to manage an entire adapter that would normally be managed by the adapter device driver. When specified, the driver must not create a device table entry for the indicated adapter.
/HCWEnable Hardware Write Caching
This parameter is used to control adapter-implemented deferred-write caching for those adapters that support it. If this parameter is not specified, this feature must be enabled. If this parameter is negated, deferred write caching must be disabled on the specified units. Host adapters that do not implement on-board caching, or that do not have direct control over the operation of the cache, must ignore this parameter if specified.
/HCREnable Hardware Read Caching
This parameter is used to control adapter-implemented Read caching for those adapters that support it. If this parameter is not specified, this feature must be enabled. If this parameter is negated, Read caching must be disabled on the specified units. Host adapters that do not implement on-board caching, or do not have direct control over the operation of the cache, must ignore this parameter if specified.
d,d...SCSI Embedded Target ID
The above parameters can be followed by a colon (:) with a list of SCSI target IDs, separated by commas. The logical unit number (LUN) for the specified SCSI target is presumed to be 0.
(d,d),(d,d)...SCSI Target/LUN ID
The above parameters can be followed by a colon (:) with a list of SCSI target/LUN pairs in parentheses.
=== Diskette-Specific Parameters ===
The following diagram illustrates a diskette-specific adapter device driver parameter structure:
<pre>
Diskette-Driver-Parameters::= ─┬── /MCA ─────────────────────►
                              │          ▲
                              └──────────┘
Diskette-Adapter-Parameters::=
                  ───► /A:d ──┬────────────────┬──────┬─────►
                              ▲├── /DMZ:d    ─►│      │
                              │├── /IRQ:dd    ─►│      │
                              │├── /PORT:hhhh ─►│      │
                              │└────────────────┘      │
                              └────────────────────────┘
Diskette-Unit-Parameters::=
                  ───► /U:d ──┬─► /<!>AHS            ──┬┬┬─►
                    ▲        ▲├── /F:Drive Capacity  ─►│││
                    │        │├── /SPEC:Specify-Bytes ─►│││
                    │        │├── /CL:Changeline-Type ─►│││
                    │        │└─────────────────────────┘││
                    │        └───────────────────────────┘│
                    └──────────────────────────────────────┘
Drive Capacity  =  ────────────┬── 360KB  ───────────────────►
                              ├── 1.2MB  ─►▲
                              ├── 720KB  ──│
                              ├── 1.44MB ─►│
                              ├── 2.88MB ─►│
                              └────────────┘
Specify-Bytes  =  ──────────────► hh,hh  ───────────────────►
Changeline-Type =  ───────────┬┬─► /AT  ──┬┬─────────────────►
                              │└── /PS2 ──┘│
                              └─── None ───┘
</pre>
'''Diskette Adapter Device Driver Parameters'''
/MCAInstall Adapter Device Driver on uChannel machines
This parameter informs the IBM1FLPY adapter device driver to install on uChannel machines. The default is not to install on uChannel machines.
/DMA:dDMA Channel Number
This parameter specifies the DMA channel number that must be used for the diskette adapter. DMA Channel 2 is used if this parameter is not specified.
/IRQ:ddInterrupt Level
This parameter specifies the interrupt level that must be used for the diskette adapter. IRQ 6 is used if this parameter is not specified.
/U:dUnit Number
This parameter specifies the diskette drive number to which options following this parameter apply. Diskette drive numbers start at 0.
'''Note:''' To define a third diskette drive on a controller, the /U and /F parameters must be specified.
/AHSAutomatic Head Switch
This parameter informs the driver to use a diskette controller feature that automatically switches from Head 0 -> 1. This improves performance by reading both sides of the diskette in a single operation. The default is to enable this option. It may be disabled by negating this parameter.
/F:ccccDrive Capacity
This parameter overrides the BIOS-supplied drive capacity information, enabling the use of drives that the host system's BIOS does not properly recognize. The drive capacity must be suffixed by a (KB) or an (MB).
/SPEC:hh,hhDrive Specify Bytes
This parameter permits the setting of diskette controller ''specify bytes''. This is used for drives with unusual or non-standard timing requirements. The correct setting of this parameter varies with drive manufacturers and must be obtained from the drive vendor.
/CL:cltChangeline Type
This parameter permits changing the interpretation of the media change detection signals. The changeline signal can be interpreted according to PC-AT* or PS/2* standards; or checking of the changeline signal can be disabled using this parameter.
=== ST-506/IDE-Specific Parameters ===
The following diagram illustrates a ST-506/IDE unit parameter structure:
<pre>
ST-506-Driver-Parameters::= ─┬─► /V ─────────────────────►
                            │        ▲
                            └────────┘
ST-506-Adapter-Parameters::=
      ──► /A:d ───┬──────────────────────────┬──────────►
                ▲ ├── /I        ─►▲        │
                │ ├── /<!>R      ─►│        │
                │ ├── /IRQ:dd    ─►│        │
                │ ├── /PORT:hhhh ─►│        │
                │ └────────────────┘        │
                └────────────────────────────┘
ST-506-Unit-Parameters::=
      ───► /U:d ───┬─► /GEO ─┬─► dd              ──┬┬┬┬─►
      ▲          ▲│        ├── (dddd,dddd,dddd) ─►││││
      │          ││        └──────────────────────┘│││
      │          │├── /T:dddd  ─────────────────────┤││
      │          │├── /SMS    ─────────────────────┤││
      │          │└── /LBA    ─────────────────────┘││
      │          └───────────────────────────────────┘│
      └───────────────────────────────────────────────┘
</pre>
====ST-506/IDE Adapter Device Driver Parameters====
/VVerbose - Display driver information
This parameter displays the adapter device driver level, disk controller status and drive geometry information during the OS/2 system initialization.
/IIgnore Adapter
This parameter indicates that the IBM1S506 driver should not attempt to initialize the adapter indicated.
This adapter device driver automatically attempts to locate and initialize both the primary and secondary adapters. In some cases other DASD controllers may appear between the primary and secondary IDE controllers. In these cases the system should be configured as follows:
<pre>
BASEDEV=IBM1S506.ADD /V /A:1 /I
BASEDEV=MOREDASD.ADD
BASEDEV=IBM1S506.ADD /V /A:0 /I
</pre>
/&lt;!>RReset Adapter
If this parameter is negated (/!R), adapter resets are disabled. In most cases resets are beneficial to assist in recovering from transient hardware problems such as lost interrupts, timeouts, or commands a particular adapter may not support.
However, for some ESDI adapters, options set by vendor unique commands such as &quot;Sector Sparing&quot; may be lost after a reset. Setting this switch is recommended for ESDI adapters with disks formatted using &quot;Sector Sparing.&quot;
/IRQ:ddInterrupt Level
This parameter overrides the default IRQ Number for the adapter indicated. The default IRQ address for Adapter 0 is (14) and for Adapter 1 is (15).
/U:dUnit Number
This parameter specifies the fixed disk drive number to which options following this parameter apply. Fixed disk drive numbers start at 0.
/GEODrive Geometry
This parameter overrides the Cylinder/Head/Sector geometry for the unit selected. The fourth parameter is the Write Precompensation Cylinder which may be omitted for drives which do not require precompensation.
As an alternate format standard BIOS drive types may be used. Types (0-47) are supported. User defined types 47-49 should be entered directly by in the previous format.
If a second set of geometry is present, then the first set specifies the physical geometry of the drive, and the second set indicates the translated geometry which is reported to the OS/2 system.
/T:ddddDrive Timeout
This parameter indicates the total allowable error recover time for a request. Error recovery times &lt; 5 seconds will be ignored. This parameter defaults to 30 seconds. A shorter interval may be desirable for fault tolerant applications.
/SMSEnable Multple Block I/O Support
This parameter enables Set Multiple Support which the improves performance of some IDE drives. If the drive does not have this feature, this switch will be ignored. The /V - (Verbose) option will indicate whether this feature has been enabled on a particular drive.
/LBAEnable LBA Support
This parameter enables Logical Block Support for IDE drives which support this option. The /V - (Verbose) option will indicate whether this feature has been enabled on a particular drive.
== DASD IOCtl Device Driver Test Tool ==
This chapter explains how to use the DDTT to test a DASD Device Driver by executing disk/diskette-oriented test scripts.
=== Overview ===
DASD functional verification tests exercise the Application Program Interfaces (APIs) - mainly DosDevIOCtl variations - that interface with DASD device drivers. The test environment is defined by the Device Driver Test Tool (DDTT) and each test is written as a DDTT script using Global and DASD grammars. See Device Driver Test Tool (DDTT) for a description of the DDTT. The tests described herein give the user a repeatable set of scripts for verifying disk and diskette functions. They may also be used as examples for creating additional specialized test cases.
As the DDTT parses and executes each test script, it simultaneously creates a disk log file that timestamps the activity and logs each script command. If the command initiates an API call, then the result of the command is logged, be it failure with a return code or success with possible returned data. If the script fails to complete, the log, up to the point of failure, is available for diagnosis.
These tests can be used to verify correct interaction between the DASD device and the following OS/2 components:
*DOSDevIOCtl API interface
*FAT and HPFS file systems
*OS2DASD.DMD, OS2SCSI.DMD and OS2ASPI.DMD device managers
*SCSI Adapter device drivers
*Non-SCSI Adapter device drivers
=== Installation ===
This CD-ROM contains the executables, libraries, grammars, and test cases necessary to run DASD test suites.
The following procedure describes installation for running test cases:
1. Copy the component files from the Device Driver Kit for OS/2 CD-ROM to the hard drive. All files should reside in a common directory, such as \TDASDIO. If the target directory is C:\TDASDIO and the E: drive contains the information from the Device Driver Kit for OS/2, then use the following commands to copy the DASD test suite:
[C:\]md tdasdio
[C:\]cd tdasdio
[C:\tdasdio]copy e:\ddk\testcert\storage\function\dasd\*
[C:\tdasdio]copy e:\ddk\testcert\general\ddtt\*
2. Add C:\TDASDIO to the LIBPATH and PATH in the CONFIG.SYS file.
3. Reboot your machine so the new LIBPATH entry takes effect.
The following DDTT files are required for execution of CD-ROM scripts:
*DDTT.EXE
*DDTT.DLL
*GLOBAL.DLL
*GLOBAL.GRA
*DDTDASD.DLL
*DASD.GRA
[[Image:Storage-img1.gif]]
===Test-Case Execution===
Test case scripts are driven by the DDTT. The DDTT can be initiated via an OS/2 command line or from a batch file or REXX statement:
  [C:\TDASDIO]DDTT DASDSTD1.SCR
The DDTT creates a Presentation Manager thread window that consists of:
*a multi-line, scrolled output field for logging script progress
*a single-line entry field for operator input
*a single-line text output field for script-initiated prompts and messages
The DDTT DASD tests must be executed on a directly-attached DASD device. These tests will not work when executed against a DASD device accessed by way of a network connection.
===DASD IOCtl Test Grammar Function Calls===
The following is a list of DASD IOCtl Test Grammar Function Calls:
*DASD_OPEN
*DASD_CLOSE
*LOCK_LOGICAL
*UNLOCK_LOGICAL
*QUERY_LOCK
*GET_LOGICAL_PARAMS
*QMEDIA_SENSE
*QLOGICAL_MAP
*SET_LOGICAL_MAP
*BLOCK_REMOVABLE
*REDETERMINE_MEDIA
*READ_LOGICAL
*WRITE_LOGICAL
*VERIFY_LOGICAL
*FORMAT_TRACK
*OPEN_PHYSICAL
*CLOSE_PHYSICAL
*LOCK_PHYSICAL
*UNLOCK_PHYSICAL
*GET_PHYSICAL_PARAMS
*QUERY_DISK_COUNT
*WRITE_PHYSICAL
*READ_PHYSICAL
*VERIFY_PHYSICAL
*READ_FILE
*WRITE_FILE
*SET_DEVICEPARAMS
*CHECKRETURN
*CHECKVALUE
====DASD_OPEN====
This function opens a logical partition on a physical drive. In the case of removable media devices, the entire device will be opened. The media must be mounted for successful completion.
{|class="wikitable"
|+Input Parameter Keywords
!Keyword||Type||Description
|-
|DEVICENAME||STRING||Drive letter for logical disk
|}
{|class="wikitable"
|+Output Parameter Keywords
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||File handle for DASD device being tested
|}
;Logged Data
None.
====DASD_CLOSE====
This function closes a logical partition on a physical drive.
{|class="wikitable"
|+Input Parameter Keywords
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||File handle for DASD device being tested
|-
|DDRC||NUM||Function return code
|}
;Output Parameter Keywords
None.
;Logged Data
None.
====LOCK_LOGICAL====
Category 8h Function 00h - Lock Drive
This function locks a logical partition on a physical drive.
{|class="wikitable"
|+Input Parameter Keywords
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||File handle for DASD device being tested
|}
{|class="wikitable"
|+Output Parameter Keywords
!Keyword||Type||Description
|-
|DDRC||NUM||Function return code
|}
;Logged Data
None.
====UNLOCK_LOGICAL====
Category 8h Function 01h - Unlock Drive
This function unlocks a logical partition on a physical drive.
Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
\--------------------------------------------------------------/
</pre>
Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
Logged Data
None.
====QUERY_LOCK====
Category 8h Function 66h - Get Lock Status
This function indicates if the drive is locked with or without media in it.
Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
\--------------------------------------------------------------/
</pre>
Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|PRESENCE            |NUM                |Media presence flag |
|--------------------+--------------------+--------------------|
|LOCKCODE            |NUM                |2-bit lock code    |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
Logged Data
Lock status and Lock/Unlock/Eject command support statement
Media presence status
====GET_LOGICAL_PARAMS====
Category 8h Function 63h - Query Device Parameters
This function gets the logical parameters for the addressed drive. Not all parameters are defined for all drive types.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|CLUSTERSIZE        |NUM                |Cluster size in    |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|FATCOUNT            |NUM                |Number of FATs      |
|--------------------+--------------------+--------------------|
|ROOTCOUNT          |NUM                |Number of root      |
|                    |                    |directory entries  |
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors  |
|                    |                    |(small disk)        |
|--------------------+--------------------+--------------------|
|FATSIZE            |NUM                |Number of sectors  |
|                    |                    |per FAT            |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Size of tracks      |
|--------------------+--------------------+--------------------|
|HEADCOUNT          |NUM                |Number of heads    |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |Number of physical  |
|                    |                    |drive cylinders    |
|--------------------+--------------------+--------------------|
|HIDDEN              |NUM                |Number of hidden    |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|RESERVED            |NUM                |Number of reserved  |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|LGSECTORCOUNT      |NUM                |Number of sectors  |
|                    |                    |(large disk)        |
|--------------------+--------------------+--------------------|
|$SECTORCOUNT        |NUM                |Applicable sector  |
|                    |                    |count              |
|--------------------+--------------------+--------------------|
|DEVICETYPE          |NUM                |Device layout code  |
|--------------------+--------------------+--------------------|
|MEDIATYPE          |NUM                |Media descriptor    |
|--------------------+--------------------+--------------------|
|HARDDISK            |NUM                |Hard disk flag      |
|                    |                    |(1=yes)            |
|--------------------+--------------------+--------------------|
|ADDR16              |NUM                |16MB size flag      |
|                    |                    |(1=greater)        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data (where defined)
Size of sectors Size of clusters Fat count Root directory size Number of sectors per FAT Sectors per track Reserved sector count Hidden sector count Number of heads Total sector count Number of cylinders Media descriptor Device attributes
====QMEDIA_SENSE====
Category 8h Function 60h - Query Media Sense
This function returns the media sense information for a removable media drive.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
Media Sense Information Returns a byte that corresponds to the type of disk that is in the 3.5-inch drive. Where:
:1 = 702KB Disk
:2 = 1.44MB Disk
:3 = 2.88MB Disk
====QLOGICAL_MAP====
Category 8h Function 21h - Query Logical Map
This function returns the logical drive letter that was last used to reference (open) the drive.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
Logical drive number of the last drive letter that was used to reference the drive (or zero if only one drive is defined).
====SET_LOGICAL_MAP====
Category 8h Function 03h - Set Logical Map
This function sets the next logical drive letter that is used to reference the drive.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DRIVEHANDLE        |NUM                |File handle for DASD
|                    |                    |device being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
Logical drive currently mapped to the drive opened per the file handle specified.
====BLOCK_REMOVABLE====
Category 8h Function 20h - Block Removable
This function is used to determine if the media is removable or fixed.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DRIVEHANDLE        |NUM                |File handle for DASD
|                    |                    |device being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
|--------------------+--------------------+--------------------
|REMOVABLE          |NUM                |1 if true; 0 if
|                    |                    |false
</pre>
Logged Data
Removable Media Returns a byte that specifies if the media is removable or not. Where:
:0 = Removable media
:1 = Nonremovable media
====REDETERMINE_MEDIA====
Category 8h Function 02h - Redetermine Media
This function redetermines the media for removable media devices.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DRIVEHANDLE        |NUM                |File handle for DASD
|                    |                    |device being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====READ_LOGICAL====
Category 8h Function 64h - Read Track
This function reads sectors from a logical partition on a physical drive.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The target head    |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The target cylinder |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector value        |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors to|
|                    |                    |be read            |
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Buffer name        |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BUFFER              |NUM                |Pointer to Read    |
|                    |                    |buffer              |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
None.
====WRITE_LOGICAL====
Category 8h Function 44h - Write Track
This function writes sectors to a logical partition on a physical drive. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer. The sector count is defaulted to the read buffer size.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The target head    |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The target cylinder |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector value        |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Name of an existing |
|                    |                    |Read buffer        |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
None.
====VERIFY_LOGICAL====
Category 8h Function 65h - Verify Track
This function verifies sectors in a logical partition on a physical drive.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The target head    |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The target cylinder |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector              |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors to|
|                    |                    |verify              |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
None.
====FORMAT_TRACK====
Category 8h Function 45h - Format Track
This function formats and verifies a track. (Removable media devices only. )
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for DASD|
|                    |                    |device being tested |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The target head    |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|TRACKNUM            |NUM                |Number of tracks to |
|                    |                    |format              |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
None.
====OPEN_PHYSICAL====
This function opens a physical disk. It will only operate on drives designated as fixed disks. This may or may not correspond to the physical characteristics of the drive.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DISKNUMBER          |STRING              |Disk number of DASD |
|                    |                    |device to test.    |
|                    |                    |Example: 1: for    |
|                    |                    |first fixed disk    |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description       
|--------------------+--------------------+--------------------
|DISKHANDLE          |NUM                |Disk handle for the
|                    |                    |request           
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====CLOSE_PHYSICAL====
This function closes a physical disk.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DISKHANDLE          |NUM                |Open handle for disk
|                    |                    |being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====LOCK_PHYSICAL====
Category 9h Function 00h - Lock Physical
This function locks a physical disk.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DISKHANDLE          |NUM                |Open handle for disk
|                    |                    |being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====UNLOCK_PHYSICAL====
Category 9h Function 01h - Unlock Physical
This function unlocks a physical disk.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DISKHANDLE          |NUM                |Open handle for disk
|                    |                    |being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====GET_DISK_COUNT====
Query Number of Physical Disks
This function returns the number of system physical disks.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DISKHANDLE          |NUM                |Open handle for disk
|                    |                    |being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DISKCOUNT          |NUM                |Number of system
|                    |                    |hard disks
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
System hard disk count.
====GET_PHYSICAL_PARAMS====
Category 9h Function 01h - Query Physical Device Parameters
This function gets the parameters of a physical disk.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DISKHANDLE          |NUM                |Open handle for disk
|                    |                    |being tested
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|CYLINDERCOUNT      |NUM                |Number of cylinders
|                    |                    |on the physical disk
|--------------------+--------------------+--------------------
|HEADCOUNT          |NUM                |Number of heads on
|                    |                    |the physical disk
|--------------------+--------------------+--------------------
|TRACKSIZE          |NUM                |Number of sectors
|                    |                    |per track on the
|                    |                    |physical disk
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
Number of cylinders on the physical disk Number of heads on the physical disk Number of sectors per track on the physical disk
====WRITE_PHYSICAL====
Category 9h Function 44h - Write Physical
This function writes to a physical disk. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DISKHANDLE          |NUM                |Open handle for disk|
|                    |                    |being tested        |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The physical head on|
|                    |                    |the drive          |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The cylinder to    |
|                    |                    |write to            |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector              |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Name of Read buffer |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
None.
====READ_PHYSICAL====
Category 9h Function 64h - Read Physical
This function reads sectors from a physical disk.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DISKHANDLE          |NUM                |Open handle for disk|
|                    |                    |being tested        |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The physical head on|
|                    |                    |the drive          |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The cylinder to read|
|                    |                    |from                |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector              |
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |The number of      |
|                    |                    |physical sectors to |
|                    |                    |read                |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Name of Read buffer |
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BUFFER              |NUM                |Pointer to Read    |
|                    |                    |buffer              |
|--------------------+--------------------+--------------------|
|DDRC                |NUM                |Function return code|
</pre>
Logged Data
None.
====VERIFY_PHYSICAL====
Category 9h Function 65h - Verify Physical
This function verifies sectors on a physical disk.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DISKHANDLE          |NUM                |Open handle for disk
|                    |                    |being tested
|--------------------+--------------------+--------------------
|HEAD                |NUM                |The target head
|                    |                    |value
|--------------------+--------------------+--------------------
|CYLINDER            |NUM                |The target cylinder
|                    |                    |value
|--------------------+--------------------+--------------------
|SECTORSTART        |NUM                |The target start
|                    |                    |sector
|--------------------+--------------------+--------------------
|SECTORCOUNT        |NUM                |The number of
|                    |                    |physical sectors to
|                    |                    |verify
|--------------------+--------------------+--------------------
|SECTORSIZE          |NUM                |Sector size in bytes
|--------------------+--------------------+--------------------
|TRACKSIZE          |NUM                |Track size in
|                    |                    |sectors
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====READ_FILE====
This function reads from a disk file.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|FILENAME            |STRING              |The qualified name
|                    |                    |of the file to read
|--------------------+--------------------+--------------------
|BYTESTART          |NUM                |The byte offset
|                    |                    |within the file
|--------------------+--------------------+--------------------
|BYTECOUNT          |NUM                |The number of bytes
|                    |                    |to read
|--------------------+--------------------+--------------------
|$BUFFER            |STRING              |Name of the Read
|                    |                    |buffer
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|BUFFER              |NUM                |Read buffer
|                    |                    |reference
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====WRITE_FILE====
This function writes to a disk file. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|FILENAME            |STRING              |The qualified name
|                    |                    |of the target file
|--------------------+--------------------+--------------------
|BYTESTART          |NUM                |The byte offset
|                    |                    |within the file
|--------------------+--------------------+--------------------
|$BUFFER            |STRING              |Name of the Read
|                    |                    |buffer
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====SET_DEVICEPARAMS====
Category 8h Function 43h - Set Device Parameters
This function sets the device parameters. Input parameters are most easily set by issuing a GET_DEVICEPARAMS.
Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DRIVEHANDLE        |NUM                |Drive handle for
|                    |                    |DASD device being
|                    |                    |tested
|--------------------+--------------------+--------------------
|SECTORSIZE          |NUM                |Sector size in bytes
|--------------------+--------------------+--------------------
|CLUSTERSIZE        |NUM                |Cluster size in
|                    |                    |sectors
|--------------------+--------------------+--------------------
|FATCOUNT            |NUM                |Number of FATs
|--------------------+--------------------+--------------------
|ROOTCOUNT          |NUM                |Number of root
|                    |                    |directory entries
|--------------------+--------------------+--------------------
|HIDDEN              |NUM                |Number of hidden
|                    |                    |sectors
|--------------------+--------------------+--------------------
|RESERVED            |NUM                |Number of reserved
|                    |                    |sectors
|--------------------+--------------------+--------------------
|LGSECTORCOUNT      |NUM                |Number of sectors
|                    |                    |(large disk)
|--------------------+--------------------+--------------------
|SECTORCOUNT        |NUM                |Number of sectors
|                    |                    |(small disk)
|--------------------+--------------------+--------------------
|FATSIZE            |NUM                |Number of sectors
|                    |                    |per FAT
|--------------------+--------------------+--------------------
|TRACKSIZE          |NUM                |Size of the tracks
|                    |                    |on the specified
|                    |                    |device
|--------------------+--------------------+--------------------
|HEADCOUNT          |NUM                |Number of heads on
|                    |                    |the physical disk
|--------------------+--------------------+--------------------
|CYLINDER            |NUM                |The number of
|                    |                    |cylinders
|--------------------+--------------------+--------------------
|MEDIATYPE          |NUM                |Media descriptor
|--------------------+--------------------+--------------------
|DEVICETYPE          |NUM                |Device layout code
|--------------------+--------------------+--------------------
|ADDR16              |NUM                |16MB size flag
|                    |                    |(1=greater)
|--------------------+--------------------+--------------------
|HARDDISK            |NUM                |Hard disk flag
|                    |                    |(1=yes)
</pre>
Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|DDRC                |NUM                |Function return code
</pre>
Logged Data
None.
====CHECKRETURN====
Check Return Code Diagnostic Function
This function verifies that the return code from a previous function is equal to a given value. The function is used for error testing to verify expected return codes. It is assumed that a previous function has set the DDRC parameter. $RC is set by the script author to the expected value.
Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|$RC                |NUM                |The expected return
|                    |                    |code
</pre>
Logged Data
Message stating the result of the comparison -- either failure or success.
====CHECKVALUE====
Check Parameter Value Diagnostic Function
This function verifies that a parameter returned by a previous DASD function is equal to a given numeric value. $PARM must be explicitly equated to the parameter being tested and $EXPECT set to the expected value .
Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|$PARM              |NUM                |The returned        |
|                    |                    |parameter value    |
|--------------------+--------------------+--------------------|
|$EXPECT            |NUM                |The expected value  |
</pre>
Logged Data
Message stating the result of the comparison -- either failure or success.
===Description of Test Cases===
Each of the DASD test cases can be executed by invoking the DDTT from either a command line, a batch file, or a REXX file. Test scripts are described below. The user is free to create additional tests or construct multi-threaded test cases after becoming familiar with the DDTT and the DASD grammar files.
Test scripts generally start by opening to the physical or logical disk and closing at completion. File operations do not require Open or Close operations as they do this internally. All test scripts log information to a log file of the same file name, but with a file name extension of .LOG. When lock status or device parameters are queried, the data is written to the DDTT's scroll output window and to the log file. Log files can be examined with a text editor after the test case has completed.
Disk sectors are addressed by cylinder, head, and sector. The maximum values for these parameters can be found with either GET_LOGICAL_PARAMS or GET_PHYSICAL_PARAMS.
DASDSTD1.SCR This script exercises all DASD physical API commands. It should be directed to a fixed disk not currently booted.
DASDSTD2.SCR This script exercises all DASD logical API commands. It should be directed to a logical drive on a fixed disk, preferably not the boot partition.
DASDERR1.SCR This script exercises the device driver's ability to detect errors related to invalid data and invalid command sequences for a physical disk. It requires a fixed disk target.
DASDERR2.SCR This script exercises the device driver's ability to detect errors related to invalid data and invalid command sequences for a logical disk. It requires a fixed disk target.
FLOPSTD.SCR This script exercises all DASD logical API commands for a removable media device. It should be directed to a floppy drive. This test script should be copied to the floppy media where it will serve as the test file.
FLOPFILE.SCR This script exercises file-oriented API commands for a removable media device. It should be directed to a floppy drive. This test script should be copied to the floppy media where it will serve as the test file.
FLOPERR.SCR This script exercises the device driver's ability to detect errors related to invalid handle and device-not-ready conditions. It requires a removable media target drive.
FLOPERR2.SCR This script exercises the device driver's ability to detect errors related to invalid data conditions. It requires a removable media target drive.
FLOPZIP.SCR This script exercises all DASD logical API commands for a removable media device. It should be directed to drives that use media larger than a standard floppy diskette.
===Evaluation of Test Case Results===
Standard (non-error) test cases are expected to succeed and there should be no ERROR statements in the logs. However, the Lock command may fail if the system has already locked the logical or physical drive. For this reason, it is suggested that if possible the target drive (logical or physical) be one that is defined but inactive.
Error test cases will have many ERROR statements but should have no failure statements. Failure statements indicate that an expected error code was not received.
Test case logs need to be examined to verify that data is returned as expected. Not all returned data is automatically checked. Script comments will note what data is expected.
==Optical IOCtl Device Driver Test Tool==
This chapter explains how to use the DDTT to test optical devices by executing removable DASD and optical-oriented test scripts.
===Overview===
Optical functional verification tests exercise the Application Program Interfaces (APIs) - mainly DosDevIOCtl variations - that interface with optical device drivers. The test environment is defined by the Device Driver Test Tool (DDTT) and each test is written as a DDTT script using Global and optical grammars. See Device Driver Test Tool (DDTT) for a description of the DDTT. The tests described herein give the user a repeatable set of scripts for verifying disk and diskette functions. They may also be used as examples for creating additional specialized test cases.
As the DDTT parses and executes each test script, it simultaneously creates a disk log file that timestamps the activity and logs each script command. If the command initiates an API call, then the result of the command is logged, be it failure with a return code or success with possible returned data. If the script fails to complete, the log, up to the point of failure, is available for diagnosis.
These tests can be used to verify correct interaction between the optical device and the following OS/2 components:
*DOSDevIOCtl API interface
*FAT file system
*OPTICAL.DMD, device manager
*SCSI Adapter device drivers
*Non-SCSI Adapter device drivers
Optical device support is currently limited to media that are blocked for 512 bytes (a file system limitation).
===Installation===
This CD-ROM contains the executables, libraries, grammars, and test cases necessary to run optical test suites.
The following procedure describes installation for running test cases:
#Copy the component files from the ''Device Driver Kit for OS/2'' CD-ROM to the hard drive. All files should reside in a common directory, such as \TOPTICAL. If the target directory is C:\TOPTICAL and the E: drive contains the information from the ''Device Driver Kit for OS/2'', then use the following commands to copy the optical test suite:<pre>
[C:\]md toptical
[C:\]cd toptical
[C:\toptical]copy e:\ddk\testcert\storage\function\dasd\*
[C:\toptical]copy e:\ddk\testcert\general\ddtt\*
</pre>
#Add C:\TOPTICAL to the LIBPATH and PATH in the CONFIG.SYS file.
#Reboot your machine so the new LIBPATH entry takes effect.
The following DDTT files are required for execution of optical scripts:
*DDTT.EXE
*DDTT.DLL
*GLOBAL.DLL
*GLOBAL.GRA
*DDTOPTI.DLL
*OPTI.GRA
===Test-Case Execution===
Test case scripts are driven by the DDTT. The DDTT can be initiated via an OS/2 command line or from a batch file or REXX statement:
[C:\TOPTICAL]DDTT OPTISTD.SCR
The DDTT creates a Presentation Manager thread window that consists of:
*a multi-line, scrolled output field for logging script progress
*a single-line entry field for operator input
*a single-line text output field for script-initiated prompts and messages
The DDTT optical tests must be executed on a directly-attached optical device. These tests will not work when executed against an optical device accessed by way of a network connection.
===Optical IOCtl Test Grammar Function Calls===
The following is a list of Optical IOCtl Test Grammar Function Calls:
*DASD_OPEN
*DASD_CLOSE
*LOCK_LOGICAL
*UNLOCK_LOGICAL
*QUERY_LOCK
*GET_LOGICAL_PARAMS
*BLOCK_REMOVABLE
*REDETERMINE_MEDIA
*READ_LOGICAL
*WRITE_LOGICAL
*VERIFY_LOGICAL
*FORMAT_TRACK
*BEGIN_FORMAT
*LOCK_DOOR
*UNLOCK_DOOR
*EJECT_MEDIA
*QUERY_SUPPORT
*SCSI_INQUIRY
*SCSI_MODE_SENSE
*READ_FILE
*WRITE_FILE
*SET_DEVICEPARAMS
*CHECKRETURN
*CHECKVALUE
====DASD_OPEN====
This function opens the optical device for processing. An optical cartridge must be mounted for successful completion.
;Input Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DEVICENAME
|STRING
|Drive letter for optical device
|}
;Output Parameter Keywords
{|class="wikitable"
!Keyword
!Type
!Description
|-
|DRIVEHANDLE
|NUM
|File handle for optical device
|}
;Logged Data
None.
====DASD_CLOSE====
This function closes the processing connection to the optical device.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
None.
;Logged Data
None.
====LOCK_LOGICAL====
Category 8h Function 00h - Lock Drive
This function logically locks the optical device for exclusive processing.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====UNLOCK_LOGICAL====
Category 8h Function 01h - Unlock Drive
This function releases a logical lock to the optical device.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====QUERY_LOCK====
Category 8h Function 66h - Get Lock Status
This function indicates if the drive is locked with or without media in it.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|PRESENCE            |NUM                |Media presence flag |
|--------------------+--------------------+--------------------|
|LOCKCODE            |NUM                |2-bit lock code    |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Lock status and Lock/Unlock/Eject command support statement
Media presence status
====GET_LOGICAL_PARAMS====
Category 8h Function 63h - Query Device Parameters
This function gets the logical parameters for the addressed drive. BIOS parameter block data may be a generic default for the optical drive.
;Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|CLUSTERSIZE        |NUM                |Cluster size in    |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|FATCOUNT            |NUM                |Number of FATs      |
|--------------------+--------------------+--------------------|
|ROOTCOUNT          |NUM                |Number of root      |
|                    |                    |directory entries  |
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors  |
|                    |                    |(small disk)        |
|--------------------+--------------------+--------------------|
|FATSIZE            |NUM                |Number of sectors  |
|                    |                    |per FAT            |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Size of tracks      |
|--------------------+--------------------+--------------------|
|HEADCOUNT          |NUM                |Number of heads    |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |Number of physical  |
|                    |                    |drive cylinders    |
|--------------------+--------------------+--------------------|
|HIDDEN              |NUM                |Number of hidden    |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|RESERVED            |NUM                |Number of reserved  |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|LGSECTORCOUNT      |NUM                |Number of sectors  |
|                    |                    |(large disk)        |
|--------------------+--------------------+--------------------|
|$SECTORCOUNT        |NUM                |Applicable sector  |
|                    |                    |count              |
|--------------------+--------------------+--------------------|
|DEVICETYPE          |NUM                |Device layout code  |
|--------------------+--------------------+--------------------|
|MEDIATYPE          |NUM                |Media descriptor    |
|--------------------+--------------------+--------------------|
|HARDDISK            |NUM                |Hard disk flag      |
|                    |                    |(1=yes)            |
|--------------------+--------------------+--------------------|
|ADDR16              |NUM                |16MB size flag      |
|                    |                    |(1=greater)        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
</pre>
;Logged Data (where defined)
:Size of sectors
:Size of clusters
:Fat count
:Root directory size
:Number of sectors per FAT
:Sectors per track
:Reserved sector count
:Hidden sector count
:Number of heads
:Total sector count
:Number of cylinders
:Media descriptor
:Device attributes
====BLOCK_REMOVABLE====
Category 8h Function 20h - Block Removable
This function is used to determine if the media is removable or fixed.
;Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
|--------------------+--------------------+--------------------|
|REMOVABLE          |NUM                |1 if true; 0 if    |
|                    |                    |false              |
</pre>
;Logged Data
Removable Media Returns a byte that specifies if the media is removable or not. Where:
:0 = Removable media
:1 = Nonremovable media
====REDETERMINE_MEDIA====
Category 8h Function 02h - Redetermine Media
This function redetermines the media for the optical device.
;Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
</pre>
;Logged Data
None.
====READ_LOGICAL====
Category 8h Function 64h - Read Track
This function reads sectors from an optical drive.
;Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The target head    |
|                    |                    |value (only 0 valid)|
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The target cylinder |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector value        |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors to|
|                    |                    |be read            |
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Buffer name        |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BUFFER              |NUM                |Pointer to Read    |
|                    |                    |buffer              |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
</pre>
;Logged Data
None.
====WRITE_LOGICAL====
Category 8h Function 44h - Write Track
This function writes sectors to an optical device. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer. The sector count is defaulted to the Read buffer size.
;Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The target head    |
|                    |                    |value (only 0 valid)|
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The target cylinder |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector value        |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Name of an existing |
|                    |                    |Read buffer        |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
</pre>
;Logged Data
None.
====VERIFY_LOGICAL====
Category 8h Function 65h - Verify Track
This function verifies sectors on an optical drive.
;Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
|--------------------+--------------------+--------------------|
|HEAD                |NUM                |The target head    |
|                    |                    |value (only 0 valid)|
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The target cylinder |
|                    |                    |value              |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |The target start    |
|                    |                    |sector              |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors to|
|                    |                    |verify              |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
</pre>
;Logged Data
None.
====FORMAT_TRACK====
Category 8h Function 45h - Format Track
This function formats and verifies a track.
;Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Track size in      |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|TRACKSTART          |NUM                |Starting track      |
|                    |                    |number              |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|LGSECTORCOUNT      |NUM                |Maximum number of  |
|                    |                    |media sectors      |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
</pre>
;Logged Data
None.
====BEGIN_FORMAT====
Category 8h Function 04h - Format Track
This function provides initialization for a format command.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====LOCK_DOOR====
Category 80h Function 40h - Lock/Unlock Door
This function locks the drive door.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====UNLOCK_DOOR====
Category 80h Function 40h - Lock/Unlock Door
This function unlocks the drive door.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====EJECT_MEDIA====
Category 80h Function 41h - Eject Media
This function ejects the cartridge from the drive. It should fail if the drive is locked.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====QUERY_SUPPORT====
Category 80h Function 60h - Query Drive Support
This function queries the optical drive support parameters.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
:Signature
:Release level
:ROM level
:Hardware level
:Format time
====SCSI_INQUIRY====
Category 80h Function 4Fh - Write Device Control String
This function constructs a SCSI Inquiry command for the optical device manager to relay to the SCSI device driver. The Device ID string will be returned to the DDTT. Support is limited to SCSI connections.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Device type Device product ID Device vendor ID
====SCSI_MODE_SENSE====
Category 80h Function 4Fh - Write Device Control String
This function constructs a SCSI Mode Sense command for the optical device manager to relay to the SCSI device driver. Mode type code will be returned to the DDTT. Support is limited to SCSI connections.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |File handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|MEDIACODE          |NUM                |Media type: 1=OROM, |
|                    |                    |3=MO, 5=PROM        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Media type
====READ_FILE====
This function reads from an optical drive file.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|FILENAME            |STRING              |The qualified name  |
|                    |                    |of the file to read |
|--------------------+--------------------+--------------------|
|BYTESTART          |NUM                |The byte offset    |
|                    |                    |within the file    |
|--------------------+--------------------+--------------------|
|BYTECOUNT          |NUM                |The number of bytes |
|                    |                    |to read            |
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Name of the Read    |
|                    |                    |buffer              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BUFFER              |NUM                |Read buffer        |
|                    |                    |reference          |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====WRITE_FILE====
This function writes to an optical file. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|FILENAME            |STRING              |The qualified name  |
|                    |                    |of the target file  |
|--------------------+--------------------+--------------------|
|BYTESTART          |NUM                |The byte offset    |
|                    |                    |within the file    |
|--------------------+--------------------+--------------------|
|$BUFFER            |STRING              |Name of the Read    |
|                    |                    |buffer              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====SET_DEVICEPARAMS====
Category 8h Function 43h - Set Device Parameters
This function sets the device parameters. Input parameters are most easily initialized by issuing a GET_LOGICAL_PARAMS.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |optical device being|
|                    |                    |tested              |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|CLUSTERSIZE        |NUM                |Cluster size in    |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|FATCOUNT            |NUM                |Number of FATs      |
|--------------------+--------------------+--------------------|
|ROOTCOUNT          |NUM                |Number of root      |
|                    |                    |directory entries  |
|--------------------+--------------------+--------------------|
|HIDDEN              |NUM                |Number of hidden    |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|RESERVED            |NUM                |Number of reserved  |
|                    |                    |sectors            |
|--------------------+--------------------+--------------------|
|LGSECTORCOUNT      |NUM                |Number of sectors  |
|                    |                    |(large disk)        |
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors  |
|                    |                    |(small disk)        |
|--------------------+--------------------+--------------------|
|FATSIZE            |NUM                |Number of sectors  |
|                    |                    |per FAT            |
|--------------------+--------------------+--------------------|
|TRACKSIZE          |NUM                |Size of the tracks  |
|                    |                    |on the specified    |
|                    |                    |device              |
|--------------------+--------------------+--------------------|
|HEADCOUNT          |NUM                |Number of heads on  |
|                    |                    |the physical disk  |
|--------------------+--------------------+--------------------|
|CYLINDER            |NUM                |The number of      |
|                    |                    |cylinders          |
|--------------------+--------------------+--------------------|
|MEDIATYPE          |NUM                |Media descriptor    |
|--------------------+--------------------+--------------------|
|DEVICETYPE          |NUM                |Device layout code  |
|--------------------+--------------------+--------------------|
|ADDR16              |NUM                |16MB size flag      |
|                    |                    |(1=greater)        |
|--------------------+--------------------+--------------------|
|HARDDISK            |NUM                |Hard disk flag      |
|                    |                    |(1=yes; 0=no)      |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|OPRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CHECKRETURN====
Check Return Code Diagnostic Function
This function verifies that the return code from a previous function is equal to a given value. The function is used for error testing to verify expected return codes. It is assumed that a previous function has set the OPRC parameter. $RC is set by the script author to the expected value.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|$RC                |NUM                |The expected return |
|                    |                    |code                |
\--------------------------------------------------------------/
</pre>
;Logged Data
:Message stating the result of the comparison - either failure or success.
====CHECKVALUE====
Check Parameter Value Diagnostic Function
This function verifies that a parameter, returned by a previous DASD function, is equal to a given numeric value. $PARM must be explicitly equated to the parameter being tested and $EXPECT set to the expected value.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|$PARM              |NUM                |The returned        |
|                    |                    |parameter value    |
|--------------------+--------------------+--------------------|
|$EXPECT            |NUM                |The expected value  |
\--------------------------------------------------------------/
</pre>
;Logged Data
Message stating the result of the comparison - either failure or success.
===Description of Test Cases===
Each of the optical test cases can be executed by invoking the DDTT from either a command line, a batch file, or a REXX file. Test scripts are described below. The user is free to create additional tests or construct multi-threaded test cases after becoming familiar with the DDTT and the optical grammar files.
Test scripts generally start by opening to the optical drive and closing at completion. File operations do not require Open or Close operations as they do this internally. All test scripts log information to a log file of the same file name, but with a file name extension of .LOG. When lock status or device parameters are queried, the data is written to the DDTT's scroll output window and to the log file. Log files can be examined with a text editor after the test case has completed.
Optical cartridge sectors are addressed by cylinder, head, and sector. Head value is currently defined only for a value of 0. The maximum value for the other parameters can be found with GET_LOGICAL_PARAMS.
Test scripts currently address drives configured as removable. If an optical drive is configured as non-removable, then the fixed-disk test suite would be appropriate.
;OPTISTD.SCR
:This script exercises all optical device related API commands, except those for file I/O. An optical cartridge supporting read and write must be mounted in the drive.
;OPTIFILE.SCR
:This script exercises optical device file read and write commands. An optical cartridge supporting read and write must be mounted in the drive. Since file I/O is supported, the cartridge must be formatted and this script must be copied to it in order to serve as a sample file.
;OPTIERR.SCR
:This script exercises the device driver's ability to detect errors related to invalid handle, device-not-ready, and invalid sequence conditions for an optical drive. It requires an optical cartridge to be mounted.
;OPTIERR2.SCR
:This script exercises the device driver's ability to detect errors related to invalid head/cylinder/sector values for an optical drive. It requires an optical cartridge to be mounted.
===Evaluation of Test Case Results===
Standard (non-error) test cases are expected to succeed and there should be no ERROR statements in the logs. SCSI Inquiry and Mode Sense commands will fail if the drive is not connected to a SCSI adapter.
Error test cases will have many ERROR statements but should have no failure statements. Failure statements indicate that an expected error code was not received.
Test case logs need to be examined to verify that data is returned as expected. Not all returned data is automatically checked. Script comments will note what data is expected.
==Using Filter Device Drivers==
There are a number of scenarios in which it is useful to insert one or more filtering algorithms between a device manager and the adapter device driver that is driving the device interface. This is accomplished under the adapter device driver model by installing one or more filter device drivers into the call-down path between the DM and the device-interfacing adapter device driver. Filter device drivers are also referred to as filter adapter device drivers, filter drivers, or simply filters.
A sample scenario that utilizes a filter device driver to encrypt the data maintained on a DASD unit is depicted in the following figure:
<pre>
      Without Filter                  With Filter
/------------------------\        /-------------------------\
|    System DASD DM    |        |  System DASD DM        |
|      (OS2DASD.DM)      |        |    (OS2DASD.DM)        |
\------------------------/        \-------------------------/
            �                                  �
            |                                  |
            |                                  �
            |                      /-------------------------\
            |                      | Encryption Algorithm    |
            |                      |  (A Filter Driver)      |
            |                      \-------------------------/
            |                                  �
            |                                  |
            �                                  �
/------------------------\        /-------------------------\
|ST-506 Interface Driver |        | ST-506 Interface Driver |
|    (IBM1S506.ADD)      |        |    (IBM1S506.ADD)      |
\------------------------/        \-------------------------/
</pre>
Filter algorithms are packaged as filter device driver drivers and, in general, they provide the same set of services as any other adapter device driver. Once initialized, filter device drivers receive IORBs from upstream drivers (for example, device managers), perform the filtering function on the data in the IORB, then pass the IORB to call down to the adapter device drivers that the filter device driver is controlling.
One or more filter device drivers can be inserted into the call-down path for a selected device.
One or more call-down paths can share the same filter device driver. For example, multiple call-down paths can share a filter device driver that is providing an encryption function.
The remainder of this chapter contains detailed information on how filter device drivers can be constructed and, subsequently, inserted into the device support for a given I/O system.
===Strategies for Providing Filter Functions===
There are two strategies for inserting a filter device driver into the call-down path for a given unit's device support:
#Edit the target unit's UNITINFO table, but do not allocate permanent ownership of the unit.
#Allocate the target unit, and present a new UNITINFO table to any upstream driver that might issue I/O requests.
In most cases, the first strategy, in which the caller does not permanently allocate the unit, is simpler than the second. The filter device driver simply daisy-chains a filter indicator into the UNITINFO structure of the target unit; then, I/O that otherwise would go directly to the target unit's adapter device driver is redirected through the filter device driver.
The second strategy is required when the filter device driver needs to hide units. For example, a data-stripping feature can be implemented using a filter device driver as follows. The data-stripping filter device driver must allocate all target units to hide them from upstream device managers. Then the data-stripping filter device driver constructs a new UNITINFO table to contain the appropriate information for presenting a logical view of a single, logical (stripped) drive.
===Installation and Initialization===
Filter device drivers are installed the same as adapter device drivers, using BASEDEV= statements in the CONFIG.SYS file of the workstation. In CONFIG.SYS, the filter device driver is loaded after any adapter device drivers it will control but before any device managers that the filter device driver will serve; this is ensured by use of the FLT file-name extension.
When the filter device driver receives its initialization packet from the kernel, it must scan the workstation's configuration to determine which units it wants to control, just as a device manager must when it initializes. A filter device driver uses the DevHlp_GetDOSVar to obtain a list of the entry points for all installed adapter device drivers, then it calls each ADD to obtain their device tables. The filter device driver must provide storage for these device tables.
Once the device tables are obtained, each is scanned by the filter device driver for units of interest. Having located the units of interest, the filter device driver must take one of the two actions previously listed, depending on whether the filter driver is using the permanent allocation method.
===Editing an Adapter Device Driver Device Table===
If the filter device driver does not need to hide the downstream units, it can initiate filtering operations by the following steps.
#Change the value of the FilterADDHandle field in the target unit's UNITINFO structure so that the field selects the filter device driver.<br />When no filter device drivers are installed, the FilterADDHandle value will be 0. So, when a device manager (or other upstream adapter device driver) finds a 0 value in this field, the referenced adapter device driver is directly managing the device interface.
#Change the UnitHandle field of the target unit's UNITINFO structure to a value assigned by the filter device driver.
Notice that the filter device driver is daisy-chaining itself into the call-down path for a given unit. As a result, the filter device driver must save the existing values in FilterADDHandle (if nonzero) and UnitHandle for the downstream driver. After the filter device driver processes a service request, it must pass the request to the downstream filter device driver or device-interface adapter driver.
The following protocol must be adhered to when editing a UNITINFO structure of another adapter device driver.
The filter device driver alters the information provided in the target UNITINFO structure by using the (IOCC_UNIT_CONTROL) IOCM_CHANGE_UNITINFO command. To issue IOCM_CHANGE_UNITINFO, the filter device driver first must allocate the unit, change the UNITINFO information, and then deallocate the unit.
Changing the UNITINFO information does not affect the operation of the downstream adapter device driver. For example, if a filter device driver changes the UF_HW_SCATGAT bit, the downstream device driver's treatment of the unit is not affected. However, the downstream adapter device driver must present the changed UNITINFO structure when its DEVICETABLE is requested. It is the responsibility of the filter device driver to convert the changed unit definition it sets to the actual unit definition of the adapter device driver owning the unit.
A filter device driver can modify a unit's flags without actually ''hooking'' the unit. For example a filter device driver could UF_set the A_DRIVE flag without actually receiving requests by leaving the original ''UnitHandle'' and ''FilterADDHandle'' fields intact.
===Allocating Permanent Ownership of a Unit===
Alternatively, a filter device driver can allocate permanent ownership of the target unit from the downstream driver and present a device table containing the new representation of the unit to any upstream drivers. Since the filter device driver retains ownership of the downstream resource, it is not necessary to edit to the downstream driver's UNITINFO structures.
===IORBs and Filtering===
Once installed, a filter device driver can apply the following to the IORBs it is filtering:
*Generally, the filter device driver will retain the original IORB and create new IORBs to pass on to the downstream drivers.
*However, a filter device driver can modify an IORB it receives and pass on the same copy of the IORB data structure (as opposed to passing on a local copy of the IORB). If the adapter device driver does this, it must alter the notification address and restore any input fields it had modified prior to doing notification callouts back to the upstream driver.
The filter device driver must not assume that the contents of the ''pIORB->ADDWorkSpace'' field will be preserved by a downstream driver.
==Library and Services==
A complement of library services for common adapter device driver tasks is provided in the ''IBM Device Driver Source Kit for OS/2''. This adapter device driver library includes a set of functions that can be statically linked with an adapter device driver at build time.
These library services are provided in both source and object form. This code is in the \addcalls and \devhelp subdirectories of the \src tree. You can modify and extend this code to suit your needs.
The ''DevHlp'' services are provided with FAR code and data-calling convention support. ''Adapter Device Driver Calls'' services are generally provided with both FAR and NEAR calling-convention support.
The library services include the following:
*'C' interface to the DevHlp kernel services
*Timer services
*Scatter/gather buffer transfers
*RBA <-> CHS computations
*DMA setup and channel control, ISA bus machines
*Command line parsing
See the headers of the individual functions for a detailed description of function services and their calling conventions.
'''Command-Line Parsing'''
To facilitate parsing of command-line parameters and to help encourage uniformity in command-line syntax, a parser/tokenizer is provided in the ''IBM Device Driver Source Kit for OS/2''. See [[Adapter Device Driver Command-Line Parameters]] for a command-line syntax definition.
The output of the parser/tokenizer is a stream of tokens that represent the contents of the command line. The parser/tokenizer performs preliminary syntactical checks on the command line and indicates the results of these checks in return codes.
As with the other library services provided in the ''IBM Device Driver Source Kit for OS/2'', you can modify the parser and its included tables to add adapter-unique flags and parameters.
==CD-ROM Device Manager Interface Specification==
This chapter contains a description of:
*CD-ROM device management
*SCSI and Non-SCSI adapter drivers
*Command support
The following figure illustrates the layered CD-ROM Device Management structure in the OS/2 operating system.
<pre>
/--------------------------------------------------------\
|                CD-ROM Device Manager                  |
|                  (OS/2 CDROM.DMD)                    |
\--------------------------------------------------------/
                  �  SCSI-2 Commands          �
                  |                            �
                  |                    /-----------------\
                  |                    | SCSI-2 Emulator |
                  |                    | Filter          |
                  �                    \-----------------/
          /------------------------\    �  Vendor Unique
          �                        �    �  SCSI-1 Commands
/----------------------\      /-----------------------\
|Non-SCSI CD-ROM      |      | SCSI Bus              |
|Adapter Device Driver |      | Adapter Device Driver |
\----------------------/      \-----------------------/
          �                                �
  Non-SCSI CD-ROM                SCSI Adapter
  Adapter  |                                |
          �                                �
  CD-ROM Drive                    CD-ROM Drive
</pre>
===The CD-ROM Device Manager===
The OS/2 CD-ROM Device Manager (OS2CDROM.DMD) is a generic CD-ROM device driver for CD-ROM drives that comply with the ANSI SCSI-2 standard X3T9.2/ 86-109 (SCSI-2 draft proposed American National Standard Revision 10g). The device driver provides generic data and audio support for drives that support the command set specified in that standard. Vendor unique CD-ROM XA support and multi-session support is provided for selected drive models.
The CD-ROM Device Manager provides a uniform interface between its clients and adapter device drivers. Clients of the Device Manager include:
*CD-ROM Installable File System (CDFS.IFS)
*Multimedia Presentation Manager/2* subsystem
*virtual CD-ROM device driver (VCDROM.SYS)
*OS/2 applications
The CD-ROM File System communicates with the CD-ROM Device Manager using the request packet interface defined in the OS/2 Physical Device Driver Reference version 2.00 or later.
The Multimedia Presentation Manager/2 subsystem and OS/2 applications communicate with the CD-ROM Device Manager using the Category 80 and 81 IOCtl services defined in the ''OS/2 Physical Device Driver Reference''.
DOS applications communicate with the CD-ROM Device Manager indirectly through the virtual DOS CD-ROM device driver VCDROM.SYS. VCDROM.SYS provides virtual support and converts the DOS application request into a file system or Cat 80/81 IOCTL request which is routed to the CD-ROM Device Manager using system device helper services.
The interface between the CD-ROM Device Manager and adapter device drivers adheres to the adapter device driver interface defined in earlier chapters of this reference. The CD-ROM Device Manager converts a request from its client into a SCSI-2 command descriptor block and routes the SCSI-2 command to the specified adapter device driver. The SCSI-2 commands are sent using the IORB adapter passthru command (command code = ADAPTER_PASSTHRU, command modifier = EXECUTE_CDB).
The CD-ROM Device Manager driver (OS2CDROM.DMD) is an installable block device driver and is loaded using a ''DEVICE='' statement in CONFIG.SYS. The driver replaces CDROM.SYS, the CD-ROM device driver shipped in the OS/2 2.1 product.
===SCSI-2 Emulation Filters===
SCSI CD-ROM target devices with vendor unique commands not supported in the SCSI-2 standard require a SCSI-2 ''emulation filter''. The emulation filter maps SCSI-2 commands received from the CD-ROM Device Manager to the vendor unique commands supported by the target device. This support is required to enable audio support on CD-ROM drives that adhere to the SCSI-1 standard. The SCSI-1 standard does not define a standard command set for audio control.
A SCSI-2 emulation filter is required for each vendor unique CD-ROM drive. Typically, a CD-ROM manufacturer uses the same vendor unique command set for all it's CD-ROM drives, therefore, one filter driver is required for each manufacturer.
The filter driver receives SCSI-2 commands from the CD-ROM Device Manager, converts the command to it's vendor unique equivalent, and routes the filtered command to the SCSI adapter device driver. If data returned with the command needs to be filtered, the filter driver regains control when the request is complete, converts the outgoing data to it's SCSI-2 equivalent, and then returns to the CD-ROM Device Manager. The filtering process is transparent to the Device Manager and to the adapter device drivers.
Filter drivers adhere to the adapter device driver interface previously defined. (See [[DASD, SCSI, and CD-ROM Device Manager Interface Specification]].) The filter driver is loaded using the BASEDEV= statement in CONFIG.SYS.
===SCSI Adapter Device Drivers===
A SCSI adapter device driver complies with the adapter device driver interface defined in DASD, SCSI, and CD-ROM Device Manager Interface Specification. It must support the ADAPTER_PASSTHRU command for EXECUTE_CDB requests. SCSI-2 commands are sent from the CD-ROM Device Manager using this command. SCSI sense data must be returned when requested.
===Non-SCSI CD-ROM Adapter Device Drivers===
Several leading CD-ROM drive manufacturers use a proprietary, non-SCSI, host adapter interface for the CD-ROM drive. To support a non-SCSI CD-ROM drive, an adapter device driver is required that emulates a SCSI-2 target device. This enables the CD-ROM Device Manager to issue a common command set to it's target devices, whether or not the firmware on the target device directly supports the SCSI-2 command set.
A non-SCSI CD-ROM adapter device driver adheres to the adapter device driver interface defined in DASD, SCSI, and CD-ROM Device Manager Interface Specification. It must support the ADAPTER_PASSTHRU command for EXECUTE_CDB requests, The SCSI-2 commands are sent from the CD-ROM Device Manager using this command.
The SCSI-2 commands must be emulated by the adapter device driver. This includes sense data which is returned back to the CD-ROM Device Manager.
===Non-SCSI CD-ROM Adapter Device Driver Specification===
A non-SCSI CD-ROM adapter device driver adheres to the adapter device driver interface defined in DASD, SCSI, and CD-ROM Device Manager Interface Specification. Most commands are received as SCSI-2 command descriptor blocks sent using the IORB ADAPTER_PASSTHRU command. The SCSI command descriptor blocks comply with the ANSI SCSI-2 standard X3T9.2/86-109 (SCSI- 2 draft proposed American National Standard Revision 10g).
The following sections describe the mandatory IORB and SCSI-2 commands that a non-SCSI CD-ROM adapter device driver must support. The command structures for the IORB command blocks are defined in IORB Control Blocks.
The C Language definitions for the IORB control blocks are included in I/O Request Block - C Definitions.
===Mandatory IORB Command Support===
The Adapter Device Driver must support the IORB command set defined in the table below.
<pre>
/-------------------------------------------------------------\
|Command Code                  |Command Modifier              |
|------------------------------+------------------------------|
|IOCC_CONFIGURATION            |IOCM_GET_DEVICE_TABLE        |
|------------------------------+------------------------------|
|IOCC_UNIT_CONTROL            |IOCM_ALLOCATE_UNIT            |
|                              |IOCM_DEALLOCATE_UNIT          |
|                              |IOCM_CHANGE_UNITINFO          |
|------------------------------+------------------------------|
|IOCC_GEOMETRY                |IOCM_GET_MEDIA_GEOMETRY      |
|                              |IOCM_GET_DEVICE_GEOMETRY      |
|------------------------------+------------------------------|
|IOCC_EXECUTE_IO              |IOCM_READ                    |
|------------------------------+------------------------------|
|IOCC_UNIT_STATUS              |IOCM_GET_UNIT_STATUS          |
|                              |IOCM_GET_LOCK_STATUS          |
|------------------------------+------------------------------|
|IOCC_DEVICE_CONTROL          |IOCM_ABORT IOCM_RESET        |
|                              |IOCM_LOCK_MEDIA              |
|                              |IOCM_UNLOCK_MEDIA            |
|                              |IOCM_EJECT_MEDIA              |
|------------------------------+------------------------------|
|IOCC_ADAPTER_PASSTHRU        |IOCM_EXECUTE_CDB              |
\-------------------------------------------------------------/
</pre>
;IOCC_CONFIGURATION
For the IOCM_GET_DEVICE_TABLE command, the following information must be returned in the device table.
*The Adapter-to-Device protocol in the AdapterDevBus field of the ADAPTERINFO structure must be set to AI_DEVBUS_NONSCSI_CDROM.
*The UnitType field in the UNITINFO structure must be set to UIB_TYPE_CDROM
*The UF_REMOVABLE bit must be set in the UnitFlags field of the UNITINFO structure. The UF_NODASD_SUPT and UF_NOSCSI_SUPT bits should be set to zero.
The adapter device driver should return all other fields in the device table as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification.
;IOCC_UNIT_CONTROL
The IOCM_ALLOCATE_UNIT, IOCM_DEALLOCATE_UNIT and IOCM_CHANGE_UNITINFO must be supported as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification.
;IOCC_GEOMETRY
The geometry returned must be the same for both the IOCM_GET_MEDIA_GEOMETRY and the IOCM_GET_DEVICE_GEOMETRY commands. For both commands, only the TotalSectors and the BytesPerSector fields should be set. The TotalSectors field should be equal to the last addressable logical block address on the media + 1. This value should correspond to the value returned in the SCSI- 2 Read Capacity command + 1, which is the starting address of the lead out area. The BytesPerSector field should be set to 2048. TheNumHeads, TotalCylinders and SectorsPerTrack fields should be set to 0.
If there is no media present in the drive, the driver should return IOERR_ UNIT_NOT_READY.
;IOCC_EXECUTE_IO
The adapter device driver must support the IOCM_READ command as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification.
;IOCC_UNIT_STATUS
The adapter device driver must support the IOCM_GET_UNIT_STATUS and IOCM_ GET_LOCK_STATUS commands as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification.
;IOCC_DEVICE_CONTROL
The adapter device driver must support the IOCM_ABORT, IOCM_RESET, IOCM_ LOCK_MEDIA, IOCM_UNLOCK_MEDIA and IOCM_EJECT_MEDIA commands as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification.
;IOCC_ADAPTER_PASSTHRU
The adapter device driver must support the IOCM_EXECUTE_CDB command. The list of mandatory SCSI-2 command descriptor blocks which must be supported via this command is defined in the following section.
===Mandatory SCSI-2 Command Support===
The following table lists the SCSI-2 commands which must be supported. The command structure for the SCSI-2 command descriptor blocks are defined in the ANSI SCSI-2 standard X3T9.2/86-109 (SCSI-2 draft proposed American National Standard Revision 10g). Developers should refer to the ANSI SCSI-2 specification for a definition of each command. Usage notes for each command, as it relates to implementation under the OS/2 operating system, are included in the following sections.
'''Note:''' The Mode Select and Mode Sense commands need only support the Block Descriptor and the Audio Control Page (Page 0E).
;TEST UNIT READY (00h)
The TEST UNIT READY command provides a means to check if the logical unit is ready. Refer to the ANSI SCSI-2 specification for a detailed description of this command.
;REQUEST SENSE (03h)
The REQUEST SENSE command requests that the target transfer sense data to the initiator.
The Adapter Device Driver should return 18 bytes of sense data, as shown in the following table.
<pre>
/--------------------------------------------------------------\
| Bit  |  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
| Byte |      |      |      |      |      |      |      |      |
|------+------+------------------------------------------------|
|  0  | Valid|                Error Code (70h)                |
|------+-------------------------------------------------------|
|  1  |                        Reserved                      |
|------+-------------------------------------------------------|
|  2  |        Reserved          |        Reserved          |
|------+-------------------------------------------------------|
|  3  | (MSB)                                                |
| ---  |                      Information                      |
|  6  | (LSB)                                                |
|------+-------------------------------------------------------|
|  7  |            Additional Sense Length (0Ah)            |
|------+-------------------------------------------------------|
|8-11  |                        Reserved                      |
|------+-------------------------------------------------------|
| 12  |                  Additional Sense Code                |
|------+-------------------------------------------------------|
| 13  |            Additional Sense Code Qualifier          |
|------+-------------------------------------------------------|
| 14  |                        Reserved                      |
|------+-------------------------------------------------------|
|15-17 |                        Reserved                      |
\--------------------------------------------------------------/
</pre>
*A valid bit of zero indicates that the Information Bytes field is not defined
*A valid bit if one indicates the Information Bytes field contains valid information
Setting this bit is optional. If set, the Information Byte field must contain the logical block address associated with the command in error.
The Sense Key, Additional Sense Code and Additional Sense Code Qualifier represent the error condition and must be returned.
All other sense data fields are unused and should be set to 0.
Refer to the ANSI SCSI-2 specification for a detailed description of this command and the complete list of sense key definitions. See I/O Request Block - C Definitions for a discussion on error processing and the mapping of sense data to IORB error codes.
;READ (08h) and READ (028h)
The READ (6-byte) and READ (10-byte) commands request that the target transfer data to the initiator.
The Adapter Device Driver should return with a sense key error of 08h (Blank Check) and additional sense code of 064h (illegal mode for this track) if any of the following events occur.
#If the requested logical block address is in an audio track and the drive does not support reading raw 2352 byte CD-DA data.
#If the requested logical block address is a mode 2 sector and the drive does not support reading mode 2 sectors.
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
Reading Mode-2 Sectors
If the CD-ROM drive supports the reading of Mode 2 Form 1 and Mode 2 Form 2 sectors, the Adapter Device Driver should mask the complexity of reading the target sector and return successfully, even if the mode of the target sector does not match the currently specified mode for the drive.
Some drives require the drive be set to the proper mode of the target sector prior to issuing the read. For those drives, the Adapter Device Driver should issue the original read, and if the read fails with an error indicating the current drive mode does not match the mode of the target sector, the adapter device driver must issue the mode select to set the proper mode and then re-issue the read request.
It is the responsibility of the CD-ROM Device Manager to ensure the proper block length is specified via the Mode Select command prior to issuing the read command. So, for Mode 2 Form 1 sectors, the device manager will issue a Mode Select command to set the block length to 2048 bytes. For a Mode 2 Form 2 sector, the device manager will issue a Mode Select to set the block length to 2340 or 2352 bytes, depending on the max block length the drive supports. See the Mode Select command section MODE SELECT (15h).
;SEEK (0Bh) and Seek (2Bh)
The SEEK (6 byte) and SEEK (10 byte) commands request that the logical unit seek to the specified logical block address.
The adapter device driver must complete the seek operation successfully even if the target sector is an audio sector. If a seek command to an audio sector is not supported by the drive, the driver should issue an alternative command which can successfully seek to the audio sector.
;INQUIRY (12h)
The INQUIRY command requests that information regarding parameters of the target and its attached peripheral devices(s) be sent to the initiator.
The standard inquiry data contains 36 required bytes and should be returned as shown in the following table.
<pre>
/--------------------------------------------------------------\
| Bit  |  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
| Byte |      |      |      |      |      |      |      |      |
|------+--------------------+----------------------------------|
|  0  |  Peripheral Qual.  |  Peripheral Device Type (05h)  |
|      |      (00h)        |                                  |
|------+-------------------------------------------------------|
|  1  |  RMB |          Device Type Modifier (00h)          |
|      |  (1) |                                                |
|------+-------------------------------------------------------|
|  2  | ISO Version | ECMA Version (00h)  ANSI Version (02h) |
|      |    (00h)    |                                        |
|------+-------------------------------------------------------|
|  3  |          Reserved        |Response Data Format (02h) |
|------+-------------------------------------------------------|
|  4  |                Additional Length (1Fh)                |
|------+-------------------------------------------------------|
|  5  |                      Reserved                        |
|------+-------------------------------------------------------|
|  6  |                      Reserved                        |
|------+-------------------------------------------------------|
|  7  |                      Reserved                        |
|------+-------------------------------------------------------|
|  8  |(MSB)                                                  |
| ---  |                Vendor Identification                  |
| 15  |(LSB)                                                  |
|------+-------------------------------------------------------|
| 16  |(MSB)                                                  |
| ---  |                Product Identification                |
| 31  |(LSB)                                                  |
|------+-------------------------------------------------------|
| 32  |(MSB)                                                  |
| ---  |                Product Revision Level                |
| 35  |(LSB)                                                  |
\--------------------------------------------------------------/
</pre>
*The Peripheral Qualifier is set to 00h.
*The Peripheral Device Type is set to 05h (CD-ROM device).
*The Removable Medium (RMB) bit is set to 1 to indicate the media is removable.
*The Device Type Modifier is set to 00h.
*The ISO version is set to 00h.
*The ECMA version is set to 00h.
*The ANSI-Approved Version field is set to 02h, indicating this driver adheres to the SCSI-2 specification.
*The Response Data Format field is set to 02h to indicate compatibility with the SCSI-2 standard.
The Vendor Identification field contains eight bytes of ASCII data identifying the vendor of the product. For example:
<pre>
Byte    08  09  10  11  12  13  14  15
ASCII    S    O    N    Y    sp  sp  sp  sp
Code    53h  4Fh  4Eh  59h  20h  20h  20h  20h
</pre>
The Product Identification field contains sixteen bytes of ASCII data identifying the product model. For example:
<pre>
Byte    16  17  18  19  20  21  22  23  24  25  26  27  28  29  30  31
ASCII    C  D  -  R  O  M  sp  C  D  U  5  6  1  sp  sp  sp
Code    43h 44h 2Dh 52h 4Fh 4Dh 20h 43h 44h 55h 35h 36h 31h 20h 20h 20h
</pre>
The Product Revision Level field contains four bytes of ASCII data which indicates the revision level of the controller firmware. For example:
<pre>
Byte    32  33  34  35
ASCII    1    .    0    0
Code    31h  2Eh  30h  30h
</pre>
;MODE SELECT (15h)
The Adapter Device Driver must support the Mode Select command for the Mode Parameter Block Descriptor and the Audio Control Parameters Page (0x0E).
The mode parameter list contains a header, followed by zero or more block descriptors, followed by zero or more variable-length pages.
Mode Select Parameter List
The following table describes the mode select header.
<pre>
/--------------------------------------------------------------\
| Bit  |  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
| Byte |      |      |      |      |      |      |      |      |
|------+------+------------------------------------------------|
|  0  |Resv. |                                                |
|------+-------------------------------------------------------|
|  1  |                  Medium Type (00h)                  |
|------+-------------------------------------------------------|
|  2  |                      Reserved                        |
|------+-------------------------------------------------------|
|  3  |          Block Descriptor Length (00h or 08h)        |
\--------------------------------------------------------------/
</pre>
The following table describes the mode select block descriptor.
<pre>
/--------------------------------------------------------------\
| Bit  |  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
| Byte |      |      |      |      |      |      |      |      |
|------+-------------------------------------------------------|
|  0  |                    Density Code                      |
|------+-------------------------------------------------------|
|  1  | (MSB)                                                |
| ---  |                Number of Blocks (00h)                |
|  3  | (LSB)                                                |
|------+-------------------------------------------------------|
|  4  |                      Reserved                        |
|------+-------------------------------------------------------|
|  5  | (MSB)                                                |
| ---  |                    Block Length                      |
|  7  |                                                      |
\--------------------------------------------------------------/
</pre>
*The medium type is set to 00h.
*The block descriptor length is set to either 00h or 08h.
*The density code is set to 00h.
*The number of blocks field is set to 00h. This indicates the entire disc has the block length specified.
*The block length specifies the length in bytes of each logical block.
===Block Length Support===
The CD-ROM Device Manager will initialize the block length to 2048 bytes per sector. When the Device Manager receives a Readlong IOCtl request (Category 80h, Function 72h), it will issue a Mode Select to change the block length to either 2340 or 2352 bytes, depending on the maximum block length the drive supports. The CD-ROM Device Manager will only issue the Mode Select command to change the block length if the current block length does not match the requested block length.
Prior to the first Read Long IOCtl command, the CD-ROM Device Manager will issue a set of Mode Select commands with various block length values to determine the maximum block length the drive supports. If the Adapter Device Driver receives a Mode Select command with a Block Length value which is not supported, it should return an error with a Sense Key of 05h (Illegal Request) and the Additional Sense Code set to 26h (Invalid field in parameter list).
If the drive can only read a maximum of 2340 bytes per sector, the CD-ROM Device Manager will append 12 bytes of zeros (where the sync bytes are normally placed) to each sector after the read completes. This will ensure a complete 2352 byte sector is always returned back to the application when a ReadLong IOCtl command is issued.
===Audio Control Parameter Page===
The audio control parameters page sets the playback modes and output controls for subsequent PLAY AUDIO commands and any current audio playback operation. (See the table below.)
{|class="wikitable"
!Bit<br>Byte||style="width:10%"|7||style="width:10%"|6||style="width:10%"|5||style="width:10%"|4||style="width:10%"|3||style="width:10%"|2||style="width:10%"|1||style="width:10%"|0
|-
|0||colspan=2|Reserved||colspan=6|Page Code (0Eh)
|-
|1||colspan=8|Parameter Length (0Eh)
|-
|2||colspan=5|Reserved||Immed (1)||colspan=2|Reserved
|-
|3-7||colspan=8|Reserved
|-
|8||colspan=4|Reserved||colspan=4|Output Port 0 Channel Selection
|-
|9||colspan=8|Output Port 0 Volume
|-
|10||colspan=4|Reserved||colspan=4|Output Port 1 Channel Selection
|-
|11||colspan=8|Output Port 1 Volume
|-
|12||colspan=4|Reserved||colspan=4|Output Port 2 Channel Selection (0)
|-
|13||colspan=8|Output Port 2 Volume (0)
|-
|14||colspan=4|Reserved||colspan=4|Output Port 3 Channel Selection (0)
|-
|15||colspan=8|Output Port 3 Volume (0)
|}
The immediate bit (Immed) is set to 1 to indicate the target shall send completion status as soon as the playback operation has been started.
The Output Port channel selection specifies the audio channels from the disc to which this output port should be connected, as shown in the table below.
<pre>
/-------------------------------------------------------------\
|Channel        |Function                                    |
|Selection      |                                            |
|---------------+---------------------------------------------|
|00h            |Output port muted.                          |
|---------------+---------------------------------------------|
|01h            |Connect audio channel 0 (left) to this output|
|              |port                                        |
|---------------+---------------------------------------------|
|02h            |Connect audio channel 1 (right) to this      |
|              |output port                                  |
|---------------+---------------------------------------------|
|03h            |Connect audio channel 0 and 1 to this output |
|              |port                                        |
|---------------+---------------------------------------------|
|04h-0Fh        |Not supported                                |
\-------------------------------------------------------------/
</pre>
The channel volume control indicates the relative volume level for this audio output port. Values between 0x00 and 0xFF and allowed. A volume level of zero indicates the output is muted, a value of 0xFF indicates maximum volume level.
The Output Port 2 and Output Port 3 channel selection and volume fields ( bytes 12 to 15) are reserved and are set to 0.
===Audio Control Determination===
At initialization time, the CD-ROM Device Manager will issue a series of Mode Select commands with various Audio Control Parameter Pages. The Output Port Channel Select and Volume Level fields will be varied to determine the audio control capabilities of the drive. For example, an Audio Control Parameter Page is sent with volume levels different for Channel 0 and Channel 1 to determine if the drive supports independent volume levels for each channel.
If the Adapter Device Driver receives a Mode Select command with an Audio Control Parameter Page which is not supported by the drive, it should return an error with a Sense Key of 05h (Illegal Request) and the Additional Sense Code set to 26h (Invalid field in parameter list). This allows the CD-ROM Device Manager to determine the audio capabilities of the drive.
MODE SENSE Command (1Ah)
The MODE SENSE (6) command provides a means for a target to report parameters to the initiator. It is a complementary command to the MODE SELECT (6) command. Refer to the ANSI SCSI-2 specification for a detailed description of this command.
START/STOP UNIT Command (1Bh)
The START/STOP UNIT command requests the target enable or disable the logical unit for media access operations. This command is used to eject media from the drive.
If a PREVENT MEDIUM REMOVAL command has been issued, a request to the disc should return with the sense key set to ILLEGAL REQUEST (O5h) and the additional sense code set to MEDIUM REMOVAL PREVENT (53h).
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
PREVENT/ALLOW MEDIUM REMOVAL (1Eh)
The PREVENT/ALLOW MEDIUM REMOVAL command requests that the target enable or disable the removal of the medium in the logical unit.
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
READ CD-ROM CAPACITY (25h)
The READ CD-ROM CAPACITY command provides a means for the initiator to request information regarding the capacity of the logical unit. The capacity is based on the starting address of the lead-out area minus one. The logical block address returned is the address of the last user accessible block on the disc.
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
READ SUB-CHANNEL (42h)
The READ SUB-CHANNEL command requests that the target return the requested sub-channel data plus the state of audio play operations.
Note: If a READ SUB CHANNEL command is issued to request the media catalog number (UPC/EAN Bar Coding), the drive should return the UPC code in ASCII format as specified in the SCSI-2 specification. Some drives return the UPC code in BCD. It should be converted to ASCII prior to returning. All other sub-channel data is returned in binary format.
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
READ TOC (43h)
The READ TOC command requests that the target transfer data from the table of contents to the initiator.
For drives which do not support a READ TOC command while an audio play operation is in progress, the adapter device driver should buffer the entire TOC data when media is first mounted in the drive. This will ensure the TOC data is retrievable during an audio play operation.
All TOC data is returned in binary format.
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
READ HEADER (44h)
The READ HEADER command requests that the device return the CD-ROM data block address header of the requested logical block.
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
PLAY AUDIO (10) (45h)
The PLAY AUDIO command requests the target to begin an audio playback operation.
The relative address bit (RelAdr) is not used and will be set to 0.
If the requested starting address is not in an audio track, the Adapter Device Driver should return with a sense key error of 08h (Blank Check) and additional sense code of 064h (illegal mode for this track).
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
PLAY AUDIO MSF (47h)
The PLAY AUDIO MSF command requests the target to begin an audio playback operation.
As specified in the SCSI-2 specification, the starting MSF address and ending MSF address fields are specified in hexadecimal (not in BCD).
If the requested starting address is not in an audio track, the Adapter Device Driver should return with a sense key error of 08h (Blank Check) and additional sense code of 064h (illegal mode for this track).
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
PAUSE/RESUME (4Bh)
The PAUSE RESUME command requests that the device stop or start an audio play operation.
It shall not be considered an error to request a pause when a pause is already in effect or to request a resume when a play operation is in progress.
Refer to the ANSI SCSI-2 specification for a detailed description of this command.
READ DISC INFORMATION (F0h)
<pre>
/--------------------------------------------------------------\
| Bit  |  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
| Byte |      |      |      |      |      |      |      |      |
|------+-------------------------------------------------------|
|  0  |                  Operation Code (F0h)                |
|------+-------------------------------------------------------|
|  1  |                Reserved                |    Type    |
|------+-------------------------------------------------------|
| 2-9  |                      Reserved                        |
\--------------------------------------------------------------/
</pre>
The READ DISC INFORMATION command is a vendor unique command to request information regarding capabilities of the target device. The command is also used to return the starting address of the last session for a multisession photo CD disc.
TYPE = 00b
If the TYPE field in the command descriptor block is 00h, the adapter device driver should return the data shown in the following table:
<pre>
/--------------------------------------------------------------\
| Bit  |  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
| Byte |    |      |      |      |      |      |      |      |
|------+--------------------------+------+------+------+-------|
|  0  |        Reserved          | CDDA | Form2| Form1|PhotoCD|
|------+-------------------------------------------------------|
|  1  |                      Reserved                        |
|------+-------------------------------------------------------|
|  2  | (MSB)                                                |
| ---  |                Maximum Block Length                  |
|  3  | (LSB)                                                |
\--------------------------------------------------------------/
</pre>
*A multisession photo CD (PhotoCD) bit set to 1 indicates the drive supports the reading of multi-session photo CD discs. *A Mode 2 Form 1 (Form1) bit set to 1 indicates the drive supports the reading of Mode 2 Form 1 sectors. *A Mode 2 Form 2 (Form2) bit set to 1 indicates the drive supports the reading of Mode 2 Form 2 sectors. *A CD-Digital Audio (CDDA) set to 1 indicates the drive supports reading 2352 byte raw CD-DA data.
The Maximum Block Length field specifies the maximum block length that can be transferred by the drive during a read operation. The value should match the maximum value which can be specified in the Block Length field of the Block Descriptor during a Mode Select command.
TYPE = 01b
If the TYPE field in the command descriptor block is 01h, the adapter device driver should return the data shown in the following table:
<pre>
/--------------------------------------------------------------\
| Bit  |  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
| Byte |      |      |      |      |      |      |      |      |
|------+-------------------------------------------------------|
|  0  |                        Reserved                      |
|------+-------------------------------------------------------|
|  1  |          Address of Last Session (Minutes)          |
|------+-------------------------------------------------------|
|  2  |          Address of Last Session (Seconds)          |
|------+-------------------------------------------------------|
|  3  |            Address of Last Session (Frame)            |
\--------------------------------------------------------------/
</pre>
If the installed media is a multi-session photo CD disc, the driver should return the absolute address of the last session. The data is returned in MSF format and is expressed in hexadecimal. If the installed media is not a multi-session photo CD disc, the driver must return zero for all fields in the returned control block.
===Multi-Session Photo CD Support===
At initialization time, the CD-ROM Device Manager will issue the READ DISC INFORMATION command with TYPE code = 00h to determine if the drive supports the reading of multi-session photo CD discs. If the drive indicates it supports the reading of multi-session photo CD discs (by returning with the PhotoCD bit set in the returned READ DISC INFORMATION data block) the CD- ROM Device Manager will issue the READ DISC INFORMATION command with TYPE code = 01h whenever media is first mounted in the drive.
If the adapter device driver indicates that a multi-session disc is mounted, the CD-ROM Device Manager will use the returned last session address to map subsequent read requests for Volume Descriptor sectors to the Volume Descriptor sectors in the last session on the disc. With this implementation, the responsibility of mapping sectors is done by the CD-ROM Device Manager and not by each adapter device driver.
===Error Processing===
When a request is issued, the CD-ROM Device Manager will set the IORB_REQ_STATUSBLOCK bit in the RequestControl field of the IORB header. If this bit is set and an error occurs, the Adapter Device Driver must return a valid status block and a valid sense data block back to the Device Manager when the request completes.
The status block is pointed to by the pStatusBlock field in the IORB header. It should be noted that pStatusBlock is a 16 bit near pointer, so the block is within the same segment as the IORB. The sense data is pointed to by the SenseData field in the status block. This field is a 16:16 far pointer. The length of the sense data to return is in specified in the ReqSenseLen field.
The adapter device driver must set the following fields when returning sense data:
#The IORB_ERROR and IORB_STATUSBLOCK_AVAIL bits must be set in the Status field of the IORB header.
#The STATUS_SENSEDATA_VALID bit must be set in the Flags field of the Status Block.
#The value in the Error Code field of the returned sense data must be set to 70h.
#The Sense Key, Additional Sense Code and Additional Sense Code Qualifier must be set to indicate the returned error.
To maintain consistency with the adapter device driver specification, an IORB error code must also be returned in the IORB header when an error occurs. This is in addition to the returned sense data information. The table below shows the mapping between Sense Data error codes and IORB error codes. If the Adapter Device Driver returns Sense Key and Sense Codes listed in the SCSI-2 specification which are not listed in the table below, the adapter device driver must map the sense key and codes to the most appropriate IORB error code.
<pre>
  Key  = Sense Key
  ASC  = Additional Sense Code
  ASCQ = Additional Sense Code Qualifier
/--------------------------------------------------------------------------------\
|          |          |Description              |IORB Error Code              |
|          |Key ASC    |                          |                              |
|          |ASCQ      |                          |                              |
|----------+-----------+--------------------------+------------------------------|
|          |          |                          |                              |
|NOT READY |02h 04h 00h|Logical Unit Not Ready    |IOERR_UNIT_NOT_READY          |
|          |02h 04h 01h|Becoming ready            |IOERR_UNIT_NOT_READY          |
|          |02h 57h 00h|Unable to recover TOC    |IOERR_UNIT_NOT_READY          |
|----------+-----------+--------------------------+------------------------------|
|          |          |                          |                              |
|MEDIUM    |03h 02h 00h|No Seek Complete          |IOERR_RBA_ADDRESSING_ERROR    |
|ERROR    |03h 11h 00h|Unrecovered Read Error    |IOERR_RBA_CRC_ERROR          |
|          |03h 11h 05h|L-EC Uncorrectable Error  |IOERR_RBA_CRC_ERROR          |
|          |03h 11h 06h|CIRC Unrecovered Error    |IOERR_RBA_CRC_ERROR          |
|          |03h 12h 00h|Address Mark Not Found    |IOERR_RBA_ADDRESSING_ERROR    |
|          |03h 15h 00h|Random Positioning Error  |IOERR_RBA_ADDRESSING_ERROR    |
|          |03h 16h 00h|Data Synchronization Error|IOERR_RBA_CRC_ERROR          |
|          |03h 30h 00h|Incompatible Medium      |IOERR_MEDIA_NOT_SUPPORTED    |
|----------+-----------+--------------------------+------------------------------|
|          |          |                          |                              |
|HARDWARE  |04h 08h 00h|Unit Communication Fail  |IOERR_DEVICE_NONSPECIFIC      |
|ERROR    |04h 09h 01h|Tracking Servo Failure    |IOERR_DEVICE_NONSPECIFIC      |
|          |04h 09h 02h|Focus Servo Failure      |IOERR_DEVICE_NONSPECIFIC      |
|          |04h 09h 03h|Spindle Servo Failure    |IOERR_DEVICE_NONSPECIFIC      |
|          |04h 44h 00h|Internal Target Failure  |IOERR_DEVICE_NONSPECIFIC      |
|----------+-----------+--------------------------+------------------------------|
|          |          |                          |                              |
|ILLEGAL  |05h 20h 00h|Invalid Command Code      |IOERR_DEVICE_REQ_NOT_SUPPORTED|
|REQUEST  |05h 21h 00h|LBA Out of Range          |IOERR_RBA_ADDRESSING_ERROR    |
|          |05h 24h 00h|Invalid field in CDB      |IOERR_CMD_SYNTAX              |
|          |05h 25h 00h|Unit not supported        |IOERR_CMD_SYNTAX              |
|          |05h 26h 00h|Invalid field in parmlist |IOERR_CMD_SYNTAX              |
|          |05h 63h 00h|End of user area          |IOERR_RBA_ADDRESSING_ERROR    |
|          |05h 64h 00h|Illegal mode for track    |IOERR_RBA_ADDRESSING_ERROR    |
|----------+-----------+--------------------------+------------------------------|
|          |          |Medium may have changed  |                              |
|UNIT      |06h 28h 00h|Power on reset            |IOERR_MEDIA_CHANGED          |
|ATTENTION |06h 29h 00h|                          |IOERR_DEVICE_RESET            |
|----------+-----------+--------------------------+------------------------------|
|          |08h 64h 00h|Illegal mode for track    |IOERR_RBA_ADDRESSING_ERROR    |
|BLANK    |          |                          |                              |
|CHECK    |          |                          |                              |
\--------------------------------------------------------------------------------/
</pre>
==CD-ROM Device Driver Test Tool==
This chapter explains how to use the DDTT to test a CD-ROM Device Driver by executing CD-ROM-oriented test scripts.
===Overview===
CD-ROM functional verification tests exercise the Application Program Interfaces (APIs) - mainly DosDevIOCtl variations - that interface with CD- ROM device drivers. The test environment is defined by the Device Driver Test Tool (DDTT) and each test is written as a DDTT script using Global and CD-ROM grammars. See Device Driver Test Tool (DDTT) for a description of the DDTT. The tests described herein give the user a repeatable set of scripts for verifying CD-ROM functions. They may also be used as examples for creating additional specialized test cases.
As the DDTT parses and executes each test script, it simultaneously creates a disk log file that timestamps the activity and logs each script command. If the command initiates an API call, then the result of the command is logged, be it failure with a return code or success with possible returned data. If the script fails to complete, the log, up to the point of failure, is available for diagnosis.
These tests can be used to verify correct interaction between the CD-ROM device and the following OS/2 components:
*DOSDevIOCtl API interface
*CDFS file system
*OS2CDROM.DMD and OS2ASPI.DMD device managers
*CDROM adapter (.ADD) device drivers
*CDROM filter (.FLT) device drivers
===Installation===
This CD-ROM contains the executables, libraries, grammars, and test cases necessary to run CD-ROM test suites.
The following procedure describes installation for running test cases.
#Copy the component files from the ''Device Driver Kit for OS/2'' CD-ROM to the hard drive. All files should reside in a common directory, such as \TSTCDROM. If the target directory is C:\TSTCDROM and the E: drive contains the information from the ''Device Driver Kit for OS/2'', then use the following commands to copy the CD-ROM test suite:<pre>
[C:\]md tstcdrom
[C:\]cd tstcdrom
[C:\tstcdrom]copy e:\ddk\testcert\storage\function\cdrom\*
[C:\tstcdrom]copy e:\ddk\testcert\general\ddtt\*
</pre>
#Add C:\TSTCDROM to the LIBPATH and PATH in the CONFIG.SYS file.
#Reboot your machine so the new LIBPATH entry takes effect.
The following DDTT files are required for execution of CD-ROM scripts:
*DDTT.EXE
*DDTT.DLL
*GLOBAL.DLL
*GLOBAL.GRA
*DDTCDROM.DLL
*CDROM.GRA
[[Image:Storage-img2.gif]]
===Test-Case Execution===
Test case scripts are driven by the DDTT. The DDTT can be initiated via an OS/2 command line or from a batch file or REXX statement:
[C:\TSTCDROM]DDTT XADATA.SCR
The DDTT creates a Presentation Manager thread window that consists of:
*a multi-line, scrolled output field for logging script progress
*a single-line entry field for operator input
*a single-line text output field for script-initiated prompts and messages
The DDTT CD-ROM tests must be executed on a directly-attached CD-ROM device. These tests will not work when executed against a CD-ROM device accessed by way of a network connection.
===DDTT CD-ROM Test Grammar Function Calls===
Test scripts are ASCII text files containing calls to DDTT commands, global functions, and device-specific functions (the latter two are defined by grammar files). The following is a list of the CD-ROM-specific grammar functions:
*CDROM_OPEN
*CDROM_CLOSE
*CDROM_GETDEVPARAMS
*CDROM_QUERYDRIVELETTER
*CDROM_EJECT
*CDROM_LOCKDOOR
*CDROM_UNLOCKDOOR
*CDROM_QUERYAUDIODISKINFO
*CDROM_QUERYAUDIOSTATUS
*CDROM_QUERYDRIVERINFO
*CDROM_QUERYSECTORINFO
*CDROM_QUERYVOLUMESIZE
*CDROM_QUERYAUDIOTRACKINFO
*CDROM_QUERYSTATUS
*CDROM_QUERYUPC
*CDROM_QUERYCHANINFO
*CDROM_QUERYAUDIOCHANINFO
*CDROM_AUDIOCHANINFO
*CDROM_RESET
*CDROM_STOPAUDIO
*CDROM_RESUMEAUDIO
*CDROM_PLAYAUDIO
*CDROM_SEEK
*CDROM_DRIVELOCATION
*CDROM_READFILE
*CDROM_READ2048
*CDROM_READ2352
*CDROM_READPRE2352
*CDROM_CHECKSECTOR
*CDROM_CHECKRETURN
*CDROM_CHECKVALUE
====CDROM_OPEN====
This function opens the CD-ROM.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DEVICENAME          |STRING              |Drive letter of    |
|                    |                    |CD-ROM              |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Returned drive      |
|                    |                    |handle              |
|--------------------+--------------------+--------------------|
|$DRIVES            |NUM                |Number of CD-ROM    |
|                    |                    |drives in the system|
|                    |                    |being tested        |
|--------------------+--------------------+--------------------|
|$FIRSTCD            |NUM                |First CD-ROM drive  |
|                    |                    |number Where:      |
|                    |                    |00=Drive a          |
|                    |                    |01=Drive b          |
|                    |                    |02=Drive c, etc.    |
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CDROM_CLOSE====
This function closes the CD-ROM.
;Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
None.
;Logged Data
None.
====CDROM_GETDEVPARAMS====
Category 08h Function 63h - Get Device Parameters
This function returns the device parameters including the BIOS parameter block (BPB).
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BYTESPERSECTOR      |NUM                |Sector size in bytes|
|--------------------+--------------------+--------------------|
|LARGESECTORS        |NUM                |Media sector count. |
|--------------------+--------------------+--------------------|
|DEVICETYPE          |NUM                |Device code        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Media sector size in bytes Media sector count Device type code (should be 7 for CD-ROM)
====CDROM_QUERYDRIVELETTER====
Category 82h Function 60h - Return Drive-Letter Information
This function queries the CD-ROM drive letter from the system.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|$DRIVES            |NUM                |Number of CD-ROM    |
|                    |                    |drives in the system|
|                    |                    |being tested        |
|--------------------+--------------------+--------------------|
|$FIRSTCD            |NUM                |Drive number for    |
|                    |                    |CD-ROM drive in the |
|                    |                    |system. Where:      |
|                    |                    |00=Drive a          |
|                    |                    |01=Drive b          |
|                    |                    |02=Drive c, etc.    |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
;Logged Data
None.
====CDROM_EJECT====
Category 80h Function 44h - Eject Disc
This function ejects the CD-ROM disc from the CD-ROM drive.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CDROM_LOCKDOOR====
Category 80h Function 46h - Lock Door
This function locks the CD-ROM drive door.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CDROM_UNLOCKDOOR====
Category 80h Function 46h - Unlock Door
This function unlocks the CD-ROM drive door.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CDROM_QUERYAUDIODISKINFO====
Category 81h Function 61h - Return Audio-Disc Information
This function returns the first and last track numbers as well as the Redbook address for the lead-out track.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|HIGHTRACK          |NUM                |Highest track number|
|--------------------+--------------------+--------------------|
|LOWTRACK            |NUM                |Lowest track number |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
:Highest track number
:Lowest track number
:Starting point of lead-out track
====CDROM_QUERYAUDIOSTATUS====
Category 81h Function 65h - Audio-Status Information
This function returns the audio status, and the starting and ending locations of the last play or next resume.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|PAUSE              |NUM                |Pause bit Where:    |
|                    |                    |0=not paused        |
|                    |                    |1=paused            |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
:Audio status bits
:Starting location of last play audio or resume audio command
:Ending location of last play audio or resume audio command
====CDROM_QUERYDRIVERINFO====
Category 80h Function 61h - Identify CD-ROM Driver
This function identifies the device driver as a valid CD-ROM driver.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
CD-ROM device driver ID
====CDROM_QSECTORINFO====
Category 80h Function 63h - Return Sector Size
This function returns the disc sector size in bytes. (Defaulted to 2MB.)
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                |Bytes per sector    |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Sector size in bytes
====CDROM_QUERYVOLUMESIZE====
Category 80h Function 78h - Return Volume Size
This function returns the total number of readable sectors on the disc.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|VOLSIZE            |NUM                |Disc sector count  |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Volume size in sectors
====CDROM_QUERYAUDIOTRACKINFO====
Category 81h Function 62h - Return Audio-Track Information
This function returns, for a specified track, the Redbook address for the starting point plus track-control information.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
|--------------------+--------------------+--------------------|
|TRACK              |NUM                |Track number        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Starting point of track Track-control information
====CDROM_QUERYSTATUS====
Category 80h Function 60h - Device Status
This function returns the device driver status codes in a double word. Hardware disc/door status and software support are indicated.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|STATUS              |NUM                |Status bits        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
CD-ROM drive status information
====CDROM_QUERYUPC====
Category 80h Function 79h - Get UPC
This function returns the UPC code for the CD-ROM disc.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Control and ADR byte Universal product code Frame
====CDROM_QUERYCHANINFO====
Category 81h Function 63h - Return Audio Q Channel Information
This function reads and returns the most current address information from the Q channel. Data returned includes current track and running time for disc and track.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|TRACK              |NUM                |Current track number|
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Control and ADR byte
Track number Index
Running time within a track, minutes
Running time within a track, seconds
Running time within a track, frames
Running time within a disc, minutes
Running time within a disc, seconds
Running time within a disc, frames
====CDROM_QUERYAUDIOCHANINFO====
Category 81h Function 60h - Return Audio Channel Control Information
This function returns the current settings of the audio channel controls.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|INCHAN1            |NUM                |Input channel for  |
|                    |                    |output 0            |
|--------------------+--------------------+--------------------|
|INCHAN2            |NUM                |Input channel for  |
|                    |                    |output 1            |
|--------------------+--------------------+--------------------|
|OUTVOL1            |NUM                |Volume for output 0 |
|--------------------+--------------------+--------------------|
|OUTVOL2            |NUM                |Volume for output 1 |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
Input channel for output channel 0 Volume control for output channel 0 Input channel for output channel 1 Volume control for output channel 1
====CDROM_AUDIOCHANINFO====
Category 81h Function 40h - Set Audio Channel Controls
This function sets the audio channel controls.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
|--------------------+--------------------+--------------------|
|VOL1                |NUM                |Volume for channel 0|
|--------------------+--------------------+--------------------|
|VOL2                |NUM                |Volume for channel 1|
|--------------------+--------------------+--------------------|
|INPUT1              |NUM                |Input channel for  |
|                    |                    |output 0            |
|--------------------+--------------------+--------------------|
|INPUT2              |NUM                |Input channel for  |
|                    |                    |output 1            |
\--------------------------------------------------------------/
EXAMPLE:
    VOL1 = (0-255)
    VOL2 = (0-255)
    INPUT1 = 0
    INPUT2 = 1
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CDROM_RESET====
Category 80h Function 40h - Reset Drive
This function resets and reinitializes the drive and controller.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CDROM_STOPAUDIO====
Category 81h Function 51h - Stop Audio
This function cancels any active play request.
;Required Input Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
\--------------------------------------------------------------/
</pre>
;Output Parameter Keywords
<pre>
/--------------------------------------------------------------\
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
\--------------------------------------------------------------/
</pre>
;Logged Data
None.
====CDROM_RESUMEAUDIO====
Category 81h Function 52h - Resume Audio
This function resumes playing audio after play has been interrupted by the stop audio command.
;Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+----------------
|DRIVEHANDLE        |NUM                |Drive handle for
|                    |                    |CD-ROM drive
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|CDRC                |NUM                |Function return code
</pre>
;Logged Data
None.
====CDROM_PLAYAUDIO====
Category 81h Function 50h - Play Audio
This function plays selected audio sectors. Sector interval may be designated using logical block or Redbook addressing (parameters for each set are mutually exclusive).
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|DRIVEHANDLE||NUM||Drive handle for CD-ROM drive
|-
|ADDRESSMODE:||STRING||Addressing mode:
LOGICAL BLOCK or REDBOOK
|-
|SECTORSTART||NUM||If using logical block
|-
|SECTORCOUNT||NUM||If using logical block
|-
|TIMESTART||STRING||If using Redbook
|-
|TIMESTOP||STRING||If using Redbook
|}
EXAMPLES:
Logical Block:
    ADDRESSMODE=LOGICALBLOCK
    SECTORSTART=20000
    SECTORCOUNT=10000
Redbook:
    ADDRESSMODE=REDBOOK
    TIMESTART=02:45:00
    TIMESTOP=05:55:00
</pre>
;Output Parameter Keywords
{|class="wikitable"
!Keyword||Type|Description
|-
|CDRC||NUM||Function return code
|}
;Logged Data
None.
====CDROM_SEEK====
Category 80h Function 50h - Seek
This function moves the read head to the specified sector. The function can operate in either address mode by specifying a sector-start value or a time-start value (mutually exclusive).
;Required Input Parameter Keywords
<pre>
|Keyword        |Type      |Description
|---------------+-----------+----------------
|DRIVEHANDLE    |NUM        |Drive handle for CD-ROM drive
|---------------+-----------+----------------
|ADDRESSMODE    |STRING    |Addressing mode:
|              |          |LOGICAL BLOCK or REDBOOK
|---------------+-----------+----------------
|SECTORSTART    |NUM        |If using logical block
|---------------+-----------+----------------
|TIMESTART      |STRING    |If using Redbook
EXAMPLES:
Logical Block
    ADDRESSMODE=LOGICALBLOCK
    SECTORSTART=20000
Redbook
    ADDRESSMODE=REDBOOK
    TIMESTART=02:45:00
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+--------------------
|CDRC                |NUM                |Function return code
</pre>
;Logged Data
None.
====CDROM_DRIVELOCATION====
Category 80h Function 70h - Location of Drive Head
This function returns the current head location in units valid for the requested addressing mode.
;Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description
|--------------------+--------------------+----------------
|DRIVEHANDLE        |NUM                |Drive handle for
|                    |                    |CD-ROM drive   
|--------------------+--------------------+----------------
|ADDRESSMODE        |STRING              |Addressing mode:
|                    |                    |LOGICAL BLOCK or
|                    |                    |REDBOOK
</pre>
EXAMPLES:
Logical Block
ADDRESSMODE=LOGICALBLOCK
Redbook
ADDRESSMODE=REDBOOK
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
</pre>
;Logged Data
Location of drive head
====CDROM_READFILE====
DOS READ FILE
This function locates a selected file on the CD-ROM disc and reads in the specified number of bytes at the specified offset.
;Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
|--------------------+--------------------+--------------------|
|FILENAME            |STRING              |Name of file to read|
|--------------------+--------------------+--------------------|
|BYTESTART          |NUM                |Starting byte to    |
|                    |                    |read                |
|--------------------+--------------------+--------------------|
|BYTECOUNT          |NUM                |Number of bytes to  |
|                    |                    |read                |
</pre>
;Optional Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BUFFER              |STRING              |Buffer name        |
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
</pre>
;Logged Data
Byte(s) read
====CDROM_READ2048====
DOS READ
This function reads 2048 bytes of each specified sector into the data buffer. The number of sectors to read is passed as input. Address mode is defaulted (and limited) to Logical Block.
;Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |Starting sector to  |
|                    |                    |read                |
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors to|
|                    |                    |read                |
</pre>
;Optional Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BUFFER              |STRING              |Buffer name        |
EXAMPLE:
Logical Block
    BUFFER=ALPHA
    SECTORSTART=20000
    SECTORCOUNT=10000
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
</pre>
;Logged Data
Byte sync
Byte header
Byte data area
Byte EDC/ECC area
====CDROM_READ2352====
Category 80h Function 72h - Read Long
This function reads 2352 bytes of each specified sector into the data buffer. Header and trailer data are read in addition to the 2048-byte data field. The number of sectors to read is passed as input. Address mode may be specified as either Redbook or Logical Block. SECTORSTART and TIMESTART parameters are mutually exclusive.
;Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
|--------------------+--------------------+--------------------|
|ADDRESSMODE        |STRING              |Addressing mode:    |
|                    |                    |LOGICALBLOCK or    |
|                    |                    |REDBOOK            |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |If using logical    |
|                    |                    |block              |
|--------------------+--------------------+--------------------|
|TIMESTART          |STRING              |If using Redbook    |
|--------------------+--------------------+--------------------|
|SECTORCOUNT        |NUM                |Number of sectors to|
|                    |                    |read                |
</pre>
;Optional Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|BUFFER              |STRING              |Buffer name        |
EXAMPLE:
Logical Block
    ADDRESSMODE=LOGICALBLOCK
    BUFFER=ALPHA
    SECTORSTART=20000
    SECTORCOUNT=10000
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
</pre>
;Logged Data
Byte sync (12 bytes)
Byte header (4 bytes)
Byte data area (2048 bytes)
Byte EDC/ECC area (288 bytes)
====CDROM_READPRE2352====
Category 80h Function 71h - Read Long Prefetch
This function operates as an abortive or advisory seek command. No data is transferred to the caller. SECTORSTART and TIMESTART parameters are mutually exclusive.
;Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE        |NUM                |Drive handle for    |
|                    |                    |CD-ROM drive        |
|--------------------+--------------------+--------------------|
|ADDRESSMODE        |STRING              |Addressing mode:    |
|                    |                    |LOGICALBLOCK or    |
|                    |                    |REDBOOK            |
|--------------------+--------------------+--------------------|
|SECTORSTART        |NUM                |If using logical    |
|                    |                    |block              |
|--------------------+--------------------+--------------------|
|TIMESTART          |STRING              |If using Redbook    |
EXAMPLE:
Logical Block
    ADDRESSMODE=LOGICALBLOCK
    SECTORSTART=20000
    SECTORCOUNT=10000
</pre>
;Output Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                |Function return code|
</pre>
;Logged Data
None
====CDROM_CHECKSECTOR====
Read Verification Diagnostic Function
This function verifies that the correct record has been read by the device driver. The expected sector value is compared with a doubleword in the input buffer that contains the sector number of the last record read (first doubleword for COOKED buffers and fifth doubleword for RAW buffers). This is a special function that only applies to the IBM Test Disc, tracks 1, 3, and 6.
;Required Input Parameter Keywords
<pre>
|Keyword            |Type                |Description        |
|--------------------+--------------------+--------------------|
|READMODE            |STRING              |RAW or COOKED buffer|
|--------------------+--------------------+--------------------|
|$BUFFER            |NUM                |Buffer reference    |
|--------------------+--------------------+--------------------|
|$SECTOR            |NUM                |Expected sector    |
|                    |                    |value
</pre>
;Logged Data
Error message if comparison fails
====CDROM_CHECKRETURN====
Check Return Code Diagnostic Function
This function verifies that the return code from a previous function is equal to a given value. The function is used for error testing to verify expected return codes. It is assumed that a previous function has set the CDRC parameter. $RC is set by the script author to the expected value.
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|$RC||NUM||The expected return code
|}
;Logged Data
Message stating the result of the comparison - either failure or success.
====CDROM_CHECKVALUE====
Check Parameter Value Diagnostic Function
This function verifies that a parameter returned by a previous CDROM function is equal to a given numeric value. $PARM must be explicitly equated to the parameter being tested and $EXPECT set to the expected value.
;Required Input Parameter Keywords
{|class="wikitable"
!Keyword||Type||Description
|-
|$PARM||NUM||The returned parameter value
|-
|$EXPECT||NUM||The expected value
|}
;Logged Data
Message stating the result of the comparison - either failure or success.
=== Description of Test Cases ===
Each of the CD-ROM test cases can be executed by invoking the DDTT from either a command line, a batch file, or a REXX file. Test scripts are described below. The user is free to create additional tests or construct multi-threaded test cases after becoming familiar with the DDTT and the CD-ROM grammar files.
Test scripts generally start by opening to the device (CDROM_OPEN) and closing at completion (CDROM_CLOSE). The device open will not succeed unless a disc is present. All test scripts log information to a log file of the same file name, but with a file name extension of .LOG. When current status is queried (for example, track, channel, or drive), this data is written to the DDTT's scroll output window and to the log file. Log files can be examined with a text editor after the test case has completed.
The CD-ROM Play-Audio function causes the CD-ROM drive to play the audio media by sending the audio signal to the CD-ROM's own pre-amplified outputs. The audio is not played through the system speaker or any multi-media device.
CD-ROM discs are accessed by Logical Block or Redbook format. Logical block format sequentially addresses each block on the disc starting at 0. Redbook format addresses each block using a time format of MM:SS:FF (MM represents minutes from the start of the CD, SS represents seconds, and FF represents frames.) Each frame represents 1/75th of a second. Logical block 0 and Redbook format block 0:2:0 are coincident and both represent the first addressable block.
;XADATA.SCR: This script exercises all CD-ROM data API interfaces. It requires the IBM Test Disc (IBM part number 81F8902) which contains known data, known size parameters, and tracks containing mode 1 and mode 2 data.
;XAAUDIO.SCR: This script exercises all CD-ROM audio API interfaces. It requires the IBM Test Disc and a pair of speakers or headphones plugged into the CD drive audio jack. The test disc has 3 audio tracks containing tones. Track 2 has different tones on left and right channels.
;XAERROR.SCR: This script exercises the device driver's ability to detect errors related to invalid data, missing media, and invalid command sequences. It requires the IBM Test Disc.
CDFILE.SCR This script exercises the device driver's ability to locate and read a file. It requires any data disk with a directory structure and a data file less than 150KB. The DDTT for this script is initiated by batch file CDFILE.CMD. The batch file first calls a filter program to search for a test file candidate. The name of this target file is passed to the DDTT test script as an included data file. Invoke by entering CDFILE followed by the CD-ROM drive letter and a colon.
;CDDATA.SCR: This script exercises all CD-ROM data API interfaces. It requires any data CD-ROM with a directory structure. Since it is dealing with unknown data, the script is not as comprehensive as that for XADATA.SCR.
;CDAUDIO.SCR: This script exercises all CD=ROM audio API interfaces. It requires any digital audio (music) CD-ROM. Since it operates on unknown audio tracks, the script is not as comprehensive as that for XAAUDIO.SCR.
=== Evaluation of Test Case Results ===
Except for XAERROR.SCR, all test cases are expected to succeed and there should be no ERROR statements in the logs (unless a function such as Read UPC is not supported by the hardware). The log for XAERROR.SCR will have many ERROR statements but should have no Failure statements. Failure statements indicate that an expected error code was not received.
Test case logs need to be examined to verify that data is returned by certain CD-ROM commands as expected, particularly drive status commands. Not all returned data is automatically checked. Script comments will note what data is expected.
== Building an OS/2 Virtual Disk Driver ==
This chapter describes how to program and build an OS/2 virtual disk driver. In order to successfully build a virtual disk driver, should be familiar with the OS/2 2.0 operating system or later, and have previous experience developing OS/2 device drivers.
In the ''IBM Developer Connection Device Driver Kit for OS/2'', you will find an OS/2 virtual disk driver. After reading this chapter and examining the code, you can use this information to write your own virtual device driver.
===Virtual Disk Driver Code===
The virtual disk driver code provides access to a virtual disk in random access memory. The virtual disk driver runs in a multi-tasking environment and is a protected resource.
In this chapter you will find:
*A table listing the virtual disk parameters
*A table listing the virtual disk commands
*An explanation of how the virtual disk initialization routine works
*Information for performing time-critical tasks
*A procedure for building the virtual disk device driver code that is provided with the ''IBM Device Driver Source Kit for OS/2''
''Using the Virtual Disk Parameters:'' To allocate the virtual disk driver volume, modify the following device statement in the CONFIG.SYS file.
DEVICE = .\PATHNAME\VDISK.SYS [bbbb] [ssss] [dddd]
Where:
bbbb Determines the disk size in K bytes. The default value is 64KB. The minimum is 16KB. The maximum is 524 288 (512MB).
ssss Determines the sector size in bytes. The default value is 128. Acceptable values are increments of 128 which include 128, 256, 512, and 1024.
dddd Determines the number of root directory entries. The default is 64; with a minimum of 2 and a maximum of 1024. The value is rounded up to the nearest sector size boundary.
The virtual disk driver adjusts the value of dddd to the nearest sector size boundary. For example if you give a value of 25, and the sector size is 512 bytes, 25 will be rounded up to 32 which is the next multiple of 16.
The parameters you use to specify byte and sector size and the number of directory entries are positional parameters. This means that if you omit a parameter, you should not leave it blank. You should use a comma in the parameter field to separate this field from the next. The only time you can use blank spaces as separators is in the instance where you are coding blanks for all the parameters.
In the event that there is not enough memory to create the virtual disk driver volume, the driver attempts to create a DOS volume with 16 directory entries. This may result in a volume with a different number of directories than you specified on the device statement (dddd).
To ensure system reliability, specify 32 megabytes or less for disk size.
Example 1
C:\OS2\VDISK.SYS ,128,64
where the disk size is 64KB, the sector size is 128 bytes, and there are 64 directory entries.
Example 2
C:\OS2\VDISK.SYS 2048,,32
where the disk size is 2 048 KB, the sector size is 128 bytes, and there are 32 directory entries.
Example 3
C:\OS2\VDISK.SYS 2048,512,
where the disk size is 2 048 KB, the sector size is 512 bytes, and there are 64 directory entries.
Example 4
C:\OS2\VDISK.SYS ,128,32
where the disk size is 64 KB, the sector size is 128 bytes, and there are 32 directory entries.
Supported Physical Device Driver Strategy Commands: The virtual disk driver is a block device driver and cannot be partitioned. For this reason , the virtual disk driver uses a limited set of physical device driver strategy commands. These are listed below:
CodeFunction 0hInit 1hMedia Check 2hBuild BPB 4hRead (Input) 8hWrite (Output) 9hWrite With Verify DhOpen Device EhClose Device FhRemovable Media 10hGeneric IOCtl 11hReset Media 12hGet Logical Drive Map 13hSet Logical Drive Map 1AhNo Caching (Write With Verify) 1DhGet Driver Capabilities
If the virtual disk driver uses any commands other than those shown above, the driver returns an unknown command error code. For more information on these commands, refer to the OS/2 Physical Device Driver Reference.
The virtual disk driver supports the Extended Device Driver Interface which is implemented through the Get Driver Capabilities command. This interface issues a Request List of prioritized commands. VDisk_Strat2, specified in the driver capabilities structure, is the entry point for all the commands.
CHKDSK uses the category 08h and function 63h IOCtl command from the kernel . This is the only command supported by the virtual disk driver in the general IOCtl commands category.
Virtual Disk Driver Initialization: The virtual disk driver initialization routine does the following:
*Initializes various global values and initializes the DevHelp function router address.
*Parses the command line and sets the values accordingly.
The "DEVICE = xxxxxxxxx" line pointer provided in request packet searches for the various device parameters. The pointer searches through the device name field to obtain the arguments. Then the pointer parses the arguments as they are encountered. All parameter errors are detected at this time. The static initialization routine sets the parameter variables to the default settings.
*Allocates the memory for the virtual disk driver.
The routine issues the DevHlp_VMAlloc command to allocate random access memory for the virtual disk driver.
*Initializes the DOS volume in random access memory for the virtual disk driver.
To so, the routine sets the BPB and initializes the RESERVED (boot) sector, FAT sectors, and root directory sectors and writes them to the virtual disk driver. First the routine initializes the BPB values. Then the routine writes the BOOT record, containing the BPB, to sector 0. The routine writes to a FAT file with all of the clusters free, and writes to the root directory with ONE entry (the Volume ID at VOLID).
*Prints a report of the RAMDrive parameters.
You can print the BPB values. To do so, use the DosGetMessage and DosPutMessage functions in your virtual disk driver. From this report, you can determine the device size, cluster size, and directory size.
*Specifies the return INIT I/O packet values.
The INIT I/O packet return values for number of units are set, as well as the BPB array pointer.
At any time during the initialization steps an error may be detected. When this happens, the system prints an error message. The virtual disk driver uninstalls and returns a unit count of 0 in the INIT device I/O packet.
Performing Time-Critical Tasks: To perform time-critical tasks, you must call the DevHlp_GetDOSVar service from the virtual disk driver code. The virtual disk driver periodically checks the TCYield flag and calls the TCYield function to yield the CPU to a time-critical thread. The location of the TCYield flag is obtained from a call to DevHlp_GetDosVar. The virtual disk driver checks the TCYield flag each time 32,768 bytes of data have been transferred. Refer to the OS/2 Physical Device Driver Reference for more information.
Building the OS/2 2.0 (and later) Virtual Disk Driver sample code: To build the sample virtual disk driver code, complete the following steps:
#Add the TOOLS directory to the OS/2 IBM Developer Connection Device Driver Kit for OS/2 and set it to the current path.
#Set the TMP environment variable to point to a work area. This is shown below:<pre> SET TMP=E:\</pre>
3. NMAKE the following makefiles in the DDK:<pre>
SRC\DEV\VDISK\MAKEFILE
CD\DDK\SRC\DEV\VDISK
NMAKE
</pre>
==[[OS2DASD.DMD - Technical Reference]]==
==Boot Record Architecture==
This appendix describes the details of the data that appear on a physical disk. It also describes the structures that are placed on the disk by various utilities.
===Master Boot Record===
The master boot record is always located on sector 1 of the first track (track 0) on the disk. The following table shows the layout of the various components inside the Master Boot Record. The various components are described below.
<pre>
|Offset    |Description                  |Size
|----------+------------------------------+----------
|+0        |Master Boot Record Program    |446 bytes
|----------+------------------------------+----------
|+446      |Partition Table              |64 bytes 
|----------+------------------------------+----------
|+510      |Signature (55AAH)            |2 bytes 
</pre>
;Master Boot Record Program
:This code is given control from BIOS during boot. Its function is to load the operating system's boot program from the partition that was marked as being startable and turn control over to the ( assumed) code that was loaded.<br />The Master Boot Record Program may be placed on the disk by individual operating systems. If the signature in the Master Boot Record is valid, then the Master Boot Record Program must not be modified. Operating systems must not place requirements on nor make assumptions about the Master Boot Record Program.
;Partition Table
:This is a vector of 4 structures that allows the disk to be divided up into four distinct areas or partitions. The following table shows how they are arranged in this vector.
<pre>
|Offset |Description |Size
|-------+------------+--------
|0      |Partition 1 |16 bytes
|-------+------------+--------
|16    |Partition 2 |16 bytes
|-------+------------+--------
|32    |Partition 3 |16 bytes
|-------+------------+--------
|48    |Partition 4 |16 bytes
</pre>
It is up to an individual operating system if one of those parts is to be further sub-divided. For example, DOS Version 3.30 implemented a scheme where an "extended partition"; could be used to define logical disks to allow the use of larger hardfiles.
The following table shows the format of the individual entries in the partition table. A description of the individual fields follows.
<pre>
|Offset| Description |    0    |    1    |    2    |    3    |
|------+-------------+---------+---------+---------+---------|
|  +0  |Partion Start|  Boot  |  Head  | Sector  |Cylinder |
|      |            |Indicator|        |        |        |
|------+-------------+---------+---------+---------+---------|
|  +4  |Partion End  | System  |  Head  | Sector  |Cylinder |
|      |            |Indicator|        |        |        |
|------+-------------+-------------------+-------------------|
|      | Offset from |                  |                  |
|  +8  |start of disk|    Low Word      |    High Word    |
|      | (sectors)  |                  |                  |
|------+-------------+-------------------+-------------------|
|      |  Partion    |                  |                  |
| +12  |  Length    |    Low Word      |    High Word    |
|      | (sectors)  |                  |                  |
</pre>
;Partition Start
:This 4 byte field identifies the beginning of a partition. It also contains an indicator that flags the partition as being active or bootable. This field is composed of several bytes defined as follows.
;Boot Indicator
:This byte indicates if the partition is active. If the byte contains 00H, then the partition is not active and will not be considered as bootable by the Master Boot Record Boot Program. If the byte contains 80H, then the partition is considered active. The Master Boot Record Boot Program will then attempt to load the first sector described by this partition table entry and transfer control to it. The Master Boot Record Boot Program should only attempt to boot the first partition it finds that is marked active.
;Head
:This byte contains the number of the first head of the partition.<br />All partitions are allocated in cylinder multiples and begin on sector 1, head 0.<br />EXCEPTION: The partition that is allocated at the beginning of the disk should start at cylinder 0, head 1, sector 1, to leave room for the disk's master boot record and other information used to define the fixed disk type on that system. An operating system should not use any data space on cylinder 0 head 0 of a fixed disk.
;Sector
:This byte contains the sector number of the first sector of the partition. This value should always be 1 (sector numbers are 1 based) for the Partition Begin field because partitions are defined to start on cylinder boundaries. Note that the sector number byte also contains the high order 2 bits of the cylinder number in the high order 2 bits of this byte. Therefore, this byte can have values other than one, but the sector bits of this byte always contains the value 1.
;Cylinder
:This byte contains the low order 8 bits of the 10 bit cylinder number that indicates the starting cylinder of the partition.
;Partition End
:This 4 byte field identifies the end of the partition. It also contains an indicator as to which operating system owns the partition. This field is composed of several bytes that are defined as follows.
;System Indicator
:This byte indicates what operating system owns the particular partition. The values and what they represent are listed in Fixed Disk Partition ID Assignments. A value of 0 indicates an unused entry.
;Head
:This byte contains the last head number in the last cylinder occupied by this partition.
;Sector
:This byte contains the sector number of the last sector on the last cylinder occupied by this partition. It also contains the high order two bits of the cylinder number in the high two bits of this byte.
;Cylinder
:This byte contains the low order 8 bits of the 10-bit cylinder number that indicates the ending cylinder of this partition.
;Offset from Start of Disk
:This 4-byte field contains the number of sectors preceding each partition on the disk. The value is obtained by counting the sectors beginning with cylinder 0, sector 1, head 0 of the disk, and incrementing the sector, head, and then cylinder values up to the beginning of the partition. Thus, if the disk has 17 sectors per track and 4 heads, and the second partition begins at cylinder 1, sector 1, head 0, the partition's starting relative sector is 68 (decimal)-there were 17 sectors on each of 4 heads on 1 track allocated ahead of it. The field is stored with the least significant word first.
;Partition Length
:This 4 byte field contains the number of sectors allocated to the partition. This field is stored least significant word first.
;Signature
:The last 2 bytes of the boot record (55AAH) are used as a signature to identify a valid boot record containing code that is executable on Intel X86 processors. Both this record and the partition boot records are required to contain the signature at offset 01FEH (510).
===Fixed Disk Technical Information===
A fixed disk boot record must be written on the first sector of all fixed disks or logical drives within an extended partition and must contain:
*Code to load and give control to the boot record for one of four possible operating systems.
*A partition table at the specified offset into the boot record. Each table entry is 16 bytes long, and contains the starting and ending cylinder, sector, and head for each of four possible partitions, as well as the number of sectors preceding the partition and the number of sectors occupied by the partition. The "boot indicator" byte is used by the boot record to determine if one of the partitions contains a loadable operating system. FDISK (or equivalent) initialization utilities mark a user-selected partition as "startable" by placing a value of 80h in the corresponding partition's boot indicator (setting all other partition's indicators to 00h at the same time). The presence of the 80h tells the Master Boot Record Program to load the sector whose location is contained in the following 3 bytes. That sector is the actual boot record for the selected operating system, and it is responsible for the remainder of the system's loading process (as it is from diskette). All boot records are loaded at absolute address 0:7C00.
*A Signature to indicate a valid Master Boot Record.
===System Initialization===
The System initialization (or system boot) sequence is as follows:
#System initialization first attempts to load an operating system from the first diskette drive. If the drive is not ready or a read error occurs, it then attempts to read the fixed disk master boot record from the first sector of the first fixed disk on the system. If unsuccessful, or if no fixed disk is present, it invokes a device, ROM BASIC or prompts for a startable diskette.
#If successful, the master boot record is given control. It examines the partition table imbedded within it. If one of the entries indicates a "startable" (active) partition, its boot record is read (from the partition's first sector) and give control.
#If none of the partitions is startable, a RIPL device or ROM BASIC is invoked or a prompt for a bootable diskette is displayed.
#If any of the boot indicators are invalid (values other than 00h or 80h) the message Invalid partition table is displayed and the system stops. You may then insert a system diskette in drive A and use system reset to restart from diskette.
#If the partition's boot record cannot be successfully read within five retries due to read errors, the message Error loading operating system appears and the system stops.
#If the partition's boot record does not contain a valid "signature", the message Missing operating system appears, and the system stops.
When a partition's boot record is given control, it has passed its partition table entry address in the DS:SI registers.
System programmers designing a utility to initialize/manage a fixed disk must provide the following functions at a minimum:
#Write the master disk boot record/partition table to the disk's first sector to initialize it if it is not already present.
#Perform partitioning of the disk-that is, create or update partition table information (all fields for the partition) when the user wishes to create, modify, or remove a partition. This may be limited to creating a partition for only one type of operating system, but must allow repartitioning the entire disk, or adding a partition without interfering with existing partitions (user's choice).<br /><br />'''Note:''' When changing the size or location of any partition, you must ensure that all existing data on that partition has been backed up (the partitioning process will "lose track" of the previous partition boundaries).
#Provide a means for marking a user-specified partition as startable, and resetting the startable indicator bytes for other partitions at the same time.
#Such utilities should not change or move any partition information that belongs to another operating system.
===Fixed Disk Partition ID Assignments===
{|class="wikitable"
!Partition||Description
|-
|00
|Unused Partition
|-
|01
|DOS, 12-bit FAT
|-
|-
|03
|XENIX User, includes SCO/XENIX
|-
|04
|DOS, 16-bit FAT
|-
|05
|DOS and OS/2, >32MB support; defines an Extended partition which may include other partition types.
|-
|06
|DOS, >32MB support, up to 64K Allocation unit
|-
|07
|OS/2, >32MB partition support (IFS)
|-
|-
|08
|OS/2 (thru Version 1.3 only)
|-
|08
|DELL partition spanning multiple drives (array)
|-
|08
|Commodore DOS Partition
|-
|09
|AIX
|-
|0A
|OS/2 Boot Manager Partition
|-
|0B - 0D
|Available for assignment
|-
|0E - 0F
|Reserved
|-
|10
|Reserved
|-
|11
|OS/2 Boot Manager: DOS - Inactive type 1
|-
|12
|Reserved
|-
|13
|Available for assignment
|-
|14
|OS/2 Boot Manager: DOS - Inactive type 4
|-
|15
|Available for assignment
|-
|16
|OS/2 Boot Manager: DOS - Inactive type 6
|-
|17
|OS/2 Boot Manager: DOS - Inactive type 7
|-
|18 - 20
|Available for assignment
|-
|21
|Reserved
|-
|22
|Available for assignment
|-
|23 - 24
|Reserved
|-
|25
|Available for assignment
|-
|26
|Reserved
|-
|27 - 30
|Available for assignment
|-
|31
|Reserved
|-
|32
|Available for assignment
|-
|33 - 34
|Reserved
|-
|35
|Available for assignment
|-
|36
|Reserved
|-
|37 - 3F
|Available for assignment
|-
|-
|41
|Personal RISC Boot Partition
|-
|42 - 4F
|Available for assignment
|-
|50
|OnTrack Disk Manager
|-
|51
|OnTrack Disk Manager
|-
|52
|Reserved
|-
|53 - 55
|Available for assignment
|-
|56
|Reserved
|-
|57 - 60
|Available for assignment
|-
|61
|Reserved
|-
|62
|Available for assignment
|-
|-
|64
|Speedstore
|-
|65
|Novell 286 Netware
|-
|66
|Novell 386 Netware
|-
|67
|Novell (future use)
|-
|68
|Novell (future use)
|-
|69
|Novell (future use)
|-
|6A - 70
|Available for assignment
|-
|71
|Reserved
|-
|72
|Available for assignment
|-
|73 - 74
|Reserved
|-
|75
|PC/IX
|-
|76
|Reserved
|-
|77 - 79
|Available for assignment
|-
|80 - 81
|Reserved
|-
|82
|Prime
|-
|-
|85 - 85
|Available for assignment
|-
|86
|Reserved
|-
|87
|HPFS FT mirrored partition
|-
|88 - 92
|Available for assignment
|-
|93 - 94
|Reserved
|-
|95 - A0
|Available for assignment
|-
|A1
|Reserved
|-
|A2
|Available for assignment
|-
|A3 - A4
|Reserved
|-
|A5
|Available for assignment
|-
|A6
|Reserved
|-
|A7 - B0
|Available for assignment
|-
|B1
|Reserved
|-
|B2
|Available for assignment
|-
|B3 - B4
|Reserved
|-
|B5
|Available for assignment
|-
|B6 - B8
|Reserved
|-
|B9 - C0
|Available for assignment
|-
|C1
|Reserved
|-
|C2 - C3
|Available for assignment
|-
|C4
|Reserved
|-
|C5
|Available for assignment
|-
|C6
|Reserved
|-
|C7
|HPFS FT disabled mirrored partition
|-
|C8 - D7
|Available for assignment
|-
|D8
|CP/M 86
|-
|D9 - DA
|Available for assignment
|-
|DB
|Reserved
|-
|DC - E0
|Available for assignment
|-
|E1
|Speedstore
|-
|E2
|Available for assignment
|-
|E3
|Storage Dimensions (Maxtor Retail Subsidiary)
|-
|E4
|Speedstore
|-
|E5 - E6
|Reserved
|-
|E7 - F0
|Available for assignment
|-
|F1
|Storage Dimensions (Maxtor Retail subsidiary)
|-
|F2 - F3
|Reserved
|-
|F4
|Storage Dimensions (Maxtor Retail subsidiary)
|-
|F5
|Available for assignment
|-
|F6
|Reserved
|-
|F7 - FD
|Available for assignment
|-
|FE
|IBM PS/2 IML
|-
|FF
|Bad Block Tables - Must be on cylinder 0
|}
===Extended DOS Partition===
Fixed disks can be divided into primary partitions, and an extended partition that contains multiple logical block devices. The extended partition is indicated by a System ID byte of 05h in the partition table of the Master Boot Record. This partition cannot be started, and programs that can set startable partitions (such as OS/2 FDISK) do not allow the partition to be marked as able to start.
The extended DOS partition can be created only if a primary DOS partition already exists on a startable drive. A primary partition is a partition with a System ID byte of 01h, 04h, 06h, or 07h. If the drive cannot be started, then an extended DOS partition can be created without having a primary DOS partition.
'''Note:'''
#FDISK refers to extended volumes as logical drives.
#This extended partition support can be used on any fixed disk supported by the OS/2 operating system.
The extended DOS partition starts and ends on a cylinder boundary, and contains a collection of extended volumes that are linked together by a pointer in the extended volumes' extended boot record. An ''extended volume'' consists of an extended boot record and one logical block device. In OS/2 Version 1.0, an extended volume could not be larger than 32MB, due to the limitations of the FAT file system. However, in OS/2 2.0 and 2.1, this restriction has been removed. An extended volume created within the extended DOS partition can be any size, from one cylinder long through the maximum available contiguous space in the extended DOS partition. All extended volumes must start and end on a cylinder boundary. The extended boot record corresponds to the Master Boot Record at the beginning of an actual physical disk. The logical block device corresponds to the DOS partition that is pointed to by the Master Boot Record.
The logical block device begins with a normal DOS boot sector if it is a DOS logical block device (System ID=1, 4, or 6). Installable File System (IFS) logical block devices (System ID=7) need not start with a normal DOS boot sector. This logical block device must start on a cylinder and head boundary and must follow the extended boot record on the physical disk. The logical block device and the extended volume both end on the same cylinder boundary.
Each extended volume contains an extended boot record located in the first sector of the disk location assigned to it. This extended boot record contains the 55AAh signature ID byte. This allows programs that look at the Extended (Master) Boot Record to be compatible. This extended boot record also contains a partition table, which can contain only two types of entries. The boot code is not critical, as the devices are not considered startable. The boot code can simply report a message indicating an unstartable partition if it is executed.
The partition table portion of the extended boot record is the same as the partition table structure in the Master Boot Record. This structure has four partition entries of 16 bytes each. The System ID byte must be filled in for all four entries with one of the following values:
:00h No space allocated in this entry.
:01h DOS partition up to 16MB.
:04h DOS partition with 32MB > SIZE > 16MB.
:05h Maps out area assigned to the next extended volume. Serves as a pointer to the next extended boot record.
:06h DOS partition size > 32MB.
:07h Installable file system.
If the System ID byte is 0, then the values in that partition table entry are set to 0.
If the operating system detects any values other than 01h, 04h, 06h, or 07h, it ignores that entry and does not attempt to install the logical block device. This allows future expansion of devices in this area without problems of compatibility with earlier systems.
The partition start and end fields Cylinder, Head, and Sector (C,H,S) are filled in for any of the four partition entries in an extended boot record that have one of the System ID bytes. This allows a program such as FDISK to determine the allocated space in the extended DOS partition, and allows the physical device drivers to determine the physical DASD area that belongs to it. The partition start and end fields (C,H,S) for the partition entry that points to the logical block device (System ID 01h, 04h , 06h, or 07h) map out the physical boundaries of the logical block device. They are offset relative to the beginning of the extended boot record that the entry resides in. The partition start and end fields for the partition entry that points to the next extended volume (System ID 05h) map out the physical boundaries of the next extended volume. They are relative to the beginning of the entire physical disk.
The ''relative sector'' and number of sector fields are set up differently depending on what System ID byte is used. If 01h, 04h, 06h, or 07h is in the ''System ID'' field for that extended partition entry (pointer to the logical block device), the relative sector field is set up as an offset from (and including) the start of the extended boot record for the associated extended volume. The number of sectors field is filled in with the size of the created logical block device area (that is, the number of sectors mapped out by the start and stop cylinder/track/sector fields). The size of the extended volume can be calculated by adding the relative sector field and the sector size field of the associated extended boot record.
If the System ID byte is 05h, then the relative sector field is the offset (of the next extended volume) in sectors from the start of the entire extended DOS partition The number of sectors field is not used in this field, and is filled with 00hs.
This architecture allows only one logical block device to be defined for each extended boot record. Therefore, a maximum of two partition entries at a time is used in each extended boot record - an entry with System ID byte of 01h, 04h, 06h, or 07h, and an entry with ID of 05h (which is the pointer to the next extended volume).
Although only two entries can be used, a program installing these devices does not assume that the first two entries will be the non-zero entries.
===Installing Block Devices in the Extended DOS Partition===
To install block devices, physical device drivers first install the primary DOS partitions on all physical drives, if any exist. This ensures that an existing drive letter, D:, on the 81h drive remains the same. After these devices are installed on the 80h drive, the drivers look for the existence of the extended DOS partition. If one exists, then the physical device drivers look at the first sector of the extended DOS partition for the first extended boot record. If there is a valid System ID (01h, 04h, 06h, or 07h) in any of the four partition entries, the device is installed and assigned the next available drive letter. This occurs before any CONFIG. SYS device drivers are loaded, so the FDISK will correctly display the drive letter when space is allocated for the drive.
The first extended boot record (in the extended DOS partition) is a special case, because it is possible there will not be a device to be installed defined in the partition table. The first device might have been created and then deleted at some time. However, the first extended boot record is needed to point to the next one, if one exists. Any other extended boot record will always have a device to be installed.
Once a device has been installed (or the special cases above occur), the physical device driver searches the other partition entries for a System ID byte of 05h, indicating that another device (extended volume) exists. If a 05h is not found, there are no more logical block devices (extended volumes) in the extended DOS partition.
If a 05h System ID is found, the start location in that partition entry is read in order to find the location of the next extended boot record. When located, it is read in, and then the process is repeated in order to install additional devices.
Once all the valid devices for a physical drive have been installed, the next physical drive is examined and the entire process is repeated.
A device driver does not assume any order dependency when searching for a particular System ID byte in an extended boot record. All four possible entries in an extended boot record partition table are searched, before a driver decides that a particular System ID byte does not exist.
The extended DOS partition can only be created if a primary DOS or IFS partition already exists on a bootable drive. A primary DOS partition has a System ID of 01h, 04h, or 06h. A primary IFS partition has a System ID of 07h. If the drive is not bootable, an extended DOS partition can be created without having a primary DOS partition. The extended DOS partition starts and ends on a cylinder boundary.
===Creating Block Devices in the Extended DOS Partition===
To create the structure for an extended volume in the extended DOS partition, FDISK determines if there is available space in the extended DOS partition and if less than 24 total devices are allocated in the system. The maximum number of block devices allowed is 26, and two are used by diskettes, A: and B:. The program then creates an extended boot record at the space located, with a partition entry filled in (with the size and location information) for that logical block device. If this is not the first extended boot record, the program backs up to the last extended boot record in the chain (as linked by the 05h entries), and creates a partition entry in that extended boot record that has the size and location data for the newly created record. This action creates the pointer required to locate the newly created boot record.
If this is the first extended boot record in the extended DOS partition only the size, type, and location of the logical block device needs to be put into a partition entry. The start of the extended DOS partition in the Master Boot Record serves as a pointer to this extended volume.
===Deleting Block Devices in the Extended DOS Partition===
To delete a block device, the program sets the 16-byte partition entry that contained the System ID byte, to 0. If in the same extended boot record there exists a partition entry with System ID of 05h, indicating that another extended volume exists, this information is copied to the 05h partition entry of the previous extended boot record. (See the following figure for further information.)
Note: There is one exception to this rule. If the deleted logical block device is at the beginning of the extended DOS partition, only the partition entry indicating the device type is set to 0. The 05h pointer information is to be left in place.
<pre>
          /-------------------------------------\
          |  Master Boot Record......Note 1.... |
          |..................../----------------|
          |............Note 2 �|4 |2 |5 |0 |55AA|  Note 3
          |-------------------------------------|
          | Primary DOS Partition Note 4        |
          |    DOS C: drive  32MB � Size        |
          |-------------------------------------|
          |  Other Operating System Partition  |
          |            (XENIX)    Note 5        |    E
E  /--  |-------------------------------------| --\ x
x  |    | Extended Boot Record..Note 6........|  | t
t  |    |..................../----------------|  |
    |    |............Note 7 �|4 |5 |0 |0 |55AA|  | V
D  |    |-------------------------------------|  | o
O  |    | LOGICAL Block Device D:      Note 8 |  | l
S  |    | 32MB � Size � 16MB or IFS          |  | u
    |    |-------------------------------------| --/ m
P  |    | Extended Boot Record..Note 9........|    e
a  |    |..................../----------------|
r  |    |...........Note 10 �|1 |5 |0 |0 |55AA|
t  |    |-------------------------------------|
i  |    | LOGICAL Block Device E:            |
t  |    | Size � 16MB                        |
i  |    |-------------------------------------|
o  |    | Extended Boot Record................|
n  |    |..................../----------------|
    |    |...........Note 11 �|6 |5 |0 |0 |55AA|
    |    |-------------------------------------|
    |    | Area reserved for future CP/DOS use |
    |    |          Note 12                  |
    |    |-------------------------------------|
    |    | Extended Boot Record................|
    |    |..................../----------------|
    |    |...........Note 13 �|4 |0 |0 |0 |55AA|
    |    |-------------------------------------|
    |    | LOGICAL Block Device G:            |
    |    | 32MB � Size � 16MB                  |
    |    |-------------------------------------|
    |    | Free Space in Extended Partition    |
    \--  |-------------------------------------|
          | Free Space not allocated to any    |
          | partition                          |
          \-------------------------------------/
</pre>
;Note 1
:Master Boot Record code, starting at Track 000, Head 00, Sector 01 of disk 80h or 81h.
;Note 2
:Partition table for Master Boot Record. See BPB and Get Device Parameters for Extended Volumes for the layout. The 4 is the System ID byte in the partition table that indicates a DOS partition greater than 16MB and less than or equal to 32MB. The 2 is a XENIX XENIX** partition, and the 05h maps the extended DOS partition.
;Note 3
:55AAh is the signature to validate the Master Boot Record.
;Note 4
:Primary DOS area, which must reside entirely in first 32MB of the disk. C: is block device 80h. D: is block device 81h, if it exists. This partition has a maximum size of 32MB.
;Note 5
:Other operating system on disk.
;Note 6
:Extended boot record for extended volume that corresponds to logical block device D:. (This assumes only the 80h block device exists.) If the 81h block device exists, this would be block device E:.
;Note 7
:Logical block device D: partition table entry. This has a maximum size of 32MB, which is indicated by the System ID of 4. This must set the logical DOS block device as starting at the next track boundary. The 05h System ID byte in the second partition entry maps out the space allocated to the next extended volume. The starting cylinder/sector/head in the partition entry with an ID of 05h is the location of the next extended boot record of the next extended volume.
;Note 8
:Logical block device D:. Logical DOS devices and the primary DOS partition always begin with a DOS boot record.
;Note 9
:Extended boot record for logical block device E:.
;Note 10
:Partition table entry for logical block device E:. This logical DOS block device is less than or equal to 16MB, as indicated by the System ID of 01h. The entry with System ID of 05h maps out the space allocated to the next extended volume.
;Note 11
:The System ID byte of 06h indicates a logical block device greater than 32MB. This block device is indicated by a block device letter of F. Note also that a pointer to the next extended volume exists.
;Note 12
:The greater than 32MB FAT partition.
;Note 13
:Partition table entry for final DOS logical block device. Note that the absence of the 05h ID byte means that there are no other extended volumes allocated in the extended DOS partition. This would have a block device letter of G:, if the previous logical block device was recognized. Otherwise, it would be F:.
<pre>
Offs Purpose                            Head  Sector  Cylinder
                            /---------------------------------\
1BE Partition 1 begin        | boot ind |  H  |  S  |  CYL    |
                            |----------+-----+-----+----------|
1C2 Partition 1 end          | syst ind |  H  |  S  |  CYL    |
                            |----------------+----------------|
1C6 Partition 1 rel sect    | Low word      | High word      |
                            |----------------+----------------|
1CA Partition 1 #sects      | Low word      | High word      |
                            |----------------+----------------|
1CE Partition 2 begin        | boot ind |  H  |  S  |  CYL    |
                            |----------+-----+-----+----------|
1D2 Partition 2 end          | syst ind |  H  |  S  |  CYL    |
                            |----------------+----------------|
1D6 Partition 2 rel sect    | Low word      | High word      |
                            |----------------+----------------|
1DA Partition 2 #sects      | Low word      | High word      |
                            |----------------+----------------|
1DE Partition 3 begin        | boot ind |  H  |  S  |  CYL    |
                            |----------+-----+-----+----------|
1E2 Partition 3 end          | syst ind |  H  |  S  |  CYL    |
                            |----------------+----------------|
1E6 Partition 3 rel sect    | Low word      | High word      |
                            |----------------+----------------|
1EA Partition 3 #sects      | Low word      | High word      |
                            |----------------+----------------|
1EE Partition 4 begin        | boot ind |  H  |  S  |  CYL    |
                            |----------+-----+-----+----------|
1F2 Partition 4 end          | syst ind |  H  |  S  |  CYL    |
                            |----------------+----------------|
1F6 Partition 4 rel sect    | Low word      | High word      |
                            |----------------+----------------|
1FA Partition 4 #sects      | Low word      | High word      |
                            |----------------+----------------/
1FE Signature                |                |
                            \----------------/
</pre>
===BPB and Get Device Parameters for Extended Volumes===
For purposes of the BIOS Parameter Block (BPB) and Get Device Parameters (generic IOCtl), an extended volume appears to the system as a fixed disk. The extended boot record corresponds to the Master Boot Record of a real fixed disk and the logical block device corresponds to the primary DOS partition.
This means the BPB of the logical DOS block device of the extended volume describes the environment in the extended volume. This consists of the extended boot record and the logical block device. The meaning of the fields is consistent with the meaning of the fields for the primary DOS partition; they relate to the entire physical disk, the primary DOS partition, and the Master Boot Record. For example, the number of hidden sectors is the distance from the beginning of the extended boot record (of the extended volume in question) to the start of the logical DOS block device (the DOS Boot Record). The number of sectors field describes only the logical block device, just as it normally only describes the primary DOS partition.
;Category 08h Generic IOCtl Commands
The philosophy described above also applies to the disk generic IOCtl commands. For any logical block device of an associated extended volume, physical cylinder, head, and sector I/O is mapped to within the extended volume - Cylinder 0, Head 0, Sector 1 is mapped to the extended boot record. An error condition is generated for any attempt to do C,H,S I/O beyond the size of the extended volume in question.
;Category 09h Generic IOCtl Commands
Category 09h generic IOCtl commands are used to access the entire physical fixed disk without consideration of logical volumes. Physical cylinder, head, and sector begin at the start of the physical drive, instead of at the beginning of an extended volume.
;Type 6 Partition
A 12-bit or 16-bit type FAT can be used to map a Type 6 partition because the type of FAT is based strictly on the number of allocation units ( clusters), and is the same algorithm used to define the type of FAT in the OS/2 Version 1.0 operating system. FAT cluster sizes are based on powers of 2. Assuming usage of the OS/2 FORMAT utility, the minimum cluster size for a hard file is 2KB. Cluster size and the type of FAT (12-bit verses 16 -bit) are determined by the media partition size. The OS/2 FORMAT algorithm is:
<pre>
If partition size =<16MB
then;
    use 12-bit FAT;              /* max 4084 entries    */
    max cluster size = 4KB;
end;
else;                            /* partition size >16MB */
    use 16-bit FAT;              /* max 64KB entries    */
    min cluster size = 2KB;
end;
</pre>
The actual determination of the partition type is made based on the number of clusters on that partition. OS/2 FORMAT makes sure that this is true for the &lt;16MB and >16MB partitions.
<pre>
If number of clusters &lt;= 4084
    use 12-bit FAT;              /* max 4084 entries  */
else
    use 16-bit FAT;              /* max 64KB entries  */
</pre>
A partition size of 128MB requires a 2KB cluster size, based on a maximum of 64KB allocation units (clusters). A partition size in the range of 129MB and 256MB requires a 4KB cluster size, based on 64KB allocation units. A partition size in the range of 257MB and 512MB requires an 8KB cluster size, based on 64KB allocation units.
The configuration table used by OS/2 FORMAT is show in the following table:
<pre>
|Total # of    |Size of        |Sector Cluster |# of Root DIR  |
|Sectors        |Partition      |              |Entries        |
|---------------+---------------+---------------+---------------|
|32K            |16MB          |8              |512            |
|---------------+---------------+---------------+---------------|
|64K            |32MB          |4              |512            |
|---------------+---------------+---------------+---------------|
|256K          |128MB          |4              |512            |
|---------------+---------------+---------------+---------------|
|512K          |256MB          |8              |512            |
|---------------+---------------+---------------+---------------|
|1M            |512MB          |16            |512            |
|---------------+---------------+---------------+---------------|
|2M            |1GB            |32            |512            |
|---------------+---------------+---------------+---------------|
|4M            |2GB            |64            |512            |
|---------------+---------------+---------------+---------------|
|8M            |4GB            |128            |512            |
</pre>
'''Note:''' For Type 6 partitions, it is safe to use a non-default configuration, but this might be unsafe for other partition types.
The partition can reside anywhere on the media, as the primary DOS partition, or as an extended volume within the extended DOS partition. The BPB parameter number of sectors per FAT field width has been extended from a byte to a WORD, in order to define a full 128KB FAT structure. This change affects all DOS partition types.
''Layout of Block Devices with a Type 6 Partition Using XENIX''
<pre>
          /-------------------------------------\
          |  Master Startup Record...Note 1.... |
          |..................../----------------|
          |...........Note 2 � |2 |6 |0 |0 |55AA|  Note 3
          |-------------------------------------|
          |  Other Operating System Partition  |
          |          (XENIX)                    |
          |    Size � 32MB  Note 4            |
          |-------------------------------------|
          | Primary DOS Partition Note 5        |
          |    DOS C: drive  32MB � Size        |
          |-------------------------------------|
          |            Free Space              |
          |  (not allocated to any partition)  |
          \-------------------------------------/
</pre>
;Note 1
:Master Startup (Boot) Record code, starting at Track 000, Head 00, Sector 01 of disk 80h or 81h.
;Note 2
:Partition table for Master Startup (Boot) Record. The 2 is the System ID byte in the partition table that indicates a XENIX partition, and the 06h map indicates a primary DOS Type 6 partition.
;Note 3
:55AAH is the signature to validate the Master Startup (Boot) Record.
;Note 4
:Other operating system (XENIX) on disk.
;Note 5
:Primary DOS partition. C: is block device 80h. The partition type in this example is a 6, because it ends beyond the first 32MB of the disk. Within the scope of this definition, though the size of a primary DOS partition can be less than 32MB (because it ends beyond the first 32MB of the disk), it is defined as a Type 6.
''Layout of Block Devices with a Type 6 Partition''
<pre>
          /-------------------------------------\
          |  Master Startup Record...Note 1.... |
          |..................../----------------|
          |...........Note 2 � |6 |0 |0 |0 |55AA|  Note 3
          |-------------------------------------|
          | Primary DOS Partition Note 4        |
          |    DOS C: drive  Size � 32MB        |
          \-------------------------------------/
</pre>
;Note 1
:Master Startup (Boot) Record code, starting at Track 000, Head 00, Sector 01 of disk 80h or 81h.
;Note 2
:Partition table for Master Boot Record. The 6 is the System ID byte in the partition table that indicates a DOS partition where SIZE > 32MB.
;Note 3
:55AAh is the signature to validate the Master Startup (Boot) Record.
;Note 4
:Primary DOS area. Owns the entire media and exceeds 32MB in size. C: is block device 80h.
''Type 7 Partition''
Partition Type 7 is used for Installable File Systems only. The internal FAT file system should not use this partition type because older versions of the DOS and OS/2 operating systems will not be able to access the partition.
==[[Extended Device Driver Interface Specification]]==
==I/O Request Block - C Definitions==
Following are the I/O request block C language definitions for ADD device support.
<pre>
/*static char *SCCSID = "@(#)iorb.h    6.2 92/02/20";*/
/****************************************************************************/
/* I/O Request Block (IORB) Structures                                      */
/****************************************************************************/
/* ASM
      Resolve H2INC references for .INC version of file
      include  iorbtype.inc
*/
/* Typedefs to resolve forward references                                  */
typedef struct _IORBH        IORBH;
typedef struct _IORBH        FAR *PIORBH;
typedef struct _IORBH        *NPIORBH;
typedef struct _IORBH        FAR *PIORB;
typedef struct _IORBH        *NPIORB;
typedef struct _DEVICETABLE  DEVICETABLE;
typedef struct _DEVICETABLE  FAR *PDEVICETABLE;
typedef struct _DEVICETABLE  *NPDEVICETABLE;
typedef struct _UNITINFO      UNITINFO;
typedef struct _UNITINFO      FAR *PUNITINFO;
typedef struct _UNITINFO      *NPUNITINFO;
typedef struct _ADAPTERINFO  ADAPTERINFO;
typedef struct _ADAPTERINFO  FAR *PADAPTERINFO;
typedef struct _ADAPTERINFO  *NPADAPTERINFO;
typedef struct _GEOMETRY      GEOMETRY;
typedef struct _GEOMETRY      FAR *PGEOMETRY;
typedef struct _GEOMETRY      *NPGEOMETRY;
typedef struct _SCATGATENTRY  SCATGATENTRY;
typedef struct _SCATGATENTRY  FAR *PSCATGATENTRY;
typedef struct _SCATGATENTRY  *NPSCATGATENTRY;
/*--------------------------------------------------------------------------*/
/* Interface for calling ADD entry point                                    */
/*--------------------------------------------------------------------------*/
/* VOID FAR *(ADDEP) (PIORBH);                                              */
/*--------------------------------------------------------------------------*/
/* IORB Header                                                              */
/*--------------------------------------------------------------------------*/
#define DM_WORKSPACE_SIZE      20
#define ADD_WORKSPACE_SIZE      16
typedef struct _IORBH  {            /* IOH                                */
USHORT        Length;                /* IORB length                        */
USHORT        UnitHandle;            /* Unit identifier                    */
USHORT        CommandCode;            /* Command code                      */
USHORT        CommandModifier;        /* Command modifier                  */
USHORT        RequestControl;        /* Request control flags              */
USHORT        Status;                /* Status                            */
USHORT        ErrorCode;              /* Error code                        */
ULONG        Timeout;                /* Cmd completion timeout(s)          */
USHORT        StatusBlockLen;        /* Status block length                */
NPBYTE        pStatusBlock;          /* Status block                      */
USHORT        Reserved_1;            /* Reserved, MBZ                      */
PIORB        pNxtIORB;              /* Pointer to next IORB              */
PIORB        (FAR *NotifyAddress)(PIORB); /* Notification address          */
UCHAR        DMWorkSpace[DM_WORKSPACE_SIZE];  /* For use by DM            */
UCHAR        ADDWorkSpace[ADD_WORKSPACE_SIZE]; /* For use by ADD          */
} IORBH;
/*--------------------------------------------------------------------------*/
/* IORB CommandCode and CommandModifier Codes                              */
/*      Note:  CommandCodes are prefixed by IOCC and CommandModifiers      */
/*            by IOCM.                                                    */
/*--------------------------------------------------------------------------*/
                                          /*--------------------------------*/
                                          /* +----M=Mandatory support      */
                                          /* |    O=Optional support        */
                                          /* |                              */
                                          /* V    Notes                    */
                                          /*--------------------------------*/
#define IOCC_CONFIGURATION        0x0001  /*                                */
#define IOCM_GET_DEVICE_TABLE    0x0001  /* M                              */
#define IOCM_COMPLETE_INIT        0x0002  /* O                              */
                                  /*----------------------------------------*/
#define IOCC_UNIT_CONTROL        0x0002  /*                                */
#define IOCM_ALLOCATE_UNIT        0x0001  /* M                              */
#define IOCM_DEALLOCATE_UNIT      0x0002  /* M                              */
#define IOCM_CHANGE_UNITINFO      0x0003  /* M                              */
/*----------------------------------------*/
#define IOCC_GEOMETRY            0x0003  /*                                */
#define IOCM_GET_MEDIA_GEOMETRY  0x0001  /* M                              */
#define IOCM_SET_MEDIA_GEOMETRY  0x0002  /* O (M) >1 media type            */
#define IOCM_GET_DEVICE_GEOMETRY  0x0003  /* M                              */
#define IOCM_SET_LOGICAL_GEOMETRY 0x0004  /* O (M) CHS addressable          */
                                  /*----------------------------------------*/
#define IOCC_EXECUTE_IO          0x0004  /*                                */
#define IOCM_READ                0x0001  /* M                              */
#define IOCM_READ_VERIFY          0x0002  /* M                              */
#define IOCM_READ_PREFETCH        0x0003  /* O                              */
#define IOCM_WRITE                0x0004  /* M                              */
#define IOCM_WRITE_VERIFY        0x0005  /* M                              */
                                  /*----------------------------------------*/
#define IOCC_FORMAT              0x0005  /*                                */
#define IOCM_FORMAT_MEDIA        0x0001  /* O (M) If HW requires          */
#define IOCM_FORMAT_TRACK        0x0002  /* O (M) If HW requires          */
#define IOCM_FORMAT_PROGRESS      0x0003  /* O                              */
#define IOCC_UNIT_STATUS          0x0006  /*                                */
#define IOCM_GET_UNIT_STATUS      0x0001  /* M                              */
#define IOCM_GET_CHANGELINE_STATE 0x0002  /* O (Mandatory for diskette)    */
#define IOCM_GET_MEDIA_SENSE      0x0003  /* O (Mandatory for diskette)    */
#define IOCM_GET_LOCK_STATUS      0x0004  /* M                              */
                                  /*----------------------------------------*/
#define IOCC_DEVICE_CONTROL      0x0007  /*                                */
#define IOCM_ABORT                0x0001  /* O (M) SCSI                    */
#define IOCM_RESET                0x0002  /* O (M) SCSI                    */
#define IOCM_SUSPEND              0x0003  /* O (M) Floppy driver            */
#define IOCM_RESUME              0x0004  /* O (M) Floppy driver            */
#define IOCM_LOCK_MEDIA          0x0005  /* M (O) Fixed media only        */
#define IOCM_UNLOCK_MEDIA        0x0006  /* M (O) Fixed media only        */
#define IOCM_EJECT_MEDIA          0x0007  /* M (O) SCSI and Floppy Driver  */
                                  /*----------------------------------------*/
#define IOCC_ADAPTER_PASSTHRU    0x0008  /*                                */
#define IOCM_EXECUTE_SCB          0x0001  /* O                              */
#define IOCM_EXECUTE_CDB          0x0002  /* O (M) SCSI adapters            */
                                  /*----------------------------------------*/
#define MAX_IOCC_COMMAND  IOCC_ADAPTER_PASSTHRU
/*--------------------------------------------------------------------------*/
/* Status flags returned in IORBH->Status                                  */
/*--------------------------------------------------------------------------*/
#define IORB_DONE                0x0001  /* 1=Done,  0=In progress          */
#define IORB_ERROR              0x0002  /* 1=Error, 0=No error            */
#define IORB_RECOV_ERROR        0x0004  /* Recovered error                */
#define IORB_STATUSBLOCK_AVAIL  0x0008  /* Status block available          */
/*--------------------------------------------------------------------------*/
/* Error Codes returned in IORBH->ErrorCode                                */
/*--------------------------------------------------------------------------*/
#define IOERR_RETRY                    0x8000
#define IOERR_CMD                      0x0100
#define IOERR_CMD_NOT_SUPPORTED        IOERR_CMD+1
#define IOERR_CMD_SYNTAX                IOERR_CMD+2
#define IOERR_CMD_SGLIST_BAD            IOERR_CMD+3
#define IOERR_CMD_SW_RESOURCE          IOERR_CMD+IOERR_RETRY+4
#define IOERR_CMD_ABORTED              IOERR_CMD+5
#define IOERR_CMD_ADD_SOFTWARE_FAILURE  IOERR_CMD+6
#define IOERR_CMD_OS_SOFTWARE_FAILURE  IOERR_CMD+7
#define IOERR_UNIT                      0x0200
#define IOERR_UNIT_NOT_ALLOCATED        IOERR_UNIT+1
#define IOERR_UNIT_ALLOCATED            IOERR_UNIT+2
#define IOERR_UNIT_NOT_READY            IOERR_UNIT+3
#define IOERR_UNIT_PWR_OFF              IOERR_UNIT+4
#define IOERR_RBA                      0x0300
#define IOERR_RBA_ADDRESSING_ERROR      IOERR_RBA+IOERR_RETRY+1
#define IOERR_RBA_LIMIT                IOERR_RBA+2
#define IOERR_RBA_CRC_ERROR            IOERR_RBA+IOERR_RETRY+3
#define IOERR_MEDIA                    0x0400
#define IOERR_MEDIA_NOT_FORMATTED      IOERR_MEDIA+1
#define IOERR_MEDIA_NOT_SUPPORTED      IOERR_MEDIA+2
#define IOERR_MEDIA_WRITE_PROTECT      IOERR_MEDIA+3
#define IOERR_MEDIA_CHANGED            IOERR_MEDIA+4
#define IOERR_MEDIA_NOT_PRESENT        IOERR_MEDIA+5
#define IOERR_ADAPTER                  0x0500
#define IOERR_ADAPTER_HOSTBUSCHECK      IOERR_ADAPTER+1
#define IOERR_ADAPTER_DEVICEBUSCHECK    IOERR_ADAPTER+IOERR_RETRY+2
#define IOERR_ADAPTER_OVERRUN          IOERR_ADAPTER+IOERR_RETRY+3
#define IOERR_ADAPTER_UNDERRUN          IOERR_ADAPTER+IOERR_RETRY+4
#define IOERR_ADAPTER_DIAGFAIL          IOERR_ADAPTER+5
#define IOERR_ADAPTER_TIMEOUT          IOERR_ADAPTER+IOERR_RETRY+6
#define IOERR_ADAPTER_DEVICE_TIMEOUT    IOERR_ADAPTER+IOERR_RETRY+7
#define IOERR_ADAPTER_REQ_NOT_SUPPORTED IOERR_ADAPTER+8
#define IOERR_ADAPTER_REFER_TO_STATUS  IOERR_ADAPTER+9
#define IOERR_ADAPTER_NONSPECIFIC      IOERR_ADAPTER+10
#define IOERR_DEVICE                    0x0600
#define IOERR_DEVICE_DEVICEBUSCHECK    IOERR_DEVICE+IOERR_RETRY+1
#define IOERR_DEVICE_REQ_NOT_SUPPORTED  IOERR_DEVICE+2
#define IOERR_DEVICE_DIAGFAIL          IOERR_DEVICE+3
#define IOERR_DEVICE_BUSY              IOERR_DEVICE+IOERR_RETRY+4
#define IOERR_DEVICE_OVERRUN            IOERR_DEVICE+IOERR_RETRY+5
#define IOERR_DEVICE_UNDERRUN          IOERR_DEVICE+IOERR_RETRY+6
#define IOERR_DEVICE_RESET              IOERR_DEVICE+7
#define IOERR_DEVICE_NONSPECIFIC        IOERR_DEVICE+8
/*--------------------------------------------------------------------------*/
/* Request Control flags in IORBH->RequestControl                          */
/*--------------------------------------------------------------------------*/
#define IORB_ASYNC_POST        0x0001  /* Asynchronous post enabled      */
#define IORB_CHAIN              0x0002  /* IORB chain link enabled        */
#define IORB_CHS_ADDRESSING    0x0004  /* CHS fmt addr in RBA field      */
#define IORB_REQ_STATUSBLOCK    0x0008  /* Obtain status block data        */
#define IORB_DISABLE_RETRY      0x0010  /* Disable retries in ADD          */
/*--------------------------------------------------------------------------*/
/* ADAPTER CONFIGURATION IORB        (for IOCC_CONFIGURATION)              */
/*--------------------------------------------------------------------------*/
typedef struct _IORB_CONFIGURATION  {  /* IOCFG                            */
  IORBH            iorbh;              /* IORB header                      */
  DEVICETABLE far *pDeviceTable;        /* Far pointer to adapt. dev. table */
  USHORT          DeviceTableLen ;    /* Length of adapter device table  */
} IORB_CONFIGURATION, FAR *PIORB_CONFIGURATION, *NPIORB_CONFIGURATION;
/* Adapter device table returned by GET_DEVICE_TABLE                        */
typedef struct _DEVICETABLE  {            /* IODT                          */
  UCHAR        ADDLevelMajor;            /* ADD major support level        */
  UCHAR        ADDLevelMinor;            /* ADD minor support level        */
  USHORT        ADDHandle;                /* ADD handle                    */
  USHORT        TotalAdapters;            /* Number of adapters supported  */
  NPADAPTERINFO pAdapter [1];            /* Array of adapter info pointers */
} DEVICETABLE, FAR *PDEVICETABLE;
/*--------------------------------------------------------------------------*/
/* Current ADD Level for DEVICETABLE->AddLevelMajor, AddLevelMinor          */
/*--------------------------------------------------------------------------*/
#define  ADD_LEVEL_MAJOR        0x01
#define  ADD_LEVEL_MINOR        0x00
typedef struct _UNITINFO  {              /* IOUI                          */
  USHORT    AdapterIndex;                  /* nth adapter this driver      */
  USHORT    UnitIndex;                    /* nth unit on this card        */
  USHORT    UnitFlags;                    /* Unit flags                    */
  USHORT    Reserved;                      /* Reserved ; must be 0          */
  USHORT    UnitHandle;                    /* Assigned by ADD or filter    */
  USHORT    FilterADDHandle;              /* Handle of filter ADD 0 = None */
  USHORT    UnitType;                      /* Unit type                    */
  USHORT    QueuingCount;                  /* Recommended number to queue  */
  UCHAR    UnitSCSITargetID;              /* SCSI target ID (SCSI only)    */
  UCHAR    UnitSCSILUN;                  /* SCSI log. unit (SCSI only)    */
} UNITINFO;
/*--------------------------------------------------------------------------*/
/* Unit Flags for UNITINFO->UnitFlags                                      */
/*--------------------------------------------------------------------------*/
#define UF_REMOVABLE    0x0001            /* Media can be removed.        */
#define UF_CHANGELINE    0x0002            /* ChangeLine supported          */
#define UF_PREFETCH      0x0004            /* Supports prefetch read        */
#define UF_A_DRIVE      0x0008            /* Manages A:                    */
#define UF_B_DRIVE      0x0010            /* Manages B:                    */
#define UF_NODASD_SUPT  0x0020            /* Suppress DASD Mgr support.    */
#define UF_NOSCSI_SUPT  0x0040            /* Suppress SCSI Mgr support.    */
#define UF_DEFECTIVE    0x0080            /* Device is defective.          */
/*--------------------------------------------------------------------------*/
/* Unit Types for UNITINFO->UnitType                                        */
/*--------------------------------------------------------------------------*/
#define  UIB_TYPE_DISK      0x0000        /* All direct access devices    */
#define  UIB_TYPE_TAPE      0x0001        /* Sequential access devices    */
#define  UIB_TYPE_PRINTER  0x0002        /* Printer device                */
#define  UIB_TYPE_PROCESSOR 0x0003        /* Processor type device        */
#define  UIB_TYPE_WORM      0x0004        /* Write Once/Read Many device  */
#define  UIB_TYPE_CDROM    0x0005        /* CD ROM device                */
#define  UIB_TYPE_SCANNER  0x0006        /* Scanner device                */
#define  UIB_TYPE_OPTICAL_MEMORY 0x0007/* Some optical disk                */
#define  UIB_TYPE_CHANGER  0x0008    /* Changer device (such as juke box) */
#define  UIB_TYPE_COMM      0x0009    /* Communication devices            */
typedef struct _ADAPTERINFO  {        /* IOAI                              */
  UCHAR            AdapterName [17];  /* Adapter name ASCIIZ string        */
  UCHAR            Reserved;          /*                                  */
  USHORT          AdapterUnits;      /* Number of units this adapter      */
  USHORT          AdapterDevBus;      /* Bus Type - Adapter to device      */
  UCHAR            AdapterIOAccess;    /* I/O Type - Adapter to host        */
  UCHAR            AdapterHostBus;    /* Bus Type - Adapter to host        */
  UCHAR            AdapterSCSITargetID;/* Adapter SCSI target ID            */
  UCHAR            AdapterSCSILUN;    /* Adapter SCSI LUN                  */
  USHORT          AdapterFlags;
  USHORT          MaxHWSGList;        /* Max HW S/G list entries          */
  ULONG            MaxCDBTransferLength;/* Max data length for CDBs        */
  UNITINFO        UnitInfo [1];      /* Unit info for each unit          */
} ADAPTERINFO;
/*--------------------------------------------------------------------------*/
/* Adapter Flags for ADAPTERINFO->AdapterFlags                              */
/*--------------------------------------------------------------------------*/
#define AF_16M              0x0001        /* Supports > 16M addresses      */
#define AF_IBM_SCB          0x0002        /* Supports IBM SCB commands    */
#define AF_HW_SCATGAT        0x0004        /* Supports scatter/gather in HW */
#define AF_CHS_ADDRESSING    0x0008        /* Supports CHS addressing in HW */
#define AF_ASSOCIATED_DEVBUS 0x0010        /* Supports > 1 Device Bus      */
/*--------------------------------------------------------------------------*/
/* Adapter-to-Device protocol for ADAPTERINFO->AdapterDevBus                */
/*--------------------------------------------------------------------------*/
#define AI_DEVBUS_OTHER          0x0000
#define AI_DEVBUS_ST506          0x0001    /* ST-506 CAM-I                */
#define AI_DEVBUS_ST506_II        0x0002    /* ST-506 CAM-II                */
#define AI_DEVBUS_ESDI            0x0003    /* ESDI                        */
#define AI_DEVBUS_FLOPPY          0x0004    /* Diskette                    */
#define AI_DEVBUS_SCSI_1          0x0005
#define AI_DEVBUS_SCSI_2          0x0006
#define AI_DEVBUS_SCSI_3          0x0007
#define AI_DEVBUS_NONSCSI_CDROM  0x0008  /* Non-SCSI CD-ROM interface bus */
/*--------------------------------------------------------------------------*/
/* Note: One of the following BUS WIDTH indicators must be                  */
/*      OR'd with the above field.                                        */
/*--------------------------------------------------------------------------*/
#define  AI_DEVBUS_FAST_SCSI      0x0100
#define  AI_DEVBUS_8BIT          0x0200
#define  AI_DEVBUS_16BIT          0x0400
#define  AI_DEVBUS_32BIT          0x0800
/*--------------------------------------------------------------------------*/
/* Adapter-to-Device protocol for ADAPTERINFO->AdapterIOAccess              */
/*--------------------------------------------------------------------------*/
#define  AI_IOACCESS_OTHER      0x00
#define  AI_IOACCESS_BUS_MASTER 0x01
#define  AI_IOACCESS_PIO        0x02
#define  AI_IOACCESS_DMA_SLAVE  0x04
#define  AI_IOACCESS_MEMORY_MAP 0x08
/*--------------------------------------------------------------------------*/
/* Adapter-to-Host bus type for ADAPTERINFO->AdapterHostBus                */
/*--------------------------------------------------------------------------*/
#define  AI_HOSTBUS_OTHER      0x00
#define  AI_HOSTBUS_ISA        0x01
#define  AI_HOSTBUS_EISA        0x02
#define  AI_HOSTBUS_uCHNL      0x03
#define  AI_HOSTBUS_UNKNOWN    0x0f
/*--------------------------------------------------------------------------*/
/* Note: One of the following BUS WIDTH indicators must be                  */
/*      OR'd with the above field.                                        */
/*--------------------------------------------------------------------------*/
#define  AI_BUSWIDTH_8BIT      0x10
#define  AI_BUSWIDTH_16BIT      0x20
#define  AI_BUSWIDTH_32BIT      0x30
#define  AI_BUSWIDTH_64BIT      0x40
#define  AI_BUSWIDTH_UNKNOWN    0xf0
/****************************************************************************/
/* UNIT CONTROL IORB                  (for IOCC_UNIT_CONTROL)              */
/****************************************************************************/
typedef struct _IORB_UNIT_CONTROL  {    /* IOUC                            */
  IORBH            iorbh;                /* IORB Header                    */
  USHORT          Flags;                /*                                */
  PUNITINFO        pUnitInfo;            /* For: IOCM_CHANGE_UNITINFO      */
  USHORT          UnitInfoLen;          /* Length of UnitInfo structure    */
} IORB_UNIT_CONTROL, FAR *PIORB_UNIT_CONTROL, *NPIORB_UNIT_CONTROL;
/****************************************************************************/
/* DASD GEOMETRY IORB                      (for IOCC_GEOMETRY)              */
/****************************************************************************/
typedef struct _IORB_GEOMETRY  {        /* IOGG                            */
  IORBH            iorbh;                /* IORB header                    */
  PGEOMETRY        pGeometry;            /* Far pointer to GEOMETRY block  */
  USHORT          GeometryLen;          /* Length of GEOMETRY block        */
} IORB_GEOMETRY, FAR *PIORB_GEOMETRY, *NPIORB_GEOMETRY;
typedef struct _GEOMETRY  {              /* IOG                            */
  ULONG      TotalSectors;
  USHORT    BytesPerSector;
  USHORT    Reserved;
  USHORT    NumHeads;
  ULONG      TotalCylinders;
  USHORT    SectorsPerTrack;
} GEOMETRY, FAR *PGEOMETRY, *NPGEOMETRY;
/****************************************************************************/
/* Scatter/Gather List Entry                                                */
/****************************************************************************/
typedef struct _SCATGATENTRY  {          / *  IOSG                        */
  ULONG          ppXferBuf;              /* Physical pointer to xfer buffer    */
  ULONG          XferBufLen;              /* Length of transfer buffer          */
} SCATGATENTRY, FAR *PSCATGATENTRY, *NPSCATGATENTRY;
#define MAXSGLISTSIZE    (sizeof(SCATGATENTRY)) * 16
/****************************************************************************/
/* EXECUTE_IO IORB                    (for IOCC_EXECUTE_IO)                */
/****************************************************************************/
typedef struct  _IORB_EXECUTEIO  {              /* IOXIO                          */
  IORBH          iorbh;              /* IORB header                                */
  USHORT          cSGList;            /* Count of S/G list elements                */
  PSCATGATENTRY  pSGList;            /* Far pointer to s/g list                */
  ULONG          ppSGList;          /* Phys. address of S/G list              */
  ULONG          RBA;                /* RBA starting address                      */
  USHORT          BlockCount;        /* Block count                                */
  USHORT          BlocksXferred;      /* Block done count                          */
  USHORT          BlockSize;          /* Size of a block in bytes                  */
  USHORT          Flags;
} IORB_EXECUTEIO, FAR *PIORB_EXECUTEIO, *NPIORB_EXECUTEIO;
/****************************************************************************/
/* CHS Direct Addressing (Overlays RBA field)                              */
/****************************************************************************/
typedef struct _CHS_ADDR    {        /* IOCHS                                      */
  USHORT          Cylinder;
  UCHAR          Head;
  UCHAR          Sector;
}  CHS_ADDR, FAR *PCHS_ADDR, *NPCHS_ADDR;
/*--------------------------------------------------------------------------*/
/* IORB specific flags for IORB EXECUTE_IO->Flags                          */
/*--------------------------------------------------------------------------*/
#define XIO_DISABLE_HW_WRITE_CACHE        0x0001
#define XIO_DISABLE_HW_READ_CACHE        0x0002
/****************************************************************************/
/* FORMAT IORB                          (for IOCC_FORMAT)                  */
/****************************************************************************/
typedef struct _IORB_FORMAT    {          /* IOFMT                                */
  IORBH          iorbh;                    /* IORB Header                        */
  USHORT          cSGList;                  /* Count of S/G list elements        */
  PSCATGATENTRY  pSGList;                  /* Far pointer to s/g list            */
  ULONG          ppSGList;                  /* Phys. address of S/Glist          */
  USHORT          FormatCmdLen;              /*                                    */
  PBYTE          pFormatCmd;                /* SCSI CDB or track fmt cmd          */
  UCHAR          Reserved_1 [8];            /* Reserved; must not be modified    */
}  IORB_FORMAT, FAR *PIORB_FORMAT, *NPIORB_FORMAT;
typedef struct _FORMAT_CMD_TRACK  {        /* FMCT                                */
  USHORT          Flags;
  ULONG          RBA;
  USHORT          cTrackEntries;
} FORMAT_CMD_TRACK, FAR *PFORMAT_CMD_TRACK, *NPFORMAT_CMD_TRAC ;
/*--------------------------------------------------------------------------*/
/* Flags for FORMAT_CMD_TRACK->Flags                                        */
/*--------------------------------------------------------------------------*/
#define FF_VERIFY      0x0001          /* Verify sectors after formatting. */
/****************************************************************************/
/* ADAPTER PASS THROUGH IORB          (for IOCC_ADAPTER_PASSTHRU)          */
/****************************************************************************/
typedef struct _IORB_ADAPTER_PASSTHRU  { /* IOPT                            */
  IORBH        iorbh;                  /* IORB header                      */
  USHORT        cSGList;                /* Count of S/G list elements      */
  PSCATGATENTRY pSGList;                /* Far pointer to s/g list          */
  ULONG        ppSGLIST;              /* Phys. address of S/G list        */
  USHORT        ControllerCmdLen;
  PBYTE        pControllerCmd;
  ULONG        ppSCB;      /* Phys. pointer to SCB for SCB_PASSTHRU      */
  USHORT        Flags;
} IORB_ADAPTER_PASSTHRU, FAR *PIORB_ADAPTER_PASSTHRU, *NPIORB_ADAPTER_PASSTHRU;
/*--------------------------------------------------------------------------*/
/* IORB specific flags for IORB_ADAPTER_PASSTHRU->Flags                    */
/*                                                                          */
/* Note: These flags apply to IOCM_EXECUTE_CDB.                            */
/*--------------------------------------------------------------------------*/
#define PT_DIRECTION_IN    0x0001      /* Data xfer to host adapter        */
/****************************************************************************/
/* UNIT STATUS IORB                  (for IOCC_UNIT_STATUS)                */
/****************************************************************************/
typedef struct _IORB_UNIT_STATUS  {    /* IOUS                            */
  IORBH        iorbh ;
  USHORT      UnitStatus ;
} IORB_UNIT_STATUS, FAR *PIORB_UNIT_STATUS, *NPIORB_UNIT_STATUS;
/*--------------------------------------------------------------------------*/
/* Unit Status for IORB_UNIT_STATUS->UnitStatus                            */
/*                                                                          */
/* Note: These flags apply to IOCM_GET_UNIT_STATUS                          */
/*--------------------------------------------------------------------------*/
#define US_READY                0x0001    /* Unit ready                    */
#define US_POWER                0x0002    /* Unit powered on                */
#define US_DEFECTIVE            0x0004    /* Unit operational              */
/*--------------------------------------------------------------------------*/
/* Unit Status for IORB_UNIT_STATUS->UnitStatus                            */
/*                                                                          */
/* Note: These flags apply to IOCM_GET_CHANGELINE_STATE                    */
/*--------------------------------------------------------------------------*/
#define US_CHANGELINE_ACTIVE    0x0001    /* ChangeLine state              */
/*--------------------------------------------------------------------------*/
/* Unit Status for IORB_UNIT_STATUS->UnitStatus                            */
/*                                                                          */
/* Note: These flags apply to IOCM_GET_MEDIA_SENSE                          */
/*--------------------------------------------------------------------------*/
#define US_MEDIA_UNKNOWN        0x0000    /* Unable to determine media    */
#define US_MEDIA_720KB          0x0001    /* 720KB in 3.5" drive          */
#define US_MEDIA_144MB          0x0002    /* 1.44MB in 3.5" drive          */
#define US_MEDIA_288MB          0x0003    /* 2.88MB in 3.5" drive          */
/****************************************************************************/
/* DEVICE CONTROL IORB                (for IOCC_DEVICE_CONTROL            */
/****************************************************************************/
typedef struct _IORB_DEVICE_CONTROL    {  /* IODC                          */
  IORBH      iorbh;                        /* IORB header                  */
  USHORT    Flags;
  USHORT    Reserved;
} IORB_DEVICE_CONTROL, FAR *PIORB_DEVICE_CONTROL, *NPIORB_DEVICE_CONTROL;
/*--------------------------------------------------------------------------*/
/* IORB-specific flags for IORB_DEVICE_CONTROL->Flags                      */
/*                                                                          */
/* Note: These flags apply to IOCM_SUSPEND                                  */
/*--------------------------------------------------------------------------*/
#define DC_SUSPEND_DEFERRED    0x0000    /* Suspend after device idle        */
#define DC_SUSPEND_IMMEDIATE    0x0001    /* Suspend after current request    */
#define MAX_IORB_SIZE  128
</pre>
==[[OS/2 SCSI Device Driver Interface Specification]]==
==[[Advanced SCSI Programming Interface (ASPI) OS/2 Specification]]==
==[[Adapter Device Driver Interface Questions and Answers]]==
==[[Device Driver Test Tool (DDTT)]]==
==Notices==
==Notices==
'''Fifth Edition (September 1997)'''
'''Fifth Edition (September 1997)'''

Latest revision as of 06:40, 7 October 2022

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

About This Book

The Storage Device Driver Reference provides a simplified programming interface to expedite the development of DASD, SCSI, and CD-ROM device driver support for the IBM OS/2 product.

Frequently, original equipment manufacturers (OEMs) develop device support to drive only their own unique device interfaces and the support may be hardware-dependent. The programming interfaces described in this reference categorize the DASD, SCSI, and CD-ROM device-driver modules as hardware-dependent or hardware-independent. Hardware-independent modules can be linked dynamically with hardware-dependent modules for a given workstation configuration.

Summary of Changes

The following changes have been made:

  • Added a new chapter, Optical IOCtl Device Driver Test Tool.
  • Removed chapters on Device Driver Test Tools, which described the 16-bit support: DASD IOCtl, DASD ADD, SCSI IOCtl, SCSI ADD, and CD-ROM.
  • Added replacement chapters, describing the 32-bit support, for DASD IOCtl and CD-ROM Device Driver Test Tools.

How This Book is Organized

A glossary and an index appear at the back of the book.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DDSC, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:

Internet: ibmsdp@vnet.ibm.com
US/Canada: 800-627-8363
International: 770-835-9902
International Fax: 770-835-9444

Notices

Fifth Edition (September 1997)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

Copyright Notices

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface. Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved." (C) Copyright International Business Machines Corporation 1997. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594 U.S.A.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

AIX
AT
Common User Access CUA
IBM Micro Channel
Multimedia Presentation Manager/2
OS/2
Personal System/2 PS/2
SAA
Series/1
Systems Application Architecture

The following terms are trademarks of other companies:

Adaptec Adaptec, Inc.
APM Astek International Ltd.
Apple Apple Computer, Inc.
Hitachi Hitachi Ltd.
Intel Intel Corporation
MSCDEX Microsoft Corporation
NEC NEC Corporation
Novell Novell, Inc.
Photo CD Eastman Kodak Company
RIPL CTA Incorporated
SCO The Santa Cruz Operation, Inc.
Sony Sony Corporation
Toshiba Toshiba Corporation
UNIX Unix System Laboratories, Inc.
XENIX Microsoft Corporation
Retrieved from "https://www.edm2.com/index.php?title=Storage_Device_Driver_Reference&oldid=78758"