VDDR/2 - Installable Virtual Device Drivers

From EDM2
Jump to: navigation, search

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

Installable Virtual Device Drivers

The following list contains all the installable virtual device drivers included with OS/2:

  • Virtual ASPI device driver (VASPI)
  • Virtual CDROM device driver (VCDROM)
  • Virtual COM device driver (VCOM)
  • Virtual DOS protect-mode extender device driver (VDPX)
  • Virtual DOS protect-mode interface device driver (VDPMI)
  • Virtual WIN-OS/2 support device driver (VWIN)
  • Virtual expanded memory specification device driver (VEMM)
  • Virtual extended memory specification device driver (VXMS)
  • Virtual keyboard device driver services
  • Virtual Advanced OS/2 Joystick Device Driver
  • Virtual mouse device driver (VMOUSE)
  • Virtual touch device driver (VTOUCH), discussed in Chapter 5
  • Virtual video device drivers (VCGA, VEGA, VMONO, VVGA, VXGA, V8514A), discussed in Chapter 5

Virtual ASPI Device Driver

The virtual ASPI device driver (VASPI) enables ASPI support for ASPI applications running in a DOS or WIN-OS/2 session of OS/2. Under DOS, users typically load an ASPI manager that routes all requests directly to the hardware. ASPI drivers, such as ASPIDISK and ASPICD, send requests to the ASPI manager, which then sends the command on to the appropriate device.

Under OS/2, applications that wish to send ASPI requests do so by routing the requests to a device manager (OS2ASPI.DMD), which converts them into requests that are recognizable to any SCSI-adapter device driver (ADD).

During initialization, VASPI establishes communication with OS2ASPI.DMD. This allows VASPI to route all DOS SCSI requests to OS2ASPI.DMD.

Virtual CDROM Device Driver

The virtual CDROM device driver (VCDROM) enables data and audio support for CDROM applications running in DOS sessions of OS/2. Under DOS, audio and other IOCtl support is provided through the pass-through function of the CDROM file system driver, MSCDEX* DOS applications build a device driver IOCtl request packet and then send it to MSCDEX to be forwarded to the CDROM device manager for service. The position of VCDROM in the CDROM subsystem is shown in the following figure.

     +-------------+      +-------------+
     | OS/2 CDROM  |      | DOS CDROM   |
     | Application |      | Application |
     +-------------+      +-------------+
                 |               |    +----- ----+ INT 21h
+-------------+  |               |        +-------------+
|   MMPM/2    |  |               |        |     DOS     |
|  Subsystem  |  |               |        | File System |
+-------------+  |     INT 2fh   |        +-------------+
       +-------- |     + - - - - + - - - - - - - + - - - - +
                 |     |                                   |
                 |     |  +-------------+ +-------------+  |
                 |     |  | OS/2 Virtual| | DOS MSCD001 |  |
                 |     |  |Device Driver| |Device Driver|  |
                 |     |  +-------------+ +-------------+  |
                 |     |                                   |
                 |     + - - - - + - - - - - - - + - - - - +
                 |               |               |
 File System API | ------------------------------+
                          Virtual Device Helper API
          +-------------+
          | OS/2 CDROM  |
          | File System |
          +-------------+
                   File System Helper API
          +-------------+
          | OS/2 CDROM  |
          | Device Mgr  |
          +-------------+
                 | SCSI-2 Commands
                 |-------------+
                 | 
                 |      +-------------+
                 |      |   SCSI-2    |
                 |      |  Emulation  |
                 |      |    Filter   |
                 |      +-------------+
                 |             | Vendor-Unique
        +-----------------+    | SCSI-1 Commands

 +-------------+   +-------------+
 |   Non-SCSI  |   |  SCSI Bus   |
 | Host Adapter|   |   Adapter   |
 |Device Driver|   |Device Driver|
 +-------------+   +-------------+

 +-------------+   +-------------+
 |   Non-SCSI  |   |    SCSI     |
 | Host Adapter|   | Bus Adapter |
 +-------------+   +-------------+

 +-------------+   +-------------+
 | CDROM Drive |   | CDROM Drive |
 +-------------+   +-------------+

