View source for Virtual Device Driver Reference for OS/2

{| style="float: right; background: #F5F5F5;font-size: 90%;"
|- style="background: silver;"
!Virtual Device Driver Reference for OS/2
|-
|Part 1. Overview
:[[#Introduction|Introduction]]
:[[Virtual Device Driver Architecture and Operations]]
|-
|Part 2. Virtual Device Drivers
:[[Base Virtual Device Drivers]]
:[[Installable Virtual Device Drivers]]
:[[Virtual Mouse Device Driver]]
|-
|Part 3. Reference Material
:[[C Language Virtual DevHlp Services]]
|-
|Appendixes
:[[#OS/2 Version Compatibility Considerations|OS/2 Version Compatibility Considerations]]
:[[Assembler Language Syntax]]
:[[IBM SDK/DDK Notices|Notices]]
:[[IBM SDK/DDK Glossary|Glossary]]
|}
''By [[IBM]]''

'''Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'''
===EDM/2 preamble===
This is the ''Virtual Device Driver Reference for OS/2'' as last published by IBM in 1995. It is republished here with explicit permission from the company (Copyright Permission #21953) and you should keep in mind that it is an intellectual property of International Business Machines Corp. that cannot be changed or reused without their permission and is not governed by the [[Attribution-Share Alike 3.0]] licence like the rest of the EDM/2 Wiki.

The content of the documentation is unchanged apart from the following:
* The original document was an INF file split into thousands of different small sections, these have been consolidated into chapters, and restructured to fit [[HTML]] formatting, mimicking the original [[GML]] format as much as possible.
* Sales, technical help, download and contact information has been removed. The VDDR/2 and the related SDK's are no longer for sale, nor is support available from IBM. Some of the INF viewer related help has been removed as well as it is superfluous after the format change and might be misleading, and the Glossary and Notices section was merged with other DDK/SDK glossary sections as they are all identical.
* Miniscule changes have been made to the text, spelling errors, formatting errors and possible copy and paste errors have been fixed and/or noted.

Outside of formatting changes, adding Wikilinks and graphic improvements, the document shall be left as it is. It should be noted that the some of the driver models and data formats described in the documentation are have been replaced or extended by both IBM and third parties, but that does not mean that this document should be changed, but it is acceptable that a link is created to an internal or external article that explains the newer models and formats.

=About This Book =
The ''OS/2 Virtual Device Driver Reference'' defines what a virtual device driver is, how it operates, and when to use one. In addition, a description of the types of virtual device drivers, their interfaces, and the available kernel services is provided. System and application programmers can use the information found in this book to write their own virtual device drivers and subsystems.

Knowledge of a programming language (such as C or assembler) that is used for writing OS/2 applications is necessary, and the programmer must be familiar with the workings of the OS/2 operating system.

==How This Book is Organized ==
This book consists of three parts:

''Part 1. Overview''
;[[#Introduction|Introduction]]:This chapter contains a general description of the three types of OS/2 device drivers, and an overview of the virtual device driver mechanism and kernel services.
;[[Virtual Device Driver Architecture and Operations]]:This chapter contains a description of virtual device driver architecture, operations, and communication between device drivers.
''Part 2. Virtual Device Drivers''
;[[Base Virtual Device Drivers]]:This chapter contains a description of each base virtual device driver shipped with OS/2.
;[[Installable Virtual Device Drivers]]:This chapter contains a description of each installable virtual virtual device driver shipped with OS/2.
;[[Virtual Mouse Device Driver]]:This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions.
''Part 3. Reference Material''
;[[C Language Virtual DevHlp Services]]:This chapter contains full C language descriptions of the kernel functions available to virtual device drivers.
''Appendixes''
;[[#OS/2 Version Compatibility Considerations|OS/2 Version Compatibility Considerations]]:This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility.
;[[Assembler Language Syntax]]:This appendix contains assembler language versions of the kernel functions covered in Chapter 6.
;[[IBM SDK/DDK Notices|Notices]]:This appendix contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.

A [[IBM SDK/DDK Glossary|glossary]] and an index are included at the back of this book.

=Introduction=
Virtual device drivers are used by the OS/2* operating system to act as virtual devices for DOS applications executing in a DOS session. These device drivers provide ''virtual hardware''support for DOS and DOS applications.

The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including:
*Asynchronous Communication (RS-232C)
*DMA (Direct Memory Access)
*Fixed Disk and Diskette
*Keyboard
*Mouse
*Parallel Port Printer
*PIC (Programmable Interrupt Controller)
*Timer <br />*Video
This book provides an overview of the virtual device driver mechanism and the available kernel services.

==Types of OS/2 Device Drivers ==
Three types of device drivers are used in the OS/2 operating system:
*Virtual device drivers
*Physical device drivers
*Presentation drivers

===Virtual Device Drivers===
The virtual device driver is an installable module, responsible for virtualizing 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, operating at Ring 0, the most privileged level of the operating system. 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.

===Physical Device Drivers===
Standard I/O devices are supported by base physical device drivers that are part of the OS/2 operating system. Additional or replacement physical device drivers can be loaded to extend the control provided by the base device drivers, or to support nonstandard I/O devices. Typical examples of these loadable device drivers are ANSI.SYS and ANSI.DLL, which are loaded by "DEVICE=" statements in the CONFIG.SYS file, and provide additional functions on the interfaces to the screen and keyboard. Physical device drivers are initialized at Ring 3 and operate at Ring 0.

Further information on physical device drivers, physical device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Physical 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 (Application Programming Interface) 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 privilege 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 are identified by the extension ".DRV". When the Presentation Manager is initialized, the display presentation driver is automatically loaded and enabled. 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.

Include (.INC and .h) files are shipped with the ''Developer's Toolkit for OS /2'' to provide support for building presentation drivers that are written in either 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''.

==When to Use a Virtual Device Driver ==
The device virtualization provided by OS/2 can be extended by creating a virtual device driver (VDD) and the corresponding physical device driver (PDD). A user-supplied virtual device driver virtualizes the hardware interfaces of an option adapter or device, usually to migrate an existing DOS application into the OS/2 DOS environment.

Note that a virtual device driver is needed only in a limited number of cases. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely. OS/2 maps interrupts, I/O ports, and I/O memory directly to any DOS device driver or DOS application which attempts to access these resources. As long as a resource is not already claimed by another session or by the OS/2 kernel, it is directly accessible to the DOS program.

Where access-sharing is required, it is generally not necessary to create a virtual device driver if the I/O is handle-based. DOS INT 21h I/O requests are routed by the OS/2 file system to the protect-mode physical device driver. If all I/O is handle-based, it is necessary only to create the physical device driver.

For block devices, it is recommended that OS/2 support be provided only by a physical device driver. Both DOS and OS/2 sessions will then access the device through file system interfaces defined by DOS and the OS/2 operating system.

In the absence of a sharing requirement, a virtual device driver might be necessary if the device has strict interrupt service latency requirements. A virtual device driver/physical device driver pair improves the interrupt service latency for an option adapter or device.

==OS/2 Version Compatibility Considerations==
The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items.
{|class="wikitable"
!Item Added or Changed ||Date Item Added or Changed||Compatibility of Addition or Change
|-
|Advanced OS/2 Joystick Device Driver||November 1995||OS/2 Warp, Version 3 and higher
|}

[[Category:Device Driver Reference]]