Storage Device Driver Reference

Storage Device Driver Reference

About This Book Introduction to DASD, SCSI, and CD-ROM Programming Interfaces Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers Adapter Device Driver Development Considerations DASD, SCSI, and CD-ROM Device Manager Interface Specification Error Handling Adapter Device Driver Command-Line Parameters DASD IOCtl Device Driver Test Tool Optical IOCtl Device Driver Test Tool Using Filter Device Drivers Library and Services CD-ROM Device Manager Interface Specification CD-ROM Device Driver Test Tool Building an OS/2 Virtual Disk Driver OS2DASD.DMD - Technical Reference Boot Record Architecture Extended Device Driver Interface Specification I/O Request Block - C Definitions OS/2 SCSI Device Driver Interface Specification Advanced SCSI Programming Interface (ASPI) OS/2 Specification Adapter Device Driver Interface Questions and Answers Device Driver Test Tool (DDTT) Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

About This Book

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

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

Summary of Changes

The following changes have been made:

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

How This Book is Organized

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

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

Assistance

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

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

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

Internet: ibmsdp@vnet.ibm.com

US/Canada: 800-627-8363

International: 770-835-9902

International Fax: 770-835-9444

Notices

Fifth Edition (September 1997)

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

Copyright Notices

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

Disclaimers

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

IBM Director of Licensing

IBM Corporation

500 Columbus Avenue

Thornwood, NY 10594 U.S.A.

Trademarks

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

AIX

AT

Common User Access CUA

IBM Micro Channel

Multimedia Presentation Manager/2

OS/2

Personal System/2 PS/2

SAA

Series/1

Systems Application Architecture

The following terms are trademarks of other companies:

Adaptec Adaptec, Inc.

APM Astek International Ltd.

Apple Apple Computer, Inc.

Hitachi Hitachi Ltd.

Intel Intel Corporation

MSCDEX Microsoft Corporation

NEC NEC Corporation

Novell Novell, Inc.

Photo CD Eastman Kodak Company

RIPL CTA Incorporated

SCO The Santa Cruz Operation, Inc.

Sony Sony Corporation

Toshiba Toshiba Corporation

UNIX Unix System Laboratories, Inc.

XENIX Microsoft Corporation