The virtual CDROM device driver provides two distinct features that are necessary to support DOS CDROM applications. First, this virtual device driver emulates MSCDEX by providing the services that CDROM applications require for installation (for example, the version of MSCDEX, the number of CDROM devices that are present in the system, and the drive letters that correspond to the CDROM devices). A listing of MSCDEX Command Codes is given in the following table:

Command Function Description
00h Get Number of CDROM Drive Letters
01h Get CDROM Drive Device List
02h Get Copyright File Name
03h Get Abstract File Name
04h Get Bibliographic File Name
05h Read VTOC
06h Reserved
07h Reserved
08h Absolute Disk Read
09h Absolute Disk Write
0Ah Reserved
0Bh CDROM Drive Check
0Ch MSCDEX Version
0Dh Get CDROM Drive Letters
0Eh Get/Set Volume Descriptor Preference
0Fh Get Directory Entry
10h Send Device Request
11h - 0FFh Reserved

The second, and major, function of the virtual CDROM device driver is to translate the DOS-style IOCtls into requests that the physical CDROM device driver can understand.

A comparison of DOS-style IOCtls and OS/2-style IOCtls is given in the following table:

DOS Category Function OS/2 Category Function IOCtl/Command Description
02h 00h *** (7) Return Address of Device Header
02h 01h 80h 70h Return Location of Head
02h 04h 81h 60h Return Audio-Channel Information
02h 06h 80h 60h Return Device Status
02h 07h 80h 63h Return Sector Size
02h 08h 80h 78h Return Volume Size
02h 09h *** (8) Return Changed Media Code
02h 0Ah 81h 61h Return Audio-Disc Information
02h 0Bh 81h 62h Return Audio-Track Information
02h 0Ch 81h 63h Return Audio-Subchannel Q Info
02h 0Eh 80h 79h Return UPC
02h 15h 81h 65h Return Audio-Status Information
03h 00h 80h 44h Eject Disc
03h 01h 80h 46h Lock/Unlock Door
03h 02h 80h 40h Reset Drive
03h 03h 81h 40h Audio-Channel Control
*** (1) 80h 61h Identify CDROM Driver
*** (2) 80h 72h Read Long
*** (3) 80h 50h Seek
*** (4) 81h 50h Play Audio
*** (5) 81h 51h Stop Audio
*** (6) 81h 52h Resume Audio

Note:

  1. Command is not available in DOS.
  2. DOS Extended Device Driver Command 130h.
  3. DOS Extended Device Driver Command 131h.
  4. DOS Extended Device Driver Command 132h.
  5. DOS Extended Device Driver Command 133h.
  6. DOS Extended Device Driver Command 136h.
  7. Command is not available in OS/2.
  8. Corresponds to OS/2 block device driver command 01h.

The virtual and physical CDROM device driver's provide roughly the same device services, but through different IOCtl interfaces. The DOS CDROM interface is available through the IOCtl input and output device driver request packets, while the physical CDROM device driver provides its services through the generic IOCtl interface. The virtual CDROM device driver maps the DOS IOCtls to their corresponding physical device driver IOCtls, and then passes them on to the physical CDROM device driver. On return from the physical CDROM device driver, the virtual CDROM device driver also maps the return information and the return codes back into the DOS-style environment.

The virtual CDROM device driver provides full emulation of MSCDEX. MSCDEX Version 2.21 is fully supported under IBM Operating System/2

Virtual COM Device Driver

The virtual COM device driver (VCOM) consists of virtual support for the serial communication I/O ports, and for the serial channel-related BIOS entry points. It provides support in each DOS session for up to four COM ports. In addition, this component allows existing DOS applications, which access communications channels by direct access to the I/O ports or by normal BIOS calls, to operate without change.

The VCOM only supports access to communication channels that are physically present on a given system. This does not include support for accessing communication devices that can be redirected by network software. From the perspective of the DOS session, the VCOM supports access through:

  • BIOS
  • I/O address space

Support Summary

The VCOM directly supports invocations of BIOS INT 14h, instead of allowing the BIOS to access the ports directly. However, direct access to the virtual I/O ports is also supported. Direct access to I/O ports results in emulation of a communication controller with the INS8250 UART. When referenced through the virtual I/O ports, the VCOM also provides all support for virtual interrupt indication. The hardware appears to the DOS session as a serial interface supported by standard expansion bus serial ports on a PS/2 personal computer.

Interrupt Service

