Jump to content

Virtual Device Driver Reference for OS/2: Difference between revisions

From EDM2
← Older edit
mNo edit summary
Ak120 (talk | contribs)
35,819 edits
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
''By [[IBM]]''
{{IBM-Reprint}}
{{VDDRef}}
==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.


'''Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'''
The content of the documentation is unchanged apart from the following:
=About This Book =
* 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.
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.
* 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.


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.
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 ==
===How This Book is Organized===
 
This book consists of three parts:
This book consists of three parts:


''Part 1. Overview''
''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.
;[[#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.
;[[00011.htm|Virtual Device Driver Architecture and Operations]]:This chapter contains a description of virtual device driver architecture, operations, and communication between device drivers.
;[[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''
''Part 2. Virtual Device Drivers''
;[[00043.htm|Base Virtual Device Drivers]]:This chapter contains a description of each base virtual device driver shipped with OS/2.
;[[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.
;[[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.
;[[Virtual Mouse Device Driver]]:This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions.
Line 24: Line 30:
''Appendixes''
''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.
;[[#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.
;[[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.
;[[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.
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.
 
 
==Assistance ==
 
Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system ( BBS) known as the "DUDE." You are encouraged to use the DUDE 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 DUDE, 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 ==
 
For an illustration of OS/2 Technical Publications and other related product documents, see the figure labeled "OS/2 Technical Publications". The documents represented in this illustration are available only in English.
 
In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, this CD-ROM also includes the following DDK reference books in online format.
 
*The Physical Device Driver Reference <br />
*The Storage Device Driver Reference <br />
*The Input/Output Device Driver Reference <br />
*The Pen for OS/2 Device Driver Reference <br />
*The Virtual Device Driver Reference <br />
*The Presentation Device Driver Reference <br />
*The Display Device Driver Reference <br />
*The Printer Device Driver Reference <br />
*The Graphics Adapter Device Driver Reference <br />
*The MMPM/2 Device Driver Reference (Multimedia) <br />
To order the DDK call:
 
<pre class="western">/----------------------------------------------------------------\
|U.S.A.:            |1-800-633-8266      |                    |
|--------------------+---------------------+---------------------|
|Canada:            |1-800-561-5293      |                    |
|--------------------+---------------------+---------------------|
|When calling from  |* English            |(+45) 48101500      |
|Europe, the Middle  |* French            |(+45) 48101200      |
|East, or Africa, the|* Italian            |(+45) 48101600      |
|number depends on  |* German            |(+45) 48101000      |
|the language you use|* Spanish            |(+45) 48101100      |
|to place the order: |* Dutch              |(+45) 48101400      |
|                    |* Danish            |(+45) 48101300      |
|                    |* Finish            |(+45) 48101650      |
|                    |* Swedish            |(+45) 48101150      |
|                    |* Norwegian          |(+45) 48101250      |
|                    |* FAX                |(+45) 48142207      |
|--------------------+---------------------+---------------------|
|When ordering from  |* Bolivia            |    02-35 1840      |
|Latin America or    |* Columbia          |  01-257-0111      |
|South America, the  |* Dominican Republic |      566-5161      |
|number depends on  |* El Salvador        |    02-98 5011      |
|the country from    |* Honduras          |      32-2319      |
|which you are      |* Paraguay          |  021-444 094      |
|calling:            |* Urugruay          |    02-923 617      |
|                    |* Chile              |  02-633-4400      |
|                    |* Costa Rica        |      223-6222      |
|                    |* Ecuador            |    02-56 5100      |
|                    |* Guatemala          |    02-31 5859      |
|                    |* Panama            |    02-639 977      |
|                    |* Peru              |  014-36 6345      |
|                    |* Venezuela          |  02-908-8901      |
|                    |* Argentina          |  01-313-0014      |
|--------------------+---------------------+---------------------|
|To order from Asia/ |* All except Japan  |(61) 2-354-7684      |
|Pacific:            |* Japan              |(81) 3-3495-2045(Fax)|
|                    |                    |Fax request to:      |
|                    |                    |DAP-J, IBM Japan    |
|--------------------+---------------------+---------------------|
|To order from SE    |(021) 800-6120(Voice)|                    |
|Brazil:            |(021) 800-6936(Fax)  |                    |
|--------------------+---------------------+---------------------|
|To order from      |* Mexico City        |627-2444            |
|Mexico:            |* Country            |91-800-00639        |
\----------------------------------------------------------------/</pre>
 
 
 
 
= What's New =
 
Following is a list of the changes made to the ''OS/2 Virtual Device Driver Reference''(Fourth Edition) since it was published in April 1995.
 
*[[00102.htm|Virtual Advanced OS/2 Joystick Device Driver]]has been added to [[00088.htm|Installable Virtual Device Drivers]]
 
Refer to [[01167.htm|OS/2 Version Compatibility Considerations]]for a table listing compatibility information about new information in 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:
The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including:
 
*Asynchronous Communication (RS-232C)
*Asynchronous Communication (RS-232C) <br />*DMA (Direct Memory Access) <br />*Fixed Disk and Diskette <br />*Keyboard <br />*Mouse <br />*Parallel Port Printer <br />*PIC (Programmable Interrupt Controller) <br />*Timer <br />*Video
*DMA (Direct Memory Access)
 
*Fixed Disk and Diskette
*Keyboard
*Mouse
*Parallel Port Printer
*PIC (Programmable Interrupt Controller)
*Timer
*Video
This book provides an overview of the virtual device driver mechanism and the available kernel services.
This book provides an overview of the virtual device driver mechanism and the available kernel services.


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


*Virtual device drivers <br />*Physical device drivers <br />*Presentation drivers
===Virtual Device 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.
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.
 
 
=== 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 &quot;DEVICE=&quot; 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''.
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 ===
=== 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.
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 &quot;.DRV&quot;. 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 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.
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.
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''.
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 ==
==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.
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.
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.
Line 199: Line 86:
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.
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==
 
 
 
= Virtual Device Driver Architecture and Operations =
 
The architecture and structure of virtual and physical device drivers differ considerably from one another. A physical device driver is considered a true device driver in the sense that it has a unique and rigid file structure, and interfaces directly with the hardware. A virtual device driver is essentially a dynamic link library, and generally does not interface directly with the hardware. Instead, it is responsible for presenting a virtual copy of a hardware resource to a DOS session, and for coordinating physical access to that resource.
 
 
 
 
 
==Virtual Device Driver Architecture ==
 
Virtual device drivers manage I/O ports, device memory, and ROM BIOS services for the devices they virtualize. For hardware compatibility purposes, a virtual device driver should behave as much as possible like the physical hardware. Otherwise, incompatible emulation could result. In the case of system drivers, a virtual device driver should use a physical device driver to manipulate hardware, wherever possible.
 
 
 
 
 
=== Virtual Device Driver Structure ===
 
A virtual device driver is a 32-bit EXE file that may contain some or all of the following types of objects:
 
*Initialization code <br />*Initialization data <br />*Swappable global code <br />*Swappable global data <br />*Swappable instance data <br />*Resident global code <br />*Resident global data <br />*Resident instance data
 
The resident objects must be used for code and data that must be accessible at physical hardware interrupt time, that is, when a physical device driver calls the virtual device driver. A virtual device driver that does not interact with a physical device driver may not need any resident objects.
 
Virtual device drivers conform to the EXE32 Load Module format. A typical virtual device driver has a shared (global) code object, a shared (global) data object, and a private (instance) data object. It is possible for a virtual device driver to have multiple objects of each type. The global code and data objects are addressable in all process contexts. As with instance data for dynamic link libraries, the instance data object is per- DOS session data; that is, the same address in each DOS session context is initialized to the same initial state, but backed by different physical memory. Each object must be equal to or less than 64KB in size.
 
Run-time allocated memory can be allocated as either ''swappable''or ''fixed''. In addition, run-time allocated memory can also be:
 
*Private (per-DOS session), which is allocated out of the DOS session private memory area. This is the preferred method, and is suitable when memory is used only in the context of owning the DOS session. <br />*Shared (global), which is allocated from the system area. This should be used only when the allocation must be created, modified, or freed in an arbitrary process context.
 
 
 
 
 
==Virtual Device Driver Operations ==
 
Virtual device drivers are loaded and initialized before the shell is started, but after all the physical device drivers have been loaded and initialized.
 
 
 
 
 
=== Virtual Device Driver Loading ===
 
After the physical device drivers have been loaded, the DOS Session Manager is initialized (at OS/2 system initialization time), which then initializes the 8086 emulation component, and loads and initializes the virtual device drivers. An initial V86-mode memory map is constructed at this time for later use at DOS session creation.
 
The DOS Session Manager calls the loader to load virtual device drivers. Base virtual device drivers are loaded first, followed by installable virtual device drivers. ''Base''virtual device drivers are those that must be present for multiple DOS sessions to function. ''Installable''virtual device drivers are those specified in the &quot;DEVICE=&quot; lines in the CONFIG.SYS file. The multiple DOS session environment is still operable if any or all of these installable drivers fail to load. The one exception to this rule is the virtual video device driver, which is a base virtual device driver that is loaded in the CONFIG.SYS file.
 
The global code and data objects are loaded into the system area. This is required so that a physical device driver can pass along a hardware interrupt by calling a virtual device driver at interrupt time, regardless of the current process context.
 
The instance data objects are loaded into the address space between 1MB and 4MB for that session. This is the private address space managed by the DOS session. The loader and DOS Session Manager cause this allocation to occur so that the full ''virtual''state of the DOS session is contained below the 4MB line, thus allowing a single Page Directory Entry (PDE) to map a DOS session context. This has two benefits:
 
*Context-switching DOS sessions are fast, because only a single PDE needs to be edited.
 
*It is simple to maintain an alias region in the system area for each DOS session. This alias region is a 4MB-aligned, 4MB region of linear address space, whose base is called a ''DOS session handle'', which can be used in a base register to manipulate the instance data of that DOS session. This is an important feature, as it allows virtual device drivers to quickly access the instance data of any DOS session.
 
The virtual device driver entry point is called after the virtual device driver is loaded. The device driver returns a nonzero value to indicate a successful load, and returns 0 to indicate an unsuccessful load.
 
 
 
 
 
=== Virtual Device Driver Initialization ===
 
After a virtual device driver is loaded, it performs the following operations, as appropriate:
 
*Verifies the presence of corresponding hardware <br />*Establishes communication with the corresponding physical device driver <br />*Reserves regions of linear memory containing device ROM and RAM <br />*Saves the initial physical device state for initializing the virtual device state upon DOS session creation <br />*Set hooks for various DOS session events (creation, termination, foreground/background switch). See [[00594.htm|VDHInstallUserHook]]for a complete list of user hooks.
 
Virtual device drivers are initialized at Ring 0. For this reason, they cannot make Ring-3 API calls, and they only interact with OS/2 through use of the virtual DevHlp services.
 
 
 
 
 
==== Installing User Hooks ====
 
Each virtual device driver must use ''VDHInstallUserHook''to install a VDM_ CREATE hook. Virtual device drivers that use foreground and background (for example, video, keyboard, or mouse) must also install VDM_FOREGROUND and VDM_BACKGROUND hooks. For more information, see [[00594.htm|VDHInstallUserHook]].
 
 
 
 
 
==== Allocating Global Resources ====
 
Global resources are allocated at this time.
 
 
 
 
 
==== Registering Virtual Device Driver for Communications ====
 
When virtual device drivers communicate with the kernel, physical device drivers, other virtual device drivers, or with the Presentation Manager interface, the Dynamic Link mechanism is used to:
 
*Export virtual DevHlp services to virtual device drivers <br />*Export kernel data to virtual device drivers <br />*Export services from one virtual device driver to another
 
To restrict the modifications required for physical device drivers (which remain 16:16), virtual DevHlp services are provided so that a virtual device driver can establish communication with a physical device driver. This is no more than an exchange of entry points. At this point, the physical device driver and the virtual device driver can use any protocol to communicate. Although a suggested protocol is provided in [[00025.htm|Inter-Device- Driver Communication]], device drivers are not restricted to this.
 
 
 
 
 
=== DOS Session Creation and VDD Per-DOS Session Initialization ===
 
When the user starts a DOS application, the DOS Session Manager notifies the virtual device drivers that have registered creation hooks, and gives them an opportunity to do per-DOS session initialization. Memory is allocated and mapped into the V86-mode address space, and the DOS Emulation code is initialized. Control is passed to the DOS Emulation kernel to load the shell specified by DOS_SHELL (usually COMMAND.COM) and the application selected by the user.
 
Virtual device drivers perform the following operations (as appropriate) at DOS session creation time:
 
*Initialize the virtual device state <br />*Initialize the virtual ROM BIOS state <br />*Map linear regions (reserved at virtual device driver initialization time) to physical or linear memory <br />*Hook the I/O ports <br />*Enable or disable the I/O port trapping <br />*Hook the software interrupts <br />*Allocate per-DOS session memory
 
 
 
 
 
==== DOS Session Screen Switching ====
 
The OS/2 Session Manager notifies the DOS Session Manager of screen switches. The DOS Session Manager, in turn, notifies all virtual device drivers that are involved in these events (generally, the video, keyboard, and mouse virtual device drivers). The virtual video device driver (VVIDEO) takes appropriate steps to map in physical or logical video RAM and disable or enable I/O port trapping for the video hardware. The virtual keyboard device driver (VKBD) can set flags to control the reaction to keyboard polling behavior.
 
 
 
 
 
==== DOS Session Destruction ====
 
When a user exits a DOS session, the virtual device drivers are notified to clean up any resources owned by that DOS session (that is, the virtual device driver's DOS session termination entry points are called by the DOS Session Manager). Memory is released and the process is terminated, as is done with a normal OS/2 process. DOS sessions can also be terminated by a virtual device driver if unsupported behavior is detected, or by the DOS emulation component (if it is damaged or is otherwise unable to function).
 
 
 
 
 
=== Local and Global Information Regions ===
 
Most of the information available through information segments can be obtained by a virtual device driver using the virtual DevHlp service ''VDHQuerySysValue''. For further information, see [[00822.htm|VDHQuerySysValue]].
 
 
 
 
 
=== Virtual DevHlp (VDH) Services ===
 
A set of virtual DevHlp (VDH) services is used to provide an abstract but efficient means for virtual device drivers to interact with DOS sessions and the OS/2 kernel. These VDH services have the following characteristics:
 
*They are available through dynamic linking.
 
*They use the 32-bit calling conventions found in the function prototype definition VDHENTRY located in the MVDM.INC and .h include files.
 
*A return value of 0 (zero) usually means that the call failed. When 0 is returned, calling ''VDHGetError''returns a detailed error code. If this return is 0, the last call succeeded and 0 was a meaningful return value, not an error. A nonzero return value means that the call succeeded. See [[00502.htm|VDHGetError]].
 
*All pointer parameters are 0:32 flat pointers.
 
The Memory Management Virtual DevHlp services are used for:
 
*Mapping <br />*Reservation <br />*Allocation/reallocation/free
 
See [[00129.htm|C Language Virtual DevHlp Services]]for a list of the page-granular memory management services and a description of each virtual DevHlp.
 
 
 
 
 
== Inter-Device-Driver Communication ==
 
A virtual device driver can communicate with a physical device driver by using the Inter-device-Driver Communication (IDC) mechanism provided by the OS/2 operating system. A virtual device driver communicates with a physical device driver directly though a callable 16:16 interface, or by using the virtual DevHlp services that map to file system APIs. Virtual device drivers communicate directly with other virtual device drivers by using a set of the virtual DevHlp services.
 
The type and form of communication is defined by the physical or virtual device driver that provides the IDC entry point to be called. These device drivers must be aware of addressability and be sensitive to interrupt-time performance. For example, a virtual device driver that is not reflecting hardware interrupts to applications, and is in communication with a physical device driver, should use the virtual DevHlp services that map to File System APIs to communicate. However, if the virtual device driver must reflect hardware interrupts, the physical device driver should use the 16: 32 callable interface because it provides a more sensitive interface in which to communicate.
 
 
 
 
 
=== Virtual Device Driver and Physical Device Driver Interaction ===
 
Many virtual device drivers virtualize hardware that generates interrupts. Generally, these drivers must interact with a physical device driver to fully virtualize a device. Virtual DevHlp services are provided for the Open, Close, Read, Write, and IOCtl functions of the File System, which is then routed to the corresponding physical device driver. This is the simplest IDC mechanism for VDD/PDD communication.
 
Where interrupt-time or other high-performance PDD/VDD IDC requirements exist, the ''VDHOpenPDD''service is used to establish communication between a virtual device driver and a physical device driver by exchanging entry points, which use a 32-bit calling convention (refer to the multiple DOS session-specific equates found in the MVDM.INC include files). At this point, the virtual device driver and physical device driver are free to communicate through whatever private protocol is chosen, including exchanging register-based entry points. However, both drivers must agree on a shutdown protocol, that is, what is used to stop the communication if the virtual device driver must shut down. See [[00650.htm|VDHOpenPDD]]for more information.
 
 
 
 
 
=== Virtual Device Driver/Virtual Device Driver Communication ===
 
Because dynamic linking is supported between virtual device drivers, multiple virtual device drivers can support inter-virtual device driver communication through dynamic links. Where these device drivers are supplied by multiple parties and it is not required that all of the virtual device drivers in the set be present, dynamic linking does not work. The virtual DevHlp services, ''VDHRegisterVDD'', ''VDHOpenVDD'', ''VDHRequestVDD'', and ''VDHCloseVDD''are used to overcome this limitation of dynamic linking. For details, see [[00908.htm|VDHRegisterVDD]], [[00658.htm|VDHOpenVDD]], [[00966.htm|VDHRequestVDD]], and [[00301.htm|VDHCloseVDD]].
 
 
 
 
 
== Hardware Emulation and Interrupt Support ==
 
The major functions of software interrupt emulation are:
 
*Hook interrupt service: see [[00573.htm|VDHInstallIntHook]]<br />*Return to DOS session interrupt handler service: see [[00742.htm|VDHPushInt]]<br />*Hook return service: see [[00216.htm|VDHArmReturnHook]]
 
 
 
 
 
=== Hook Interrupt Service (VDHInstallIntHook) ===
 
The handler supplied to this service is a ''post-reflection handler''. Post- reflection handlers are called after the INT instruction is reflected into the DOS session interrupt code. A DOS session breakpoint address is put into the interrupt vector table entry at INIT time, so control returns to the kernel at the end of the DOS session's interrupt code chain. The virtual device driver interrupt handler chain is then called. The ROM routine address (or whatever was initially in the interrupt vector table), which was replaced by the DOS session breakpoint, is returned to, if the virtual device driver handlers do not call ''VDHPopInt''. See [[00687.htm|VDHPopInt]].
 
 
 
 
 
=== Return to DOS Session Interrupt Handler Service (VDHPushInt) ===
 
''VDHPushInt''calls the interrupt reflection code to change the DOS session's execution flow to the DOS session's interrupt code. This is done by building a return IRET frame on the client's stack with the CS:IP and flags from the kernel stack frame. The DOS session's CS:IP on the kernel stack is edited with the address from the DOS session's interrupt vector table. See the figure in the next section.
 
 
 
 
 
=== Hook Return Service (VDHArmReturnHook) ===
 
The ''VDHArmReturnHook''service allows the IRET to be hooked after the ''VDHPushInt''service is called. A DOS session breakpoint is allocated, and the address replaces the client's CS:IP on the return IRET frame. The client's CS:IP is saved. For additional information, see [[00208.htm|VDHArmContextHook]]and [[00742.htm|VDHPushInt]]. These services are shown in the following figure.
 
When building the return IRET frame, the client's stack pointer can wrap around from 0 to 0FFFEH. This does not terminate the DOS session. If the client's stack pointer is equal to 1 when this function is begun (before the virtual device driver handlers are called), the DOS session is terminated (to emulate the 386 hardware when it is in real mode).
 
When the virtual device driver installs an interrupt handler, a DOS session breakpoint is installed in the interrupt vector table before any DOS session code hooks. The DOS session breakpoint is executed after the DOS session interrupt code chain is executed but before ROM. The virtual device driver interrupt handlers are executed until one returns the ''stop chaining''indication, or the end-of-list is reached. ROM code is executed after the last virtual device driver handler is called unless one of these handlers calls ''VDHPopInt''. See [[00687.htm|VDHPopInt]]. This service emulates the IRET when a V86 code interrupt handler has popped off the IRET frame and restored the DOS session's CS, IP, and flags to the IRET frame contents. ''VDHPushInt''is used by the software interrupt instruction trap and by the virtual PIC device driver in the last stages of simulating hardware interrupts.
 
<pre class="western">
Kernel Stack        Client Stack      Kernel Stack      Client Stack
/------------\                        /--------------\    /------------\
|  0  |  SS  |                        |      |  SS  |    |  Flags    |
|------------|                        |--------------|    |------------|
|    ESP    |                        |    ESP      |    |    CS    |
|------------|                        |--------------|    |------------|
|  EFlags  |                        |    EFlags    |    |    IP    |
|------------|                        |--------------|    \------------/
|  0  |  CS  |                        |      |INT CS |
|------------|                        |--------------|
|    IP    |                        |    INT IP    |
\------------/                        \--------------/
Before VDHPushInt                    After VDHPushInt
 
 
  Kernel Stack      Client Stack
/--------------\    /------------\
|  0  |  SS  |    |  Flags    |
|--------------|    |------------|
|      ESP    |    |  VDMBP CS  |
|--------------|    |------------|
|    EFlags    |    |  VDMBP IP  |
|--------------|    \------------/
|  0  |INT CS |
|--------------|
|    INT IP    |
\--------------/
After VDHArmReturnHook
</pre>
 
 
 
 
==== Access to Ports Not Trapped by a Virtual Device Driver ====
 
In order to support DOS applications that use hardware that does not have virtual device drivers, a mechanism is provided for DOS applications to access ports on those devices. This is done by having the default handler for each I/O port turn trapping OFF for the port in question. All accesses after the first one go straight through to the hardware. This is done only for ports that are not trapped by a virtual device driver.
 
 
 
 
 
==== Global and Local Context Hooks ====
 
''Global context hooks''are a mechanism to delay work until the CPU is at task time (as opposed to interrupt time). If a global context hook is set at task time, the handler is called immediately. ''Local context hooks''are a mechanism to delay work until the CPU is at task time in the context of a specific process. When a virtual device driver sets a local context hook, that hook is guaranteed to execute before any user code (that is, code executing in V86 mode).
 
 
 
 
 
== Interrupts Supported by Multiple DOS Sessions ==
 
The following interrupts are supported by multiple DOS sessions:
 
*BIOS hardware interrupt support <br />*BIOS software interrupt support <br />*DOS software interrupt support <br />*Other software interrupt support
 
 
 
 
 
=== BIOS Hardware Interrupt Support ===
 
In previous versions of the OS/2 operating system, DOS applications were prevented from hooking hardware interrupts when the IRQ level was owned by an OS/2 device driver. A DOS application that violated this rule was terminated. In the current version of OS/2 this restriction is significantly relaxed. Depending on the support provided by the device's virtual device driver, DOS applications can now hook the hardware interrupt vector. The following list summarizes the support provided by OS/2 virtual device drivers for each of the hardware interrupt request (IRQ) levels:
 
IRQ 0 '''Timer (INT 08h)'''. The INT 08h handler is invoked on hardware interrupts from Channel 0 of the system timer. DOS applications can hook this interrupt. See the description of INT 08h in [[00037.htm|BIOS Software Interrupt Support]].
 
IRQ 1 '''Keyboard (INT 09h)'''. The INT 09h handler is invoked upon the make or break of every keystroke. DOS applications can hook this interrupt.
 
IRQ 2 '''The Cascade (Slave) Interrupt Controller'''. This controller supports interrupt request levels 8 through 15, as described below.
 
IRQ 3 '''Serial Ports (COM2, 3, 4)'''. These ports are supported when the virtual and physical COM device drivers are installed.
 
IRQ 4 '''Serial Port (COM1)'''. This port is supported when the virtual and physical COM device drivers are installed.
 
IRQ 5 '''Parallel Port 2'''. This hardware interrupt is simulated in DOS sessions .
 
IRQ 6 '''Diskette'''. This hardware interrupt is not simulated in DOS sessions. See the description of INT 0Eh in [[00037.htm|BIOS Software Interrupt Support]].
 
IRQ 7 '''Parallel Port 1'''. This hardware interrupt is simulated in DOS sessions .
 
IRQ 8 '''Real-Time Clock'''. This hardware interrupt is not simulated in DOS sessions. See the description of INT 70h in [[00037.htm|BIOS Software Interrupt Support]] .
 
IRQ 9 '''Redirect Cascade'''. A virtual device driver to simulate this hardware interrupt is not provided.
 
IRQ 10 '''Reserved'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]for more information.
 
IRQ 11 '''Reserved'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]for further information.
 
IRQ 12 '''Auxiliary Device'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]for further information.
 
IRQ 13 '''Mathematics Coprocessor (NPX)'''. NPX exception interrupts on IRQ 13 are reflected into the DOS session.
 
IRQ 14 '''Fixed Disk'''. This hardware interrupt is not simulated in DOS sessions .
 
IRQ 15 '''Reserved'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]below for more information.
 
 
 
 
 
==== Reserved IRQ Support in OS/2 ====
 
The OS/2 operating system does not provide support for optional devices on the ''Reserved''and ''Redirect Cascade''interrupt levels in OS/2-mode sessions, or in DOS sessions. Hooking one of these hardware interrupt request levels in a DOS application has no effect. If there is no physical device driver/ virtual device driver pair to service an interrupt, the DOS application's interrupt handler is not invoked, even though the hardware interrupts are generated.
 
These hardware interrupt request levels can be supported in a DOS session by a user-installed virtual device driver. However, a user-installed physical device driver is also required to provide this support since there is no mechanism for a virtual device driver to directly service a hardware interrupt.
 
 
 
 
 
=== BIOS Software Interrupt Support ===
 
BIOS software interrupt compatibility considerations and restrictions for OS/2 DOS sessions are shown below. Notice that only specific compatibility considerations and functional restrictions for users of BIOS in the DOS session environment of the OS/2 operating system are listed.
 
02h '''Nonmaskable Interrupt (NMI)'''. Not reflected to the DOS sessions; this BIOS interrupt handler is not invoked on NMI.
 
05h '''Print Screen'''. The BIOS INT 05h handler is supported. If the DOS application issues INT 05h, the contents of the video buffer is printed. The '''Shift+PrtScr'''keystroke combination (or equivalent) also invokes this function.
 
08h '''System Timer'''. This interrupt is invoked every time the system timer Channel 0 counts down to zero (normally, 18.2 times per second). DOS applications can hook this interrupt. However, in a DOS session these timer interrupts can come in a burst and have variable latency. The INT 08h interrupt handler is emulated by the virtual timer device driver.
 
0Eh '''Diskette'''. The INT 0Eh handler is not used to service interrupts generated by the diskette device (IRQ 6). DOS applications should not hook this interrupt.
 
10h '''Video'''. The INT 10h functions are fully supported in DOS sessions. The following INT 10h functions are emulated by the virtual video device driver .
 
0Eh Write Teletype (TTY) <br />13h Write String
 
'''Note:'''These functions are emulated only if the INT 10h vector is unmodified. If any piece of DOS session code hooks INT 10h, emulation occurs only if these functions are passed to the virtual video device driver's interrupt hook.
 
13h '''Hard Disk/Diskette'''. INT 13h emulation in a DOS session supports both removable and nonremovable media. The following subset of INT 13h functions are supported in DOS sessions:
 
00h Reset Diskette <br />01h Read Status <br />02h Read Sectors <br />03h Write Sectors (Diskette only) <br />04h Verify Sectors <br />05h Format Track (Diskette only) <br />08h Get Drive Parameters <br />0Ah Read Long (Fixed Disk only) <br />15h Read DASD Type <br />16h Change Status (Diskette only) <br />17h Set Disk Type (Diskette only) <br />18h Set Media Type (Diskette only)
 
14h '''ASYNC'''. When the virtual COM device driver is installed, all BIOS INT 14h functions are supported. These functions are emulated by the virtual COM device driver to enhance performance:
 
00h Initialize Port <br />01h Send Character <br />02h Receive Character <br />03h Read Status <br />04h Extended Initialize <br />05h Extended Port Control
 
15h '''System Services'''. These services are listed in the following table:
 
<pre class="western">/--------------------------------------------------------------\
|AH|Function                |Description                      |
|--+------------------------+----------------------------------|
|00|Cassette Motor ON      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|01|Cassette Motor OFF      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|02|Cassette Read          |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|03|Cassette Write          |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|0F|Format Periodic INT    |Error. On return, CF is set.      |
|--+------------------------+----------------------------------|
|4F|Keyboard Intercept      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|80|Open Device            |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|81|Close Device            |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|82|Program Terminate      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|83|Event Wait              |Support. Supported  by  VTIMER .      |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 84 | Joystick  Support          | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 85 | SysReq  Key  Pressed        | Support .  Issued  by  VKBD .  On        |
|    |                            | return ,  AL = 0  ( key  make ) ,  or  AL = 1    |
|    |                            | ( key  break ) .                          |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 86 | Wait                      | Support .  Supported  by  VTIMER .      |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 87 | Move  Block                | Error .  Managed  by  VXMS .              |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 88 | Get  Extended  Memory  Size | Error .  Managed  by  VXMS .  On  return , |
|    |                            | AX = 0  ( no  Extended  Memory ) .          |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 89 | Switch  to  Protect  Mode    | Error .  On  return ,  AX  ! = 0  ( fail      |
|    |                            | switch ) .                              |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 90 | Device  Wait                | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 91 | Device  Post                | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C0 | Get  System  Config  Parms  | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C1 | Get  EBIOS  Data  Area      | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C2 | PS / 2  Mouse  Functions      | Error .  On  return ,  CF  is  set ,  and    |
|    |                            | AH = 01  is  an  invalid  function .      |
|    |                            | Notice  that  all  mouse  support  is    |
|    |                            | through  INT  33h .                    |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C3 | Watchdog  Timeout          | Ignore .  On  return ,  CF  is  clear .    |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C4 | Prog  Option  Select        | Default .  Routed  to  ROM  BIOS .        |
\ -- - ---------- ---------- ---- - ---------- ---------- ---------- ---- / </pre>
16h '''Keyboard'''. The keyboard is supported directly by the ROM BIOS INT 16h routines.
 
17h '''Printer'''. The printer is supported (emulated) by the virtual parallel port device driver.
 
19h '''Restart'''. Restart (reboot) is supported. However, this does not operate in the same manner as DOS (the system is not restarted). If the DOS setting DOS_STARTUP_DRIVE is set, the diskette or image restarts. Otherwise, the DOS session is terminated.
 
1Ah '''Time-of-Day'''. The virtual CMOS device driver component supports read- only access to the Real-Time Clock device. Because of this restriction, the following BIOS INT 1Ah functions are not supported in a DOS session:
 
01h Set RTC Count <br />03h Set RTC Time <br />05h Set RTC Date <br />06h Set RTC Alarm <br />07h Reset RTC Alarm <br />08h Set RTC Activated Power-on mode <br />0Bh Set System Timer Day Counter <br />80h Setup Sound Multiplexer
 
A DOS application can read the Real-Time Clock Count, Time, and Date. The INT 1Ah functions are not emulated by the virtual CMOS device driver. Instead, the BIOS ROM functions are executed directly. The CMOS/RTC hardware is virtualized by the virtual CMOS device driver.
 
1Eh '''Diskette Parameters'''. The segment address of the diskette parameters table is stored in the INT 1Eh entry.
 
70h '''Real-Time Clock Interrupt'''. Interrupts from the Real-Time Clock (IRQ 8) are not reflected into DOS sessions. This software interrupt handler is not used for either alarm or periodic interrupts.
 
 
 
 
 
=== DOS Software Interrupt Support ===
 
The DOS emulation component supports the documented aspects of the following DOS features:
 
20h '''Program Terminate'''.
 
21h '''DOS Function Request'''. All documented and undocumented INT 21h functions are supported by DOS emulation. However the following functions are supported, with restrictions:
 
4410h <br />4411h <br />4B05h <br />5Dh <br />5Eh <br />5Fh <br />64h <br />69h <br />6Dh <br />6Eh
 
'''Note:'''Function 53h is not supported by DOS emulation.
 
22h '''Terminate Address'''.
 
23h '''Ctrl+Break Exit Address'''.
 
24h '''Critical Error Handler'''.
 
25h '''Absolute Disk Read'''.
 
26h '''Absolute Disk Write'''. A hard error is reported on requests for nonremovable media.
 
27h '''Terminate-and-Stay-Resident'''.
 
28h '''Idle Loop'''.
 
2Fh '''Multiplex'''. Time slice yield (AX = 1680h) is supported. When a DOS application issues INT 2Fh with AX = 1680h, it offers to yield its time slice. This can be used by DOS applications in busy wait loops (preserves all registers).
 
 
 
 
 
=== Other Software Interrupt Support ===
 
The following are other software interrupts supported in an OS/2 DOS session:
 
 
 
 
 
=== INT 33h - Mouse ===
 
Supported. When the OS/2 virtual mouse driver is installed, the full range of INT 33h functions, as defined in the ''Microsoft Mouse Programmer's Reference Guide''are available.
 
 
 
 
 
=== INT 4Bh - Virtual DMA Services (VDS) - Function 81h ===
 
Supported. When the OS/2 virtual DMA device driver is installed, the VDS INT 4Bh functions as defined in the ''Microsoft Virtual DMA Services Specification, Version 1.0''are available.
 
 
 
 
 
=== INT 67h - LIM Expanded Memory Manager (EMM) ===
 
Supported. When the OS/2 virtual expanded memory manager device driver is installed, the LIM EMM V4.0 INT 67h functions as defined in the ''Lotus/Intel /Microsoft Expanded Memory Specification, Version 4.0''are available.
 
 
 
 
 
=Base Virtual Device Drivers=
 
The following list contains all the base virtual device drivers included with OS/2:
 
*Virtual BIOS device driver (VBIOS) <br />*Virtual CMOS device driver (VCMOS) <br />*Virtual direct memory access device driver (VDMA) <br />*Virtual diskette device driver (VFLPY) <br />*Virtual hard disk device driver (VDSK) <br />*Virtual keyboard device driver (VKBD) <br />*Virtual numeric coprocessor device driver (VNPX) <br />*Virtual parallel port device driver (VLPT) <br />*Virtual programmable interrupt controller device driver (VPIC) <br />*Virtual timer device driver (VTIMER)
 
=== Virtual BIOS Device Driver ===
 
The virtual BIOS device driver (VBIOS) contains the mechanism to initialize the Interrupt Vector table, BIOS data area, extended BIOS data area (on a PS/2* personal computer adapter ROM area), and the system ROM. It also provides virtual access to Programmable Option Select (POS) registers (on a PS/2 personal computer) and supports some of the DOS settings.
 
 
 
 
 
=== DOS Session Creation ===
 
When a DOS session is created, the virtual BIOS device driver is responsible for allocating and initializing the following areas in the DOS session's address space with the respective values from physical memory:
 
*Interrupt Vector Table <br />*BIOS data area <br />*DOS communications area <br />*Extended BIOS data area (on a PS/2 personal computer).
 
The virtual BIOS device driver is also responsible for mapping the system ROM and adapter ROM into the address space of the DOS session. The per-DOS session copy of the POS registers is initialized at this time.
 
 
 
 
 
=== DOS Settings ===
 
The virtual BIOS device driver is responsible for Include/Exclude region support. The DOS setting MEM_INCLUDE_REGIONS gives the user an option to give more space to EMM/XMS. If the user knows that in a particular DOS session an adapter will not be used, then the linear region taken by that adapter can be given to EMM and XMS through MEM_INCLUDE_REGIONS. MEM_ EXCLUDE_REGIONS gives the user an option to restrict EMM and XMS from claiming a particular region. Both these options are provided through DOS settings. These DOS settings are only applicable at DOS session creation time.
 
 
 
 
 
=== Adapter ROM ===
 
At system initialization, the virtual BIOS device driver searches the region between the top of the DOS user space (RMSIZE) and 1MB to find all of the adapter ROM. Adapter ROMs that include the ROM signature will be found. In a normal DOS session creation (without any Include/Exclude properties specified), these linear addresses are mapped to corresponding physical ROM.
 
All the ranges specified in the DOS setting MEM_INCLUDE_REGIONS are taken out of the list used for mapping the linear addresses to corresponding physical ROM. As a result, MEM_INCLUDE_REGIONS is not mapped to physical ROM and it remains available to EMM or XMS.
 
For MEM_EXCLUDE_REGIONS, the virtual BIOS device driver reserves those regions and maps them to their corresponding physical addresses. This allows the user the ability to map adapter ROM that does not contain the ROM signature and adapter RAM.
 
 
 
 
 
=== Virtual CMOS Device Drivers ===
 
The virtual CMOS device driver consists of virtual support for the CMOS battery backed-up RAM, the Real-Time Clock (RTC) and the Nonmaskable Interrupt (NMI) disable logic. It provides virtual access to the address and data latches through virtual I/O ports. This component allows the majority of existing DOS applications that access its ports by direct access, or by normal BIOS calls, to operate without change.
 
 
 
 
 
=== Supported Functions ===
 
The following functions are supported by the virtual CMOS device driver:
 
*CMOS memory access <br />*I/O port support <br />*NMI-disable <br />*Read time-of-day and date <br />*Real-Time Clock and interrupt access
 
 
 
 
 
=== CMOS Memory Access ===
 
CMOS Memory Access provides support for passive reads and writes to virtual CMOS memory. The CMOS portion of the CMOS/RTC can be read or written. The virtual CMOS memory is initialized to the contents of the physical CMOS memory (at the time of DOS session initialization) through the physical clock device driver, which is the physical device driver of the virtual CMOS component. Values are written to the virtual CMOS memory in a buffer local to the DOS session. Unlike the physical CMOS memory, however, the contents of the virtual CMOS memory are lost when the DOS session is terminated.
 
 
 
 
 
=== Input/Output Port Support ===
 
The virtual CMOS device driver component monitors all accesses to its two DOS session I/O ports. The two ports are a write-only address latch and a read/write data latch. The address latch port has two functions, NMI Disable and CMOS/RTC Device Address Selection. The data latch is a register for holding a byte being transferred to or from the CMOS/RTC device.
 
 
 
 
 
=== Disabling Nonmaskable Interrupts ===
 
The Nonmaskable Interrupt (NMI)-Disable portion of the the address latch can be set or reset by a DOS application. However, changes to enable or disable NMI are otherwise ignored.
 
 
 
 
 
=== Read Time-of-Day and Date ===
 
This function presents the correct seconds, minutes, and hours to an application reading the appropriate locations. This function also provides atomic access to all values to avoid reading the values during time transition.
 
 
 
 
 
=== Real-Time Clock and Interrupt Access ===
 
The Real-Time Clock consists of a time-of-day clock, an alarm interrupt, and a periodic interrupt. Accesses to the Real-Time Clock to change the time of day or the timing mode, or to set an alarm or periodic interrupt, are disallowed. The CMOS/RTC registers related to the Real-Time Clock are supported for read-only access. Because interrupts can only be supported through write access to the ports, Real-Time Clock interrupts are not supported.
 
 
 
 
 
=== BIOS Support ===
 
The virtual CMOS device driver component does not emulate BIOS functions. Instead, it allows the existing BIOS functions to be used without change.
 
 
 
 
 
=== Unsupported Functions ===
 
From the perspective of the DOS session, the virtual CMOS device driver component supports access to I/O address space only. Therefore, the following functions are not supported:
 
*Set Time-of-Day and Date <br />*Set Time-of-Day Alarm <br />*Set/Enable Periodic Interrupt <br />*Enable Update Interrupt
 
 
 
 
 
=== Virtual Direct Memory Access Device Driver ===
 
The virtual direct memory access device driver (VDMA) provides per-DOS session per-direct memory access (DMA) channel virtualization. In addition, the virtual DMA device driver provides the following:
 
*Serializes the DOS session's DMA requests on a per-DMA channel basis (but allows simultaneous requests on different DMA channels)
 
*Converts the DOS session's linear addresses to physical addresses, and handles all the data movement required
 
*Handles all the restrictions of a DMA chip
 
*Supports the enhanced DMA operations and commands of a personal computer
 
*Optimizes DMA virtualization on personal computers by using the enhanced mode
 
*Supports INT 4Bh - Function 81h virtual DMA services
 
*Supports virtualized DMA in auto-initialization mode
 
In addition to the above features, the virtual DMA device driver also synchronizes the operations with other virtual device drivers registered on different DMA channels. A virtual device driver for a piece of hardware, which uses a DMA channel, registers with the virtual DMA device driver. The virtual device driver informs these virtual device drivers before starting and stopping the DMA operation on their channels.
 
 
 
 
 
=== Virtual Diskette Device Driver ===
 
The virtual diskette device driver (VFLPY) intercepts applications that try to access the diskette drive directly or issue INT 13h calls. This virtual device driver also serializes and coordinates I/O operations between multiple DOS sessions.
 
 
 
 
 
=== Obtaining Physical Diskette Hardware Ownership ===
 
When the system first starts up, the physical diskette device driver owns the physical diskette hardware. All diskette accesses from the OS/2 applications go through the file system or the physical diskette device driver, and are eventually serialized into requests. Initially, the virtual hard disk device driver does not own the diskette controller, and it hooks all the diskette ports. It requests ownership from the physical diskette device driver when the DOS session accesses any diskette port, or when the virtual DMA device driver informs the virtual hard disk device driver that the diskette DMA channel has been unmasked. If the immediate ownership request is not successful, the DOS session is blocked until the physical diskette device driver calls back and grants the ownership.
 
 
 
 
 
=== Releasing Physical Diskette Hardware Ownership ===
 
Once the virtual diskette device driver has obtained the diskette ownership , it does not release ownership until the physical diskette device driver requests it, or the diskette motor is turned OFF.
 
 
 
 
 
=== Physical Diskette Interrupt Routing ===
 
Physical diskette interrupts are always routed to the physical device driver by the interrupt manager. If the virtual diskette device driver has the exclusive hardware ownership when the interrupt happens, the physical diskette device driver routes the event to the virtual diskette device driver, which simulates the interrupt to the DOS session.
 
 
 
 
 
=== Virtual Hard Disk Device Driver ===
 
The virtual hard disk device driver (VDSK) provides virtual disk support for multiple DOS sessions and supports access to the disk through BIOS (INT 13h) calls. Since BIOS accesses the hardware ports directly, the virtual hard disk device driver component overrides the BIOS by directly emulating INT 13h for hard disks. The virtual hard disk device driver component does not provide I/O port level access to the disk controllers. Access to hardware ports that are supported for the diskette drive, and BIOS INT 13h calls, are not emulated; instead, they are run from the actual BIOS. INT 13h support includes:
 
AH=00h Reset diskette system <br />AH=01h Status of disk system <br />AH=02h Read sectors into memory (both diskette and hard disk) <br />AH=03h Write sectors from memory (diskette only) <br />AH=04h Verify sectors (both diskette and hard disk) <br />AH=05h Format track (diskette only) <br />AH=08h Get current drive parameters (both diskette and hard disk) <br />AH=0Ch Seek <br />AH=15h Get disk type (both diskette and hard disk) <br />AH=16h Change of disk status (diskette only) <br />AH=17h Set disk type (diskette only) <br />AH=18h Set media type for format (diskette only)
 
The INT 13h emulator is also responsible for maintaining the diskette and hard disk areas of the ROM BIOS data area.
 
Typical steps of an INT 13h access are listed below:
 
*A DOS application accesses the disk through the INT 13h interface. The INT 13h call is trapped by the virtual hard disk device driver.
 
*A request packet is built and sent to the physical hard disk device driver . The DOS session is then blocked, waiting for the request to finish.
 
*Upon receiving the request packet, if the disk is currently busy, the physical hard disk device driver queues the request.
 
*When the request is completed, the physical device driver notifies virtual device driver, which unblocks the DOS session.
 
Because the virtual hard disk device driver component does not support register level accesses of the disk controller, all accesses to its registers are trapped and ignored.
 
'''Note:'''Timing-related copy protection can fail because real-time access is not guaranteed. Sector WRITE and FORMAT requests are not supported for hard disk. Sector WRITE and FORMAT operations are supported for diskette.
 
 
 
 
 
=== Virtual Numeric Coprocessor Device Driver ===
 
The virtual numeric coprocessor device driver (VNPX) provides virtual coprocessor (80 x 87) support for multiple DOS sessions. The virtual numeric coprocessor device driver coordinates exception and interrupt reflection for the real coprocessor. Machines with the 80386 B1 processor, or without a coprocessor, do not have coprocessor support.
 
 
 
 
 
=== Virtual Keyboard Device Driver ===
 
The virtual keyboard device driver (VKBD) consists of virtual support for the keyboard. It allows keystrokes to be passed from the keyboard to the DOS session and text to be pasted from another application into the DOS session as keystrokes. This virtual device driver also allows existing DOS applications that access the keyboard to operate without change. Such applications can access the keyboard through BIOS calls, access to the BIOS data area, or monitoring of the keyboard interrupt, and reading keystroke data directly from the I/O ports.
 
The virtual keyboard device driver addresses the following issues:
 
*'''INT 21h Access'''. DOS applications can access the keyboard by opening the &quot; CON:&quot; (console) device, or by default standard input access.
 
*'''BIOS Access'''. DOS applications can access the keyboard through BIOS INT 09h and INT 16h.
 
*'''I/O Port Access'''. DOS applications can access the keyboard by reading and writing I/O ports 60h and 64h. This access is not restricted to reading scan codes, and can include other types of access (such as LED control).
 
*'''Pasting'''. Data can be pasted from other OS/2 applications.
 
*'''Internationalization'''. Keystrokes are translated according to the current keyboard translation table and code page.
 
*'''Idle Detection'''. DOS applications must not waste excessive CPU time when in input peek loops.
 
 
 
 
 
=== Levels of I/O Support ===
 
The various levels of support for the virtual keyboard device driver are as follows:
 
*BIOS support <br />*CON device driver support <br />*DOS support <br />*Idle detection support <br />*I/O port support <br />*Pasting support
 
 
 
 
 
=== BIOS Support ===
 
Since the BIOS INT 16h service only references the BIOS data area for keystrokes, the BIOS continues to provide this service.
 
The BIOS INT 09h interrupt service routine, however, is emulated within the virtual keyboard device driver. When the INT 09h vector is invoked, the virtual keyboard device driver passes the character to the physical device driver, which translates the character according to the current translation table.
 
It is possible for an application or a DOS memory-resident program to hook the INT 09h vector. Often, such applications simply monitor keystrokes, and pass them on to the previously-hooked interrupt service routine. In this case, the virtual keyboard device driver emulation code still runs and translates scan codes according to the current translation table. Otherwise , if an application that has hooked INT 09h fails to pass the scan code on, then the scan code is not translated, or placed into the BIOS data area by the virtual keyboard device driver.
 
 
 
 
 
=== CON Device Driver Support ===
 
This support consists of allowing the virtual console device driver to be replaced. Although the default virtual console device driver. restricts keyboard access to BIOS calls, user-supplied drivers can access the keyboard through I/O ports or through the BIOS data area.
 
 
 
 
 
=== DOS Support ===
 
This support consists of keyboard access through the various INT 21h functions. In particular, this is support for access from the DOS emulation component. For compatibility, DOS calls the virtual console device driver to read keystrokes. This allows the virtual console device driver to be replaced without ill effect.
 
 
 
 
 
=== Idle Detection Support ===
 
DOS applications waste CPU time in a multitasking system when they peek for input in a loop. Idle conditions are detected when:
 
*The application is polling the keyboard using INT 16h in a loop <br />*DOS is polling in an input loop <br />*Repeated INT 28h calls are received from a DOS application <br />*INT 2Fh, AX=1680h yield calls are received <br />*DOS INT 21h, service 0Bh calls are received
 
Two services are available to device drivers to assist and for handling, [[00951.htm|VDHReportPeek]]and [[01126.htm|VDHWakeIdle]].
 
 
 
 
 
=== I/O Port Support ===
 
The virtual keyboard device driver is responsible for supporting programs that access the keyboard ports directly. These ports provide access to data ports on the hardware that controls I/O to the keyboard. This support is provided primarily for applications that simply read the scan code directly from the port. However, other functions are possible, such as setting the key repeat rate. Repeat rates affect the entire system; per-DOS session repeat rates are not supported. Extended scanner functions, such as providing keyboard pre-controller translation, are not supported; such commands are ignored.
 
 
 
 
 
=== Pasting Support ===
 
The virtual keyboard device driver supports two levels of pasting from the clipboard into a DOS session; ''fast pasting''and ''slow pasting''. In fast pasting support, characters from the clipboard are put directly into the BIOS buffer. For those DOS applications that get their key strokes from the BIOS key buffer (through INT 16h), fast pasting is adequate. For those DOS applications that hook INT 09h or INT 15h (AH=4Fh), key scan sequences are expected, which must be generated by the slow pasting mechanism.
 
In slow pasting, every character from the clipboard is reverse translated into scan sequence and can involve generating make-and-break scans of not only the character itself, but also the make and break of the shift keys in order to adjust the upper, lower, or control case of the character. It can even involve generating '''Alt+numeric keypad'''scan sequences for those characters, which cannot be directly typed on the keyboard (such as graphics characters or international characters).
 
 
 
 
 
=== Virtual Programmable Interrupt Controller Device Driver ===
 
The virtual PIC device driver (VPIC) is responsible for the virtualization of the 8259 Programmable Interrupt Controller (PIC) for multiple DOS sessions and for the simulation of interrupts to DOS sessions. Performance is a major requirement for hardware interrupt simulation. In this book, ''hardware interrupt''and ''interrupt''have the same meaning. ''Simulated interrupt'' , ''interrupt simulation'', and ''hardware interrupt simulation''all refer to the virtual PIC device driver sending an interrupt to a DOS session.
 
The virtual PIC device driver supports the hardware interrupt-related services needed by virtual device drivers and DOS sessions. The services include setting handlers to trap EOI and IRET events, simulating interrupts to DOS sessions, and handling PIC I/O accesses by DOS sessions. See [[00150.htm|Virtual Interrupt Services]]for a list of these virtual DevHlp services. The virtual PIC device driver maintains a per-DOS session virtual PIC state so that each DOS session appears to have its own independent 8259 Programmable Interrupt Controller. Provisions are included to demand page DOS sessions interrupt handling code. The virtual PIC device driver provides a DOS session with the following services:
 
*Virtualization of the 8259 PIC ports:
 
-Separate master and slave PICs <br />-Mask and unmask IRQ commands <br />-Specific and nonspecific EOI commands <br />-Read IR and IS register commands
 
*Hardware interrupts that can be be postponed until task time so that a DOS session can be paged
 
*Interrupts from an optional hardware adapter, which does not have a virtual device driver and a physical device driver, that can be simulated to a DOS application
 
The virtual PIC device driver provides virtual device drivers with:
 
*A high-performance mechanism to send hardware interrupts to DOS sessions:
 
-Support for more than one virtual device driver to share an interrupt level <br />-Support for a virtual device driver to regain control when a DOS session issues EOI commands, or when a DOS session executes the IRET at the end of the interrupt routine
 
*A mechanism for virtual device drivers to send a virtual EOI to the virtual PIC device driver
 
*A way to block until an interrupt is simulated
 
*A mechanism to query a DOS session's virtual IRQ state or status:
 
-Masked or unmasked state (IMR) <br />-Waiting to be sent to a DOS session state (IRR) <br />-Executing DOS session's interrupt handler code state (ISR) <br />-Pending interrupt routine IRET state
 
Hardware interrupt simulation is closely tied to the PIC virtualization. Virtual device drivers need a fast mechanism to call a DOS session's real- mode interrupt handler for a hardware interrupt. Because paging of DOS sessions (and therefore DOS session interrupt handlers) is required, simulated interrupts are delayed until the task-time context of the target DOS session.
 
 
 
 
 
=== Virtual Timer Device Driver ===
 
The virtual timer device driver (VTIMER) provides virtual timer support for multiple DOS sessions. This virtual timer device driver emulates the Intel* * 8254A Programmable Interval Timer.
 
 
 
 
 
=== DOS Support ===
 
The virtual timer device driver provides the following:
 
*Virtualization of timer ports to allow reprogramming of the interrupt rate and the speaker tone frequency <br />*Distribution of timer ticks to DOS sessions <br />*Maintenance of the timer tick count in the BIOS data area <br />*Serialization of Timer 0 and Timer 2 between the virtual timer device driver and the physical timer device driver
 
 
 
 
 
=== Virtual Parallel Port Device Driver ===
 
The virtual parallel port device driver (VLPT) consists of virtual support for direct hardware access to the three parallel ports (LPT1, LPT2, and LPT3), and for the printer-related BIOS entry points (Printer I/O INT 17h, Print Screen INT 05h). Existing DOS applications that access the parallel ports, either by direct access to the ports or by printer BIOS, operate without change. The VLPT provides the virtualization to allow multiple DOS applications to access virtual printer hardware simultaneously. This virtual device driver, in conjunction with the spooler, attempts to prevent multiple DOS applications that transmit data by using BIOS functions or direct hardware access, from intermixing output at the parallel port.
 
The virtual parallel port device driver consists of several sections:
 
*BIOS INT 17h Emulation <br />*BIOS INT 05h Emulation <br />*Printer Close Processing <br />*Direct I/O Access
 
 
 
 
 
=== BIOS INT 17h Emulation ===
 
One method DOS applications can use to send data to a printer is to use BIOS interrupt 17h. The VLPT emulates BIOS INT 17h and passes these requests through the file system to the physical parallel port device driver (PLPT) by using the system services ''VDHOpen'', ''VDHWrite''and ''VDHClose''. See [[00636.htm|VDHOpen]]. [[01140.htm|VDHWrite]], and [[00294.htm|VDHClose]]. These functions are not passed to the BIOS for processing.
 
The BIOS INT 17h emulation supports three functions:
 
*'''Print Character'''. The Print Character function buffers single character requests in the virtual device driver buffer associated with each device in a DOS session. When the buffer becomes full, its contents are sent to the VLPT by using ''VDHWrite''. If the device is not open, the VLPT issues ''VDHOpen''to obtain a file handle and start a printer data stream. See [[01140.htm|VDHWrite]]and [[00636.htm|VDHOpen]].
 
*'''Initialize'''. The virtual parallel port device driver buffer is sent to the physical parallel port device driver by using ''VDHWrite''. The printer data stream is closed by using ''VDHClose''. See [[01140.htm|VDHWrite]]and [[00294.htm|VDHClose]].
 
When the spooler is enabled, closing the data stream closes the spool file. Any subsequent printing will open a new spool file. The beginning of the spool file contains escape sequences to reset the printer to its power-on defaults. When the spooler is disabled, no initialization of the device takes place.
 
*'''Read Status'''. The Read Status function returns the contents of the virtual device status register.
 
See [[00078.htm|Printer Close Processing]]for the possible methods of closing a printer data stream opened with BIOS INT 17h.
 
 
 
 
 
=== BIOS INT 05h Emulation ===
 
The method used to send data from the display to the printer (LPT1) is to press the '''Print Screen'''key. DOS applications can also initiate a Print Screen function by issuing a call to a BIOS INT 05h function. The virtual parallel port device driver passes this request to BIOS for processing. The virtual device driver performs some special processing to prevent the INT 05h request from intermixing with an INT 17h print request to the same device. Also, two BIOS INT 05h requests cannot be performed simultaneously from within the same DOS session. The second print screen request is ignored.
 
 
 
 
 
=== Printer Close Processing ===
 
BIOS printer interrupts operate on a single-character basis, which can have a negative impact on printer and system performance. For this reason, the VLPT buffers BIOS print requests. When the buffer becomes full, print requests are sent to the file system to be spooled and printed. The size of the application's print request is rarely an even multiple of the VLPT buffer size. This causes the virtual device driver to provide methods of flushing the remaining characters in its buffer.
 
A virtual parallel port device driver's BIOS INT 17h buffers are flushed in one of four ways:
 
*DOS settings PRINT_TIMEOUT automatic close feature <br />*Ctrl+Alt+Print Screen key sequence (''VDHPrintClose'') <br />*Application termination <br />*DOS session termination
 
 
 
 
 
=== DOS Settings PRINT_SEPARATE_OUTPUT ===
 
The user can set the DOS setting PRINT_SEPARATE_OUTPUT to specify whether or not the virtual parallel port device driver should separate INT 17h output sent to the same device by two different DOS programs that are running in the same DOS session.
 
If set OFF, the VLPT will not open a new data stream each time the Program Segment Prefix (PSP) changes.
 
 
 
 
 
=== PRINT_TIMEOUT ===
 
The user can set the DOS setting PRINT_TIMEOUT to specify the length of time in seconds that the VLPT will wait between occurrences of INT 17h before flushing its buffer. A setting of 0 (zero) specifies to wait indefinitely, that is, to never flush the buffer using the timeout mechanism. The PRINT_TIMEOUT mechanism flushes the buffer and closes the data stream automatically each time the DOS application stops printing by using INT 17h for the time specified.
 
 
 
 
 
=== Ctrl+Alt+Print Screen Key Sequence ===
 
After the DOS application has printed the entire file (issued INT 17h), the virtual parallel port device driver can be alerted to flush the remaining characters in its buffer by pressing '''Control+Alt+Print Screen'''. The virtual keyboard device driver calls ''VDHPrintClose''(an exported virtual parallel port device driver entry point) to alert the virtual parallel port device driver that the key sequence has been pressed, and to flush the buffer. See [[00728.htm|VDHPrintClose]].
 
 
 
 
 
=== Application and DOS Session Termination ===
 
The virtual parallel port device driver is notified when the application terminates or the DOS session is closed, and will flush the remaining characters in its buffer.
 
 
 
 
 
=== Direct I/O Access ===
 
The virtual parallel port device driver, at its initialization, registers an Inter-device Driver Communication (IDC) with the physical parallel port device driver. The VLPT requests exclusive access to the parallel port hardware through the VDD/PDD IDC when a DOS application interfaces directly with the hardware. Data transmitted using the direct I/O access method will bypass the spooler. Completion of exclusive access occurs when the key combination '''Ctrl+Alt+Print Screen'''is pressed, the application is terminated , or the DOS session is terminated.
 
 
 
 
 
=== Share Access ===
 
Share Access is an option of the spooler that enables multiple DOS applications to simultaneously access the parallel port. The option is enabled by selecting the '''Share Access'''checkbox in the Parallel Port Settings dialog box found on the output page of the Print Object Setting Notebook.
 
Once enabled, multiple copies of DOS applications that access security devices attached to the parallel port can be started simultaneously. Use of this option turns OFF the serialization of accesses (the protection mechanism) to the parallel port.
 
One DOS application can overwrite another that is using the parallel port, causing the latter application to fail.
 
 
 
 
 
=== Interrupt-Driven Data Transfers ===
 
The virtual parallel port device driver reflects virtual hardware interrupts to applications executing in a DOS session.
 
 
 
 
 
=== Bidirectional Data Transfers ===
 
The extended mode of the PS/2 personal computer parallel port allows the port to be used as a bidirectional eight-bit parallel interface. This capability is supported by the virtual parallel port device driver when DOS applications directly access the parallel port hardware.
 
 
 
 
 
=== Enabling DOS Print TSRs ===
 
The DOS operating system implements its printing function by passing print requests from its INT 21h interface to the single character BIOS INT 17h interface. Many Terminate-and-Stay-Resident (TSR) DOS applications hook into the INT 17h vector chain to perform additional processing (such as font support, spooling, and character set downloading) before sending the print data to the device attached to the parallel port. They expect all print data to pass through to the INT 17h interface.
 
Since these additional functions are now provided by the OS/2 operating system and since BIOS INT 17h is not performance-sensitive, the operating system passes INT 21h print requests as buffers through the file system to the physical parallel port device driver for transmission instead of sending print requests as single character requests to BIOS INT 17h. The gain, by this approach, is the increased throughput and better utilization of the device attached to the parallel port. The trade-off has been the inability of some DOS TSR applications to perform their print functions.
 
LPTDD.SYS is a DOS device driver that can be installed to convert DOS session INT 21h print requests to INT 17h and thereby enable this class of DOS TSRs. By using the &quot;DEVICE=&quot; statement in the CONFIG.SYS file or the DOS_DEVICE option in DOS Settings, the device driver can perform the INT 17h conversion either in all DOS sessions, or in individual DOS sessions corresponding to the two methods, respectively.
 
 
 
=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.
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"
{| class="wikitable"
!Item Added or Changed ||Date Item Added or Changed||Compatibility of Addition or Change
!Item Added or Changed ||Date Item Added or Changed||Compatibility of Addition or Change
|-
|-
Line 1,199: Line 94:
|}
|}


[[Category:Driver Articles]]
[[Category:Device Driver Reference]]

Latest revision as of 04:44, 29 September 2022

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

Virtual Device Driver Reference for OS/2
Part 1. Overview
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
Assembler Language Syntax
Notices
Glossary

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
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
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.
Notices
This appendix 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.

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

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
Retrieved from "https://www.edm2.com/index.php?title=Virtual_Device_Driver_Reference_for_OS/2&oldid=78604"