Storage Device Driver Reference
By IBM
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
- #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.
- 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.
- 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.
- 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.
- 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.
- 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 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.
- 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.
- Extended Device Driver Interface Specification describes the supports for servicing fixed disk devices.
- I/O Request Block - C Definitionslists 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.
- 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.
- 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.
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
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:
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:
| 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:
| 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:
| 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:
BASEDEV= ---- filename ---------------------|
\-- arguments --/
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.
(BASEDEV= Load Ordering by File Extension) .SYS (processed first) .BID .VSD | .TSD | .ADD | .I13 .FLT .DMD (processed last)
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:
| 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:
*******************************************************************
* *
* 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.
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
DASD, SCSI, and CD-ROM Device Manager Interface Specification
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.
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
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
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
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)
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
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 datathat indicates a successful command completion.
IOERR_CMD_ADD_SOFTWARE_FAILURE
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
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
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
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
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
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)
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
This error indicates that the specified RBA exceeded the allowable maximum for the media currently in the device.
IOERR_RBA_CRC_ERROR(retry required)
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
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
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
This error indicates that either the media or the drive is Write protected or that the media is not writable.
IOERR_MEDIA_CHANGED
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
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
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)
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)
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)
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
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)
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)
This error indicates the failure of a device to respond to the host adapter .
IOERR_ADAPTER_REQ_NOT_SUPPORTED
This error indicates that the requested operation or function is not supported by this adapter.
IOERR_ADAPTER_REFER_TO_STATUS
This error indicates that the reported error could not be classified. Additional information can be provided in the IORB StatusBlockfield 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)
This error should be reported when an ADD cannot classify an adapter- related error condition and an IORB StatusBlockvalue is not provided. If an IORB StatusBlockvalue 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)
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
This error indicates that the requested operation or function is not supported by this device.
IOERR_DEVICE_DIAGFAIL
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)
This error indicates that the device is busy and cannot accept the requested operation. This error includes, but is not limited to, SCSI Contingent Allegianceconditions.
IOERR_DEVICE_OVERRUN(retry required)
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)
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)
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)
This error should be returned when the ADD cannot classify a device-related error and an IORB StatusBlockvalue was not supplied. If an IORB StatusBlockvalue 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)
|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 |
Flags
Flags contain bit flags indicating the validity of other fields within the SCSI Status Block.
|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. |
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 "GOOD" 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:
BASEDEV=AddName.ADD──►
──►Driver-Parameters──►Adapter-Parameters──►Unit-Parameters─┬┐
▲ ▲ ││
│ └─────────────────┘│
└───────────────────────────────────────┘
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.
*The alphabetic dcharacter (<d>) indicates a decimal digit.
*The alphabetic hcharacter (<h>) indicates a hexadecimal digit.
Command-Line Parameter Classes
An adapter device driver command line contains three classes of parameters:
- Adapter Device Driver Parameters
Adapter device driver parametersapply to all adapters and units managed by an adapter device driver unless overridden by adapter parameters or unit parameters. - Adapter Parameters
Adapter parametersbegin with the (/A) switch and identify a specific adapter card. Parameters following the (/A) switch apply only to the adapter card indicated. - Unit Parameters
Unit parametersapply 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:
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) ──┘│
└─── , ───┘
Note: All SCSI adapter device drivers must support the following parameters:
/V Verbose
/A Adapter Identification
/DM Enable/Disable DASD Manager Support
/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
/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:
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
/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 <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, <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:
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 ───┘
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:
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 ─────────────────────┘││
│ └───────────────────────────────────┘│
└───────────────────────────────────────────────┘
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:
BASEDEV=IBM1S506.ADD /V /A:1 /I BASEDEV=MOREDASD.ADD BASEDEV=IBM1S506.ADD /V /A:0 /I
/<!>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 "Sector Sparing" may be lost after a reset. Setting this switch is recommended for ESDI adapters with disks formatted using "Sector Sparing." /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 < 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
Optical IOCtl Device Driver Test Tool
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:
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) |
\------------------------/ \-------------------------/
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.
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
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:
[C:\]md tstcdrom [C:\]cd tstcdrom [C:\tstcdrom]copy e:\ddk\testcert\storage\function\cdrom\* [C:\tstcdrom]copy e:\ddk\testcert\general\ddtt\*
- 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
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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DEVICENAME |STRING |Drive letter of | | | |CD-ROM | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |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. | \--------------------------------------------------------------/
- Logged Data
None.
CDROM_CLOSE
This function closes the CD-ROM.
- Input Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |BYTESPERSECTOR |NUM |Sector size in bytes| |--------------------+--------------------+--------------------| |LARGESECTORS |NUM |Media sector count. | |--------------------+--------------------+--------------------| |DEVICETYPE |NUM |Device code | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |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 | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- Logged Data
None.
CDROM_LOCKDOOR
Category 80h Function 46h - Lock Door This function locks the CD-ROM drive door.
- Required Input Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- Logged Data
None.
CDROM_UNLOCKDOOR
Category 80h Function 46h - Unlock Door This function unlocks the CD-ROM drive door.
- Required Input Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |HIGHTRACK |NUM |Highest track number| |--------------------+--------------------+--------------------| |LOWTRACK |NUM |Lowest track number | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |PAUSE |NUM |Pause bit Where: | | | |0=not paused | | | |1=paused | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |SECTORSIZE |NUM |Bytes per sector | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |VOLSIZE |NUM |Disc sector count | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | |--------------------+--------------------+--------------------| |TRACK |NUM |Track number | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |STATUS |NUM |Status bits | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |TRACK |NUM |Current track number| |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |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| \--------------------------------------------------------------/
- 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
/--------------------------------------------------------------\
|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
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- Logged Data
None.
CDROM_RESET
Category 80h Function 40h - Reset Drive
This function resets and reinitializes the drive and controller.
- Required Input Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- Logged Data
None.
CDROM_STOPAUDIO
Category 81h Function 51h - Stop Audio
This function cancels any active play request.
- Required Input Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | \--------------------------------------------------------------/
- Output Parameter Keywords
/--------------------------------------------------------------\ |Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code| \--------------------------------------------------------------/
- 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
|Keyword |Type |Description |--------------------+--------------------+---------------- |DRIVEHANDLE |NUM |Drive handle for | | |CD-ROM drive
- Output Parameter Keywords
|Keyword |Type |Description |--------------------+--------------------+-------------------- |CDRC |NUM |Function return code
- 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
| 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
- Output Parameter Keywords
| Keyword | 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
|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
- Output Parameter Keywords
|Keyword |Type |Description |--------------------+--------------------+-------------------- |CDRC |NUM |Function return code
- 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
|Keyword |Type |Description |--------------------+--------------------+---------------- |DRIVEHANDLE |NUM |Drive handle for | | |CD-ROM drive |--------------------+--------------------+---------------- |ADDRESSMODE |STRING |Addressing mode: | | |LOGICAL BLOCK or | | |REDBOOK
EXAMPLES: Logical Block
ADDRESSMODE=LOGICALBLOCK
Redbook
ADDRESSMODE=REDBOOK
- Output Parameter Keywords
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code|
- 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
|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 |
- Optional Input Parameter Keywords
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |BUFFER |STRING |Buffer name |
- Output Parameter Keywords
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code|
- 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
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |DRIVEHANDLE |NUM |Drive handle for | | | |CD-ROM drive | |--------------------+--------------------+--------------------| |SECTORSTART |NUM |Starting sector to | | | |read | |--------------------+--------------------+--------------------| |SECTORCOUNT |NUM |Number of sectors to| | | |read |
- Optional Input Parameter Keywords
|Keyword |Type |Description |
|--------------------+--------------------+--------------------|
|BUFFER |STRING |Buffer name |
EXAMPLE:
Logical Block
BUFFER=ALPHA
SECTORSTART=20000
SECTORCOUNT=10000
- Output Parameter Keywords
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code|
- 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
|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 |
- Optional Input Parameter Keywords
|Keyword |Type |Description |
|--------------------+--------------------+--------------------|
|BUFFER |STRING |Buffer name |
EXAMPLE:
Logical Block
ADDRESSMODE=LOGICALBLOCK
BUFFER=ALPHA
SECTORSTART=20000
SECTORCOUNT=10000
- Output Parameter Keywords
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code|
- 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
|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
- Output Parameter Keywords
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |CDRC |NUM |Function return code|
- 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
|Keyword |Type |Description | |--------------------+--------------------+--------------------| |READMODE |STRING |RAW or COOKED buffer| |--------------------+--------------------+--------------------| |$BUFFER |NUM |Buffer reference | |--------------------+--------------------+--------------------| |$SECTOR |NUM |Expected sector | | | |value
- 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
| 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
| 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:
SET TMP=E:\
3. NMAKE the following makefiles in the DDK:
SRC\DEV\VDISK\MAKEFILE CD\DDK\SRC\DEV\VDISK NMAKE
OS2DASD.DMD - Technical Reference
Boot Record Architecture
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.
/*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
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
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