Input/Output Device Driver Reference

About This Book
The Input/Output Device Driver Reference for OS/2 contains specific character device drivers that are shipped with OS/2. A generic discussion of character and block device drivers can be found in the Physical Device Driver Reference for OS/2 and the Storage Device Driver Reference for OS/2.

How This Book is Organized
Advanced Power Management Architecture describes the Advanced Power Management specification, a component of the OS/2 operating system that is used to manage power (AC/DC) consumption and utilization for PC systems.

APM IOCtl Device Driver Test Tool explains the test tool and its various test cases.

Asynchronous (RS232-C) Communications Device Driver presents the physical asynchronous (RS232-C) communications device driver and describes how it enables OS/2 applications to utilize the RS232-C device hardware.

CLOCK$ Device Driver describes the physical clock device driver.

Joystick Device Driver describes the Advanced OS/2 Joystick Device Driver.

Keyboard Device Driver describes the KBD$ (device-independent) driver.

Keyboard Inter-Device-Driver Communication Interfaces describes the IBMKBD (device-dependent) driver.

Keyboard Device Driver Test Tool describes how to use the keyboard Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of keyboard device drivers.

Mouse Device Driver describes a physical mouse device driver (MOUSE.SYS) whose job it is to detect the types of pointing devices currently installed on the OS/2 operating system. When a pointing device is identified, support for it is set up dynamically.

Mouse (DOS) Device Driver Test Tool describes how to use the mouse Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of mouse device drivers.

Parallel Port Device Driver describes the parallel port device driver, which supports the parallel port device interface for OS/2, Versions 2.0 and later.

Physical Bidirectional Parallel Port Device Driver describes the function the new PAR1284.SYS device driver provides.

Parallel Port Device Driver Test Tool describes how to use the parallel port Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers.

PCMCIA Architecture contains a description of the PCMCIA architecture as it applies to the OS/2 operating system. Also included is a list of the supported functions and information on deviations from the PCMCIA standard.

PCMCIA Socket Services Device Driver Test Tool describes how to use the PCMCIA Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of PCMCIA device drivers.

Touch Display Device Driver introduces and describes the IBM Touch Display device driver, which, in addition to the video cable connection to a VGA/ XGA port, has a touch data cable that attaches to the IBM PS/2 Mouse (pointing device) port on the system unit. OS/2 protect-mode and DOS real-mode applications are supported by the touch component.

Touch Inter-Device-Driver Communication Interfaces describes the IBM interfaces for the Touch Display device driver.

USB Device Driver Stack for OS/2 Warp briefly describes OS/2 USB stack implementation and gives guidelines for host controller driver and class/client driver implementation together with stack driver communication API specification.

Notices contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.

A glossary and an index are included at the back of this book.

Conventions
Throughout this publication, there are references to specific values for character strings. These values are for the Single-Byte Character Set (SBCS). When using the Double-Byte Character Set, note that one DBCS character equals two SBCS characters.
 * Double-Byte Character Set

Unless otherwise stated, "OS/2" as used in this book refers to the Warp Version of the IBM Operating System/2.
 * Version

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 BBS, 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

Ordering Information
In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it also includes the following DDK reference books in online format.
 * The Physical Device Driver Reference
 * The Storage Device Driver Reference
 * The Input/Output Device Driver Reference
 * The Pen for OS/2 Device Driver Reference
 * The Virtual Device Driver Reference
 * The Presentation Device Driver Reference
 * The Display Device Driver Reference
 * The Printer Device Driver Reference
 * The Graphics Adapter Device Driver Reference
 * The MMPM/2 Device Driver Reference (Multimedia)

What's New
A new chapter, is provided. This chapter explains the Advanced Power Management test tool.

A new chapter, was added which describes the PAR1284.SYS device driver.

For information on any items discussed in this reference that have been added to OS/2 beginning with OS/2 Warp Version 3.0 and their compatibility with different versions of OS/2, see.

Introduction
Device drivers are software modules that act as an interface between OS/2 (or its applications) and physical devices. In DOS, applications are responsible for knowing and managing all the differences between different devices of like types. The device drivers of OS/2 enable applications to focus on the logic of the actual application and treat devices in a device-independent way.

This device-independence is a fundamental benefit of the OS/2 programming environment. For example, drawing a circle on the screen or on a printer is as easy as opening a device context for the correct output device and performing the drawing operations. By placing the drawing operation into the device context, the programmer does not have to be concerned about whether the device is a printer or a display.

Types of OS/2 Device Drivers
Three types of device drivers are used in OS/2 Version 3:
 * Physical device drivers
 * Virtual device drivers
 * Presentation drivers

Physical Device Drivers
Physical device drivers, in most cases, resolve device-independent input and output (I/O) requests from the operating system and its applications with the device-dependent physical attributes of the device. The physical device drivers shipped with OS/2 Version 3 include support for the following:
 * Advanced Power Management
 * Asynchronous Communication (RS-232C)
 * CD-ROM
 * Hard Disk and Diskette
 * Keyboard
 * Mouse
 * Parallel Port Printer
 * PCMCIA
 * System Clock
 * Touch Screen
 * Video

Virtual Device Drivers
The virtual device driver is an installable module that virtualizes a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers that operate at Ring 0. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.

Further information on virtual device drivers, virtual device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Virtual Device Driver Reference.

Presentation Drivers
The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API call interface, which uses the program stack to communicate with, or pass parameters to, the presentation drivers. These drivers are special purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.

Presentation drivers are dynamic link library modules that are supplied as files and identified by the extension DRV. When the Presentation Manager interface is initialized, the display presentation driver is loaded and enabled automatically. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the DevOpenDC function to open the device.

Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.

Header and include files are shipped with OS/2 to provide support for building presentation drivers that are written in C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Presentation Device Driver Reference.

OS/2 Version Compatibility Considerations
The following table lists any items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.

Glossary

 * IBM SDK/DDK Glossary