The virtual COM device driver provides full support for the virtualization of communication channel interrupts, and follows the same logic as the actual hardware.

Virtual DOS Protect-Mode Extender Device Driver

The virtual DOS protect-mode extender device driver (VDPX) provides address translation from protect mode to V86 mode for DOS protect-mode interface (DPMI) applications. This translation is necessary because DPMI applications run in protect mode but issue interrupt requests, which can be handled in V86 mode, to perform various system services. When running in protect mode, the application is using selectors instead of segments. Therefore, any data buffers in the protect-mode memory address space (above 1MB) must be copied into a region of memory within the V86 address space.

The vdpx registers the DOS setting DPMI_DOS_API, which controls whether the VDPX is active or not. If the user selects:

Enabled
The VDPX always translates the interrupts it supports from protect mode to V86 mode.
Auto
The application must first issue the following INT 2Fh in protect mode to begin the translation:
     ENTRY     AX = 168Ah
               DS:(E)SI points to the ASCIIZ
                  string "MS-DOS"
     EXIT      If VDPX fails initialization:
                  AL = 0x8A
Note: MS-DOS is a trademark of Microsoft Corporation.
Disabled
The VDPX does not perform any address translation.

DPMI applications can provide their own translation services. Therefore, it might be unnecessary for the VDPX to perform any address translation.

The VDPX translates various interrupts from protect mode to V86 mode, including INT 10h, 15h, 21h, 25h, 26h, 2Ah, 33h, and 5Ch. The VDPX translates most of the commonly-used functions for these interrupts. After the virtual device driver translates the interrupt, the V86-mode interrupt service routine (or the virtual device driver, if it has hooked the interrupt) handles the interrupt request. After issuing the interrupt in V86 mode, the VDPX ensures that any data returned from the V86 service is copied into the data area originally passed in by the DPMI application. The registers and flags returned by the V86-mode handler (other than mode- sensitive registers such as segment registers) are returned to the DPMI application.

Virtual DOS Protect-Mode Interface Device Driver

The virtual DOS protect-mode interface device driver (VDPMI) provides Version 0.9 DPMI support for applications in a DOS session. DPMI applications run in protect mode instead of V86 mode. The VDPMI provides the necessary support to allow DPMI applications to run under OS/2. The VDPMI supports the DPMI memory limit DOS setting, which allows the user to specify how much protect-mode memory should be available to the DOS session .

The VDPMI supports INT 31h in protect mode, which is issued by DPMI applications to request a DPMI service. The VDPMI device driver keeps track of the resources used by the application, such as memory, selector, interrupt, and debug watchpoint management. This virtual device driver also supports the mechanisms necessary to allow DPMI applications to switch the DOS session in and out of V86 mode (translation services). When a DPMI application terminates, the virtual DPMI device driver ensures that all of the DPMI application resources are freed.

If a DPMI application issues an interrupt in protect mode and there is no protect-mode interrupt handler, the request is reissued in V86 mode. Most virtual device drivers hook only interrupt requests in V86 mode, so they are not called until the interrupt is reflected to V86 mode unless the virtual device driver has issued VDHSetVPMIntVector. (see VDHSetVPMIntVector). However, it is up to the application or the virtual DOS protect-mode extender device driver (VDPX) to do any address translation that is necessary, such as converting the selector address to a segment address. See #Virtual DOS Protect-Mode Extender Device Driver for further information on address translation.

DPMI 1.0 Functions Supported

  • 401 - Get DPMI Capabilities
  • 504 - Allocate Linear Memory Block
  • 509 - Map Conventional Memory in Memory Block
  • E00 - Get Coprocessor Status
  • E01 - Set Coprocessor Status
  • Separate Local Descriptor Table (LDT) and Interrupt Descriptor Table (IDT) for each protect-mode client

Virtual WIN-OS/2 Support Device Driver

The virtual WIN-OS/2* support device driver (VWIN) provides interfaces and transport services which enable DOS and OS/2 applications to do communication between processes in a very fast, event-driven, specialized way. The clipboard, DDE and WIN-OS/2 window functions use these interfaces to exchange data between WIN-OS/2 sessions and the Presentation Manager desktop.

