Adapter Device Driver Development Considerations

From EDM2
Jump to: navigation, search
Storage Device Driver Reference
  1. About This Book
  2. Introduction to DASD, SCSI, and CD-ROM Programming Interfaces
  3. Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers
  4. Adapter Device Driver Development Considerations
  5. DASD, SCSI, and CD-ROM Device Manager Interface Specification
  6. Error Handling
  7. Adapter Device Driver Command-Line Parameters
  8. DASD IOCtl Device Driver Test Tool
  9. Optical IOCtl Device Driver Test Tool
  10. Using Filter Device Drivers
  11. Library and Services
  12. CD-ROM Device Manager Interface Specification
  13. CD-ROM Device Driver Test Tool
  14. Building an OS/2 Virtual Disk Driver
  15. OS2DASD.DMD - Technical Reference
  16. Boot Record Architecture
  17. Extended Device Driver Interface Specification
  18. I/O Request Block - C Definitions
  19. OS/2 SCSI Device Driver Interface Specification
  20. Advanced SCSI Programming Interface (ASPI) OS/2 Specification
  21. Adapter Device Driver Interface Questions and Answers
  22. Device Driver Test Tool (DDTT)
  23. Glossary

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

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:

  • 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.
  • 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.
  • 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.
  • 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.

  • 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.
  • Adapter device drivers register their entry points using the DevHlp service.
    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.
  • 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.
  • 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.

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.