Storage Device Driver Reference
By IBM
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
About This Book
The Storage Device Driver Reference provides a simplified programming interface to expedite the development of DASD, SCSI, and CD-ROM device driver support for the IBM OS/2 product.
Frequently, original equipment manufacturers (OEMs) develop device support to drive only their own unique device interfaces and the support may be hardware-dependent. The programming interfaces described in this reference categorize the DASD, SCSI, and CD-ROM device-driver modules as hardware-dependent or hardware-independent. Hardware-independent modules can be linked dynamically with hardware-dependent modules for a given workstation configuration.
Summary of Changes
The following changes have been made:
- Added a new chapter, Optical IOCtl Device Driver Test Tool.
- Removed chapters on Device Driver Test Tools, which described the 16-bit support: DASD IOCtl, DASD ADD, SCSI IOCtl, SCSI ADD, and CD-ROM.
- Added replacement chapters, describing the 32-bit support, for DASD IOCtl and CD-ROM Device Driver Test Tools.
How This Book is Organized
- #Notices contains trademark and service mark notices and information.
- Introduction to DASD, SCSI, and CD-ROM Programming Interfaces introduces the OS/2 DASD,SCSI, and CD-ROM programming interfaces for OEM device support, and describes what they are and what they are not. It shows the organization of the code, and presents various types of device drivers, device managers, adapter device drivers, and filter device drivers.
- Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers describes key design points and the strategies for addressing them. The BASEDEV keyword, introduced in OS/2 2.0, is described. This chapter describes system and adapter device driver installations along with the presence-check function.
- Adapter Device Driver Development Considerations covers pertinent considerations when developing adapter device drivers, such as loading, initialization, and operation.
- DASD, SCSI, and CD-ROM Device Manager Interface Specification presents the Direct Call Commands used with the DASD, SCSI, and CD-ROM device manager interface specification and the available device helpers (DevHlps). It covers I/O request blocks (IORBs) and their configuration, along with detailed descriptions of command codes, command modifiers, control blocks, and data structures.
- Error Handling contains a summary of all the adapter device driver error codes and guidelines for their usage.
- Adapter Device Driver Command-Line Parameters presents the adapter device driver command-line parameters and structures, including syntax conventions and specific parameter information for the various bus interfaces.
- DASD IOCtl Device Driver Test Tool discusses the DASD IOCtl Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of DASD drivers. These tests are implemented with the Device Driver Test Tool.
- Optical IOCtl Device Driver Test Tool discusses the optical IOCtl Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for optical device drivers. The tests are implemented with the Device Driver Test Tool.
- Using Filter Device Drivers presents filter device drivers and the strategies for providing filter functions.
- Library and Services provides a complement of library services for common adapter device driver tasks.
- CD-ROM Device Manager Interface Specification provides CD-ROM specific device driver support information.
- CD-ROM Device Driver Test Tool discusses the Application Program Interfaces (APIs) defined for the interface of CD-ROM drivers.
- Building an OS/2 Virtual Disk Driver describes how to program and build an OS/2 virtual disk driver.
- OS2DASD.DMD - Technical Reference describes how the OS2DASD Manager provides support for fixed and removable magnetic disks.
- Boot Record Architecture describes how to install, create, and delete block devices in the Extended DOS partition. This appendix also discuss BIOS Parameter Blocks and Get Device Parameters for Extended Volumes.
- Extended Device Driver Interface Specification describes the supports for servicing fixed disk devices.
- I/O Request Block - C Definitionslists the I/O request block C language definitions for adapter device driver device support.
- OS/2 SCSI Device Driver Interface Specification describes the high-level interface for the SCSI device driver for OS/2. All functions are listed.
- Advanced SCSI Programming Interface (ASPI) OS/2 Specification describes the advanced SCSI programming interface (ASPI) OS/2 specification. The information was provided by Adaptec Corporation.
- Adapter Device Driver Interface Questions and Answers covers the most commonly asked questions about adapter device driver interfaces. The answers are presented in detail.
- Device Driver Test Tool (DDTT) describes how to use the Device Driver Test Tool in different environments.
A glossary and an index appear at the back of the book.
Assistance
Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.
To access the DDSC, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.
Additional assistance is available through the IBM Solution Developer Program. For membership information:
- Internet: ibmsdp@vnet.ibm.com
- US/Canada: 800-627-8363
- International: 770-835-9902
- International Fax: 770-835-9444
Introduction to DASD, SCSI, and CD-ROM Programming Interfaces
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
A complement of library services for common adapter device driver tasks is provided in the IBM Device Driver Source Kit for OS/2. This adapter device driver library includes a set of functions that can be statically linked with an adapter device driver at build time.
These library services are provided in both source and object form. This code is in the \addcalls and \devhelp subdirectories of the \src tree. You can modify and extend this code to suit your needs.
The DevHlp services are provided with FAR code and data-calling convention support. Adapter Device Driver Calls services are generally provided with both FAR and NEAR calling-convention support.
The library services include the following:
- 'C' interface to the DevHlp kernel services
- Timer services
- Scatter/gather buffer transfers
- RBA <-> CHS computations
- DMA setup and channel control, ISA bus machines
- Command line parsing
See the headers of the individual functions for a detailed description of function services and their calling conventions.
Command-Line Parsing
To facilitate parsing of command-line parameters and to help encourage uniformity in command-line syntax, a parser/tokenizer is provided in the IBM Device Driver Source Kit for OS/2. See Adapter Device Driver Command-Line Parameters for a command-line syntax definition.
The output of the parser/tokenizer is a stream of tokens that represent the contents of the command line. The parser/tokenizer performs preliminary syntactical checks on the command line and indicates the results of these checks in return codes.
As with the other library services provided in the IBM Device Driver Source Kit for OS/2, you can modify the parser and its included tables to add adapter-unique flags and parameters.
CD-ROM Device Manager Interface Specification
CD-ROM Device Driver Test Tool
Building an OS/2 Virtual Disk Driver
This chapter describes how to program and build an OS/2 virtual disk driver. In order to successfully build a virtual disk driver, should be familiar with the OS/2 2.0 operating system or later, and have previous experience developing OS/2 device drivers.
In the IBM Developer Connection Device Driver Kit for OS/2, you will find an OS/2 virtual disk driver. After reading this chapter and examining the code, you can use this information to write your own virtual device driver.
Virtual Disk Driver Code
The virtual disk driver code provides access to a virtual disk in random access memory. The virtual disk driver runs in a multi-tasking environment and is a protected resource.
In this chapter you will find:
- A table listing the virtual disk parameters
- A table listing the virtual disk commands
- An explanation of how the virtual disk initialization routine works
- Information for performing time-critical tasks
- A procedure for building the virtual disk device driver code that is provided with the IBM Device Driver Source Kit for OS/2
Using the Virtual Disk Parameters: To allocate the virtual disk driver volume, modify the following device statement in the CONFIG.SYS file.
DEVICE = .\PATHNAME\VDISK.SYS [bbbb] [ssss] [dddd]
Where: bbbb Determines the disk size in K bytes. The default value is 64KB. The minimum is 16KB. The maximum is 524 288 (512MB). ssss Determines the sector size in bytes. The default value is 128. Acceptable values are increments of 128 which include 128, 256, 512, and 1024. dddd Determines the number of root directory entries. The default is 64; with a minimum of 2 and a maximum of 1024. The value is rounded up to the nearest sector size boundary. The virtual disk driver adjusts the value of dddd to the nearest sector size boundary. For example if you give a value of 25, and the sector size is 512 bytes, 25 will be rounded up to 32 which is the next multiple of 16. The parameters you use to specify byte and sector size and the number of directory entries are positional parameters. This means that if you omit a parameter, you should not leave it blank. You should use a comma in the parameter field to separate this field from the next. The only time you can use blank spaces as separators is in the instance where you are coding blanks for all the parameters. In the event that there is not enough memory to create the virtual disk driver volume, the driver attempts to create a DOS volume with 16 directory entries. This may result in a volume with a different number of directories than you specified on the device statement (dddd). To ensure system reliability, specify 32 megabytes or less for disk size. Example 1
C:\OS2\VDISK.SYS ,128,64
where the disk size is 64KB, the sector size is 128 bytes, and there are 64 directory entries. Example 2
C:\OS2\VDISK.SYS 2048,,32
where the disk size is 2 048 KB, the sector size is 128 bytes, and there are 32 directory entries. Example 3
C:\OS2\VDISK.SYS 2048,512,
where the disk size is 2 048 KB, the sector size is 512 bytes, and there are 64 directory entries. Example 4
C:\OS2\VDISK.SYS ,128,32
where the disk size is 64 KB, the sector size is 128 bytes, and there are 32 directory entries. Supported Physical Device Driver Strategy Commands: The virtual disk driver is a block device driver and cannot be partitioned. For this reason , the virtual disk driver uses a limited set of physical device driver strategy commands. These are listed below: CodeFunction 0hInit 1hMedia Check 2hBuild BPB 4hRead (Input) 8hWrite (Output) 9hWrite With Verify DhOpen Device EhClose Device FhRemovable Media 10hGeneric IOCtl 11hReset Media 12hGet Logical Drive Map 13hSet Logical Drive Map 1AhNo Caching (Write With Verify) 1DhGet Driver Capabilities If the virtual disk driver uses any commands other than those shown above, the driver returns an unknown command error code. For more information on these commands, refer to the OS/2 Physical Device Driver Reference. The virtual disk driver supports the Extended Device Driver Interface which is implemented through the Get Driver Capabilities command. This interface issues a Request List of prioritized commands. VDisk_Strat2, specified in the driver capabilities structure, is the entry point for all the commands. CHKDSK uses the category 08h and function 63h IOCtl command from the kernel . This is the only command supported by the virtual disk driver in the general IOCtl commands category. Virtual Disk Driver Initialization: The virtual disk driver initialization routine does the following:
- Initializes various global values and initializes the DevHelp function router address.
- Parses the command line and sets the values accordingly.
The "DEVICE = xxxxxxxxx" line pointer provided in request packet searches for the various device parameters. The pointer searches through the device name field to obtain the arguments. Then the pointer parses the arguments as they are encountered. All parameter errors are detected at this time. The static initialization routine sets the parameter variables to the default settings.
- Allocates the memory for the virtual disk driver.
The routine issues the DevHlp_VMAlloc command to allocate random access memory for the virtual disk driver.
- Initializes the DOS volume in random access memory for the virtual disk driver.
To so, the routine sets the BPB and initializes the RESERVED (boot) sector, FAT sectors, and root directory sectors and writes them to the virtual disk driver. First the routine initializes the BPB values. Then the routine writes the BOOT record, containing the BPB, to sector 0. The routine writes to a FAT file with all of the clusters free, and writes to the root directory with ONE entry (the Volume ID at VOLID).
- Prints a report of the RAMDrive parameters.
You can print the BPB values. To do so, use the DosGetMessage and DosPutMessage functions in your virtual disk driver. From this report, you can determine the device size, cluster size, and directory size.
- Specifies the return INIT I/O packet values.
The INIT I/O packet return values for number of units are set, as well as the BPB array pointer.
At any time during the initialization steps an error may be detected. When this happens, the system prints an error message. The virtual disk driver uninstalls and returns a unit count of 0 in the INIT device I/O packet.
Performing Time-Critical Tasks: To perform time-critical tasks, you must call the DevHlp_GetDOSVar service from the virtual disk driver code. The virtual disk driver periodically checks the TCYield flag and calls the TCYield function to yield the CPU to a time-critical thread. The location of the TCYield flag is obtained from a call to DevHlp_GetDosVar. The virtual disk driver checks the TCYield flag each time 32,768 bytes of data have been transferred. Refer to the OS/2 Physical Device Driver Reference for more information.
Building the OS/2 2.0 (and later) Virtual Disk Driver sample code: To build the sample virtual disk driver code, complete the following steps:
- Add the TOOLS directory to the OS/2 IBM Developer Connection Device Driver Kit for OS/2 and set it to the current path.
- Set the TMP environment variable to point to a work area. This is shown below:
SET TMP=E:\
3. NMAKE the following makefiles in the DDK:
SRC\DEV\VDISK\MAKEFILE CD\DDK\SRC\DEV\VDISK NMAKE
OS2DASD.DMD - Technical Reference
Boot Record Architecture
Extended Device Driver Interface Specification
I/O Request Block - C Definitions
Following are the I/O request block C language definitions for ADD device support.
/*static char *SCCSID = "@(#)iorb.h 6.2 92/02/20";*/
/****************************************************************************/
/* I/O Request Block (IORB) Structures */
/****************************************************************************/
/* ASM
Resolve H2INC references for .INC version of file
include iorbtype.inc
*/
/* Typedefs to resolve forward references */
typedef struct _IORBH IORBH;
typedef struct _IORBH FAR *PIORBH;
typedef struct _IORBH *NPIORBH;
typedef struct _IORBH FAR *PIORB;
typedef struct _IORBH *NPIORB;
typedef struct _DEVICETABLE DEVICETABLE;
typedef struct _DEVICETABLE FAR *PDEVICETABLE;
typedef struct _DEVICETABLE *NPDEVICETABLE;
typedef struct _UNITINFO UNITINFO;
typedef struct _UNITINFO FAR *PUNITINFO;
typedef struct _UNITINFO *NPUNITINFO;
typedef struct _ADAPTERINFO ADAPTERINFO;
typedef struct _ADAPTERINFO FAR *PADAPTERINFO;
typedef struct _ADAPTERINFO *NPADAPTERINFO;
typedef struct _GEOMETRY GEOMETRY;
typedef struct _GEOMETRY FAR *PGEOMETRY;
typedef struct _GEOMETRY *NPGEOMETRY;
typedef struct _SCATGATENTRY SCATGATENTRY;
typedef struct _SCATGATENTRY FAR *PSCATGATENTRY;
typedef struct _SCATGATENTRY *NPSCATGATENTRY;
/*--------------------------------------------------------------------------*/
/* Interface for calling ADD entry point */
/*--------------------------------------------------------------------------*/
/* VOID FAR *(ADDEP) (PIORBH); */
/*--------------------------------------------------------------------------*/
/* IORB Header */
/*--------------------------------------------------------------------------*/
#define DM_WORKSPACE_SIZE 20
#define ADD_WORKSPACE_SIZE 16
typedef struct _IORBH { /* IOH */
USHORT Length; /* IORB length */
USHORT UnitHandle; /* Unit identifier */
USHORT CommandCode; /* Command code */
USHORT CommandModifier; /* Command modifier */
USHORT RequestControl; /* Request control flags */
USHORT Status; /* Status */
USHORT ErrorCode; /* Error code */
ULONG Timeout; /* Cmd completion timeout(s) */
USHORT StatusBlockLen; /* Status block length */
NPBYTE pStatusBlock; /* Status block */
USHORT Reserved_1; /* Reserved, MBZ */
PIORB pNxtIORB; /* Pointer to next IORB */
PIORB (FAR *NotifyAddress)(PIORB); /* Notification address */
UCHAR DMWorkSpace[DM_WORKSPACE_SIZE]; /* For use by DM */
UCHAR ADDWorkSpace[ADD_WORKSPACE_SIZE]; /* For use by ADD */
} IORBH;
/*--------------------------------------------------------------------------*/
/* IORB CommandCode and CommandModifier Codes */
/* Note: CommandCodes are prefixed by IOCC and CommandModifiers */
/* by IOCM. */
/*--------------------------------------------------------------------------*/
/*--------------------------------*/
/* +----M=Mandatory support */
/* | O=Optional support */
/* | */
/* V Notes */
/*--------------------------------*/
#define IOCC_CONFIGURATION 0x0001 /* */
#define IOCM_GET_DEVICE_TABLE 0x0001 /* M */
#define IOCM_COMPLETE_INIT 0x0002 /* O */
/*----------------------------------------*/
#define IOCC_UNIT_CONTROL 0x0002 /* */
#define IOCM_ALLOCATE_UNIT 0x0001 /* M */
#define IOCM_DEALLOCATE_UNIT 0x0002 /* M */
#define IOCM_CHANGE_UNITINFO 0x0003 /* M */
/*----------------------------------------*/
#define IOCC_GEOMETRY 0x0003 /* */
#define IOCM_GET_MEDIA_GEOMETRY 0x0001 /* M */
#define IOCM_SET_MEDIA_GEOMETRY 0x0002 /* O (M) >1 media type */
#define IOCM_GET_DEVICE_GEOMETRY 0x0003 /* M */
#define IOCM_SET_LOGICAL_GEOMETRY 0x0004 /* O (M) CHS addressable */
/*----------------------------------------*/
#define IOCC_EXECUTE_IO 0x0004 /* */
#define IOCM_READ 0x0001 /* M */
#define IOCM_READ_VERIFY 0x0002 /* M */
#define IOCM_READ_PREFETCH 0x0003 /* O */
#define IOCM_WRITE 0x0004 /* M */
#define IOCM_WRITE_VERIFY 0x0005 /* M */
/*----------------------------------------*/
#define IOCC_FORMAT 0x0005 /* */
#define IOCM_FORMAT_MEDIA 0x0001 /* O (M) If HW requires */
#define IOCM_FORMAT_TRACK 0x0002 /* O (M) If HW requires */
#define IOCM_FORMAT_PROGRESS 0x0003 /* O */
#define IOCC_UNIT_STATUS 0x0006 /* */
#define IOCM_GET_UNIT_STATUS 0x0001 /* M */
#define IOCM_GET_CHANGELINE_STATE 0x0002 /* O (Mandatory for diskette) */
#define IOCM_GET_MEDIA_SENSE 0x0003 /* O (Mandatory for diskette) */
#define IOCM_GET_LOCK_STATUS 0x0004 /* M */
/*----------------------------------------*/
#define IOCC_DEVICE_CONTROL 0x0007 /* */
#define IOCM_ABORT 0x0001 /* O (M) SCSI */
#define IOCM_RESET 0x0002 /* O (M) SCSI */
#define IOCM_SUSPEND 0x0003 /* O (M) Floppy driver */
#define IOCM_RESUME 0x0004 /* O (M) Floppy driver */
#define IOCM_LOCK_MEDIA 0x0005 /* M (O) Fixed media only */
#define IOCM_UNLOCK_MEDIA 0x0006 /* M (O) Fixed media only */
#define IOCM_EJECT_MEDIA 0x0007 /* M (O) SCSI and Floppy Driver */
/*----------------------------------------*/
#define IOCC_ADAPTER_PASSTHRU 0x0008 /* */
#define IOCM_EXECUTE_SCB 0x0001 /* O */
#define IOCM_EXECUTE_CDB 0x0002 /* O (M) SCSI adapters */
/*----------------------------------------*/
#define MAX_IOCC_COMMAND IOCC_ADAPTER_PASSTHRU
/*--------------------------------------------------------------------------*/
/* Status flags returned in IORBH->Status */
/*--------------------------------------------------------------------------*/
#define IORB_DONE 0x0001 /* 1=Done, 0=In progress */
#define IORB_ERROR 0x0002 /* 1=Error, 0=No error */
#define IORB_RECOV_ERROR 0x0004 /* Recovered error */
#define IORB_STATUSBLOCK_AVAIL 0x0008 /* Status block available */
/*--------------------------------------------------------------------------*/
/* Error Codes returned in IORBH->ErrorCode */
/*--------------------------------------------------------------------------*/
#define IOERR_RETRY 0x8000
#define IOERR_CMD 0x0100
#define IOERR_CMD_NOT_SUPPORTED IOERR_CMD+1
#define IOERR_CMD_SYNTAX IOERR_CMD+2
#define IOERR_CMD_SGLIST_BAD IOERR_CMD+3
#define IOERR_CMD_SW_RESOURCE IOERR_CMD+IOERR_RETRY+4
#define IOERR_CMD_ABORTED IOERR_CMD+5
#define IOERR_CMD_ADD_SOFTWARE_FAILURE IOERR_CMD+6
#define IOERR_CMD_OS_SOFTWARE_FAILURE IOERR_CMD+7
#define IOERR_UNIT 0x0200
#define IOERR_UNIT_NOT_ALLOCATED IOERR_UNIT+1
#define IOERR_UNIT_ALLOCATED IOERR_UNIT+2
#define IOERR_UNIT_NOT_READY IOERR_UNIT+3
#define IOERR_UNIT_PWR_OFF IOERR_UNIT+4
#define IOERR_RBA 0x0300
#define IOERR_RBA_ADDRESSING_ERROR IOERR_RBA+IOERR_RETRY+1
#define IOERR_RBA_LIMIT IOERR_RBA+2
#define IOERR_RBA_CRC_ERROR IOERR_RBA+IOERR_RETRY+3
#define IOERR_MEDIA 0x0400
#define IOERR_MEDIA_NOT_FORMATTED IOERR_MEDIA+1
#define IOERR_MEDIA_NOT_SUPPORTED IOERR_MEDIA+2
#define IOERR_MEDIA_WRITE_PROTECT IOERR_MEDIA+3
#define IOERR_MEDIA_CHANGED IOERR_MEDIA+4
#define IOERR_MEDIA_NOT_PRESENT IOERR_MEDIA+5
#define IOERR_ADAPTER 0x0500
#define IOERR_ADAPTER_HOSTBUSCHECK IOERR_ADAPTER+1
#define IOERR_ADAPTER_DEVICEBUSCHECK IOERR_ADAPTER+IOERR_RETRY+2
#define IOERR_ADAPTER_OVERRUN IOERR_ADAPTER+IOERR_RETRY+3
#define IOERR_ADAPTER_UNDERRUN IOERR_ADAPTER+IOERR_RETRY+4
#define IOERR_ADAPTER_DIAGFAIL IOERR_ADAPTER+5
#define IOERR_ADAPTER_TIMEOUT IOERR_ADAPTER+IOERR_RETRY+6
#define IOERR_ADAPTER_DEVICE_TIMEOUT IOERR_ADAPTER+IOERR_RETRY+7
#define IOERR_ADAPTER_REQ_NOT_SUPPORTED IOERR_ADAPTER+8
#define IOERR_ADAPTER_REFER_TO_STATUS IOERR_ADAPTER+9
#define IOERR_ADAPTER_NONSPECIFIC IOERR_ADAPTER+10
#define IOERR_DEVICE 0x0600
#define IOERR_DEVICE_DEVICEBUSCHECK IOERR_DEVICE+IOERR_RETRY+1
#define IOERR_DEVICE_REQ_NOT_SUPPORTED IOERR_DEVICE+2
#define IOERR_DEVICE_DIAGFAIL IOERR_DEVICE+3
#define IOERR_DEVICE_BUSY IOERR_DEVICE+IOERR_RETRY+4
#define IOERR_DEVICE_OVERRUN IOERR_DEVICE+IOERR_RETRY+5
#define IOERR_DEVICE_UNDERRUN IOERR_DEVICE+IOERR_RETRY+6
#define IOERR_DEVICE_RESET IOERR_DEVICE+7
#define IOERR_DEVICE_NONSPECIFIC IOERR_DEVICE+8
/*--------------------------------------------------------------------------*/
/* Request Control flags in IORBH->RequestControl */
/*--------------------------------------------------------------------------*/
#define IORB_ASYNC_POST 0x0001 /* Asynchronous post enabled */
#define IORB_CHAIN 0x0002 /* IORB chain link enabled */
#define IORB_CHS_ADDRESSING 0x0004 /* CHS fmt addr in RBA field */
#define IORB_REQ_STATUSBLOCK 0x0008 /* Obtain status block data */
#define IORB_DISABLE_RETRY 0x0010 /* Disable retries in ADD */
/*--------------------------------------------------------------------------*/
/* ADAPTER CONFIGURATION IORB (for IOCC_CONFIGURATION) */
/*--------------------------------------------------------------------------*/
typedef struct _IORB_CONFIGURATION { /* IOCFG */
IORBH iorbh; /* IORB header */
DEVICETABLE far *pDeviceTable; /* Far pointer to adapt. dev. table */
USHORT DeviceTableLen ; /* Length of adapter device table */
} IORB_CONFIGURATION, FAR *PIORB_CONFIGURATION, *NPIORB_CONFIGURATION;
/* Adapter device table returned by GET_DEVICE_TABLE */
typedef struct _DEVICETABLE { /* IODT */
UCHAR ADDLevelMajor; /* ADD major support level */
UCHAR ADDLevelMinor; /* ADD minor support level */
USHORT ADDHandle; /* ADD handle */
USHORT TotalAdapters; /* Number of adapters supported */
NPADAPTERINFO pAdapter [1]; /* Array of adapter info pointers */
} DEVICETABLE, FAR *PDEVICETABLE;
/*--------------------------------------------------------------------------*/
/* Current ADD Level for DEVICETABLE->AddLevelMajor, AddLevelMinor */
/*--------------------------------------------------------------------------*/
#define ADD_LEVEL_MAJOR 0x01
#define ADD_LEVEL_MINOR 0x00
typedef struct _UNITINFO { /* IOUI */
USHORT AdapterIndex; /* nth adapter this driver */
USHORT UnitIndex; /* nth unit on this card */
USHORT UnitFlags; /* Unit flags */
USHORT Reserved; /* Reserved ; must be 0 */
USHORT UnitHandle; /* Assigned by ADD or filter */
USHORT FilterADDHandle; /* Handle of filter ADD 0 = None */
USHORT UnitType; /* Unit type */
USHORT QueuingCount; /* Recommended number to queue */
UCHAR UnitSCSITargetID; /* SCSI target ID (SCSI only) */
UCHAR UnitSCSILUN; /* SCSI log. unit (SCSI only) */
} UNITINFO;
/*--------------------------------------------------------------------------*/
/* Unit Flags for UNITINFO->UnitFlags */
/*--------------------------------------------------------------------------*/
#define UF_REMOVABLE 0x0001 /* Media can be removed. */
#define UF_CHANGELINE 0x0002 /* ChangeLine supported */
#define UF_PREFETCH 0x0004 /* Supports prefetch read */
#define UF_A_DRIVE 0x0008 /* Manages A: */
#define UF_B_DRIVE 0x0010 /* Manages B: */
#define UF_NODASD_SUPT 0x0020 /* Suppress DASD Mgr support. */
#define UF_NOSCSI_SUPT 0x0040 /* Suppress SCSI Mgr support. */
#define UF_DEFECTIVE 0x0080 /* Device is defective. */
/*--------------------------------------------------------------------------*/
/* Unit Types for UNITINFO->UnitType */
/*--------------------------------------------------------------------------*/
#define UIB_TYPE_DISK 0x0000 /* All direct access devices */
#define UIB_TYPE_TAPE 0x0001 /* Sequential access devices */
#define UIB_TYPE_PRINTER 0x0002 /* Printer device */
#define UIB_TYPE_PROCESSOR 0x0003 /* Processor type device */
#define UIB_TYPE_WORM 0x0004 /* Write Once/Read Many device */
#define UIB_TYPE_CDROM 0x0005 /* CD ROM device */
#define UIB_TYPE_SCANNER 0x0006 /* Scanner device */
#define UIB_TYPE_OPTICAL_MEMORY 0x0007/* Some optical disk */
#define UIB_TYPE_CHANGER 0x0008 /* Changer device (such as juke box) */
#define UIB_TYPE_COMM 0x0009 /* Communication devices */
typedef struct _ADAPTERINFO { /* IOAI */
UCHAR AdapterName [17]; /* Adapter name ASCIIZ string */
UCHAR Reserved; /* */
USHORT AdapterUnits; /* Number of units this adapter */
USHORT AdapterDevBus; /* Bus Type - Adapter to device */
UCHAR AdapterIOAccess; /* I/O Type - Adapter to host */
UCHAR AdapterHostBus; /* Bus Type - Adapter to host */
UCHAR AdapterSCSITargetID;/* Adapter SCSI target ID */
UCHAR AdapterSCSILUN; /* Adapter SCSI LUN */
USHORT AdapterFlags;
USHORT MaxHWSGList; /* Max HW S/G list entries */
ULONG MaxCDBTransferLength;/* Max data length for CDBs */
UNITINFO UnitInfo [1]; /* Unit info for each unit */
} ADAPTERINFO;
/*--------------------------------------------------------------------------*/
/* Adapter Flags for ADAPTERINFO->AdapterFlags */
/*--------------------------------------------------------------------------*/
#define AF_16M 0x0001 /* Supports > 16M addresses */
#define AF_IBM_SCB 0x0002 /* Supports IBM SCB commands */
#define AF_HW_SCATGAT 0x0004 /* Supports scatter/gather in HW */
#define AF_CHS_ADDRESSING 0x0008 /* Supports CHS addressing in HW */
#define AF_ASSOCIATED_DEVBUS 0x0010 /* Supports > 1 Device Bus */
/*--------------------------------------------------------------------------*/
/* Adapter-to-Device protocol for ADAPTERINFO->AdapterDevBus */
/*--------------------------------------------------------------------------*/
#define AI_DEVBUS_OTHER 0x0000
#define AI_DEVBUS_ST506 0x0001 /* ST-506 CAM-I */
#define AI_DEVBUS_ST506_II 0x0002 /* ST-506 CAM-II */
#define AI_DEVBUS_ESDI 0x0003 /* ESDI */
#define AI_DEVBUS_FLOPPY 0x0004 /* Diskette */
#define AI_DEVBUS_SCSI_1 0x0005
#define AI_DEVBUS_SCSI_2 0x0006
#define AI_DEVBUS_SCSI_3 0x0007
#define AI_DEVBUS_NONSCSI_CDROM 0x0008 /* Non-SCSI CD-ROM interface bus */
/*--------------------------------------------------------------------------*/
/* Note: One of the following BUS WIDTH indicators must be */
/* OR'd with the above field. */
/*--------------------------------------------------------------------------*/
#define AI_DEVBUS_FAST_SCSI 0x0100
#define AI_DEVBUS_8BIT 0x0200
#define AI_DEVBUS_16BIT 0x0400
#define AI_DEVBUS_32BIT 0x0800
/*--------------------------------------------------------------------------*/
/* Adapter-to-Device protocol for ADAPTERINFO->AdapterIOAccess */
/*--------------------------------------------------------------------------*/
#define AI_IOACCESS_OTHER 0x00
#define AI_IOACCESS_BUS_MASTER 0x01
#define AI_IOACCESS_PIO 0x02
#define AI_IOACCESS_DMA_SLAVE 0x04
#define AI_IOACCESS_MEMORY_MAP 0x08
/*--------------------------------------------------------------------------*/
/* Adapter-to-Host bus type for ADAPTERINFO->AdapterHostBus */
/*--------------------------------------------------------------------------*/
#define AI_HOSTBUS_OTHER 0x00
#define AI_HOSTBUS_ISA 0x01
#define AI_HOSTBUS_EISA 0x02
#define AI_HOSTBUS_uCHNL 0x03
#define AI_HOSTBUS_UNKNOWN 0x0f
/*--------------------------------------------------------------------------*/
/* Note: One of the following BUS WIDTH indicators must be */
/* OR'd with the above field. */
/*--------------------------------------------------------------------------*/
#define AI_BUSWIDTH_8BIT 0x10
#define AI_BUSWIDTH_16BIT 0x20
#define AI_BUSWIDTH_32BIT 0x30
#define AI_BUSWIDTH_64BIT 0x40
#define AI_BUSWIDTH_UNKNOWN 0xf0
/****************************************************************************/
/* UNIT CONTROL IORB (for IOCC_UNIT_CONTROL) */
/****************************************************************************/
typedef struct _IORB_UNIT_CONTROL { /* IOUC */
IORBH iorbh; /* IORB Header */
USHORT Flags; /* */
PUNITINFO pUnitInfo; /* For: IOCM_CHANGE_UNITINFO */
USHORT UnitInfoLen; /* Length of UnitInfo structure */
} IORB_UNIT_CONTROL, FAR *PIORB_UNIT_CONTROL, *NPIORB_UNIT_CONTROL;
/****************************************************************************/
/* DASD GEOMETRY IORB (for IOCC_GEOMETRY) */
/****************************************************************************/
typedef struct _IORB_GEOMETRY { /* IOGG */
IORBH iorbh; /* IORB header */
PGEOMETRY pGeometry; /* Far pointer to GEOMETRY block */
USHORT GeometryLen; /* Length of GEOMETRY block */
} IORB_GEOMETRY, FAR *PIORB_GEOMETRY, *NPIORB_GEOMETRY;
typedef struct _GEOMETRY { /* IOG */
ULONG TotalSectors;
USHORT BytesPerSector;
USHORT Reserved;
USHORT NumHeads;
ULONG TotalCylinders;
USHORT SectorsPerTrack;
} GEOMETRY, FAR *PGEOMETRY, *NPGEOMETRY;
/****************************************************************************/
/* Scatter/Gather List Entry */
/****************************************************************************/
typedef struct _SCATGATENTRY { / * IOSG */
ULONG ppXferBuf; /* Physical pointer to xfer buffer */
ULONG XferBufLen; /* Length of transfer buffer */
} SCATGATENTRY, FAR *PSCATGATENTRY, *NPSCATGATENTRY;
#define MAXSGLISTSIZE (sizeof(SCATGATENTRY)) * 16
/****************************************************************************/
/* EXECUTE_IO IORB (for IOCC_EXECUTE_IO) */
/****************************************************************************/
typedef struct _IORB_EXECUTEIO { /* IOXIO */
IORBH iorbh; /* IORB header */
USHORT cSGList; /* Count of S/G list elements */
PSCATGATENTRY pSGList; /* Far pointer to s/g list */
ULONG ppSGList; /* Phys. address of S/G list */
ULONG RBA; /* RBA starting address */
USHORT BlockCount; /* Block count */
USHORT BlocksXferred; /* Block done count */
USHORT BlockSize; /* Size of a block in bytes */
USHORT Flags;
} IORB_EXECUTEIO, FAR *PIORB_EXECUTEIO, *NPIORB_EXECUTEIO;
/****************************************************************************/
/* CHS Direct Addressing (Overlays RBA field) */
/****************************************************************************/
typedef struct _CHS_ADDR { /* IOCHS */
USHORT Cylinder;
UCHAR Head;
UCHAR Sector;
} CHS_ADDR, FAR *PCHS_ADDR, *NPCHS_ADDR;
/*--------------------------------------------------------------------------*/
/* IORB specific flags for IORB EXECUTE_IO->Flags */
/*--------------------------------------------------------------------------*/
#define XIO_DISABLE_HW_WRITE_CACHE 0x0001
#define XIO_DISABLE_HW_READ_CACHE 0x0002
/****************************************************************************/
/* FORMAT IORB (for IOCC_FORMAT) */
/****************************************************************************/
typedef struct _IORB_FORMAT { /* IOFMT */
IORBH iorbh; /* IORB Header */
USHORT cSGList; /* Count of S/G list elements */
PSCATGATENTRY pSGList; /* Far pointer to s/g list */
ULONG ppSGList; /* Phys. address of S/Glist */
USHORT FormatCmdLen; /* */
PBYTE pFormatCmd; /* SCSI CDB or track fmt cmd */
UCHAR Reserved_1 [8]; /* Reserved; must not be modified */
} IORB_FORMAT, FAR *PIORB_FORMAT, *NPIORB_FORMAT;
typedef struct _FORMAT_CMD_TRACK { /* FMCT */
USHORT Flags;
ULONG RBA;
USHORT cTrackEntries;
} FORMAT_CMD_TRACK, FAR *PFORMAT_CMD_TRACK, *NPFORMAT_CMD_TRAC ;
/*--------------------------------------------------------------------------*/
/* Flags for FORMAT_CMD_TRACK->Flags */
/*--------------------------------------------------------------------------*/
#define FF_VERIFY 0x0001 /* Verify sectors after formatting. */
/****************************************************************************/
/* ADAPTER PASS THROUGH IORB (for IOCC_ADAPTER_PASSTHRU) */
/****************************************************************************/
typedef struct _IORB_ADAPTER_PASSTHRU { /* IOPT */
IORBH iorbh; /* IORB header */
USHORT cSGList; /* Count of S/G list elements */
PSCATGATENTRY pSGList; /* Far pointer to s/g list */
ULONG ppSGLIST; /* Phys. address of S/G list */
USHORT ControllerCmdLen;
PBYTE pControllerCmd;
ULONG ppSCB; /* Phys. pointer to SCB for SCB_PASSTHRU */
USHORT Flags;
} IORB_ADAPTER_PASSTHRU, FAR *PIORB_ADAPTER_PASSTHRU, *NPIORB_ADAPTER_PASSTHRU;
/*--------------------------------------------------------------------------*/
/* IORB specific flags for IORB_ADAPTER_PASSTHRU->Flags */
/* */
/* Note: These flags apply to IOCM_EXECUTE_CDB. */
/*--------------------------------------------------------------------------*/
#define PT_DIRECTION_IN 0x0001 /* Data xfer to host adapter */
/****************************************************************************/
/* UNIT STATUS IORB (for IOCC_UNIT_STATUS) */
/****************************************************************************/
typedef struct _IORB_UNIT_STATUS { /* IOUS */
IORBH iorbh ;
USHORT UnitStatus ;
} IORB_UNIT_STATUS, FAR *PIORB_UNIT_STATUS, *NPIORB_UNIT_STATUS;
/*--------------------------------------------------------------------------*/
/* Unit Status for IORB_UNIT_STATUS->UnitStatus */
/* */
/* Note: These flags apply to IOCM_GET_UNIT_STATUS */
/*--------------------------------------------------------------------------*/
#define US_READY 0x0001 /* Unit ready */
#define US_POWER 0x0002 /* Unit powered on */
#define US_DEFECTIVE 0x0004 /* Unit operational */
/*--------------------------------------------------------------------------*/
/* Unit Status for IORB_UNIT_STATUS->UnitStatus */
/* */
/* Note: These flags apply to IOCM_GET_CHANGELINE_STATE */
/*--------------------------------------------------------------------------*/
#define US_CHANGELINE_ACTIVE 0x0001 /* ChangeLine state */
/*--------------------------------------------------------------------------*/
/* Unit Status for IORB_UNIT_STATUS->UnitStatus */
/* */
/* Note: These flags apply to IOCM_GET_MEDIA_SENSE */
/*--------------------------------------------------------------------------*/
#define US_MEDIA_UNKNOWN 0x0000 /* Unable to determine media */
#define US_MEDIA_720KB 0x0001 /* 720KB in 3.5" drive */
#define US_MEDIA_144MB 0x0002 /* 1.44MB in 3.5" drive */
#define US_MEDIA_288MB 0x0003 /* 2.88MB in 3.5" drive */
/****************************************************************************/
/* DEVICE CONTROL IORB (for IOCC_DEVICE_CONTROL */
/****************************************************************************/
typedef struct _IORB_DEVICE_CONTROL { /* IODC */
IORBH iorbh; /* IORB header */
USHORT Flags;
USHORT Reserved;
} IORB_DEVICE_CONTROL, FAR *PIORB_DEVICE_CONTROL, *NPIORB_DEVICE_CONTROL;
/*--------------------------------------------------------------------------*/
/* IORB-specific flags for IORB_DEVICE_CONTROL->Flags */
/* */
/* Note: These flags apply to IOCM_SUSPEND */
/*--------------------------------------------------------------------------*/
#define DC_SUSPEND_DEFERRED 0x0000 /* Suspend after device idle */
#define DC_SUSPEND_IMMEDIATE 0x0001 /* Suspend after current request */
#define MAX_IORB_SIZE 128
OS/2 SCSI Device Driver Interface Specification
Advanced SCSI Programming Interface (ASPI) OS/2 Specification
Adapter Device Driver Interface Questions and Answers
Device Driver Test Tool (DDTT)
Notices
Fifth Edition (September 1997)
The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.
Copyright Notices
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface. Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved." (C) Copyright International Business Machines Corporation 1997. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Disclaimers
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
- IBM Director of Licensing
- IBM Corporation
- 500 Columbus Avenue
- Thornwood, NY 10594 U.S.A.
Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
- AIX
- AT
- Common User Access CUA
- IBM Micro Channel
- Multimedia Presentation Manager/2
- OS/2
- Personal System/2 PS/2
- SAA
- Series/1
- Systems Application Architecture
The following terms are trademarks of other companies:
- Adaptec Adaptec, Inc.
- APM Astek International Ltd.
- Apple Apple Computer, Inc.
- Hitachi Hitachi Ltd.
- Intel Intel Corporation
- MSCDEX Microsoft Corporation
- NEC NEC Corporation
- Novell Novell, Inc.
- Photo CD Eastman Kodak Company
- RIPL CTA Incorporated
- SCO The Santa Cruz Operation, Inc.
- Sony Sony Corporation
- Toshiba Toshiba Corporation
- UNIX Unix System Laboratories, Inc.
- XENIX Microsoft Corporation