═══ 1. Notices ═══ Third Edition (September 1994) 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 authorized reseller or IBM marketing representative. ═══ 1.1. 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 1994. 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. ═══ 1.2. 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 IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. 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 the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. ═══ 1.3. Trademarks ═══ The following terms are trademarks of the IBM Corporation in the United States or other countries: 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 ═══ 2. 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. ═══ 2.1. Summary of Changes ═══ The following changes have been made to the Storage Device Driver Reference since the release of IBM Device Driver Source Kit for OS/2, Version 1.2: o The TESTCFG IOCtls can now be found in OS/2 Physical Device Driver Reference. o Chapters on Device Driver Test Tools have been added (DASD IOCtl, DASDADD, SCSI IOCtl, SCSI ADD, and CD-ROM). o Source Code for ASPI has been included (see Advanced SCSI Programming Interface (ASPI) OS/2 Specification). o An appendix has been added to explain the Device Driver Test Tool. ═══ 2.1.1. 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. DASD ADD Device Driver Test Tool discusses the DASD ADD Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the Inter-Device-Driver Communication (IDC) interface of DASD drivers. The tests are implemented with the Device Driver Test Tool. SCSI IOCtl Device Driver Test Tool discusses the SCSI IOCtl Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the interface of SCSI device drivers. The tests are implemented with the Device Driver Test Tool. SCSI ADD Device Driver Test Tool discusses the Inter-Device-Driver Communication Interface (IDC) defined for the interface of SCSI Adapter 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 Definitions lists the I/O request block C language definitions for adapter device driver device support. OS/2 SCSI Device Driver Interface Specification describes the high-level interface for the SCSI device driver for OS/2. All functions are listed. 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. Using the 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. ═══ 2.2. Assistance ═══ Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS) known as the "DUDE." You are encouraged to use the DUDE 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 DUDE, dial 407-982-3217 (using a modem) to register and access the support system. For voice support in the United States, call 407-982-4239. Additional assistance is available through the IBM Developer Assistance Program. For membership information: Telephone: 407-982-6408 Fax: 407-988-7610 (U.S.A.) or Fax: 407-982-4259 (worldwide) ═══ 2.3. Ordering Information ═══ For an illustration of OS/2 Technical Publications and other related product documents, see the following figure. The IBM Developer Connection Device Driver Kit for OS/2 on CD-ROM contains actual source code for sample device drivers, as well as the complete text of the books in online form. To order any of the publications shown in the illustration, call: ┌────────────────────┬─────────────────────┬─────────────────────┐ │U.S.A.: │1-800-633-8266 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Canada: │1-800-561-5293 │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Europe, Middle East,│ English language │(+45) 48101500 │ │Africa, and │ French language │(+45) 48101200 │ │Latin America: │ Italian language │(+45) 48101600 │ │ │ German language │(+45) 48101000 │ │ │ Spanish language │(+45) 48101100 │ │ │ Dutch language │(+45) 48101400 │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Asia/Pacific: │ All except Japan │(61) 2-354-7684 │ │ │ Japan │(81) 3-3495-2045(Fax)│ │ │ │Fax request to: │ │ │ │DAP-J, IBM Japan │ ├────────────────────┼─────────────────────┼─────────────────────┤ │SE Brazil: │(021) 800-6120(Voice)│ │ │ │(021) 800-6936(Fax) │ │ ├────────────────────┼─────────────────────┼─────────────────────┤ │Mexico: │ Mexico City │627-2444 │ │ │ Country │91-800-00639 │ └────────────────────┴─────────────────────┴─────────────────────┘ ═══ 3. 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: o Device drivers can be written in the C programming language. o 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. o Facilitate development of a new DASD, SCSI, or CD-ROM driver for a specific bus interface. o Relatively complex OS/2 kernel interfaces are replaced with a single interface. o Independent development organizations are better able to reuse existing DASD device driver code. o 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: o Device managers o Adapter device drivers o 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. ═══ 3.1. 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 │OS/2 SCSI Device Driver │ │ │drivers │Specification │ ├─────────────────┼──────────────────┼─────────────────────────┤ │OS2ASPI.DMD │ASPI option │Advanced SCSI Programming│ │ │drivers │Interface │ ├─────────────────┼──────────────────┼─────────────────────────┤ │OS2CDROM.DMD │CD-ROM File System│OS/2 CD-ROM Interface │ └─────────────────┴──────────────────┴─────────────────────────┘ ═══ 3.2. 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. ═══ 3.3. Filter Device Drivers ═══ Filter device drivers are a special class of device drivers that provide the following: o Generic value-added services, such as data stripping or encryption o 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 │ │ └─────────────────┴───────────────────────────────────────────┘ ═══ 4. 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: o The ability to install and, subsequently, start up from a DASD device that requires an OEM-specific adapter device driver interface o 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. ═══ 4.1. 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. ═══ 4.2. 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 │Supported Device Managers │ │Driver │ │ ├────────────────────┼──────────────────────────────────────────────────┤ │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. ═══ 4.2.1. 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. ═══ 4.2.2. 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: o Determines CPU host bus type o Reads adapter ROM space o Executes IN/OUT instruction o 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. ═══ 4.2.3. 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 ────────────────────────────────────────────────────────────────────────── where 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. ────────────────────────────────────────────────────────────────────────── ═══ 4.2.4. 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. ═══ 5. Adapter Device Driver Development Considerations ═══ Adapter device drivers are packaged as 16-bit OS/2 device drivers. This chapter describes how adapter device drivers differ from installable OS/2 device drivers. ═══ 5.1. Loading and Initialization ═══ Adapter device drivers are loaded using the BASEDEV= statement in CONFIG.SYS. The processing of these statements occurs before the operating system is fully initialized. The adapter device driver writer must be aware of the following differences between installable device drivers and adapter device drivers: o Adapter device drivers initialize at Ring 0 rather than Ring 3. Generally, this does not cause any problems. However, adapter device drivers cannot use the DOSxxx APIs available to installable device drivers during initialization. To display a message, an adapter device driver must use the DevHlp_Save_Message service. o INIT request packet command code The INIT request packet command code for all base device drivers (which include all adapter device drivers) is hex 1B rather than hex 0. o Device Driver Header An adapter device driver must identify itself as a participant in the adapter device driver strategy by setting the following bits to 1 in the device driver header. The bit-numbering convention is that bit 15 is the most significant bit in a WORD, and bit 31 is the most significant bit in a DWORD. - Device attribute field - Bits 15, 8, 7 Bit 15 indicates CHARACTER device driver. Bits 8 and 7 define driver as a Level 3 device driver, which indicates usage of the DWORD capabilities bit strip in the header file. - Capabilities Bit Strip - Bit 3 Bit 3 indicates that the driver is participating in the adapter device driver strategy which, in turn, selects an alternate INIT request packet format from the kernel. o INIT request packet format The INIT request packet for a driver that has identified itself as an adapter device driver (through bits set in the device driver header as just described) corresponds to the RPINITIN structure defined in REQPKT.H, supplied with the IBM Developer Connection Device Driver Kit for OS/2. The InitArgs member of the RPINITIN structure points to the following structure, defined in DSKINIT.H in the kit. ────────────────────────────────────────────────────────────────────────── typedef struct _DDD_PARM_List { /* DDPL */ USHORT reserved1; /* Reserved */ USHORT disk_config_table; /* Address of config table */ USHORT reserved2; /* Reserved */ USHORT cmd_line_args; /* Address of command line parm */ USHORT machine_config_table; /* Address of config info */ } DDD_Parm_List, FAR *PDD_Parm_List; ────────────────────────────────────────────────────────────────────────── By following the appropriate pointers in the DDD_Parm_List, the driver writer can obtain BASEDEV= command-line parameters, as well as information collected during system initialization. o Adapter device drivers process a limited set of OS/2 kernel request packets. With the exception of the OS/2 system kernel initialization request packet just described and vendor-defined IOCtls, adapter device drivers must reject all other kernel request packets. The primary interface to adapter device drivers is defined in this reference. o Adapter device drivers register their entry points using the DevHlp service. Adapter device drivers register their main entry points with the the OS/2 kernel using the DevHlp_RegisterDeviceClass service. See DASD, SCSI, and CD-ROM Device Manager Interface Specification for details. The table of registered entry points is available to other adapter device drivers and device managers that can call an adapter device driver directly. o Adapter device drivers must declare a valid character device name in their headers. The OS/2 kernel treats the name in the adapter device driver header as a valid character device name. Adapter device drivers must end their device names with a dollar sign ($) to avoid conflict with valid file names. o Adapter device drivers must fail quietly when hardware is not found. Adapter device drivers should check for the presence of their hardware interface at initialization time. If it is not found, the adapter device driver must set the ERROR_I24_QUIET_INIT_FAIL flags (as defined in BSEERR.H) in the Status field of the request packet. ═══ 5.2. Operation ═══ Adapter device drivers receive commands through an I/O request block (IORB) entry point. The format of IORB commands received by an adapter device driver is defined in this reference. Adapter device drivers have full use of both the 16-bit and 32-bit DevHlp services defined in OS/2 operating system. Although the adapter device driver to DM interface is 16-bit, adapter device drivers can manipulate 32-bit objects with assembly subroutines. The service request entry point of an adapter device driver can be called in either kernel (also known as task) or interrupt contexts. Consequently, an adapter device driver must never block while servicing a request after it has completed initialization. (An adapter device driver can block at initialization.) Service requests that involve time delays normally are initiated by the adapter device driver; then, the adapter device driver immediately returns to its caller. Service request completion is indicated to the caller using asynchronous callback notification. ═══ 5.3. Command-Line Parameters ═══ To facilitate the parsing of command-line parameters, and to help encourage uniformity in command-line syntax, a parser/tokenizer is provided in the IBM Developer Connection Device Driver Kit for OS/2. In addition, a command-line syntax definition is provided in Adapter Device Driver Command-Line Parameters. The output of the parser/tokenizer is a stream of tokens that represents the contents of the command line. The parser/tokenizer performs preliminary syntactical checks on the command line and indicates the results of these checks by the return code. However, the adapter device driver must ensure that the tokenized parameters' values are acceptable. The adapter device driver is responsible for displaying error messages as appropriate. OEMs can modify the parser and included tables to add their own adapter-unique flags and parameters. ═══ 6. DASD, SCSI, and CD-ROM Device Manager Interface Specification ═══ The IBM OS/2 2.0 (and later) DASD and SCSI device manager interface consists of direct call commands and Device Helper (DevHlp) services. ═══ 6.1. Direct Call Command Interface ═══ All direct call commands are issued by the device managers (OS2DASD.DMD and OS2SCSI.DMD) or filter device drivers to an adapter device driver's registered entry point, with a global pointer to the Input/Output Request Block (IORB), as follows: C Language Syntax ────────────────────────────────────────────────────────────────────────── #include VOID (FAR * ADDEntryPoint) (piorb); PIORB piorb; /* Far pointer to the IORB control block */ ────────────────────────────────────────────────────────────────────────── Assembly Language Syntax ────────────────────────────────────────────────────────────────────────── #include ; ** ES:BX = IORB Pointer PUSH es ; IORB Segment PUSH bx ; IORB Offset CALL dword ptr AddEntryPoint ; Call adapter device driver ADD sp, 4 ; Clean-up stack ────────────────────────────────────────────────────────────────────────── Results The results of the command are returned in the IORB. The following table categorizes and lists the direct call commands used for the DASD and SCSI device manager interface: ┌────────────────────────┬────────────────────────────────────┐ │Command Type │Commands │ ├────────────────────────┼────────────────────────────────────┤ │CONFIGURATION │ │ │ │GET_DEVICE_TABLE │ │ │COMPLETE_INIT │ ├────────────────────────┼────────────────────────────────────┤ │UNIT_CONTROL │ │ │ │ALLOCATE_UNIT │ │ │DEALLOCATE_UNIT │ │ │CHANGE_UNITINFO │ ├────────────────────────┼────────────────────────────────────┤ │GEOMETRY │ │ │ │GET_MEDIA_GEOMETRY │ │ │SET_MEDIA_GEOMETRY │ │ │GET_DEVICE_GEOMETRY │ │ │SET_LOGICAL_GEOMETRY │ ├────────────────────────┼────────────────────────────────────┤ │EXECUTE_IO │ │ │ │READ │ │ │READ_VERIFY │ │ │READ_PREFETCH │ │ │WRITE │ │ │WRITE_VERIFY │ ├────────────────────────┼────────────────────────────────────┤ │FORMAT │ │ │ │FORMAT_MEDIA │ │ │FORMAT_TRACK │ │ │FORMAT_PROGRESS │ ├────────────────────────┼────────────────────────────────────┤ │UNIT_STATUS │ │ │ │GET_UNIT_STATUS │ │ │CHANGELINE_STATE │ │ │GET_MEDIA_SENSE │ │ │GET_LOCK_STATUS │ ├────────────────────────┼────────────────────────────────────┤ │DEVICE_CONTROL │ │ │ │ABORT │ │ │RESET │ │ │SUSPEND │ │ │RESUME │ │ │LOCK_MEDIA │ │ │UNLOCK_MEDIA │ │ │EJECT_MEDIA │ ├────────────────────────┼────────────────────────────────────┤ │ADAPTER_PASSTHRU │ │ │ │EXECUTE_SCB │ │ │EXECUTE_CDB │ └────────────────────────┴────────────────────────────────────┘ DevHlp services introduced with the OS/2 2.0 operating system to support this strategy include: o RegisterDeviceClass o GetDOSVar ═══ 6.2. IORB Control Blocks ═══ All direct call command control blocks are defined in the IBM-supplied IORB.H and IORB.INC Include files. (See I/O Request Block - C Definitions.) The following sections, which describe the commands and their associated control blocks, are written from both C and assembler programmers' points of view, with references to the actual Include files and field names. ═══ 6.2.1. IORB General Format ═══ The IORB is the main control block for all direct call commands. To accommodate varying command-specific data, there are eight types of IORBs, one per CommandCode, as shown in the following table. ┌──────────────────────────────┬──────────────────────────────┐ │IORB Type │CommandCode │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_CONFIGURATION │IOCC_CONFIGURATION │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_UNIT_CONTROL │IOCC_UNIT_CONTROL │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_GEOMETRY │IOCC_GEOMETRY │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_EXECUTE_IO │IOCC_EXECUTE_IO │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_FORMAT │IOCC_FORMAT │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_UNIT_STATUS │IOCC_UNIT_STATUS │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_DEVICE_CONTROL │IOCC_DEVICE_CONTROL │ ├──────────────────────────────┼──────────────────────────────┤ │IORB_ADAPTER_PASSTHRU │IOCC_ADAPTER_PASSTHRU │ └──────────────────────────────┴──────────────────────────────┘ Each IORB consists of a common I/O Request Block Header (IORBH data structure), followed by unique command-specific data, as shown in the following table. ┌──────────────────────┬──────────┬─────────┬───────────────────┐ │Field Name │C Type │Length │Description │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Length │USHORT │DW │Length of IORB │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │UnitHandle │USHORT │DW │Unit handle │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │CommandCode │USHORT │DW │Command code │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │CommandModifier │USHORT │DW │Command modifier │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │RequestControl │USHORT │DW │Flags │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Status │USHORT │DW │Status │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │ErrorCode │USHORT │DW │Error code │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Timeout │ULONG │DD │Completion timeout │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │StatusBlockLen │USHORT │DW │Length of status │ │ │ │ │info │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │pStatusBlock │NPBYTE │DW │Pointer to status │ │ │ │ │info │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │Reserved_1 │USHORT │DW │Reserved │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │pNxtIORB │PIORB │DD │Pointer to next │ │ │ │ │IORB │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │NotifyAddress │(*PFN)( ) │DD │Notification │ │ │ │ │address │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │DMWorkSpace[20] │UCHAR │DB(20) │Reserved │ ├──────────────────────┼──────────┼─────────┼───────────────────┤ │ADDWorkSpace[16] │UCHAR │DB(16) │adapter device │ │ │ │ │driver work area │ └──────────────────────┴──────────┴─────────┴───────────────────┘ On entry to the driver: Length is set to the total length of the IORB (IORBH plus Command-Specific Data) in bytes. UnitHandle identifies the adapter device driver's unit for which the request is intended. The adapter device driver must assign a unique UnitHandle in the DEVICETABLE UNITINFO structure for each of the units it manages. Refer to the IOCC_CONFIGURATION CommandCode section for additional information. CommandCode/CommandModifier contains the direct call commands. These commands are grouped by CommandCode as shown in the following table. The CommandCode field defines the IORB; the CommandModifier field selects the actual operation within a specified CommandCode. For details on each of the commands, refer to their corresponding CommandCode sections. ┌────────────────────────┬────────────────────────────────────┐ │CommandCode │CommandModifier │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_CONFIGURATION │ │ │ │IOCM_GET_DEVICE_TABLE │ │ │IOCM_COMPLETE_INIT │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_UNIT_CONTROL │ │ │ │IOCM_ALLOCATE_UNIT │ │ │IOCM_DEALLOCATE_UNIT │ │ │IOCM_CHANGE_UNITINFO │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_GEOMETRY │ │ │ │IOCM_GET_MEDIA_GEOMETRY │ │ │IOCM_SET_MEDIA_GEOMETRY │ │ │IOCM_GET_DEVICE_GEOMETRY │ │ │IOCM_SET_LOGICAL_GEOMETRY │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_EXECUTE_IO │ │ │ │IOCM_READ │ │ │IOCM_READ_VERIFY │ │ │IOCM_READ_PREFETCH │ │ │IOCM_WRITE │ │ │IOCM_WRITE_VERIFY │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_FORMAT │ │ │ │IOCM_FORMAT_MEDIA │ │ │IOCM_FORMAT_TRACK │ │ │IOCM_FORMAT_PROGRESS │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_UNIT_STATUS │ │ │ │IOCM_GET_UNIT_STATUS │ │ │IOCM_GET_CHANGELINE_STATE │ │ │IOCM_GET_MEDIA_SENSE │ │ │IOCM_GET_LOCK_SENSE │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_DEVICE_CONTROL │ │ │ │IOCM_ABORT │ │ │IOCM_RESET │ │ │IOCM_SUSPEND │ │ │IOCM_RESUME │ │ │IOCM_LOCK_MEDIA │ │ │IOCM_UNLOCK_MEDIA │ │ │IOCM_EJECT_MEDIA │ ├────────────────────────┼────────────────────────────────────┤ │IOCC_ADAPTER_PASSTHRU │ │ │ │IOCM_EXECUTE_SCB │ │ │IOCM_EXECUTE_CDB │ └────────────────────────┴────────────────────────────────────┘ RequestControl contains flags which control the processing of the IORB, as shown in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │IORB_ASYNC_POST │Command-completion protocol. This │ │ │ADD will always return immediately, │ │ │as this is an asynchronous protocol │ │ │requiring ASYNC_NOTIFY to be set. If│ │ │set, this flag indicates that the │ │ │NotifyAddress field is valid and │ │ │that the adapter device driver │ │ │should call this routine when the │ │ │IORB request is completed. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_CHAIN │IORB chaining. If set, this flag │ │ │indicates that the pNxtIORB field is│ │ │valid and that there is a chained │ │ │IORB command to service. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_CHS_ADDRESSING │I/O addressing format. If set, this│ │ │flag indicates that the command's │ │ │RBA field is in the format defined │ │ │by the CHS_ADDR structure. This bit│ │ │should be set only for diskette │ │ │controllers. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_REQ_STATUSBLOCK │Request for status information. If │ │ │set, this flag indicates that the │ │ │StatusBlockLen and pStatusBlock │ │ │fields are valid and that the │ │ │adapter device driver should return │ │ │the command's associated status │ │ │information. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_DISABLE_RETRY │No error retry. If set, this flag │ │ │indicates that the adapter device │ │ │driver should not retry the request │ │ │if a processing error occurs. │ └────────────────────────┴────────────────────────────────────┘ For more information about chained IORBs (IORB_CHAIN), see Adapter Device Driver Interface Questions and Answers. Status equals 0 on entry. Upon exit from the adapter device driver, Status contains flags to indicate the command's completion status. (See the following table.) ┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │IORB_DONE │Processing complete. If set, this │ │ │flag indicates that the adapter │ │ │device driver has completed │ │ │processing the request. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_ERROR │Error encountered. If set, this │ │ │flag indicates that an error │ │ │occurred while processing the │ │ │request. This flag should not be │ │ │set if the error was successfully │ │ │recovered by the adapter device │ │ │driver. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_RECOV_ERROR │Recoverable error. If set, this │ │ │flag indicates that, although an │ │ │error occurred, the adapter device │ │ │driver successfully recovered │ │ │through retries. │ ├────────────────────────┼────────────────────────────────────┤ │IORB_STATUSBLOCK_AVAIL │Status information returned. If │ │ │set, this flag indicates that the │ │ │adapter device driver has returned │ │ │status information in the buffer │ │ │defined by pStatusBlock. │ └────────────────────────┴────────────────────────────────────┘ ErrorCode equals 0, on entry. On exit from the driver, it contains the command's completion error code. This field is valid only if the IORB_ERROR flag in the Status field is set. The error codes are summarized in Error Handling. Timeout contains the maximum number of seconds the driver will permit for command completion before timing out. If this field is set to 0, the timeout value assigned is the default set by the driver If this field is set to -1, the timeout value assigned is infinite. The timeout period is measured from the last valid contact (interrupt) with the target device. Therefore, if the device interrupts periodically within the timeout interval, the interval is reset after each interrupt. StatusBlockLen contains the size of the block of storage, in bytes, for the driver to return status information (pStatusBlock). This field is valid only if the IORB_REQ_STATUSBLOCK flag is set in the RequestControl field. pStatusBlock contains a near pointer to a block of storage (length = StatusBlockLength), allocated by the caller, for the driver to return status information. On exit from the driver, the storage area contains status information. This field is valid only if the IORB_REQ_STATUSBLOCK flag is set in the RequestControl field. The format of information in the status block depends on the class of adapters the driver supports. For SCSI devices, see IORB Status Block for more information. Note: The pointer to the status block is a 16-bit near pointer. The status block must reside in the same segment as the IORB. Reserved_1 is reserved for use by the device manager and must not be modified by the adapter device driver. pNxtIORB contains a far pointer to the next IORB for chained commands. This field is valid only if the IORB_CHAIN flag is set in the RequestControl field. NotifyAddress contains a far pointer to the notification routine to be called when the request has completed successfully or aborted due to error conditions. This field is valid only if the IORB_ASYNC_POST flag is set in the RequestControl field. The notification routine should be called with a far pointer to the command's IORB. C Language Syntax ────────────────────────────────────────────────────────────────────────── (FAR *piorb->NotifyAddress) (piorb); ────────────────────────────────────────────────────────────────────────── Assembly Language Syntax ────────────────────────────────────────────────────────────────────────── ; ** ES:BX = IORB Pointer PUSH es ; IORB segment PUSH bx ; IORB offset CALL dword ptr es:[bx+IOH_NotifyAddress] ; Call notify routine add sp, 4 ; Cleanup stack ────────────────────────────────────────────────────────────────────────── Note: The Notify routine will preserve only the DS, ES, SI, and DI registers. DMWorkSpace[20] defines a workspace, for use by the device manager, that must not be modified by the device driver. ADDWorkSpace[16] defines a workspace for the adapter device driver that is ignored by the device manager. Command-Specific Data contains the command-unique parameters. The commands and actual formats of the corresponding IORBs are described in the following sections. ═══ 6.3. IORB CommandCode Format ═══ The IORB CommandCode format is defined in the following section. ═══ 6.3.1. IOCC Configuration ═══ The IOCC_CONFIGURATION CommandCode consists of all the CommandModifiers responsible for returning information about the characteristics of the devices supported by the driver, as follows: IOCM_COMPLETE_INIT Indicates that the driver can complete its initialization phase. In the interval between driver initialization and receipt of this IORB, the device driver must not disable its INT 13h BIOS support because this support is needed to load other components of the operating system. IOCM_GET_DEVICE_TABLE Returns the DEVICETABLE structure in the buffer supplied by the caller. DEVICETABLE contains detailed information on each adapter and the associated units supported by the adapter device driver. Remarks Support: Mandatory Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK Note: Any adapter device driver that registers by way of the RegisterDeviceClass DevHlp must process this IORB and return a valid DEVICETABLE, even if the driver supports 0 adapters. Format of IORB o IORB Type - IORB_CONFIGURATION o IORBH Fields - CommandCode o IOCC_CONFIGURATION - CommandModifiers o IOCM_COMPLETE_INIT o IOCM_GET_DEVICE_TABLE - Valid RequestControl Flags o IORB_ASYNC_POST IORB_CONFIGURATION Description This section defines the IORB_CONFIGURATION control block and the following associated structures: DEVICETABLE Table of supported devices ADAPTERINFO Adapter characteristics UNITINFO Unit characteristics ═══ 6.3.2. DEVICETABLE Structure Overview ═══ ┌──────────────┐ │ pDeviceTable ├───DEVICETABLE └──────────────┘ ┌─────────────────┐ ┌───┤ pAdapter[0] │ │ ├─────────────────┤ │┌──┤ pAdapter[1] │ ││ ├─────────────────┤ ││ │ . . . │ ││ ├─────────────────┤ ││┌─┤ pAdapter[N] │ │││ ├─────────────────┤ ┌───────────┐ └┼┼│ ADAPTERINFO 0 ├────┤ ADAPTER 0 ├┐ ┌────────┐ ││ ├─────────────────┤ └───────────┘├─┤ UNIT 0 │ ││ │ UNITINFO[0] │ │ └────────┘ ││ │ UNITINFO[1] │ │ . . . ││ │ . . . │ │ ┌────────┐ ││ │ UNITINFO[N] │ └─┤ UNIT N │ ││ ├─────────────────┤ └────────┘ ││ ├─────────────────┤ ││ ├─────────────────┤ ┌───────────┐ └┼│ ADAPTERINFO 1 ├────┤ ADAPTER 1 ├┐ ┌────────┐ │ ├─────────────────┤ └───────────┘├─┤ UNIT 0 │ │ │ UNITINFO[0] │ │ └────────┘ │ │ UNITINFO[1] │ │ . . . │ │ . . . │ │ ┌────────┐ │ │ UNITINFO[N] │ └─┤ UNIT N │ │ ├─────────────────┤ └────────┘ │ ├─────────────────┤ │ ├─────────────────┤ ┌───────────┐ └│ ADAPTERINFO N ├────┤ ADAPTER N ├┐ ┌────────┐ ├─────────────────┤ └───────────┘├─┤ UNIT 0 │ │ UNITINFO[0] │ │ └────────┘ │ UNITINFO[1] │ │ . . . │ . . . │ │ ┌────────┐ │ UNITINFO[N] │ └─┤ UNIT N │ └─────────────────┘ └────────┘ IORB_CONFIGURATION ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pDeviceTable │FAR *PDEVICETABLE│DD │Device table │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │DeviceTableLen │USHORT │DW │Length of table │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. pDeviceTable contains a far pointer to a block of storage (length = DeviceTableLen), allocated by the caller, for the driver to return the DEVICETABLE. DeviceTableLen contains the length of the block of storage, in bytes, for the driver to return the DEVICETABLE (pDeviceTable). DEVICETABLE ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ADDLevelMajor │UCHAR │DB │ADD major level │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ADDLevelMinor │UCHAR │DB │ADD minor level │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ADDHandle │USHORT │DW │ADD index │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │TotalAdapters │USHORT │DW │Number of │ │ │ │ │adapters │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pAdapter[N] │NPADAPTERINFO │DW(N) │AdapterInfo │ │ │ │ │pointers │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On exit from the driver: ADDLevelMajor/ADDLevelMinor defines the level of support the adapter device driver is written to. A driver written to this specification (IBM 0S/2 2.0 Support Level), should set the fields as follows: ┌────────────────────────┬────────────────────────────────────┐ │Field Name │Value │ ├────────────────────────┼────────────────────────────────────┤ │ADD_Level_Major │ADD_LEVEL_MAJOR │ ├────────────────────────┼────────────────────────────────────┤ │ADD_Level_Minor │ADD_LEVEL_MINOR │ └────────────────────────┴────────────────────────────────────┘ ADDHandle contains the adapter device driver's index returned by the RegisterDeviceClass DevHlp. TotalAdapters defines the number of adapters the device driver supports. pAdapter[N] contains an array of near ADAPTERINFO pointers. The number of elements in the array is determined by the TotalAdapters field. AdapterInfo ┌────────────────────┬──────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterName[17] │UCHAR │DB(17) │ASCIIZ name │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │Reserved │UCHAR │DB │Reserved. Must │ │ │ │ │be 0. │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterUnits │USHORT │DW │Number of units │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterDevBus │USHORT │DW │Device bus types │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterIOAccess │UCHAR │DB │Host I/O type │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterHostBus │UCHAR │DB │Host bus type │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterSCSITargetID │UCHAR │DB │Target ID │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterSCSILUN │UCHAR │DB │Logical unit │ │ │ │ │number │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │AdapterFlags │USHORT │DW │Flags │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │MaxHWSGList │USHORT │DW │Max HW s/g │ │ │ │ │elements │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │MaxCDBTransferLength│ULONG │DD │Max CDB data │ │ │ │ │transfer length │ ├────────────────────┼──────────────┼─────────┼─────────────────┤ │UnitInfo[N] │UNITINFO │DD(N) │Unit information │ └────────────────────┴──────────────┴─────────┴─────────────────┘ On exit from the driver: AdapterName[17] contains the ASCIIZ name string of the adapter. This name is used by the caller for diagnostic purposes. Reserved contains a 0. This is a 16-bit alignment byte. AdapterUnits contains the number of units supported by this adapter. AdapterDevBus defines the adapter-to-device bus protocol used, as shown in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Protocol │Description │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_ST506 │DASD - ST506 CAM-I │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_ST506_II │DASD - ST506 CAM-II │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_ESDI │DASD -ESDI │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_FLOPPY │DASD - Diskette │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_SCSI_1 │SCSI - Version-I │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_SCSI_2 │SCSI -Version-II │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_SCSI_3 │SCSI - Version-III │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_OTHER │Protocol not listed. │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_NONSCSI_CDROM │non-SCSI CD-ROM interface │ └────────────────────────┴────────────────────────────────────┘ One protocol should be elected. The AdapterDevBus protocol values can be OR'd with one or more modifier bits as listed in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Modifier │Description │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_FAST_SCSI │Fast SCSI bus timings │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_8BIT │8-bit bus width │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_16BIT │16-bit bus width │ ├────────────────────────┼────────────────────────────────────┤ │AI_DEVBUS_32BIT │32-bit bus width │ └────────────────────────┴────────────────────────────────────┘ AdapterIOAccess defines the adapter-to-host I/O data transfer capabilities, as shown in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │AI_IOACCESS_BUS_MASTER │1st-party DMA adapter │ ├────────────────────────┼────────────────────────────────────┤ │AI_IOACCESS_PIO │Programmed INs/OUTs │ ├────────────────────────┼────────────────────────────────────┤ │AI_IOACCESS_DMA_SLAVE │2nd-party DMA adapter │ ├────────────────────────┼────────────────────────────────────┤ │AI_IOACCESS_MEMORY_MAP │Memory-mapped I/O │ ├────────────────────────┼────────────────────────────────────┤ │AI_IOACCESS_OTHER │I/O access not listed. │ └────────────────────────┴────────────────────────────────────┘ AdapterHostBus defines the adapter-to-host bus type used, as shown in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Type │Device Connection │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_ISA │ISA │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_EISA │Extended ISA │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_uCHNL │Micro-channel │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_OTHER │Bus type not listed. │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_UNKNOWN │Bus type unknown. │ └────────────────────────┴────────────────────────────────────┘ ┌────────────────────────┬────────────────────────────────────┐ │Width │Description │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_8BIT │8-bit bus │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_16BIT │16-bit bus │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_32BIT │32-bit bus │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_64BIT │64-bit bus │ ├────────────────────────┼────────────────────────────────────┤ │AI_HOSTBUS_UNKNOWN │Bus width unknown. │ └────────────────────────┴────────────────────────────────────┘ Note: One bus type should be set with one bus width OR'd in. AdapterSCSITargetID contains the target ID for the SCSI adapter. For non-SCSI devices, this field should be set to 0. AdapterSCSILUN contains the logical unit number for the SCSI adapter. For non-SCSI devices, this field should be set to 0. AdapterFlags defines the adapter's characteristics, as shown in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │AF_16M │>16M addresses supported. If set, │ │ │this flag indicates that the adapter│ │ │supports >16M addresses. │ ├────────────────────────┼────────────────────────────────────┤ │AF_IBM_SCB │IBM SCB support. If set, this flag │ │ │indicates that the adapter supports │ │ │IBM SCB-formatted │ │ │IOCC_ADAPTER_PASSTHRU requests. │ ├────────────────────────┼────────────────────────────────────┤ │AF_HW_SCATGAT │Hardware scatter/gather. If set, │ │ │this flag indicates that hardware │ │ │supports scatter/gather. If this │ │ │flag is not set, it indicates that │ │ │the device driver is emulating the │ │ │s/g function in software. │ ├────────────────────────┼────────────────────────────────────┤ │AF_CHS_ADDRESSING │I/O addressing. If set, this flag │ │ │indicates that the adapter supports │ │ │cylinder/head/sector addressing. │ │ │This flag should be set only for │ │ │diskette controllers. │ ├────────────────────────┼────────────────────────────────────┤ │AF_ASSOCIATED_DEVBUS │Multiple bus adapter. If set, this │ │ │flag indicates that the adapter │ │ │supports more than one device bus. │ │ │An ADAPTERINFO and UNITINFO │ │ │structure(s) should be created to │ │ │describe each device bus. This flag │ │ │must be set in each ADAPTERINFO │ │ │structure for the adapter, except │ │ │the first. │ └────────────────────────┴────────────────────────────────────┘ MaxHWSGList contains the maximum number of elements supported in a single hardware scatter/gather list. This field should be set to 0 if the adapter hardware supports an unlimited s/g list length. Note: This is not a limit on the number of s/g elements an adapter device driver can receive in a scatter/gather list for an Execute_IO IORB. See Adapter Device Driver Interface Questions and Answers for more information. MaxCDBTransferLength contains the maximum number of bytes supported by this adapter on a CDB-data transfer request. This field is set in cases where a device driver needs to emulate s/g support in software and requires a fixed-size buffer to do so. This field should be set to 0 if an driver does not need to emulate its s/g function using an in-memory buffer. See Adapter Device Driver Interface Questions and Answers for more information. UnitInfo[N] contains an array of UNITINFO structures as shown in the following table. The number of elements in the array is determined by the AdapterUnits field. UNITINFO Structure ┌─────────────────┬──────────┬─────────┬────────────────────────┐ │Element │C Type │Length │Description │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │AdapterIndex │USHORT │DW │Associated AdapterIndex │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │UnitIndex │USHORT │DW │Unit tag │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │UnitFlags │USHORT │DW │Unit flags │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │Reserved │USHORT │DW │Reserved. Must be 0. │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │UnitHandle │USHORT │DW │Assigned by adapter │ │ │ │ │device driver │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │FilterADDHandle │USHORT │DW │Filter device driver │ │ │ │ │handle │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │UnitType │USHORT │DW │Unit type │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │QueuingCount │USHORT │DW │IORB queue length │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │UnitSCSITargetID │UCHAR │DB │SCSI target ID │ ├─────────────────┼──────────┼─────────┼────────────────────────┤ │UnitSCSILUN │UCHAR │DB │SCSI logical unit number│ └─────────────────┴──────────┴─────────┴────────────────────────┘ On exit from the driver: AdapterIndex contains the unit's corresponding adapter's index in the pAdapter[N] array. UnitIndex contains the unit's index in the UnitInfo[N] array. UnitFlags defines the unit's characteristics, as shown in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │UF_REMOVABLE │Media can be removed. If set, this │ │ │flag indicates that the unit's media│ │ │is removable. │ ├────────────────────────┼────────────────────────────────────┤ │UF_CHANGELINE │Changeline supported. If set, this │ │ │flag indicates that the unit can │ │ │detect media removal. │ ├────────────────────────┼────────────────────────────────────┤ │UF_PREFETCH │Read Prefetch supported. If set, │ │ │this flag indicates the unit │ │ │supports read prefetch. │ ├────────────────────────┼────────────────────────────────────┤ │UF_A_DRIVE │Manages drive A. If set, this flag │ │ │indicates that the unit manages │ │ │drive A. │ ├────────────────────────┼────────────────────────────────────┤ │UF_B_DRIVE │Manages drive B. If set, this flag │ │ │indicates that the unit manages │ │ │drive B. │ ├────────────────────────┼────────────────────────────────────┤ │UF_NODASD_SUPT │Suppress DASD device manager. If │ │ │set, this flag indicates that the │ │ │driver does not want this unit to be│ │ │managed by the OS2DASD.DMD device │ │ │manager. │ ├────────────────────────┼────────────────────────────────────┤ │UF_NOSCSI_SUPT │Suppress SCSI device manager. If │ │ │set, this flag indicates that the │ │ │driver does not want this unit to be│ │ │managed by the OS2SCSI.DMD device │ │ │manager. │ ├────────────────────────┼────────────────────────────────────┤ │UF_DEFECTIVE │Device is defective. If set, this │ │ │flag indicates that the unit is not │ │ │operational. Defective units are │ │ │ignored by the DASD and SCSI device │ │ │managers. However, the driver │ │ │should accept allocation requests │ │ │for the unit and pass commands to │ │ │the unit for other device managers. │ │ │The information returned by the │ │ │IOCM_UNIT_STATUS command reflects │ │ │this flag's current setting. │ └────────────────────────┴────────────────────────────────────┘ Reserved is reserved for future growth. Must be set to 0 by the adapter device driver. UnitHandle defines the unit's handle. This handle is a unique ID, assigned by either the filter device driver or the adapter device driver. A unit is fully identified by the UnitHandle field and its associated ADD's handle, defined by either the FilterADDHandle or ADDHandle fields. FilterADDHandle contains the handle of the filter device driver. If a filter device driver does not exist, this field must be 0. See Using Filter Device Drivers for more information on filter device drivers. UnitType defines the unit's device type. Unit types and their supported devices are shown in the following table. ┌──────────────────────────────┬──────────────────────────────┐ │UnitType │Devices Supported │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_DISK │Direct access (DASD) │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_TAPE │Tape │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_PRINTER │Printer │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_PROCESSOR │Processor │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_WORM │Write Once/Read Many │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_CDROM │CD ROM │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_SCANNER │Scanner │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_OPTICAL_MEMORY │Optical disk │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_CHANGER │Changer (example, jukebox) │ ├──────────────────────────────┼──────────────────────────────┤ │UIB_TYPE_COMM │Communication │ └──────────────────────────────┴──────────────────────────────┘ Note: One unit type must be set. QueuingCount defines the recommended number of commands to queue for this unit. Note: Do not design drivers assuming a fixed length queue. This field provides to the device manager the recommended queue length for optimum performance. UnitSCSITargetID contains the target ID for SCSI devices. For all other devices, this field equals 0. UnitSCSILUN contains the logical unit number for SCSI devices. For all other devices, this field equals 0. On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_CONFIGURATION request. Return Codes Following is a list of the IOCC_CONFIGURATION error codes: IOERR_CMD_SYNTAX IOERR_CMD_SW_RESOURCE. For a detailed description of all the return codes, see Error Handling. ═══ 6.3.3. IOCC_UNIT_CONTROL ═══ The IOCC_UNIT_CONTROL CommandCode consists of all the CommandModifiers responsible for controlling the ownership of a unit. The following table describes the CommandModifiers. ┌────────────────────────┬────────────────────────────────────┐ │CommandModifier │Description │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_ALLOCATE_UNIT │Assigns ownership of the specified │ │ │unit to the caller. A unit must be │ │ │allocated prior to accepting any │ │ │other direct call commands. Once │ │ │allocated, a unit cannot be assigned│ │ │to another owner until that unit is │ │ │deallocated. It is the │ │ │responsibility of the owner to │ │ │coordinate sharing of a unit. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_DEALLOCATE_UNIT │Removes the caller's ownership of │ │ │the specified unit. Once │ │ │deallocated, a unit can be assigned │ │ │to another owner. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_CHANGE_UNITINFO │Modifies the specified unit's │ │ │UNITINFO portion of the DEVICETABLE │ │ │structure with the information │ │ │passed by the caller. │ └────────────────────────┴────────────────────────────────────┘ Remarks Support: Mandatory Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK Format of IORB o IORB Type - IORB_UNIT_CONTROL o IORBH Fields - CommandCode o IOCC_CONFIGURATION - CommandModifiers o IOCM_ALLOCATE_UNIT o IOCM_DEALLOCATE_UNIT o IOCM_CHANGE_UNITINFO - Valid RequestControl Flags o IORB_ASYNC_POST IORB_UNIT_CONTROL Description This section defines the IORB_UNIT_CONTROL control block. (See the table below.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Flags │USHORT │DW │Flags │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pUnitInfo │PUNITINFO │DD │Pointer to │ │ │ │ │UnitInfo │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │UnitInfoLen │USHORT │DW │Length of │ │ │ │ │UnitInfo │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. Flags contains a 0. pUnitInfo contains a far pointer to a buffer containing modified unit characteristics, in the format defined by the UNITINFO structure. The adapter device driver uses this information to update the unit's UNITINFO structure in the DEVICETABLE. This field is valid only for the IOCM_CHANGE_UNITINFO CommandModifier. Note: A device driver can access the UNITINFO structure provided by the IOCM_CHANGE_UNITINFO IORB at any time. The caller, therefore, must not invalidate or release the passed UNITINFO structure on successful completion of this IORB request. UnitInfoLen contains the length, in bytes, of the UNITINFO buffer (pUnitInfo) passed to the driver. This field is valid only for the IOCM_CHANGE_UNITINFO CommandModifier. On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_UNIT_CONTROL request. Return Codes Following is a list of the IOCC_UNIT_CONTROL error codes: IOERR_CMD_SYNTAX IOERR_CMD_SW_RESOURCE IOERR_UNIT_ALLOCATED IOERR_UNIT_NOT_ALLOCATED For a detailed description of all the return codes, see Error Handling. ═══ 6.3.4. IOCC_GEOMETRY ═══ The IOCC_GEOMETRY CommandCode consists of all the CommandModifiers responsible for setting and returning information about the capacity of a unit. The CommandModifiers are described in the following table: ┌──────────────────────────────┬──────────────────────────────┐ │CommandModifier │Description │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_MEDIA_GEOMETRY │Returns the geometry of the │ │ │current media in a drive. │ │ │For non-removable media │ │ │devices, the geometry returned│ │ │must be identical to the │ │ │geometry returned by │ │ │IOCM_GET_DEVICE_GEOMETRY. │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_SET_MEDIA_GEOMETRY │Informs the adapter device │ │ │driver of the required media │ │ │geometry in preparation for │ │ │formatting. This command is │ │ │mandatory only for standard │ │ │diskette media. │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_DEVICE_GEOMETRY │Returns the device geometry │ │ │compatible with INT 13h BIOS │ │ │function 08h. │ │ │If the INT 13h support for a │ │ │device provides translation, │ │ │the INT 13h geometry of the │ │ │device must be returned with │ │ │the BIOS translation performed│ │ │within the driver. That is, │ │ │the driver must emulate any │ │ │INT 13h translation performed │ │ │by BIOS. │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_SET_LOGICAL_GEOMETRY │Indicates that the geometry │ │ │recorded in the file system │ │ │tables on the media does not │ │ │match the physical media │ │ │geometry reported by the │ │ │device driver. │ │ │The driver should convert RBA │ │ │to CHS addresses according to │ │ │the geometry passed in this │ │ │IORB, rather than using the │ │ │media geometry the driver is │ │ │reporting. The device driver │ │ │should stop performing this │ │ │translation if a media change │ │ │indication is detected. │ │ │Support of this command is │ │ │mandatory only for standard │ │ │diskette media. │ └──────────────────────────────┴──────────────────────────────┘ Remarks Support: Mandatory (See CommandModifiers for exceptions.) Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK, INTERRUPT Format of IORB o IORB Type - IORB_GEOMETRY o IORBH Fields - CommandCode o IOCC_GEOMETRY - CommandModifiers o IOCM_GET_MEDIA_GEOMETRY o IOCM_SET_MEDIA_GEOMETRY o IOCM_GET_DEVICE_GEOMETRY o IOCM_SET_LOGICAL_GEOMETRY - Valid RequestControl Flags o IORB_ASYNC_POST o IORB_REQ_STATUSBLOCK o IORB_DISABLE_RETRY IOCC_GEOMETRY Description This section defines the IORB_GEOMETRY and GEOMETRY control blocks. (See the table below.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pGeometry │PGEOMETRY │DD │Pointer to │ │ │ │ │GEOMETRY │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │GeometryLen │USHORT │DW │Length of │ │ │ │ │GEOMETRY data │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. pGeometry contains a far pointer to the block of storage (length = GeometryLen) allocated by the caller for the GEOMETRY. GeometryLen contains the size of the block of storage, in bytes, for the GEOMETRY structure (pGeometry). GEOMETRY Description ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │TotalSectors │ULONG │DD │Number of sectors│ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │BytesPerSector │USHORT │DW │Bytes per sector │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Reserved │USHORT │DW │Reserved │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │NumHeads │USHORT │DW │Number of heads │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │TotalCylinders │ULONG │DD │Number of │ │ │ │ │cylinders │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │SectorsPerTrack │USHORT │DW │Number of sectors│ │ │ │ │per track │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver for SET CommandModifiers, and on exit from the driver for GET CommandModifiers, the following apply: TotalSectors contains the total number of sectors. BytesPerSector contains the number of bytes per sector. The IBM OS/2 2.0 File System supports only a value of 512. Reserved contains a 0. This alignment field ensures that the GEOMETRY structure aligns with SCSI Read Capacity output. NumHeads contains the number of heads. TotalCylinders contains the number of cylinders. SectorsPerTrack contains the number of sectors per track. Note: SCSI devices normally do not support cylinder/head/sector (CHS) addressing. However, to maintain INT 13h BIOS compatibility, most controllers create CHS mapping for the devices they support. For non-boot devices, which do not provide INT 13h support, NumHeads, TotalCylinders, and SectorsPerTrack can be set to 0, and the device manager will select appropriate CHS values. On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_GEOMETRY request. Return Codes Following is a list of the IOCC_GEOMETRY error codes: IOERR_CMD_NOT_SUPPORTED IOERR_CMD_SYNTAX IOERR_CMD_SW_RESOURCE IOERR_UNIT_NOT_ALLOCATED IOERR_UNIT_NOT_READY IOERR_UNIT_PWR_OFF IOERR_MEDIA_NOT_FORMATTED IOERR_MEDIA_NOT_SUPPORTED IOERR_MEDIA_CHANGED IOERR_MEDIA_NOT_PRESENT IOERR_ADAPTER_HOSTBUSCHECK IOERR_ADAPTER_DEVICEBUSCHECK IOERR_ADAPTER_OVERRUN IOERR_ADAPTER_UNDERRUN IOERR_ADAPTER_DIAGFAIL IOERR_ADAPTER_TIMEOUT IOERR_ADAPTER_DEVICE_TIMEOUT IOERR_ADAPTER_REQ_NOT_SUPPORTED IOERR_ADAPTER_REFER_TO_STATUS IOERR_DEVICE_DEVICEBUSCHECK IOERR_DEVICE_REQ_NOT_SUPPORTED IOERR_DEVICE_DIAGFAIL IOERR_DEVICE_BUSY IOERR_DEVICE_OVERRUN IOERR_DEVICE_UNDERRUN For a detailed description of all the return codes, see Error Handling. ═══ 6.3.5. IOCC_EXECUTE_IO ═══ The IOCC_EXECUTE_IO CommandCode consists of all CommandModifiers responsible for issuing a Read or Write to a unit. The following table describes the IOCC_EXECUTE_IO CommandModifiers: ┌────────────────────────┬────────────────────────────────────┐ │CommandModifier │Description │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_READ │Reads a unit's data into the │ │ │scatter/gather list buffers. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_READ_VERIFY │Verifies that the recorded data at │ │ │the requested I/O address is │ │ │readable. No data is transferred. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_READ_PREFETCH │Reads data from the device into the │ │ │adapter's hardware cache. Support of│ │ │this command is optional. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_WRITE │Writes data from the scatter/gather │ │ │list buffers to the unit's specified│ │ │I/O address. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_WRITE_VERIFY │Writes data from the scatter/gather │ │ │list buffers to the unit's specified│ │ │I/O address, then verifies that the │ │ │data can be read (Write/Read Verify │ │ │combination). │ └────────────────────────┴────────────────────────────────────┘ Remarks Support: Mandatory Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK, INTERRUPT Format of IORB o IORB Type - IORB_EXECUTEIO o IORBH Fields - CommandCode o IOCC_EXECUTE_IO - CommandModifiers o IOCM_READ o IOCM_READ_VERIFY o IOCM_READ_PREFETCH o IOCM_WRITE o IOCM_WRITE_VERIFY - Valid RequestControl Flags o IORB_ASYNC_POST o IORB_CHAIN o IORB_CHS_ADDRESSING (Diskette only, see AF_CHS_ADDRESSING) o IORB_REQ_STATUSBLOCK o IORB_DISABLE_RETRY IORB_EXECUTEIO Description This section defines the IORB_EXECUTEIO control block. (See the following table.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │cSGLIST │USHORT │DW │Number of │ │ │ │ │elements │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pSGLIST │PSCATGATENTRY │DD │Far pointer to │ │ │ │ │s/g list │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ppSGLIST │ULONG │DD │Physical address │ │ │ │ │of s/g list │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │RBA │ULONG │DD │I/O starting │ │ │ │ │address │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │BlockCount │USHORT │DW │Sector count │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │BlocksXferred │USHORT │DW │Number of sectors│ │ │ │ │transferred │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │BlockSize │USHORT │DW │Number of bytes │ │ │ │ │per sector │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Flags │USHORT │DW │I/O-specific │ │ │ │ │flags │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. cSGList contains the number of scatter/gather elements in the scatter/gather list (pSGLIST). pSGLIST contains a far pointer to the scatter/gather list, supplied by the caller. The scatter/gather list consists of an array of cSGList elements, each pointing to a physically contiguous area of real memory in a format defined by the SCATGATENTRY structure. (See the following table.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ppXferBuf │ULONG │DD │Physical pointer │ │ │ │ │to buffer │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │XferBufLen │ULONG │DD │Length of buffer │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ ppSGLIST contains a 32-bit physical address of the scatter/gather list. RBA contains the starting relative block address for the data transfer operation. If the IORB_CHS_ADDRESSING flag is set in the IORBH RequestControl field, then the format of the RBA field is defined by the CHS_ADDR structure. (See the following table.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Cylinder │USHORT │DW │Starting cylinder│ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Head │UCHAR │DB │Starting head │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Sector │UCHAR │DB │Starting sector │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ BlockCount contains the number of sectors (length = BlockSize) to transfer. Note: If this value exceeds the adapter's maximum transfer size, the driver is responsible for issuing multiple operations to the unit to complete the caller's request. BlocksXferred equals 0 on entry. On exit from the driver BlocksXferred contains the number of sectors successfully transferred. BlockSize contains the number of bytes in a block or sector. The IBM OS/2 2.0 File System supports only a value of 512. Flags defines Execute I/O cache control flags, as shown in the table below. ┌──────────────────────────────┬──────────────────────────────┐ │Flag │Description │ ├──────────────────────────────┼──────────────────────────────┤ │XIO_DISABLE_HW_WRITE_CACHE │Disable-deferred Write. │ │ │Indicates the driver should │ │ │ensure that the requested data│ │ │is written to the media prior │ │ │to doing a notification │ │ │callout. │ ├──────────────────────────────┼──────────────────────────────┤ │XIO_DISABLE_HW_READ_CACHE │Disable Read caching. │ │ │Indicates to the driver that │ │ │the data being read is of a │ │ │transient nature and does not │ │ │need to be retained in the │ │ │adapter's hardware cache. │ └──────────────────────────────┴──────────────────────────────┘ Note: The scatter/gather list-related fields (cSGLIST, pSGLIST, and ppSGLIST) are at the same offset as their equivalent pointers in the IOCC_ADAPTER_PASSTHRU and IOCC_FORMAT CommandCodes. On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_EXECUTE_IO request. Return Codes Following is a list of the IOCC_EXECUTE_IO error codes: IOERR_CMD_NOT_SUPPORTED IOERR_CMD_SYNTAX IOERR_CMD_SGLIST_BAD IOERR_CMD_SW_RESOURCE IOERR_CMD_ABORTED IOERR_UNIT_NOT_ALLOCATED IOERR_UNIT_NOT_READY IOERR_UNIT_PWR_OFF IOERR_RBA_ADDRESSING_ERROR IOERR_RBA_LIMIT IOERR_RBA_CRC_ERROR IOERR_MEDIA_NOT_FORMATTED IOERR_MEDIA_NOT_SUPPORTED IOERR_MEDIA_WRITE_PROTECT IOERR_MEDIA_CHANGED IOERR_MEDIA_NOT_PRESENT IOERR_ADAPTER_HOSTBUSCHECK IOERR_ADAPTER_DEVICEBUSCHECK IOERR_ADAPTER_OVERRUN IOERR_ADAPTER_UNDERRUN IOERR_ADAPTER_DIAGFAIL IOERR_ADAPTER_TIMEOUT IOERR_ADAPTER_DEVICE_TIMEOUT IOERR_ADAPTER_REQ_NOT_SUPPORTED IOERR_ADAPTER_REFER_TO_STATUS IOERR_DEVICE_DEVICEBUSCHECK IOERR_DEVICE_REQ_NOT_SUPPORTED IOERR_DEVICE_DIAGFAIL IOERR_DEVICE_BUSY IOERR_DEVICE_OVERRUN IOERR_DEVICE_UNDERRUN For a detailed description of all the return codes, see Error Handling. ═══ 6.3.6. IOCC_FORMAT ═══ The IOCC_FORMAT CommandCode consists of all CommandModifiers responsible for unit format requests. The following table describes the IOCC_FORMAT CommandModifiers: ┌────────────────────────┬────────────────────────────────────┐ │CommandModifier │Description │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_FORMAT_MEDIA │Formats the entire media in the │ │ │unit. Support of this command is │ │ │mandatory for SCSI devices that │ │ │require low-level formatting. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_FORMAT_TRACK │Formats the specified track on the │ │ │unit. Support of this command is │ │ │mandatory for standard diskette │ │ │media. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_FORMAT_PROGRESS │Reports the progress of the │ │ │formatting. Support of this command │ │ │is mandatory for standard diskette │ │ │media. │ └────────────────────────┴────────────────────────────────────┘ Remarks Support: See CommandModifiers. Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK, INTERRUPT Format of IORB o IORB Type - IORB_FORMAT o IORBH Fields - RequestControl: Flags can be enabled or disabled. - CommandCode o IOCC_FORMAT - CommandModifiers o IOCM_FORMAT_MEDIA o IOCM_FORMAT_TRACK o IOCM_FORMAT_PROGRESS - Valid RequestControl Flags o IORB_ASYNC_POST o IORB_CHS_ADDRESSING (Diskette only, see AF_CHS_ADDRESSING) o IORB_REQ_STATUSBLOCK o IORB_DISABLE_RETRY IORB_FORMAT Description: This section defines the IORB_FORMAT control block. (See the following table.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │cSGLIST │USHORT │DW │Number of │ │ │ │ │elements │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pSGLIST │PSCATGATENTRY │DD │Far pointer to │ │ │ │ │s/g list │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ppSGLIST │ULONG │DD │Physical address │ │ │ │ │of s/g list │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │FormatCmdLen │USHORT │DW │Length of Format │ │ │ │ │command │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pFormatCmd │PBYTE │DD │Pointer to Format│ │ │ │ │command │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Reserved_1 │UCHAR │DB(8) │Reserved. │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. cSGList contains the number of scatter/gather elements in the scatter/gather list (pSGLIST). pSGLIST contains a far pointer to the scatter/gather list supplied by the caller. The scatter/gather list consists of an array of cSGList elements, each pointing to a physically contiguous area of real memory in a format defined by the SCATGATENTRY structure. (See the following table.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ppXferBuf │ULONG │DD │Physical pointer │ │ │ │ │to buffer │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │XferBufLen │ULONG │DD │Length of buffer │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ ppSGLIST contains a 32-bit physical address of the scatter/gather list. Note: For IOCM_FORMAT_MEDIA, the s/g pointers will point to a Format Unit Parameter List as defined by the SCSI-2 specification. If the SCSI Format Unit CDB does not require a parameter list and other command modifiers, the s/g pointers must be 0. FormatCmdLen contains the length of the format command (pFormatCmd), in bytes. pFormatCmd contains a pointer to device-specific formatting information. For diskette controllers, this points to the FORMAT_CMD_TRACK structure (see the table below). For SCSI devices, this points to a SCSI Format Unit CDB. ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Flags │USHORT │DW │Flags │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │RBA │ULONG │DD │Starting RBA │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │cTrackEntries │USHORT │DW │Number of track │ │ │ │ │entries │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: Flags contains flags to define the request, as shown in the following table. ┌───────────────┬─────────────────────────────────────────────┐ │Flag │Description │ ├───────────────┼─────────────────────────────────────────────┤ │FF_VERIFY │Verify after format. If set, this flag │ │ │indicates that the driver should verify the │ │ │sectors after formatting. │ └───────────────┴─────────────────────────────────────────────┘ RBA contains the starting relative block address for an IOCM_FORMAT_TRACK request. For IOCM_FORMAT_MEDIA and IOCM_FORMAT_PROGRESS requests, this field equals 0. If the IORB_CHS_ADDRESSING flag is set in the IORBH->RequestControl field, then the format of the RBA field is defined by the CHS_ADDR structure, shown in the following table. ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Cylinder │USHORT │DW │Starting cylinder│ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Head │UCHAR │DB │Starting head │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Sector │UCHAR │DB │Starting sector │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ Note: The scatter/gather list-related fields (cSGLIST, pSGLIST, and ppSGLIST) are at the same offset as its equivalent pointers in the IOCC_EXECUTE_IO and IOCC_ADAPTER_PASSTHRU CommandCodes. On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_FORMAT request. Return Codes Following is a list of the IOCC_FORMAT error codes: IOERR_CMD_NOT_SUPPORTED IOERR_CMD_SYNTAX IOERR_CMD_SW_RESOURCE IOERR_CMD_ABORTED IOERR_UNIT_NOT_ALLOCATED IOERR_UNIT_NOT_READY IOERR_UNIT_PWR_OFF IOERR_RBA_ADDRESSING_ERROR IOERR_RBA_LIMIT IOERR_RBA_CRC_ERROR IOERR_MEDIA_NOT_SUPPORTED IOERR_MEDIA_WRITE_PROTECT IOERR_MEDIA_CHANGED IOERR_MEDIA_NOT_PRESENT IOERR_ADAPTER_HOSTBUSCHECK IOERR_ADAPTER_DEVICEBUSCHECK IOERR_ADAPTER_OVERRUN IOERR_ADAPTER_UNDERRUN IOERR_ADAPTER_DIAGFAIL IOERR_ADAPTER_TIMEOUT IOERR_ADAPTER_DEVICE_TIMEOUT IOERR_ADAPTER_REQ_NOT_SUPPORTED IOERR_ADAPTER_REFER_TO_STATUS IOERR_DEVICE_DEVICEBUSCHECK IOERR_DEVICE_REQ_NOT_SUPPORTED IOERR_DEVICE_DIAGFAIL IOERR_DEVICE_BUSY IOERR_DEVICE_OVERRUN IOERR_DEVICE_UNDERRUN For a detailed description of all the return codes, see Error Handling. ═══ 6.3.7. IOCC_UNIT_STATUS ═══ The IOCC_UNIT_STATUS CommandCode consists of all the CommandModifiers responsible for returning a unit's current status. The following table describes these CommandModifiers: ┌──────────────────────────────┬──────────────────────────────┐ │CommandModifier │Description │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_UNIT_STATUS │Returns flags indicating the │ │ │unit's current Ready, Power │ │ │On, and Defective status. For│ │ │SCSI devices, if a SCSI Target│ │ │is detected, the driver must │ │ │issue a SCSI Test Unit Ready │ │ │command to obtain the current │ │ │unit status. │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_CHANGELINE_STATE │Returns the unit's current │ │ │changeline state. This │ │ │command is mandatory for │ │ │standard diskette devices. │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_MEDIA_SENSE │Returns the unit's current │ │ │media storage capacity. This │ │ │command is mandatory for │ │ │standard diskette devices. │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_LOCK_STATUS │Returns media sense │ │ │information This command is │ │ │mandatory for standard │ │ │diskette devices. │ └──────────────────────────────┴──────────────────────────────┘ Remarks Support: Mandatory (See CommmandModifiers for exceptions.) Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK, INTERRUPT Format of IORB o IORB Type - IORB_UNIT_STATUS o IORBH Fields - CommandCode o IOCC_UNIT_STATUS - CommandModifiers o IOCM_GET_UNIT_STATUS o IOCM_GET_CHANGELINE_STATE o IOCM_GET_MEDIA_SENSE o IOCM_GET_LOCK_STATUS - Valid RequestControl Flags o IORB_ASYNC_POST o IORB_REQ_STATUSBLOCK IORB_UNIT_STATUS Description This section defines the IORB_UNIT_STATUS control block. IORB_UNIT_STATUS ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C-Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │UnitStatus │USHORT │DW │Unit status │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. UnitStatus equals 0, on entry. On exit from the driver, this field contains the status information request, based on the CommandModifier field, as shown in the following table. ┌──────────────────────────────┬──────────────────────────────┐ │CommandModifier │Description │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_UNIT_STATUS │ │ │US_READY │Unit in Ready state │ │US_POWER │Unit Powered On │ │US_DEFECTIVE │Unit Defective │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_CHANGELINE_STATE │ │ │US_CHANGELINE_ACTIVE │Changeline occurred │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_MEDIA_SENSE │ │ │US_MEDIA_144MB │144KB media capacity │ │US_MEDIA_288MB │288KB media capacity │ │US_MEDIA_720KB │720KB media capacity │ │US_MEDIA_UNKNOWN │Media capacity unknown │ ├──────────────────────────────┼──────────────────────────────┤ │IOCM_GET_LOCK_STATUS │ │ │US_LOCKED │Unit Locked │ └──────────────────────────────┴──────────────────────────────┘ Remarks o The UnitStatus field reports the general status of the unit. If the adapter device driver encounters a SCSI Check condition, it must convert any retrieved sense data into IOERR_* error codes and report these in the IORBH->ErrorCode field in addition to setting the UnitStatus field. o The reporting of units that are powered-off is optional. The driver possibly might be able to determine powered-off units from configuration data stored in non-volatile memory. o The detection of defective units is optional. On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_UNIT_STATUS request. Return Codes For a detailed description of all the return codes, see IORB General Format. ═══ 6.3.8. IOCC_DEVICE_CONTROL ═══ The IOCC_DEVICE_CONTROL CommandCode consists of all the CommmandModifiers responsible for device control. The following table describes the IOCC_DEVICE_CONTROL CommandModifiers: ┌────────────────────────┬────────────────────────────────────┐ │CommandModifier │Description │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_ABORT │Aborts the unit's current operation │ │ │and causes the driver to return any │ │ │pending work in its queues. │ │ │Support is mandatory for SCSI │ │ │devices. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_RESET │Resets the unit to its default │ │ │operating parameters. │ │ │Support is mandatory for SCSI │ │ │devices. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_SUSPEND │Suspends the unit's current │ │ │operation. This command provides for│ │ │sharing disk controller hardware │ │ │with other device drivers. │ │ │Support is mandatory for diskette │ │ │controllers. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_RESUME │Resumes the unit's suspended │ │ │operation. This command provides │ │ │for the sharing of the diskette │ │ │controller with other device │ │ │drivers. │ │ │Support is mandatory for diskette │ │ │controllers. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_LOCK_MEDIA │Locks the current media in the unit.│ │ │Support is mandatory for SCSI │ │ │adapter device drivers and for other│ │ │devices that support a media-locking│ │ │function. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_UNLOCK_MEDIA │Unlocks the current media from the │ │ │unit. │ │ │Mandatory for SCSI adapter device │ │ │drivers and for other devices that │ │ │support a media-locking function. │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_EJECT_MEDIA │Ejects the current media from the │ │ │unit. │ │ │Mandatory for SCSI adapter device │ │ │drivers and for other devices that │ │ │support a media-locking function. │ └────────────────────────┴────────────────────────────────────┘ Remarks Support: See the command descriptions. Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK, INTERRUPT Format of IORB o IORB Type - IORB_DEVICE_CONTROL o IORBH Fields - CommandCode o IOCC_DEVICE_CONTROL - CommandModifiers o IOCM_ABORT o IOCM_RESET o IOCM_SUSPEND o IOCM_RESUME o IOCM_LOCK_MEDIA o IOCM_UNLOCK_MEDIA o IOCM_EJECT_MEDIA - Valid RequestControl Flags o IORB_ASYNC_POST o IORB_REQ_STATUSBLOCK o IORB_DISABLE_RETRY IORB_DEVICE_CONTROL Description This section defines the IORB_DEVICE_CONTROL control block. (See the following table.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C-Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Flags │USHORT │DW │Flags │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Reserved │USHORT │DW │Reserved │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. Flags contains flags defined only for IOCM_SUSPEND requests. For all other requests, this field equals 0. The following table describes the IOCM_SUSPEND flags. ┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │DC_SUSPEND_DEFERRED │Suspend on idle. If set, this flag │ │ │indicates that the suspend should │ │ │occur once the unit is idle. │ ├────────────────────────┼────────────────────────────────────┤ │DC_SUSPEND_IMMEDIATE │Suspend immediate. If set this flag│ │ │indicates that the suspend should │ │ │occur once the current request is │ │ │complete. │ └────────────────────────┴────────────────────────────────────┘ Reserved contains a 0. On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_DEVICE_CONTROL request. Return Codes Following is a list of the IOCC_DEVICE_CONTROL error codes: IOERR_CMD_NOT_SUPPORTED IOERR_CMD_SYNTAX IOERR_CMD_SW_RESOURCE IOERR_UNIT_NOT_ALLOCATED IOERR_UNIT_NOT_READY IOERR_UNIT_PWR_OFF For a detailed description of all the return codes, see Error Handling. ═══ 6.3.9. IOCC_ADAPTER_PASSTHRU ═══ The IOCC_ADAPTER_PASSTHRU CommandCode consists of all the CommandModifiers responsible for issuing SCSI-formatted requests to a unit. The following table describes the CommandModifiers: ┌────────────────────────┬────────────────────────────────────┐ │CommandModifier │Description │ ├────────────────────────┼────────────────────────────────────┤ │IOCM_EXECUTE_SCB │Issues an IBM Subsystem Control │ │ │Block (SCB) request to the specified│ │ │unit. │ │ │Support of this command is optional.│ ├────────────────────────┼────────────────────────────────────┤ │IOCM_EXECUTE_CDB │Issues a SCSI Command Descriptor │ │ │Block (CDB) request to the specified│ │ │unit. │ │ │This command is mandatory for all │ │ │SCSI units. │ └────────────────────────┴────────────────────────────────────┘ Remarks Support: Mandatory for SCSI units (See CommmandModifiers for exceptions.) Called By: OS2DASD.DMD, other device manager, or filter device driver Context of Call: TASK, INTERRUPT Format of IORB o IORB Type - IORB_ADAPTER_PASSTHRU o IORBH Fields - CommandCode o IOCC_ADAPTER_PASSTHRU - CommandModifiers o IOCM_EXECUTE_SCB o IOCM_EXECUTE_CDB - Valid RequestControl Flags o IORB_ASYNC_POST o IORB_REQ_STATUSBLOCK o IORB_DISABLE_RETRY IORB_ADAPTER_PASSTHRU Description This section defines the IORB_ADAPTER_PASSTHRU control block. (See the following table.) ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C-Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │iorbh │IORBH │DB(68) │IORB header │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │cSGLIST │USHORT │DW │Number of │ │ │ │ │elements │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pSGLIST │PSCATGATENTRY │DD │Far pointer to │ │ │ │ │s/g list │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ppSGLIST │ULONG │DD │Physical address │ │ │ │ │of s/g list │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ControllerCmdLen │USHORT │DW │Length │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │pControllerCmd │PBYTE │DD │Controller │ │ │ │ │command pointer │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ppSCB │ULONG │DD │Physical SCB │ │ │ │ │pointer │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │Flags │USHORT │DW │Flags │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ On entry to the driver: iorbh See IORB General Format. cSGList contains the number of scatter/gather elements in the scatter/gather list (pSGLIST), for IOCM_EXECUTE_CDB requests. For all other requests this field contains a 0. pSGLIST contains a far pointer to the scatter/gather list, supplied by the caller, for IOCM_EXECUTE_CDB requests. For all other requests this field contains a 0. The scatter/gather list consists of an array of cSGList elements, each pointing to a physically contiguous area of real memory in a format defined by the SCATGATENTRY structure, shown in the following table. ┌─────────────────┬─────────────────┬─────────┬─────────────────┐ │Field Name │C-Type │Length │Description │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │ppXferBuf │ULONG │DD │Physical pointer │ │ │ │ │to buffer │ ├─────────────────┼─────────────────┼─────────┼─────────────────┤ │XferBufLen │ULONG │DD │Length of buffer │ └─────────────────┴─────────────────┴─────────┴─────────────────┘ ppSGLIST contains a 32-bit physical address of the scatter/gather list for IOCM_EXECUTE_CDB requests. For all other requests, this field contains a 0. ControllerCmdLen contains the length, in bytes, of the command controller buffer. pControllerCmd contains a pointer to the controller command buffer in either SCB or CDB format, based on the CommandModifier field. ppSCB contains a 32-bit physical address of the Subsystem Control Block (SCB) for IOCM_EXECUTE_SCB requests. For all other requests, this field contains a 0. Flags contains flags to define the request, as shown in the following table. ┌────────────────────────┬────────────────────────────────────┐ │Flag │Description │ ├────────────────────────┼────────────────────────────────────┤ │PT_DIRECTION_IN │Data transfer direction. This flag │ │ │defines the direction of the data │ │ │transfer for IOCM_EXECUTE_CDB │ │ │requests. If set, the data transfer│ │ │is from the target device to the │ │ │host adapter. For all other │ │ │requests, this flag is ignored. │ └────────────────────────┴────────────────────────────────────┘ On exit, the driver sets the Status and ErrorCode fields of the IORBH to reflect the results of the IOCC_ADAPTER_PASSTHRU request. Return Codes Following is a list of the IOCC_ADAPTER_PASSTHRU error codes: IOERR_CMD_NOT_SUPPORTED IOERR_CMD_SYNTAX IOERR_CMD_SGLIST_BAD IOERR_CMD_SW_RESOURCE IOERR_CMD_ABORTED IOERR_UNIT_NOT_ALLOCATED IOERR_UNIT_NOT_READY IOERR_UNIT_PWR_OFF IOERR_ADAPTER_HOSTBUSCHECK IOERR_ADAPTER_DEVICEBUSCHECK IOERR_ADAPTER_OVERRUN IOERR_ADAPTER_UNDERRUN IOERR_ADAPTER_DIAGFAIL IOERR_ADAPTER_TIMEOUT IOERR_ADAPTER_DEVICE_TIMEOUT IOERR_ADAPTER_REQ_NOT_SUPPORTED IOERR_ADAPTER_REFER_TO_STATUS IOERR_DEVICE_DEVICEBUSCHECK IOERR_DEVICE_REQ_NOT_SUPPORTED IOERR_DEVICE_DIAGFAIL IOERR_DEVICE_BUSY IOERR_DEVICE_OVERRUN IOERR_DEVICE_UNDERRUN For a detailed description of all the return codes, see Error Handling. ═══ 6.4. Device Helpers (DevHlp) ═══ In this specification, device helpers are a set of C or assembler callable routines that provide operating system services for OS/2 device drivers. These DevHlp services are RegisterDeviceClass and GetDOSVar. ═══ 6.4.1. RegisterDeviceClass ═══ At initialization, the driver calls the RegisterDeviceClass DevHlp to register its direct call command handler entry point with the kernel. Processing ────────────────────────────────────────────────────────────────────────── LDS SI, ADD_Name ; DS:SI = Ptr device driver to ASCIIZ name ; maximum of 16 chars MOV AX,SEGMENT ADD_Function ; AX:BX = Ptr to driver's DirectCall LEA BX,ADD_Function ; Command Handler MOV DI,Device_Flags ; Must be 0 for adapter device drivers MOV CX,Device_Class ; Must be 1 for adapter device drivers MOV DL,DevHlp_RegisterADD CALL [Device_Help] ────────────────────────────────────────────────────────────────────────── Results ────────────────────────────────────────────────────────────────────────── 'C' Cleared if successful AX = ADDHandle 'C' Set if error AX = ERROR_NOT_ENOUGH_MEMORY if CX out of range if table is full ────────────────────────────────────────────────────────────────────────── ═══ 6.4.2. GetDOSVar ═══ The existing GetDOSVar DevHlp has been modified to return a pointer to the device class table for a specified device class. This pointer is valid at initialization, task, and interrupt times, and is used by the device managers or filter device drivers to obtain the adapter device driver entry points from the kernel. Processing ────────────────────────────────────────────────────────────────────────── MOV AL,DHGETDOSV_DEVICECLASSTABLE ; Device Class table index MOV CX,Device_Class ; Must be 1 for DISK adapter device drivers MOV DL,DevHlp_GetDOSVar CALL [Device_Help] ────────────────────────────────────────────────────────────────────────── Results ────────────────────────────────────────────────────────────────────────── 'C' Cleared if successful AX:BX = global pointer to a table of registered adapter device driver entry points 'C' Set if error ────────────────────────────────────────────────────────────────────────── Remarks o Adapter Device Driver Entry Point Table format Note: MAX DCTableEntries can be different for each device class, as follows: Device_Class = 1 (disk) has a maximum of 32 entries Device_Class = 2 (mouse) has a maximum of 3 entries ────────────────────────────────────────────────────────────────────────── struct DevClassTableEntry { USHORT DCOffset; USHORT DCSelector; USHORT DCFlags; UCHAR DCName[16]; }; struct DevClassTableStruc { USHORT DCCount; USHORT DCMaxCount; struct DevClassTableEntry DCTableEntries[MAX]; }; ────────────────────────────────────────────────────────────────────────── Note: The location of the entry point for an adapter device driver can be derived from its adapter device driver handle, as follows: ────────────────────────────────────────────────────────────────────────── { USHORT i = ADDHandle - 1; AddSelector = pDevClassTable->DCTableEntries[i].DCSelector ; AddOffset = pDevClassTable->DCTableEntries[i].DCOffset ; }; ────────────────────────────────────────────────────────────────────────── ═══ 7. 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: o 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. o Program an adapter device driver to protect against timeouts and hung devices, transient environmental factors, noise, and so forth. o Ensure that the adapter device driver has the capability to properly process any scatter/gather list it receives. o 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. o 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. o 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. o An IOCM_GET_UNIT_STATUS command is not expected to fail, regardless of the condition of the underlying devices. o The IOCM_GET_DEVICE_TABLE command addresses the entire adapter device driver rather than a specific unit; ALLOCATION checks should not be performed. ═══ 7.1. 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. o 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 data that 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. o 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. o 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. o 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. o 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 StatusBlock field if requested by the device manager. The ADD should retry the operation unless the IORB_DISABLE_RETRY bit is set. IOERR_ADAPTER_NONSPECIFIC (retry required) This error should be reported when an ADD cannot classify an adapter-related error condition and an IORB StatusBlock value is not provided. If an IORB StatusBlock value is provided, IOERR_ADAPTER_REFER_TO_STATUS should be returned. o 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 Allegiance conditions. 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 StatusBlock value was not supplied. If an IORB StatusBlock value is supplied, IOERR_ADAPTER_REFER_TO_STATUS should be returned. ═══ 7.2. 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. ═══ 7.2.1. 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 │ └────────────────┴───────────────────┴──────┴────────────────────┘ ═══ 7.2.1.1. 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. ═══ 7.2.1.2. 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. ═══ 7.2.1.3. TargetStatus ═══ TargetStatus indicates the SCSI status byte returned by the target during the SCSI status bus phase. ═══ 7.2.1.4. 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. ═══ 7.2.1.5. 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. ═══ 7.2.1.6. 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. ═══ 7.2.1.7. 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. ═══ 8. 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─┬┐   ││ │ └─────────────────┘│ └───────────────────────────────────────┘ ═══ 8.1. Syntax Conventions ═══ Following are the adapter device driver syntax conventions: o Command-line contents are case-insensitive. o All command-line options begin with the slash character (/). o 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. o The alphabetic d character () indicates a decimal digit. o The alphabetic h character () indicates a hexadecimal digit. ═══ 8.2. Command-Line Parameter Classes ═══ An adapter device driver command line contains three classes of parameters: o Adapter Device Driver Parameters Adapter device driver parameters apply to all adapters and units managed by an adapter device driver unless overridden by adapter parameters or unit parameters. o Adapter Parameters Adapter parameters begin with the (/A) switch and identify a specific adapter card. Parameters following the (/A) switch apply only to the adapter card indicated. o Unit Parameters Unit parameters apply specific units on an adapter. Note: In some cases, a parameter may appear as both an Adapter parameter and a Unit parameter. If the host adapter hardware supports specifying a parameter on a per-unit basis, then it is recommended that the adapter device driver support both the per-Adapter and per-Unit forms of the parameter. ═══ 8.3. 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 /SN Synchronous 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. /ET Embedded 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. /V Verbose 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:d Adapter 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:d Adapter 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 is a small 0-based number specifying the host system slot. /P::hhhh Adapter 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, 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. /DM DASD 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. /SM SCSI 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. /I Ignore 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. /HCW Enable 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. /HCR Enable 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. ═══ 8.4. 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 /MCA Install 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:d DMA 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:dd Interrupt 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:d Unit 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. /AHS Automatic 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:cccc Drive 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:clt Changeline 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. ═══ 8.5. 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 /V Verbose - Display driver information This parameter displays the adapter device driver level, disk controller status and drive geometry information during the OS/2 system initialization. /I Ignore 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 ────────────────────────────────────────────────────────────────────────── /R Reset 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:dd Interrupt 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:d Unit Number This parameter specifies the fixed disk drive number to which options following this parameter apply. Fixed disk drive numbers start at 0. /GEO Drive 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:dddd Drive 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. /SMS Enable 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. /LBA Enable 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. ═══ 9. DASD IOCtl Device Driver Test Tool ═══ This chapter explains the DASD IOCtl Device Driver Test Tool. ═══ 9.1. Overview ═══ The DASD IOCtl Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of DASD device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. See Using the Device Driver Test Tool (DDTT) for a description of the DDTT. The test scripts give the user a repeatable set of tests that demonstrate DASD function and performance. Errors are reported and are easily isolated to a specific test sequence and API. User input and output from each thread of the DASD tests is by way of a separate Presentation Manager window. Multi-threaded test cases log all information to single log file, clearly indicating the actual execution sequence in the event of errors. ═══ 9.2. DASD IOCtl Test Architecture ═══ The DDTT provides a common front-parser for test case scripts and also tests several devices and APIs. The following DDTT DASD IOCtl-specific stub code and grammar files are required: o DDTDASD.DLL o DASD.GRA The C++ source code DDTCDROM.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2. The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA ═══ 9.3. Installation ═══ There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2 that utilize test suites. The TESTCERT substructure contains the executables; the test cases and the TESTTOOL substructure contains the files required to change the code for a particular DLL and rebuild. The following procedure describes installation for running test cases: 1. Copy the executable and DASD IOCtl test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TDASDIO. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TDASDIO and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the DASD IOCtl test suite: [C:\]md tdasdio [C:\]cd tdasdio [C:\tdasdio]copy e:\ddk_x86\testcert\storage\function\dasd\ioctl\* [C:\tdasdio]copy e:\ddk_x86\testcert\general\ddtt\* 2. Add C:\TDASDIO to the LIBPATH and PATH in the CONFIG.SYS file. 3. Reboot your machine so the new LIBPATH entry and DEVICE statement take effect. ═══ 9.4. Test-Case Execution ═══ There are two different ways to run DASD tests. One way is to run the program from a command file. To run the command file first make sure you are in the directory in which the files were installed into and then type in TEST. The command file will run all of the script files. Another way to run DASD IOCtl tests is to run each script file individually. To run one script file at a time, see Description of Test Cases for a description of each script file. After deciding on a script file to run, type in DDTT followed by the script file name: [C:\fvt\ddt\ioctl]DDTT GLPARAMS.SCR After the script has finished executing, control will transfer back to the OS/2 Window. If you decide to run the script files individually, and you have not run the TEST command file first, run SETINFO to setup the drive letter of a logical drive and the drive number of a physical drive. The SETINFO command file will set up the necessary information that is needed for the DASD IOCtl script files. The command file will ask the following two questions. (The physical numbering starts at 1 not 0.) PLEASE ENTER IN THE DRIVE LETTER OF THE LOGICAL DRIVE YOU WOULD LIKE TO TEST ex: D ? d PLEASE ENTER IN THE DRIVE NUMBER OF THE PHYSICAL DRIVE YOU WOULD LIKE TO TEST ex: 1 ? 2 After you input this information, the command file will store this information in two different files. The files are SYSINFO.TXT and SYSINFO2.TXT. The contents of SYSINFO.TXT are: da SET DEVICENAME=D: The contents of SYSINFO2.TXT are: da SET DISKNUMBER=2: ═══ 9.4.1. DASD IOCtl Test Grammar Function Calls ═══ The following is a list of DASD IOCtl Test Grammar Function Calls: o DASD_OPEN o DASD_CLOSE o LOCK_LOGICAL o UNLOCK_LOGICAL o GET_LOGICAL_PARAMS o QMEDIA_SENSE o QLOGICAL_MAP o SET_LOGICAL_MAP o BLOCK_REMOVABLE o REDETERMINE_MEDIA o READ_LOGICAL o WRITE_LOGICAL o VERIFY_LOGICAL o FORMAT_TRACK o OPEN_PHYSICAL o CLOSE_PHYSICAL o LOCK_PHYSICAL o UNLOCK_PHYSICAL o GET_PHYSICAL_PARAMS o WRITE_PHYSICAL o READ_PHYSICAL o VERIFY_PHYSICAL o READ_FILE o WRITE_FILE o SET_DEVICEPARAMS ═══ 9.4.1.1. DASD_OPEN ═══ This function opens one partition on a physical drive. ═══ 9.4.1.1.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DEVICENAME │STRING │Drive letter of DASD│ │ │ │device to test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.1.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.1.3. Logged Data ═══ None. ═══ 9.4.1.2. DASD_CLOSE ═══ This function closes one partition on a physical drive. ═══ 9.4.1.2.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.2.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.2.3. Logged Data ═══ None. ═══ 9.4.1.3. LOCK_LOGICAL ═══ Category 8h Function 00h - Lock Drive This function locks one partition on a physical drive. ═══ 9.4.1.3.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.3.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.3.3. Logged Data ═══ None. ═══ 9.4.1.4. UNLOCK_LOGICAL ═══ Category 8h Function 01h - Unlock Drive This function locks one partition on a physical drive. ═══ 9.4.1.4.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.4.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.4.3. Logged Data ═══ None. ═══ 9.4.1.5. GET_LOGICAL_PARAMS ═══ Category 8h Function 63h - Query Device Parameters This function gets the logical parameters of one partition on a physical drive. ═══ 9.4.1.5.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.5.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of sectors │ ├────────────────────┼────────────────────┼────────────────────┤ │CLUSTERSIZE │NUM │Size of clusters │ ├────────────────────┼────────────────────┼────────────────────┤ │FATCOUNT │NUM │Fat count │ ├────────────────────┼────────────────────┼────────────────────┤ │ROOTCOUNT │NUM │Root count │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORCOUNT │NUM │Number of sectors │ ├────────────────────┼────────────────────┼────────────────────┤ │FATSIZE │NUM │Fat size │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of tracks │ ├────────────────────┼────────────────────┼────────────────────┤ │HEADCOUNT │NUM │Number of heads │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │Number of cylinders │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.5.3. Logged Data ═══ Size of sectors Size of clusters Fat count Root count Number of sectors Fat size Size of tracks Number of heads Number of cylinders defined for the device specified Describes the physical layout of the device specified Removable media flag Changeline flag Greater than 16MB support flag ═══ 9.4.1.6. QMEDIA_SENSE ═══ Category 8h Function 60h - Query Media Sense This function returns the media sense information. ═══ 9.4.1.6.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.6.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.6.3. Logged Data ═══ MEDIA SENSE INFORMATION Returns a byte that corresponds to the type of disk that is in the 3.5-inch drive. Where: 1 = 702KB Disk 2 = 1.44MB Disk 3 = 2.88MB Disk ═══ 9.4.1.7. QLOGICAL_MAP ═══ Category 8h Function 21h - Query Logical Map This function returns the logical drive letter that was last used to reference (open) the drive. ═══ 9.4.1.7.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.7.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.7.3. Logged Data ═══ Logical drive number of the last drive letter that was used to reference the device under test. ═══ 9.4.1.8. SET_LOGICAL_MAP ═══ Category 8h Function 03h - Set Logical Map This function sets the next logical drive letter that is used to reference the drive. ═══ 9.4.1.8.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.8.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.8.3. Logged Data ═══ Logical drive currently mapped to the drive that the specified file handle is opened on. ═══ 9.4.1.9. BLOCK_REMOVABLE ═══ Category 8h Function 20h - Block Removable This function is used to determine if the media is removable or fixed. ═══ 9.4.1.9.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.9.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.9.3. Logged Data ═══ REMOVABLE MEDIA Returns a byte that specifies if the media is removable or not. Where: 0 = Removable media 1 = Nonremovable media ═══ 9.4.1.10. REDETERMINE_MEDIA ═══ Category 8h Function 02h - Redetermine Media This function redetermines media. In the process, it rebuilds the device parameters. ═══ 9.4.1.10.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.10.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.10.3. Logged Data ═══ None. ═══ 9.4.1.11. READ_LOGICAL ═══ Category 8h Function 64h - Read Track This function reads sectors from one partition on a physical drive. ═══ 9.4.1.11.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │HEAD │NUM │The physical head on│ │ │ │the drive │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │The cylinder to read│ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSTART │NUM │The logical sector │ │ │ │number where DDTT │ │ │ │will start reading │ │ │ │from │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of the sectors │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORCOUNT │NUM │Number of sectors to│ │ │ │be read │ ├────────────────────┼────────────────────┼────────────────────┤ │$BUFFER │STRING │Name of a DDTT │ │ │ │buffer where │ │ │ │information will be │ │ │ │stored │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.11.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │BUFFER CONTENTS │STRING │Information that was│ │ │ │read │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.11.3. Logged Data ═══ None. ═══ 9.4.1.12. WRITE_LOGICAL ═══ Category 8h Function 44h - Write Track This function writes to one partition on a physical drive. ═══ 9.4.1.12.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │HEAD │NUM │The physical head on│ │ │ │the drive │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │The cylinder to │ │ │ │write to │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSTART │NUM │The logical sector │ │ │ │number where DDTT │ │ │ │will start writing │ │ │ │to │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │$BUFFER │STRING │Name of a DDTT │ │ │ │buffer where │ │ │ │information is │ │ │ │stored │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.12.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.12.3. Logged Data ═══ None. ═══ 9.4.1.13. VERIFY_LOGICAL ═══ Category 8h Function 65h - Verify Track This function returns the status of one partition on a physical drive. ═══ 9.4.1.13.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │HEAD │NUM │The physical head on│ │ │ │the drive │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │The cylinder to read│ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSTART │NUM │The logical sector │ │ │ │number where DDTT │ │ │ │will start reading │ │ │ │from │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of the sectors │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORCOUNT │NUM │Number of sectors to│ │ │ │be read │ ├────────────────────┼────────────────────┼────────────────────┤ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.13.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.13.3. Logged Data ═══ None. ═══ 9.4.1.14. FORMAT_TRACK ═══ Category 8h Function 45h - Format Track This function formats a track. ═══ 9.4.1.14.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │HEAD │NUM │The physical head on│ │ │ │the drive │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of the sectors │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKNUM │NUM │Number of track to │ │ │ │format │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.14.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.14.3. Logged Data ═══ None. ═══ 9.4.1.15. OPEN_PHYSICAL ═══ This function opens an entire physical disk. ═══ 9.4.1.15.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKNUMBER │STRING │Disk number of DASD │ │ │ │device to test. │ │ │ │Example: 1: for │ │ │ │first fixed disk │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.15.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.15.3. Logged Data ═══ None. ═══ 9.4.1.16. CLOSE_PHYSICAL ═══ This function closes a physical disk. ═══ 9.4.1.16.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.16.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.16.3. Logged Data ═══ None. ═══ 9.4.1.17. LOCK_PHYSICAL ═══ Category 9h Function 00h - Lock Physical This function closes a physical disk. ═══ 9.4.1.17.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.17.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.17.3. Logged Data ═══ None. ═══ 9.4.1.18. UNLOCK_PHYSICAL ═══ Category 9h Function 01h - Unlock Physical This function unlocks a physical disk. ═══ 9.4.1.18.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.18.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.18.3. Logged Data ═══ None. ═══ 9.4.1.19. GET_PHYSICAL_PARAMS ═══ Category 9h Function 01h - Query Physical Device Parameters This function gets the parameters of a physical disk. ═══ 9.4.1.19.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.19.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDERS │NUM │Number of cylinders │ │ │ │on the physical disk│ ├────────────────────┼────────────────────┼────────────────────┤ │HEADCOUNT │NUM │Number of heads on │ │ │ │the physical disk │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Number of sectors │ │ │ │per track on the │ │ │ │physical disk │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.19.3. Logged Data ═══ Number of cylinders on the physical disk Number of heads on the physical disk Number of sectors per track on the physical disk ═══ 9.4.1.20. WRITE_PHYSICAL ═══ Category 9h Function 44h - Write Physical This function writes to a physical disk. ═══ 9.4.1.20.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ ├────────────────────┼────────────────────┼────────────────────┤ │HEAD │NUM │The physical head on│ │ │ │the drive │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │The cylinder to │ │ │ │write to │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSTART │NUM │The physical sector │ │ │ │number where DDTT │ │ │ │will start writing │ │ │ │to │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of the sectors │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │$BUFFER │STRING │Name of a DDTT │ │ │ │buffer where │ │ │ │information is │ │ │ │stored. │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.20.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.20.3. Logged Data ═══ None. ═══ 9.4.1.21. READ_PHYSICAL ═══ Category 9h Function 64h - Read Physical This function reads sectors from a physical disk. ═══ 9.4.1.21.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ ├────────────────────┼────────────────────┼────────────────────┤ │HEAD │NUM │The physical head on│ │ │ │the drive │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │The cylinder to │ │ │ │write to │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSTART │NUM │The physical sector │ │ │ │number where DDTT │ │ │ │will start writing │ │ │ │to │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORCOUNT │NUM │The number of │ │ │ │physical sectors to │ │ │ │read │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of the sectors │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │$BUFFER │STRING │Name of a DDTT │ │ │ │buffer where │ │ │ │information is │ │ │ │stored. │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.21.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │BUFFER CONTENTS │STRING │Information that was│ │ │ │read │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.21.3. Logged Data ═══ None. ═══ 9.4.1.22. VERIFY_PHYSICAL ═══ Category 9h Function 65h - Verify Physical This function returns the status of a physical disk. ═══ 9.4.1.22.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ ├────────────────────┼────────────────────┼────────────────────┤ │HEAD │NUM │The physical head on│ │ │ │the drive │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │The cylinder to │ │ │ │write to │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSTART │NUM │The physical sector │ │ │ │number where DDTT │ │ │ │will start writing │ │ │ │to │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORCOUNT │NUM │The number of │ │ │ │physical sectors to │ │ │ │read │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of the sectors │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.22.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.22.3. Logged Data ═══ None. ═══ 9.4.1.23. READ_FILE ═══ This function reads a file from a physical disk. ═══ 9.4.1.23.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ ├────────────────────┼────────────────────┼────────────────────┤ │FILENAME │STRING │The name of the file│ │ │ │to read │ ├────────────────────┼────────────────────┼────────────────────┤ │BYTESTART │NUM │The number of the │ │ │ │byte to start │ │ │ │reading from │ ├────────────────────┼────────────────────┼────────────────────┤ │BYTECOUNT │NUM │The number of bytes │ │ │ │to read │ ├────────────────────┼────────────────────┼────────────────────┤ │$BUFFER │STRING │Name of a DDTT │ │ │ │buffer where │ │ │ │information is │ │ │ │stored. │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.23.2. Output Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │BUFFER CONTENTS │STRING │Information that was│ │ │ │read │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.23.3. Logged Data ═══ None. ═══ 9.4.1.24. WRITE_FILE ═══ This function writes a file to a physical disk. ═══ 9.4.1.24.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DISKHANDLE │NUM │Disk handle for DASD│ │ │ │device under test │ ├────────────────────┼────────────────────┼────────────────────┤ │FILENAME │STRING │The name of the file│ │ │ │to read │ ├────────────────────┼────────────────────┼────────────────────┤ │BYTESTART │NUM │The number of the │ │ │ │byte to start │ │ │ │reading from │ ├────────────────────┼────────────────────┼────────────────────┤ │$BUFFER │STRING │Name of a DDTT │ │ │ │buffer where │ │ │ │information is │ │ │ │stored. │ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.24.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.24.3. Logged Data ═══ None. ═══ 9.4.1.25. SET_DEVICEPARAMS ═══ Category 8h Function 43h - Lock Drive This function sets the device parameters. ═══ 9.4.1.25.1. Input Parameter Keywords ═══ ┌────────────────────┬────────────────────┬────────────────────┐ │Keyword │Type │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for │ │ │ │DASD device under │ │ │ │test │ ├────────────────────┼────────────────────┼────────────────────┤ │SECTORSIZE │NUM │Size of the sectors │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │CLUSTERSIZE │NUM │Size of clusters │ ├────────────────────┼────────────────────┼────────────────────┤ │FATCOUNT │NUM │Fat count │ ├────────────────────┼────────────────────┼────────────────────┤ │ROOTCOUNT │NUM │Root count │ ├────────────────────┼────────────────────┼────────────────────┤ │TOTALSECTORS │NUM │Total sectors │ ├────────────────────┼────────────────────┼────────────────────┤ │FATSIZE │NUM │Fat size │ ├────────────────────┼────────────────────┼────────────────────┤ │TRACKSIZE │NUM │Size of the tracks │ │ │ │on the specified │ │ │ │device │ ├────────────────────┼────────────────────┼────────────────────┤ │HEADCOUNT │NUM │Number of heads on │ │ │ │the physical disk │ ├────────────────────┼────────────────────┼────────────────────┤ │CYLINDER │NUM │The number of │ │ │ │cylinders │ ├────────────────────┼────────────────────┼────────────────────┤ │DEVICETYPE │NUM │Describes the │ │ │ │physical layout of │ │ │ │the device specified│ └────────────────────┴────────────────────┴────────────────────┘ ═══ 9.4.1.25.2. Output Parameter Keywords ═══ None. ═══ 9.4.1.25.3. Logged Data ═══ None. ═══ 9.5. Description of Test Cases ═══ Each of the DASD IOCtl test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the DASD IOCtl grammar files. All of the DASD IOCtl test cases use the DDTT @IMPORT command to include one or more of the script files: o SYSINFO.TXT o SYSINFO2.TXT The contents of the SYSINFO*.TXT files is set by the SETINFO.CMD command file. SETINFO.CMD should be executed once to establish values for the following DDTT parameter keywords: o DEVICENAME - device name of the logical DASD device under test, for example, E: o DISKNUMBER - disk number of the physical DASD device under test, for example, 1: The SYSINFO.TXT file contains the DEVICENAME keyword and the SYSINFO2.TXT file contains the DISKNUMBER keyword. All test scripts close the channels opened to the DASD device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension, .LOG. When current status is queried (for example, track, channel, or drive), this data is written to DDTT's output windows and to the log file. Log files can be examined after the test case has completed. LOCKLOG.SCR Locks a logical drive. ULOCKLOG.SCR Unlocks a logical drive. REDETERM.SCR Redetermines the media for a drive. It will rebuild the device parameters. SLOGMAP.SCR Sets the next logical drive letter that is used to reference the drive. BLOCK.SCR Determines if the media is removable or fixed. QLOGMAP.SCR Returns the logical drive letter that was last used to reference the drive. RLOGT1.SCR Reads a track from a logical drive. WLOGT1.SCR Writes a track to a logical drive. VLOG.SCR Verifies a track on a logical drive. FORMTRK.SCR Formats a track on the drive A. QMEDIA.SCR Returns the media sense information. GLPARAMS.SCR Returns the device parameters for a logical drive. LOCKPHY.SCR Locks a physical drive. ULOCKPHY.SCR Unlocks a physical drive. VPHY.SCR Verifies a physical drive. RPHYT1.SCR Reads from a physical drive. WPHYT1.SCR Writes to a physical drive. GPPARAMS.SCR Gets the device parameters of a physical drive. READFILE.SCR Reads a file from a physical drive. WRITEFILE.SCR Writes a file to a physical drive. FORMTRK2.SCR Queries the specified drive for the number of heads and then format each head. RLOGT2.SCR Reads from a logical drive. It will loop 100 times and read the 50 sectors each time. It will log the time it starts the loop and the time when it finishes the loop. RPHYT2.SCR Reads from a physical drive. It will loop 100 times and read the 30 sectors each time. It will log the time it starts the loop and the time when it finishes the loop. WLOGT2.SCR Reads from one logical drive and then writes it to another logical drive specified. It will loop 100 times and read data from the C drive and store the data in a buffer. After the read command is finished, it will write the buffer to the specified drive. It will log the time it starts the loop and the time when it finishes the loop. WPHYT2.SCR Reads from one physical drive and then writes it to another logical drive specified. It will loop 100 times and read data from the C drive and store the data in a buffer. After the read command is finished, it will write the buffer to the specified drive. It will log the time it starts the loop and the time when it finishes the loop. ═══ 9.6. Evaluation of Test Case Results ═══ The script files test all of the different DASD IOCtl functions for physical and logical drives. After each script file has finished executing, it will log all of the test information to a log file. When all of the script files have finished executing, the command file then searches all of the log files for any errors that have occurred. The results from this search are stored in the RESULTS.TXT file. When the command file has finished searching the log files, it will also display the results on the screen. ═══ 10. DASD ADD Device Driver Test Tool ═══ ═══ 10.1. Overview ═══ The DASD ADD Functional Verification Tests (FVTs) exercise the functions defined for the Inter-Device-Communication (IDC) interface of DASD device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file. The script files can be modified using a text editor to create additional, specialized test cases. See Using the Device Driver Test Tool (DDTT) for a description of DDTT. The test scripts give the user a repeatable set of tests that demonstrate DASD function and performance. Errors are reported and are easily isolated to a specific test sequence and API. User input and output from each thread of the DASD ADD tests is by way of a separate Presentation Manager window. Multi-threaded test cases log all information to single log file, clearly indicating the actual execution sequence in the event of errors. ═══ 10.2. DASD ADD Test Architecture ═══ The DDTT provides a common front-parser for test case scripts and tests several devices and APIs. The following DDTT DASD ADD-specific files are required: o DASDADD.DLL o DASDADD.GRA. o DASDADD.SYS The C++ source code for DASDADD.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2. The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA ═══ 10.3. Installation ═══ There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2 that utilize test suites. The TESTCERT substructure contains the executables and test cases and the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL. The following procedure describes installation for running test cases: 1. Copy the executable and DASD ADD test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TDASDADD. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TDASDADD and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the DASD ADD test suite: ────────────────────────────────────────────────────────────── [C:\]md tdasdadd [C:\]cd tdasdadd [C:\tdasdadd]copy e:\ddk_x86\testcert\storage\function\dasd\add\* [C:\tdasdadd]copy e:\ddk_x86\testcert\general\ddtt\* ────────────────────────────────────────────────────────────── 2. Add C:\TDASDADD to the LIBPATH and PATH in the CONFIG.SYS file. 3. To install the device driver, edit your system's CONFIG.SYS file and add the following line: ────────────────────────────────────────────────────────────── DEVICE=c:\tdasdadd\dasdadd.sys ────────────────────────────────────────────────────────────── 4. Reboot your machine so the new LIBPATH entry and DEVICE statement take effect. ═══ 10.4. Test-Case Execution ═══ 1. Change to the directory where the DASD ADD test script files were copied, for example, c:\TDASDADD\. 2. To run the tests in synchronous mode, start TESTSY.CMD. To run in asynchronous mode, start TESTASY.CMD. Note: o Physical drive numbering starts with a "1". o Potentially destructive tests are commented out of the above command files. Review the DASDADD.GRA grammar file before using these functions. o The asynchronous tests log results to files with extensions of *.L1 and a summary of all ERRORS is collected in the RESULTS1.TXT files. The synchronous tests log results to files with extensions of *.L2 and a summary of all ERRORs is collected in the RESULTS2.TXT file. ═══ 10.4.1. DASD ADD Test Grammar Function Calls ═══ The following is a list of the DASD ADD Test Grammar Function Calls: o DD_OPEN o DD_GETDRIVERS o DD_GETDEVICETABLE o DD_ALLOCATEUNIT o DD_DEALLOCATE o DD_CHANGEUNITINFO o DD_GETMEDIAGEOMETRY o DD_SETMEDIAGEOMETRY o DD_GETDEVICEGEOMETRY o DD_SETLOGICALGEOMETRY o DD_READ o DD_READVERIFY o DD_READPREFETCH o DD_WRITE o DD_WRITEVERIFY o DD_GETUNITSTATUS o DD_GETCHANGELINESTATE o DD_GETMEDIASENSE o DD_GETLOCKSTATUS o DD_ABORT o DD_RESET o DD_SUSPEND o DD_RESUME o DD_LOCKMEDIA o DD_UNLOCKMEDIA o DD_EJECTMEDIA o DD_CDB12 o DD_CDB10 o DD_CDB6 o DD_CLOSE o DD_CHECKSTATUS ═══ 10.4.2. DASD ADD Synchronous Calls ═══ The following functions are DASD ADD Synchronous Calls. ═══ 10.4.2.1. DD_OPEN ═══ The following function opens the DASDADD SYS. ═══ 10.4.2.1.1. Input Parameter Keywords ═══ None. ═══ 10.4.2.1.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for DASD device │ │ │ │under test │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.1.3. Logged Data ═══ None. ═══ 10.4.2.2. DD_GETDRIVERS ═══ The following function gets all installed drivers of DASD device class. ═══ 10.4.2.2.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for DASD device │ │ │ │under test │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.2.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.2.3. Logged Data ═══ DRIVERS Names of installed drivers on system ═══ 10.4.2.3. DD_GETDEVICETABLE ═══ The following function gets the devicetable for a specified device driver. ═══ 10.4.2.3.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for DASD device │ │ │ │under test │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.3.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.3.3. Logged Data ═══ DEVICETABLE Add major support level Add minor support level Add handle support level Number of adapters Adapter name Adapter information Number of units this adapter supports Adapter-to-device bus protocol used Adapter I/O access Adapter host bus Adapter SCSI target ID Adapter SCSI LUN Adapter flags Unit information Unit adapter index Unit index Unit flags Unit handle Unit filter Add handle Unit type Unit queuing count Unit SCSI target ID; Unit SCSI LUN ═══ 10.4.2.4. DD_ALLOCATEUNIT ═══ The following function allocates a given unit. ═══ 10.4.2.4.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.4.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.4.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.5. DD_DEALLOCATE ═══ The following function deallocates given unit. ═══ 10.4.2.5.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.5.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.5.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.6. DD_CHANGEUNITINFO ═══ The following function changes UNITINFO for given unit. ═══ 10.4.2.6.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADAPTERINDEX │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITINDEX │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITFLAGS │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │FILTERHANDLE │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITTYPE │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │QUEUINGCOUNT │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITSCSIID │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITSCSILUN │NUM │Obtained by DD_GETDEVICETABLE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.6.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.6.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.7. DD_GETMEDIAGEOMETRY ═══ The following function gets Media Geometry for given unit. ═══ 10.4.2.7.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.7.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.7.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure TOTALSECTORS Total sectors for current media in drive BYTESPERSECTOR Total bytes-per-sector for current media in drive NUMHEAD Number of heads for current media in drive TOTALCYLINDER Total cylinders for current media in drive SECTORPERTRACK Sectors-per-track for current media in drive ═══ 10.4.2.8. DD_SETMEDIAGEOMETRY ═══ The following function sets Media Geometry for the given unit. ═══ 10.4.2.8.1. Input Parameter Keywords ═══ ┌─────────────────────────┬──────┬──────────────────────────────┐ │Keyword │Type │Description │ ├─────────────────────────┼──────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├─────────────────────────┼──────┼──────────────────────────────┤ │DRVNAME │STRING│16-character driver name │ ├─────────────────────────┼──────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├─────────────────────────┼──────┼──────────────────────────────┤ │TOTALSECTORS │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │BYTESPERSECTOR │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │NUMHEAD │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │TOTALCYLINDER │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │SECTORPERTRACK │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └─────────────────────────┴──────┴──────────────────────────────┘ ═══ 10.4.2.8.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.8.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.9. DD_GETDEVICEGEOMETRY ═══ The following function gets device geometry. ═══ 10.4.2.9.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.9.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.9.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure TOTALSECTORS Total sectors for current device. BYTESPERSECTOR Bytes-per-sector for current device. NUMHEAD Number-of-heads for current device. TOTALCYLINDER Total cylinders for current device SECTORPERTRACK Sectors-per-track for current device ═══ 10.4.2.10. DD_SETLOGICALGEOMETRY ═══ The following function sets logical geometry. ═══ 10.4.2.10.1. Input Parameter Keywords ═══ ┌─────────────────────────┬──────┬──────────────────────────────┐ │Keyword │Type │Description │ ├─────────────────────────┼──────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├─────────────────────────┼──────┼──────────────────────────────┤ │DRVNAME │STRING│16-character driver name │ ├─────────────────────────┼──────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├─────────────────────────┼──────┼──────────────────────────────┤ │TOTALSECTORS │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │BYTESPERSECTOR │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │NUMHEAD │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │TOTALCYLINDER │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │SECTORPERTRACK │NUM │Obtained by │ │ │ │DD_GETMEDIAGEOMETRY │ ├─────────────────────────┼──────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └─────────────────────────┴──────┴──────────────────────────────┘ ═══ 10.4.2.10.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.10.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.11. DD_READ ═══ The following function reads from the given unit. ═══ 10.4.2.11.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of elements in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKCOUNT │NUM │Number of sectors │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKSIZE │NUM │Sector size │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │READFLAGS │NUM │Read Flags │ │ │ │Where │ │ │ │0=NONE, │ │ │ │1=DISABLE WRITE CACHE, │ │ │ │2=DISABLE READ CACHE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │RBA │NUM │Relative Block Address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.11.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.11.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure READ BLOCKS Blocks read successfully ═══ 10.4.2.12. DD_READVERIFY ═══ The following function verifies read from the given unit. ═══ 10.4.2.12.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of elements in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKCOUNT │NUM │Number of sectors │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKSIZE │NUM │Sector size │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │READFLAGS │NUM │Read Flags │ │ │ │Where │ │ │ │0=NONE, │ │ │ │1=DISABLE WRITE CACHE, │ │ │ │2=DISABLE READ CACHE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │RBA │NUM │Relative Block Address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.12.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.12.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure Read Blocks Blocks read successfully ═══ 10.4.2.13. DD_READPREFETCH ═══ The following function reads prefetch. ═══ 10.4.2.13.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of elements in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKCOUNT │NUM │Number of sectors │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKSIZE │NUM │SECTOR SIZE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │READFLAGS │NUM │READ FLAGS │ │ │ │Where │ │ │ │0=NONE, │ │ │ │1=DISABLE WRITE CACHE, │ │ │ │2=DISABLE READ CACHE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │RBA │NUM │Relative Block Address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.13.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.13.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure READ BLOCKS Blocks read successfully ═══ 10.4.2.14. DD_WRITE ═══ The following function writes to a given unit. ═══ 10.4.2.14.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of elements in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKCOUNT │NUM │Number of sectors │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKSIZE │NUM │Sector size │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │READFLAGS │NUM │Read flags │ │ │ │Where │ │ │ │0=NONE, │ │ │ │1=DISABLE WRITE CACHE, │ │ │ │2=DISABLE READ CACHE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │RBA │NUM │Relative Block Address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.14.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.14.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure WRITTEN BLOCKS Blocks written successfully ═══ 10.4.2.15. DD_WRITEVERIFY ═══ The following function writes verify. ═══ 10.4.2.15.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of elements in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKCOUNT │NUM │Number of sectors │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BLOCKSIZE │NUM │Sector size │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │READFLAGS │NUM │Read flags │ │ │ │Where │ │ │ │0=NONE, │ │ │ │1=DISABLE WRITE CACHE, │ │ │ │2=DISABLE READ CACHE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │RBA │NUM │Relative Block Address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.15.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.15.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure WRITTEN BLOCKS Blocks written successfully ═══ 10.4.2.16. DD_GETUNITSTATUS ═══ The following function gets unit status. ═══ 10.4.2.16.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.16.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.16.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure UNIT STATUS BITS Set bits in unit status ═══ 10.4.2.17. DD_GETCHANGELINESTATE ═══ The following function gets CHANGELINE status. ═══ 10.4.2.17.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.17.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.17.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure CHANGELINE STATE CHANGELINE state ═══ 10.4.2.18. DD_GETMEDIASENSE ═══ The following function gets Media Sense. ═══ 10.4.2.18.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.18.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.18.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure MEDIA SENSE Media Sense ═══ 10.4.2.19. DD_GETLOCKSTATUS ═══ The following function gets Lock Status. ═══ 10.4.2.19.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.19.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.19.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure LOCK STATUS Lock Status ═══ 10.4.2.20. DD_ABORT ═══ The following function aborts previous request. ═══ 10.4.2.20.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.20.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.20.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.21. DD_RESET ═══ The following function resets driver. ═══ 10.4.2.21.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.21.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.21.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.22. DD_SUSPEND ═══ The following function suspends the driver function. ═══ 10.4.2.22.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.22.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.22.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.23. DD_RESUME ═══ The following function resumes driver function. ═══ 10.4.2.23.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.23.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.23.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.24. DD_LOCKMEDIA ═══ The following function locks media. ═══ 10.4.2.24.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.24.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.24.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.25. DD_UNLOCKMEDIA ═══ The following function unlocks media. ═══ 10.4.2.25.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.25.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.25.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.26. DD_EJECTMEDIA ═══ The following function ejects media. ═══ 10.4.2.26.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.26.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.26.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.27. DD_CDB12 ═══ The following function sends a 12-byte CDB to the unit. ═══ 10.4.2.27.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of buffers in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │REQUESTCONTROL │NUM │Request Control Flags │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMEOUT │NUM │Device Driver Timeout │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE0 │NUM │BYTE 0 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE1 │NUM │BYTE 1 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE2 │NUM │BYTE 2 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE3 │NUM │BYTE 3 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE4 │NUM │BYTE 4 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE5 │NUM │BYTE 5 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE6 │NUM │BYTE 6 OF THE CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE7 │NUM │BYTE 7 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE8 │NUM │BYTE 8 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE9 │NUM │BYTE 9 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE10 │NUM │BYTE 10 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE11 │NUM │BYTE 11 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.27.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.27.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.28. DD_CDB10 ═══ The following function sends a 10-byte CDB to the unit. ═══ 10.4.2.28.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of buffers in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │REQUESTCONTROL │NUM │Request Control Flags │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMEOUT │NUM │Device Driver Timeout │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE0 │NUM │Byte 0 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE1 │NUM │Byte 1 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE2 │NUM │Byte 2 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE3 │NUM │Byte 3 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE4 │NUM │Byte 4 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE5 │NUM │Byte 5 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE6 │NUM │Byte 6 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE7 │NUM │Byte 7 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE8 │NUM │Byte 8 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE9 │NUM │Byte 9 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.28.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.28.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.29. DD_CDB6 ═══ The following function sends a 6-byte CDB to the unit. ═══ 10.4.2.29.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Handle to Unit to be tested │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total bytes in SCATTERGATHER │ │ │ │list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │Number of buffers in │ │ │ │SCATTERGATHER list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │REQUESTCONTROL │NUM │Request Control Flags │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMEOUT │NUM │Device Driver Timeout │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE0 │NUM │BYTE 0 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE1 │NUM │BYTE 1 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE2 │NUM │BYTE 2 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE3 │NUM │BYTE 3 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE4 │NUM │BYTE 4 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE5 │NUM │BYTE 5 of the CDB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │(0 OR 1) Optional │ │ │ │0 = Asynchronous (Default) │ │ │ │1 = Synchronous │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.29.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.29.3. Logged Data ═══ STATUS Only on failure ERROR Only on failure ═══ 10.4.2.30. DD_CLOSE ═══ The following function closes DASDADD SYS. ═══ 10.4.2.30.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Automatically set by DD_OPEN │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.30.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.30.3. Logged Data ═══ None. ═══ 10.4.2.31. DD_CHECKSTATUS ═══ The following function prints status and return data. ═══ 10.4.2.31.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Label assigned to Asynchronous│ │ │ │function. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 10.4.2.31.2. Output Parameter Keywords ═══ None. ═══ 10.4.2.31.3. Logged Data ═══ Function specific. ═══ 10.5. Description of Test Cases ═══ Each of the DASDADD test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the DASDADD grammar files. All test scripts close the channels opened to the DASDADD device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension, .L1 and L2. When current status is queried (for example, track, channel, or drive), this data is written to DDTT's output windows and to the log file. Log files can be examined after the test case has completed. DEVTABLE.SY Calls the DD_GETDRIVERS function and displays the installed DASD ADDs and FLTs (Filter Device Drivers) on the system. This function then prompts the user to type in the driver name to be tested, displays the devicetable for the given driver, prompts the user for a unithandle for the unit to be tested, and creates two files: SYSINFO.U1, SYSINFO2.U1. These files are included into other test scripts. Their content preserves the driver name and unit handle for the use of other test scripts. This script must be run before the rest of the test suite is run. ABORT.SY Reads asynchronously, and issues an abort message. ABORT2.SY Reads 10 times asynchronously, and issues an abort message from a separate thread. ALLOCU.SY Allocates the specified unit. That if the unit is already allocated, (most cases), it should return a valid error. CHNGUINF.SY Changes the unit information for the given unit. DRIVERS.SY Lists the installed DASD drivers on the machine. EJECTM.SY Ejects media. Only for removable media. GETCSTAT.SY Gets the changeline state for the device. Only for removable media. GETDGEO.SY Gets device geometry for the given device. GETLSTAT.SY Gets lock status for device. GETMGEO.SY Gets media geometry. GETMSENS.SY Gets media sense. Only for removable media. GETUSTAT.SY Gets unit status. LOCKM.SY Locks media. Only for removable media. READ.SY Reads synchronously. READPRE.SY Reads prefetch synchronously. READV.SY Reads verify synchronously. RESET.SY Resets unit. SETLGEO.SY Sets logical geometry. SETMGEO.SY Sets media geometry. SUSPRESU.SY Suspends and resumes a read operation. UNLOCKM.SY Unlocks media. Only for removable media. WRITE.SY Reads and then writes a block. WRITEV.SY Reads and writes with verify. ABORT.ASY Reads asynchronously, and issues an abort message asynchronously. ABORT2.ASY Reads 10 times asynchronously, and issues an abort message from a separate thread asynchronously. ALLOCU.ASY Allocates the specified unit asynchronously. Note: If the unit is already allocated (in most cases), it should return a valid error. CHNGUNINF.AS Changes the unit information for the given unit asynchronously. EJECTM.ASY Ejects media asynchronously. Only for removable media. GETCSTAT.ASY Gets the changeline state for the device asynchronously. Only for removable media. GETDGEO.ASY Gets device geometry for the given device asynchronously. GETLSTAT.ASY Gets lock status for device asynchronously. GETMGEO.ASY Gets media geometry asynchronously. GETMSENS.ASY Gets media sense asynchronously. Only for removable media. GETUSTAT.ASY Gets unit status asynchronously. LOCKM.ASY Locks media asynchronously. Only for removable media. READ.ASY Reads synchronously. READPRE.ASY Reads prefetch synchronously. READV.ASY Reads verify synchronously. RESET.ASY Resets unit asynchronously. SETLGEO.ASY Sets logical geometry asynchronously. SETMGEO.ASY Sets media geometry asynchronously. SUSPRESU.ASY Suspends and resumes read asynchronously. UNLOCKM.ASY Unlocks media asynchronously. Only for removable media. WRITE.ASY Reads and then writes a block asynchronously. WRITEV.ASY Reads and writes verify. ═══ 11. SCSI IOCtl Device Driver Test Tool ═══ The SCSI IOCtl Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of SCSI device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file. The script files can be modified using a text editor to create additional, specialized test cases. See Using the Device Driver Test Tool (DDTT) for a description of DDTT. The test scripts give the user a repeatable set of tests that demonstrate SCSI IOCtl function and performance. Errors are reported and are easily isolated to a specific test sequence and API. User input and output from each thread of the SCSI IOCtl tests is by way of a separate Presentation Manager window. Multi-threaded test cases log all information to a single log file, clearly indicating the actual execution sequence in the event of errors. ═══ 11.1. SCSI IOCtl Test Architecture ═══ The DDTT provides a common front-parser for test case scripts and tests several devices and APIs. SCSI IOCtl-specific code for the DDTT is contained in DDTSCSI.DLL. The SCSI IOCtl-specific grammar is contained in SCSI.GRA. The following DDTT SCSI IOCtl-specific stub code and grammar files are required: o DDTSCSI.DLL o SCSI.GRA The C++ source code DDTSCSI.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2. The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA ═══ 11.2. Installation ═══ There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2 that utilize test suites. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL. The following procedure describes installation for running test cases. 1. Copy the executable and SCSI IOCtl test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TSCSIIO. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TSCSIIO and the E drive contains information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the SCSI IOCtl test suite: ────────────────────────────────────────────────────────────── [C:\]md tscsiio [C:\]cd tscsiio [C:\tscsiio]copy e:\ddk_x86\testcert\storage\function\dasd\ioctl\* [C:\tscsiio]copy e:\ddk_x86\testcert\general\ddtt\* ────────────────────────────────────────────────────────────── 2. Add C:\TSCSIIO to the LIBPATH and PATH in the CONFIG.SYS file. 3. Reboot your machine so the new LIBPATH entry and DEVICE statement take effect. ═══ 11.3. Test-Case Execution ═══ 1. Change to the directory where the SCSI IOCtl test script files were copied, for example C:\TSCSIIO. 2. Execute the script ALLOCDV.SCR by entering the following command DDTT ALLOCDV.SCR This command returns the DEVICE HANDLE for the specified device (default-CD_ROM). Edit the script file SCCOM.SCR and change the value of DEVICEHANDLE. Note: o Each script file can be executed individually. o To execute all the scripts, deallocate the device by executing the script DALLOCDV.SCR and starting the command file ALL.CMD. 3. The output is written to the corresponding file names with a .LOG extension. ═══ 11.3.1. DDTT SCSI IOCtl Test Grammar Function Calls ═══ The following are the names of the SCSI IOCtl Test Grammar Function Calls: o SCSI_OPEN o SCSI_CLOSE o SCSI_PARAMS o SCSI_RESETINIT o SCSI_ENABLECACHE o SCSI_DISABLECACHE o SCSI_CACHESTATUS o SCSI_SETDEVTIMEOUT o SCSI_READDEVTIMEOUT o SCSI_TRANSFERSCB o SCSI_ALLOCATEDEVICE o SCSI_DEALLOCATEDEVICE o SCSI_PERIPHERALTYPECOUNT o SCSI_SENDABORT ═══ 11.3.1.1. SCSI_OPEN ═══ This function opens the SCSI OS2SCSI.DMD device driver by opening SCSI-02$. ═══ 11.3.1.1.1. Input Parameter Keywords ═══ None. ═══ 11.3.1.1.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.1.3. Logged Data ═══ None. ═══ 11.3.1.2. SCSI_CLOSE ═══ This function closes the SCSI device driver OS2SCSI.DMD. ═══ 11.3.1.2.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.2.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.2.3. Logged Data ═══ None. ═══ 11.3.1.3. SCSI_PARAMS ═══ This function returns information about the device. ═══ 11.3.1.3.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.3.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.3.3. Logged Data ═══ Device Key Index SCB Architecture Card Comp. Level Adapter Index Device Flags Logical Unit Number (LUN) Physical Unit Number (PUN) ═══ 11.3.1.4. SCSI_RESETINIT ═══ This function resets the physical device. ═══ 11.3.1.4.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.4.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.4.3. Logged Data ═══ None. ═══ 11.3.1.5. SCSI_ENABLECACHE ═══ This function enables the adapter cache capability for all subsequent commands to the SCSI device. ═══ 11.3.1.5.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.5.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.5.3. Logged Data ═══ None. ═══ 11.3.1.6. SCSI_DISABLECACHE ═══ This function disables the adapter cache capability for all subsequent commands to the SCSI device. ═══ 11.3.1.6.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.6.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.6.3. Logged Data ═══ None. ═══ 11.3.1.7. SCSI_CACHESTATUS ═══ This function returns the adapter cache status for the specified SCSI device. ═══ 11.3.1.7.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.7.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.7.3. Logged Data ═══ Adapter Cache Status (0-enabled, 1-disabled) ═══ 11.3.1.8. SCSI_SETDEVTIMEOUT ═══ This function sets the timeout value for the device. ═══ 11.3.1.8.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMEOUT │NUM │Time out value (msecs) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.8.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.8.3. Logged Data ═══ None. ═══ 11.3.1.9. SCSI_READDEVTIMEOUT ═══ This function returns the current timeout value for the device. ═══ 11.3.1.9.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.9.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.9.3. Logged Data ═══ Timeout value ═══ 11.3.1.10. SCSI_TRANSFERSCB ═══ This function causes a SCSI Control Block (SCB) or a chain of SCB's to be sent to the adapter. ═══ 11.3.1.10.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │PHYSICALSCBPTR │NUM │Physical Pointer to SCB │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICALSCBPTR │NUM │Logical Pointer to SCB Chain │ │ │ │Header │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │FLAGS │NUM │Flags │ │ │ │0 = Normal Length SCB │ │ │ │1 = Long SCB │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.10.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.10.3. Logged Data ═══ None. ═══ 11.3.1.11. SCSI_ALLOCATEDEVICE ═══ This function allocates a SCSI peripheral device and returns the device handle that will be used to access the device. ═══ 11.3.1.11.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │PERIPHTYPE │NUM │Device Peripheral Type: where │ │ │ │0 = Direct Access │ │ │ │1 = Sequential Access │ │ │ │2 = Printer │ │ │ │3 = Processor │ │ │ │4 = Write Once/Read Many │ │ │ │5 = CD-ROM │ │ │ │6 = Scanner │ │ │ │7 = Optical Memory │ │ │ │8 = Medium Changer │ │ │ │9 = Communications │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVTYPEFLG │NUM │Device Type Flags: where │ │ │ │The most significant bit of │ │ │ │the device type flags set │ │ │ │indicates that the media is │ │ │ │removable. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │AVAILDEV │NUM │Nth device in the device type │ │ │ │group. │ │ │ │0 = the next available device │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.11.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.11.3. Logged Data ═══ Device Handle ═══ 11.3.1.12. SCSI_DEALLOCATEDEVICE ═══ This function deallocates the SCSI peripheral device assigned to this device handle. ═══ 11.3.1.12.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.12.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.12.3. Logged Data ═══ None. ═══ 11.3.1.13. SCSI_PERIPHERALTYPECOUNT ═══ This function returns a count of the number of devices of a particular type that are detected. ═══ 11.3.1.13.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │PERIPHTYPE │NUM │Device Peripheral Type: where │ │ │ │0 = Direct Access │ │ │ │1 = Sequential Access │ │ │ │2 = Printer │ │ │ │3 = Processor │ │ │ │4 = Write Once/Read Many │ │ │ │5 = CD-ROM │ │ │ │6 = Scanner │ │ │ │7 = Optical Memory │ │ │ │8 = Medium Changer │ │ │ │9 = Communications │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVTYPEFLG │NUM │Device Type Flags: where │ │ │ │The most significant bit of │ │ │ │the device type flags set │ │ │ │indicates that the media is │ │ │ │removable. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.13.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.13.3. Logged Data ═══ Count of Device Type Requested ═══ 11.3.1.14. SCSI_SENDABORT ═══ This function sends an abort request to the device. ═══ 11.3.1.14.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the SCSI adapter, │ │ │ │set by SSCSI_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICEHANDLE │NUM │Handle for the SCSI device, │ │ │ │obtained from │ │ │ │SCSI_ALLOCATEDEVICE │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 11.3.1.14.2. Output Parameter Keywords ═══ None. ═══ 11.3.1.14.3. Logged Data ═══ None. ═══ 11.4. Description of Test Cases ═══ Each of the SCSI IOCtl test cases can be executed individually as previously described. The corresponding test scripts are described below. You can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the SCSI grammar files. All test scripts close the channels opened to the SCSI adapter/device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name with a file name extension .LOG. When current status is queried (for example, the timeout value and cache status), this data is written to the DDTT's output windows and to the log file. Log files can be examined after the test case has completed. SCCOM.SCR This is a common script which is imported by almost all the SCSI scripts. This script SETS hardware dependent keywords like DEVICEHANDLE. ABORT.SCR Causes an abort request to be sent to the device. ALLOCDV.SCR Allocates the specified SCSI peripheral device and returns the device handle that will be used to access the device. CACHSTAT.SCR Returns the adapter cache status for the specified device. DALLOCDV.SCR Deallocates the SCSI peripheral device assigned to the specified device handle. DISCACHE.SCR Disables the adapter cache capability for subsequent commands to the specified device. ENCACHE.SCR Enables the adapter cache capability for all subsequent commands to the specified device. PARAM.SCR Returns some information about the device. PTYPECT.SCR Returns a count of the number of devices of a specified type that are detected. READTOUT.SCR Returns the current timeout value of the specified device. RESET.SCR Issues a reset message to the specified physical device. SETTOUT.SCR Sets the timeout value for the specified device. ═══ 12. SCSI ADD Device Driver Test Tool ═══ ═══ 12.1. Overview ═══ The SCSI ADD Functional Verification Tests (FVTs) exercise the Inter-Device-Driver Communications (IDC) (IDCs) defined for the SCSI Adapter device drivers. The tests are implemented with the Device Driver Test Tool (DDTT) and a test device driver (DASD.SYS), which communicates directly with the SCSI Adapter device driver under test. Each test is defined in a script file. The script files can be modified using a text editor to create additional, specialized test cases. See Using the Device Driver Test Tool (DDTT) for a description of the DDTT. The test scripts give the user a repeatable set of tests that demonstrate SCSI function and performance. Errors are reported and are easily isolated to a specific test sequence and API. User input and output from each thread of the SCSI ADD tests is by way of a separate Presentation Manager window. Multi-threaded test cases log all information to single log file, clearly indicating the actual execution sequence in the event of errors. ═══ 12.2. SCSI ADD Test Architecture ═══ DDTT provides a common front-parser for test case scripts and tests several devices and APIs. The following DDTT SCSI ADD-specific stub code and grammar files are required files: o SCSIADD.DLL o SCSIADD.GRA o DASDADD.SYS The C++ source code SCSIADD.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2. The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA ═══ 12.3. Installation ═══ There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2 that utilize test suites. The TESTCERT substructure contains the executables and test cases and the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL. The following describes installation for running test cases: 1. Copy the executable and SCSI ADD test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TSCSIADD. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TSCSIADD and the E drive contains information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the SCSI ADD test suite: ────────────────────────────────────────────────────────────── [C:\]md tscsiadd [C:\]cd tscsiadd [C:\tscsiadd]copy e:\ddk_x86\testcert\storage\function\scsi\add\* [C:\tscsiadd]copy e:\ddk_x86\testcert\general\ddtt\* ────────────────────────────────────────────────────────────── 2. Add C:\TSCSIADD to the LIBPATH and PATH in the CONFIG.SYS file. 3. To install the device driver, edit your system's CONFIG.SYS file and add the following line: ────────────────────────────────────────────────────────────── DEVICE=C:\TSCSIADD\DASDADD.SYS ────────────────────────────────────────────────────────────── 4. Reboot your machine so the new LIBPATH entry and DEVICE statement take effect. ═══ 12.4. Test-Case Execution ═══ 1. Change to the directory where the SCSI ADD test script files were copied, for example, C:\TSCSIADD. 2. To execute a test, enter DDTT followed by the name of the script file. Note: Review the SCSIADD.GRA grammar file before using WRITE functions since they could be destructive. 3. The output is written to the corresponding file names with a .LOG extension. ═══ 12.4.1. DDTT SCSI ADD Test Grammar Function Calls ═══ The following are the names of the SCSI ADD Test Grammar Function Calls: o DD_OPEN o DD_CLOSE o DD_GETDRIVERS o DD_GETDEVICETABLE o READCAPACITY o READ10 o READ6 o SEEK6 o REZERO_UNIT o PREFETCH o LOCK_UNLOCK_MEDIA o START_STOP_UNIT o SYNC_CACHE o WRITE_6 o WRITE_10 o WRITE_AND_VERIFY o WRITE_SAME o READ_LONG o WRITE_LONG o VERIFY o LOCK_UNLOCK_CACHE o INQUIRY o TEST_UNIT_READY o SEND_DIAGNOSTIC o RELEASE o RESERVE o DD_CDB12 o DD_CDB10 o DD_CDB6 ═══ 12.4.1.1. DD_OPEN ═══ This function opens the DASDADD$ (DASDADD.SYS) test device driver. ═══ 12.4.1.1.1. Input Parameter Keywords ═══ None. ═══ 12.4.1.1.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.1.3. Logged Data ═══ None. ═══ 12.4.1.2. DD_CLOSE ═══ This function closes the DASDADD$ (DASDADD.SYS) test device driver. ═══ 12.4.1.2.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.2.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.2.3. Logged Data ═══ None. ═══ 12.4.1.3. DD_GETDRIVERS ═══ This function returns the names of all the installed drivers of DASD CLASS. ═══ 12.4.1.3.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.3.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.3.3. Logged Data ═══ Names of installed drivers on the system ═══ 12.4.1.4. DD_GETDEVICETABLE ═══ This function gets the devicetable for a given adapter device driver. ═══ 12.4.1.4.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.4.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.4.3. Logged Data ═══ DEVICETABLE Add major support level Add minor support level Add handle support level Number of adapters Adapter name Adapter information Number of units this adapter supports Adapter-to-device bus protocol used Adapter I/O access Adapter host bus Adapter SCSI target ID Adapter SCSI LUN Adapter flags Unit information Unit adapter index Unit index Unit flags Unit handle Unit filter Add handle Unit type Unit queuing count Unit SCSI target ID; Unit SCSI LUN ═══ 12.4.1.5. READCAPACITY ═══ This function reads information about the capacity of the logical unit. ═══ 12.4.1.5.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.5.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LAST_LOGICAL_BLOCK_ADDR │NUM │Last logical block address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of each logical block │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.5.3. Logged Data ═══ Status and error information Number of logical blocks Size of each logical block ═══ 12.4.1.6. READ10 ═══ This function reads the most recent data from the addressed logical blocks. Cache control bits can be set. ═══ 12.4.1.6.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name for the read │ │ │ │buffer(optional) │ │ │ │to be used in write operations│ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │FORCE_MEDIA_ACCESS │NUM │1 (Force access from media), 0│ │ │ │(Can access from cache) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CACHE_IF_POSSIBLE │NUM │1 (Cache if possible), 0 (Need│ │ │ │not cache it) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.6.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.6.3. Logged Data ═══ Status and error information Data read from the specified blocks ═══ 12.4.1.7. READ6 ═══ This function reads the most recent data from the addressed logical blocks. Cache control bits CANNOT be set. ═══ 12.4.1.7.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name for the read │ │ │ │buffer(optional) │ │ │ │to be used in write operations│ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │21-bit starting logical block │ │ │ │address │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.7.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.7.3. Logged Data ═══ Status and error information Data read from the specified blocks ═══ 12.4.1.8. SEEK6 ═══ This function seeks to the specified logical block address. ═══ 12.4.1.8.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │21-bit starting logical block │ │ │ │address │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.8.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.8.3. Logged Data ═══ Status and error information ═══ 12.4.1.9. REZERO_UNIT ═══ This function sets the logical unit to a specific state. Details are vendor-specific. ═══ 12.4.1.9.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.9.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.9.3. Logged Data ═══ Status and error information ═══ 12.4.1.10. PREFETCH ═══ This function reads the specified logical blocks into the adapter's cache memory. ═══ 12.4.1.10.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LAST_LOGICAL_BLOCK_ADDR │NUM │Address of the last logical │ │ │ │block │ │ │ │set by READCAPACITY │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │STATUS_RETURN_IMMED │NUM │Status to be returned │ │ │ │0 = after the operation is │ │ │ │complete │ │ │ │1 = as soon as the command │ │ │ │descriptor block is validated │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.10.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.10.3. Logged Data ═══ Status and error information Data read from the specified blocks ═══ 12.4.1.11. LOCK_UNLOCK_MEDIA ═══ This function enables (unlocks) or disables (locks) the removal of the media in the logical unit. ═══ 12.4.1.11.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOCK_UNLOCK │NUM │1 (lock media), 0 (unlock │ │ │ │media) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.11.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.11.3. Logged Data ═══ Status and error information ═══ 12.4.1.12. START_STOP_UNIT ═══ This function enables (Starts) or disables (stops) the media access operations on the logical unit. ═══ 12.4.1.12.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │STATUS_RETURN_IMMED │NUM │Status to be returned │ │ │ │0 = after the operation is │ │ │ │complete │ │ │ │1 = as soon as the command │ │ │ │descriptor block is validated │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │START_STOP │NUM │Start/Stop media access │ │ │ │0 = stops the logical unit │ │ │ │(cannot access media) │ │ │ │1 = makes the logical unit │ │ │ │ready for use │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOAD_EJECT │NUM │Loads/Ejects the media │ │ │ │0 = no action is taken │ │ │ │1= medium is unloaded if │ │ │ │START_STOP is zero (STOP) │ │ │ │medium is loaded if START_STOP│ │ │ │is one (START) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.12.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.12.3. Logged Data ═══ Status and error information ═══ 12.4.1.13. SYNC_CACHE ═══ This function ensures that the logical blocks in the cache memory (within the specified range) have their most recent data value recorded on the physical medium. ═══ 12.4.1.13.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LAST_LOGICAL_BLOCK_ADDR │NUM │Address of the last logical │ │ │ │block │ │ │ │set by READCAPACITY │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │STATUS_RETURN_IMMED │NUM │Status to be returned │ │ │ │0 = after the operation is │ │ │ │complete │ │ │ │1 = as soon as the command │ │ │ │descriptor block is validated │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.13.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.13.3. Logged Data ═══ Status and error information Data read from the specified blocks ═══ 12.4.1.14. WRITE6 ═══ This function writes data to the medium. Cache control bits are not provided. ═══ 12.4.1.14.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name of the buffer to write │ │ │ │data from │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │21-bit starting logical block │ │ │ │address │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.14.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.14.3. Logged Data ═══ Status and error information Data written to the specified blocks ═══ 12.4.1.15. WRITE10 ═══ This function writes data to the medium. Cache control bits can be set. ═══ 12.4.1.15.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name of the buffer to write │ │ │ │data from │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │FORCE_MEDIA_ACCESS │NUM │1 (Force access from media), 0│ │ │ │(can access from cache) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CACHE_IF_POSSIBLE │NUM │1 (Cache if possible), 0 (Need│ │ │ │not cache it) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.15.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.15.3. Logged Data ═══ Status and error information Data written to the specified blocks ═══ 12.4.1.16. WRITE_AND_VERIFY ═══ This function writes the data to the medium and verifies if data is correctly written. ═══ 12.4.1.16.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name of the buffer to write │ │ │ │data from │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BYTE_CHECK │NUM │Verify data │ │ │ │0 = no data comparison │ │ │ │1 = byte-by-byte compare │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CACHE_IF_POSSIBLE │NUM │1 (Cache if possible), 0 (Need│ │ │ │not cache it) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.16.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.16.3. Logged Data ═══ Status and error information Data written to the specified blocks ═══ 12.4.1.17. WRITE_SAME ═══ This function writes the single block of data to the medium multiple times. ═══ 12.4.1.17.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name of the buffer to write │ │ │ │data from │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LAST_LOGICAL_BLOCK_ADDR │NUM │Address of the last logical │ │ │ │block │ │ │ │set by READCAPACITY │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_DATA │NUM │Logical block data │ │ │ │1 = replaces the first four │ │ │ │bytes of the data to be │ │ │ │written to the current logical│ │ │ │block with the logical block │ │ │ │address of the block currently│ │ │ │being written. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │PHYSICAL_BLOCK_DATA │NUM │Physical block data │ │ │ │1 = replaces the first eight │ │ │ │bytes of the data to be │ │ │ │written to the current │ │ │ │physical sector with the │ │ │ │physical address of the sector│ │ │ │currently being written using │ │ │ │the physical sector format. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.17.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.17.3. Logged Data ═══ Status and error information Data written to the specified blocks ═══ 12.4.1.18. READ_LONG ═══ This function reads the most recent data from the addressed logical block (reads only one block). The data passed is vendor-specific, but includes the data bytes and the ECC bytes recorded on the medium. ═══ 12.4.1.18.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name for the read │ │ │ │buffer(optional) │ │ │ │to be used in write operations│ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BYTES │NUM │No of bytes to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ECC_CORRECT │NUM │ECC correction │ │ │ │0 = read without making any │ │ │ │correction │ │ │ │1 = data to be corrected by │ │ │ │ECC before transferring │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.18.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.18.3. Logged Data ═══ Status and error information Data read from the specified block ═══ 12.4.1.19. WRITE_LONG ═══ This function writes data to the medium (writes only one block). The data passed is implementation-specific, but includes the data bytes and the ECC bytes recorded on the medium. The READ LONG command is usually issued before issuing a WRITE LONG command. ═══ 12.4.1.19.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SCATGAT │STRING │Name of the buffer to write │ │ │ │data from │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BYTES │NUM │No of bytes to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.19.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.19.3. Logged Data ═══ Status and error information Data written to the specified block ═══ 12.4.1.20. SET_LIMITS ═══ This function defines the range within which subsequent linked commands can operate. ═══ 12.4.1.20.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing status and error │ │ │ │information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LAST_LOGICAL_BLOCK_ADDR │NUM │Address of the last logical │ │ │ │block │ │ │ │set by READCAPACITY │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │WRITE_INHIBIT │NUM │Write inhibit │ │ │ │1 = write operations within │ │ │ │the range will be inhibited. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │READ_INHIBIT │NUM │Read inhibit │ │ │ │1 = read operations within the│ │ │ │range will be inhibited. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.20.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.20.3. Logged Data ═══ Status and error information ═══ 12.4.1.21. VERIFY ═══ This function verifies the data written on the medium. ═══ 12.4.1.21.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BYTE_CHECK │NUM │Verify data │ │ │ │0 = no data comparison │ │ │ │1 = byte-by-byte compare │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CACHE_IF_POSSIBLE │NUM │1 (Cache if possible), 0 (Need│ │ │ │not cache it) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.21.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.21.3. Logged Data ═══ Status and error information Data from the specified blocks ═══ 12.4.1.22. LOCK_UNLOCK_CACHE ═══ This function requests the target device to allow or disallow logical blocks within the specified range to be removed from the cache memory. ═══ 12.4.1.22.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_SIZE │NUM │Size of the logical block │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BLOCKS │NUM │No of blocks to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOGICAL_BLOCK_ADDR │NUM │32-bit starting logical block │ │ │ │address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDR_MODE │NUM │Addressing mode │ │ │ │0 = specified address is the │ │ │ │first logical block │ │ │ │1 = specified address is a │ │ │ │two's complement displacement │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOCK_CACHE │NUM │1 (lock cache), 0 (unlock │ │ │ │cache) │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.22.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.22.3. Logged Data ═══ Status and error information ═══ 12.4.1.23. INQUIRY ═══ This function returns information regarding parameters of the target and its attached peripheral device(s). ═══ 12.4.1.23.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BYTES │NUM │length of returned data in │ │ │ │bytes │ │ │ │should not exceed 255 │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ENABLE_VITAL_PRODUCT_DATA │NUM │Vital product data │ │ │ │0 = returns standard inquiry │ │ │ │data │ │ │ │1 = returns the optional vital│ │ │ │product data specified by the │ │ │ │page code field (not │ │ │ │implemented) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CODE_PAGE │NUM │Data page codes(not │ │ │ │implemented) │ │ │ │82h ASCII implemented │ │ │ │operating definition page │ │ │ │01h-7Fh ASCII information │ │ │ │page │ │ │ │81h Implemented operating│ │ │ │definitions page │ │ │ │80h Unit serial number │ │ │ │page │ │ │ │83h-BFh Reserved │ │ │ │C0h-FFh Vendor-specific │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.23.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.23.3. Logged Data ═══ Status and error information Standard inquiry data contains 36 bytes followed by a variable number of vendor-specific parameters. Bytes 56 - 95 are reserved for future standardization. The data contains info such as peripheral type, version, capabilities, and so on. ═══ 12.4.1.24. TEST_UNIT_READY ═══ This function checks if the logical unit is ready. ═══ 12.4.1.24.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.24.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.24.3. Logged Data ═══ Status and error information ═══ 12.4.1.25. SEND_DIAGNOSTIC ═══ This function requests the target to perform diagnostic operations on itself. ═══ 12.4.1.25.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NUM_BYTES │NUM │Parameter list length in bytes│ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNIT_OFF_LINE │NUM │Unit access permissions(not │ │ │ │implemented) │ │ │ │0 = prohibits any diagnostic │ │ │ │operations that can be │ │ │ │detected by subsequent I/O │ │ │ │processes. │ │ │ │1 = grants permission to the │ │ │ │target to perform diagnostic │ │ │ │operations that can affect the│ │ │ │user accessible medium on the │ │ │ │logical unit, for example, │ │ │ │write operations to the user │ │ │ │accessible medium, or │ │ │ │repositioning of the medium on│ │ │ │sequential access devices. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICE_OFF_LINE │NUM │Device access permissions(not │ │ │ │implemented) │ │ │ │0 = prohibits diagnostic │ │ │ │operations that can be │ │ │ │detected by subsequent I/O │ │ │ │processes. │ │ │ │1 = grants permission to the │ │ │ │target to perform diagnostic │ │ │ │operations that can affect all│ │ │ │the logical units on a target,│ │ │ │for example, alteration of │ │ │ │reservations, log parameters, │ │ │ │or sense data. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SELF_TEST │NUM │Default test-test │ │ │ │0 = requests the target │ │ │ │perform the diagnostic │ │ │ │operation specified in the │ │ │ │parameter list. │ │ │ │1 = directs the target to │ │ │ │complete its default │ │ │ │self-test. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │PAGE_FORMAT │NUM │Page structure │ │ │ │0 = parameters are as │ │ │ │specified in SCSI-1 (all │ │ │ │parameters are │ │ │ │vendor-specific). │ │ │ │1 = parameters conform to the│ │ │ │page structure as specified in│ │ │ │the International Standard. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.25.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.25.3. Logged Data ═══ Status and error information ═══ 12.4.1.26. RELEASE ═══ This function releases the previously reserved logical unit. ═══ 12.4.1.26.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │EXTENT_RELEASE │NUM │Release extents (not │ │ │ │implemented) │ │ │ │0 = terminates all │ │ │ │non-third-party logical unit │ │ │ │and extent reservations that │ │ │ │are active on the specified │ │ │ │logical unit. The reservation │ │ │ │ID field is ignored. │ │ │ │1 = terminates any reservation│ │ │ │matching the reservation │ │ │ │identification. Other │ │ │ │reservations will remain in │ │ │ │effect. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │THIRD_PARTY_DEVICE_ID │NUM │Third party device ID │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │THIRD_PARTY_RELEASE │NUM │Third party release │ │ │ │0 = Third Party release is not│ │ │ │requested. │ │ │ │1 = Releases the specified │ │ │ │logical unit or extents. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │RESERVATION_ID │NUM │Reservation ID │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.26.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.26.3. Logged Data ═══ Status and error information ═══ 12.4.1.27. RESERVE ═══ This function reserves a logical unit. ═══ 12.4.1.27.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │EXTENT_RESERVE │NUM │Reserve extents (not │ │ │ │implemented) │ │ │ │0 = Reserves the entire │ │ │ │logical unit for exclusive use│ │ │ │1 = Reserves the extents │ │ │ │specified │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │THIRD_PARTY_DEVICE_ID │NUM │Third party device ID │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │THIRD_PARTY_RESERVE │NUM │Third party reserve │ │ │ │0 = Third Party reservation is│ │ │ │not requested. │ │ │ │1 = Reserves the specified │ │ │ │logical unit or extents. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │RESERVATION_ID │NUM │Reservation ID │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.27.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.27.3. Logged Data ═══ Status and error information ═══ 12.4.1.28. DD_CDB12 ═══ This function sends a CDB for 12-byte commands. ═══ 12.4.1.28.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total no of bytes in │ │ │ │Scatter/Gather list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │No of buffers in │ │ │ │Scatter/Gather list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │REQUESTCONTROL │NUM │Request Control flags │ │ │ │0x01 Asynchronous post │ │ │ │enabled │ │ │ │0x02 IORB Chain Link enabled│ │ │ │0x04 CHS fmt addr in RBA │ │ │ │Field │ │ │ │0x08 Obtain Status Block │ │ │ │Data │ │ │ │0x10 Disable retries in ADD │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMEOUT │NUM │Device driver timeout (secs) │ │ │ │0 = default set by the driver.│ │ │ │-1 = infinite. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE0 │NUM │Byte 0 of the CDB. │ │ │ │Operation Code │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE1 │NUM │Byte 1 of the CDB. │ │ │ │bits 0-4 = Command specific │ │ │ │ 5-7 = LUN (ZERO) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE2 │NUM │Byte 2 of the CDB. │ │ │ │MSB of the starting logical │ │ │ │block address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE3 │NUM │Byte 3 of the CDB. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE4 │NUM │Byte 4 of the CDB. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE5 │NUM │Byte 5 of the CDB. │ │ │ │LSB of the starting logical │ │ │ │block address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE6 │NUM │Byte 6 of the CDB. │ │ │ │MSB of Transfer/Parameter │ │ │ │list/Allocation length │ │ │ │(command specific) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE7 │NUM │Byte 7 of the CDB. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE8 │NUM │Byte 8 of the CDB. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE9 │NUM │Byte 9 of the CDB. │ │ │ │LSB of Transfer/Parameter │ │ │ │list/Allocation length │ │ │ │(command specific) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE10 │NUM │Byte 10 of the CDB (Reserved).│ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE11 │NUM │Byte 11 of the CDB - Control │ │ │ │Field │ │ │ │Bit 0 = Link bit │ │ │ │ 1 = flag bit │ │ │ │2-5 = Reserved │ │ │ │6-7 = Vendor-specific │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.28.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.28.3. Logged Data ═══ Status and error information ═══ 12.4.1.29. DD_CDB10 ═══ This function sends a CDB for 10-byte commands. ═══ 12.4.1.29.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total no of bytes in │ │ │ │Scatter/Gather list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │No of buffers in │ │ │ │Scatter/Gather list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │REQUESTCONTROL │NUM │Request Control flags │ │ │ │0x01 Asynchronous post │ │ │ │enabled │ │ │ │0x02 IORB Chain Link enabled│ │ │ │0x04 CHS fmt addr in RBA │ │ │ │Field │ │ │ │0x08 Obtain Status Block │ │ │ │Data │ │ │ │0x10 Disable retries in ADD │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMEOUT │NUM │Device driver timeout (secs) │ │ │ │0 = default set by the driver.│ │ │ │-1 = infinite. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE0 │NUM │Byte 0 of the CDB. │ │ │ │Operation Code │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE1 │NUM │Byte 1 of the CDB. │ │ │ │bits 0-4 = Command specific │ │ │ │ 5-7 = LUN (ZERO) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE2 │NUM │Byte 2 of the CDB. │ │ │ │MSB of the starting logical │ │ │ │block address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE3 │NUM │Byte 3 of the CDB. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE4 │NUM │Byte 4 of the CDB. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE5 │NUM │Byte 5 of the CDB. │ │ │ │LSB of the starting logical │ │ │ │block address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE6 │NUM │Byte 6 of the CDB (Reserved). │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE7 │NUM │Byte 7 of the CDB. │ │ │ │MSB of Transfer/Parameter │ │ │ │list/Allocation length │ │ │ │(command specific) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE8 │NUM │Byte 8 of the CDB. │ │ │ │LSB of Transfer/Parameter │ │ │ │list/Allocation length │ │ │ │(command specific) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE9 │NUM │Byte 9 of the CDB - Control │ │ │ │Field │ │ │ │Bit 0 = Link bit │ │ │ │ 1 = flag bit │ │ │ │ 2-5 = Reserved │ │ │ │ 6-7 = Vendor-specific │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.29.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.29.3. Logged Data ═══ Status and error information ═══ 12.4.1.30. DD_CDB6 ═══ This function sends a CDB for 6-byte commands. ═══ 12.4.1.30.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Handle for the DASD device │ │ │ │driver │ │ │ │set by DD_OPEN │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRVNAME │STRING │16-character driver name │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MODE │NUM │Optional │ │ │ │0 = Asynchronous mode │ │ │ │(default) │ │ │ │1 = Synchronous mode │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │UNITHANDLE │NUM │Obtained from device table │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LABEL │STRING │Name for the data block │ │ │ │containing │ │ │ │status and error information │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │MEMSIZE │NUM │Total no of bytes in │ │ │ │Scatter/Gather list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │NBUFF │NUM │No of buffers in │ │ │ │Scatter/Gather list │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │REQUESTCONTROL │NUM │Request Control flags │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMEOUT │NUM │Device driver timeout (secs) │ │ │ │ 0 = default set by the │ │ │ │driver. │ │ │ │-1 = infinite. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE0 │NUM │Byte 0 of the CDB. │ │ │ │Operation Code │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE1 │NUM │Byte 1 of the CDB. │ │ │ │bits 0-4 = MSB of the starting│ │ │ │logical block addr │ │ │ │ 5-7 = LUN (ZERO) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE2 │NUM │Byte 2 of the CDB. │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE3 │NUM │Byte 3 of the CDB. │ │ │ │LSB of the starting logical │ │ │ │block address │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE4 │NUM │Byte 4 of the CDB │ │ │ │Transfer/Parameter │ │ │ │list/Allocation length │ │ │ │(command specific) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │CDB_BYTE5 │NUM │Byte 5 of the CDB - Control │ │ │ │Field │ │ │ │Bit 0 = Link bit │ │ │ │ 1 = flag bit │ │ │ │ 2-5 = Reserved │ │ │ │ 6-7 = Vendor-specific │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 12.4.1.30.2. Output Parameter Keywords ═══ None. ═══ 12.4.1.30.3. Logged Data ═══ Status and error information ═══ 12.5. Description of Test Cases ═══ Each of the SCSI ADD test cases can be executed individually as previously described. The corresponding test scripts are described below. You can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the SCSI ADD grammar files. All test scripts close the channels opened to the SCSI adapter or device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name with a file name extension .LOG. When current status is queried (for example, for the timeout value and cache status), this data is written to the DDTT's output windows and to the log file. Log files can be examined after the test case has completed. SCSICOM.SCR ASSIGN COMMON KEYWORDS - This is a common script which is imported by almost all the SCSIADD scripts. This script sets hardware-dependent keywords such as DRVNAME, UNITHANDLE. DEVTABLE.SCR GET DEVICE TABLE - Prints the currently loaded drivers, and prints the device table for the device driver specified in the script SCSICOM.SCR DRIVERS.SCR GET DRIVERS - Prints the currently loaded drivers to the log file. INQUIRY.SCR INQUIRY - Returns information regarding parameters of the target and its attached peripheral device(s). LCKCACH.SCR LOCK CACHE - Requests the target device to disallow logical blocks within the specified range to be removed from the cache memory. LCKMED.SCR LOCK MEDIA - Disables the removal of the media in the logical unit. PREFETCH.SCR PRE-FETCH - Reads the specified logical blocks into the adapter's cache memory. READLONG.SCR READ LONG - Reads the most recent data from the addressed logical block (reads only one block). The data passed is vendor-specific, but includes the data bytes and the ECC bytes recorded on the medium. READ10.SCR READ(10) - Reads the most recent data from the addressed logical blocks. Cache control bits can be set. READ6.SCR READ(6) - Reads the most recent data from the addressed logical blocks. Cache controlbits are not provided. READCAP.SCR READ CAPACITY - Reads information about the capacity of the logical unit. It returns the logical block address and the block length in bytes of the last logical block on the logical unit. RELEASE.SCR RELEASE - Releases the previously reserved logical unit. RESERVE.SCR RESERVE - Reserves a logical unit. REZERO.SCR REZERO UNIT - Sets the logical unit to a specific state. Details are vendor-specific. SEEK6.SCR SEEK(6) - Seeks to the specified logical block address. SETLIMIT.SCR SET LIMITS - Defines the range within which subsequent linked commands can operate. SNDIAGNO.SCR SEND DIAGNOSTIC - Requests the target to perform diagnostic operations on itself. START.SCR START UNIT - Enables the media access operations on the logical unit. STOP.SCR STOP UNIT - Disables the media access operations on the logical unit. SYNCACHE.SCR SYNCHRONIZE CACHE - Ensures that logical blocks in the cache memory, within the specified range, have their most recent data value recorded on the physical medium. TSTREADY TEST READY - Checks if the logical unit is ready. UNLKCACH.SCR UNLOCK CACHE - Requests the target device to allow logical blocks within the specified range to be removed from the cache memory. UNLCKMED.SCR UNLOCK MEDIA - Enables the removal of the media in the logical unit. VERIFY.SCR VERIFY - Verifies the data written on the medium. WRITE10.SCR WRITE(10) - Writes data to the medium. Cache control bits can be set. WRITE6.SCR WRITE(6) - Writes data to the medium. Cache control bits are not provided. WRTLONG.SCR WRITE LONG - Writes data to the medium ( writes only one block). The data passed is implementation-specific, but includes the data bytes and the ECC bytes recorded on the medium. The READ LONG command is usually issued before issuing a WRITE LONG command. WRTSAME.SCR WRITE SAME - Writes the single block of data to the medium multiple times. WRTVERFY.SCR WRITE AND VERIFY - Writes the data to the medium and then verify the data is correctly written. ═══ 13. 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. ═══ 13.1. 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: 1. Edit the target unit's UNITINFO table, but do not allocate permanent ownership of the unit. 2. 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. ═══ 13.2. 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. ═══ 13.3. 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. 1. 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. 2. 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. ═══ 13.4. 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. ═══ 13.5. IORBs and Filtering ═══ Once installed, a filter device driver can apply the following to the IORBs it is filtering: o Generally, the filter device driver will retain the original IORB and create new IORBs to pass on to the downstream drivers. o 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. ═══ 14. 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: o 'C' interface to the DevHlp kernel services o Timer services o Scatter/gather buffer transfers o RBA <-> CHS computations o DMA setup and channel control, ISA bus machines o 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. ═══ 15. CD-ROM Device Manager Interface Specification ═══ This chapter contains a description of: o CD-ROM device management o SCSI and Non-SCSI adapter drivers o Command support ═══ 15.1. Overview ═══ The following figure illustrates the layered CD-ROM Device Management structure in the OS/2 operating system. ┌────────────────────────────────────────────────────────┐ │ CD-ROM Device Manager │ │ (OS/2 CDROM.DMD) │ └────────────────────────────────────────────────────────┘  SCSI-2 Commands  │  │ ┌─────────────────┐ │ │ SCSI-2 Emulator │ │ │ Filter │  └─────────────────┘ ┌────────────────────────┐  Vendor Unique    SCSI-1 Commands ┌──────────────────────┐ ┌───────────────────────┐ │Non-SCSI CD-ROM │ │ SCSI Bus │ │Adapter Device Driver │ │ Adapter Device Driver │ └─────────┬────────────┘ └───────────┬───────────┘   Non-SCSI CD-ROM SCSI Adapter Adapter │ │   CD-ROM Drive CD-ROM Drive ═══ 15.1.1. The CD-ROM Device Manager ═══ The OS/2 CD-ROM Device Manager (OS2CDROM.DMD) is a generic CD-ROM device driver for CD-ROM drives that comply with the ANSI SCSI-2 standard X3T9.2/86-109 (SCSI-2 draft proposed American National Standard Revision 10g). The device driver provides generic data and audio support for drives that support the command set specified in that standard. Vendor unique CD-ROM XA support and multi-session support is provided for selected drive models. The CD-ROM Device Manager provides a uniform interface between its clients and adapter device drivers. Clients of the Device Manager include: o CD-ROM Installable File System (CDFS.IFS) o Multimedia Presentation Manager/2* subsystem o virtual CD-ROM device driver (VCDROM.SYS) o OS/2 applications The CD-ROM File System communicates with the CD-ROM Device Manager using the request packet interface defined in the OS/2 Physical Device Driver Reference version 2.00 or later. The Multimedia Presentation Manager/2 subsystem and OS/2 applications communicate with the CD-ROM Device Manager using the Category 80 and 81 IOCtl services defined in the OS/2 Physical Device Driver Reference. DOS applications communicate with the CD-ROM Device Manager indirectly through the virtual DOS CD-ROM device driver VCDROM.SYS. VCDROM.SYS provides virtual support and converts the DOS application request into a file system or Cat 80/81 IOCTL request which is routed to the CD-ROM Device Manager using system device helper services. The interface between the CD-ROM Device Manager and adapter device drivers adheres to the adapter device driver interface defined in earlier chapters of this reference. The CD-ROM Device Manager converts a request from its client into a SCSI-2 command descriptor block and routes the SCSI-2 command to the specified adapter device driver. The SCSI-2 commands are sent using the IORB adapter passthru command (command code = ADAPTER_PASSTHRU, command modifier = EXECUTE_CDB). The CD-ROM Device Manager driver (OS2CDROM.DMD) is an installable block device driver and is loaded using a DEVICE= statement in CONFIG.SYS. The driver replaces CDROM.SYS, the CD-ROM device driver shipped in the OS/2 2.1 product. ═══ 15.1.2. SCSI-2 Emulation Filters ═══ SCSI CD-ROM target devices with vendor unique commands not supported in the SCSI-2 standard require a SCSI-2 emulation filter. The emulation filter maps SCSI-2 commands received from the CD-ROM Device Manager to the vendor unique commands supported by the target device. This support is required to enable audio support on CD-ROM drives that adhere to the SCSI-1 standard. The SCSI-1 standard does not define a standard command set for audio control. A SCSI-2 emulation filter is required for each vendor unique CD-ROM drive. Typically, a CD-ROM manufacturer uses the same vendor unique command set for all it's CD-ROM drives, therefore, one filter driver is required for each manufacturer. The filter driver receives SCSI-2 commands from the CD-ROM Device Manager, converts the command to it's vendor unique equivalent, and routes the filtered command to the SCSI adapter device driver. If data returned with the command needs to be filtered, the filter driver regains control when the request is complete, converts the outgoing data to it's SCSI-2 equivalent, and then returns to the CD-ROM Device Manager. The filtering process is transparent to the Device Manager and to the adapter device drivers. Filter drivers adhere to the adapter device driver interface previously defined. (See DASD, SCSI, and CD-ROM Device Manager Interface Specification.) The filter driver is loaded using the BASEDEV= statement in CONFIG.SYS. ═══ 15.1.3. SCSI Adapter Device Drivers ═══ A SCSI adapter device driver complies with the adapter device driver interface defined in DASD, SCSI, and CD-ROM Device Manager Interface Specification. It must support the ADAPTER_PASSTHRU command for EXECUTE_CDB requests. SCSI-2 commands are sent from the CD-ROM Device Manager using this command. SCSI sense data must be returned when requested. ═══ 15.1.4. Non-SCSI CD-ROM Adapter Device Drivers ═══ Several leading CD-ROM drive manufacturers use a proprietary, non-SCSI, host adapter interface for the CD-ROM drive. To support a non-SCSI CD-ROM drive, an adapter device driver is required that emulates a SCSI-2 target device. This enables the CD-ROM Device Manager to issue a common command set to it's target devices, whether or not the firmware on the target device directly supports the SCSI-2 command set. A non-SCSI CD-ROM adapter device driver adheres to the adapter device driver interface defined in DASD, SCSI, and CD-ROM Device Manager Interface Specification. It must support the ADAPTER_PASSTHRU command for EXECUTE_CDB requests, The SCSI-2 commands are sent from the CD-ROM Device Manager using this command. The SCSI-2 commands must be emulated by the adapter device driver. This includes sense data which is returned back to the CD-ROM Device Manager. ═══ 15.2. Non-SCSI CD-ROM Adapter Device Driver Specification ═══ A non-SCSI CD-ROM adapter device driver adheres to the adapter device driver interface defined in DASD, SCSI, and CD-ROM Device Manager Interface Specification. Most commands are received as SCSI-2 command descriptor blocks sent using the IORB ADAPTER_PASSTHRU command. The SCSI command descriptor blocks comply with the ANSI SCSI-2 standard X3T9.2/86-109 (SCSI-2 draft proposed American National Standard Revision 10g). The following sections describe the mandatory IORB and SCSI-2 commands that a non-SCSI CD-ROM adapter device driver must support. The command structures for the IORB command blocks are defined in IORB Control Blocks. The C Language definitions for the IORB control blocks are included in I/O Request Block - C Definitions. ═══ 15.2.1. Mandatory IORB Command Support ═══ The Adapter Device Driver must support the IORB command set defined in the table below. ┌──────────────────────────────┬──────────────────────────────┐ │Command Code │Command Modifier │ ├──────────────────────────────┼──────────────────────────────┤ │IOCC_CONFIGURATION │IOCM_GET_DEVICE_TABLE │ ├──────────────────────────────┼──────────────────────────────┤ │IOCC_UNIT_CONTROL │IOCM_ALLOCATE_UNIT │ │ │IOCM_DEALLOCATE_UNIT │ │ │IOCM_CHANGE_UNITINFO │ ├──────────────────────────────┼──────────────────────────────┤ │IOCC_GEOMETRY │IOCM_GET_MEDIA_GEOMETRY │ │ │IOCM_GET_DEVICE_GEOMETRY │ ├──────────────────────────────┼──────────────────────────────┤ │IOCC_EXECUTE_IO │IOCM_READ │ ├──────────────────────────────┼──────────────────────────────┤ │IOCC_UNIT_STATUS │IOCM_GET_UNIT_STATUS │ │ │IOCM_GET_LOCK_STATUS │ ├──────────────────────────────┼──────────────────────────────┤ │IOCC_DEVICE_CONTROL │IOCM_ABORT IOCM_RESET │ │ │IOCM_LOCK_MEDIA │ │ │IOCM_UNLOCK_MEDIA │ │ │IOCM_EJECT_MEDIA │ ├──────────────────────────────┼──────────────────────────────┤ │IOCC_ADAPTER_PASSTHRU │IOCM_EXECUTE_CDB │ └──────────────────────────────┴──────────────────────────────┘ ═══ 15.2.1.1. IOCC_CONFIGURATION ═══ For the IOCM_GET_DEVICE_TABLE command, the following information must be returned in the device table. o The Adapter-to-Device protocol in the AdapterDevBus field of the ADAPTERINFO structure must be set to AI_DEVBUS_NONSCSI_CDROM. o The UnitType field in the UNITINFO structure must be set to UIB_TYPE_CDROM o The UF_REMOVABLE bit must be set in the UnitFlags field of the UNITINFO structure. The UF_NODASD_SUPT and UF_NOSCSI_SUPT bits should be set to zero. The adapter device driver should return all other fields in the device table as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification. ═══ 15.2.1.2. IOCC_UNIT_CONTROL ═══ The IOCM_ALLOCATE_UNIT, IOCM_DEALLOCATE_UNIT and IOCM_CHANGE_UNITINFO must be supported as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification. ═══ 15.2.1.3. IOCC_GEOMETRY ═══ The geometry returned must be the same for both the IOCM_GET_MEDIA_GEOMETRY and the IOCM_GET_DEVICE_GEOMETRY commands. For both commands, only the TotalSectors and the BytesPerSector fields should be set. The TotalSectors field should be equal to the last addressable logical block address on the media + 1. This value should correspond to the value returned in the SCSI-2 Read Capacity command + 1, which is the starting address of the lead out area. The BytesPerSector field should be set to 2048. TheNumHeads, TotalCylinders and SectorsPerTrack fields should be set to 0. If there is no media present in the drive, the driver should return IOERR_UNIT_NOT_READY. ═══ 15.2.1.4. IOCC_EXECUTE_IO ═══ The adapter device driver must support the IOCM_READ command as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification. ═══ 15.2.1.5. IOCC_UNIT_STATUS ═══ The adapter device driver must support the IOCM_GET_UNIT_STATUS and IOCM_GET_LOCK_STATUS commands as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification. ═══ 15.2.1.6. IOCC_DEVICE_CONTROL ═══ The adapter device driver must support the IOCM_ABORT, IOCM_RESET, IOCM_LOCK_MEDIA, IOCM_UNLOCK_MEDIA and IOCM_EJECT_MEDIA commands as specified in DASD, SCSI, and CD-ROM Device Manager Interface Specification. ═══ 15.2.1.7. IOCC_ADAPTER_PASSTHRU ═══ The adapter device driver must support the IOCM_EXECUTE_CDB command. The list of mandatory SCSI-2 command descriptor blocks which must be supported via this command is defined in the following section. ═══ 15.2.2. Mandatory SCSI-2 Command Support ═══ The following table lists the SCSI-2 commands which must be supported. The command structure for the SCSI-2 command descriptor blocks are defined in the ANSI SCSI-2 standard X3T9.2/86-109 (SCSI-2 draft proposed American National Standard Revision 10g). Developers should refer to the ANSI SCSI-2 specification for a definition of each command. Usage notes for each command, as it relates to implementation under the OS/2 operating system, are included in the following sections. ┌────────────────────────────────────────┬────────────────────┐ │Command Name │Command Code │ ├────────────────────────────────────────┼────────────────────┤ │Group 0 Commands │ │ ├────────────────────────────────────────┼────────────────────┤ │ │ │ │TEST UNIT READY │00h │ │REQUEST SENSE │03h │ │READ (6) │08h │ │SEEK (6) │0Bh │ │INQUIRY │12h │ │MODE SELECT (6) │15h (see note) │ │MODE SENSE (6) │1Ah (see note) │ │START/STOP UNIT │1Bh │ │PREVENT/ALLOW MEDIUM REMOVAL │1Eh │ ├────────────────────────────────────────┼────────────────────┤ │Group 1 Commands │ │ ├────────────────────────────────────────┼────────────────────┤ │ │ │ │READ CD-ROM CAPACITY │25h │ │READ (10) │28h │ │SEEK (10) │2Bh │ ├────────────────────────────────────────┼────────────────────┤ │Group 2 Commands │ │ ├────────────────────────────────────────┼────────────────────┤ │ │ │ │READ SUB-CHANNEL │42h │ │READ TOC │43h │ │READ HEADER │44h │ │PLAY AUDIO (10) │45h │ │PLAY AUDIO MSF │47h │ │PAUSE/RESUME │4Bh │ ├────────────────────────────────────────┼────────────────────┤ │Vendor Unique Commands │ │ ├────────────────────────────────────────┼────────────────────┤ │READ DISC INFORMATION │F0h │ └────────────────────────────────────────┴────────────────────┘ Note: The Mode Select and Mode Sense commands need only support the Block Descriptor and the Audio Control Page (Page 0E). ═══ 15.2.2.1. TEST UNIT READY (00h) ═══ The TEST UNIT READY command provides a means to check if the logical unit is ready. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.2. REQUEST SENSE (03h) ═══ The REQUEST SENSE command requests that the target transfer sense data to the initiator. The Adapter Device Driver should return 18 bytes of sense data, as shown in the following table. ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼──────┼──────┴──────┴──────┴──────┴──────┴──────┴──────┤ │ 0 │ Valid│ Error Code (70h) │ ├──────┼──────┴────────────────────────────────────────────────┤ │ 1 │ Reserved │ ├──────┼───────────────────────────┬───────────────────────────┤ │ 2 │ Reserved │ Reserved │ ├──────┼───────────────────────────┴───────────────────────────┤ │ 3 │ (MSB) │ │ --- │ Information │ │ 6 │ (LSB) │ ├──────┼───────────────────────────────────────────────────────┤ │ 7 │ Additional Sense Length (0Ah) │ ├──────┼───────────────────────────────────────────────────────┤ │8-11 │ Reserved │ ├──────┼───────────────────────────────────────────────────────│ │ 12 │ Additional Sense Code │ ├──────┼───────────────────────────────────────────────────────┤ │ 13 │ Additional Sense Code Qualifier │ ├──────┼───────────────────────────────────────────────────────┤ │ 14 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │15-17 │ Reserved │ └──────┴───────────────────────────────────────────────────────┘ o A valid bit of zero indicates that the Information Bytes field is not defined o A valid bit if one indicates the Information Bytes field contains valid information Setting this bit is optional. If set, the Information Byte field must contain the logical block address associated with the command in error. The Sense Key, Additional Sense Code and Additional Sense Code Qualifier represent the error condition and must be returned. All other sense data fields are unused and should be set to 0. Refer to the ANSI SCSI-2 specification for a detailed description of this command and the complete list of sense key definitions. See I/O Request Block - C Definitions for a discussion on error processing and the mapping of sense data to IORB error codes. ═══ 15.2.2.3. READ (08h) and READ (028h) ═══ The READ (6-byte) and READ (10-byte) commands request that the target transfer data to the initiator. The Adapter Device Driver should return with a sense key error of 08h (Blank Check) and additional sense code of 064h (illegal mode for this track) if any of the following events occur. 1. If the requested logical block address is in an audio track and the drive does not support reading raw 2352 byte CD-DA data. 2. If the requested logical block address is a mode 2 sector and the drive does not support reading mode 2 sectors. Refer to the ANSI SCSI-2 specification for a detailed description of this command. Reading Mode-2 Sectors If the CD-ROM drive supports the reading of Mode 2 Form 1 and Mode 2 Form 2 sectors, the Adapter Device Driver should mask the complexity of reading the target sector and return successfully, even if the mode of the target sector does not match the currently specified mode for the drive. Some drives require the drive be set to the proper mode of the target sector prior to issuing the read. For those drives, the Adapter Device Driver should issue the original read, and if the read fails with an error indicating the current drive mode does not match the mode of the target sector, the adapter device driver must issue the mode select to set the proper mode and then re-issue the read request. It is the responsibility of the CD-ROM Device Manager to ensure the proper block length is specified via the Mode Select command prior to issuing the read command. So, for Mode 2 Form 1 sectors, the device manager will issue a Mode Select command to set the block length to 2048 bytes. For a Mode 2 Form 2 sector, the device manager will issue a Mode Select to set the block length to 2340 or 2352 bytes, depending on the max block length the drive supports. See the Mode Select command section MODE SELECT (15h). ═══ 15.2.2.4. SEEK (0Bh) and Seek (2Bh) ═══ The SEEK (6 byte) and SEEK (10 byte) commands request that the logical unit seek to the specified logical block address. The adapter device driver must complete the seek operation successfully even if the target sector is an audio sector. If a seek command to an audio sector is not supported by the drive, the driver should issue an alternative command which can successfully seek to the audio sector. ═══ 15.2.2.5. INQUIRY (12h) ═══ The INQUIRY command requests that information regarding parameters of the target and its attached peripheral devices(s) be sent to the initiator. The standard inquiry data contains 36 required bytes and should be returned as shown in the following table. ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼──────┴──────┴──────┼──────┴──────┴──────┴──────┴──────┤ │ 0 │ Peripheral Qual. │ Peripheral Device Type (05h) │ │ │ (00h) │ │ ├──────┼──────┬─────────────┴──────────────────────────────────┤ │ 1 │ RMB │ Device Type Modifier (00h) │ │ │ (1) │ │ ├──────┼──────┴──────┬─────────────────────────────────────────┤ │ 2 │ ISO Version │ ECMA Version (00h) ANSI Version (02h) │ │ │ (00h) │ │ ├──────┼─────────────┴─────────────┬───────────────────────────┤ │ 3 │ Reserved │Response Data Format (02h) │ ├──────┼───────────────────────────┴───────────────────────────┤ │ 4 │ Additional Length (1Fh) │ ├──────┼───────────────────────────────────────────────────────┤ │ 5 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │ 6 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │ 7 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │ 8 │(MSB) │ │ --- │ Vendor Identification │ │ 15 │(LSB) │ ├──────┼───────────────────────────────────────────────────────┤ │ 16 │(MSB) │ │ --- │ Product Identification │ │ 31 │(LSB) │ ├──────┼───────────────────────────────────────────────────────┤ │ 32 │(MSB) │ │ --- │ Product Revision Level │ │ 35 │(LSB) │ └──────┴───────────────────────────────────────────────────────┘ o The Peripheral Qualifier is set to 00h. o The Peripheral Device Type is set to 05h (CD-ROM device). o The Removable Medium (RMB) bit is set to 1 to indicate the media is removable. o The Device Type Modifier is set to 00h. o The ISO version is set to 00h. o The ECMA version is set to 00h. o The ANSI-Approved Version field is set to 02h, indicating this driver adheres to the SCSI-2 specification. o The Response Data Format field is set to 02h to indicate compatibility with the SCSI-2 standard. The Vendor Identification field contains eight bytes of ASCII data identifying the vendor of the product. For example: ────────────────────────────────────────────────────────────────────────── Byte 08 09 10 11 12 13 14 15 ASCII S O N Y sp sp sp sp Code 53h 4Fh 4Eh 59h 20h 20h 20h 20h ────────────────────────────────────────────────────────────────────────── The Product Identification field contains sixteen bytes of ASCII data identifying the product model. For example: ────────────────────────────────────────────────────────────────────────── Byte 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 ASCII C D - R O M sp C D U 5 6 1 sp sp sp Code 43h 44h 2Dh 52h 4Fh 4Dh 20h 43h 44h 55h 35h 36h 31h 20h 20h 20h ────────────────────────────────────────────────────────────────────────── The Product Revision Level field contains four bytes of ASCII data which indicates the revision level of the controller firmware. For example: ────────────────────────────────────────────────────────────────────────── Byte 32 33 34 35 ASCII 1 . 0 0 Code 31h 2Eh 30h 30h ────────────────────────────────────────────────────────────────────────── ═══ 15.2.2.6. MODE SELECT (15h) ═══ The Adapter Device Driver must support the Mode Select command for the Mode Parameter Block Descriptor and the Audio Control Parameters Page (0x0E). The mode parameter list contains a header, followed by zero or more block descriptors, followed by zero or more variable-length pages. ═══ 15.2.2.7. Mode Select Parameter List ═══ The following table describes the mode select header. ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼──────┼──────┴──────┴──────┴──────┴──────┴──────┴──────┤ │ 0 │Resv. │ │ ├──────┼──────┴────────────────────────────────────────────────┤ │ 1 │ Medium Type (00h) │ ├──────┼───────────────────────────────────────────────────────┤ │ 2 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │ 3 │ Block Descriptor Length (00h or 08h) │ └──────┴───────────────────────────────────────────────────────┘ The following table describes the mode select block descriptor. ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┤ │ 0 │ Density Code │ ├──────┼───────────────────────────────────────────────────────┤ │ 1 │ (MSB) │ │ --- │ Number of Blocks (00h) │ │ 3 │ (LSB) │ ├──────┼───────────────────────────────────────────────────────┤ │ 4 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │ 5 │ (MSB) │ │ --- │ Block Length │ │ 7 │ │ └──────┴───────────────────────────────────────────────────────┘ o The medium type is set to 00h. o The block descriptor length is set to either 00h or 08h. o The density code is set to 00h. o The number of blocks field is set to 00h. This indicates the entire disc has the block length specified. o The block length specifies the length in bytes of each logical block. ═══ 15.2.2.7.1. Block Length Support ═══ The CD-ROM Device Manager will initialize the block length to 2048 bytes per sector. When the Device Manager receives a Readlong IOCtl request (Category 80h, Function 72h), it will issue a Mode Select to change the block length to either 2340 or 2352 bytes, depending on the maximum block length the drive supports. The CD-ROM Device Manager will only issue the Mode Select command to change the block length if the current block length does not match the requested block length. Prior to the first Read Long IOCtl command, the CD-ROM Device Manager will issue a set of Mode Select commands with various block length values to determine the maximum block length the drive supports. If the Adapter Device Driver receives a Mode Select command with a Block Length value which is not supported, it should return an error with a Sense Key of 05h (Illegal Request) and the Additional Sense Code set to 26h (Invalid field in parameter list). If the drive can only read a maximum of 2340 bytes per sector, the CD-ROM Device Manager will append 12 bytes of zeros (where the sync bytes are normally placed) to each sector after the read completes. This will ensure a complete 2352 byte sector is always returned back to the application when a ReadLong IOCtl command is issued. ═══ 15.2.2.7.2. Audio Control Parameter Page ═══ The audio control parameters page sets the playback modes and output controls for subsequent PLAY AUDIO commands and any current audio playback operation. (See the table below.) ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼──────┴──────┼──────┴──────┴──────┴──────┴──────┴──────┤ │ 0 │ Reserved │ Page Code (0Eh) │ ├──────┼─────────────┴─────────────────────────────────────────┤ │ 1 │ Parameter Length (0Eh) │ ├──────┼──────────────────────────────────┬──────┬─────────────┤ │ 2 │ Reserved │Immed │ Reserved │ │ │ │ (1) │ │ ├──────┼──────────────────────────────────┴──────┴─────────────┤ │ 3-7 │ Reserved │ ├──────┼───────────────────────────┬───────────────────────────┤ │ 8 │ Reserved │ Output Port 0 Channel │ │ │ │ Selection │ ├──────┼───────────────────────────┴───────────────────────────┤ │ 9 │ Output Port 0 Volume │ ├──────┼───────────────────────────┬───────────────────────────┤ │ 10 │ Reserved │ Output Port 1 Channel │ │ │ │ Selection │ ├──────┼───────────────────────────┴───────────────────────────┤ │ 11 │ Output Port 1 Volume │ ├──────┼───────────────────────────┬───────────────────────────┤ │ 12 │ Reserved │ Output Port 2 Channel │ │ │ │ Selection (0) │ ├──────┼───────────────────────────┴───────────────────────────┤ │ 13 │ Output Port 2 Volume (0) │ ├──────┼───────────────────────────┬───────────────────────────┤ │ 14 │ Reserved │ Output Port 3 Channel │ │ │ │ Selection (0) │ ├──────┼───────────────────────────┴───────────────────────────┤ │ 15 │ Output Port 3 Volume (0) │ └──────┴───────────────────────────────────────────────────────┘ The immediate bit (Immed) is set to 1 to indicate the target shall send completion status as soon as the playback operation has been started. The Output Port channel selection specifies the audio channels from the disc to which this output port should be connected, as shown in the table below. ┌───────────────┬─────────────────────────────────────────────┐ │Channel │Function │ │Selection │ │ ├───────────────┼─────────────────────────────────────────────┤ │00h │Output port muted. │ ├───────────────┼─────────────────────────────────────────────┤ │01h │Connect audio channel 0 (left) to this output│ │ │port │ ├───────────────┼─────────────────────────────────────────────┤ │02h │Connect audio channel 1 (right) to this │ │ │output port │ ├───────────────┼─────────────────────────────────────────────┤ │03h │Connect audio channel 0 and 1 to this output │ │ │port │ ├───────────────┼─────────────────────────────────────────────┤ │04h-0Fh │Not supported │ └───────────────┴─────────────────────────────────────────────┘ The channel volume control indicates the relative volume level for this audio output port. Values between 0x00 and 0xFF and allowed. A volume level of zero indicates the output is muted, a value of 0xFF indicates maximum volume level. The Output Port 2 and Output Port 3 channel selection and volume fields (bytes 12 to 15) are reserved and are set to 0. ═══ 15.2.2.7.3. Audio Control Determination ═══ At initialization time, the CD-ROM Device Manager will issue a series of Mode Select commands with various Audio Control Parameter Pages. The Output Port Channel Select and Volume Level fields will be varied to determine the audio control capabilities of the drive. For example, an Audio Control Parameter Page is sent with volume levels different for Channel 0 and Channel 1 to determine if the drive supports independent volume levels for each channel. If the Adapter Device Driver receives a Mode Select command with an Audio Control Parameter Page which is not supported by the drive, it should return an error with a Sense Key of 05h (Illegal Request) and the Additional Sense Code set to 26h (Invalid field in parameter list). This allows the CD-ROM Device Manager to determine the audio capabilities of the drive. ═══ 15.2.2.8. MODE SENSE Command (1Ah) ═══ The MODE SENSE (6) command provides a means for a target to report parameters to the initiator. It is a complementary command to the MODE SELECT (6) command. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.9. START/STOP UNIT Command (1Bh) ═══ The START/STOP UNIT command requests the target enable or disable the logical unit for media access operations. This command is used to eject media from the drive. If a PREVENT MEDIUM REMOVAL command has been issued, a request to the disc should return with the sense key set to ILLEGAL REQUEST (O5h) and the additional sense code set to MEDIUM REMOVAL PREVENT (53h). Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.10. PREVENT/ALLOW MEDIUM REMOVAL (1Eh) ═══ The PREVENT/ALLOW MEDIUM REMOVAL command requests that the target enable or disable the removal of the medium in the logical unit. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.11. READ CD-ROM CAPACITY (25h) ═══ The READ CD-ROM CAPACITY command provides a means for the initiator to request information regarding the capacity of the logical unit. The capacity is based on the starting address of the lead-out area minus one. The logical block address returned is the address of the last user accessible block on the disc. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.12. READ SUB-CHANNEL (42h) ═══ The READ SUB-CHANNEL command requests that the target return the requested sub-channel data plus the state of audio play operations. Note: If a READ SUB CHANNEL command is issued to request the media catalog number (UPC/EAN Bar Coding), the drive should return the UPC code in ASCII format as specified in the SCSI-2 specification. Some drives return the UPC code in BCD. It should be converted to ASCII prior to returning. All other sub-channel data is returned in binary format. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.13. READ TOC (43h) ═══ The READ TOC command requests that the target transfer data from the table of contents to the initiator. For drives which do not support a READ TOC command while an audio play operation is in progress, the adapter device driver should buffer the entire TOC data when media is first mounted in the drive. This will ensure the TOC data is retrievable during an audio play operation. All TOC data is returned in binary format. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.14. READ HEADER (44h) ═══ The READ HEADER command requests that the device return the CD-ROM data block address header of the requested logical block. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.15. PLAY AUDIO (10) (45h) ═══ The PLAY AUDIO command requests the target to begin an audio playback operation. The relative address bit (RelAdr) is not used and will be set to 0. If the requested starting address is not in an audio track, the Adapter Device Driver should return with a sense key error of 08h (Blank Check) and additional sense code of 064h (illegal mode for this track). Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.16. PLAY AUDIO MSF (47h) ═══ The PLAY AUDIO MSF command requests the target to begin an audio playback operation. As specified in the SCSI-2 specification, the starting MSF address and ending MSF address fields are specified in hexadecimal (not in BCD). If the requested starting address is not in an audio track, the Adapter Device Driver should return with a sense key error of 08h (Blank Check) and additional sense code of 064h (illegal mode for this track). Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.17. PAUSE/RESUME (4Bh) ═══ The PAUSE RESUME command requests that the device stop or start an audio play operation. It shall not be considered an error to request a pause when a pause is already in effect or to request a resume when a play operation is in progress. Refer to the ANSI SCSI-2 specification for a detailed description of this command. ═══ 15.2.2.18. READ DISC INFORMATION (F0h) ═══ ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┤ │ 0 │ Operation Code (F0h) │ ├──────┼─────────────────────────────────────────┬─────────────┤ │ 1 │ Reserved │ Type │ ├──────┼─────────────────────────────────────────┴─────────────┤ │ 2-9 │ Reserved │ └──────┴───────────────────────────────────────────────────────┘ The READ DISC INFORMATION command is a vendor unique command to request information regarding capabilities of the target device. The command is also used to return the starting address of the last session for a multisession photo CD disc. ═══ 15.2.2.18.1. TYPE = 00b ═══ If the TYPE field in the command descriptor block is 00h, the adapter device driver should return the data shown in the following table: ┌──────┬─────┬──────┬──────┬──────┬──────┬──────┬──────┬───────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼─────┴──────┴──────┴──────┼──────┼──────┼──────┼───────┤ │ 0 │ Reserved │ CDDA │ Form2│ Form1│PhotoCD│ ├──────┼──────────────────────────┴──────┴──────┴──────┴───────┤ │ 1 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │ 2 │ (MSB) │ │ --- │ Maximum Block Length │ │ 3 │ (LSB) │ └──────┴───────────────────────────────────────────────────────┘ o A multisession photo CD (PhotoCD) bit set to 1 indicates the drive supports the reading of multi-session photo CD discs. o A Mode 2 Form 1 (Form1) bit set to 1 indicates the drive supports the reading of Mode 2 Form 1 sectors. o A Mode 2 Form 2 (Form2) bit set to 1 indicates the drive supports the reading of Mode 2 Form 2 sectors. o A CD-Digital Audio (CDDA) set to 1 indicates the drive supports reading 2352 byte raw CD-DA data. The Maximum Block Length field specifies the maximum block length that can be transferred by the drive during a read operation. The value should match the maximum value which can be specified in the Block Length field of the Block Descriptor during a Mode Select command. ═══ 15.2.2.18.2. TYPE = 01b ═══ If the TYPE field in the command descriptor block is 01h, the adapter device driver should return the data shown in the following table: ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ │ Byte │ │ │ │ │ │ │ │ │ ├──────┼──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┤ │ 0 │ Reserved │ ├──────┼───────────────────────────────────────────────────────┤ │ 1 │ Address of Last Session (Minutes) │ ├──────┼───────────────────────────────────────────────────────┤ │ 2 │ Address of Last Session (Seconds) │ ├──────┼───────────────────────────────────────────────────────┤ │ 3 │ Address of Last Session (Frame) │ └──────┴───────────────────────────────────────────────────────┘ If the installed media is a multi-session photo CD disc, the driver should return the absolute address of the last session. The data is returned in MSF format and is expressed in hexadecimal. If the installed media is not a multi-session photo CD disc, the driver must return zero for all fields in the returned control block. ═══ 15.2.2.19. Multi-Session Photo CD Support ═══ At initialization time, the CD-ROM Device Manager will issue the READ DISC INFORMATION command with TYPE code = 00h to determine if the drive supports the reading of multi-session photo CD discs. If the drive indicates it supports the reading of multi-session photo CD discs (by returning with the PhotoCD bit set in the returned READ DISC INFORMATION data block) the CD-ROM Device Manager will issue the READ DISC INFORMATION command with TYPE code = 01h whenever media is first mounted in the drive. If the adapter device driver indicates that a multi-session disc is mounted, the CD-ROM Device Manager will use the returned last session address to map subsequent read requests for Volume Descriptor sectors to the Volume Descriptor sectors in the last session on the disc. With this implementation, the responsibility of mapping sectors is done by the CD-ROM Device Manager and not by each adapter device driver. ═══ 15.2.3. Error Processing ═══ When a request is issued, the CD-ROM Device Manager will set the IORB_REQ_STATUSBLOCK bit in the RequestControl field of the IORB header. If this bit is set and an error occurs, the Adapter Device Driver must return a valid status block and a valid sense data block back to the Device Manager when the request completes. The status block is pointed to by the pStatusBlock field in the IORB header. It should be noted that pStatusBlock is a 16 bit near pointer, so the block is within the same segment as the IORB. The sense data is pointed to by the SenseData field in the status block. This field is a 16:16 far pointer. The length of the sense data to return is in specified in the ReqSenseLen field. The adapter device driver must set the following fields when returning sense data: 1. The IORB_ERROR and IORB_STATUSBLOCK_AVAIL bits must be set in the Status field of the IORB header. 2. The STATUS_SENSEDATA_VALID bit must be set in the Flags field of the Status Block. 3. The value in the Error Code field of the returned sense data must be set to 70h. 4. The Sense Key, Additional Sense Code and Additional Sense Code Qualifier must be set to indicate the returned error. To maintain consistency with the adapter device driver specification, an IORB error code must also be returned in the IORB header when an error occurs. This is in addition to the returned sense data information. The table below shows the mapping between Sense Data error codes and IORB error codes. If the Adapter Device Driver returns Sense Key and Sense Codes listed in the SCSI-2 specification which are not listed in the table below, the adapter device driver must map the sense key and codes to the most appropriate IORB error code. ────────────────────────────────────────────────────────────────────────── Key = Sense Key ASC = Additional Sense Code ASCQ = Additional Sense Code Qualifier ────────────────────────────────────────────────────────────────────────── ┌──────────┬───────────┬──────────────────────────┬──────────────────────────────┐ │ │ │Description │IORB Error Code │ │ │Key ASC │ │ │ │ │ASCQ │ │ │ ├──────────┼───────────┼──────────────────────────┼──────────────────────────────┤ │ │ │ │ │ │NOT READY │02h 04h 00h│Logical Unit Not Ready │IOERR_UNIT_NOT_READY │ │ │02h 04h 01h│Becoming ready │IOERR_UNIT_NOT_READY │ │ │02h 57h 00h│Unable to recover TOC │IOERR_UNIT_NOT_READY │ ├──────────┼───────────┼──────────────────────────┼──────────────────────────────┤ │ │ │ │ │ │MEDIUM │03h 02h 00h│No Seek Complete │IOERR_RBA_ADDRESSING_ERROR │ │ERROR │03h 11h 00h│Unrecovered Read Error │IOERR_RBA_CRC_ERROR │ │ │03h 11h 05h│L-EC Uncorrectable Error │IOERR_RBA_CRC_ERROR │ │ │03h 11h 06h│CIRC Unrecovered Error │IOERR_RBA_CRC_ERROR │ │ │03h 12h 00h│Address Mark Not Found │IOERR_RBA_ADDRESSING_ERROR │ │ │03h 15h 00h│Random Positioning Error │IOERR_RBA_ADDRESSING_ERROR │ │ │03h 16h 00h│Data Synchronization Error│IOERR_RBA_CRC_ERROR │ │ │03h 30h 00h│Incompatible Medium │IOERR_MEDIA_NOT_SUPPORTED │ ├──────────┼───────────┼──────────────────────────┼──────────────────────────────┤ │ │ │ │ │ │HARDWARE │04h 08h 00h│Unit Communication Fail │IOERR_DEVICE_NONSPECIFIC │ │ERROR │04h 09h 01h│Tracking Servo Failure │IOERR_DEVICE_NONSPECIFIC │ │ │04h 09h 02h│Focus Servo Failure │IOERR_DEVICE_NONSPECIFIC │ │ │04h 09h 03h│Spindle Servo Failure │IOERR_DEVICE_NONSPECIFIC │ │ │04h 44h 00h│Internal Target Failure │IOERR_DEVICE_NONSPECIFIC │ ├──────────┼───────────┼──────────────────────────┼──────────────────────────────┤ │ │ │ │ │ │ILLEGAL │05h 20h 00h│Invalid Command Code │IOERR_DEVICE_REQ_NOT_SUPPORTED│ │REQUEST │05h 21h 00h│LBA Out of Range │IOERR_RBA_ADDRESSING_ERROR │ │ │05h 24h 00h│Invalid field in CDB │IOERR_CMD_SYNTAX │ │ │05h 25h 00h│Unit not supported │IOERR_CMD_SYNTAX │ │ │05h 26h 00h│Invalid field in parmlist │IOERR_CMD_SYNTAX │ │ │05h 63h 00h│End of user area │IOERR_RBA_ADDRESSING_ERROR │ │ │05h 64h 00h│Illegal mode for track │IOERR_RBA_ADDRESSING_ERROR │ ├──────────┼───────────┼──────────────────────────┼──────────────────────────────┤ │ │ │Medium may have changed │ │ │UNIT │06h 28h 00h│Power on reset │IOERR_MEDIA_CHANGED │ │ATTENTION │06h 29h 00h│ │IOERR_DEVICE_RESET │ ├──────────┼───────────┼──────────────────────────┼──────────────────────────────┤ │ │08h 64h 00h│Illegal mode for track │IOERR_RBA_ADDRESSING_ERROR │ │BLANK │ │ │ │ │CHECK │ │ │ │ └──────────┴───────────┴──────────────────────────┴──────────────────────────────┘ ═══ 16. CD-ROM Device Driver Test Tool ═══ This chapter explains how to use the CD-ROM Device Driver Test Tool. ═══ 16.1. Overview ═══ CD-ROM Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of CD-ROM device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. See Using the Device Driver Test Tool (DDTT) for a description of the DDTT. The test scripts give the user a repeatable set of tests that demonstrate CD-ROM function and performance. Errors are reported and are easily isolated to a specific test sequence and API. User input and output from each thread of the CD-ROM tests is performed by way of a separate Presentation Manager window. Multi-threaded test cases log all information to a single log file, clearly indicating the actual execution sequence in the event of errors. ═══ 16.2. CD-ROM Test Architecture ═══ DDTT provides a common front-end parser for test-case scripts. The following DDTT CD-ROM-specific files are required: o DDTCDROM.DLL o CDROM.GRA The C++ source code for DDTCDROM.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2. The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE: o DDTT.EXE o DDTT.DLL o GLOBAL.DLL o GLOBAL.GRA ═══ 16.3. Installation ═══ There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2 that utilize test suites. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL. The following procedure describes installation for running test cases. 1. Copy the executable and CD-ROM test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TSTCDROM. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TSTCDROM and the E: drive contains the information from the IBM Developer Connection 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_x86\testcert\storage\function\cdrom\* [C:\tstcdrom]copy e:\ddk_x86\testcert\general\ddtt\* ────────────────────────────────────────────────────────────── 2. Add C:\TSTCDROM to the LIBPATH and PATH in the CONFIG.SYS file. 3. Reboot your machine so the new LIBPATH entry takes effect. ═══ 16.4. Test-Case Execution ═══ 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. There are two ways to run CD-ROM tests. To run the program from a command file, be sure the files are installed in the current directory. Then, execute the TEST command file. The command file will run all the script files. Refer to Description of Test Cases to get a description of each script file. Then, after determining which script file to run, type in DDTT followed by the script file name: ────────────────────────────────────────────────────────────── [C:\TSTCDROM]DDTT LOCK.SCR ────────────────────────────────────────────────────────────── After the script has finished executing, control will transfer back to the OS/2 Window. If the script files are run individually, and the TEST command file has not been run first, then, run SETINFO to set up your CD-ROM drive letter and a file name. There are two different sets of script files in the DDTT CD-ROM package. The first set is the audio script files and the second set is the media script files. When TEST is run, it will ask you for the drive letter of your CD-ROM drive and the name of a file on the media CD-ROM disc. For these test purposes, enter in a file that has at least 100 000 bytes. (If you do not enter in a file that has at least that many bytes, there will be some file comparison errors when the media script files run.) After you enter the file name and press Enter, the command file will then prompt you to load an audio CD-ROM disc into the CD-ROM drive. After the audio script files have been completed, the CD-ROM drive will eject the CD-ROM disc. The command file will then ask you to change the CD-ROM disc and load a data type or media CD-ROM disc. Press Enter and the command file will continue running the script files until they are all completed. To run only the audio script files, type in TESTAUD, or to run the media script files, type in TESTMED. The SETINFO command file will set up the necessary information that is needed for the CD-ROM script files. The command file will ask the following two questions: ────────────────────────────────────────────────────────────── PLEASE ANSWER THE FOLLOWING QUESTIONS. PLEASE ENTER IN THE DRIVE LETTER OF YOUR CD-ROM, FOLLOWED BY A COLON. ex E:? e: PLEASE ENTER THE NAME OF A DATA FILE ON THE CD-ROM DATA DISC. THE FILE NEEDS TO BE AT LEAST 100,000 BYTES IN LENGTH. PLEASE ENTER FILE NAME IN AS SHOWN BELOW. EXAMPLE \FILENAME OR \DIRECTORY\FILENAME PLEASE ENTER FILE NAME:? \minstall.exe ────────────────────────────────────────────────────────────── After this information is entered, the command file will store this information in three different files: SYSINFO.TXT, SYSINFO2.TXT, and SYSINFO3.TXT. The contents of the three files are the same. ────────────────────────────────────────────────────────────── CD SET DEVICENAME=E: CD SET FILENAME=E:\\minstall.exe ────────────────────────────────────────────────────────────── ═══ 16.4.1. DDTT CD-ROM Test Grammar Function Calls ═══ The following is a list of CD-ROM Test Grammar Function Calls: o CDROM_OPEN o CDROM_CLOSE o CDROM_QUERYDRIVELETTER o CDROM_EJECT o CDROM_LOCKDOOR o CDROM_UNLOCKDOOR o CDROM_QUERYAUDIODISCINFO o CDROM_QUERYAUDIOSTATUS o CDROM_QUERYDRIVERINFO o CDROM_QSECTORINFO o CDROM_QUERYVOLUMESIZE o CDROM_QUERYAUDIOTRACKINFO o CDROM_QUERYSTATUS o CDROM_QUERYUPC o CDROM_QUERYCHANINFO o CDROM_QUERYAUDIOCHANINFO o CDROM_AUDIOCHANINFO o CDROM_RESET o CDROM_STOPAUDIO o CDROM_RESUMEAUDIO o CDROM_PLAYAUDIO o CDROM_SEEK o CDROM_DRIVELOCATION o CDROM_READFILE o CDROM_READ2048 o CDROM_READ2 352 o CDROM_READPRE2 352 ═══ 16.4.1.1. CDROM_OPEN ═══ This function opens the CD-ROM. ═══ 16.4.1.1.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DEVICENAME │STRING │Drive letter of CD-ROM │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.1.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │$DRIVES │NUM │Number of CD-ROM drives in the│ │ │ │system under test │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │$FIRSTCD │NUM │Drive number for CD-ROM drive │ │ │ │in the system │ │ │ │Where: │ │ │ │00=Drive a │ │ │ │01=Drive b │ │ │ │02=Drive c, and so on. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.1.3. Logged Data ═══ None. ═══ 16.4.1.2. CDROM_CLOSE ═══ This function closes the CD-ROM. ═══ 16.4.1.2.1. Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.2.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.2.3. Logged Data ═══ None. ═══ 16.4.1.3. CDROM_QUERYDRIVELETTER ═══ Category 82h Function 60h - Return Drive-Letter Information This function queries the CD-ROM drive letter from the system. ═══ 16.4.1.3.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.3.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │$DRIVES │NUM │Number of CD-ROM drives in the│ │ │ │system under test │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │$FIRSTCD │NUM │Drive number for CD-ROM drive │ │ │ │in the system. │ │ │ │Where │ │ │ │00=Drive a │ │ │ │01=Drive b │ │ │ │02=Drive c, and so on. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.3.3. Logged Data ═══ None. ═══ 16.4.1.4. CDROM_EJECT ═══ Category 80h Function 44h - Eject Disc This function ejects the CD-ROM disc from the CD-ROM drive. ═══ 16.4.1.4.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.4.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.4.3. Logged Data ═══ None. ═══ 16.4.1.5. CDROM_LOCKDOOR ═══ Category 80h Function 46h - Lock Door This function locks the CD-ROM drive door. ═══ 16.4.1.5.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.5.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.5.3. Logged Data ═══ None. ═══ 16.4.1.6. CDROM_UNLOCKDOOR ═══ Category 80h Function 46h - Unlock Door This function unlocks the CD-ROM drive door. ═══ 16.4.1.6.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.6.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.6.3. Logged Data ═══ None. ═══ 16.4.1.7. CDROM_QUERYAUDIODISCINFO ═══ Category 81h Function 61h - Return Audio-Disc Information This function returns the first and last track numbers. This function also returns the Redbook address for leading track. ═══ 16.4.1.7.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.7.2. Output Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │HIGHTRACK │NUM │Highest track number │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │LOWTRACK │NUM │Lowest track number │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.7.3. Logged Data ═══ Highest track number Lowest track number Starting point of lead-out track ═══ 16.4.1.8. CDROM_QUERYAUDIOSTATUS ═══ Category 81h Function 65h - Audio-Status Information This function returns the audio status, and the starting and ending locations of the last playback. ═══ 16.4.1.8.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.8.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.8.3. 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 ═══ 16.4.1.9. CDROM_QUERYDRIVERINFO ═══ Category 80h Function 61h - Identify CD-ROM Driver This function identifies the device driver as a valid CD-ROM driver. ═══ 16.4.1.9.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.9.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.9.3. Logged Data ═══ CD-ROM device driver ID ═══ 16.4.1.10. CDROM_QSECTORINFO ═══ Category 80h Function 63h - Return Sector Size This function returns the number of bytes-per-sector that the device driver supports. ═══ 16.4.1.10.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.10.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.10.3. Logged Data ═══ Size of sectors on disc ═══ 16.4.1.11. CDROM_QUERYVOLUMESIZE ═══ Category 80h Function 78h - Return Volume Size This function returns the total number of accessible sectors on the disc. ═══ 16.4.1.11.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.11.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.11.3. Logged Data ═══ Volume size in sectors ═══ 16.4.1.12. CDROM_QUERYAUDIOTRACKINFO ═══ Category 81h Function 62h - Return Audio-Track Information This function returns the Redbook address for the starting point and track-control information for a specified track. ═══ 16.4.1.12.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TRACK │NUM │Track number │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.12.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.12.3. Logged Data ═══ Starting point of track Track-control information ═══ 16.4.1.13. CDROM_QUERYSTATUS ═══ Category 80h Function 60h - Device Status This function returns the device driver status codes. ═══ 16.4.1.13.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.13.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.13.3. Logged Data ═══ CD-ROM drive status information ═══ 16.4.1.14. CDROM_QUERYUPC ═══ Category 80h Function 79h - Get UPC This function returns the UPC code for the CD-ROM disc. ═══ 16.4.1.14.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.14.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.14.3. Logged Data ═══ Control and ADR byte Universal product code Frame ═══ 16.4.1.15. CDROM_QUERYCHANINFO ═══ Category 81h Function 63h - Return Audio-Subchannel Q Information This function returns track and control information while the drive is playing an audio CD-ROM disc. ═══ 16.4.1.15.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.15.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.15.3. 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 ═══ 16.4.1.16. CDROM_QUERYAUDIOCHANINFO ═══ Category 81h Function 40h - Audio Channel Control This function returns the current settings of the audio channel controls. ═══ 16.4.1.16.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.16.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.16.3. 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 Input channel for output channel 2 Volume control for output channel 2 Input channel for output channel 3 Volume control for output channel 3 ═══ 16.4.1.17. CDROM_AUDIOCHANINFO ═══ This function sets the current settings of the audio channel controls. ═══ 16.4.1.17.1. 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 │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │VOL3 │NUM │Volume for channel 2 │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │VOL4 │NUM │Volume for channel 3 │ └──────────────────────────────┴───────┴──────────────────────────────┘ EXAMPLE: ────────────────────────────────────────────────────────────── VOL1 = (0-255) VOL2 = (0-255) VOL3 = (0-255) VOL4 = (0-255) ────────────────────────────────────────────────────────────── ═══ 16.4.1.17.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.17.3. Logged Data ═══ None. ═══ 16.4.1.18. CDROM_RESET ═══ Category 80h Function 40h - Reset Drive This function resets and reinitializes the drive and controller. ═══ 16.4.1.18.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.18.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.18.3. Logged Data ═══ None. ═══ 16.4.1.19. CDROM_STOPAUDIO ═══ Category 81h Function 51h - Stop Audio This function cancels any active play request. ═══ 16.4.1.19.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.19.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.19.3. Logged Data ═══ None. ═══ 16.4.1.20. CDROM_RESUMEAUDIO ═══ Category 81h Function 52h - Resume Audio This function resumes playing audio after play has been interrupted by the stop audio command. ═══ 16.4.1.20.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.20.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.20.3. Logged Data ═══ None. ═══ 16.4.1.21. CDROM_PLAYAUDIO ═══ Category 81h Function 50h - Play Audio This function plays a selected audio track. The function can play audio by being passed a sector-start value or a time-start value. ═══ 16.4.1.21.1. 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 │NUM │If using Redbook │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMESTOP │NUM │If using Redbook │ └──────────────────────────────┴───────┴──────────────────────────────┘ EXAMPLE: LOGICAL BLOCK: ────────────────────────────────────────────────────────────── ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 SECTORCOUNT=10000 ────────────────────────────────────────────────────────────── EXAMPLE: REDBOOK: ────────────────────────────────────────────────────────────── ADDRESSMODE=REDBOOK TIMESTART=02:45:00 TIMESTOP=05:55:00 ────────────────────────────────────────────────────────────── ═══ 16.4.1.21.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.21.3. Logged Data ═══ None. ═══ 16.4.1.22. CDROM_SEEK ═══ Category 80h Function 50h - Seek This function moves the read head to a specified block that is passed to the function. The function can seek a specified block by having the sector-start value or a time-start value. ═══ 16.4.1.22.1. 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 │NUM │If using Redbook │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │TIMESTOP │NUM │If using Redbook │ └──────────────────────────────┴───────┴──────────────────────────────┘ EXAMPLE: LOGICAL BLOCK ────────────────────────────────────────────────────────────── ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 SECTORCOUNT=10000 ────────────────────────────────────────────────────────────── EXAMPLE: REDBOOK ────────────────────────────────────────────────────────────── ADDRESSMODE=REDBOOK TIMESTART=02:45:00 TIMESTOP=05:55:00 ────────────────────────────────────────────────────────────── ═══ 16.4.1.22.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.22.3. Logged Data ═══ None. ═══ 16.4.1.23. CDROM_DRIVELOCATION ═══ Category 80h Function 70h - Location of Drive Head This function returns the current drive-head location and returns the value in either addressing mode. ═══ 16.4.1.23.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDRESSMODE │STRING │Addressing mode │ │ │ │LOGICAL BLOCK or REDBOOK │ └──────────────────────────────┴───────┴──────────────────────────────┘ EXAMPLE: LOGICAL BLOCK ────────────────────────────────────────────────────────────── ADDRESSMODE=LOGICALBLOCK ────────────────────────────────────────────────────────────── EXAMPLE: REDBOOK ────────────────────────────────────────────────────────────── ADDRESSMODE=REDBOOK ────────────────────────────────────────────────────────────── ═══ 16.4.1.23.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.23.3. Logged Data ═══ Location of drive head ═══ 16.4.1.24. CDROM_READFILE ═══ DOS READ FILE This function reads a selected file from a CD-ROM disc and reads in the number of bytes that are passed to the function. ═══ 16.4.1.24.1. 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 │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BUFFER │STRING │DDTT named buffer to read data│ │ │ │into. │ └──────────────────────────────┴───────┴──────────────────────────────┘ ═══ 16.4.1.24.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.24.3. Logged Data ═══ Byte(s) read ═══ 16.4.1.25. CDROM_READ2048 ═══ DOS READ This function reads a selected file from a CD-ROM disc and simultaneously reads in a group of sectors. Each sector contains 2048 bytes. The number of sectors to read need to be passed to the function. ═══ 16.4.1.25.1. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDRESSMODE │STRING │Addressing mode: │ │ │ │LOGICAL BLOCK (only) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SECTORSTART │NUM │Starting sector to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SECTORCOUNT │NUM │Number of sectors to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BUFFER │STRING │DDTT named buffer to read data│ │ │ │into. │ └──────────────────────────────┴───────┴──────────────────────────────┘ EXAMPLE: LOGICAL BLOCK ────────────────────────────────────────────────────────────── ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 SECTORCOUNT=10000 ────────────────────────────────────────────────────────────── ═══ 16.4.1.25.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.25.3. Logged Data ═══ Byte sync Byte header Byte data area Byte EDC/ECC area ═══ 16.4.1.26. CDROM_READ2352 ═══ Category 80h Function 72h - Read Long This function reads a selected file from a CD-ROM disc and reads in a group of sectors at one time. This function reads 2 352 bytes from each sector. Also, this function is the same as READ2048, except it also reads in all of the sector header information. The number of sectors to read need to be passed to the function. ═══ 16.4.1.27. Required Input Parameter Keywords ═══ ┌──────────────────────────────┬───────┬──────────────────────────────┐ │Keyword │Type │Description │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │DRIVEHANDLE │NUM │Drive handle for CD-ROM drive │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │ADDRESSMODE │STRING │Addressing mode: │ │ │ │LOGICAL BLOCK (only) │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SECTORSTART │NUM │Starting sector to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SECTORCOUNT │NUM │Number of sectors to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │BUFFER │STRING │DDTT named buffer to read data│ │ │ │into │ └──────────────────────────────┴───────┴──────────────────────────────┘ EXAMPLE: LOGICAL BLOCK ────────────────────────────────────────────────────────────── ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 SECTORCOUNT=10000 ────────────────────────────────────────────────────────────── ═══ 16.4.1.27.1. Output Parameter Keywords ═══ None. ═══ 16.4.1.27.2. Logged Data ═══ Byte sync Byte header Byte data area Byte EDC/ECC area ═══ 16.4.1.28. CDROM_READPRE2352 ═══ Category 81h Function 71h - Read Long Prefetch This function reads a selected file from a CD-ROM disc and reads in a group of sectors at one time. This function reads 2 352 bytes from each sector. This function is the same as READ2 352, except it prefetches the sector information. This will read in the sector information in anticipation of a system request for the sector information. The number of sectors to read need to be passed to the function. ═══ 16.4.1.28.1. 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 │Starting sector to read │ ├──────────────────────────────┼───────┼──────────────────────────────┤ │SECTORCOUNT │NUM │Number of sectors to read │ └──────────────────────────────┴───────┴──────────────────────────────┘ EXAMPLE: LOGICAL BLOCK ────────────────────────────────────────────────────────────── ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 SECTORCOUNT=10000 ────────────────────────────────────────────────────────────── ═══ 16.4.1.28.2. Output Parameter Keywords ═══ None. ═══ 16.4.1.28.3. Logged Data ═══ Byte sync Byte header Byte data area Byte EDC/ECC area ═══ 16.5. Description of Test Cases ═══ Each of the CD-ROM test cases can be executed individually as previously described. The corresponding test scripts are described below. The user is free to create additional tests or combine tests into multi-threaded test cases after becoming familiar with DDTT and the CD-ROM grammar files. All of the CD-ROM test cases use the DDTT @IMPORT command to include one or more of the script files: o SYSINFO.TXT o SYSINFO2.TXT o SYSINFO3.TXT The content of the SYSINFO*.TXT files is set by the SETINFO.CMD command file. SETINFO.CMD should be executed one time to establish values for the following DDTT parameter keywords: o DEVICENAME - drive name of the CD-ROM device under test, such as E. o FILENAME - path and name of a large data file, 100K bytes or larger, on the media CD to be used in the tests. Do not include the drive name as part of this string. The only difference between the three SYSINFO*.TXT files is the parameter keywords are set for the different DDTT alias names used in the test scripts. All test scripts close the channels opened to the CD-ROM device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension, .LOG. When current status is queried (for example, track, channel, or drive), this data is written to DDTT's output windows and to the log file. Log files can be examined after the test case has completed. All CD-ROM play audio functions cause 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's are accessed by Logical Block or Redbook format. Logical block format sequentially addresses each block on the disk 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. AUDCH.SCR Sets all four audio channel volumes to a value of 150, queries the audio channel volumes and places the result in the log file. AUDCH2.SCR Thread 1 sets all four audio channel volumes to a value of 175. Thread 2 waits for 20 seconds, then retrieves and logs the current values for each of the audio channel volumes. The retrieved volumes should be 175. DRLOCSC.SCR Queries the CD-ROM's current read head location. The location is written in logical block format to the log file. DRLOCTS.SCR Queries the CD-ROM's current read head location. The location is written in Redbook format to the log file. EJECT.SCR Eject the CD media from the CD-ROM drive. On most drives, the user will have to manually reinsert the CD media before performing additional tests. LOCK.SCR Locks the CD media in the CD-ROM drive. After performing this test, the user should not be able to remove the CD media by pressing the CD-ROM drive's "eject" button. PAUDSC.SCR (Requires an audio CD.) Plays the audio information through the CD-ROM drive output. The media is accessed using logical block format and starts at Sector 40 000 and plays 42 000 sectors. The channel to the CD-ROM drive is closed after two minutes or after the user provides some input to DDTT's input window. Closing the channel does not terminate the play audio. Each sector is 1/75th of a second; therefore, 42 000 sectors will play for 9 minutes, 33 seconds. Play should continue for that period, unless another command is sent to the CD-ROM or the media is manually ejected. PAUDSC2.SCR (Requires an audio CD.) Plays the audio information through the CD-ROM drive output. This test uses two threads that alternate playing audio. Although only a single play audio command can be executed a given time, multiple threads should be able to send requests to the CD-ROM in an interleaved fashion. The stop audio is used to terminate the play audio and coordinate use of the CD-ROM by two threads. The resume audio command is used to continue playing the CD where it last stopped without head re-positioning, thus, Thread 2 should continue from where Thread 1 left the head. PAUDSC3.SCR (Requires an audio CD.) Plays the audio information through the CD-ROM drive output. Using logical block address format, play 42 000 sectors starting at sector 40 000. Repeat this operation three times in a loop. Play is interrupted after 20 seconds with a stop audio command. Play will be interrupted sooner if the tester enters any information into DDTT's input window displayed during the audio play operations. PAUDSC4.SCR (Requires an audio CD.) This test case has two threads (all addressing uses Logical Block format). Thread 1 plays some audio while Thread 2 attempts to retrieve audio disc and track information. The query operations are repeated five times while the audio is playing. The information retrieved is for the three highest-numbered audio tracks on the CD. All information is written to the log file. The audio disc and track query functions should work while the disc is playing the audio information. PAUDTS.SCR (Requires an audio CD.) Plays the audio information through the CD-ROM drive output. Using Redbook address format, this test case starts playing the audio at 22:17:62 (22 minutes, 17 seconds, and 62 frames) from the start of the CD until 32:00:00. If the CD is a multi-volume CD, then the time is from the start of the first CD in the set. Audio play will be allowed to continue for 45 seconds or until the tester enters any data into the DDTT input window, at which time a stop audio command is executed and sound should cease immediately. PAUDTS2.SCR (Requires an audio CD.) Plays the audio information through the CD-ROM drive output. This test case uses two threads and all CD-ROM addressing is by way of Redbook format. Thread 1 plays audio starting at 24:20:00 with a programmed stop at 28:00:00. Thread 1 plays for two minutes before stopping the audio as a result of a 2-minute user response time-out or for less than two minutes if the tester gives some input on DDTT's test window. Thread 2 starts playing a different area of the CD after two minutes. Thread 2 also plays for two minutes unless the tester provides some input to the DDTT input window. The audio should stop instantly upon tester input for both threads. PAUDTS3.SCR (Requires an audio CD.) This test case has two threads (all addressing uses Redbook format). Thread 1 plays some audio while Thread 2 attempts to retrieve audio disc and track information. A query audio disc information is followed by a query track function for each audio track on the CD. The query operation are performed while the audio is playing in Thread 1. All information is written to the log file. The audio disc and track query functions should work while the disc is playing the audio information. PAUDTS4.SCR (Requires an audio CD.) The test case has three threads (all addressing uses Redbook format). Thread 1 plays audio 20 seconds and then Thread 2 plays audio for 20 seconds and finally Thread 3 plays audio for 20 seconds. Threads 2 and 3 wait for the previous threads to complete before starting their own audio plays. The tester can complete any play or wait sooner by entering any data at the DDTT input window. QAUDCH.SCR Queries the CD-ROM drive and returns the current audio channel output volume channel for all four audio channel outputs. QAUDCH2.SCR (Requires an audio CD.) This test case has two threads. Thread 1 uses Logical Block format to play 30 seconds of audio and Thread 2 runs queries the audio channel volume levels and logs this information in the log file. Thread 2 queries the current volume information while Thread 1 is playing audio. QAUDDK.SCR (Requires an audio CD.) Queries the CD-ROM media and return the lowest and highest tracks on the audio CD-ROM disc. This information is set in the DDTT parameter keywords: HIGHTRACK and LOWTRACK. QAUDDK2.SCR (Requires an audio CD.) This test case has two threads. Thread 1 queries the audio disc information and then loops from the lowest track up to the highest track. For each track it queries the individual track information. Thread 2 does the same thing, except that it loops from the highest track down to the lowest track. Both of these threads run concurrently. QAUDSTA.SCR (Requires an audio CD.) Queries the most current audio status information. Audio status information includes the starting and ending location of the last play command that was executed. QAUDSTA2.SCR (Requires an audio CD.) This test case has two threads. Thread 1 plays audio for 40 seconds. Thread 2 queries the audio status information while Thread 1 is playing. Audio status information includes the starting and ending location of the last play command that was executed. QAUDTRK.SCR (Requires an audio CD.) Queries the CD-ROM for the audio track information from tracks 4 and 5. Audio track information includes the type of data stored in the track and the Redbook address of the starting block in the track. QCHAN.SCR (Requires an audio CD.) Queries the CD-ROM drive for the current channel information while the CD-ROM is playing audio information. This test case uses only one DDTT thread. Channel information includes the current track number, elapsed time within the current track, and the elapsed time on the disk. QCHAN2.SCR (Requires an audio CD.) Queries the CD-ROM drive for the current channel information while the CD-ROM is playing audio information. This test case uses two DDTT threads. Thread 1 plays 40 seconds of audio and Thread 2 queries the current channel information. Channel information includes the current track number, elapsed time within the current track, and the elapsed time on the disc. QDRIV.SCR Queries the CD-ROM drive and returns the CD-ROM device driver ID. QSECIN.SCR Queries the CD-ROM drive and returns the size of the number of bytes in each sector on the CD-ROM media. QSTA.SCR Queries the CD-ROM drive and returns the CD-ROM drive status. Device status includes: o door is open or closed o door is locked or unlocked o supports 2 352 byte sector reads o readable and writeable o supports audio and video data o supports interleaved access o supports prefetched reads o supports audio channel manipulations o disc is present in drive o drive is playing audio QUPCC.SCR Queries the CD-ROM drive and returns the current media's universal product code. Warning: At the current printing, this function is seldom supported. If this function is not supported, such an error should be returned by the CD-ROM device driver. QVOLSIZE.SCR Queries the CD-ROM drive and returns the number of logical blocks on the current CD-ROM media. RD2048T1.SCR Reads 25 sectors starting at sector 200 from the disc in 2048 byte mode and returns the data in the DDTT-named buffer, BUFFER. RD2048T2.SCR Reads 400 sectors starting with sector 20 in a loop. The loop is repeated 100 times; the data is compared to the original read each time through the loop. An error message is generated if the buffers do not compare. RD2048T3.SCR Reads 500 sectors starting at sector 50 and compares the data with 500 sectors read starting at sector 990. The second set of data is read in a loop 100 times. The buffers are compared and expected to not match. RD2048T4.SCR Performs a timed read of 20 sectors in a loop of 40 iterations. The test case logs the time when it starts the first loop and the time it completes the final loop. The tester will need to examine the log file subtract the times to find the total duration of the read operations. Rd23SCT1.SCR Reads 27 sectors in 2 352 byte mode starting at the Redbook address of 02:00:00. RD23SCT2.SCR Reads 27 sectors in 2 352 byte mode starting at Sector 100. The same data is read into a second buffer and compared to first buffer. The data is expected to match. The second read is repeated 100 times in a loop. RD23SCT3.SCR Reads 27 sectors in 2 352 byte mode starting at Sector 10. The data in 27 sectors starting at sector 999 is read into a second buffer and compared to first buffer. The data is not expected to match. RD23SCT4.SCR Reads 27 sectors in 2 352 byte mode starting at Sector 1. The data in 27 sectors starting at sector 00:02:00 is read into a second buffer and compared to first buffer. The data is not expected to match. RDFILET1.SCR Opens the CD-ROM resident file defined in the DDTT parameter keyword: FILENAME (from SYSINFO.TXT) and reads 500 bytes starting at byte 600 within the file. The data is read into the DDTT named buffer, ALPHA. ALPHA is dumped to the log file. RDFILET2.SCR Opens the CD-ROM resident file defined in the DDTT parameter keyword: FILENAME (from SYSINFO.TXT) and reads 100000 bytes starting at byte 600 within the file into a DDTT named buffer: ALPHA. This test case then re-reads the same data into another named buffer: BETA. ALPHA and BETA buffers are compared; the BETA buffer re-read and the compare operation is repeated in a loop 100 times. Data in the ALPHA buffer is expected to match the data in the BETA buffer. RDFILET3.SCR Opens the CD-ROM resident file defined in the DDTT parameter keyword: FILENAME (from SYSINFO.TXT) and reads 130000 bytes starting at byte 1 000 within the file into a DDTT named buffer: ALPHA. This test case then reads 130000 bytes starting at byte 200 from the same file into another named buffer, BETA. ALPHA and BETA buffers are compared; the BETA buffer re-read and the compare operation is repeated in a loop 100 times. Data in the ALPHA buffer is not expected to match the data in the BETA buffer. RDFILET4.SCR This test case uses two threads. Both threads open the CD-ROM resident file defined in the DDTT parameter keyword: FILENAME (from SYSINFO.TXT) and then loop 20 times. Thread 1 reads 30 000 bytes starting at byte 1 000 and Thread 2 reads 20 000 bytes starting at byte 200. The operations run concurrently. RDPRSCT1.SCR Reads with prefetch two sectors (2 352 bytes each) of data starting at Sector 1 000. RDPRSCT2.SCR Reads with prefetch 27 sectors (2 352 bytes each) into two different DDTT named buffers. The data is compared and expected to match. The read and compare operations are repeated in a loop 30 times. RDPRSCT3.SCR Reads with prefetch 27 sectors (2 352 bytes each) into two different DDTT-named buffers. Initially, the data reads starting at sector 550; a second read of the same size starts at Sector 15 500. The data is compared and expected to not match. The read and compare operations are repeated in a loop 30 times. RESET.SCR Resets and reinitializes the CD-ROM drive and controller. RESUME.SCR (Requires an audio CD.) Resumes playing the last audio command sent to the CD-ROM drive. The previous play audio must have been interrupted by a stop audio command. If the last play command is finished running, then an error is returned. RESUME2.SCR (Requires an audio CD.) This test case has two threads. Thread 1 starts a 13 minute play audio, but interrupts it after 25 seconds of play. Thread 2 waits for Thread 1 to perform the stop audio and then performs a resume audio from where Thread 1 left off. SAUD.SCR Performs a stop audio operation on any currently active play audio operation. SAUD2.SCR (Requires an audio CD.) This test case has two threads. Thread 1 starts a 4 minute play. Thread 2 waits for 30 seconds and then stops the audio. SEEKSEC.SCR (Requires an audio CD.) Performs a sector seek in Logical Block address mode, plays audio for 25 seconds, performs a stop audio before exiting. SEEKTS.SCR (Requires an audio CD.) Performs a sector seek in Redbook address mode, plays audio for 30 seconds, performs a stop audio before exiting. SEEKTS2.SCR (Requires an audio CD.) This test case has two threads. Thread 1 performs Redbook format seek, starts a 3 minute play audio and then waits for 60 seconds. While Thread 1's play audio is running, Thread two performs a query audio disc information, query drive status, and a query UPC. All operations are expected to complete successfully, however at this printing the query UPC function seldom works correctly. UNLOCK.SCR Unlocks the CD-ROM drive door. ═══ 16.6. Evaluation of Test Case Results ═══ Unless otherwise stated in the test-case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DDTT, then the token "ERROR" will be written to the corresponding log file. The script files test all of the different CD-ROM functions. After each script file has finished executing, it will log all of the test information out to a log file. When all of the script files have finished executing, the command file will search all of the log files for any errors that have occurred. The results from this search are stored in the RESULTS.TXT file. When the command file has finished searching the log files, it will also display the results on the screen. The command file is searching only for the word "ERROR". Look at the following script files to determine if there were any buffer comparison errors. The script file names are: RDFILET2 RDFILET3 RD2048T2 RD2048T3 RD23SCT2 RD23SCT3 RDPRSCT2 RDPRSCT3 If there are any buffer-comparison errors, you first must know what the different script files are doing. Some of these script files are comparing the same sectors or bytes and some of them are comparing different sectors or bytes. If the script file is comparing the same information, it should come back with BUFFER COMPARE SUCCESS. If the script files are comparing different information, they then should come back with BUFFER COMPARE FAILURE. ═══ 16.7. Kodak Multi-session Test ═══ Testing for Kodak Kodak** multi-session photo CD compatibility requires the Kodak "MULTI SESSION BRANDING" PHOTO CD. A multi-session CD contains data that was written to the CD media at different times or recording sessions. If the CD-ROM drive and device driver under test are capable of reading multi-session CD media then the tester should be able to view all 24 pictures on the Kodak photo CD test disc. The files necessary to run this test are not available through IBM, but can be purchased directly from Kodak at this address: KODAK 1700 DEWEY AVE. ROCHESTER, NY 14650-1924 (716) 588-4155 ═══ 17. 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. ═══ 17.1. Overview ═══ 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: o A table listing the virtual disk parameters o A table listing the virtual disk commands o An explanation of how the virtual disk initialization routine works o Information for performing time-critical tasks o 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:\0S2\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: Code Function 0h Init 1h Media Check 2h Build BPB 4h Read (Input) 8h Write (Output) 9h Write With Verify Dh Open Device Eh Close Device Fh Removable Media 10h Generic IOCtl 11h Reset Media 12h Get Logical Drive Map 13h Set Logical Drive Map 18h No Caching (read) 19h No Caching (write) 1Ah No Caching (Write With Verify) 1Dh Get 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: o Initializes various global values and initializes the DevHelp function router address. o 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. o 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. o 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). o 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. o 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: 1. Add the TOOLS directory to the OS/2 IBM Developer Connection Device Driver Kit for OS/2 and set it to the current path. 2. 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 ═══ 18. OS2DASD.DMD - Technical Reference ═══ The OS2DASD Device Manager (OS2DASD.DMD) provides the interface between the OS/2 File Systems (FAT, HPFS) and Adapter Drivers (*.ADDs) that support fixed and removable magnetic disks. This device manager allows the *.ADD drivers to communicate with adapter or disk hardware without interacting with the logical contents of these devices or being affected by the complexity of OS/2 block device driver interfaces. The device manager communicates with *.ADD drivers exclusively by way of Input/Output Request Blocks (IORBs), as described in the preceding chapters of the Storage Device Driver Reference. The primary functions of this device manager are: 1. Implementing the OS/2 Kernel/FileSystem block device driver interfaces; creating IORBs as required for communication to .ADD drivers. 2. Scanning .ADD drivers for removable or fixed magnetic devices. 3. Managing partitioned devices by creating logical drives for partitioned disks and reporting these logical drives to the OS/2 kernel. 4. Providing IOCtl interfaces to the file system utility applications to allow for the preparation of the media. 5. Providing for the attachment from a set of logical drives to a physical removable device is called pseudo drive support. An example is the mapping of drive A: or B: to a single diskette drive. ═══ 18.1. Kernel/FileSystem Interfaces ═══ The OS2DASD device manager supports three major types of kernel interfaces: Request Packets, Extended Disk Interface, and Generic IOCtls. With the exception of Generic IOCtls, these interfaces are used by the OS/2 Kernel and OS/2 File Systems to communicate with device drivers and are not directly available to applications. ═══ 18.1.1. Request Packets ═══ Request Packets are used for small I/O requests or status requests to the device manager. The following table shows the Request Packets that are supported by the OS2DASD Device Manager: ┌──────────┬──────────────────────────────────────────────────┐ │Cmd Code │Packet Name │ ├──────────┼──────────────────────────────────────────────────┤ │01h │Check Media Change │ ├──────────┼──────────────────────────────────────────────────┤ │02h │Build BPB │ ├──────────┼──────────────────────────────────────────────────┤ │04h │Read │ ├──────────┼──────────────────────────────────────────────────┤ │08h │Write │ ├──────────┼──────────────────────────────────────────────────┤ │09h │Write with Verify │ ├──────────┼──────────────────────────────────────────────────┤ │0Fh │Check Removable │ ├──────────┼──────────────────────────────────────────────────┤ │10h │Generic IOCtl │ ├──────────┼──────────────────────────────────────────────────┤ │11h │Reset Media Change │ ├──────────┼──────────────────────────────────────────────────┤ │12h │Get Logical Drive Map │ ├──────────┼──────────────────────────────────────────────────┤ │13h │Set Logical Drive Map │ ├──────────┼──────────────────────────────────────────────────┤ │16h │Get Partitionable Disk Count │ ├──────────┼──────────────────────────────────────────────────┤ │17h │Map Unit Numbers to Physical Drive │ ├──────────┼──────────────────────────────────────────────────┤ │18h │Read (Suppress caching) │ ├──────────┼──────────────────────────────────────────────────┤ │19h │Write (Suppress caching) │ ├──────────┼──────────────────────────────────────────────────┤ │1Ah │Write w/Verify (Suppress caching) │ ├──────────┼──────────────────────────────────────────────────┤ │1Dh │Get Extended Disk Interface Info │ └──────────┴──────────────────────────────────────────────────┘ The formats of these packets can be found in the OS/2 Physical Device Driver Reference. For more information regarding the implementation and interpretation of these packets by OS2DASD, see Request Packet Management. ═══ 18.1.2. Extended Disk Interface ═══ The Extended Disk Interface provides a higher performance path for a limited set of commands. The advantages of this interface are: o Multiple I/O requests may be submitted in a single list. o Each request may transfer data to or from discontinuous areas of memory. o Each request may specify a priority to other I/O requests. o A file system can directly call the device driver to submit I/O requests, rather than going through the OS/2 kernel. o This interface may be used at interrupt time. See Request Lists and Request Control for information about the format of the Extended Disk Interface "Request Lists". ═══ 18.1.3. Generic IOCtls ═══ IOCtl interfaces are generally used by the file system utility applications such as FORMAT and CHKDSK to prepare or access media when a file system is not operating. The interfaces also perform operations that query or change hardware-specific characteristics of a device. Category 08h IOCtls apply to a single drive letter or partition. Most file system utility programs access disks using this IOCtl category. Category 09h IOCtls apply to the entire physical device. In other words, these IOCtls ignore any partitioning scheme that may be present on the drive. Partitioning utility programs such as FDISK and FDISKPM use this IOCtl category to set up a disk partitioning scheme. The OS2DASD Device Manager supports the IOCtls shown in the following table: ┌──────────┬──────────┬────────────────────────────────────────┐ │Category │Function │Purpose │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │22h │Create Alias Drive Letter │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │40h │Lock/Unlock/Eject Media │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │43h │Set Drive Parameters │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │44h │Write Track │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │45h │Format/Verify Track, Multitrack Verify │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │5Dh │Stop/Start Diskette Controller │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │60h │Read Diskette Media Type Switches │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │63h │Get Drive Parameters │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │64h │Read Track │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │65h │Verify Track │ ├──────────┼──────────┼────────────────────────────────────────┤ │08h │66h │Get Drive Status - Locked/Unlocked/Ready│ ├──────────┼──────────┼────────────────────────────────────────┤ │09h │44h │Physical Volume - Write Track │ ├──────────┼──────────┼────────────────────────────────────────┤ │09h │63h │Physical Volume - Get Drive Parameters │ ├──────────┼──────────┼────────────────────────────────────────┤ │09h │64h │Physical Volume - Read Track │ ├──────────┼──────────┼────────────────────────────────────────┤ │09h │65h │Physical Volume - Verify Track │ └──────────┴──────────┴────────────────────────────────────────┘ ═══ 18.2. Block Device Management ═══ When the OS2DASD initializes, it scans .ADD drivers for fixed or removable magnetic devices. For each device found, the driver creates an internal control block that is called a UnitCB. To access the device, the UnitCB provides the linkage to the corresponding ADD driver and ADD UnitHandle. When UnitCBs have been created, the driver creates VolCBs to represent each of the following: o Physical non-removable drive o Removable drive o Logical volumes on a partitioned drive VolCBs are linked together to create a unit number ordering system, based on DOS conventions. In addition, VolCBs are linked to their corresponding UnitCB, which provides the information necessary to access the physical device by way of the ADD drivers. Unit numbers are not equivalent to drive letters. The OS/2 Kernel/FileSystems assigns drive letters. For example, a block device driver cannot demand that a particular set of drive letters be assigned to it. OS2DASD assigns unit numbers as follows: 80h - 98h Physical Drives A VolCB is created for each non-removable drive found. This VolCB represents the drive as a single device and ignores any partitioning scheme. For each drive found, a unit number is assigned from 80h to 98h. 0,1 Reserved for diskette drives Regardless of whether an .ADD driver is found claiming diskette units, Unit Numbers 0,1 will be declared. This prevents the traditional unit numbering from "shifting" on workstations with 0 or 1 diskette drives installed. There is an "implicit" assumption by OS/2 System Initialization, that OS2DASD will be the first block driver loaded. In addition, if a single diskette drive is installed, OS2DASD creates a pseudo drive B unit, which is mapped to the first diskette drive. 2-24 Logical Drives / Removable Devices OS2DASD scans the UnitCBs created previously for non-removable drives. The Sector 0 of each drive is read and the partition record is checked for a file system partition entry. See Boot Record Architecture for more information. If a file system partition is found, it is considered the primary partition on the volume. A VolCB is created and given the next available unit number from this range. When all non-removable drives have been scanned, sector 0 of each non-removable drive is read again and scanned for an extended volume entry. This entry points to a new extended boot sector on the same drive. The extended boot sector is read and scanned for a file system partition entry. If an entry is found, then a VolCB is allocated and assigned the next available unit number from this range. The sector is also searched for another extended volume entry. This process is repeated until the end of the extended volume chain on the drive is reached or no drive letters are left. When the search is completed, the same search is repeated on the next physical drive. After all non-removable drives have been processed and the primary or logical drives are allocated, then VolCBs are allocated for any remaining removable drives in the system. ═══ 18.3. BIOS Parameter Block (BPB) Management ═══ The BPB resides at byte 0 in the first sector of a file system partition. This sector is called the operating system startup record. On non-partitioned media, the BPB resides at sector 0, byte 0. The operating system startup record does not contain a partition table. The partition containing the operating system startup record is pointed to by an entry at the partition table contained in a master or extended boot record. The BPB is is a shared data structure between a block device driver and the FAT file system. In the case of an HPFS, the driver maintains a pseudo BPB. When the VolCB for the logical drive is created during OS2DASD initialization, the BPB for each logical drive is read. Validation checks are made by OS2DASD on the BPB to determine if any BPB had been written to the media. In the absence of a valid BPB, OS2DASD creates one, based on the size of the partition. The remainder of the BPB fields are filled in by a table-driven lookup, based on the size of the volume. This BPB is supplied to the OS/2 Kernel and not written to the media. The driver keeps two copies of the BPB. One representing the BPB determined from the media currently in the drive and one representing the device, assuming its maximum capacity. For non-removable devices, the BPBs are always identical. For removable devices, the BPBs may differ if the media in the drive is formatted to a lower capacity than the drive is capable of handling. An example would be a 720KB diskette in a 1.44MB diskette drive. The media BPB is altered to match the media when OS2DASD receives a Build BPB request packet. The device BPB is only altered by using the Category 08h, Function 43 "Set Device Parameters" IOCtl. This would typically be done by FORMAT which forces a diskette drive to format media at a lower capacity than which it normally operates. One other idiosyncrasy of BPBs is the Hidden Sector field. This is discussed further in the Request Packet Management section. ═══ 18.4. Request Packet Management ═══ The following section groups request packets by function rather than by numerics. ═══ 18.4.1. Removable and Non-Removable Media ═══ 04h Read 08h Write 09h Write with Verify 18h Read (No caching) 19h Write (No caching) 1Ah Write with Verify (No caching) These operations are relatively straightforward, except for the calculation of the location to read. The disk location to access is calculated as follows: Absolute Disk Location = Absolute location of Master/Extended Boot Record + Hidden Sector Field of Logical Drive BPB + RBA Offset in Request Packet The no caching versions of these commands are handled identically to the regular versions except when commands 18h through 1Ah are processed. To suppress adapter level hardware caching, the appropriate bits are set in the EXECUTE_IO IORB. ═══ 18.4.2. Removable Media ═══ 01h Check Media Change 11h Reset Media Change 0Fh Check for Removable Media 12h Get Logical Drive Map 13h Set Logical Drive Map 01h Check Media Change 11h Reset Media Change 01h - Check Media Change, 11h - Reset Media Change: When a Check Media Change packet has been received and the last unit status indicates that a media change has not occurred, then OS2DASD will send a request to the .ADD driver to get an updated status. If the current internal status indicates the media has changed, then "Changed" status will be returned. OS2DASD retains the result of this call and monitors for a media change indication on other I/O operations. When a Media Change is detected, the driver retains this information and blocks subsequent I/O requests to the unit until a Reset Media Change packet is received. 0Fh - Check for Removable Media: When OS2DASD receives the Check for Removable Media request, it locates the appropriate VolCB that corresponds to the requested unit number. The VolCB points to the corresponding UnitCB that contains the UnitInfo obtained from the .ADD driver. The BUSY bit of the request packet is set accordingly. 12h - Get Logical Drive Map, 13h - Set Logical Drive Map: OS/2 allows multiple drive letters to be assigned to the same removable device. This assignment occurs automatically for the B drive on a single diskette system and by way of the EXTDSKDD.SYS driver to create additional drive letter aliases for removable drives. Only one drive letter at a time may be assigned to a removable drive from a set of drive letters that might potentially be mapped to the drive. The binding of a specific unit number to a removable device is accomplished through the use of Set Logical Drive Map. When OS2DASD receives the Set Logical Drive Map request, it looks up the physical removable device that should be assigned to this drive letter. It then updates its tables to indicate that the requested unit number owns the removable device. When OS2DASD receives the Get Logical Drive Map request, it determines the physical drive associated with the unit number provided. OS2DASD then searches the VolCBs to determine which VolCB currently owns the removable device. This owning unit number is returned to the kernel. The unit numbers returned on both of these packets must be 1-based rather than zero-based. A zero unit number returned indicates that there are no alias drive letters that can be assigned to the removable device. ═══ 18.4.3. Non-Removable (Partitionable) Media ═══ 16h Get Partitionable Disk Count 17h Map Unit Numbers to Physical Drive 16h - Get Partitionable Disk Count: The number of non-removable drives is returned. 17h - Map Unit Numbers to Physical Drive: The request packet unit field indicates a non-removable drive number that is zero-based. OS2DASD adds Function 80h and searches for VolCBs associated with that particular physical unit. A bit map of unit numbers associated with the physical drive is returned. The bit numbering scheme for the bit mask corresponds to 2**(unit number) in a ULONG field. ═══ 19. Boot Record Architecture ═══ This appendix describes the details of the data that appear on a physical disk. It also describes the structures that are placed on the disk by various utilities. ═══ 19.1. Master Boot Record ═══ The master boot record is always located on sector 1 of the first track (track 0) on the disk. The following table shows the layout of the various components inside the Master Boot Record. The various components are described below. ┌──────────┬──────────────────────────────┬────────────────────┐ │Offset │Description │Size │ ├──────────┼──────────────────────────────┼────────────────────┤ │+0 │Master Boot Record Program │446 bytes │ ├──────────┼──────────────────────────────┼────────────────────┤ │+446 │Partition Table │64 bytes │ ├──────────┼──────────────────────────────┼────────────────────┤ │+510 │Signature (55AAH) │2 bytes │ └──────────┴──────────────────────────────┴────────────────────┘ Master Boot Record Program This code is given control from BIOS during boot. Its function is to load the operating system's boot program from the partition that was marked as being startable and turn control over to the (assumed) code that was loaded. The Master Boot Record Program may be placed on the disk by individual operating systems. If the signature in the Master Boot Record is valid, then the Master Boot Record Program must not be modified. Operating systems must not place requirements on nor make assumptions about the Master Boot Record Program. Partition Table This is a vector of 4 structures that allows the disk to be divided up into four distinct areas or partitions. The following table shows how they are arranged in this vector. ┌──────────────────┬──────────────────┬──────────────────┐ │Offset │Description │Size │ ├──────────────────┼──────────────────┼──────────────────┤ │0 │Partition 1 │16 bytes │ ├──────────────────┼──────────────────┼──────────────────┤ │16 │Partition 2 │16 bytes │ ├──────────────────┼──────────────────┼──────────────────┤ │32 │Partition 3 │16 bytes │ ├──────────────────┼──────────────────┼──────────────────┤ │48 │Partition 4 │16 bytes │ └──────────────────┴──────────────────┴──────────────────┘ It is up to an individual operating system if one of those parts is to be further sub-divided. For example, DOS Version 3.30 implemented a scheme where an "extended partition" could be used to define logical disks to allow the use of larger hardfiles. The following table shows the format of the individual entries in the partition table. A description of the individual fields follows. ┌──────┬─────────────┬─────────┬─────────┬─────────┬─────────┐ │Offset│ Description │ 0 │ 1 │ 2 │ 3 │ ├──────┼─────────────┼─────────┼─────────┼─────────┼─────────┤ │ +0 │Partion Start│ Boot │ Head │ Sector │Cylinder │ │ │ │Indicator│ │ │ │ ├──────┼─────────────┼─────────┼─────────┼─────────┼─────────┤ │ +4 │Partion End │ System │ Head │ Sector │Cylinder │ │ │ │Indicator│ │ │ │ ├──────┼─────────────┼─────────┴─────────┼─────────┴─────────┤ │ │ Offset from │ │ │ │ +8 │start of disk│ Low Word │ High Word │ │ │ (sectors) │ │ │ ├──────┼─────────────┼───────────────────┼───────────────────┤ │ │ Partion │ │ │ │ +12 │ Length │ Low Word │ High Word │ │ │ (sectors) │ │ │ └──────┴─────────────┴───────────────────┴───────────────────┘ Partition Start This 4 byte field identifies the beginning of a partition. It also contains an indicator that flags the partition as being active or bootable. This field is composed of several bytes defined as follows. Boot Indicator This byte indicates if the partition is active. If the byte contains 00H, then the partition is not active and will not be considered as bootable by the Master Boot Record Boot Program. If the byte contains 80H, then the partition is considered active. The Master Boot Record Boot Program will then attempt to load the first sector described by this partition table entry and transfer control to it. The Master Boot Record Boot Program should only attempt to boot the first partition it finds that is marked active. Head This byte contains the number of the first head of the partition. All partitions are allocated in cylinder multiples and begin on sector 1, head 0. EXCEPTION: The partition that is allocated at the beginning of the disk should start at cylinder 0, head 1, sector 1, to leave room for the disk's master boot record and other information used to define the fixed disk type on that system. An operating system should not use any data space on cylinder 0 head 0 of a fixed disk. Sector This byte contains the sector number of the first sector of the partition. This value should always be 1 (sector numbers are 1 based) for the Partition Begin field because partitions are defined to start on cylinder boundaries. Note that the sector number byte also contains the high order 2 bits of the cylinder number in the high order 2 bits of this byte. Therefore, this byte can have values other than one, but the sector bits of this byte always contains the value 1. Cylinder This byte contains the low order 8 bits of the 10 bit cylinder number that indicates the starting cylinder of the partition. Partition End This 4 byte field identifies the end of the partition. It also contains an indicator as to which operating system owns the partition. This field is composed of several bytes that are defined as follows. System Indicator This byte indicates what operating system owns the particular partition. The values and what they represent are listed in Fixed Disk Partition ID Assignments. A value of 0 indicates an unused entry. Head This byte contains the last head number in the last cylinder occupied by this partition. Sector This byte contains the sector number of the last sector on the last cylinder occupied by this partition. It also contains the high order two bits of the cylinder number in the high two bits of this byte. Cylinder This byte contains the low order 8 bits of the 10-bit cylinder number that indicates the ending cylinder of this partition. Offset from Start of Disk This 4-byte field contains the number of sectors preceding each partition on the disk. The value is obtained by counting the sectors beginning with cylinder 0, sector 1, head 0 of the disk, and incrementing the sector, head, and then cylinder values up to the beginning of the partition. Thus, if the disk has 17 sectors per track and 4 heads, and the second partition begins at cylinder 1, sector 1, head 0, the partition's starting relative sector is 68 (decimal)-there were 17 sectors on each of 4 heads on 1 track allocated ahead of it. The field is stored with the least significant word first. Partition Length This 4 byte field contains the number of sectors allocated to the partition. This field is stored least significant word first. Signature The last 2 bytes of the boot record (55AAH) are used as a signature to identify a valid boot record containing code that is executable on Intel X86 processors. Both this record and the partition boot records are required to contain the signature at offset 01FEH (510). ═══ 19.2. Fixed Disk Technical Information ═══ A fixed disk boot record must be written on the first sector of all fixed disks or logical drives within an extended partition and must contain: o Code to load and give control to the boot record for one of four possible operating systems. o A partition table at the specified offset into the boot record. Each table entry is 16 bytes long, and contains the starting and ending cylinder, sector, and head for each of four possible partitions, as well as the number of sectors preceding the partition and the number of sectors occupied by the partition. The "boot indicator" byte is used by the boot record to determine if one of the partitions contains a loadable operating system. FDISK (or equivalent) initialization utilities mark a user-selected partition as "startable" by placing a value of 80h in the corresponding partition's boot indicator (setting all other partition's indicators to 00h at the same time). The presence of the 80h tells the Master Boot Record Program to load the sector whose location is contained in the following 3 bytes. That sector is the actual boot record for the selected operating system, and it is responsible for the remainder of the system's loading process (as it is from diskette). All boot records are loaded at absolute address 0:7C00. o A Signature to indicate a valid Master Boot Record. ═══ 19.2.1. System Initialization ═══ The System initialization (or system boot) sequence is as follows: 1. System initialization first attempts to load an operating system from the first diskette drive. If the drive is not ready or a read error occurs, it then attempts to read the fixed disk master boot record from the first sector of the first fixed disk on the system. If unsuccessful, or if no fixed disk is present, it invokes a device, ROM BASIC or prompts for a startable diskette. 2. If successful, the master boot record is given control. It examines the partition table imbedded within it. If one of the entries indicates a "startable" (active) partition, its boot record is read (from the partition's first sector) and give control. 3. If none of the partitions is startable, a RIPL device or ROM BASIC is invoked or a prompt for a bootable diskette is displayed. 4. If any of the boot indicators are invalid (values other than 00h or 80h) the message Invalid partition table is displayed and the system stops. You may then insert a system diskette in drive A and use system reset to restart from diskette. 5. If the partition's boot record cannot be successfully read within five retries due to read errors, the message Error loading operating system appears and the system stops. 6. If the partition's boot record does not contain a valid "signature," the message Missing operating system appears, and the system stops. When a partition's boot record is given control, it has passed its partition table entry address in the DS:SI registers. System programmers designing a utility to initialize/manage a fixed disk must provide the following functions at a minimum: 1. Write the master disk boot record/partition table to the disk's first sector to initialize it if it is not already present. 2. Perform partitioning of the disk-that is, create or update partition table information (all fields for the partition) when the user wishes to create, modify, or remove a partition. This may be limited to creating a partition for only one type of operating system, but must allow repartitioning the entire disk, or adding a partition without interfering with existing partitions (user's choice). Note: When changing the size or location of any partition, you must ensure that all existing data on that partition has been backed up (the partitioning process will "lose track" of the previous partition boundaries). 3. Provide a means for marking a user-specified partition as startable, and resetting the startable indicator bytes for other partitions at the same time. 4. Such utilities should not change or move any partition information that belongs to another operating system. ═══ 19.3. Fixed Disk Partition ID Assignments ═══ ┌──────────┬──────────────────────────────────────────────────┐ │Partition │Description │ ├──────────┼──────────────────────────────────────────────────┤ │00 │Unused Partition │ ├──────────┼──────────────────────────────────────────────────┤ │01 │DOS, 12-bit FAT │ ├──────────┼──────────────────────────────────────────────────┤ ├──────────┼──────────────────────────────────────────────────┤ │03 │XENIX User, includes SCO/XENIX │ ├──────────┼──────────────────────────────────────────────────┤ │04 │DOS, 16-bit FAT │ ├──────────┼──────────────────────────────────────────────────┤ │05 │DOS and OS/2, >32MB support; defines an Extended │ │ │partition which may include other partition types.│ ├──────────┼──────────────────────────────────────────────────┤ │06 │DOS, >32MB support, up to 64K Allocation unit │ ├──────────┼──────────────────────────────────────────────────┤ │07 │OS/2, >32MB partition support (IFS) │ ├──────────┼──────────────────────────────────────────────────┤ ├──────────┼──────────────────────────────────────────────────┤ │08 │OS/2 (thru Version 1.3 only) │ ├──────────┼──────────────────────────────────────────────────┤ │08 │DELL partition spanning multiple drives (array) │ ├──────────┼──────────────────────────────────────────────────┤ │08 │Commodore DOS Partition │ ├──────────┼──────────────────────────────────────────────────┤ │09 │AIX │ ├──────────┼──────────────────────────────────────────────────┤ │0A │OS/2 Boot Manager Partition │ ├──────────┼──────────────────────────────────────────────────┤ │0B - 0D │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │0E - 0F │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │10 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │11 │OS/2 Boot Manager: DOS - Inactive type 1 │ ├──────────┼──────────────────────────────────────────────────┤ │12 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │13 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │14 │OS/2 Boot Manager: DOS - Inactive type 4 │ ├──────────┼──────────────────────────────────────────────────┤ │15 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │16 │OS/2 Boot Manager: DOS - Inactive type 6 │ ├──────────┼──────────────────────────────────────────────────┤ │17 │OS/2 Boot Manager: DOS - Inactive type 7 │ ├──────────┼──────────────────────────────────────────────────┤ │18 - 20 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │21 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │22 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │23 - 24 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │25 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │26 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │27 - 30 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │31 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │32 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │33 - 34 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │35 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │36 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │37 - 3F │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ ├──────────┼──────────────────────────────────────────────────┤ │41 │Personal RISC Boot Partition │ ├──────────┼──────────────────────────────────────────────────┤ │42 - 4F │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │50 │OnTrack Disk Manager │ ├──────────┼──────────────────────────────────────────────────┤ │51 │OnTrack Disk Manager │ ├──────────┼──────────────────────────────────────────────────┤ │52 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │53 - 55 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │56 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │57 - 60 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │61 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │62 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ ├──────────┼──────────────────────────────────────────────────┤ │64 │Speedstore │ ├──────────┼──────────────────────────────────────────────────┤ │65 │Novell 286 Netware │ ├──────────┼──────────────────────────────────────────────────┤ │66 │Novell 386 Netware │ ├──────────┼──────────────────────────────────────────────────┤ │67 │Novell (future use) │ ├──────────┼──────────────────────────────────────────────────┤ │68 │Novell (future use) │ ├──────────┼──────────────────────────────────────────────────┤ │69 │Novell (future use) │ ├──────────┼──────────────────────────────────────────────────┤ │6A - 70 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │71 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │72 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │73 - 74 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │75 │PC/IX │ ├──────────┼──────────────────────────────────────────────────┤ │76 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │77 - 79 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │80 - 81 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │82 │Prime │ ├──────────┼──────────────────────────────────────────────────┤ ├──────────┼──────────────────────────────────────────────────┤ │85 - 85 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │86 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │87 │HPFS FT mirrored partition │ ├──────────┼──────────────────────────────────────────────────┤ │88 - 92 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │93 - 94 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │95 - A0 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │A1 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │A2 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │A3 - A4 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │A5 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │A6 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │A7 - B0 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │B1 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │B2 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │B3 - B4 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │B5 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │B6 - B8 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │B9 - C0 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │C1 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │C2 - C3 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │C4 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │C5 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │C6 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │C7 │HPFS FT disabled mirrored partition │ ├──────────┼──────────────────────────────────────────────────┤ │C8 - D7 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │D8 │CP/M 86 │ ├──────────┼──────────────────────────────────────────────────┤ │D9 - DA │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │DB │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │DC - E0 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │E1 │Speedstore │ ├──────────┼──────────────────────────────────────────────────┤ │E2 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │E3 │Storage Dimensions (Maxtor Retail Subsidiary) │ ├──────────┼──────────────────────────────────────────────────┤ │E4 │Speedstore │ ├──────────┼──────────────────────────────────────────────────┤ │E5 - E6 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │E7 - F0 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │F1 │Storage Dimensions (Maxtor Retail subsidiary) │ ├──────────┼──────────────────────────────────────────────────┤ │F2 - F3 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │F4 │Storage Dimensions (Maxtor Retail subsidiary) │ ├──────────┼──────────────────────────────────────────────────┤ │F5 │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │F6 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │F7 - FD │Available for assignment │ ├──────────┼──────────────────────────────────────────────────┤ │FE │IBM PS/2 IML │ ├──────────┼──────────────────────────────────────────────────┤ │FF │Bad Block Tables - Must be on cylinder 0 │ └──────────┴──────────────────────────────────────────────────┘ ═══ 19.4. Extended DOS Partition ═══ Fixed disks can be divided into primary partitions, and an extended partition that contains multiple logical block devices. The extended partition is indicated by a System ID byte of 05h in the partition table of the Master Boot Record. This partition cannot be started, and programs that can set startable partitions (such as OS/2 FDISK) do not allow the partition to be marked as able to start. The extended DOS partition can be created only if a primary DOS partition already exists on a startable drive. A primary partition is a partition with a System ID byte of 01h, 04h, 06h, or 07h. If the drive cannot be started, then an extended DOS partition can be created without having a primary DOS partition. Note: 1. FDISK refers to extended volumes as logical drives. 2. This extended partition support can be used on any fixed disk supported by the OS/2 operating system. The extended DOS partition starts and ends on a cylinder boundary, and contains a collection of extended volumes that are linked together by a pointer in the extended volumes' extended boot record. An extended volume consists of an extended boot record and one logical block device. In OS/2 Version 1.0, an extended volume could not be larger than 32MB, due to the limitations of the FAT file system. However, in OS/2 2.0 and 2.1, this restriction has been removed. An extended volume created within the extended DOS partition can be any size, from one cylinder long through the maximum available contiguous space in the extended DOS partition. All extended volumes must start and end on a cylinder boundary. The extended boot record corresponds to the Master Boot Record at the beginning of an actual physical disk. The logical block device corresponds to the DOS partition that is pointed to by the Master Boot Record. The logical block device begins with a normal DOS boot sector if it is a DOS logical block device (System ID=1, 4, or 6). Installable File System (IFS) logical block devices (System ID=7) need not start with a normal DOS boot sector. This logical block device must start on a cylinder and head boundary and must follow the extended boot record on the physical disk. The logical block device and the extended volume both end on the same cylinder boundary. Each extended volume contains an extended boot record located in the first sector of the disk location assigned to it. This extended boot record contains the 55AAh signature ID byte. This allows programs that look at the Extended (Master) Boot Record to be compatible. This extended boot record also contains a partition table, which can contain only two types of entries. The boot code is not critical, as the devices are not considered startable. The boot code can simply report a message indicating an unstartable partition if it is executed. The partition table portion of the extended boot record is the same as the partition table structure in the Master Boot Record. This structure has four partition entries of 16 bytes each. The System ID byte must be filled in for all four entries with one of the following values: 00h No space allocated in this entry. 01h DOS partition up to 16MB. 04h DOS partition with 32MB > SIZE > 16MB. 05h Maps out area assigned to the next extended volume. Serves as a pointer to the next extended boot record. 06h DOS partition size > 32MB. 07h Installable file system. If the System ID byte is 0, then the values in that partition table entry are set to 0. If the operating system detects any values other than 01h, 04h, 06h, or 07h, it ignores that entry and does not attempt to install the logical block device. This allows future expansion of devices in this area without problems of compatibility with earlier systems. The partition start and end fields Cylinder, Head, and Sector (C,H,S) are filled in for any of the four partition entries in an extended boot record that have one of the System ID bytes. This allows a program such as FDISK to determine the allocated space in the extended DOS partition, and allows the physical device drivers to determine the physical DASD area that belongs to it. The partition start and end fields (C,H,S) for the partition entry that points to the logical block device (System ID 01h, 04h, 06h, or 07h) map out the physical boundaries of the logical block device. They are offset relative to the beginning of the extended boot record that the entry resides in. The partition start and end fields for the partition entry that points to the next extended volume (System ID 05h) map out the physical boundaries of the next extended volume. They are relative to the beginning of the entire physical disk. The relative sector and number of sector fields are set up differently depending on what System ID byte is used. If 01h, 04h, 06h, or 07h is in the System ID field for that extended partition entry (pointer to the logical block device), the relative sector field is set up as an offset from (and including) the start of the extended boot record for the associated extended volume. The number of sectors field is filled in with the size of the created logical block device area (that is, the number of sectors mapped out by the start and stop cylinder/track/sector fields). The size of the extended volume can be calculated by adding the relative sector field and the sector size field of the associated extended boot record. If the System ID byte is 05h, then the relative sector field is the offset (of the next extended volume) in sectors from the start of the entire extended DOS partition The number of sectors field is not used in this field, and is filled with 00hs. This architecture allows only one logical block device to be defined for each extended boot record. Therefore, a maximum of two partition entries at a time is used in each extended boot record - an entry with System ID byte of 01h, 04h, 06h, or 07h, and an entry with ID of 05h (which is the pointer to the next extended volume). Although only two entries can be used, a program installing these devices does not assume that the first two entries will be the non-zero entries. ═══ 19.5. Installing Block Devices in the Extended DOS Partition ═══ To install block devices, physical device drivers first install the primary DOS partitions on all physical drives, if any exist. This ensures that an existing drive letter, D:, on the 81h drive remains the same. After these devices are installed on the 80h drive, the drivers look for the existence of the extended DOS partition. If one exists, then the physical device drivers look at the first sector of the extended DOS partition for the first extended boot record. If there is a valid System ID (01h, 04h, 06h, or 07h) in any of the four partition entries, the device is installed and assigned the next available drive letter. This occurs before any CONFIG.SYS device drivers are loaded, so the FDISK will correctly display the drive letter when space is allocated for the drive. The first extended boot record (in the extended DOS partition) is a special case, because it is possible there will not be a device to be installed defined in the partition table. The first device might have been created and then deleted at some time. However, the first extended boot record is needed to point to the next one, if one exists. Any other extended boot record will always have a device to be installed. Once a device has been installed (or the special cases above occur), the physical device driver searches the other partition entries for a System ID byte of 05h, indicating that another device (extended volume) exists. If a 05h is not found, there are no more logical block devices (extended volumes) in the extended DOS partition. If a 05h System ID is found, the start location in that partition entry is read in order to find the location of the next extended boot record. When located, it is read in, and then the process is repeated in order to install additional devices. Once all the valid devices for a physical drive have been installed, the next physical drive is examined and the entire process is repeated. A device driver does not assume any order dependency when searching for a particular System ID byte in an extended boot record. All four possible entries in an extended boot record partition table are searched, before a driver decides that a particular System ID byte does not exist. The extended DOS partition can only be created if a primary DOS or IFS partition already exists on a bootable drive. A primary DOS partition has a System ID of 01h, 04h, or 06h. A primary IFS partition has a System ID of 07h. If the drive is not bootable, an extended DOS partition can be created without having a primary DOS partition. The extended DOS partition starts and ends on a cylinder boundary. ═══ 19.6. Creating Block Devices in the Extended DOS Partition ═══ To create the structure for an extended volume in the extended DOS partition, FDISK determines if there is available space in the extended DOS partition and if less than 24 total devices are allocated in the system. The maximum number of block devices allowed is 26, and two are used by diskettes, A: and B:. The program then creates an extended boot record at the space located, with a partition entry filled in (with the size and location information) for that logical block device. If this is not the first extended boot record, the program backs up to the last extended boot record in the chain (as linked by the 05h entries), and creates a partition entry in that extended boot record that has the size and location data for the newly created record. This action creates the pointer required to locate the newly created boot record. If this is the first extended boot record in the extended DOS partition only the size, type, and location of the logical block device needs to be put into a partition entry. The start of the extended DOS partition in the Master Boot Record serves as a pointer to this extended volume. ═══ 19.7. Deleting Block Devices in the Extended DOS Partition ═══ To delete a block device, the program sets the 16-byte partition entry that contained the System ID byte, to 0. If in the same extended boot record there exists a partition entry with System ID of 05h, indicating that another extended volume exists, this information is copied to the 05h partition entry of the previous extended boot record. (See the following figure for further information.) Note: There is one exception to this rule. If the deleted logical block device is at the beginning of the extended DOS partition, only the partition entry indicating the device type is set to 0. The 05h pointer information is to be left in place. ┌─────────────────────────────────────┐ │ Master Boot Record......Note 1.... │ │....................┌──┬──┬──┬──┬────┤ │............Note 2 │4 │2 │5 │0 │55AA│ Note 3 ├────────────────────┴──┴──┴──┴──┴────┤ │ Primary DOS Partition Note 4 │ │ DOS C: drive 32MB  Size │ ├─────────────────────────────────────┤ │ Other Operating System Partition │ │ (XENIX) Note 5 │ E E ┌── ├─────────────────────────────────────┤ ──┐ x x │ │ Extended Boot Record..Note 6........│ │ t t │ │....................┌──┬──┬──┬──┬────┤ │ │ │............Note 7 │4 │5 │0 │0 │55AA│ │ V D │ ├────────────────────┴──┴──┴──┴──┴────┤ │ o O │ │ LOGICAL Block Device D: Note 8 │ │ l S │ │ 32MB  Size  16MB or IFS │ │ u │ ├─────────────────────────────────────┤ ──┘ m P │ │ Extended Boot Record..Note 9........│ e a │ │....................┌──┬──┬──┬──┬────┤ r │ │...........Note 10 │1 │5 │0 │0 │55AA│ t │ ├────────────────────┴──┴──┴──┴──┴────┤ i │ │ LOGICAL Block Device E: │ t │ │ Size  16MB │ i │ ├─────────────────────────────────────┤ o │ │ Extended Boot Record................│ n │ │....................┌──┬──┬──┬──┬────┤ │ │...........Note 11 │6 │5 │0 │0 │55AA│ │ ├────────────────────┴──┴──┴──┴──┴────┤ │ │ Area reserved for future CP/DOS use │ │ │ Note 12 │ │ ├─────────────────────────────────────┤ │ │ Extended Boot Record................│ │ │....................┌──┬──┬──┬──┬────┤ │ │...........Note 13 │4 │0 │0 │0 │55AA│ │ ├────────────────────┴──┴──┴──┴──┴────┤ │ │ LOGICAL Block Device G: │ │ │ 32MB  Size  16MB │ │ ├─────────────────────────────────────┤ │ │ Free Space in Extended Partition │ └── ├─────────────────────────────────────┤ │ Free Space not allocated to any │ │ partition │ └─────────────────────────────────────┘ Note 1 Master Boot Record code, starting at Track 000, Head 00, Sector 01 of disk 80h or 81h. Note 2 Partition table for Master Boot Record. See BPB and Get Device Parameters for Extended Volumes for the layout. The 4 is the System ID byte in the partition table that indicates a DOS partition greater than 16MB and less than or equal to 32MB. The 2 is a XENIX XENIX** partition, and the 05h maps the extended DOS partition. Note 3 55AAh is the signature to validate the Master Boot Record. Note 4 Primary DOS area, which must reside entirely in first 32MB of the disk. C: is block device 80h. D: is block device 81h, if it exists. This partition has a maximum size of 32MB. Note 5 Other operating system on disk. Note 6 Extended boot record for extended volume that corresponds to logical block device D:. (This assumes only the 80h block device exists.) If the 81h block device exists, this would be block device E:. Note 7 Logical block device D: partition table entry. This has a maximum size of 32MB, which is indicated by the System ID of 4. This must set the logical DOS block device as starting at the next track boundary. The 05h System ID byte in the second partition entry maps out the space allocated to the next extended volume. The starting cylinder/sector/head in the partition entry with an ID of 05h is the location of the next extended boot record of the next extended volume. Note 8 Logical block device D:. Logical DOS devices and the primary DOS partition always begin with a DOS boot record. Note 9 Extended boot record for logical block device E:. Note 10 Partition table entry for logical block device E:. This logical DOS block device is less than or equal to 16MB, as indicated by the System ID of 01h. The entry with System ID of 05h maps out the space allocated to the next extended volume. Note 11 The System ID byte of 06h indicates a logical block device greater than 32MB. This block device is indicated by a block device letter of F. Note also that a pointer to the next extended volume exists. Note 12 The greater than 32MB FAT partition. Note 13 Partition table entry for final DOS logical block device. Note that the absence of the 05h ID byte means that there are no other extended volumes allocated in the extended DOS partition. This would have a block device letter of G:, if the previous logical block device was recognized. Otherwise, it would be F:. Offs Purpose Head Sector Cylinder ┌──────────┬─────┬─────┬──────────┐ 1BE Partition 1 begin │ boot ind │ H │ S │ CYL │ ├──────────┼─────┼─────┼──────────┤ 1C2 Partition 1 end │ syst ind │ H │ S │ CYL │ ├──────────┴─────┼─────┴──────────┤ 1C6 Partition 1 rel sect │ Low word │ High word │ ├────────────────┼────────────────┤ 1CA Partition 1 # sects │ Low word │ High word │ ├──────────┬─────┼─────┬──────────┤ 1CE Partition 2 begin │ boot ind │ H │ S │ CYL │ ├──────────┼─────┼─────┼──────────┤ 1D2 Partition 2 end │ syst ind │ H │ S │ CYL │ ├──────────┴─────┼─────┴──────────┤ 1D6 Partition 2 rel sect │ Low word │ High word │ ├────────────────┼────────────────┤ 1DA Partition 2 # sects │ Low word │ High word │ ├──────────┬─────┼─────┬──────────┤ 1DE Partition 3 begin │ boot ind │ H │ S │ CYL │ ├──────────┼─────┼─────┼──────────┤ 1E2 Partition 3 end │ syst ind │ H │ S │ CYL │ ├──────────┴─────┼─────┴──────────┤ 1E6 Partition 3 rel sect │ Low word │ High word │ ├────────────────┼────────────────┤ 1EA Partition 3 # sects │ Low word │ High word │ ├──────────┬─────┼─────┬──────────┤ 1EE Partition 4 begin │ boot ind │ H │ S │ CYL │ ├──────────┼─────┼─────┼──────────┤ 1F2 Partition 4 end │ syst ind │ H │ S │ CYL │ ├──────────┴─────┼─────┴──────────┤ 1F6 Partition 4 rel sect │ Low word │ High word │ ├────────────────┼────────────────┤ 1FA Partition 4 # sects │ Low word │ High word │ ├────────────────┼────────────────┘ 1FE Signature │ │ └────────────────┘ ═══ 19.8. BPB and Get Device Parameters for Extended Volumes ═══ For purposes of the BIOS Parameter Block (BPB) and Get Device Parameters (generic IOCtl), an extended volume appears to the system as a fixed disk. The extended boot record corresponds to the Master Boot Record of a real fixed disk and the logical block device corresponds to the primary DOS partition. This means the BPB of the logical DOS block device of the extended volume describes the environment in the extended volume. This consists of the extended boot record and the logical block device. The meaning of the fields is consistent with the meaning of the fields for the primary DOS partition; they relate to the entire physical disk, the primary DOS partition, and the Master Boot Record. For example, the number of hidden sectors is the distance from the beginning of the extended boot record (of the extended volume in question) to the start of the logical DOS block device (the DOS Boot Record). The number of sectors field describes only the logical block device, just as it normally only describes the primary DOS partition. ═══ 19.8.1. Category 08h Generic IOCtl Commands ═══ The philosophy described above also applies to the disk generic IOCtl commands. For any logical block device of an associated extended volume, physical cylinder, head, and sector I/O is mapped to within the extended volume - Cylinder 0, Head 0, Sector 1 is mapped to the extended boot record. An error condition is generated for any attempt to do C,H,S I/O beyond the size of the extended volume in question. ═══ 19.8.2. Category 09h Generic IOCtl Commands ═══ Category 09h generic IOCtl commands are used to access the entire physical fixed disk without consideration of logical volumes. Physical cylinder, head, and sector begin at the start of the physical drive, instead of at the beginning of an extended volume. ═══ 19.8.3. Type 6 Partition ═══ A 12-bit or 16-bit type FAT can be used to map a Type 6 partition because the type of FAT is based strictly on the number of allocation units (clusters), and is the same algorithm used to define the type of FAT in the OS/2 Version 1.0 operating system. FAT cluster sizes are based on powers of 2. Assuming usage of the OS/2 FORMAT utility, the minimum cluster size for a hard file is 2KB. Cluster size and the type of FAT (12-bit verses 16-bit) are determined by the media partition size. The OS/2 FORMAT algorithm is: ────────────────────────────────────────────────────────────────────────── If partition size =<16MB then; use 12-bit FAT; /* max 4084 entries */ max cluster size = 4KB; end; else; /* partition size >16MB */ use 16-bit FAT; /* max 64KB entries */ min cluster size = 2KB; end; ────────────────────────────────────────────────────────────────────────── The actual determination of the partition type is made based on the number of clusters on that partition. OS/2 FORMAT makes sure that this is true for the <16MB and >16MB partitions. ────────────────────────────────────────────────────────────────────────── If number of clusters <= 4084 use 12-bit FAT; /* max 4084 entries */ else use 16-bit FAT; /* max 64KB entries */ ────────────────────────────────────────────────────────────────────────── A partition size of 128MB requires a 2KB cluster size, based on a maximum of 64KB allocation units (clusters). A partition size in the range of 129MB and 256MB requires a 4KB cluster size, based on 64KB allocation units. A partition size in the range of 257MB and 512MB requires an 8KB cluster size, based on 64KB allocation units. The configuration table used by OS/2 FORMAT is show in the following table: ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Total # of │Size of │Sector Cluster │# of Root DIR │ │Sectors │Partition │ │Entries │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │32K │16MB │8 │512 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │64K │32MB │4 │512 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │256K │128MB │4 │512 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │512K │256MB │8 │512 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1M │512MB │16 │512 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │2M │1GB │32 │512 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │4M │2GB │64 │512 │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │8M │4GB │128 │512 │ └───────────────┴───────────────┴───────────────┴───────────────┘ Note: For Type 6 partitions, it is safe to use a non-default configuration, but this might be unsafe for other partition types. The partition can reside anywhere on the media, as the primary DOS partition, or as an extended volume within the extended DOS partition. The BPB parameter number of sectors per FAT field width has been extended from a byte to a WORD, in order to define a full 128KB FAT structure. This change affects all DOS partition types. ═══ 19.8.3.1. Layout of Block Devices with a Type 6 Partition Using XENIX ═══ ┌─────────────────────────────────────┐ │ Master Startup Record...Note 1.... │ │....................┌──┬──┬──┬──┬────┤ │...........Note 2  │2 │6 │0 │0 │55AA│ Note 3 ├────────────────────┴──┴──┴──┴──┴────┤ │ Other Operating System Partition │ │ (XENIX) │ │ Size  32MB Note 4 │ ├─────────────────────────────────────┤ │ Primary DOS Partition Note 5 │ │ DOS C: drive 32MB  Size │ ├─────────────────────────────────────┤ │ Free Space │ │ (not allocated to any partition) │ └─────────────────────────────────────┘ Note 1 Master Startup (Boot) Record code, starting at Track 000, Head 00, Sector 01 of disk 80h or 81h. Note 2 Partition table for Master Startup (Boot) Record. The 2 is the System ID byte in the partition table that indicates a XENIX partition, and the 06h map indicates a primary DOS Type 6 partition. Note 3 55AAH is the signature to validate the Master Startup (Boot) Record. Note 4 Other operating system (XENIX) on disk. Note 5 Primary DOS partition. C: is block device 80h. The partition type in this example is a 6, because it ends beyond the first 32MB of the disk. Within the scope of this definition, though the size of a primary DOS partition can be less than 32MB (because it ends beyond the first 32MB of the disk), it is defined as a Type 6. ═══ 19.8.3.2. Layout of Block Devices with a Type 6 Partition ═══ ┌─────────────────────────────────────┐ │ Master Startup Record...Note 1.... │ │....................┌──┬──┬──┬──┬────┤ │...........Note 2  │6 │0 │0 │0 │55AA│ Note 3 ├────────────────────┴──┴──┴──┴──┴────┤ │ Primary DOS Partition Note 4 │ │ DOS C: drive Size  32MB │ └─────────────────────────────────────┘ Note 1 Master Startup (Boot) Record code, starting at Track 000, Head 00, Sector 01 of disk 80h or 81h. Note 2 Partition table for Master Boot Record. The 6 is the System ID byte in the partition table that indicates a DOS partition where SIZE > 32MB. Note 3 55AAh is the signature to validate the Master Startup (Boot) Record. Note 4 Primary DOS area. Owns the entire media and exceeds 32MB in size. C: is block device 80h. ═══ 19.8.4. Type 7 Partition ═══ Partition Type 7 is used for Installable File Systems only. The internal FAT file system should not use this partition type because older versions of the DOS and OS/2 operating systems will not be able to access the partition. ═══ 20. Extended Device Driver Interface Specification ═══ The Extended Device Driver interface supported in OS/2 2.1 is specifically targeted for service of hard disk devices. This interface can: o Support submission of multiple asynchronous requests o Allow physically discontiguous data transfer areas o Support a new class of disk devices with advanced bus-mastering and intelligent transfer capabilities o Allow physical device drivers to optimally service large numbers of requests in a heavily loaded environment o Provide a mechanism and supporting semantics to support prioritization of request services The Extended Device Driver interface employs a Request List of prioritized commands the driver can reorder to optimize disk access, subject to prioritization requirements. The requests can also be grouped by the kernel for notification callout from the device driver. In addition, READ and WRITE operations use scatter/gather descriptors, which allow for data transfer to and from discontiguous data buffers. The interface is used asynchronously, removing the need for blocking in the physical device driver or the physical device driver manager when the I/O request itself is asynchronous. While the asynchronous, multi-request aspects of the interface contribute greatly to overall system performance on existing hardware, scatter and gather is specifically targeted for new classes of disk device hardware. This new class of devices supports transfer from disk to physically discontiguous memory space much more efficiently than alternative implementations. The importance of this relative efficiency is amplified by the introduction of paging to the OS/2 operating system, where linearly contiguous memory normally maps to lists of discontiguous physical addresses. In addition, this interface is designed and optimized for server environments such as LAN Server 2.0, where file service paths are Ring 0 only and can execute at task or interrupt time. In such an environment, it must be possible to queue requests to the disk driver for service in the context of a network interrupt. Extended physical disk device drivers refer to a superset of the standard OS/2 1.x physical disk device drivers. The term standard request is used to refer to the old style request packets format. The term extended request is used to refer to the new request packet format. ═══ 20.1. Disk Device Driver Architecture ═══ Driver architecture centers around the need to provide fast, efficient services to a file system in a paged environment. In addition, consideration for the needs of a network file server has influenced aspects of the design; however, the requirements are identical in a local-only or workstation environment (that is, a direct, asynchronous, zero-overhead interface between the file system and the supporting physical disk device drivers). In the OS/2 operating system, a physical disk device driver receives requests for service through a strategy routine at task time in the context of the requestor (an OS/2 thread). The thread of control is also obtained, in the context of interrupts generated by the disk controller, at the physical device driver interrupt routine. In the extended architecture, a second strategy routine is introduced, which can be called directly by File System Drivers (FSDs) at task time or in the context of an arbitrary interrupt. This yields a set of new requirements. ═══ 20.1.1. Standard OS/2 Strategy Routine ═══ The standard OS/2 strategy routine is essentially unchanged in this architecture. Underlying queueing mechanisms used by the driver in the strategy routine are modified to support an environment where there are normally two kinds of requests in the queue, standard and extended. ═══ 20.1.2. Extended Strategy Routine ═══ The extended strategy routine entry point can be called at interrupt or task time. At interrupt time, the driver can work only with physical addresses or global virtual addresses; therefore, only physical and global virtual addresses, which reference structures that are physically contiguous in memory, are used in this interface. Physical addresses are used for data transfer areas. Global virtual addresses are used for request packets, control structures, and entry points. Much of the performance gain realized in this interface is dependent on the asynchronous processing of requests. The performance gain realized is degraded considerably if the driver blocks in the strategy routine, forcing the request to be synchronous. Therefore, while it is not required that the driver never block, it is very strongly recommended if performance is of interest in the system for which the driver is targeted. Additionally, if the driver has set the does-not-block bit in the DD_DriverCaps field returned from the GET DRIVER CAPABILITIES command, then the driver absolutely must not block in any code path accessible by the extended strategy routine entry point. Furthermore, it must not call any DevHlp routine that could block, effectively limiting the DevHlps that can be called to only those permissible at interrupt time. Among the DevHlps that could block are Lock and Unlock, so all buffers passed through the extended entry points are guaranteed to be locked. The extended strategy routine is used only to pass requests in Request List form (see Request Lists and Request Control). The physical device driver queues the requests passed, services the controller as necessary, sets status fields in the requests, and returns. ═══ 20.1.3. Sorting and Priority ═══ Requests should be sorted into internal queues based on physical disk location and I/O priority to optimize request servicing. Lower priority requests should be satisfied only where they do not significantly slow service of higher priority requests (for example, when a lower priority request refers to a sector in the same cylinder as a high priority request). Because the format of requests in Request Lists is different from the format of standard OS/2 requests, the queue management DevHlp routines cannot be used. The queueing strategy adopted by the driver is highly dependent on the devices it services. In general, efficiency and request priority are the primary concerns in determining a queueing strategy. Lower priority requests should never slow service of higher priority requests. Lower priority requests can be serviced in the context of servicing higher priority requests, so long as no time-costly operations are necessary to service the lower priority requests. In addition, where contention for resources such as auxiliary, driver-allocated buffers or space on a controller buffer is an issue, higher priority requests should be given preference. ═══ 20.1.4. Request Management ═══ The physical device driver needs to manage both requests submitted to the extended strategy routines with the Request List format and requests submitted to the standard strategy routine with the standard request packet format. Notice that the CommandCode field in the OS/2 standard request packet coincides with the CommandPrefix byte in the extended request packet, which is guaranteed to be the ExecuteChain prefix. This allows the driver to manage both requests on the same queue. ═══ 20.1.5. Removable Media ═══ The physical device driver should support requests targeted for removable media in the same way it supports requests for nonremovable media. ═══ 20.1.6. Devices Not Capable of Scatter/Gather ═══ Although this interface is clearly targeted for a disk device controller capable of scatter/gather, even devices that are not capable of scatter/gather still realize overall system performance gains as a result of supporting multi-request, asynchronous I/O, and interrupt-time execution. The driver is responsible for deciding how to emulate scatter/gather. In general, emulating scatter/gather to programmed I/O devices introduces no significant overhead. However, if DMA devices, which do not support scatter/gather, attempt to emulate scatter/gather by mapping each scatter/gather descriptor in a single request to one DMA operation, performance will be poor. The driver is better off staging transfers through a pair of contiguous buffers. One buffer can be serviced by the controller while the other is being set up for subsequent operations. While there is overhead incurred in block-copying data through the staging buffer, this is no worse than the overhead the file system would incur in contiguous cache blocks before submission to a standard OS/2 device driver. ═══ 20.2. Identifying Extended Device Drivers and Capabilities ═══ If the physical device driver is an extended device driver, it recognizes the GET DRIVER CAPABILITIES command. This command returns a characteristics bit field, which describes functional capabilities of the device driver, and an entry point vector, which includes the extended strategy routine and several device driver control routines. If the device driver does not recognize the command or does not respond appropriately, the kernel and all client FSD assume the physical device driver supports only standard OS/2 requests and restricts its behavior appropriately. ═══ 20.2.1. GET DRIVER CAPABILITIES Command ═══ This command is structured as a standard OS/2 request packet. Note that the fields prefixed by DD_ are filled in by the physical device driver. (See the following table.) ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Request Header │13 BYTES │ ├──────────────────────────────┼──────────────────────────────┤ │Reserved. Must be zero. │3 BYTES │ ├──────────────────────────────┼──────────────────────────────┤ │DD_CapStruct │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DD_VolCharStruct │DWORD │ └──────────────────────────────┴──────────────────────────────┘ DD_CapStruct A 16:16 virtual pointer to the Driver Capabilities Structure. This pointer is filled in by the physical device driver. See Driver Capabilities Structure (DCS) for the format of this structure. DD_VolCharStruct A 16:16 virtual pointer to the Volume Characteristics Structure (VCS) for this volume. This pointer is filled in by the physical device driver. See Volume Characteristics Structure (VCS) for the format of this structure. ═══ 20.2.1.1. Driver Capabilities Structure (DCS) ═══ The Driver Capabilities Structure (DCS) is maintained by the physical device driver and is passed by reference to the kernel and client FSDs in the GET DRIVER CAPABILITIES command. The kernel and client FSDs must not modify the structure, as it is shared by FSDs and the physical device driver. A DCS has the following format: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Reserved. Must be zero. │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │DD_VerMajor │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │DD_VerMinor │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │DD_Capabilities │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DD_Strategy2 │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DD_SetFSDInfo │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DD_ChgPriority │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DD_SetRestPos │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DD_GetBoundary │DWORD │ └──────────────────────────────┴──────────────────────────────┘ DD_VerMajor The major version number of the interface the physical device driver supports, equal to 01h in the first release. Old major versions do not function correctly with a file system using a newer version. DD_VerMinor The minor version number of the interface the physical device driver supports, equal to 01h in the first release. Old minor versions support a strict subset of the functionality found in newer versions. DD_Capabilities A bit field describing the capabilities of the physical device driver: Bits 0-2 Reserved. Must be zero. Bit 3 If set, supports disk mirroring. Bit 4 If set, supports disk duplexing. Bit 5 If set, driver does not block in Strategy2. LAN Server and LAN Manager products using the HPFS 386 file system require that bit 5 be set to guarantee that the physical device driver does not block in Strategy2. Bits 6-31 Reserved. Must be zero. DD_Strategy2 The 16:16 entry point for the strategy routine that supports multi-request asynchronous I/O. DD_SetFSDInfo The 16:16 entry point for DD_SetFSDInfo. The value returned is 0:0, if the service is not provided by the physical device driver. DD_ChgPriority The 16:16 entry point for DD_ChgPriority. The value returned is 0:0, if the service is not provided by the physical device driver. DD_SetRestPos The 16:16 entry point for DD_SetRestPos. The value returned is 0:0, if the service is not provided by the physical device driver. DD_GetBoundary The 16:16 entry point for DD_GetBoundary. The value returned is 0:0, if the service is not provided by the physical device driver. ═══ 20.2.1.2. Volume Characteristics Structure (VCS) ═══ The parameters passed in the Volume Characteristics Structure (VCS) are used by FSDs to optimize disk access and placement of file system structures on an advisory basis. All values reflect the physical parameters of the logical volume, as if it were a single physical device (that is, whether the media is partitioned or not). This data structure is passed by reference and is maintained and updated by the physical device driver, as necessary. It is expected that the physical device driver would maintain a separate VCS for each logical volume supported. A VCS has the following format: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │VolDescriptor │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │AvgSeekTime │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │AvgLatency │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │TrackMinBlocks │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │TrackMaxBlocks │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │Head Per Cylinder │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │VolCylinderCount │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │VolMedianBlock │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │MaxSGList │WORD │ └──────────────────────────────┴──────────────────────────────┘ VolDescriptor A bit field, defined as follows: Bit 0 If set, volume resides on removable media Bit 1 If set, volume is read-only Bit 2 If set, average seek time independent of position (RAM disk) Bit 3 If set, outboard cache supported Bit 4 If set, scatter/gather supported by adapter Bit 5 If set, ReadPrefetch supported Bits 6-15 Reserved, set to 0 AvgSeekTime The average seek time (in milliseconds) in servicing this volume. If the seek time is unknown, FFFFH is to be specified. Can be 0 for RAM disks. AvgLatency The average rotational latency (in milliseconds) for the device servicing this volume. If the average latency is unknown, FFFFH is to be specified. Latency can be 0 for RAM disks. TrackMinBlocks The number of blocks available on the smallest capacity track; if unknown or not applicable, a value of 1 is specified. TrackMaxBlocks The number of blocks available on the largest capacity track; if unknown or not applicable, a value of 1 is specified. Heads Per Cylinder The number of heads per cylinder; if unknown or not applicable, a value of 1 is specified. VolCylinderCount The number of cylinders in the volume; if unknown or not applicable, the number of allocation blocks (sectors) is used. VolMedianBlock The number of the block, which is in the center of the volume with respect to seek time (that is, the block with the smallest average seek time). MaxSGList The maximum number of scatter and gather list entries, which can be directly submitted to the adapter servicing this volume with one low-level I/O command. File systems submitting extended commands with scatter and gather lists greater than MaxSGList entries must ensure that the cumulative byte count of each MaxSGList entry in the list is a multiple of the sector size. This field is set to 0, if the volume is serviced by an adapter that does not directly support scatter/gather lists. See Scatter/Gather Descriptor for details on scatter/gather lists passed in extended requests. ═══ 20.3. Request Lists and Request Control ═══ In order to support multi-request asynchronous I/O, a new request format has been defined, called Request Lists. This format allows multiple requests to be submitted in one call to the extended strategy routine, as well as grouping of those requests for notification purposes. In general, requests from any and all lists can be reordered and considered independently by the physical device driver for optimal throughput. Presently, only READ, WRITE, and READ PREFETCH commands have been defined in the new format. Through Request Control flags, optional restrictions can be set on the requests to force sequential execution and to allow early termination of request processing, should any of the requests fail. The notification mechanism allows the kernel and client file systems to receive callout notification when specific individual requests complete, when the entire request list completes, or both. In addition, notification can take place when an error condition occurs, when requests complete successfully, or both. Alternatively, no callout notification can be specified, allowing the system to poll for request completion during idle time. Extended disk driver requests are submitted directly through the extended strategy routine entry point, DD_Strategy2, obtained through the GET DRIVER CAPABILITIES command and passed to client FSDs through FS_MOUNT. Requests are submitted in request list format, with ES:BX containing a global pointer to the Request List. Each request in the list is an EXECUTE CHAIN command containing the EXECUTE CHAIN command prefix at the same offset into the extended request packet as the Command field in the standard request packet. Request Lists have the following format: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Request List Header │20 BYTES │ ├──────────────────────────────┼──────────────────────────────┤ │Requests │ARRAY │ └──────────────────────────────┴──────────────────────────────┘ The Request List header has the following format: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │ReqListCount │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │Reserved │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │LstNotifyAddress │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │LstRequestControl │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │Block Device Unit │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │LstStatus │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │DDReserved │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DDReserved │DWORD │ └──────────────────────────────┴──────────────────────────────┘ ReqListCount The number of requests in the Request List. Reserved Must be 0. LstNotifyAddress The 16:16 address of a notification routine to be called (according to the flags in LstRequestControl) when all requests have been completed or terminated due to error conditions. LstNotifyAddress is not valid if bits 4 and 5 of LstRequestControl are clear. LstNotifyAddress is called with the following parameters: ES:BX 16:16 Address of Request List header CF Set, if an unrecoverable error has occurred The physical device driver is responsible for saving and restoring any registers that must survive the call. LstRequestControl A bit field of control flags as follows: Bit 0 Reserved. Bit 1 If set, there is only one request in the list. The same mechanism is used to submit one or many requests. Bit 2 If set, requests are to be executed in sequence. Indicates that requests in this list must be executed in the order in which they appear in the Request List. They need not be executed adjacently; requests from other lists can interleave execution of this list. Bit 3 If set, terminate on error. Indicates that, if an unrecoverable error occurs in processing any request in the list, outstanding requests in the list must not be executed. All Status, ErrorCode, and BlocksXferred fields must be updated, however. Bit 4 If set, notify immediately on error only. Indicates that the request list notification routine, LstNotifyAddress, should be called immediately if an unrecoverable error occurs in servicing any of the requests in the Request List. Bit 5 If set, notify on completion. Indicates that the request list notification routine should be called when execution of the requests has completed, regardless of error conditions. If bit 4 and bit 5 are clear, the request list notification routine address is not valid. If bit 4 or bit 5 is set, the notification routine address is valid. Bits 6-15 Reserved. Must be 0. Block Device Unit The logical unit number of the volume the requests are directed to. Note this forces all requests in the list to be addressed to the same block device unit. LstStatus Indicates the overall status for the Request List. This field should be set immediately by the physical device driver at strategy time and updated as requests complete successfully or unsuccessfully. The low nibble indicates the completion status of the requests in the list, giving the LstStatus byte the following values: X0h Indicates that no requests have been queued. It is guaranteed that the kernel will set this status on entry to the physical device driver. The physical device driver sets this status on return only if queueing was not possible due to exhausted driver-internal resources. X1h Indicates that some requests have not yet been sorted into internal queues. That is, queueing is in process but has not yet been completed. X2h Indicates that all requests in the list have been queued and are awaiting service. X4h Indicates that all requests in the list have been completed successfully or unsuccessfully due to error conditions. X8h Reserved. The high nibble indicates the error status of the requests in the list, giving the LstStatus byte the following values: 0Xh No error. 1Xh Indicates that an error has occurred in processing at least one of the requests, but the physical device driver has successfully recovered the error through retries, ECC, disk mirroring, or duplexing. 2Xh Indicates that an unrecoverable error has occurred in processing at least one of the requests. 3Xh An unrecoverable error has occurred with retry. 4Xh Reserved. 8Xh Reserved. Bits in the high nibble can be set in combination with bits in the low nibble to indicate the various error and completion states. LstStatus is guaranteed to be 0 when the request list is submitted to the physical device driver. DDReserved Reserved for device driver use in tracking request completion. Since the number of requests in the list is variable, this field might be used to point to an auxiliary structure maintained by the device driver. Each request has a fixed length header, followed by a variable length, command-specific area. The general format of an extended request is shown in the following table: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Request Header │32 BYTES │ ├──────────────────────────────┼──────────────────────────────┤ │Command-Specific │BYTE │ └──────────────────────────────┴──────────────────────────────┘ ═══ 20.3.1. Extended Commands ═══ The following extended commands, and corresponding command codes, are defined for use in Request Lists: 1Eh READ 1Fh WRITE 20h WRITE VERIFY 21h READ PREFETCH The format of the command-specific portion of the request packet format along with details of each command are described in the sections that follow. ═══ 20.3.1.1. Request Header ═══ Each request in the Request List begins with a fixed length header, which has the following format: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Request Length │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │Command Prefix=1Ch │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │Command Code │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │Header Offset │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Request Control │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │Priority │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │Status │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │Error Code │BYTE │ ├──────────────────────────────┼──────────────────────────────┤ │Notify Address │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Hint Pointer │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DDReserved │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DDReserved │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │DDReserved │DWORD │ └──────────────────────────────┴──────────────────────────────┘ Request Length The offset of the next request. If this is the last request, the value is FFFFH. Command Prefix At the same offset in this request header as the command code in the standard OS/2 request header. This byte is always set to EXTENDED REQUEST (1Ch) to allow the physical device driver to maintain one queue for both standard and extended requests, while distinguishing the two packet types. Command Code The request command code. Can have any of the values defined in Extended Commands. Header Offset The offset from the beginning of the Request List header to the header of this request. This field, when subtracted from the address of the header of this request, yields the header of the list. This provides fast access to the control information in the header. Request Control A bit field of control flags as follows: Bits 0-3 Reserved. Must be 0. Bit 4 If set, notify on error only. Indicates that the individual request notification routine, NotifyAddress, should be called immediately in the event that an unrecoverable error occurs in servicing the request. Bit 5 If set, notify on completion. Indicates that the individual notification routine, NotifyAddress, should be called when execution of the request has completed successfully and possibly with a recoverable error. This bit does not indicate notification in the case of an unrecoverable error. If bit 4 and bit 5 are clear, the individual request notification routine address is not valid. If bit 4 or bit 5 is set, the notification routine address is valid. Bits 4 and 5 can both be set to indicate notification in case of error or successful completion. Bits 6-7 Reserved. Must be 0. Priority A bit field indicating the priority of the request. The following values are currently defined, and others may be added as needed, without notice: 00h Prefetch Requests. 01h Low priority request to be satisfied in the context of servicing other, higher priority requests or when no other work exists (lazy-write). 02h Read ahead, low priority pager I/O. 04h Background synchronous user I/O. 08h Foreground synchronous user I/O. 10h High priority pager I/O. 80h Urgent request; all requests at this priority should be satisfied in a single sweep of the disk; no stopping allowed at cylinders other than those necessary to satisfy requests in this priority. The kernel uses this priority in cases such as an impending power failure or shutdown. The kernel or client FSD can request a priority change after the initial submission of the request to the physical device driver by issuing a call to DD _ChgPriority. Status A bit field indicating the status of the request. The low nibble indicates the completion status of the request, giving the Status byte the following values: X0h Not yet queued X1h Queued and waiting X2h In process X4h Done X8h Reserved The high nibble indicates the error status of the request, giving the Status byte the following values: 0Xh No error 1Xh A recoverable error has occurred 2Xh An unrecoverable error has occurred 3Xh An unrecoverable error has occurred 4Xh The request was abnormally ended 8Xh Reserved High and low nibbles can be set in combination by the physical device driver to indicate combinations of error and status conditions. For example, a code of 12h indicates that a recoverable error has occurred and the request is still in progress. An error condition indicates a valid error code in the ErrorCode field. Status is guaranteed to be 00h when the request is submitted. Error Code Contains a valid error condition, if an error status is indicated in Status. The following error codes are possible if the error is unrecoverable and are compatible with previous OS/2 error returns: 00h Write-protect violation 01h Unknown unit 02h Device not ready 03h Unknown command 04h CRC error 06h Seek error 07h Unknown media 08h Block not found 0Ah Write fault 0Bh Read fault 0Ch General failure 10h Uncertain media 13h Invalid parameter The following error codes are possible, if the error is recoverable: 1Ah Verify error on write, succeeded after retry 2Ah Write error, write to mirrored or duplexed drive succeeded 3Ah Write error on mirrored or duplexed drive; write to primary drive succeeded 1Bh Read error, corrected using ECC 2Bh Read succeeded after retry 3Bh Read error, recovered from mirrored or duplexed drive NotifyAddress The address of a notification routine to be called (according to the flags in RequestControl) when the request has completed successfully or unsuccessfully due to error conditions. NotifyAddress is not valid if bits 4 and 5 of RequestControl are clear. NotifyAddress is called with the following parameters: ES:BX 16:16 Address of the request header CF Set, if an unrecoverable error has occurred. The physical device driver is responsible for saving and restoring any registers that must survive the call. Hint Pointer A 16:16 pointer to a request packet in a Request List. This field can be used when the kernel or the client FSD determines that this request might be best grouped with another request it has already submitted to the physical device driver. The request might have already completed, so the physical device driver must validate that the pointer points to a request on its internal queues. This field is FFFF:FFFFH if it is unused (that is, if a hint is not being passed). DDReserved Fields reserved for device driver use. ═══ 20.3.1.2. Write/Read/WriteVerify ═══ The format of the request packet for the WRITE, READ, and WRITE VERIFY commands is: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Request Header │32 BYTES │ ├──────────────────────────────┼──────────────────────────────┤ │Start Block │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Block Count │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │BlocksXferred │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Flags │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │SGDescrCount │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │Reserved │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │SGDescriptors │ARRAY │ └──────────────────────────────┴──────────────────────────────┘ Request Header The fixed length request header. Start Block The starting disk block for the data transfer operation. A disk block is defined as a 512-byte logical disk sector. Block Count The number of 512-byte blocks to be transferred. BlocksXferred The number of 512-byte blocks successfully transferred by the driver. This field is updated before the request and request list notification routines are called and before the Status field is marked as Done. Flags A bit field of command-specific control flags. The following flags have been defined: Bit 0 If set, write through. Defeats any lazy-write caching performed by the physical device driver. Notice that lazy-write, through battery-backed RAM, is permitted, even if this bit is set. Bit 1 If set, cache request on outboard controller cache. Bits 2-15 Reserved, set to 0. SGDescrCount The number of scatter/gather descriptors in the SGDescriptors field. SGDescriptors An array of scatter/gather descriptors describing the buffers for data transfer specified by the command. The File System Driver (FSD) guarantees the following to be true: ────────────────────────────────────────────────────────────────────────── BlockCount * 512 equals the sum of the BufferSize fields in SGDescriptors. ────────────────────────────────────────────────────────────────────────── In addition, buffers are typically DWORD aligned. The physical device driver should be optimized for this case, but should not rely upon it. ═══ 20.3.1.3. Scatter/Gather Descriptor ═══ READ and WRITE operations use an array of scatter/gather descriptors to describe the buffer space to be used in the operation. This enables transfers of contiguous disk blocks into physically discontiguous, byte-aligned memory blocks. Scatter/gather descriptors have the following format: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │BufferPtr │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Buffer Size │DWORD │ └──────────────────────────────┴──────────────────────────────┘ BufferPtr A 32-bit physical pointer to the buffer Buffer Size Size of the buffer in bytes ═══ 20.3.1.4. READ PREFETCH ═══ READ PREFETCH is defined to take advantage of a two-tiered disk caching scheme, where the first tier is the file system and the second tier is the controller buffer. This command is optionally supported, if the Read Prefetch bit is set in the VolDescriptor bit field of the VCS for the device. If this bit is set, it is assumed that: o The physical device driver manages a cache located on the controller. o A Read into controller memory, followed by a Read into system memory, is less expensive (in terms of host CPU utilization) than just a Read into system memory. If both of these conditions are not met, then the physical device driver does not publish READ PREFETCH capabilities because it is more efficient for the file system to perform read-ahead into its own cache. READ PREFETCH commands are the lowest priority requests submitted to the physical device driver through the extended strategy routine and are never serviced prior to other Read/Write requests. The format of the request packet for READ PREFETCH is: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Request Header │32 BYTES │ ├──────────────────────────────┼──────────────────────────────┤ │Start Block │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Block Count │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │BlocksXferred │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Flags │WORD │ ├──────────────────────────────┼──────────────────────────────┤ │Reserved. Must be 0. │WORD │ └──────────────────────────────┴──────────────────────────────┘ Request Header The fixed length request header. Start Block The starting disk block for the data prefetch operation. A disk block is defined as a 512-byte logical disk sector. Block Count The number of 512-byte blocks to be prefetched. BlocksXferred The number of 512-byte blocks successfully prefetched by the physical device driver. This field is updated before the request and request list notification routines are called and before the Status field is marked as Done. Flags A bit field of command-specific control flags. The following flags have been defined: Bit 0 If set, hold only until read. The physical device driver retains the data in controller prefetch buffers only until it is read once. This is to prevent redundant caching in the controller. Bits 1-15 Reserved, set to 0. ═══ 20.3.2. Request Control Functions ═══ Request control functions are used by the FSD to manage requests after they have been submitted to obtain advisory information from the physical device driver and to pass advisory information to the physical device driver. Entry points are exported by the physical device driver through the GET DRIVER CAPABILITIES command. Request control functions can be called at interrupt time and cannot block. Request control functions need only preserve segment registers. The following request control functions are defined: o DD_SetFSDInfo o DD_ChgPriority o DD_SetRestPos o DD_GetBoundary ═══ 20.3.2.1. DD_SetFSDInfo ═══ This entry point allows the FSD to inform the physical disk device driver of its FSD_EndOfInt and FSD_AccValidate entry points. The physical disk device driver allows DD_SetFSDInfo to be called exactly once, and ignores subsequent calls. ────────────────────────────────────────────────────────────────────────── ENTRY ES:BX 16:16 pointer to the FSDInfo structure. EXIT CF Set, if call was ignored. ────────────────────────────────────────────────────────────────────────── The format of the FSDInfo structure is: ┌──────────────────────────────┬──────────────────────────────┐ │Field │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Reserved. Must be 0. │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │FSD_EndOfInt │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │Reserved. Must be 0. │DWORD │ ├──────────────────────────────┼──────────────────────────────┤ │FSD_AccValidate │DWORD │ └──────────────────────────────┴──────────────────────────────┘ FSD_EndOfInt The 16:16 entry point of the FSD's FSD_EndOfInt routine. This field is set to 0 if the FSD does not provide an FSD_EndofInt routine. The entry point is called by the physical device driver when it has completed interrupt processing and after it has called DevHlp_EOI. FSD_EndOfInt takes no parameters and leaves all registers intact. FSD_AccValidate The 16:16 entry point of the FSD's FSD_AccValidate routine. This field is set to 0 if the FSD does not provide an FSD_AccValidate routine. The entry point is called whenever direct I/O is done through a Category 08h or 09h IOCtl to an HPFS volume or whenever direct I/O is done to the Master Startup (Boot) record through a Category 09h IOCtl. For Category 09h IOCtls, the physical device driver must use the Head, Cylinder, and Sector values passed in the IOCtl. These values are used to determine whether the I/O request falls within an HPFS volume, because the unit number in the IOCtl represents the entire physical disk and not the logical volume. The physical device driver should call FSD_AccValidate with: ────────────────────────────────────────────────────────────────────────── AL Operation Code 00 Non-destructive (READ, VERIFY) 01 Destructive (WRITE, FORMAT TRACK, and so forth) ────────────────────────────────────────────────────────────────────────── On return from the FSD: ────────────────────────────────────────────────────────────────────────── NC I/O access is allowed. CF If set, access is denied. The physical device driver should return error code 00h (Write-protection violation) to the caller. ────────────────────────────────────────────────────────────────────────── ═══ 20.3.2.2. DD_ChgPriority ═══ This entry point allows the FSD to notify the physical device driver of a possible change in the priority of a request. HPFS calls this entry point with: ────────────────────────────────────────────────────────────────────────── ENTRY ES:BX Address of the request AL New priority for the request; EXIT CF Set, if request packet not found on any of the physical device driver's internal queues ────────────────────────────────────────────────────────────────────────── This call is used to change the priority of a previously submitted request. The physical device driver performs whatever resorting of internal queues is necessary, and returns. The FSD guarantees that the pointer that was passed references a valid request (that is, a request with allowed values in all fields). There is no guarantee that the priority of the request has actually been changed or that the request is still on the internal queues of the driver. If the request has been removed from internal queues, has already been incorporated into internal structures in preparation for service, or has already been serviced, the physical device driver can ignore the requested change. ═══ 20.3.2.3. DD_SetRestPos ═══ This entry point advises the physical device driver of a block to seek when there is no work in the queue. No immediate action is necessary when the call is made. This call is purely advisory and can be ignored by the driver if it is not useful or applicable to the hardware it supports. ────────────────────────────────────────────────────────────────────────── ENTRY AX:BX Block to use as resting point, FFFF:FFFFH, if none CL Logical Unit Number (A:=0) EXIT CF Set, if block is out of range. ────────────────────────────────────────────────────────────────────────── The physical device driver updates a static variable, specifying where to rest the heads during idle time. When any seek occurs, either as a result of this call or as the result of I/O requests, the variable is set to FFFFFFFFH. A value of FFFFFFFFH indicates rest-where-you-end-up. This call essentially assumes that there is only one active logical volume serviced by the underlying physical device. Physical device, in this context, means mechanical, usually multi-headed, disk arm. If this is not the case, this call should be ignored by the driver. ═══ 20.3.2.4. DD_GetBoundary ═══ This entry point returns the first block number that is greater than the block number specified in the DWORD passed and is past an access time boundary, such as a cylinder. This information can be used by file systems to optimally place file system objects. ────────────────────────────────────────────────────────────────────────── ENTRY AX:BX Reference block number EXIT AX:BX Number of first block past access time boundary CF Set, if block number out of range. ────────────────────────────────────────────────────────────────────────── If the physical device driver cannot compute this efficiently, it can precompute this information and retain it internally, or if this is not feasible, it can return (AX:BX) + 1. ═══ 21. 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/G list */ 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_TRACK; /*--------------------------------------------------------------------------*/ /* 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 ────────────────────────────────────────────────────────────── ═══ 22. OS/2 SCSI Device Driver Interface Specification ═══ This appendix describes the high-level interface for the SCSI device driver for the OS/2 operating system. For completeness, all functions are listed; however, functions that are not implemented are so indicated. Some of the internal specifications of the device driver have not been included here so that this document can be externally distributed to vendors wanting to write device drivers to the SCSI device driver interface. ═══ 22.1. Introduction ═══ The SCSI driver is the lower half of a split model for OS/2 SCSI device drivers. The SCSI driver drives the SCSI adapter through the SCSI adapter device driver as shown in the following figure. ┌───────────────────────────────────────────────────────────┐ │ │ │ │ │ OS/2 KERNEL │ │ │ │ │ └──────┬──────────────────┬─────────────────┬───────────────┘ │ │ │ │ │ │ ┌──────┴───────┐ ┌────────┴───────┐ ┌───────┴──────┐ │ CDROM CLASS │ │ OPTICAL CLASS │ │ OTHER CLASS │ .... │ DRIVER │ │ DRIVER │ │ DRIVER │ └──────┬───────┘ └────────┬───────┘ └───────┬──────┘ │ │ │ │ │ │ ┌──────┴──────────────────┴─────────────────┴───────────────┐ │ │ │ OS2SCSI.DMD SCSI DEVICE MANAGER │ │ │ └─────────────────────────────┬─────────────────────────────┘ │ │ ┌─────────────────────────────┴─────────────────────────────┐ │ SCSI ADD │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────┴─────────────────────────────┐ │ SCSI ADAPTER │ └──────┬─────────────────┬──────────────────┬───────────────┘ │ │ │ ┌──────┴───────┐ ┌───────┴────────┐ ┌───────┴──────┐ │ CDROM SCSI │ │ OPTICAL SCSI │ │ OTHER SCSI │ .... │ DEVICE │ │ DEVICE │ │ DEVICE │ └──────────────┘ └────────────────┘ └──────────────┘ The diagram illustrates the relationship between the device drivers and their interaction with other components of the system. The split device driver model uses the principles of code layering to facilitate development and maintenance of new SCSI device drivers. The provision of common functions in the SCSI driver also reduces memory requirements. Performance is enhanced because the SCSI driver centralizes control of the SCSI channel, thus reducing contention. Only one interrupt handler is registered for all the SCSI peripheral devices. A split device driver model has been used by IBM for all the SCSI devices except the SCSI fixed disks, which use the OS/2 DASD Manager. The device-class driver is the upper-level driver, and the SCSI driver is the lower-level driver. The device-class driver does not interact directly with the SCSI adapter or the SCSI device. The device-class driver sends commands to the SCSI device manager, which in turn sends commands to the device using the IORB ADD interface. The device-class driver looks very much like an OS/2 device driver. It maps an OS/2 request into an SCB, or a chain of SCBs, and passes the request immediately to the SCSI driver. The SCSI driver handles all queuing and interrupts and insulates the device-class driver from the procedural details of managing adapter hardware. The device-class driver requests a service, like Transfer SCB, from the SCSI device manager. When control is returned to the device-class driver, the called service is complete. If an error occurred, the termination status block (TSB) might contain error information. In addition, sense data might have been returned. ═══ 22.2. Naming Conventions ═══ o SCSI Driver The file name for the SCSI driver is OS2SCSI.DMD. The IDC entry point for the SCSI driver can be obtained from the AttachDD DevHlp function by using the name SCSI-02$ as the device driver name parameter. o IBM Device-Class Drivers Current device driver names used by IBM are: OPTICAL.SYS Read/Write optical device driver Note: Naming conflicts are possible, so try to choose unique names for your device-class drivers. In a SCSI environment, different vendor devices for the same SCSI device class can be present in one system. o Message Files The IBM-reserved message file name for device drivers that have been developed internally is DEV002.MSG. Independent vendors must not use DEV002.MSG for their message files, because if they do, one of those message files could be destroyed during the user installation process. It is suggested that vendors choose a unique message file name by embedding part of their logo or company name in the file name; that would eliminate the possibility of having different vendor devices with the same message file name installed in the same system. ═══ 22.3. Generic IOCtl Request ═══ The input to the SCSI driver is a generic IOCtl request packet, pointed to by the ES:BX register pair. Note: It is not the intention of the IOCTL definitions in the SCSI.SYS specification to provide an application level programming interface to SCSI devices. The intention of the IOCTL definitions is to allow client drivers at their Ring 3 INIT time to communicate with the OS2SCSI.DMD which is running at a higher privilege level than the installable driver. A client driver may choose to provide application level services. However, all responsibility for locking and removing LDT references from the IOCTL/SCB/TSB structures would rest with the client driver not OS2SCSI.DMD. ═══ 22.3.1. OS/2 SCSI Services ═══ The SCSI driver supports the following requests: o Read Device Parameters o Reset/Initialization o Enable Adapter Cache o Disable Adapter Cache o Return Adapter Cache Status o Set Device Timeout o Read Device Timeout o Transfer SCB o Deallocate Device o Allocate Device o Return Peripheral Type Count o Abort ═══ 22.3.1.1. Read Device Parameters ═══ This function returns some information about the device. The logical unit number (LUN) is required if a Send Other command is used. Input Parameter Structure Field Length Device Handle WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 43h ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code are to be set up as shown above. ┌────────────────────────┬────────────────────────────────────┐ │Field Name │Length │ ├────────────────────────┼────────────────────────────────────┤ │Device Key Index │WORD │ ├────────────────────────┼────────────────────────────────────┤ │SCB Architecture Card │BYTE │ │Comp. Level │ │ ├────────────────────────┼────────────────────────────────────┤ │Adapter Index │BYTE │ ├────────────────────────┼────────────────────────────────────┤ │Device Flags │WORD │ ├────────────────────────┼────────────────────────────────────┤ │Logical unit number │BYTE │ │(LUN) │ │ ├────────────────────────┼────────────────────────────────────┤ │Physical unit number │BYTE │ │(PUN) │ │ └────────────────────────┴────────────────────────────────────┘ Adapter Index contains the adapter number for the SCSI adapter. Device Flags Bit 4 0 = Adapter cache not supported. 1 = Adapter cache supported. Bit 1 0 = Device power ON. 1 = Device power OFF. Bit 0 0 = Device is not defective. 1 = Device is defective. ═══ 22.3.1.2. Reset/Initialize ═══ This function results in a reset message being issued to the physical device. Input Parameter Structure Field Length Device Handle WORD Sense Data Size WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 45h ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code must be set up as shown above. Data Buffer This function does not require a data buffer. Status is returned in the Status field of the request packet. ═══ 22.3.1.3. Enable Adapter Cache ═══ This function enables the adapter cache capability for all subsequent commands to this device. Input Parameter Structure Field Length Device Handle WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 4Dh ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code must be set up as shown above. Data Buffer This function does not require a data buffer. Status is returned in the Status field of the request packet. ═══ 22.3.1.4. Disable Adapter Cache ═══ This function disables the adapter cache capability for subsequent commands to the specified device. Input Parameter Structure Field Length Device Handle WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 4Eh ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code must be set up as shown above. Data Buffer This function does not require a data buffer. Status is returned in the Status field of the request packet. ═══ 22.3.1.5. Return Adapter Cache Status ═══ This function returns the adapter cache status for the specified device. Input Parameter Structure Field Length Device Handle WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 4Fh ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code must be set up as shown above. ┌──────────────────────────────┬──────────────────────────────┐ │Field Name │Length │ ├──────────────────────────────┼──────────────────────────────┤ │Adapter Cache Status │BYTE │ └──────────────────────────────┴──────────────────────────────┘ ────────────────────────────────────────────────────────────────────────── Adapter Cache Status : 00H Enabled 01H Disabled ────────────────────────────────────────────────────────────────────────── ═══ 22.3.1.6. Set Device Timeout ═══ This function sets the timeout value for this device. Input Parameter Structure Field Length Timeout Value DWORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 50h ────────────────────────────────────────────────────────────────────────── This function requires a device handle and a timeout value to be passed in the request. The timeout value is in milliseconds. The device must be allocated by the device-class driver before calling this function. The function category and function code must be set up as shown above. Data Buffer This function does not require a data buffer. Status is returned in the Status field of the request packet. ═══ 22.3.1.7. Read Device Timeout ═══ This function returns the current timeout value for this device. Input Parameter Structure Field Length Device Handle WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 51h ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code must be set up as shown above. ┌────────────────────────┬────────────────────────────────────┐ │Field Name │Length │ ├────────────────────────┼────────────────────────────────────┤ │Timeout Value │DWORD │ └────────────────────────┴────────────────────────────────────┘ The timeout value is in milliseconds. ═══ 22.3.1.8. Transfer SCB ═══ This function causes an SCB or a chain of SCBs to be sent to the adapter. ┌─────────────────────────────────────────────┬───────────────┐ │Field Name │Length │ ├─────────────────────────────────────────────┼───────────────┤ │Device Handle │WORD │ ├─────────────────────────────────────────────┼───────────────┤ │Sense Data Size │WORD │ ├─────────────────────────────────────────────┼───────────────┤ │Physical Pointer to SCB │DWORD │ ├─────────────────────────────────────────────┼───────────────┤ │Logical Pointer to SCB Chain Header │DWORD │ ├─────────────────────────────────────────────┼───────────────┤ │Flags │BYTE │ └─────────────────────────────────────────────┴───────────────┘ ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 52h ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code are to be set up as shown above. Flags Bit 0 = 0 Normal Length SCB 1 Long SCB A normal length SCB is used to send generic SCSI commands to a device. The long SCB is used to send a vendor-unique SCSI command embedded in the SCB. Data Buffer If an error occurs, the data buffer might contain sense data; the return code indicates whether the sense data is valid. A termination status block also might be returned. SCB Chain Header +00h ┌────────────────────────────┐ │ Reserved │ +02h ├────────────────────────────┤ │ Logical Pointer to next │ ├─ SCB Chain Header ─┤ │ │ +06h ├────────────────────────────┤ │ Reserved │ +08h ├────────────────────────────┤ │ Reserved │ +0Ah ├────────────────────────────┤ │ Logical Pointer to TSB │ ├─ ─┤ │ │ +0Eh ├────────────────────────────┤ │ Reserved │ +10h ├────────────────────────────┤ │ │ │ │ │ SCB │ │ │ │ Immediately │ │ │ │ Follows │ │ │ │ the │ │ │ │ Chain │ │ │ │ Header │ │ │ │ │ └────────────────────────────┘ See Subsystem Control Blocks for a description of the SCB architecture. ═══ 22.3.1.9. Allocate Device ═══ This function allocates a SCSI peripheral device and returns the device handle that will be used to access the device. Input Parameter Structure Field Length Device Peripheral Type BYTE Device Type Flags BYTE Nth Available WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 55h ────────────────────────────────────────────────────────────────────────── This function requires a device type, device type flags, and Nth available device to be passed in the request. The device type flags define the removable media indicator. The most significant bit of the device type flags set indicates that the media is removable. The Nth available is the Nth device in the device type group. If Nth available is 0, the next available device is returned. o SCSI Device Types Direct Access 0x00 Sequential Access 0x01 Printer 0x02 Processor 0x03 Write Once/Read Many 0x04 CD-ROM 0x05 Scanner 0x06 Optical Memory 0x07 Medium Changer 0x08 Communications 0x09 Data Buffer ┌────────────────────┬────────────────────────────────────────┐ │Field Name │Length │ ├────────────────────┼────────────────────────────────────────┤ │Device Handle │WORD │ └────────────────────┴────────────────────────────────────────┘ Device Handle Returned to the caller. ═══ 22.3.1.10. Deallocate Device ═══ This function deallocates the SCSI Peripheral Device assigned to this device handle. Input Parameter Structure Field Length Device Handle WORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 54h ────────────────────────────────────────────────────────────────────────── This function requires a device handle to be passed in the request. The device must be allocated by the device-class driver before calling this function. The function category and function code must be set up as shown above. Data Buffer This function does not require a data buffer. Status is returned in the Status field of the request packet. ═══ 22.3.1.11. Return Peripheral Type Count ═══ This function returns a count of the number of devices of a particular type that are detected. Input Parameter Structure Field Length Device Peripheral Type BYTE Device Type Flags BYTE ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 56h ────────────────────────────────────────────────────────────────────────── This function requires a device type and device type flags to be passed in the request. The device type flags define the removable media indicator. The most significant bit of the device type flags set indicates that the media is removable. Function category and function code must be set up as shown above. ┌────────────────────┬────────────────────────────────────────┐ │Field Name │Length │ ├────────────────────┼────────────────────────────────────────┤ │Count of Device Type│WORD │ │Requested │ │ └────────────────────┴────────────────────────────────────────┘ Count of Device Type Requested Returned when the request is completed successfully. ═══ 22.3.1.12. Send Abort ═══ This function causes an abort request to be sent to the device. Input Parameter Structure Field Length Device Handle WORD Sense Data Size WORD Reserved DWORD ────────────────────────────────────────────────────────────────────────── FUNCTION CATEGORY : 80h FUNCTION CODE : 57h ────────────────────────────────────────────────────────────────────────── Data Buffer This function does not require a data buffer. Status is returned in the Status field of the request packet. ═══ 22.4. Return Codes ═══ The following table describes return code bit categories. ┌──────────┬──────────────────────────────────────────────────┐ │Bit │Category │ │Numbers │ │ ├──────────┼──────────────────────────────────────────────────┤ │15 │ERROR │ ├──────────┼──────────────────────────────────────────────────┤ │10 - 14 │RESERVED │ ├──────────┼──────────────────────────────────────────────────┤ │9 │BUSY │ ├──────────┼──────────────────────────────────────────────────┤ │8 │DONE │ ├──────────┼──────────────────────────────────────────────────┤ │7 │SCSI ERROR │ ├──────────┼──────────────────────────────────────────────────┤ │0 - 6 │ERROR CODE (when Bit 15 = 1) │ └──────────┴──────────────────────────────────────────────────┘ The following table describes bit descriptions. ┌──────────┬──────────────────────────────────────────────────┐ │Bit │Description │ ├──────────┼──────────────────────────────────────────────────┤ │07 │SCSI Driver-Specific Error │ ├──────────┼──────────────────────────────────────────────────┤ │08 │Operation Complete │ ├──────────┼──────────────────────────────────────────────────┤ │15 │Request Completed with Error │ └──────────┴──────────────────────────────────────────────────┘ The following table describes SCSI error codes. ┌──────────┬──────────────────────────────────────────────────┐ │Error Code│Description │ ├──────────┼──────────────────────────────────────────────────┤ │00h │Device Error (Sense Data Returned) │ ├──────────┼──────────────────────────────────────────────────┤ │01h │Timeout Error │ ├──────────┼──────────────────────────────────────────────────┤ │02h │Unusual Wakeup Error │ ├──────────┼──────────────────────────────────────────────────┤ │03h │DevHlp Error │ ├──────────┼──────────────────────────────────────────────────┤ │04h │Request Block Not Available │ ├──────────┼──────────────────────────────────────────────────┤ │05h │Maximum Device Support Exceeded │ ├──────────┼──────────────────────────────────────────────────┤ │06h │Interrupt Level Not Available │ ├──────────┼──────────────────────────────────────────────────┤ │07h │Device Not Available │ ├──────────┼──────────────────────────────────────────────────┤ │08h │More IRQ Levels than Adapters │ ├──────────┼──────────────────────────────────────────────────┤ │09h │Device Busy │ ├──────────┼──────────────────────────────────────────────────┤ │0Ah │Request Sense Failed │ ├──────────┼──────────────────────────────────────────────────┤ │0Bh │Adapter Cache Not Supported │ └──────────┴──────────────────────────────────────────────────┘ The SCSI device driver can return any of the standard OS/2 device driver return codes as well as the specific error codes listed above. If Bit 15 is set, Bits 0 - 6 contain an error code. If, in addition, Bit 7 is set, the error code in Bits 0 - 6 is one of the SCSI device driver-specific error codes from the table. Otherwise, it is a standard OS/2 device driver error code, such as unknown_command or invalid_parameter. The DONE bit always is set by the SCSI device driver so that a successful return code is hex 0100 , not 0. At initialization time, the returned status is OR'd with hex FF00 by the kernel. ═══ 22.5. Error Recovery Procedure ═══ The SCSI device driver will not perform any error recovery on the SCSI adapter. The SCSI adapter will not be allocated and, therefore, no error recovery procedure is followed. If a Check Condition is detected, the SCSI device driver will request sense data from the device and return it to the device-specific driver if successful. A return code of hex xx80 indicates that sense data has been returned. ═══ 22.6. Device-Class Driver Model ═══ The device-class driver model is described briefly here to assist in the design of a device-class driver. ═══ 22.6.1. Overview ═══ The device-class driver receives OS/2 request packets from the kernel. It is responsible for mapping the received request to a generic IOCtl request to be passed to the SCSI device driver. When a request from the kernel results in sending a Transfer SCB command to the SCSI driver, the device-class driver allocates the SCB chain header and formats the SCB and the SCB chain header. The TSB also must be allocated. When a request from the kernel results in multiple Transfer SCBs, the device-class driver chains the SCBs and sends only one Transfer SCB command to the SCSI driver. This achieves better performance and guarantees that requests are processed sequentially. The device-class driver calls the SCSI driver to send the request to the device. The SCSI driver returns to the device-class driver after the request is completed. When a Transfer SCB request completes with an error, the SCSI driver performs a Request Sense command to the device to obtain sense data. The sense data is passed back to the caller in the data buffer area of the generic IOCtl request packet. The device-class driver might take some error-recovery steps at this point or return to the kernel, passing the return code from the device. ═══ 22.6.2. Initialization Routine ═══ This routine is called when the device-class driver is first loaded into the system. This routine performs all initialization required for the device-class driver and the device. At Init time, all calls to the SCSI driver are made through the DosDevIoctl interface. Typically, initialization performs the functions in the following list: 1. Performs a return peripheral device count to determine the count of devices attached. 2. Allocates the device. 3. Queries the device to determine whether it is supported. 4. Sets the return code in the request block. 5. Returns the offsets for the end of the code and data segments. ═══ 22.6.3. Strategy Routine ═══ This routine receives requests from the kernel at task time. It builds a generic IOCtl request packet and sends it to the SCSI driver through the IDC entry point. The generic IOCtl request contains the following parameters: o FUNCTION CATEGORY 80h o FUNCTION CODE Represents function to be performed by the SCSI driver. o PARAMETER BUFFER ADDRESS Contains a pointer to the parameters required for the function to be performed. o DATA BUFFER ADDRESS Contains a pointer to the data buffer where returned data is stored. ═══ 22.6.4. Interrupt Handler ═══ An interrupt handler is not required for the device-class driver. All interrupts from the SCSI peripheral devices are handled by the SCSI driver. ═══ 22.6.5. DMA Data Structures ═══ All data structures that will be accessed by the DMA must be locked into memory before calling OS2SCSI.DMD. These data structures include the following: o SCB chain header and SCBs o Scatter/gather list o Scatter/gather data areas o TSB o Sense data area o User data areas. ═══ 22.7. Subsystem Control Blocks ═══ The SCB commands relieve the system of transferring command blocks to the adapter through programmed input and output. The SCB specifies the desired command and associated parameters. An SCB must begin on a doubleword boundary, and any address translations, from virtual to physical, must be performed by system software before the SCB pointer is loaded into the command interface registers. If 80386 virtual page mode is being used, system software must also ensure that the SCB, data buffers, and termination status block (TSB) areas are locked into memory. The SCB specifies the desired command and associated parameters. When the SCB (or chain of SCBs) has been performed by the adapter, an interrupt request is issued to the system. The adapter presents only one interrupt request at a time to the system. The following figure shows the format of the subsystem control block as it applies to device-related commands. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks <---- Command Dependent ---> ND NS C5 C4 C3 C2 C1 C0 Command Word RD ES RE PT 0 SS BB 0 0 0 0 0 0 0 0 CH Enable Word <------------ Least Significant Word --------------> Logical Block <------------ Most Significant Word ---------------> Address <------------ Least Significant Word --------------> System Buffer <------------ Most Significant Word ---------------> Address <------------ Least Significant Word --------------> System Buffer <------------ Most Significant Word ---------------> Byte Count <------------ Least Significant Word --------------> Termination Status <------------ Most Significant Word ---------------> Block Address <------------ Least Significant Word --------------> Optional SCB Chain <------------ Most Significant Word ---------------> Address <------------ Number of Blocks --------------------> Block Count <------------ Block Size --------------------------> Block Length ────────────────────────────────────────────────────────────────────────── A command is encoded in the first word of the SCB. The setting of bits 15 - 8 of the first word depends on the specific command identified in bits 5 - 0. If bit 7 (ND) of this word is set to 1, the adapter will not disconnect the target device during command execution. If bit 6 (NS) of this word is set to 1, the adapter will not send any Synchronous Data Transfer Request messages to the target device. The second word of the SCB is used to enable options that are used to modify a specified command, as shown in the following table. ┌──────┬──────┬──────────────────────────────────────────────────┐ │Bit │Symbol│Function │ ├──────┼──────┼──────────────────────────────────────────────────┤ │15 │RD │Input/Output Control │ ├──────┼──────┼──────────────────────────────────────────────────┤ │14 │ES │Report TSB Status Only on Error │ ├──────┼──────┼──────────────────────────────────────────────────┤ │13 │RE │Retry Enable │ ├──────┼──────┼──────────────────────────────────────────────────┤ │12 │PT │Pointer to List │ ├──────┼──────┼──────────────────────────────────────────────────┤ │10 │SS │Suppress Exception Short │ ├──────┼──────┼──────────────────────────────────────────────────┤ │9 │BB │Bypass Buffer │ ├──────┼──────┼──────────────────────────────────────────────────┤ │8 - 1 │ │Reserved │ ├──────┼──────┼──────────────────────────────────────────────────┤ │0 │CH │Chain on No Error │ ├──────┼──────┼──────────────────────────────────────────────────┤ │ │ │ │ └──────┴──────┴──────────────────────────────────────────────────┘ Bit 15 (RD) When this bit is set to 1, the adapter transfers data from the SCSI device or adapter into system memory (read). When this bit is set to 0, the adapter transfers data from system memory to the SCSI device or adapter (write). Bit 14 (ES) When this bit is set to 1, the TSB is transferred to memory only if an error (Interrupt ID = C) is detected. When this bit is set to 0, the TSB is always transferred. Note: This bit should always be set to 1, unless the command requires the TSB when no error occurs; command performance is degraded by unnecessarily writing to memory. Bit 13 (RE) When this bit is set to 1, the adapter automatically retries certain operations that fail. This bit may be set to 0 by diagnostic programs to enhance fault isolation. Normally, this bit should be set to 1. See Word 1 - Retry Counts for more information. Bit 12 (PT) When this bit is set to 1, it allows a single command to write data to or read data from several different areas in memory (buffers) as specified in a list. This list contains up to 16 pairs of values, each pair being a 32-bit address and its related 32-bit count. In the SCB, the system buffer address field contains the address of the list, and the system buffer byte count field contains the length of the list in bytes. Bit 10 (SS) When this bit is set to 1, it allows the amount of data transferred on a read operation to be shorter than the system buffer byte count, specified in the SCB, without generating an error. Bit 9 (BB) When set to 1, this bit forces the adapter to transfer data directly from the SCSI device and not from a copy in the cache. Some buffer maintenance may still be performed by the adapter. Bits 8 - 1 These bits are reserved. Bit 0 (CH) This bit selects the type of chaining condition used in command block transfers. When it is set to 0, chaining is disabled. When command blocks are chained, the SCB must contain the 32-bit address of the next SCB. When this bit is set to 1, chaining will occur if the SCB ends with no error. ═══ 22.7.1. System Interface ═══ The following is a list of supported SCBS commands. ┌───────────┬──────────────────────────────────────────┬───────┐ │Command │Command │Hex │ │Type │ │Code │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Device Inquiry │0B │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Format Unit │16 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Get Command Complete Status │07 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Read Data │01 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Read Device Capacity │09 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Read Prefetch │31 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Read Verify │03 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Reassign Block │18 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Request Sense │08 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Send Other SCSI Command (SCSI CDB) │1F │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Write Data │02 │ ├───────────┼──────────────────────────────────────────┼───────┤ │SCB │Write with Verify │04 │ └───────────┴──────────────────────────────────────────┴───────┘ Note: The hex code represents bits 5 - 0 of the first command word. The adapter maintains a Command Complete status block for each of the command blocks. The command blocks are updated at the completion of each command. This command status block can be obtained by using the Get Command Complete Status Block command. See Command Complete Status Block. The format for each command is given following the associated command. ═══ 22.7.1.1. Device Inquiry ═══ Through the SCB Device Inquiry command, the system determines which SCSI devices are attached to the adapter, and specific information about those devices. When the Device Inquiry data block has been transferred, the adapter interrupts the system. Because the length of the returned data block is device-dependent, the system should specify the amount of data to be returned. If this is not known, then the system should specify the maximum value (255) and set the suppress short exception (SS) bit to 1. After the Device Inquiry data block is transferred to the specific address, the adapter interrupts the system to indicate that the command is complete. If a SCSI device is not attached at the assigned physical SCSI address, the command-completed-with-failure interrupt will be returned in the Interrupt Status register. The Command Complete status will indicate selection time-out. If the SCSI logical unit number is not supported by an attached SCSI physical unit, the device type in the Device Inquiry data block is set to hex 7F by the SCSI physical device. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 0 1 0 1 1 Device Inquiry 1 ES RE 0 0 SS 1 0 0 0 0 0 0 0 0 CH Enable Word <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Byte Count <---------- Least Significant Word ----------> Termination Status Block <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> Optional SCB Chain <---------- Most Significant Word -----------> Address <---------- Reserved ------------------------> <---------- Reserved ------------------------> ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.2. Device Inquiry Data Block ═══ ────────────────────────────────────────────────────────────────────────── Byte 7 6 5 4 3 2 1 0 Remarks 0 Major Type 1 RMB <- Type Qualifier -> Removable Media Bit 2 <-ECMA-> <-ANSI-> Standards Compliance 3 <------ Reserved ------> 4 <- Additional Length --> # Of Bytes (N-4) - - - - - - - - - - - - - - - - - - - - - - - - - - 5 <-- Additional Data ---> Additional . Inquiry N <-- Additional Data ---> Data ECMA - European Computer Manufacturer's Association ISO - International Standards Organization ────────────────────────────────────────────────────────────────────────── For more information about the Device Inquiry data block, refer to the American National Standards Institute SCSI Standard X3.131-1986. ═══ 22.7.1.3. Format Unit ═══ This SCB command is used to format a storage device. Formatting the storage device destroys all data. The device performs defect management as specified in the command. Bits within the command specify the source of the defect list and the use and disposition of any defect list on the device. Because all device data is considered erased, any cache data for the device is cleared. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 1 0 1 1 0 Format Unit 0 ES RE 0 0 0 1 0 0 0 0 0 0 0 0 CH Enable Word <------ Reserved ----> 0 0 0 FD CL 0 0 0 Modifier Bits <---------- Interleave Factor ----------------> Interleave <---------- Least Significant Word -----------> System Buffer <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> Defect List <---------- Most Significant Word ------------> Byte Count <---------- Least Significant Word -----------> Termination Status <---------- Most Significant Word ------------> Block Address <---------- Least Significant Word -----------> Optional SCB Chain <---------- Most Significant Word ------------> Address <---------- Number of Blocks -----------------> Block Count <---------- Block Size -----------------------> Block Length ────────────────────────────────────────────────────────────────────────── The interleave factor used during the format operation is specified in the control block. An interleave factor of 0 selects the device default. A factor of 1 selects sequential numbering of logical blocks. All other factor values are device dependent. Modifier bits select options to be used during formatting and are defined as follows: FD Format Data: When this modifier bit is set to 1, the system supplies a defect list for the format operation. The structure of the list depends on the device being formatted. The system buffer address points to the defect list; the length is specified in the byte count. If this bit is set to 0, no defect list is transferred to the device. Note: Not all SCSI devices support the transfer of a defect list. CL Complete List: If the defect list is supplied, this bit determines whether the supplied defect list is in addition to, or replaces, the defect list already in the device. If the bit is set to 1, any previous defect list is replaced. Note: Only a defect list in the following block format is supported by the adapter. See the ANSI SCSI Standard or specific device specification for more information. ────────────────────────────────────────────────────────────────────────── Defect List Header Byte 7 6 5 4 3 2 1 0 Remarks 0 <----- Reserved -----> 1 <----- Reserved -BF--> 2 <----- High Byte ----> 3 <----- Low Byte -----> Defect Descriptors 4 <----- High Byte ----> First 5 <--------------------> Defective Block 6 <--------------------> Address 7 <----- Low Byte -----> . . . <----- High Byte ----> Last <--------------------> Defective Block <--------------------> Address N <----- Low Byte -----> ────────────────────────────────────────────────────────────────────────── BF Background Format: When this bit is set to 1, the device performs a background format. If the device supports this option, it checks the format of the command, then returns a command status indicating good status, and starts the format operation. If the device does not support the option, it may return a command status block indicating a check condition. Commands received before completing the background format are returned with a command status block indicating a check condition. The Request Sense command returns a sense key indicating that the device is not ready and returns an additional sense code indicating that a Format operation is in progress. The Request Sense data block also shows the percentage of the format completed. ═══ 22.7.1.4. Get Command Complete Status ═══ This SCB command requests the Command Complete status block for the last command executed on a specified device. When the status block is transferred to the system, the adapter generates an interrupt and updates the Interrupt Status register. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 0 0 0 0 0 1 1 1 Get Command Status 1 ES RE 0 0 0 1 0 0 0 0 0 0 0 0 CH Enable Word <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Address 0 0 0 0 0 0 0 0 0 0 0 1 1 0 1 0 System Buffer 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Byte Count <---------- Least Significant Word ----------> Termination Status Block <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> Optional SCB Chain <---------- Most Significant Word -----------> Address <---------- Reserved ------------------------> <---------- Reserved ------------------------> ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.5. Command Complete Status Block ═══ The command complete status block is returned to the location specified in the system buffer address field of the Get Command Complete Status command. It contains the status of the last command to a device. It is unchanged until another command is issued to that device or until a reset occurs. An optional termination status block is returned automatically whenever an error occurs. This allows command complete status to be returned for error recovery. The command complete status block and termination status block contain the same information. ────────────────────────────────────────────────────────────────────────── Word 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 <---------- SCB End Status Word --------------> SCB Status 1 <---------- Retry Counts ---------------------> Retry Counts 2 <---------- Least Significant Word -----------> Residual Byte 3 <---------- Most Significant Word ------------> Count 4 <---------- Least Significant Word------------> Scatter/Gather List 5 <---------- Most Significant Word ------------> Element Address 6 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 Device Dependent Status Length 7 <-- Command Status --><---- Device Status ----> Command Device Status 8 <-- Command Error ---><---- Device Error -----> Error Codes 9 <---------- Reserved -------------------------> A <---------- Cache Information Word -----------> B <---------- Least Significant Word -----------> Last SCB Address C <---------- Most Significant Word ------------> Processed ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.5.1. Word 0 - Subsystem Control Block End Status ═══ ┌──────────┬──────────────────────────────────────────────────┐ │Bit │Function │ ├──────────┼──────────────────────────────────────────────────┤ │15 - 13 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │12 │Major Exception Occurred │ ├──────────┼──────────────────────────────────────────────────┤ │11 │Device Not Initialized │ ├──────────┼──────────────────────────────────────────────────┤ │10 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │ 9 │Device Dependent Status Available │ ├──────────┼──────────────────────────────────────────────────┤ │ 8 │Additional Status Available │ ├──────────┼──────────────────────────────────────────────────┤ │ 7 │SCB Interrupt Queued │ ├──────────┼──────────────────────────────────────────────────┤ │ 6 │SCB Halted (Error/End Chain) │ ├──────────┼──────────────────────────────────────────────────┤ │ 5 │Long Record Exception │ ├──────────┼──────────────────────────────────────────────────┤ │ 4 │SCB Specification Check │ ├──────────┼──────────────────────────────────────────────────┤ │ 3 │SCB Rejected │ ├──────────┼──────────────────────────────────────────────────┤ │ 2 │Invalid Command Rejected │ ├──────────┼──────────────────────────────────────────────────┤ │ 1 │Short Record Exception │ ├──────────┼──────────────────────────────────────────────────┤ │ 0 │SCB Ended (No Error) │ └──────────┴──────────────────────────────────────────────────┘ Note: The function indicated is true when the value of the bit is one. Reserved bits are undefined. ═══ 22.7.1.5.2. Word 1 - Retry Counts ═══ ┌──────────┬──────────────────────────────────────────────────┐ │Bit │Function │ ├──────────┼──────────────────────────────────────────────────┤ │15 │Adapter Retry Invoked │ ├──────────┼──────────────────────────────────────────────────┤ │14 - 6 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │5 │System Interface Check Retry │ ├──────────┼──────────────────────────────────────────────────┤ │4 - 0 │Reserved │ └──────────┴──────────────────────────────────────────────────┘ ═══ 22.7.1.5.3. Words 2 and 3 - Residual Byte Count ═══ These words contain the number of bytes that were not transferred. ═══ 22.7.1.5.4. Words 4 and 5 - Scatter/Gather List Element Address ═══ These words contain the address of the scatter/gather list element being used when the command was ended. ═══ 22.7.1.5.5. Word 6 - Device Dependent Status Length ═══ This word contains the number of bytes of device status information that follow. This word is set to hex 0C to indicate 12 bytes. ═══ 22.7.1.5.6. Word 7 - Command and Device Status ═══ The following table describes command status codes. ┌──────────┬──────────────────────────────────────────────────┐ │Hex │Command Status │ ├──────────┼──────────────────────────────────────────────────┤ │1 │SCB Command Completed with Success │ ├──────────┼──────────────────────────────────────────────────┤ │5 │SCB Command Completed with Success after Retries │ ├──────────┼──────────────────────────────────────────────────┤ │7 │Adapter Hardware Failure │ ├──────────┼──────────────────────────────────────────────────┤ │A │Immediate Command Completed │ ├──────────┼──────────────────────────────────────────────────┤ │C │Command Completed with Failure │ ├──────────┼──────────────────────────────────────────────────┤ │E │Command Error (Invalid Command or Parameter) │ ├──────────┼──────────────────────────────────────────────────┤ │F │Software Sequencing Error │ └──────────┴──────────────────────────────────────────────────┘ Note: All values not shown are reserved. The following table describes device status bytes. ┌──────────┬──────────────────────────────────────────────────┐ │Bit │Function │ ├──────────┼──────────────────────────────────────────────────┤ │7 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │6 │Vendor Unique Bit │ ├──────────┼──────────────────────────────────────────────────┤ │5 │Vendor Unique Bit │ ├──────────┼──────────────────────────────────────────────────┤ │4 - 1 │Device Status Code │ ├──────────┼──────────────────────────────────────────────────┤ │0 │Vendor Unique Bit │ └──────────┴──────────────────────────────────────────────────┘ The following table describes bytes 4-1 device status code. ┌──────────┬──────────────────────────────────────────────────┐ │Hex │Device Status │ ├──────────┼──────────────────────────────────────────────────┤ │0 │Good Status (No Error) │ ├──────────┼──────────────────────────────────────────────────┤ │1 │Check Condition (Error) │ ├──────────┼──────────────────────────────────────────────────┤ │2 │Condition Met/Good (No Error) │ ├──────────┼──────────────────────────────────────────────────┤ │4 │Busy (Error) │ ├──────────┼──────────────────────────────────────────────────┤ │8 │Intermediate/Good (No Error) │ ├──────────┼──────────────────────────────────────────────────┤ │A │Intermediate/Condition Met/Good (No Error) │ ├──────────┼──────────────────────────────────────────────────┤ │C │Reservation Conflict (Error) │ └──────────┴──────────────────────────────────────────────────┘ Note: All values not shown are reserved. ═══ 22.7.1.5.7. Word 8 - Command Error Code/Device Error Code ═══ The following table describes bits 15-8 command error codes. ┌──────────┬──────────────────────────────────────────────────┐ │Hex │Error │ ├──────────┼──────────────────────────────────────────────────┤ │00 │No Error │ ├──────────┼──────────────────────────────────────────────────┤ │01 │Invalid Parameter in SCB │ ├──────────┼──────────────────────────────────────────────────┤ │02 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │03 │Command Not Supported │ ├──────────┼──────────────────────────────────────────────────┤ │04 │Command Aborted (By System) │ ├──────────┼──────────────────────────────────────────────────┤ │05 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │06 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │07 │Format Rejected - Sequence Error │ ├──────────┼──────────────────────────────────────────────────┤ │08 │Assign Rejected - Command in Progress on Device │ ├──────────┼──────────────────────────────────────────────────┤ │09 │Assign Rejected - SCSI Device Already Assigned │ ├──────────┼──────────────────────────────────────────────────┤ │0A │Command Rejected - SCSI Device Not Assigned │ ├──────────┼──────────────────────────────────────────────────┤ │OB │Maximum Logical Block Address Exceeded │ ├──────────┼──────────────────────────────────────────────────┤ │OC │16-Bit Card Slot Address Range Exceeded. │ ├──────────┼──────────────────────────────────────────────────┤ │0D - 12 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │13 │Invalid Device for Command │ ├──────────┼──────────────────────────────────────────────────┤ │14 - 1F │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │20 │Adapter Hardware Error │ ├──────────┼──────────────────────────────────────────────────┤ │21 │Global Command Time-out │ ├──────────┼──────────────────────────────────────────────────┤ │22 │DMA Error │ ├──────────┼──────────────────────────────────────────────────┤ │23 │Adapter Buffer Defective │ ├──────────┼──────────────────────────────────────────────────┤ │24 │Command Aborted by Adapter │ ├──────────┼──────────────────────────────────────────────────┤ │25 - 7F │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │80 │Adapter Microprocessor Detected Error │ ├──────────┼──────────────────────────────────────────────────┤ │81 - FF │Reserved │ └──────────┴──────────────────────────────────────────────────┘ The following table describes bits 7-0 device error codes. ┌──────────┬──────────────────────────────────────────────────┐ │Hex │Error │ ├──────────┼──────────────────────────────────────────────────┤ │00 │No Error │ ├──────────┼──────────────────────────────────────────────────┤ │01 │SCSI Bus Reset Occurred │ ├──────────┼──────────────────────────────────────────────────┤ │02 │SCSI Interface Fault │ ├──────────┼──────────────────────────────────────────────────┤ │03 - 0F │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │10 │SCSI Selection Time-out (device not available) │ ├──────────┼──────────────────────────────────────────────────┤ │11 │Unexpected SCSI Bus Free │ ├──────────┼──────────────────────────────────────────────────┤ │12 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │13 │Invalid SCSI Phase Sequence │ ├──────────┼──────────────────────────────────────────────────┤ │14 - 1F │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │20 │Short Length Record │ ├──────────┼──────────────────────────────────────────────────┤ │21 - FF │Reserved │ └──────────┴──────────────────────────────────────────────────┘ ═══ 22.7.1.5.8. Word 9 - Reserved ═══ ═══ 22.7.1.5.9. Word A - Cache Information Word ═══ Bits 7 - 0 are the cache-read hit ratio (expressed as a percentage in a binary coded decimal format). The following table describes cache-read hit rations. ┌──────────┬──────────────────────────────────────────────────┐ │Hex │Percent │ ├──────────┼──────────────────────────────────────────────────┤ │00 - 99 │00% - 99% │ ├──────────┼──────────────────────────────────────────────────┤ │A0 │100% │ └──────────┴──────────────────────────────────────────────────┘ The following table describes bits 15-8 cache statuses. ┌──────────┬──────────────────────────────────────────────────┐ │Bit │Function │ ├──────────┼──────────────────────────────────────────────────┤ │15 - 12 │Reserved │ ├──────────┼──────────────────────────────────────────────────┤ │11 │Cache Enabled │ ├──────────┼──────────────────────────────────────────────────┤ │10 │Cache Retry Occurred │ ├──────────┼──────────────────────────────────────────────────┤ │9 │Total Write Hit │ ├──────────┼──────────────────────────────────────────────────┤ │8 │Total Read Hit │ └──────────┴──────────────────────────────────────────────────┘ ═══ 22.7.1.5.10. Word B - Last SCB Address Processed - Low Word ═══ ═══ 22.7.1.5.11. Word C - Last SCB Address Processed - High Word ═══ ═══ 22.7.1.6. Read Data ═══ This SCB command is used for devices with fixed length blocks, such as fixed disk drives. This command causes the adapter to send the SCSI Read command to the device. The blocks specified are read and the data is transferred to the system. The Read Data command supports multiple block operations up to 65,535 blocks or 16MB minus 1 byte (MB = 1,048,576 bytes), whichever is less, of total data transferred. For devices with variable length blocks, such as tape drives, the Send Other SCSI SCB command should be used to generate the SCSI Read command. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 0 0 0 0 1 Read Data 1 ES RE PT 0 0 BB 0 0 0 0 0 0 0 0 CH Enable Word <---------- Least Significant Word ----------> Logical <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Byte Count <---------- Least Significant Word ----------> Termination Status Block <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> Optional SCB Chain <---------- Most Significant Word -----------> Address <---------- Number of Blocks ----------------> Block Count <---------- Block Size ----------------------> Block Length ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.7. Read Device Capacity ═══ This SCB command is used to return the Device Capacity status block of the specific device. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 0 1 0 0 1 Read Device Capacity 1 ES RE 0 0 0 1 0 0 0 0 0 0 0 0 CH Enable Word <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Address 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 System Buffer 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Byte Count <---------- Least Significant Word ----------> Termination Status Block <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> Optional SCB Chain <---------- Most Significant Word -----------> Address <---------- Reserved ------------------------> <---------- Reserved ------------------------> ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.8. Device Capacity Data Block ═══ ────────────────────────────────────────────────────────────────────────── Byte 7 6 5 4 3 2 1 0 Remarks 0 <----- High Byte ------> 1 <----------------------> Last Logical 2 <----------------------> Block Address 3 <----- Low Byte -------> 4 <----- High Byte ------> 5 <----------------------> Block 6 <----------------------> Length 7 <----- Low Byte -------> ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.9. Read Prefetch ═══ For this SCB command, the blocks specified are read and the data is transferred into the on-card disk cache for later access by a Read Data command. The block length specified must be 512 bytes and the block count must be less than or equal to 17 for the command to transfer data into the cache. If other values are specified, the command is treated as a no-operation. This command is supported only by the cached adapter. The non-cached adapter will reject this command with a Command Error Interrupt ID. The presence of a cached adapter can be determined by bit 11 of the Cache Information word in the Command Complete Status Block. If this bit is set to 1, the adapter has a cache. Otherwise, no cache is present. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 1 1 0 0 0 1 Read Prefetch 1 ES RE 0 0 0 1 0 0 0 0 0 0 0 0 CH Enable Word <---------- Least Significant Word ----------> Logical Block <---------- Most Significant Word -----------> Address <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Least Significant Word ----------> Termination Status Block <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> Optional SCB Chain <---------- Most Significant Word -----------> Address <---------- Number of Blocks ----------------> Block Count <---------- Block Size ----------------------> Block Length ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.10. Read Verify ═══ This SCB command reads the specified blocks of data and checks for errors. Data is not transferred by this command; it serves to verify the readability of the data and the correct operation of the device. This command is used for devices with fixed length blocks, such as fixed disk drives. This command causes the adapter to send the SCSI Read and Verify commands to the device. The blocks specified are read and the data is transferred to the system. The Read Verify command supports multiple block operations up to 65,535 blocks or 16MB minus 1 byte (MB = 1,048,576 bytes), whichever is less, of total data transferred. For devices with variable length blocks, such as tape drives, the Send Other SCSI SCB command should be used to generate the SCSI Read and Verify commands. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 0 0 0 1 1 Read Verify 1 ES RE 0 0 0 1 0 0 0 0 0 0 0 0 CH Enable Word <---------- Least Significant Word ----------> Logical Block <---------- Most Significant Word -----------> Address <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Least Significant Word ----------> Termination Status Block <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> Optional SCB Chain <---------- Most Significant Word -----------> Address <---------- Number of Blocks ----------------> Block Count <---------- Block Size ----------------------> Block Length ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.11. Reassign Block ═══ This SCB command reassigns the logical block address for a defective block to a spare block. The system supplies the reassign block defect list. The system buffer address in the command block serves as a pointer to the defect list. Because the device data is considered erased by a Reassign Block command, the cache automatically clears any data from the device having a block reassigned. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 0 0 0 1 1 0 0 0 Reassign Block 0 ES RE 0 0 0 1 0 0 0 0 0 0 0 0 CH Enable Word <--------- Reserved -------------------------> <--------- Reserved -------------------------> <--------- Least Significant Word -----------> System Buffer <--------- Most Significant Word ------------> Address <--------- Least Significant Word -----------> System Buffer <--------- Most Significant Word ------------> Byte Count <--------- Least Significant Word -----------> Termination Status Block <----------Most Significant Word ------------> Address <--------- Least Significant Word -----------> Optional SCB Chain <--------- Most Significant Word ------------> Address <--------- Reserved -------------------------> <--------- Reserved -------------------------> ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.12. Reassign Block Defect List ═══ ────────────────────────────────────────────────────────────────────────── Defect List Header Byte 7 6 5 4 3 2 1 0 Remarks 0 <----- Reserved -----> 1 <----- Reserved -----> 2 <----- High Byte ----> Defect List 3 <----- Low Byte -----> Length Defect Descriptors 4 <----- High Byte ----> 5 <--------------------> Defective Logical 6 <--------------------> Block 7 <----- Low Byte -----> Address ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.13. Request Sense ═══ This SCB command is used to return the sense data for the specified device. The adapter interrupts the system when the Sense data block is transferred. The length of the data block depends on the device and can be four bytes (non-extended) or more (extended). The format of the data block for both cases is shown. The system should specify the amount of data to be returned in the SCB based on the particular device attached, or specify the maximum value (255) and set the suppress short exception (SS) bit to 1. The sense data is valid only if a Check Condition status was returned for the previous command to the device. The sense data provides additional information on the check condition. Refer to the ANSI SCSI publication or the particular SCSI device specification for detailed information about the Request Sense data block. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 0 1 0 0 0 Request Sense 1 ES RE 0 0 SS 1 0 0 0 0 0 0 0 0 CH Enable Word <---------- Reserved ------------------------> <---------- Reserved ------------------------> <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> System Buffer <---------- Most Significant Word -----------> Byte Count <---------- Least Significant Word ----------> Termination Status Block <---------- Most Significant Word -----------> Address <---------- Least Significant Word ----------> Optional SCB Chain <---------- Most Significant Word -----------> Address <---------- Reserved ------------------------> <---------- Reserved ------------------------> ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.14. Sense Data Block ═══ ────────────────────────────────────────────────────────────────────────── Byte Sense Bits 7 6 5 4 3 2 1 0 Remarks 0 AV <- Code -> Error Class/Code 1 X X X < High Byte > Logical 2 <--------------------> Block 3 <----- Low Byte -----> Address ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.14.1. Byte 0 Error Class/Error Code ═══ Bit 7 Address Valid: When this bit is set to 1, the logical block address field is valid. Bits 6 - 4 Error Class: When the error class is 0, the sense data block is in the format shown above. When the error class is 7, the sense data block is in the extended format, shown on the following page. All other settings are device dependent. Bits 3 - 0 Error Code: Errors are device dependent. ═══ 22.7.1.14.2. Bytes 1 - 3 Logical Block Address ═══ This address is device dependent. Note: The adapter does not examine or use device-dependent information. ═══ 22.7.1.15. Extended Sense Data Block ═══ ────────────────────────────────────────────────────────────────────────── Byte Sense Bits 7 6 5 4 3 2 1 0 Remarks 0 V 1 1 1 <-- Code --> Error Class/Code 1 <----- Segment # -----> Segment Number 2 FM EM IL X <-- Key --> Sense Key 3 <- Most Significant --> Information Bytes 4 <---------------------> 5 <---------------------> 6 <- Least Significant -> 7 <--Additional Length--> # of Bytes 8 <--Additional Sense --> Additional . Sense . N <--Additional Sense---> Bytes ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.15.1. Byte 0 Error Class/Error Code ═══ Bit 7 The Information bytes are valid only if this bit is a 1. Bits 6 - 4 Error class 7 is for extended sense data. Bits 3 - 0 Error code 0 is standard format. Error codes hex 1 - E are reserved. Error code hex F is device dependent. ═══ 22.7.1.15.2. Byte 1 Segment Number ═══ This byte contains the current segment descriptor. ═══ 22.7.1.15.3. Byte 2 Extended Error Bits/Sense Key ═══ Bit 7 A filemark (FM) has been reached on a sequential access device. Bit 6 An end of medium (EM) has been reached on a sequential access device. Bit 5 An Invalid Length (IL) resulted when the specified logical block length did not match the device. Bit 4 X - This bit is reserved. Bits 3 - 0 The coding of these bits is shown in the following table. ┌────────────┬────────────────────────────────────────────────┐ │Hex Value │Function │ ├────────────┼────────────────────────────────────────────────┤ │0 │No Sense │ ├────────────┼────────────────────────────────────────────────┤ │1 │Recovered Error │ ├────────────┼────────────────────────────────────────────────┤ │2 │Not Ready │ ├────────────┼────────────────────────────────────────────────┤ │3 │Medium Error │ ├────────────┼────────────────────────────────────────────────┤ │4 │Hardware Error │ ├────────────┼────────────────────────────────────────────────┤ │5 │Illegal Request │ ├────────────┼────────────────────────────────────────────────┤ │6 │Unit Attention │ ├────────────┼────────────────────────────────────────────────┤ │7 │Data Protect │ ├────────────┼────────────────────────────────────────────────┤ │8 │Blank Check │ ├────────────┼────────────────────────────────────────────────┤ │9 │Device Dependent │ ├────────────┼────────────────────────────────────────────────┤ │A │Copy Aborted │ ├────────────┼────────────────────────────────────────────────┤ │B │Aborted Command │ ├────────────┼────────────────────────────────────────────────┤ │C │Equal │ ├────────────┼────────────────────────────────────────────────┤ │D │Volume Overflow │ ├────────────┼────────────────────────────────────────────────┤ │E │Miscompare │ ├────────────┼────────────────────────────────────────────────┤ │F │Reserved │ └────────────┴────────────────────────────────────────────────┘ Bytes 3 - N Device-Dependent Status: Refer to the particular device specifications for a definition of these bytes. Note: The adapter does not examine or use device-dependent information. ═══ 22.7.1.16. Send Other SCSI Command (SCSI CDB) ═══ This SCB command is used to send any SCSI command not supported by the adapter directly to a SCSI device. The command to be issued is placed at the end of the SCB. When commands are issued directly to a device using this command, messages are handled by the adapter. Data transfer direction is controlled by the read-option bit (RD) in the Enable word. When this bit is set to 1, the adapter transfers data to the system from the device. When the read-option bit is set to 0, the adapter transfers data to the device from the system. If the system-buffer byte count specified in the SCB is 0, no data is transferred. Because device data can be altered by this command, the cache is automatically cleared of any data from that device. Note: This command should be used only when other commands cannot perform the operation; otherwise, performance of the SCSI subsystem can be impacted. This command should be issued only to logical device numbers 0 to 14. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 1 0 0 1 0 0 ND NS 0 1 1 1 1 1 Send Other SCSI Command RD ES RE PT 0 SS 1 0 0 0 0 0 0 0 0 CH Enable Word <------ Reserved -----><-- SCSI CMD Length ---> <---------- Reserved -------------------------> <---------- Least Significant Word -----------> System Buffer <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> System Buffer <---------- Most Significant Word ------------> Byte Count <---------- Least Significant Word -----------> Termination Status Block <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> Optional SCB Chain <---------- Most Significant Word ------------> Address <-------1------- SCSI Command -------0--------> SCSI Command <-------3------- SCSI Command -------2--------> <-------5------- SCSI Command -------4--------> Six Bytes or <-------7------- SCSI Command -------6--------> <-------9------- SCSI Command -------8--------> Ten Bytes or <------11------- SCSI Command ------10--------> Twelve Bytes ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.17. Write Data ═══ This SCB command writes data from the system to the device in consecutive blocks. This command is used for devices with fixed length blocks, such as fixed disk drives. This command causes the adapter to send the SCSI Write command to the device. The blocks specified are read and the data is transferred to the system. No verification is performed. The Read Data command supports multiple block operations up to 65,535 blocks or 16MB minus 1 byte (MB = 1,048,576 bytes), whichever is less, of total data transferred. For devices with variable length blocks, such as tape drives, the Send Other SCSI SCB command should be used to generate the SCSI Write command. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 0 0 0 1 0 Write Data 0 ES RE PT 0 0 BB 0 0 0 0 0 0 0 0 CH Enable Word <---------- Least Significant Word -----------> Logical Block <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> System Buffer <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> System Buffer <---------- Most Significant Word ------------> Byte Count <---------- Least Significant Word -----------> Termination Status Block <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> Optional SCB Chain <---------- Most Significant Word ------------> Address <---------- Number of Blocks -----------------> Block Count <---------- Block Size -----------------------> Block Length ────────────────────────────────────────────────────────────────────────── ═══ 22.7.1.18. Write with Verify ═══ This SCB command is similar to Write Data, except that a Read Verify command is performed after all blocks are written. This command is used for devices with fixed length blocks, such as fixed disk drives. This command causes the adapter to send the SCSI Write and Verify commands to the device. The blocks specified are read and the data is transferred to the system. The Write with Verify command supports multiple block operations up to 65 535 blocks or 16MB minus 1 byte (MB = 1,048,576 bytes), whichever is less, of total data transferred. If an error occurs during a Write with Verify command, the system should retry the command. If all retries of the command fail, the system can allocate a spare block to replace the failing one through the Reassign Block command, and then reissue the command. For devices with variable length blocks, such as tape drives, the Send Other SCSI SCB command should be used to generate the SCSI Write and Verify commands. ────────────────────────────────────────────────────────────────────────── 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Remarks 0 0 0 1 1 1 0 0 ND NS 0 0 0 1 0 0 Write Verify 0 ES RE PT 0 0 BB 0 0 0 0 0 0 0 0 CH Enable Word <---------- Least Significant Word -----------> Logical Block <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> System Buffer <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> System Buffer <---------- Most Significant Word ------------> Byte Count <---------- Least Significant Word -----------> Termination Status Block <---------- Most Significant Word ------------> Address <---------- Least Significant Word -----------> Optional SCB Chain <---------- Most Significant Word ------------> Address <---------- Number of Blocks -----------------> Block Count <---------- Block Size -----------------------> Block Length ────────────────────────────────────────────────────────────────────────── ═══ 23. Advanced SCSI Programming Interface (ASPI) OS/2 Specification ═══ This chapter describes the function of ASPI, gives an overview of the steps involved in programming ASPI for OS/2, and discusses the SCSI request block and ASPI command codes executed by the ASPI manager. ═══ 23.1. Introduction to ASPI ═══ ASPI is an application interface that allows easier access to SCSI devices. When running DOS, users typically load an ASPI manager that routes all requests directly to the hardware. ASPI drivers (such as ASPIDISK and ASPICD) send requests to the ASPI manager, which then sends the command to the appropriate device. The device driver model used by OS/2 is layered (similar to ASPI) so that an adapter device driver (ADD) is responsible for knowing about the hardware dependencies of a particular SCSI adapter. Applications that want to send ASPI requests do so by routing these requests to a device manager (OS2ASPI.DMD) and then converts them into requests recognizable to any ADD. The ASPI support currently embedded within OS/2 2.x allows any OS/2 application to send commands to a SCSI device. However, there are a large number of DOS and Windows applications that could be supported if the commands were routed to OS2ASPI.DMD. VASPI.SYS is a virtual device driver that allows DOS applications to issue SCSI commands that will be handled by OS2ASPI.DMD. If you have an existing DOS or Windows ASPI application, it should now be able to run in a virtual DOS session under OS/2 2.x. ═══ 23.2. Accessing ASPI ═══ Device drivers that need to access ASPIN, must determine the address of the ASPI entry point through an OS/2 Attach DevHelp call as follows: SCSIMGR$ DB 'SCSIMGR$',0 Return_Data_Buffer DB 12 DUP (?) MOV BX,OFFSET SCSIMGR MOV DI,OFFSET Return_Data_Buffer MOV DL,DevHlp_AttachDD CALL [DevHlp] On return from the Attach DevHelp call, a clear-carry flag indicates that the SCSI manager SCSIMGR$ was found and the return data is valid. A set-carry flag indicates that the SCSI manager was not found. The return data buffer has the following format: ASPI_Real DW Real Mode offset of ASPI entry point DW Real Mode CS segment of ASPI entry point Real_DS DW Real Mode DS of ASPI entry point ASPI_Prot DW Protected Mode offset of ASPI entry point DW Protected Mode CS selector of ASPI entry point Prot_DS DW Protected Mode DS of ASPI entry point Note: ASPI_Real and Real_DS are used by OS/2 1.x only. Information returned under OS/2 2.x is irrelevant. ═══ 23.2.1. Calling ASPI ═══ When the ASPI entry-point parameters have been successfully determined, calling ASPI uses the values appropriate to the mode of the processor. The address of the ASPI request block and the DS of the ASPI entry point must be pushed onto the stack before making a FAR call. The following is an example of how to call ASPI: PUSH AX ;Save AX PUSH @ASPI_SRB ;Push pointer to ASPI SRB SMSW AX ;Check mode of processor TEST AX,PROTECT_MODE JNZ PROT_CALL PUSH Real_DS CALL [ASPI_REAL] JMP CALL_DONE PROT_CALL: PUSH Prot_DS CALL [ASPI_PROT] CALL_DONE: ADD SP,6 ;Restore the stack POP AX ═══ 23.2.2. Accessing ASPI At Initialization Time ═══ At initialization time, an OS/2 device driver lacks the privilege level for making a FAR call to the ASPI interface. To circumvent this restriction, the SCSI manager provides a special IOCtl which can be used by a driver to pass an ASPI request. To use the IOCtl, the driver must first use a DosOpen call to get a file handle for the SCSI manager. Having completed this successfully, the driver can call ASPI at initialization time as follows: PUSH @DATA_BUFFER ;Not Applicable PUSH @REQUEST_BLOCK ;Parameter List = SRB PUSH 40H ;Function Code PUSH 80H ;Function Category PUSH ASPI_Handle ;File handle from DosOpen CALL DOSDEVIOCTL When the driver has returned from initialization, this access method is no longer valid. ═══ 23.2.3. ASPI and OS/2 2.x ═══ The device driver architecture for OS/2 2.x is divided into several basic layers. The Device Manager Drivers (DMD) receive requests from the file systems and other device drivers. These requests are passed on to an Adapter Device Driver (ADD), which then sends the appropriate command to the host adapter. ASPI for OS/2 2.x is a translation layer, and has been implemented as a device driver (OS2ASPI.DMD). An application can send SRBs to any SCSI adapter which has an ADD installed. It is no longer possible to set host adapter parameters because OS2ASPI has no direct control over the host adapter. ═══ 23.2.4. Target Allocation With OS/2 2.x ═══ The device driver architecture for OS/2 2.x is structured so that targets controlled by an ADD must be allocated to an individual (DMD). For example, when the system boots, OS2DASD.DMD is usually the first device manager loaded, and it automatically searches for all available hard drives and permanently allocates them for use by the file systems. Other DMDs usually do something similar with targets that they assume should be controlled by them. The standard method for preventing a DMD from allocating a particular target is through the use of command line switches on the ADD that handles the device. If you are planning to use ASPI to control a device that may be allocated by a DMD that loads before OS2ASPI.DMD, be sure to specify that the device manager in question is not allowed access to it. o If you are writing an ASPI application for a magneto-optical drive (target 6 on an AHA-1540) that returns device type 0 (DASD) in the Inquiry data, you must be sure to prevent OS2DASD from accessing it by adding the parameter /!DM6 to disable ID 6. See the following example: BASEDEV=AHA154X.ADD /A:0 /!DM:6 o If you are writing an ASPI application for a device that also may be controlled by a device driver through os2scsi.dmd (target 6 on an AHA-1540), you can also prevent OS2SCSI from accessing it by adding the parameter /!SM6 for ID 6. See the following example: BASEDEV=AHA154X.ADD /A:0 /!SM:6 Currently, only OS2DASD.DMD and OS2SCSI.DMD can be controlled in this manner because they are the only DMDs to be mentioned in IBM's specification for ADDs. For a complete explanation of command line switches supported by the ADD that are provided with OS/2 2.1, search for SCSI in the OS/2 Command Line Reference. Device managers can handle allocations in one of two ways: wait for a device driver to issue an allocation request (OS2SCSI.DMD performs this) or permanently allocate the device during system boot (OS2DASD.DMD and OS2CDROM.DMD perform this function). Typically, OS2ASPI will not allocate a device until the first execute I/O command is issued. This command allows it to scan for devices and not interfere with them until an application decides to issue a command. However, once this allocation takes place, OS2ASPI will not release the device because it can never be sure when the application is finished with it. O2ASPI.DMD can be used without any command line switches, but there are usually two situations that can arise that OS2ASPI must address: o A user wants to utilize two applications by way of different interfaces (such as OS2ASPI and OS2SCSI) and both need to access the device. In this case, if the application using OS2SCSI is well-behaved, it will release the device when it is finished and OS2ASPI will be able to allocate it. If OS2ASPI does not release the device, the OS2SCSI application will not be able to access the device until the system is rebooted and the device allocation information is reset. o A user wants to access a device that has been permanently allocated by another device manager, such as a diagnostic that reports information about the system configuration. However, if the devices are allocated to another manager, the application will never be able to see them. The previous two problems can be solved by the use of optional command line switches such as the following: /ALL - This switch instructs OS2ASPI.DMD to allow commands to be issued to ANY device on the SCSI bus, even those allocated by other managers. Warning: Commands should be issued to devices under the control of other managers with extreme caution. If you are using the /ALL switch and plan to issue commands to devices that are shared with another manager, try and limit them to non-destructive commands such as Inquiry and Test Unity Ready. /SHARE - This switch instructs OS2ASPI.DMD to release any target after each command, allowing multiple managers to access a target at different times. Because this requires more commands to be issued to the driver, there will be a slight performance penalty when this switch is used. Warning: When sharing devices and sending multiple concurrent requests, it is possible that allocation/deallocation of the device will cause a command to be rejected. This switch is best suited for use when you have applications that require different managers, but will not be used simultaneously. BASEDEV=OS2ASPI.DMD /SHARE BASEDEV=OS2ASPI.DMD /ALL ═══ 23.3. SCSI Request Block (SRB) ═══ A SCSI Request Block (SRB) contains the command to be executed by the ASPI manager and is used by both drivers and application programs. An SRB consists of an SRB header followed by additional fields dependent on the command code. All request blocks have an 8-byte header. ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Offset │# Bytes │Description │R/W* │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │00h (00) │01h (01) │Command Code │W │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │01h (01) │01h (01) │Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │02h (02) │01h (01) │Host Adapter │W │ │ │ │Number │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │03h (03) │01h (01) │SCSI Request │W │ │ │ │Flags │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │04h (04) │04h (04) │Reserved for │- │ │ │ │Expansion = 0 │ │ └───────────────┴───────────────┴───────────────┴───────────────┘ *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (-). Command Code: The Command Code field indicates which of the ASPI services is being accessed. Refer to ASPI Command Codes. Status: The Status Byte field is used to post the status of the command. Refer to ASPI Status Bytes. Host Adapter Number: The Host Adapter Number field specifies which installed host adapter the request is intended for. Host adapter numbers are always assigned by the SCSI manager layer beginning with zero. SCSI Request Flags: The SCSI Request Flags field definition is command-code specific. Reserved for Expansion: The last four bytes of the header are reserved and must be zero. ═══ 23.3.1. ASPI Command Codes ═══ The ASPI Command Codes, including valid ASPI command codes and ASPI status bytes and their descriptions are given as follows. ═══ 23.3.1.1. Valid ASPI Command Codes ═══ ┌──────────────────────────────┬──────────────────────────────┐ │Command Code │Description │ ├──────────────────────────────┼──────────────────────────────┤ │00h │Host Adapter Inquiry │ ├──────────────────────────────┼──────────────────────────────┤ │01h │Get Device Type │ ├──────────────────────────────┼──────────────────────────────┤ │02h │Execute SCSI I/O Command │ ├──────────────────────────────┼──────────────────────────────┤ │03h │Abort SCSI I/O Command │ ├──────────────────────────────┼──────────────────────────────┤ │04h │Reset SCSI Device │ ├──────────────────────────────┼──────────────────────────────┤ │05h │Set Host Adapter Parameters │ ├──────────────────────────────┼──────────────────────────────┤ │06h-7Fh │Reserved for Future Expansion │ ├──────────────────────────────┼──────────────────────────────┤ │80h-FFh │Reserved for Vendor Unique │ └──────────────────────────────┴──────────────────────────────┘ ═══ 23.3.2. ASPI Status Bytes ═══ ┌──────────────────────────────┬──────────────────────────────┐ │Status Byte │Description │ ├──────────────────────────────┼──────────────────────────────┤ │00h │SCSI Request In Progress │ ├──────────────────────────────┼──────────────────────────────┤ │01h │SCSI Request Completed Without│ │ │Error │ ├──────────────────────────────┼──────────────────────────────┤ │02h │SCSI Request Aborted By Host │ ├──────────────────────────────┼──────────────────────────────┤ │04h │SCSI Request Completed With │ │ │Error │ ├──────────────────────────────┼──────────────────────────────┤ │80h │Invalid SCSI Request │ ├──────────────────────────────┼──────────────────────────────┤ │81h │Invalid Host Adapter Number │ ├──────────────────────────────┼──────────────────────────────┤ │82h │SCSI Device Not Installed │ └──────────────────────────────┴──────────────────────────────┘ ═══ 23.3.2.1. ASPI Command Code = 0: Host Adapter Inquiry ═══ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Offset │# Bytes │Description │R/W* │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │00h (00) │01h (01) │Command Code = │W │ │ │ │0 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │01h (01) │01h (01) │Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │02h (02) │01h (01) │Host Adapter │W │ │ │ │Number │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │03h (03) │01h (01) │SCSI Request │W │ │ │ │Flags │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │04h (04) │04h (04) │Reserved for │- │ │ │ │Expansion = 0 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │08h (08) │01h (01) │Number of Host │R │ │ │ │Adapters │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │09h (09) │01h (01) │Target ID of │R │ │ │ │Host Adapter │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │0Ah (10) │10h (16) │SCSI Manager ID│R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1Ah (26) │10h (16) │Host Adapter ID│R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │2Ah (42) │10h (16) │Host Adapter │R │ │ │ │Unique │ │ │ │ │Parameters │ │ └───────────────┴───────────────┴───────────────┴───────────────┘ *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (-). The status byte always returns with a non-zero status. A SCSI Request Completed Without Error (01h) status indicates that the remaining fields are valid. An Invalid Host Adapter Number (81h) status indicates that the specified host adapter is not installed. This function gets information on the installed host adapter hardware, including number of host adapters installed. It can be issued once with host adapter zero specified, to get the number of host adapters. If further information is desired, it can be issued for each individual host adapter. The SCSI Request Flags field is currently undefined for this command and should be zeroed. The SCSI Manager ID field contains a 16-byte ASCII string describing the SCSI manager. The Host Adapter ID field contains a 16-byte ASCII string describing the SCSI host adapter. The definition of the Host Adapter Unique Parameters field is left to implementation notes, specific to a particular host adapter. ═══ 23.3.2.2. ASPI Command Code = 1: Get Device Type ═══ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Offset │# Bytes │Description │R/W* │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │00h (00) │01h (01) │Command Code = │W │ │ │ │1 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │01h (01) │01h (01) │Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │02h (02) │01h (01) │Host Adapter │W │ │ │ │Number │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │03h (03) │01h (01) │SCSI Request │W │ │ │ │Flags │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │04h (04) │04h (04) │Reserved for │- │ │ │ │Expansion = 0 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │08h (08) │01h (01) │Target ID │W │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │09h (09) │01h (01) │LUN │W │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │0Ah (10) │01h (01) │Peripheral │R │ │ │ │Device Type of │ │ │ │ │Target/LUN │ │ └───────────────┴───────────────┴───────────────┴───────────────┘ *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (-). This command always returns with a non-zero status. A SCSI Request Completed Without Error (01h) status indicates that the specified device is installed and the peripheral device type field is valid. A SCSI Device Not Installed Error (82h) indicates that the peripheral device type field is not valid. This command is intended for use by various drivers, during initialization, for identifying the targets that they need to support. A CD-ROM driver, for example, can scan each Target/LUN on each installed host adapter looking for the device type corresponding to CD-ROM devices. This eliminates the need for each driver to duplicate the effort of scanning the SCSI bus for devices. The peripheral device type is determined by sending a SCSI Inquiry command to the given target. Refer to any SCSI specification to learn more about the Inquiry command. The SCSI Request Flags field is currently undefined for this command and should be zeroed. ═══ 23.3.2.3. ASPI Command Code = 2: Execute SCSI I/O Command ═══ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Offset │# Bytes │Description │R/W* │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │00h (00) │01h (01) │Command Code = │W │ │ │ │2 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │01h (01) │01h (01) │Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │02h (02) │01h (01) │Host Adapter │W │ │ │ │Number │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │03h (03) │01h (01) │SCSI Request │W │ │ │ │Flags │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │04h (04) │02h (02) │Length of │W │ │ │ │Scatter/Gather │ │ │ │ │List │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │06h (06) │02h (02) │Reserved for │- │ │ │ │Expansion = 0 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │08h (08) │01h (01) │Target ID │W │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │09h (09) │01h (01) │LUN │W │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │0Ah (10) │04h (04) │Data Allocation│W │ │ │ │Length │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │0Eh (14) │01h (01) │Sense │W │ │ │ │Allocation │ │ │ │ │Length (N) │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │0Fh (15) │04h (04) │Data Buffer │W │ │ │ │Pointer │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │13h (19) │04h (04) │SRB Link │W │ │ │ │Pointer │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │17h (23) │01h (01) │SCSI CDB Length│W │ │ │ │(M) │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │18h (24) │01h (01) │Host Adapter │R │ │ │ │Status │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │19h (25) │01h (01) │Target Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1Ah (26) │02h (02) │Real Mode Post │W │ │ │ │Routine │ │ │ │ │Offset** │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1Ch (28) │02h (02) │Real Mode Post │W │ │ │ │Routine CS** │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1Eh (30) │02h (02) │Real Mode Post │W │ │ │ │Routine DS** │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │20h (32) │02h (02) │Protected Mode │W │ │ │ │Post Routine │ │ │ │ │Offset │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │22h (34) │02h (02) │Protected Mode │W │ │ │ │Post Routine CS│ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │24h (36) │02h (02) │Protected Mode │W │ │ │ │Post Routine DS│ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │26h (38) │04h (04) │Physical │W │ │ │ │Address of SRB │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │2Ah (42) │16h (22) │Reserved for │- │ │ │ │ASPI Workspace │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │40h (64) │M │SCSI Command │W │ │ │ │Descriptor │ │ │ │ │Block (CDB) │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │40h+M │N │Sense │R │ │ │ │Allocation Area│ │ └───────────────┴───────────────┴───────────────┴───────────────┘ *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (-). **Used by OS/2 1.x only. Fields are not used under OS/2 2.x. This command usually returns with zero status indicating that the request was queued successfully. Command completion can be determined by polling for non-zero status or through the use of the Post Routine Address field. If you are going to use polling, interrupts must be enabled. The SCSI Request Flags byte is defined as follows: ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ │7 │6 │5 │4 │3 │2 │1 │0 │ ├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤ │Rsvd │Rsvd │SGE │Direction│Direction│Reserved │Link │Post │ │ │ │ │Bits │Bits │ │ │ │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ The Post bit specifies whether posting is enabled (bit 0 = 1) or disabled (bit 0 = 0). The Link bit specifies whether linking is enabled (bit 1 = 1) or disabled (bit 1 = 0). The Direction Bits specify the direction of the transfer: 00 - Direction determined by SCSI command. Length not checked. 01 - Transfer from SCSI target to host. Length checked. 10 - Transfer from host to SCSI target. Length checked. 11 - No data transfer. The Scatter/Gather Enable (SGE) bit specifies whether scatter/gather is enabled (bit 5=1) or disabled (bit 5=0). The Target ID and LUN fields are used to specify the peripheral device involved in the I/O. The Data Allocation Length field indicates the number of bytes to be transferred. If the SCSI command to be executed does not transfer data (such as Rewind, Start Unit, and so forth) the data allocation length must be set to zero. The Length of Scatter/Gather List field is valid only when the scatter/gather enable bit in the flags is set. It contains the number of descriptors in the array pointed by the Data Buffer Pointer field. The Sense Allocation Length field indicates the number of bytes allocated at the end of the SRB for sense data. A request sense is automatically generated if a check condition is presented at the end of a SCSI command. The Data Buffer Pointer field is a pointer to the I/O data buffer. When scatter/gather is enabled, this field is a physical pointer to a scatter/gather list. A scatter/gather list is made up of one or more descriptors of the following format: ┌─────────────────────┐ │DWORD Buffer Pointer │ ├─────────────────────┤ │ DWORD Buffer Size │ └─────────────────────┘ The SRB Link Pointer field is a pointer to the next SRB in a chain. See the SCSI Command Linking With ASPI for more information. The SCSI CDB Length field establishes the length, in bytes, of the SCSI Command Descriptor Block (CDB). The Host Adapter Status field reports the host adapter status, as follows: 00h - Host adapter did not detect any error 11h - Selection timeout 12h - Data overrun/underrun 13h - Unexpected bus free 14h - Target bus phase sequence failure The Target Status field reports the target's SCSI status, including: 00h - No target status 02h - Check status (sense data is in sense allocation area) 08h - Specified target/LUN is busy 18h - Reservation conflict Note: The host adapter status and the target status are valid only when the status byte is either 2 or 4. The Post Routine Address field, if specified, is called when the I/O is completed. The SCSI Command Descriptor Block (CDB) field contains the CDB as defined by the target's SCSI command set. The length of the SCSI CDB is specified in the SCSI Command Length field. The Sense Allocation Area is filled with sense data on a check condition. The maximum length of this field is specified in the Sense Allocation Length field. The target can return fewer than the number of sense bytes requested. ═══ 23.3.2.3.1. SCSI Command Linking With ASPI ═══ ASPI provides the ability to use SCSI linking to guarantee the sequential execution of several commands. This feature requires that the involved target(s) support SCSI linking. To use SCSI linking, a chain of SRBs is built with the SRB link pointer used to link the elements together. The link bit should be set in the SCSI request flags byte of all SRBs except the last in the chain. When a SCSI target returns indicating that the linked command is complete, the next SRB is immediately processed, and the appropriate CDB is dispatched. When using SCSI linking, make sure that the linking flags in the SCSI CDB agree with the link bit in the SCSI request flags. Inconsistencies can cause unpredictable results. For example, setting the CDB up for linking but failing to set the link bit may result in a random address being used for the next SRB pointer. Any error returned from the target on a linked command will break the chain. Note that if linking without tags is used, as defined in SCSI, posting may not occur on any elements in the chain until the chain is complete. If you have the post bit set in each SRB's SCSI request flags byte, then each SRB's post routine will be called. Note: Do not use SCSI linking. Many SCSI targets, as well as SCSI host adapters, do not handle SCSI linking and will not work with your ASPI module. ═══ 23.3.2.3.2. ASPI Command Posting ═══ Posting refers to the SCSI manager making a FAR call to a post routine as specified in the SRB. This can be used by a driver much like a hardware interrupt might be used. Post routines have all the same privileges and restrictions as a hardware-interrupt service routine in OS/2. Posting is optional, but should almost always be used in OS/2. To use Posting, the post bit must be set in the SCSI request flags. The post routine is called to indicate that the requested I/O is complete. The specific SRB completed is indicated by the four-byte SRB pointer on the stack. The DS of the post routine as specified in the SRB is also passed to the stack. The post routine will be called with interrupts enabled. It is assumed that all registers are preserved by the post routine. ASPI_Post proc far push bp ;Use bp as a reference mov bp,sp pusha ;Save all registers push es ;Save ES mov bx,[bp+6] ;Load DS of POST routine mov ax,[bp+10] ;Physical address of SRB-->AX:BX mov ax,[bp+8] . . . pop es ;Restore registers popa pop ds pop bp retf ASPI_Post endp When your post routine is first entered, the stack looks like this: ┌──────────────────────────┐ Top of Stack [SP+0] > │ Return Address (Offset) │ ├──────────────────────────┤ [SP+2] > │ Return Address (Segment) │ ├──────────────────────────┤ [SP+4] > │ SRB Pointer (Offset) │ ├──────────────────────────┤ [SP+6] > │ SRB Pointer (Segment) │ ├──────────────────────────┤ │ . . . │ ├──────────────────────────┤ │ . . . │ ├──────────────────────────┤ │ . . . │ │ │ └──────────────────────────┘ You can issue any ASPI command from within your post routine except for an abort command. Your post routine should get in and out as quickly as possible. ═══ 23.3.2.3.3. ASPI Command Code = 3: Abort SCSI I/O Request ═══ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Offset │# Bytes │Description │R/W* │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │00h (00) │01h (01) │Command Code = │W │ │ │ │3 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │01h (01) │01h (01) │Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │02h (02) │01h (01) │Host Adapter │W │ │ │ │Number │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │03h (03) │01h (01) │SCSI Request │W │ │ │ │Flags │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │04h (04) │04h (04) │Reserved for │- │ │ │ │Expansion = 0 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │08h (08) │04h (04) │Physical SRB │W │ │ │ │Pointer │ │ └───────────────┴───────────────┴───────────────┴───────────────┘ *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (-). This command is used to request that an SRB be aborted. It should be issued on any I/O request that has not completed if the driver wishes to timeout on that request. Success of the Abort command is never assured. This command always returns with SCSI Request Completed Without Error, but the actual failure or success of the abort operation is indicated by the status eventually returned in the SRB specified. The SCSI Request Flags field is currently undefined for this command and should be zeroed. The SRB Pointer to Abort field contains a pointer to the SRB which is to be aborted. Note: An abort command should not be issued during a post routine. ═══ 23.3.2.3.4. ASPI Command Code = 4: Reset SCSI Device ═══ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Offset │# Bytes │Description │R/W* │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │00h (00) │01h (01) │Command Code = │W │ │ │ │4 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │01h (01) │01h (01) │Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │02h (02) │01h (01) │Host Adapter │W │ │ │ │Number │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │03h (03) │01h (01) │SCSI Request │W │ │ │ │Flags │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │04h (04) │04h (04) │Reserved for │- │ │ │ │Expansion = 0 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │08h (08) │01h (01) │Target ID │W │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │09h (09) │01h (01) │LUN │W │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │0Ah (10) │0Eh (14) │Reserved │- │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │18h (24) │01h (01) │Host Adapter │R │ │ │ │Status │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │19h (25) │01h (01) │Target Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1Ah (26) │02h (02) │Real Mode POST │W │ │ │ │Routine │ │ │ │ │Offset** │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1Ch (28) │02h (02) │Real Mode POST │W │ │ │ │Routine CS** │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │1Eh (30) │02h (02) │Real Mode POST │W │ │ │ │Routine DS** │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │20h (32) │02h (02) │Protected Mode │W │ │ │ │POST Routine │ │ │ │ │Offset │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │22h (34) │02h (02) │Protected Mode │W │ │ │ │POST Routine CS│ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │24h (36) │02h (02) │Protected Mode │W │ │ │ │POST Routine DS│ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │26h (38) │16h (22) │Reserved for │- │ │ │ │ASPI Workspace │ │ └───────────────┴───────────────┴───────────────┴───────────────┘ *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (-). **Used by OS/2 1.x only. Fields are not used under OS/2 2.x. This command is used to reset a specific SCSI target. Note that the structure passed is almost identical to the execute SCSI I/O SRB except that some of the fields are not used. This command usually returns with zero status indicating that the request was queued successfully. Command completion can be determined by polling for non-zero status or through the use of posting. The SCSI Request Flags byte is defined as follows: ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ │7 │6 │5 │4 │3 │2 │1 │0 │ ├─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤ │Rsvd │Rsvd │Rsvd │Rsvd │Rsvd │Rsvd │Rsvd │Post │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ The Post bit specifies whether posting is enabled (bit 0 = 1) or disabled (bit 0 = 0). ═══ 23.3.2.3.5. ASPI Command Code = 5: Set Host Adapter Parameters ═══ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │Offset │# Bytes │Description │R/W* │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │00h (00) │01h (01) │Command Code = │W │ │ │ │5 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │01h (01) │01h (01) │Status │R │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │02h (02) │01h (01) │Host Adapter │W │ │ │ │Number │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │03h (03) │01h (01) │SCSI Request │W │ │ │ │Flags │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │04h (04) │04h (04) │Reserved for │- │ │ │ │Expansion = 0 │ │ ├───────────────┼───────────────┼───────────────┼───────────────┤ │08h (08) │10h (16) │Host Adapter │W │ │ │ │Unique │ │ │ │ │Parameters │ │ └───────────────┴───────────────┴───────────────┴───────────────┘ *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (-). The definition of the host adapter unique parameters is left to implementation notes specific to a particular host adapter. ═══ 24. Adapter Device Driver Interface Questions and Answers ═══ This appendix covers the most commonly asked questions about adapter device driver interfaces, including discussion of scatter/gather lists and functionality. The answers are presented in detail. ═══ 24.1. Scatter/Gather Lists ═══ Question: Is there a limit on the length of an individual scatter/gather element? Answer: No. We are aware that some SCSI PIO drivers have a 64KB limitation on scatter/gather elements. At present, OS/2 2.0 appears to remain within this limitation. However, it is recommended that this restriction be lifted because there is no guarantee that adapter device drivers with such a limitation will be compatible with future OS/2 operating system releases. Question: Is there a limit on the number of elements in a scatter/gather list? Answer: No. Question: What is the meaning of the field: ────────────────────────────────────────────────────────────────────────── AdapterInfo->UnitInfo->MaxHWSGList ────────────────────────────────────────────────────────────────────────── Answer: This is the maximum number of scatter/gather list entries your adapter hardware can handle. The OS/2 operating system will ensure that the adapter device driver is not required to split a sector across a MaxHWSGList boundary. However, the adapter device driver is responsible for iterating an I/O command because of limitations in its s/g support. Question: What about s/g lists associated with CDB PassThru commands? Answer: adapter device drivers are not required to iterate commands through the CDB PassThru mechanism. Commands received from SCSI.SYS device class drivers will require a minimum of 16 s/g elements. At present, the number of s/g elements required by device modules written to ASPI interfaces is not known. If the OS2SCSI or OS2ASPI device managers receive an s/g list that does not conform to the adapter device driver's s/g requirement, these device managers will reject the request. Question: What is the meaning of the field: ────────────────────────────────────────────────────────────────────────── AdapterInfo->UnitInfo->MaxCDBXferLen ────────────────────────────────────────────────────────────────────────── Answer: This field is not the maximum CDB length. The purpose of this field relates to the limitations on s/g list lengths and their effect on PassThru commands. For adapter device drivers written for adapters that have severe s/g list limitations or unusual s/g address limitations, the adapter device driver might emulate s/g functionality using an I/O buffer. In this case, the adapter device driver would inform the OS2SCSI or OS2ASPI device managers of the length of its emulation buffer by way of the above field. It is up to the adapter device driver to perform this emulation. Question: My adapter requires an s/g list format different from the one provided. Do I need to allocate storage for separate lists? Answer: No. Provided that your transformations are reversible, you can reformat the passed s/g list to what your adapter can accept. You must reverse the reformatting prior to performing your notification call out. ═══ 24.2. Adapter Device Driver Functionality ═══ Question: Do I need to support every command in this specification? Answer: No. For specific device types, some commands are mandatory and others are optional. For example, there are several commands that apply only to floppy controllers. We must support these commands due to the unusual characteristics of diskette media. Where possible, mandatory commands for particular device types are indicated. Question: Some commands do not appear to be used by the current OS/2 2.0 device managers. Must I implement these commands? Answer: Yes. To preclude compatibility problems with future releases of OS/2, you should follow this specification as closely as possible with respect to mandatory commands. Question: What happens if IBM-supplied sample code differs in some way from this specification? Answer: This specification takes precedence over IBM-supplied samples. Obtain clarification from IBM if you have questions on a particular code sample. Question: SCSI defines different command formats for different device types. Do I need to support all the different CDB formats? Answer: No. You must support the DASD type formats only. The remainder of the device types will be supported by way of CDB PassThru; that is, the adapter device driver will be supplied with an appropriate CDB. Question: Do I need to support the IORB_CHAIN RequestControl flag on every IORB command type? Answer: No. The chain flag is used only on IOCC_EXECUTE_IO commands. In addition, all IORBs contained in the chained request will reference the same UnitHandle. Question: Do I need to support any unusual SCSI commands? Answer: No. We expect most DASD devices to conform to CCS. Regarding SCSI Write/Verify, adapter device driver writers are encouraged to emulate this command for drives that do not provide this function directly. Suppliers of devices that have unusual command requirements are expected to provide filter device drivers. Question: What kind of error recovery is an adapter device driver required to perform? Answer: Adapter device drivers are responsible for error recovery. An error reported to the layers above the adapter device driver is considered not recoverable. In general, SCSI devices retry at the device level, so the adapter device driver does not need to retry commands that failed at the device. However, the adapter device driver should retry commands that failed due to errors on the SCSI bus during either the command or data transfer phases. Question: Must the adapter device driver retry commands that were disrupted due to an adapter reset for a hang condition? Answer: Yes, the adapter device driver is responsible for retrying commands disrupted by an adapter device driver-initiated reset of an adapter to clear a hang condition. Question: Does the adapter device driver have to report media removal with an error code to the device manager? Answer: If the unit supports media removal, the adapter device driver is required to report media removal to the device manager by way of the appropriate IOERR_* code. In addition, the adapter device driver should return the same error code for all work queued for the unit. The adapter device driver should not retry this error. The adapter device driver should treat a power-on condition the same as media removal. The adapter device driver should return the appropriate IOERR_* code for all queued work after a not ready condition. If the unit does not support media removal, the adapter device driver should retry the operation. Question: Must my adapter device driver perform SCSI sense code->IOERR_* translation? Answer: Yes. The OS/2 DASD device manager expects a uniform set of error codes and will not examine SCSI sense codes. Question: Must my adapter device driver return sense data when requested? Answer: Yes. The OS2SCSI and OS2ASPI device mangers need to return this data to their clients. ═══ 25. Using the Device Driver Test Tool (DDTT) ═══ The Device Driver Test Tool (DDTT) provides an efficient environment to create, execute, and refine device driver test cases. The DDTT is extensible by the addition of new device-dependent DLLs and grammar files. DLL files implement device-specific interface functions, such as DosDevIOCtl calls. Actual test-case content and execution is controlled by test-case script files. Test-case script files are parsed by DDTT's generic parser. Device-specific functions resident in the DLLs are indirectly called from the test-case parser. Device-specific grammar files tell the parser which device-specific function and parameter keywords to expect in the test-case script files. Accelerated development of test interfaces to new devices is achieved with the DDTT by isolating the device-specific calls in "stub routines", which are compiled and linked into a separate DLL file. Linkage to the device-interface routines is established at run-time by demand loading the DLL functions. The DLL name and function name information is obtained from the device-specific grammar file. The DDTT parser reads a test-case file and locates a @NEWALIAS command. The @NEWALIAS command contains the name of a DDTT grammar file for all commands prefaced with the specified new alias name. The parser uses the device grammar file name to map all device-specific commands to the correct DLL and function name within the DLL. ═══ 25.1. Overall Data Flow Diagram ═══ The following data flow diagram shows the major components of the DDTT. Shaded modules represent components that are intended to be modified or re-created when adding new support for devices and test cases. Note: When adding new C++ device interface modules, it is necessary to provide a device-dependent grammar file that provides run-time linkage information to DDTT's parser. ═══ 25.1.1. Development Environments ═══ The DDTT provides the following three development environments: o Test Case Execution o Test Case Development o Ring-3 Device Interface ═══ 25.1.1.1. Test-Case Execution ═══ Test case executors are the intended users of the DDTT at this level and is a procedural interface. DDTT test cases are contained in flat text files called Script Files. Typically, each script file contains one test case, although a test case could span multiple files by utilizing the DDTT's script file's include capability. To start a test case contained within a file named TEST01.SCR, type DDTT TEST01.SCR from an OS/2 command prompt. Operator prompts are displayed in separate windows, one window for each test thread. Any resulting logs are written to the file names specified on the @THREAD commands in the test script file. At the Test-Case Execution level, the DDTT requires limited knowledge of OS/2 (for example, how to start and stop command files, and any device-specific knowledge required by the test-case grammar file. DDTT scripted test cases are repeatable. When a test case is defined and contained within a Test-Case Script File, the execution and subsequent re-executions of the test case always execute functions within a thread in the same order. Although intra-thread operations occur in the same order, there is no guarantee that inter-thread operations will always occur in the same order. Use the DDTT's shared file logging to determine test-case execution order in multiple thread test cases. ═══ 25.1.1.2. Test-Case Development ═══ When a device's function set has been defined, additional test cases can be created by adding or modifying existing test-case scripts. Thus, adding new test cases for an existing device requires knowledge of that device and an flat file editor. Using DDTT's scripting capabilities, new test cases can be quickly developed to cover any "holes" identified in existing test "buckets". In addition to device-specific functions, DDTT test case developers can use all of the functions described in Script Utility Functions. The interface provided for the test case script writer is procedural. Commands are executed top-to-bottom within a given test-case thread. Built-in generic functions are provided for creating test case scripts. Generic functions are independent of any device under test. Syntax of these functions is the same across all DDTT device interfaces. ═══ 25.1.1.3. Ring-3 Device Interface ═══ The C++ DLL modules implement DDTT device-specific stub functions. Creating DDTT device interfaces requires knowledge of the C++ programming language and a detailed understanding of the device driver to be tested (such as which functions the device is capable of performing). The DDTT provides many common functions, such as log file management and cover routines for the OS/2 APIs. DDTT device stub function developers can use all of the functions described in Stub Utility Functions. ═══ 25.1.2. Script Utility Functions ═══ Test-case script functions are device-specific or generic. Generic or utility-script functions are part of all DDTT grammar files. Most DDTT commands are associated with an aliasname. The general form of a DDTT command is as follows: alias_name FUNCTION_NAME [[PARAMETER=value], ...] The DDTT built-in functions which are not associated with an aliasname are preceded with an "at"(@) character. Script Utility Function keywords and their parameters are case insensitive and all tokens are uppercased by the DDTT. In the descriptions below, upper case represents fixed tokens or keywords, and lower case indicates a variable token, specific to the particular function invokation. To preserve a token's case, use the syntax $(Token). All DDTT commands are automatically continued to the next line if the last character in the line is the backslash character (\). The DDTT test case files can use OS/2 environment variables. Environment variables can be used anywhere in the script. Any valid symbolic token with a (%) sign preceding it will be interpreted as an OS/2 system environment variable. To establish or change an environment variable from an OS/2 prompt, type the following: [C:\]set cdrom=cdrom.scr. The environment variable can then be referenced from within a test case script as follows: @thread %cdrom. (%cdrom will then be replaced by cdrom.scr.) ═══ 25.1.2.1. @THREAD ═══ @Thread log_filename This function starts the new thread of execution. Any resulting DDTT file logs will be written to log_filename. The DDTT shares access to log_filename, and the same log_filename may be used for multiple @THREAD commands within the same test case. The DDTT also creates a separate OS/2 Presentation Manager window for every @THREAD token. Any operator messages and prompts generated in the @THREAD section are displayed in the corresponding window. Each occurrence of the @THREAD token marks the start of a section in the test case script file which is to be executed sequentially under the control of a single OS/2 thread created by DDTT. DDTT parses the entire test case file looking for @THREAD tokens. When the entire test case file (including any @IMPORT commands) has been parsed, DDTT creates and starts an OS/2 thread for each @THREAD token located. All threads are initially created within the DDTT process with the following characteristics: Stack size: 4KB Note: o Thread windows are created on top of each other. To access multiple windows simultaneously, drag the thread windows to separate places on the screen o All OS/2 threads are started at approximately the same time. o The DDTT must encounter an @THREAD command as the first command after resolving all @IMPORT commands in the test case file. o The DDTT test scripts can start no more than 50 threads. ═══ 25.1.2.2. @NEWALIAS ═══ @NEWALIAS alias_name grammar_file Create a DDTT alias name and establish the device-specific grammar to use when parsing all other commands with the same alias_name in the test case. The first required parameter is the alias_name and can be any alpha-numeric string. The specified alias_name is the first token in all commands that follow and share the same family of parameter keywords. The second required parameter specifies the grammar file to be used when parsing all commands which start with the alias_name token. The DDTT's parser uses the content resolve all device-grammar file function, the parameter keyword and the expected value keywords used in the test case commands. ═══ 25.1.2.3. @IMPORT ═══ @IMPORT import_filename Insert the content of the specified import_filename into the test-case file. DDTT test-script files can include or insert other DDTT test script files. Up to ten levels of imported files are allowed. An environment variable may be used to contain the file name of the file to be included. ═══ 25.1.2.4. @LOOP ═══ @LOOP loop_cnt | [alias_name, numeric_parameter_kwd] Execute the following block of one or more scripted functions up to the next @ENDLOOP token in a loop. Nested loops are permitted. The number of loop iterations is controlled in one of two methods. A single loop count-positive numeric value may be specified or a DDTT environment variable may be used. The other method is syntactically different, but allows specification of a DDTT parameter_keyword as the loop count. Place the DDTT alias_name and a numeric parameter_keyword defined by the alias inside square brackets {[]}. Use a comma separator between these tokens. Note: o The value used for the loop count is the current value of the parameter_keyword at the start of the loop. The actual value of the parameter_keyword is not changed by executing the @LOOP command. o The current loop count value is not accessible from within the loop. ═══ 25.1.2.5. @LOG ═══ @LOG "string" This function logs the only parameter to the log file opened with the previous @THREAD command. The log entry is time-stamped. If the log command string contains script variables, the script variables will be expanded before the text is placed in the log file. Every log file entry made from the script interface will be prefaced with the current time/date stamp from the real-time clock of the machine under test. The quotation marks are required only if the string contains white space. ═══ 25.1.2.6. @PAUSE ═══ @PAUSE seconds This function stops execution of all aliases in the current thread for the specified number of seconds. Execution is automatically resumed. No tester action is required. ═══ 25.1.2.7. @FLUSH ═══ @FLUSH alias_name This function releases buffers and closes the log file for the current thread. ═══ 25.1.2.8. SET ═══ alias_name SET parameter_name=value This function initializes or reinitializes the current value of the DDTT keyword parameter_name to the string value. Any previous value is erased. Multiple keyword parameters may be set in one DDTT SET command. Separate each parameter equate with white space. All keyword parameters are associated with the specified alias_name. A keyword parameter_name need not exist or be expected; no warning or error is generated if a SET command is performed on a nonexistent parameter_name. The parameter_name will exist after executing the SET command. Type checking of values for parameter_names is not performed with the SET command, instead, type checking is done when DDTT invokes the device function. ═══ 25.1.2.9. LOG ═══ alias_name LOG $PROMPT="String to be logged" This function generates a time-stamped entry in the log file opened at the previous @THREAD command. The string specified in the $PROMPT keyword is also written to the DDTT thread window during test case execution. If the $PROMPT keyword is not set, then a time-stamp is written to the log file. ═══ 25.1.2.10. RESPONSE ═══ alias_name RESPONSE $PROMPT="String to be output" $PAUSE=seconds $RESPONSE=param_kwd This function displays a tester prompt string contained in the $PROMPT parameter keyword and returns any tester input in the parameter keyword referenced by $RESPONSE. The $PAUSE keyword can be used to specify the number of seconds to wait for the tester to start inputting the response. As long as the tester has pressed at least one keystroke before $PAUSE seconds has elapsed, DDTT will wait with an infinite timeout for the remainder of the input. Input is terminated by the enter key. If no value is specified for the $PROMPT keyword, this function causes test case execution to pause for $PAUSE seconds. If $PAUSE is not defined or specified as 0, then no tester input will be accepted, but the $PROMPT is displayed. If $PAUSE is specified to be -1, the DDTT will wait for a tester response with an infinite timeout. Note: Place the cursor in the input window before providing tester input to a DDTT thread panel. The cursor does not automatically go to the thread input window. ═══ 25.1.2.11. INCREMENT ═══ alias_name INCREMENT This function increments the DDTT $COUNT keyword parameter in alias_name by 1. ═══ 25.1.2.12. DECREMENT ═══ alias_name DECREMENT This function decrements the DDTT $COUNT keyword parameter in alias_name by 1. ═══ 25.1.2.13. ADD ═══ alias_name ADD This function adds the DDTT $OP1 and $OP2 keyword parameters and places the result into the $RESULT keyword parameter. ═══ 25.1.2.14. SUB ═══ alias_name SUB This function subtracts the DDTT $OP2 keyword parameter from $OP1 and places the result into the $RESULT keyword parameter. ═══ 25.1.2.15. COMPARE ═══ alias_name COMPARE BUFFER1=alpha BUFFER2=beta This function compares the two DDTT keywords. It returns BUFFER COMPARE SUCCESS or BUFFER COMPARE FAILURE. ═══ 25.1.2.16. DUMP ═══ alias_name DUMP $BUFFER=alpha This function will place the contents of a buffer in the log file. ═══ 25.1.2.17. Named Data Buffers ═══ The DDTT test scripts can access named buffers by way of device-dependent read and write operations. The named buffer is device-independent and may be used with different devices from within the same test script. A named data buffer is initialized by referencing the named buffer as part of a device-read operation. Data from a device can be read into a named data buffer and then written to another device or file. Comparison of two named data buffers and dumping a buffer to a log file is provided. Named buffer comparison and dumping operations are provided as device-independent functions. ═══ 25.1.3. OS/2 API Cover Functions ═══ A set of DDTT OS/2 API-cover routines is provided. These routines detect and report error conditions returned by OS/2 API calls. Formatted error messages do not have to be created for each API called; however, if the API returns an error, it will be reported in the log file. The provided cover APIs have the same name as their OS/2 counterparts but are prefaced with ddt. Likewise, the calling parameters are also identical, except for three additional parameters added after the standard parameters: IString pszCallingRoutineName; / / Name of the device specific stub function / / calling routine . This IString is printed / / as part of any error message generated in / / the API cover routine . IString pszLocationDescription ; / / Any text the DLL writer wants included / / with the error message text from the API / / cover routine . OutputStream & output ; / / OutputStream to send any error or / / informational messages from the API cover / / routine . Listed below is the current set of OS/2 APIs for which DDTT has implemented cover routines: ddtDosOpen ddtDosRead ddtDosWrite ddtDosDevIOCtl ddtDosClose ddtDosPhysicalDisk The writer of a device-specific DLL must include ddtos2.h. # include ddtos2.h Below is a sample prototype of one of the most frequently used API cover routines. APIRET _export ddtDosDevIOCtl( HFILE hDevice, ULONG category, ULONG function, PVOID pParams, ULONG cbParmLenMax, PULONG pcbParmLen, PVOID pData, ULONG cbDataLenMax, PULONG pcbDataLen, IString pszCallingRoutineName, IString pszLocationDescription, OutputStream& output); ═══ 25.1.4. Stub Utility Functions ═══ The functions and classes described in this section are intended for use in developing interface stub functions and are accessed through a C++ interface. Although these functions are written in and accessed through C++, these functions can be called from device stub functions that are primarily written in C. The utility classes described are the following: IString Kwd_List DdtOStream Buffer ═══ 25.1.4.1. IString Class ═══ The IString class is the most basic of the utility classes. Items of type IString contain and manipulate character data. Data types other than characters can be stored in a IString object, however, other types of data will first be converted to a character representation. IString objects automatically grow and shrink as their content is manipulated and are not pre-allocated to a known size. The complete information on the functionality of the IString class is found in the ISTRING.HPP header file. This class and associated files were taken from what became part of a user interface class library in the IBM C++ product. The following is a subset of the constructor methods available to create IString objects: IString(); IString( const char* ); IString( int ); IString( const IString& ); IString( char ); IString( const void *pBuffer1, unsigned lenBuffer1, char padCharacter=' ' ); The following is a subset of the methods available for IString objects: long asInt() const; unsigned size() const; unsigned length() const; IString subString( unsigned startPos, unsigned length=0, char padCharacter=' ' ) const; The following is a subset of the overloaded operator methods available for IString objects: char &operator[]( unsigned index ); IString &operator=( const IString &aString ); IString operator + ( const IString &aString ) const; IString operator + ( const char *pString ) const; friend _export IString operator + ( const char *pString, const IString &aString ); IString operator - ( const IString &aString ) const; IString operator - ( const char *pString ) const; friend _export IString operator - ( const char *pString, const IString &aString ); IString & operator += ( const IString &aString ); IString & operator += ( const char *pString ); operator char*() const; const char &operator[]( unsigned index ) const;\ The == operator prototyped below works similarly for operators: !=, <, <=, >, and >=. friend _export Boolean operator == ( const IString &string1, const IString &string2 ); friend _export Boolean operator == ( const IString &string1, const char *pString2 ); friend _export Boolean operator == ( const char *pString1, const IString &string2 ); IString objects can be automatically instantiated on the stack as shown below. This example creates a IString object named str: #include "istring.hpp" . . . IString str; IString objects can also be dynamically instantiated by way of a constructor method. Below is an example of constructing a IString and referencing it with a pointer named pstr: #include "istring.hpp" . . IString * pstr; . . pstr = new IString("ABC"); IStrings act as a repository for data given to them. All data given to an IString object is first converted to ASCII character data and then copied into the IString. Thus, after constructing an IString, data may be deposited into it such as the following: str = "Output from YourFunction:\n"; The creating and initialization of a IString object may be combined as the following: IString str("Output from YourFunction:\n"); Used as above in the first example, with the = operator, any existing content of the IString item is entirely replaced with the new data, Output from YourFunction. The IString class provides additional overridden operators for manipulating the content of an IString object. To concatenate data to an existing IString item, use the +=operator: str += (IString)"Input ABC returned XZY\n"; or, str = (IString)"Input ABC " + (IString)"returned XYZ\n"; The following is also an eraser or subtraction operator which deletes the first occurrence of the specified substring. (str = str - (IString)"returned") If the above three IString operations were performed in sequence, str would contain the following: Output from YourFunction:\n Input ABC XZY\n Notice the use of the (IString) casting operator on the RHS operands when using the + operator. This function is necessary for the + and - overridden IString operators in order to keep the compiler from getting confused and trying to do the wrong type of "addition" or "subtraction". In addition to character strings, IString items can also accept other data types. IString items recognize these other data types and convert the data into a character string. The user must tell the IString what type of data is being input through the use of casting operators, for example: str += (int)101; The integer will be converted to its base 10, character equivalent and the resultant content of str would be the: Output from YourFunction:\n Input ABC XZY\n 101 IString items can accept for input and convert the following data types: (const char *) // Deref's ptr, copies in string, %s (char) // Converts to ASCII, %c (IString &) // Deref's ref, copies in IString (int) // Converts integer to ASCII, %d (void *) // Converts pointer to integer ASCII, %p One last overridden operator is the square brackets, [], which provide similar function as they do for normal C strings except the index origin begins with 1. They provide a convenient mechanism for indexed access to individual characters within the IString. The index has an origin of 1. From the above example, str[2] is currently equal to the character u. IString substrings can be accessed through the following subString method: str = (IString)"ABCEFG"; IString str2 = str.subString(3,3); After executing these lines, str2 contains CEF. Although IString objects store all data internally as character data, several methods are provided to retrieve data types other than characters. For example: int i; IString str; . . . i = 5; str = (IString)2 + (IString)i; i = str.asInt(); // Returns IString as an integer After this code executes, str[1] = '2', str[2] = '5', and i = 25. A length method is included that returns the current number of characters stored in the following IString object: i = str.length(); results in: i = 2. ═══ 25.1.4.2. Kwd_List Class ═══ A reference to a Kwd_List object is passed into every stub function. The Kwd_List object contains all the parameters for the current alias name. Through operations on the Kwd_List object, values of parameters may be set or retrieved from the current alias the test script. By referencing the same Kwd_List parameter, two or more stub functions can share a parameter. Each Kwd_List is a List object. Each item "on the" Kwd_List is also an object and consists of a Keyword and a Value. Both Keyword and Value are IString objects. Think of the Keyword as that parameter's "ASCII handle" and Value as the current content or value of that parameter. The DDTT creates an entry for each parameter keyword specified in the associated grammar file for the current DDTT alias. Thus, the stub function's view of the Kwd_List object is primarily that of accessing and updating the existing entries in the Kwd_List. The following constructor method is available to create Kwd_List objects: Kwd_List(); // Creates an empty list The following methods are available for Kwd_List objects: // Add or update a keyword-value pair in the Kwd_List void set(IString kwd, IString value); // Remove a keyword-value pair from the Kwd_List void unset(IString kwd); // Return an sscanf'd int corresponding to a keyword long int getInt(IString kwd); // Return an sscanf'd pointer corresponding to a keyword void * getPtr(IString kwd); // Return true if the keyword is known BOOL isKeyword(IString kwd); // Return the number of entries in the Kwd_List int nKey(); // Return a pointer corresponding to the FILES keyword FileInfo * files(); The following overloaded operator methods are available for Kwd_List objects: // Return the corresponding value to a keyword IString operator[](IString kwd); // Numerically indexes the list, return keyword-value void operator()(int inx, IString& kwd, IString& value); Below is a declaration of a sample stub function: #include "kwdlist.h" . . APIRET SampleStubFtn( Kwd_List ¶m ) { // code here }; The only parameter to all stub functions must be a Kwd_List object reference. Assume the grammar file specifies the following parameter keywords: DEVICENAME READTRYS BUFFERCOUNT OUTPUTBUFFER Also assume that input kwd_list reference is named param, as in the above example stub declaration. To access DEVICENAME as an IString use the overloaded operator: [] IString name; . . . name = param["DEVICENAME"]; The overloaded operator [] expects an IString object as input, (an input variable of type const char * works also, because const char * can convert themselves to IString objects). The [] operator then automatically converts to IString, performs the lookup in the Kwd_List, param, and returns a copy of the value associated with the parameter keyword. A stub function can change the current Value of an item on the input Kwd_List by way of the set method. ═══ 25.1.4.3. READTRYS ═══ param.set("READTRYS", (long)6); This function sets the current value of the READTRYS parameter keyword to 6. This procedure will overwrite any value set in the test case script file to this point in the script file's execution. Keyword parameter values can be retrieved as long integers and pointers respectively, by way of the getInt getPtr methods: long loop_cnt; char * huge_buf; . . . loop_cnt = param.getInt("READTRYS"); huge_buf = param.getPtr("OUTPUTBUFFER"); The unset method has a more permanent effect on the input parameter's keyword param.unset("READTRYS");. This unset operation removes READTRYS from Kwd_List. After executing this method, any future reference to the READTRYS parameter keyword within the execution of the current DDTT alias would return an empty IString object. The unset method drops the entire Keyword and Value pair from the input Kwd_List. As such, the unset method should be used with caution! The isKeyword method tests the Kwd_List object to determine if the specified parameter keyword is currently in the Kwd_List object. int test; . . // This will return TRUE test = param.isKeyword("READTRYS"); // This will return FALSE. test = param.isKeyword("RETRYCNT"); Returns TRUE if the keyword is on the list, FALSE otherwise. int kwd_count; . . kwd_count = param.nKey(); Returns the number of keywords currently in the Kwd_List object. By convention, keywords that begin with a "$" character are built-in, automatic variables. Existing #define macros in the DDTKWDS.H file ensure proper error checking by the compiler. For example: // Pointer to associated FileInfo object #define FILES_KEY "$FILES" // Pointer to associated BufferList object #define BUFFER_LIST "$BUFFERLIST" // Current DO, FOR loop index value #define COUNTER "$I" Access to the protected log file output stream is obtained through the $FILES parameter keyword. The required C++ syntax is relatively complicated; therefore, a special Kwd_List method, files(), is provided to simplify access to the standard logging output stream IString s1; . . param.files()->out1<out1<<(IString)"Hello world!"; The only difference between a DdtOStream and an OutputStream is that each output to a DdtOStream is precluded with the current Thread Identification. The current threadID is set for DdtOStream when DDTT executes an @THREAD command. The current ThreadID can be changed through the settid method: out1.settid("New thread name");. ═══ 25.1.4.5. Buffer Class ═══ The Buffer class provides a memory buffer object that can be used to contain blocks of data read and written to devices. Buffer objects must always be created by the stub writer. If they are attached to the Kwd_List by way of the BUFFER_LIST keyword, then Buffer object destruction will occur automatically by DDTT. A test script writer references a buffer name in a test script such as in the DEV_ALIAS READ_SECTOR BUFFER1=ALPHA. script command. ALPHA is only the specified name of the buffer, not the actual Buffer object. The function stub must create the actual Buffer object and associate the name, ALPHA, with the created Buffer object. The function stub uses the DDTT keyword, BUFFER1, to access the Buffer's specified name, ALPHA. The following constructor method is available for Buffer objects: Buffer(const char * name, size_t size, void * = NULL); The following methods are available for operating on Buffer objects: // Return a pointer to the Buffer's data PVOID buffer(); void reallocate(size_t size); int compare(Buffer&, size_t); PCHAR kwd(); size_t size(); The following overridden operator methods are available for operating on Buffer objects: // Replace RHS Buffer with a copy of LHS Buffer Buffer& operator=(Buffer& buf2); // Compare Buffer objects BOOL operator==(Buffer&); The #include "buffer.h" include statement must be at the top your C++ stub module in order to use Buffer objects. The following are some examples showing usage of the C++ methods provided to operate on Buffer objects. size_t size = 2048; Buffer * buf; . . buf = new Buffer( param["BUF_NAME"], size, param.getPtr(BUFFER_LIST)); The above statement constructs a new Buffer object with memory block of length-size bytes associated with the test script keyword BUF_NAME. The constructor also adds the new buffer to a BufferList attached to the Kwd_List, by the keyword BUFFER_LIST. By specifying the last parameter in the constructor, a BufferList pointer, DDTT, will automatically destroy the Buffer object when the current thread terminates. The BufferList parameter can be left out or specified as NULL, in which case, the new Buffer object is not attached to the Kwd_List. However, the user is then responsible for deleting the Buffer object when it is no longer required by the stub functions. The delete buf; function destroys the Buffer object and deallocates its memory. For example: Buffer buf; void * ptr; . . ptr = buf.buffer(); The delete buf; function returns a pointer to the buffer's internal block of memory. For example: void * datap; . . datap = (param.getPtr(param["BUFFER"]))->buffer(); Buffer objects can be easily "dumped" to the standard DDTT log file as: Buffer buf1; . . param.files()->out1<Destroy(); This function deletes Buffer pointed to by bufp. ═══ 25.1.5. Adding New Grammar Specifications ═══ A grammar file is a flat text file that specifies the stub functions available for a particular DDTT test grammar. Within DDTT, the scope of a grammar is the alias. Each alias specified in a test script associates a single grammar with the alias. For example: @NEWALIAS ABC ABC_GRAM.GRA The above line from a test script file creates the ABC alias and associates the grammar specified in the file, ABC_GRAM.GRA , with the ABC alias. All further references to functions called within the ABC alias will use the ABC_GRAM.GRA grammar file to resolve the DDTT stub function entry point. Every DDTT callable stub function has a corresponding entry in a grammar file. The grammar file provides the mapping between the function name as it is referenced in the test script file and the actual entry point in a DDTT stub function DLL file. See Sample Grammar Specification for a sample DDTT grammar file. ═══ 25.1.5.1. Specifying Comments ═══ The DDTT grammar files should serve as the primary mechanism for communicating function and parameter details to the test script writer. As such, use of comments is encouraged. All lines with an (*) as the first character specifies a comment line in the DDTT grammar file and its entire content is ignored by the parser. * this is a comment ═══ 25.1.5.2. Stub Function Entry Specification ═══ Each DDTT callable stub function is defined by a Stub Function Entry Specification. The following is syntax for a grammar file Stub Function Entry Specification: func_kwd $DLL=dll_name \ $FUNC=_func_name \ [param_kwd=param_type]... \ [$EXPECTED [param_kwd=param_type]...] The complier name of the stub function's DLL entry point is @func_name$qr8Kwd_List. The name shown here is specific to Borland's OS/2 Version 1.5 C++ compiler. The function, func_name, is as it appears in the C++ function stub source. Use the prefix (@) and suffix $qr8Kwd_List for all stub functions called by the DDTT. Where param_type is defined as one of the following parameter type tokens: param_type=NUM|ALPHA|ALNUM|STRING Param_type token definitions: NUM - All characters in this parameter must be numeric, [0..9, +, -, .] ALPHA - All characters in this parameter must be alphabetic, [a..z, A..Z] ALNUM - All characters in this parameter must be alphabetic or numeric,[a..z, A..Z, 0..9, +, -, .] STRING - Any character string or nothing (null string) may be specified. This is the default param_type. Each complete Stub Function Specification must be on a single logical line. Actual lines in the grammar file may be extended by placing backward slash, (\) as the last non-blank character in the line. For OS/2, the dll_name must be a valid DDTT DLL file with the location specified in LIBPATH. For DOS, $DLL is still used to determine which set of functions the stub is called from; it does not refer to a DLL name, but is prefaced with the underscore character,(_). The name of the stub function, func_kwd, is used in the test case script file. All func_kwds must be unique within a grammar file. The same param_kwd may be used for different functions. If the same param_kwd is used, then only one parameter keyword is created and the value of this parameter keyword is used for all functions specifying the same param_kwd. One or more param_kwds with param_type may be specified to pass data into the DDTT stub function. Param_kwds defined before the $EXPECTED keyword in the Stub Function Entry Specification are required. At runtime, DDTT's parser will not call a function specified in the test script unless all required param_kwds are defined and of the correct type. If the user attempts to call a stub function with incorrectly specified parameters, DDTT prints an error message identifying which function is not being called and what parameter(s) are incorrect. If a script file calls a stub function without specifying EV_ or ET_ values for all $EXPECTED parameters then DDTT calls the function, checks any specified parameters and also prints a warning message to the log file specifying which expected parameters are missing. ═══ 25.1.5.3. Automatic Expected Value Checking ═══ If the Stub Function includes a $EXPECTED keyword then the list of param_kwd(s) which follow will be automatically verified by DDTT. Use of the $EXPECTED param_kwd list permits the user to specify expected results in the test case script file. The DDTT will automatically compare the specified expected results with the param_kwd's actual resultant value. If the results match, then no log message is produced. If the value or type fails to compare then an ERROR message is logged which show the actual and expected results. Each param_kwd specified in the grammar file's $EXPECTED list may contain a param_type specifier. It is not necessary to specify a param_type if the param_kwd is a required input parameter and as such has already been specified in the Stub Function Specification. If the parameter is not a required input then the param_type specifier is required. The test case writer may verify the expected results two ways: o Prefix: ET_ - Verify result has the same param_type, NUM, ALNUM, ALPHA, or STRING as the associated param_kwd. o Prefix: EV_ - Verify the result matches the expected value of the associated param_kwd. The test case script writer specifies which verification method by placing either an "EV_" or "ET_" prefix on param_kwd to be verified. in the test case script file. Consider the following example grammar and test script files: * * Example grammar entry, video.gra * @import global.gra read_video $DLL=vidotest \ $FUNC=@MMVID_GETCLIP$qr8Kwd_List \ MODE=ALNUM \ START_FRAME=NUM \ FRAME_COUNT=NUM \ $EXPECTED \ NEXT_FRAME=NUM \ ACT_FRAME_CNT=NUM \ FRAME_TYPE=ALNUM * * Example Test Case Script * @newalias alias_1 video.gra alias_1 read_video \ MODE=UNCOMPRESSED \ START_FRAME=100 \ FRAME_COUNT=30 \ EV_NEXT_FRAME=131 \ EV_ACT_FRAME_CNT=30 \ ET_FRAME_TYPE The above example grammar defines the read_video function, Before this function can be invoked, the test script must have previously defined the input parameters: MODE, START_FRAME, and FRAME_COUNT. The script writer can also provide definitions for expected values, "EV_", or specify that DDTT verify the param_types with the "ET_" prefix for the returned parameters: NEXT_FRAME, ACT_FRAME_CNT, and FRAME_TYPE. If the script writer does not define expected values with the "EV_" or "ET_" prefix for all of the param_kwds listed under $EXPECTED, then DDTT will by default issue a warning that no parameter checking is taking place for the missing param_kwd(s). After executing the above example, DDTT verifies NEXT_FRAME has the value of 131, ACT_FRAME_CNT has the value of 30, and FRAME_TYPE returns an alpha-numeric string. DDTT logs an error message if any of these conditions are not met. The script writer may turn off all parameter verification by setting the param_kwd $EXPECTED to "off". Parameter verification may be re-activated by setting it back to "ON". alias_1 set $EXPECTED=OFF * * Parameter Verification is now disabled. ... alias_1 set $EXPECTED=ON * * Parameter Verification is now re-enabled. ... API returns may be automatically checked for expected non-zero returns by capturing the APIRET from the DDTT API cover routines and setting the value into a DDTT keyword variable such as: APIRET_01. Extend the associated grammar specification for the function under test as: $EXPECTED \ APIRET_00=NUM Test cases which call a function instrumented as such will be required to specify an expected value for APIRET_00 and if it fails to match, DDTT will automatically send an error message to the log file. ═══ 25.2. Sample Grammar Specification ═══ * * Sample grammar file for a set of DDTT stub * functions. * ******************************************** * Empty lines are ignored. * The @IMPORT function imports the contents * of the specified filename into this file. * Global.gra is needed to define generic * DDTT test case script functions such as: * set, log, and loop @IMPORT \PATH\GLOBAL.GRA ******************************************** * CD_OPEN - * Open a channel to the CDROM device. * * Required Input Parameters: * DEVICENAME - Name of the CDROM drive * to open, i.e., E:. * * Output Parameters: * DRIVEHANDLE - Open Drive handle to * CDROM device. * ******************************************** CD_OPEN $DLL=DDTCDROM \ $FUNC=_cdrom_devopen \ DEVICENAME=STRING ******************************************** * CD_CLOSE - * Close channel to the CDROM device. * * Required Input Parameters: * DRIVEHANDLE - Open Drive handle to * CDROM device. * * Output Parameters: * -none- * ******************************************** CD_CLOSE $DLL=DDTCDROM \ $FUNC=_cdrom_devclose \ DRIVEHANDLE=NUM ******************************************** * CD_EJECT - * Eject disk from the CDROM drive. * * Required Input Parameters: * DRIVEHANDLE - Open Drive handle to * CDROM device. * * Output Parameters: * -none- * ******************************************** CD_EJECT $DLL=DDTCDROM \ $FUNC=_cdrom_eject \ DRIVEHANDLE=NUM ******************************************** * CD_PLAYAUDIO - * Play a selected audio track from the audio * CDROM. The starting location may be * specified in either Logical Block format * or Redbook (time offset) format. * * Required Input Parameters: * DRIVEHANDLE - Open Drive handle to * CDROM device. * ADDRESSMODE - Addressing mode, one of: * LOGICAL_BLOCK * REDBOOK - * minutes/seconds/frames * START_SECTOR - First block to play * END_SECTOR - Last block to play ******************************************** CD_PLAYAUDIO \ $DLL=DDTCDROM \ $FUNC=_cdrom_playaudio \ DRIVEHANDLE=NUM \ ADDRESSMODE=STRING \ START_SECTOR=ALNUM \ END_SECTOR=ALNUM ═══ 25.2.1. Sample Test Script ═══ * This is an example script file. It * includes most commands supported by the * parser. ******************************************** * @thread takes a filename as a parameter * to open as * the thread log file @thread test ******************************************** * @log accepts a string to be logged to the * log file specified in the immediately * preceding @thread command. All entries to * the log file are preceded with the current * date/time stamp taken from the system * real-time clock. @log "Beginning of thread 1" ******************************************** * @newalias takes a unique alias name and * name of device grammar file to be opened * for input @newalias mycd cdrom.scr ******************************************** * @import takes a filename as a parameter. * The filename is a script filename which * contains script commands that follow * conventions described in this file. @import filename ******************************************** * example device directive lines. The first * token is a previously opened @newalias * name, 2nd token is device specific * function keyword as declared in the device * grammar file. mycd CD_OPEN DEVICENAME=G: mycd CD_READFILE mycd cd_close mycd cd_open ******************************************** * The following commands/functions are * available to any grammar that imports * global.gra * For all global functions the first * token is a previously-opened alias name, * 2nd token is a generic function name. mycd set param_kwd=value mycd message "some string to be prompted" $pause=5 $response=MESSAGE_1 mycd log "Send this text to the log file." ═══ 25.2.2. Sample Function Stub Source ═══ * Name: APIRET _export sample_stub(Kwd_List param) * * Description: Sample stub function. * * Parameters: Kwd_List &. * * Returns: APIRET. * * Cautions: * *******************************************/ APIRET _export sample_stub(Kwd_List & param) { APIRET apiret; struct { BYTE one; BYTE two; BYTE three; } paramblock; ULONG ulParamsize = sizeof(paramblock); paramblock.one = param.getInt("ONE"); paramblock.two = param["TWO"]; paramblock.three = param.getPtr("THREE"); struct { BYTE data1; BYTE data2; } data; ULONG ulDataSize = sizeof(data); HFILE hfDrvHandle = param.getInt("DRIVEHANDLE"); apiret = ddtDosDevIOCtl(hfDrvHandle, 0x99, 0x99, ¶mblock, ulParamsize, &ulParamsize, &data, ulDataSize, &ulDataSize, "Sample Stub", "only call", param.files()->out1); // Let DDTT check the APIRET param.set("APIRET_00", (IString)apiret ); if (apiret == 0) { IString s1; s1 = "The result is:"; s1 += "\n\tdata1 :"; s1 += (LONG)data.data1; s1 += "\n\tdata2 :"; s1 += (LONG)data.data2; } return 0; } ═══ 26. Glossary ═══ This glossary contains terms and definitions that are, for the most part, used for OS/2 products. This is not a complete dictionary of computer terms. ═══ 26.1. Introduction ═══ This glossary defines many of the terms used in this book. It includes terms and definitions from the IBM Dictionary of Computing, as well as terms specific to the Presentation Manager, but it is not a complete glossary for OS/2. Other primary sources for these definitions are: o The American National Standard Dictionary for Information Systems, ANSI X3.172-1990, copyrighted 1990 by the American National Standards Institute, 11 West 42nd Street, New York, New York 10036. These definitions are identified by the symbol (A) after the definition. o The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions taken from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1. ═══ 26.2. Glossary Listing ═══ Select a starting letter of glossary terms: A N B O C P D Q E R F S G T H U I V J W K X L Y M Z ═══ Glossary - A ═══ A ABIOS - Advanced BIOS. See BIOS. accumulator - (1) A register in which one operand of an operation can be stored and subsequently replaced by the result of that operation. (T) (2) In the IBM 3800 Printing Subsystem Models 3 and 8, a feature that supplies a separate storage that can hold data in raster form. It can be used either for composing a sheet of data that combines a large amount of variable and constant data, or for storing an electronic overlay in raster form that will be merged with variable data as the sheet is printed. access permission - All access rights a user has regarding an object. (I) adapter - A piece of hardware that modifies the system unit to allow it to operate in a particular way, often by connecting the system unit to an external device such as a video monitor. adapter device driver - A device driver that provides hardware-dependent services for an OEM adapter. address space - (1) The range of addresses available to a program. (A) (2) The area of virtual storage available for a particular job. all points addressable (APA) - In computer graphics, pertaining to the ability to address and display or not display each picture element (pel) on a display surface. anchor block - An area of the internal resources of OS/2 Presentation Manager which is allocated to a process or thread that calls WinInitialize. anchor point - The position or choice from which selection or deselection is extended. APA - All points addressable. API - Application programming interface. application programming interface (API) - A functional interface supplied by the operating system, or by a separately-orderable licensed program, that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program. archive flag - In the OS/2 operating system, a flag of files and directories that the operating system uses to determine which files are new or modified. Files with this flag are included when a backup copy is made or when all the files are restored on a hard disk. See flag. area - In computer graphics, a filled shape such as a solid rectangle. ASCIIZ - A string of ASCII characters that is terminated with a byte containing the value 0. aspect ratio - (1) The ratio of the height of a rectangle to its width. A rectangle of width 10 inches and height 5 inches has an aspect ratio of 10/5 or 2. (2) On a display screen, the ratio of the maximum length of a display line to the maximum length of a display column. asynchronous (ASYNC) - (1) Pertaining to two or more processes that do not depend upon the occurrence of specific events such as common timing signals. (T) (2) Without regular time relationship; unexpected or unpredictable with respect to the execution of program instructions. atom - A constant that represents a string. Once a string has been defined as an atom, the atom can be used in place of the string to save space. Strings are associated with their respective atoms in an atom table. See integer atom. atom table - A table used to associate atoms with the strings that they represent. This table contains the mechanism by which the presence of a string can be verified. AVIO - Advanced Video Input/Output ═══ Glossary - B ═══ B background color - The color assigned to a background image. background mix - An attribute that determines how the background of a graphic primitive is combined with the existing color of the graphics presentation space. base device driver - An OS/2 device driver that performs I/O during the OS/2 kernel boot sequence to provide IPL support. Base device drivers are loaded by way of the CONFIG.SYS BASEDEV keyword, rather than the DEVICE keyword. See BASEDEV keyword, adapter device driver, and device manager. BASEDEV keyword - New CONFIG.SYS keyword; loads a base device driver into the operating system. Basic Input/Output System (BIOS) - Code that controls basic hardware operations, such as interactions with diskette drives, hard disk drives, and the keyboard. Bezier curve - A mathematical technique of specifying a smooth, continuous line or surface, requiring a starting point and an ending point, with several intermediate points that influence or control the path of the linking curve. BIOS - Basic Input/Output System. bit-block transfer (bitblt) - Transfer of a rectangular array of bit-map data. bitblt - Bit-block transfer. bit map - A representation of an image by an array of bits. block - (1) In programming languages, a compound statement that coincides with the scope of at least one of the declarations contained within it. A block may also specify storage allocation or segment programs for other purposes. (I) (2) A string of data elements recorded or transmitted as a unit. The elements may be characters, words or physical records. (T) (3) A collection of contiguous records recorded as a unit. Blocks are separated by interblock gaps and each block may contain one or more records. (A) Bit block transfer (bitblt) - The process of transferring one or more blocks of data. border - A visual indicator of a window's boundaries. BPB - BIOS Parameter Block. breakpoint - (1) A point in a computer program where execution may be halted. A breakpoint is usually at the beginning of an instruction where halts, caused by external intervention, are convenient for resuming execution. (T) (2) An instruction in a program for halting execution. Breakpoints are usually established at positions in a program where halts, caused by external intervention, are convenient for restarting. (T) (3) A place in a program, specified by a command or a condition, where the system halts execution and gives control to the workstation user or to a specified program. Bus Master adapter - An adapter capable of performing Reads and Writes to physical storage by communicating directly with the storage subsystem (memory) rather than depending on a host DMA channel or host CPU. Synonymous with first-party DMA adapter. ═══ Glossary - C ═══ C cached micro presentation space - A presentation space from a Presentation Manager owned store of micro presentation spaces. It can be used for drawing to a window only, and must be returned to the store when the task is complete. CDB - Command Descriptor Block. cell - See character cell. character box - (1) An imaginary parallelogram on a display surface that contains all parts of one graphic character. Synonymous with bounding box. (T) (2) The maximum area in which a symbol and all associated elements, such as a cursor, an underline, or space surrounding the symbol to separate it from other symbols, can be printed or displayed. Synonymous with character cell. (3) The imaginary parallelogram whose boundaries govern the size, orientation, and spacing of individual characters to be displayed on a graphics display device. character cell - (1) An addressable location on a display surface or printing medium. (2) The physical width and height in pels of a font. See also bounding box. (3) The imaginary box whose boundaries govern the size, orientation, and spacing of individual characters to be displayed on a workstation. character mode - A mode that, in conjunction with the font type, determines the extent to which graphics characters are affected by the character box, shear, and angle attributes. clipping - In computer graphics, removing those parts of display elements that lie outside of given boundary. clip limits - The area of the paper that can be reached by a printer or plotter. clipping path - A clipping boundary in world-coordinate space. code page - An assignment of graphic characters and control function meanings to all code points; for example, assignment of characters and meanings to 256 code points for an 8-bit code, assignment of characters and meanings to 128 code points for a 7-bit code. code point - A 1-byte code representing one of 256 potential characters. code segment - An executable section of programming code within a load module. color conversion - Changing one color format to another. Required, for example, when the source color format is different from the destination color format. When going from the monochrome color format to the color format, 1 (one) bits are converted to the image foreground color, and 0 (zero) bits are converted to the image background color. When going from color to monochrome, all pels that match the passed background color are converted to the image background color of the destination. All other pels are converted to the image foreground color of the destination. The color conversion takes place prior to any mix mode. color dithering - See dithering. command code - In this specification, refers to a group of related commands that an adapter device driver can receive. All command codes have a prefix of "IOCC_". For example, common I/O requests (such as Read, Write, etc.) are grouped under the command code IOCC_EXECUTE_IO. command data block - A data structure defined by the Small Computer System Interface standard to send commands to devices that conform to SCSI standards. command descriptor block (CDB) - The structure used to communicate commands from a source to a destination. command modifier - In this specification, a specific operation that an adapter device driver is to perform. All command modifiers have a prefix of "IOCM_". For example, an adapter device driver might receive an IOCC_EXECUTE_IO command with a command modifier of IOCM_READ. compatibility kernel - The portion of the OS/2 kernel that exists to support DOS INT 20, 21, 25, 26, and 27 functions. It acts as an interface to common kernel functionality such as the file system. CON - Character-device name reserved for the console keyboard and screen. conditional compilation - Processing by the preprocessor of certain specified code in the file, depending on the evaluation of a specified condition. context hook - Similar to a "force flag" in earlier versions of OS/2. These are events, signaled by a virtual device driver, that are processed at task time. Forcing an IRET, and simulating an NMI, can fall into this category. control program - A computer program designed to schedule and to supervise the execution of programs of a computer system. controller sector buffer - One or more buffers, managed by a hardware adapter, to improve I/O transfer rates by helping to match a device and software timing requirements. ═══ Glossary - D ═══ D DASD - Direct-access storage device. data bus - A bus used to communicate data internally and externally to and from a processing unit, storage, and peripheral devices. (A) See bus. data structure - The syntactic structure of symbolic expressions and their storage allocation characteristics. (T) DBCS - Double-byte character set. DC - Device context. DDB - Device-dependent bit map. deinstantiation - See instantiation. DevHlp - Device helper. device context (DC) - A logical description of a data destination such as memory, metafile, display, printer, or plotter. See also direct device context, information device context, memory device context, metafile device context, and screen device context. device driver - A file that contains the code needed to attach and use a device such as a display, printer, or plotter. device driver initialization (init) time - See initialization (init) time, device driver. device driver profile - A file with a "DDP" extension, containing a script that is interpreted by the OS/2 DDINSTAL utility. Among other things, it defines which files to copy from installation diskettes to target directories and specifies how the CONFIG.SYS file will be updated. device helper (DevHlp) - (1) A kernel service (memory, hardware interrupt, software interrupt, queuing, semaphore, and so forth) provided to physical device drivers. (2) A callable C-language or assembler-language routine that provides an operating system service for an OS/2 device driver. device object - A device that provides a means of communication between a computer and the outside world. A printer is an example of a device object. device table - A data structure containing a summary of the adapters an adapter device driver supports and a list of the I/O devices attached to each adapter. This data structure is built by the adapter device driver in response to an IOCC_CONFIGURATION IOCM_GET_DEVICE_TABLE request. direct access storage device (DASD) - A device in which access time is effectively independent of the location of the data. direct memory access (DMA) - (1) A technique for moving data directly between main storage and peripheral equipment without requiring processing of the data by the processing unit. (2) The transfer of data between memory and input/output units without processor intervention. display frame - (1) In computer graphics, an area in storage in which a display image can be recorded. (2) In computer micrographics, an area on a microform in which a display image can be recorded. dispatch table - (1) A block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. (2) An array of pointers to function-handling routines. dithering - A technique for interleaving dark and light pels so that the resulting image looks smoothly shaded from a distance. DLL - Dynamic link library. DMA - Direct memory access. double-byte character set (DBCS) - A set of characters in which each character is represented by two bytes. Languages such as Japanese, Chinese, and Korean, which contain more characters than can be represented by 256 code points, require double-byte character sets. Because each character requires 2 bytes, the typing, display, and printing of DBCS characters requires hardware and programs that support DBCS. Contrast with single-byte character set. driver - (1) A program (and possibly data files) that contain information needed to run a particular unit, such as a plotter, printer, port, or mouse. See also device driver and printer driver. (2) A system or device that enables a functional unit to operate. dynamic link library (DLL) - A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously. ═══ Glossary - E ═══ E entry point - (1) In a database, the record that is first accessed upon entry into a database, caused by a user's command. (T) (2) The address or label of the first instruction executed on entering a computer program, routine, or subroutine. A computer program, routine, or subroutine may have a number of different entry points, each perhaps corresponding to a different function or purpose. (I) (A) Synonymous with entrance, entry. (3) In a routine, any place to which control can be passed. (A) (4) In the C, FORTRAN, and Pascal languages, the address or label of the first instruction processed or entered in a program, routine, or subroutine. A program, routine, or subroutine can have a number of different entry points, each corresponding to a different function or purpose. EOI - End Of Interrupt ═══ Glossary - F ═══ F Far call - Code that calls from one segment into another segment. fillet - An arc that is tangential to the end points of two adjacent lines. See also polyfillet. filter adapter device driver - A special class of adapter device drivers that do not manage the hardware directly, but monitor the stream of commands between a device manager and an adapter device driver. See Device Manager and adapter device driver. first-party DMA adapter - See bus master adapter. flag - A characteristic of a file or directory that enables it to be used in certain ways. See also archive flag, hidden flag, and read-only flag. flat address - See linear address. frame styles - Standard window layouts provided by the Presentation Manager. freeze and thaw services - Functions that prevent a DOS session from executing (VDHFreezeVDM) until the matching thaw function (VDHThawVDM) is called. The freeze occurs when the specified DOS session leaves kernel mode. ═══ Glossary - G ═══ G GDT - Global descriptor table. Global Descriptor Table (GDT) - A table that defines code and data segments available to all tasks in an application. glyph - A graphic symbol whose appearance conveys information; for example, the vertical and horizontal arrows on cursor keys that indicate the directions in which they control cursor movement, the sunburst symbol on the screen illumination control of a display device. GPI - Graphics programming interface graphic primitive - In computer graphics, a basic element, such as an arc or a line, that is not made up of smaller parts and that is used to create diagrams and pictures. graphics attributes - The attributes that apply to graphics primitives. Examples are color selection, line type, and shading pattern definition. Contrast with segment attributes. Graphics programming interface (GPI) - The formally-defined programming language that lies between an IBM graphics program and the user of the program. graphics segment - A sequence of related graphic primitives and graphics attributes. See also graphic primitive. GRE - Graphics engine. ═══ Glossary - H ═══ H handle - (1) An identifier that represents an object, such as a device or a window, to the Presentation Interface. (2) In the Advanced DOS and OS/2 operating systems, a binary value created by the system that identifies a drive, directory, and file so that the file can be found and opened. handshaking - A method by which two pieces of hardware, such as a personal computer and a plotter, can communicate. Depending upon the devices communicating, handshaking occurs either as a hardware function or through software, such as a device driver. hard error - An error condition on a network that requires that the network be reconfigured or that the source of the error be removed before the network can resume reliable operation. hardware palette - The array of RGBs that the physical device is displaying. heap - An area of free storage available for dynamic allocation by an application. Its size varies depending on the storage requirements of the application. hex - See hexadecimal hexadecimal - Pertaining to a system of numbers to the base 16; hexadecimal digits range from 0 through 9 and A through F, where A represents 10 and F represents 15. hook - A point in a system-defined function where an application can supply additional code that the system processes as though it were part of the function. hook chain - A sequence of hook procedures that are "chained" together so that each event is passed in turn to each procedure in the chain. ═══ Glossary - I ═══ I IDC - Inter-device-driver communication. in-memory buffer - A block of memory in the address space of the host machine, used for data transfer. init time - See initialization time, device driver. initialization time, device driver - After the OS/2 loads a device driver, it sends it an OS/2 request packet to initialize. During this initialization, certain DevHlp functions are not permitted. Also called init time. Input/Output Control (IOCtl) - A system service that provides a way for an application to send device-specific control commands to a device driver. Input/Output Privilege Level (IOPL) - Allows part of a Ring 3 application or device driver to execute at Ring 0. input router - OS/2 internal process that removes messages from the system queue. inter-device-driver communication (IDC) - A mechanism that enables a physical device driver to communicate with another physical device driver. interprocess communication - In the OS/2 operating system, the exchange of information between processes or threads through semaphores, queues, and shared memory. interrupt - An instruction that directs the microprocessor to suspend what it is doing and run a specified routine. When the routine is complete, the microprocessor resumes its original work. See also routine. interrupt request (IR) - Broadly, an "interrupt request level", referring to pending or in-service interrupt requests, or to a specific level (for example, IR 4). interrupt request flag - A bit in the 8259 PIC controller that indicates an interrupt is pending on particular level. The VPIC also maintains a virtual interrupt request flag for each interrupt level for each DOS session. interrupt service flag - A bit in the 8259 PIC controller that indicates an interrupt request is being serviced. It is cleared when the PIC is sent EOI. The VPIC maintains a virtual interrupt service flag indicating that a simulated interrupt is in-progress in a DOS session. interrupt time - When a device driver is run because of an interrupt rather than because of an application request. OS/2 device drivers receive interrupts either from the hardware they manage or from the system real-time clock. During interrupt time, certain DevHlp functions are not permitted. Also, addresses received directly from OS/2 applications might not be valid unless they are converted system addresses. IOCtl - Input/Output Control. IOPL - Input/Output Privilege Level. IORB - Input/Output Request Block. Input/Output Request Block (IORB) - A data structure defined by this specification that is passed as a parameter on all calls to an adapter device driver. It contains a fixed section, followed by a command-dependent section. IORBH - Input/Output Request Block Header IRET - Interrupt return. IRQ - Interrupt Request. ═══ Glossary - J ═══ J journal - A special-purpose file or data set that can be used to provide an audit trail of operator and system actions, or as a means of recovering superseded data. ═══ Glossary - K ═══ K kanji - A graphic character set consisting of symbols used in Japanese ideographic alphabets. Each character is represented by 2 bytes. kernel - (1) The part of an operating system that performs basic functions such as allocating hardware resources. (2) A program that can run under different operating system environments. kerning - The design of graphic characters so that their character boxes overlap. The toned picture elements (pels) of the character appear outside the character cell. Note: Kerning allows character boxes to overlap and characters to run together, so that characters can be designed for cursive languages, ligatures, or any other kind of character that requires more than one character box. It also allows for design of proportional-spaced fonts. By overlapping character boxes, characters can be placed closer together, or they can be placed farther apart by using overlapped blank character boxes. ═══ Glossary - L ═══ L LCT - logical color table. LDT - Local descriptor table. LIFO stack - A data structure from which data is retrieved in "Last-In, First-Out" order. linked list - A list in which the data elements may be dispersed, but in which each data element contains information for locating the next. Synonym for chained list. linear address - A unique value that identifies the memory object. Local Descriptor Table (LDT) - A table that defines code and data segments specific to a single task. logical palette - An array of RGB and mapping index pairs, created by the device driver when defining a palette (as a result of a GpqCreatePalette call). LVB - Logical Video Buffer. ═══ Glossary - M ═══ M memory device context - A logical description of a data destination that is a memory bit map. See also device context. metafile - A file containing a series of attributes that set color, shape, and size, usually of a picture or a drawing. Using a program that can interpret these attributes, a user can view the assembled image. metafile device context - A logical description of a data destination that is a metafile which is used for graphics interchange. See also device context. mickey - A unit of measurement for physical mouse motion whose value depends on the mouse device driver that is currently loaded. mixed character string - A string containing a mixture of one-byte and kanji or Hangeul (two-byte) characters. mutex semaphore - (Mutual exclusion semaphore). A semaphore that enables threads to serialize their access to resources. Only the thread that currently owns the mutex semaphore can gain access to the resource, thus preventing one thread from interrupting operations being performed by another. ═══ Glossary - N ═══ N named pipe - A named buffer that provides client-to-server, server-to-client or duplex communication between unrelated processes. Contrast with unnamed pipe. notification callout - The feature that provides for a routine to be called on completion of an input/output request. See also notification routine. notification routine - The routine indicated in an input/output request block to be called on completion of that request. See also notification callout. null-terminated string - A string of (n+1) characters where the (n+1)th character is the "null" character (X'00') and is used to represent an n-character string with implicit length. Also called a "zero-terminated" string or an "ASCIIZ". string. ═══ Glossary - O ═══ O ═══ Glossary - P ═══ P palette - A list of colors assigned to various areas on a panel. A user can change the color of these areas. PDD - Physical Device Driver. PDE - PageDirectoryEntry. pel - Picture element. permissible action - In a conceptual schema language, an action conforming to specified rules or constraints that changes a presumably consistent collection of sentences into a consistent one or makes known a consistent one present in the information base or conceptual schema. phase alignment - Aligning source bits with destination bits. Often required in a Bitblt function move operation where byte blocks are moved on bit boundaries. physical address - A 32-bit byte address giving the actual address in physical storage for a data item. physical device driver (PDD) - A system interface that handles hardware interrupts and supports a set of input and output functions. pipe - See named pipe, unnamed pipe. picture element (pel, pixel) - (1) In computer graphics, the smallest element of a display surface that can be independently assigned color and intensity. (T). (2) The area of the finest detail that can be reproduced effectively on the recording medium. (3) An element of a raster pattern about which a toned area on a photoconductor can appear. PIO - Programmed I/O. pixel - Picture element. polyfillet - A curve based on a sequence of lines. The curve is tangential to the end points of the first and last lines, and tangential also to the midpoints of all other lines. polyline - In computer graphics, a sequence of adjoining lines. pop - To remove an item from the top of a pushdown list. Contrast with push. prefetch - To locate and load a quantity of data in anticipation of a request. presence-check function - A Ring 3 (non-privileged) .EXE program that determines whether a given hardware interface is present on a workstation. PRESENCECHECK - A keyword, interpreted by the DDINSTAL utility, to determine whether to process the device driver profile file, based on the return code from PRESENCECHECK. printer driver - A file that describes the physical characteristics of a printer, plotter, or other peripheral device, and is used to convert graphics and text into device-specific data at the time of printing or plotting. Print Manager - In the Presentation Manager, the part of the spooler that manages the spooling process. It also allows the user to view print queues and to manipulate print jobs. privilege level - A method of protection that allows only certain program instructions to be used by certain programs. program group - Several programs that can be acted upon as a single entity. protect mode - A method of program operation that limits or prevents access to certain instructions or areas of storage. Contrast with real mode. push - To add an item to the top of a pushdown list. Contrast with pop. ═══ Glossary - Q ═══ Q queued device context - A logical description of a data destination (for example, a printer or plotter) where the output is to go through the spooler. See also device context. ═══ Glossary - R ═══ R read-only memory basic input/output system (ROM-BIOS) - Microcode in read-only memory that controls basic input/output operations such as interactions with cassettes, diskette drives, hard disk drives, and the keyboard. See also BIOS, NetBIOS. Note: ROM BIOS allows the user to write programs and add or remove devices without concern for characteristics such as device addresses. real mode - In the OS/2 operating system, a method of program operation that does not limit or prevent access to any instructions or areas of storage. The operating system loads the entire program into storage and gives the program access to all system resources. reentrant - The attribute of a program or routine that allows the same copy of the program or routine to be used concurrently by two or more tasks. removable-media indicator - A flag (bit) indicating that a device permits media removal. resource - The means of providing extra information used in the definition of a window. A resource can contain definitions of fonts, templates, accelerators and mnemonics; the definitions are held in a resource file. resurrection - The Presentation Manager event that occurs when switched back from a full-screen DOS or WIN-OS/2 session. RETF - Return far. reverse video - A form of highlighting a character, field, or cursor by reversing the color of the character, field, or cursor with its background; for example, changing a red character on a black background to a black character on a red background. ROM BIOS - Read-Only Memory Basic Input/Output System. ROP - Raster operation. RTC - Real-Time Clock. ═══ Glossary - S ═══ S SBCS - Single-byte character set SCB - See subsystem control block architecture. screen device context - A logical description of a data destination that is a particular window on the screen. See also device context. SCSI - Small Computer System Interface. seamless windows - An architecture contained within OS/2 which permits one or more applications to share windowed desktop graphical space and other resources, while executing concurrently. Application session windows managed by seamless windows can share border information, and pointing device transitions from session to session are handled smoothly and transparently. second-party DMA adapter - See DMA slave. semaphore - (1) A variable that is used to enforce mutual exclusion. (T) (2) An indicator used to control access to a file; for example, in a multiuser application, a flag that prevents simultaneous access to a file. (3) An entity used to control access to system resources. Processes can be locked to a resource with semaphores if the processes follow certain programming conventions. sense data - Data which describes an I/O error as defined by the ANSI SCSI specifications. single-byte character set (SBCS) - A character set in which each character is represented by a one-byte code. Contrast with double-byte character set. Small Computer System Interface (SCSI) - An input and output bus that provides a standard interface between the OS/2 multimedia system and peripheral devices. spline curve - In computer graphics, a shape created when a user specifies a series of points and the computer software draws a curve that smoothly approaches those points. spooler - A program that intercepts data going to a device driver and writes it to a disk. The data is later printed or plotted when the required device is available. A spooler prevents output from different sources from being intermixed. synchronous - Pertaining to two or more processes that depend upon the occurrence of specific events such as common timing signals. ═══ Glossary - T ═══ T text window - See VIO window. thread - The smallest unit of operation to be performed within a process. thunk - term used to describe the process of address conversion, stack, and structure realignment that is necessary when passing control between 16-bit and 32-bit modules. thunk layer - An interface that converts 32-bit parameters to 16-bit parameters, and maps linear addresses to segmented addresses. time slice - (1) The period of processing time allocated for running a program. (2) An interval of time on the processing unit allocated for use in performing a task. After the interval has expired, processing unit time is allocated to another task, so a task cannot monopolize processing unit time beyond a fixed limit. tuple - In a relational database, a part of a relation that uniquely describes an entity and its attribute. ═══ Glossary - U ═══ U unnamed pipe - A circular buffer created in memory; used by related processes to communicate with one another. Contrast with named pipe. ═══ Glossary - V ═══ V VBIOS - Virtual BIOS device driver VCMOS - Virtual CMOS device driver VDD - Virtual device driver VDH - Virtual video Device Handler VDM - Virtual DOS Machine; use DOS session. VDMA - Virtual Direct Memory Access device driver VDSK - Virtual hard DiSK device driver video graphics adapter (VGA) - A computer adapter that provides high-resolution graphics and a total of 256 colors. VIO - Virtual Input/Output VIRR - Virtual Interrupt Request Register Virtual Device Driver (VDD) - In the OS/2 operating system, a type of device driver used by DOS programs running in a DOS session to access devices, such as the screen or mouse, which must be shared with other processes in the system. The virtual device driver maps DOS device commands to the normal (physical) device driver under OS/2 2.0 and later versions of the operating system. virtual DevHlp (VDH) - Kernel (linear memory, paging, hardware interrupt, event control, port control) services provided to virtual device drivers. virtual I/O (VIO) - A facility that pages data into and out of external page storage. virtual memory - Synonym for virtual storage. Virtual Programmable Interrupt Controller - Virtualizes the 8259 Programmable Interrupt Controller (PIC). A special virtual device driver, in that it provides services to other virtual device drivers. virtual storage - Addressable space that is apparent to the user as the processor storage space, from which the instructions and the data are mapped into the processor storage locations. Synonymous with virtual memory. visible region - A window's presentation space clipped to the boundary of the window and the boundaries of any overlying window. VPIC - Virtual Programmable Interrupt Controller device driver. VRAM - Video Random-Access Memory. VTIMER - Virtual TIMER device driver. V86 mode - Virtual 8086 mode of the 80386 CPU. ═══ Glossary - W ═══ W window coordinates - A set of coordinates by which a window position or size is defined; measured in device units, or pels. ═══ Glossary - X ═══ X ═══ Glossary - Y ═══ Y There are no glossary terms for this initial letter. ═══ Glossary - Z ═══ Z