The data and messages which pass through VWIN are not actually inspected nor understood by the driver. Instead, the driver provides a store and forward mechanism. To accomplish this, an interface is exported for each environment. In an OS/2 session, a thread of the OS/2 process blocks in VWIN waiting for data from any of the other processes. In a DOS session and in a WIN-OS/2 session, the address of a notification routine is registered, and this routine is invoked when a message or data is available from one of the other processes using the interface. Interfaces are provided which allow for sending messages and data to other specific processes or for broadcasting to all processes. This system is outlined in the illustration below:

          +------------+       +----------------+
          |   OS/2     |       |DOS or WIN-OS/2 |
          |  Process   |       |      Process   |
          +------------+       +----------------+

                |    +------------+     |
                |    |   VWIN     |     |
                +--- |            | ----+
                     +------------+

Virtual Expanded Memory Specification Device Driver

The Lotus/Intel/Microsoft Expanded Memory Specification, Version 4.0 (LIM 4) provides a standard interface for the use of expanded memory on 8086- family computers. This specification offers up to 32MB of expanded memory divided into as many as 255 expanded memory objects. Regions of these objects can be mapped at 8086 addresses (below 1MB), thus allowing DOS applications access to large memory allocations. However, the memory that is to be accessed must be explicitly mapped.

Alternate page tables are provided for quick switches among mappings and function calls with remapping. These tables are also used as the means to save and update mappings, or move and exchange memory contents.

The OS/2 virtual expanded memory specification (EMM) device driver:

  • Implements all the INT 67h functions in the LIM 4.0 EMS, except those for the DMA registers.
  • Provides each DOS session with a separate EMS emulation. A DOS session has its own set of expanded objects so that features such as interprocess communication work as if each DOS session was running on a different real 80386 DOS sessions cannot affect the availability of objects, or access memory in other DOS sessions.
  • Provides support for remapping of conventional memory (below 640KB) for use by programs.
  • Provides a configurable limit for the amount of EMS memory available per DOS session.
  • Supports multiple physical to single logical mappings. Different 8086 addresses can map to the same expanded memory object address.

Configurable Defaults

Default values are set for properties in order to be appropriate in most instances. However, users can change these defaults, if desired. The following defaults can be set in the CONFIG.SYS file:

Default EMS Memory Size Default limit set by specifying the number of kilobytes of memory desired on a "DEVICE=" line in the CONFIG.SYS file. Alternately, the limit can be specified by using a switch, /S=xxx, on the line. For example:

DEVICE=path\VEMM.SYS 1024

or

DEVICE=path\VEMM.SYS/S=1024

Default EMS Low OS Map Region Size of remappable conventional memory set by using the /L switch. For example:

DEVICE=path\VEMM.SYS /L=256

EMS High OS Map Region Size of extra mappable memory (other than the 64KB minimum) set by using the /H switch. For example:

DEVICE=path\VEMM.SYS /H=32

EMS Frame Location Default frame position set by using the /F switch. Any value in the DOS setting list can be chosen as the default. For example:

DEVICE=path\VEMM.SYS /F=AUTO

or

DEVICE=path\VEMM.SYS/F=C800

When devices without virtual device drivers can directly map memory, the Include and Exclude regions are crucial for the virtual EMM device driver. These properties are supplied by another component, and determine which regions can be directly mapped to physical addresses by default when touched by applications.

The virtual DevHlp Mapping services allow the same master page to be aliased in by successive pages in the V86 address space. In particular, EMM allows an application to map in the same 16KB size range of memory repeatedly (for example, a 64KB page frame could consist of the same four pages mapped four times). Since DMA requires contiguous physical memory, I/ O that involves aliased pages, which map to the same physical page, must be handled by breaking up DMA requests.

Virtual Extended Memory Specification Device Driver

The Extended Memory Specification, Version 2 provides a standard interface for the use of extended memory on 80286- and 80386-based machines. The XMS specifications manage three distinct regions of memory:

  • High Memory Area (HMA). Extended memory accessible from real mode by enabling the A20 address line. Code can be executed in the HMA, if the A20 line is enabled. The high memory area is exactly 65520 bytes (64KB-16 bytes ) long.
  • Extended Memory Blocks (EMBs). Blocks of extended memory accessible by way of XMM function calls through a handle. Without leaving V86 mode, code cannot be executed from EMBs; they serve only for data storage. The specification offers up to 64MB of extended memory divided into as many as 255 blocks.
  • Upper Memory Blocks (UMBs). Block of memory located between 640KB and 1MB. Once a UMB is allocated, its memory is always available. Since the memory lies in conventional memory, code can be executed in it at any time.

