Adapter Device Driver Development Considerations

Adapter device drivers are packaged as 16-bit OS/2 device drivers. This chapter describes how adapter device drivers differ from installable OS/2 device drivers.

Loading and Initialization
Adapter device drivers are loaded using the BASEDEV= statement in CONFIG.SYS. The processing of these statements occurs before the operating system is fully initialized. The adapter device driver writer must be aware of the following differences between installable device drivers and adapter device drivers: 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. The INIT request packet command code for all base device drivers (which include all adapter device drivers) is hex 1B rather than hex 0. 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. 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. 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. 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.
 * Adapter device drivers initialize at Ring 0 rather than Ring 3.
 * INIT request packet command code
 * Device Driver Header
 * Device attribute field - Bits 15, 8, 7
 * Capabilities Bit Strip - Bit 3
 * INIT request packet format

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. With the exception of the OS/2 system kernel initialization request packet just described and vendor-defined IOCtls, adapter device drivers must reject all other kernel request packets. The primary interface to adapter device drivers is defined in this reference. Adapter device drivers register their main entry points with 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. The OS/2 kernel treats the name in the adapter device driver header as a valid character device name. Adapter device drivers must end their device names with a dollar sign ($) to avoid conflict with valid file names. Adapter device drivers 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.
 * Adapter device drivers process a limited set of OS/2 kernel request packets.
 * Adapter device drivers register their entry points using the DevHlp service.
 * Adapter device drivers must declare a valid character device name in their headers.
 * Adapter device drivers must fail quietly when hardware is not found.

Operation
Adapter device drivers receive commands through an I/O request block (IORB) entry point. The format of IORB commands received by an adapter device driver is defined in this reference.

Adapter device drivers have full use of both the 16-bit and 32-bit DevHlp services defined in OS/2 operating system. Although the adapter device driver to DM interface is 16-bit, adapter device drivers can manipulate 32-bit objects with assembly subroutines.

The service request entry point of an adapter device driver can be called in either kernel (also known as task) or interrupt contexts. Consequently, an adapter device driver must never block while servicing a request after it has completed initialization. (An adapter device driver can block at initialization.)

Service requests that involve time delays normally are initiated by the adapter device driver; then, the adapter device driver immediately returns to its caller. Service request completion is indicated to the caller using asynchronous callback notification.

Command-Line Parameters
To facilitate the parsing of command-line parameters, and to help encourage uniformity in command-line syntax, a parser/tokenizer is provided in the IBM Developer Connection Device Driver Kit for OS/2. In addition, a command-line syntax definition is provided in Adapter Device Driver Command-Line Parameters.

The output of the parser/tokenizer is a stream of tokens that represents the contents of the command line. The parser/tokenizer performs preliminary syntactical checks on the command line and indicates the results of these checks by the return code. However, the adapter device driver must ensure that the tokenized parameters' values are acceptable. The adapter device driver is responsible for displaying error messages as appropriate.

OEMs can modify the parser and included tables to add their own adapter-unique flags and parameters.