The virtual extended memory specification (XMS) device driver:

  • Implements all the functions in XMS 2.0.
  • Provides each DOS session with a separate XMS emulation. Each DOS session has its own high memory area, upper memory blocks, and extended memory blocks so that features such as interprocess communication perform as if each DOS session was running on a different real 80386. A DOS session cannot affect the availability of objects, or access memory in another DOS session.
  • Provides configurable limits for the amount of XMM memory available across DOS sessions, and a limit per DOS session. An installed program in the start list should be able to override the per-DOS session limit, subject to the constraint given by the overall limit. In addition, it should be able to disable XMS completely for a particular DOS session, if its installation would conflict with the program running in the DOS session.

A CONFIG.SYS line of the form DEVICE=path\VXMS.SYS [options], will interpret options as "/keyword=value". These options are as follows:

/XMMLIMIT=g,i Set the global (system-wide) maximum memory usage of the virtual XMS device driver to g KB, and set a per-DOS session maximum of i KB. These values are large enough to accommodate an automatic 64KB allocation in each DOS session for the HMA. Values are restricted to the range 0 through 65535 (=64KB).
The values of g and i are rounded up to the nearest multiple of four. Specifying i=0 suppresses XMS installation in all DOS sessions unless overridden by a DOS session-specific configuration string. The default for /XMMLIMIT is 16384,2048.
/HMAMIN=d Set the minimum request size (in kilobytes) for an HMA request to succeed. Values are restricted to the range 0 through 63. The default for / HMAMIN is 0.
/NUMHANDLES=n Set the number of handles available in each DOS session. Each handle occupies eight bytes. Values are restricted to the range 0 through 128. The default for /NUMHANDLES is 32.
/UMB Instruct XMM to create Upper Memory Blocks (UMB). The default is / NOUMB.
/NOUMB Instruct XMM to not create Upper Memory Blocks (UMB). The default is /NOUMB.

Virtual Keyboard Device Driver Services

The virtual video device driver utilizes the Post Peek and Post Read requests from the virtual keyboard device driver to post events to the DOS session Window Manager when the windowed DOS session video state changes. In addition to generating the VVDEVENT_INPUT event to the DOS session Window Manager to adjust window orientation, these notifications also serve to suggest to the virtual video device driver when to check for palette and LVB changes, which generate VVDEVENT_PALETTE and VVDEVENT_LVB events.

The virtual keyboard device driver uses the Post Paste request to indicate whether paste operations can start or end. The virtual video device driver posts the VVDEVENT_PASTE or VVDEVENT_ENDPASTE event to the DOS session Window Manager, based on the type of paste operation requested.

Virtual Advanced OS/2 Joystick Device Driver

The virtual joystick device driver has two main purposes:

  • To provide a reliable joystick device driver for DOS games running under OS/2.
  • To provide a standard device driver for OS/2 game programmers that they can use as an interface between the PC game adapter port and their products .

See the OS/2 Input/Output Device Driver Reference for detailed information on understanding how the IBM PC Game-Port Adapter works and using the Advanced OS/2 Joystick Device Driver.

Understanding How the Joystick Device Driver Works

The pre-emptive multi-tasking nature of OS/2 can cause DOS applications reading the game adapter port to deduce incorrect positions for the joysticks connected. The solution to this potential inaccuracy, implemented in the joystick device driver, is to regularly sample the game adapter port inside the Physical Device Driver (PDD) and then return fabricated values to the DOS application that reflect that state. With the logic for regular sampling already in the PDD, it is simply a matter of activating the procedure.

Before any of this can be initiated, however, access to the game port by the DOS application must first be trapped. Whenever I/O ports are to be trapped or emulated, an OS/2 Virtual Device Driver (VDD) is required. The VDD works in conjunction with the PDD to provide the device emulation. The VDD does this by capturing port reads and returning values that reflect the current state as determined by the PDD. The VDD is also responsible for determining whether a given virtual DOS machine (VDM) is to have direct access to the port and, if it is, for obtaining ownership of the VDM.