VDDR/2 - Virtual Mouse Device Driver

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

Virtual Mouse Device Driver

This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions. The virtual mouse device driver also supports applications that use the BIOS INT 15h (AH = C2h) pointing-device services.

Some of the most common mouse driver services, available through the INT 33h interface, are listed below:

• Driver-state save, restore, and disable
• Light-pen emulation
• Miscellaneous features
• Position and button-event notification
• Position and button-data tracking
• Selectable pel-to-coordinate and mickey-to-pel mappings
• Video-mode tracking
• Video pointer management (location and appearance)

There are no restrictions on any use of the INT 33h interface, even when a DOS session is in background mode. The only difference between background, focused, and foreground DOS session support is that no mouse events are posted for a background DOS session. Mouse events are posted to full-screen DOS session from the physical mouse device driver, and are posted through the Presentation Manager shield to focused, windowed DOS sessions. The pointer position should remain unchanged as long as a DOS session is in background mode, unless an application initiates pointer movement of its own. In that case, the virtual pointer position changes but nothing is drawn (not even in virtual video space).

The virtual mouse device driver also supports applications that use the BIOS INT 15h (AH=C2h) Pointing Device services.

INT 33h Support

INT 33h support is provided directly by the virtual mouse device driver. If a DOS session is running in a window (instead of full screen), and is in focus, the physical mouse device driver routes the mouse events to the Presentation Manager single queue device driver, then to the shield, and eventually to the virtual mouse device driver. The virtual mouse device driver then buffers the mouse event as if it were for the full-screen DOS session. When the DOS setting MOUSE_EXCLUSIVE_ACCESS is ON for a windowed DOS session, all mouse events go directly from the physical mouse device driver to the virtual mouse device driver, bypassing the Presentation Manager interface. This property is necessary for those applications that track and draw their own mouse pointer.

Driver-State Save, Restore, and Disable

Services are provided to copy all per-DOS session mouse-state information to an application-defined block and back again. When the driver is disabled , it ignores all INT 33h requests and physical mouse device driver events.

Light-Pen Emulation

Whenever this INT 33h feature is enabled, a virtual mouse device driver INT 10h hook is established, and INT 10h light-pen functions are emulated with mouse position and button data.

Miscellaneous Features

The INT 33h interface provides a function to read-and-reset mouse motion counters, which are simply software counters of total horizontal and vertical mickeys. These counters are simulated within the virtual mouse device driver by taking reported pel movements and converting them to mickeys (based on the current mickey-to-pel ratio). This interface must also provide counts of button presses and releases, and the positions at the time of the last press and release. These are maintained by the virtual mouse device driver without any assistance from the physical mouse device driver.

Position and Button-Event Notification

The INT 33h interface provides services to allow the DOS session to receive call-back notification for selectable motion and button events. These call- backs occur at DOS session task time, and do not involve the physical mouse device driver.

Each time the DOS session is notified of a mouse event, it might have to notify the DOS session's user-defined mouse-event subroutine, depending on whether the DOS session's application has registered the subroutine (by way of an INT 33h function) and what events the caller has asked to be notified of.

A registered subroutine is called by requesting a pseudo interrupt in the DOS session. A simulated interrupt service routine (loaded into each DOS session at creation) immediately EOIs (ends the interrupt) and then proceeds to notify the DOS session's registered subroutine. In order to pick an IRQ that is guaranteed not to conflict with any other virtual device driver, the DOS session queries the physical mouse device driver at initialization for its physical IRQ.

Note: It is not important to have the real mouse IRQ, but simply an IRQ that no other virtual device driver needs.

Movement-only events are coalesced. As an event is posted from the physical mouse device driver, the DOS session compares it with any previous event in the event buffer; if it is a movement-only event, the current event accumulates with the previous event in the buffer. This process continues until a non-movement-only event occurs or the current movement event is simulated, thus reducing interrupt-simulation overhead during rapid event- generation periods.

Position and Button-Data Tracking

Other services within the INT 33h interface allow the DOS session to poll the virtual mouse device driver on the current mouse status. There are also services to return the last button press and also the last button-release event.

Selectable Pel-to-Coordinate and Mickey-to-Pel Mapping

Through the INT 33h interface, the DOS session can control the acceleration of the DOS session mouse pointer by varying both the thresholds and the multipliers. This is managed by the entirely by the virtual mouse device driver, without assistance from the physical mouse device driver, which reports only raw mickey events to the DOS session for full-screen DOS sessions.

For windowed DOS sessions, the PM Shield reports absolute pel mouse events to the virtual mouse device driver The virtual mouse device driver maps the raw delta mickeys to the DOS session's current virtual-coordinate grid.

Video Mode Tracking

The virtual mouse device driver receives notification of video mode changes from the virtual video device driver, so that the pointer size and bounds can be appropriately set.

The virtual mouse device driver must be notified of changes in the physical dimensions of the screen. It uses that information to map the raw mickeys into pel coordinates. The virtual device driver uses a device-independent interface to notify the virtual mouse device driver of mode changes so that the virtual mouse driver is capable of supporting any video device without code changes.

Video Pointer Management

The virtual mouse device driver tracks the pointer location, and whether or not the pointer is visible. The actual drawing and hiding of the pointer, however, is handled by the virtual video device driver.

Interfaces are provided by the virtual video device driver to the virtual mouse device driver to perform the following operations:

• Define pointer This describes the desired pointer shape and always is issued prior to making a pointer visible for the first time. An error might be returned if the virtual video device driver does not provide pointer support for the current video mode, thus permitting the virtual mouse device driver to skip further drawing and moving requests. The virtual video device driver refuses calls it cannot support.
• Draw pointer A position, in pel coordinates, is provided. For text modes, the virtual video device driver maps chunks of pels to individual character locations. The size of a chunk is 8 pels x 8 pels, unless the mode is 40- column, in which case the chunk size is 16 pels x 8 pels. A video page parameter is provided to support the INT 33h SetCRTPage service. Draw requests without intervening Remove requests are treated as Move requests.
• Remove pointer Deletes pointer from the screen.

INT 15h (AH=C2h) Support

All the published Pointing Device BIOS services (INT 15h, AH=C2H) are emulated in the virtual mouse device driver For a complete listing of these services, refer to the IBM Personal System/2 and Personal Computer BIOS Interface Technical Reference.

Virtual Mouse Device Driver Services

For the virtual mouse device driver, the virtual video device driver provides a VDHRequestVDD function, as well as several direct interfaces for pointer drawing operations. The following VDHRequestVDD service is provided:

   VDHRequestVDD
   (
      HVDD  hvddVideo,
      HVDM  hvdm,
      INT   iFunc,       /* Virtual video device driver EVREQ_POSTMOUSE (4) */
      PVOID pReqIn,      /* Undefined.                                      */
      PVOID pReqOut      /* Undefined.                                      */
   );                    /* Returns TRUE.                                   */

The virtual mouse device driver must return the address of a function that permits the virtual video device driver to obtain mouse position and button status during processing of the INT 10h, Query Light Pen function, when light pen emulation is enabled for the active DOS session. Also, whenever the DOS session changes video modes (including the initial mode change that takes place during DOS session creation), the virtual video device driver notifies the virtual mouse device driver of the new mode and screen dimensions.

Virtual Touch Device Driver

The virtual touch device driver (VTOUCH) provides support for the INT 7Fh in multiple DOS sessions. This virtual device driver is limited (by default) to making actual touch XYZ data available only to full-screen DOS programs because the physical device driver, which handles the touch data interrupts, cannot determine which window to send the touch data to when running with the Presentation Manager session in the foreground.

In contrast, the physical mouse device driver can determine which window to send the mouse data to because it is able to feed the single queue of the Presentation Manager. The Presentation Manager can then determine, based upon the event XYZ data, which window is to receive the event. If the window is a DOS window, it calls the virtual device driver.

For those DOS applications that receive full screen XYZ touch data while running in a window, the DOS setting TOUCH_EXCLUSIVE_ACCESS is provided. This DOS setting effectively turns off mouse emulation and directs all touch data to that window. The (now device-independent) INT 7Fh continues to function in a window. However, touch data is not available to the application until it is switched to full screen. In all other respects, the application functions exactly as before.

DOS mouse applications are not subject to this restriction because they can run in a windowed or full screen DOS session with touch input in the form of emulated mouse data.

INT 7Fh Support

To access the touch-sensitive display device, DOS applications use the software interrupt 7Fh (INT 7Fh) interface. OS/2 applications use the Tou xxx API. The virtual touch-sensitive device driver provides this by using a standard DOS session software interrupt hook. This virtual device driver runs in protect mode (which allows it to share code in all DOS sessions) and virtualizes all the hardware-dependent features that the INT 7Fh interface provides (for example, changing thresholds).

In addition to the touch-sensitive device capability, it is also possible to use the touch-sensitive display to emulate the IBM* mouse. In this case, the standard mouse INT 33h API (for DOS) is used.

Note that only DOS sessions running full screen can obtain full touch XYZ data. Windowed DOS sessions running under Presentation Manager are restricted to emulated mouse data. A DOS touch application that started as full screen stops receiving touch data if it is switched to a window, and starts receiving data again if it switched back to full screen. Conversely, a DOS touch application that is started in a window does not receive data until it is switched to full screen, and does not stop receiving data until it is switched back to a window.

Discussion

A virtual video device driver is used by OS/2 as a virtual display device for DOS applications executing in a DOS session, by providing virtual hardware support. Virtual video device drivers are required when it is necessary for multiple DOS sessions to share one or more video devices.

The virtual video device driver manages access to video memory, video registers, and video adapter ROM BIOS Special functions have been defined to permit other OS/2 Ring 3 components (such as the DOS Session Manager and the Presentation Manager display device driver) to obtain the vital video state information necessary to window a DOS session on the Presentation Manager desktop.

For simplicity, a dedicated virtual video device driver should be targeted to a specific video device. This reference manual includes a set of virtual video device drivers that can be used as templates for enhancement modifications to any of the currently supported devices, or they can be used as samples to create a virtual device driver from scratch for a similar but compatible device. For example, the OS/2 virtual Super VGA device driver (VSVGA.SYS) is a derivative of the virtual VGA device driver (VVGA.SYS).

The following virtual video device drivers, which cover an extensive range of the most commonly used video devices, are included in this reference manual:

Virtual CGA device driver	VCGA
Virtual EGA device driver	VEGA
Virtual MONO device driver	VMONO
Virtual VGA device driver	VVGA
Virtual XGA* device driver	VXGA
Virtual SVGA device driver	SVGA
Virtual 8514/A device driver	V8514A

The video devices for which the OS/2 provides virtual video device drivers include:

• Western Digital**
• ATI**
• Cirrus Logic**
• Headland Technology**
• Trident**
• Tseng**
• Video 7**

Note: Specific Super VGA chip revision and model support can be found in VVDP.H.

Installable Virtual Video Device Driver Architecture

The architecture of a virtual video device driver adheres to the architecture defined for all virtual device drivers. However, some parts of the multiple DOS sessions architecture have been designed primarily for virtual video device drivers, as follows:

• Foreground and background notification hooks
• Freeze and thaw services
• Title change and code-page change notification hooks

A significant amount of the primary virtual video device driver code involves communication with the DOS session Window Manager. A Remote Procedure Call (RPC) mechanism must be used to communicate between the DOS session Window Manager and a virtual video device driver under the following conditions:

• The DOS session Window Manager is a Ring 3 component (lowest privilege level)
• Virtual device drivers run at Ring 0 (highest privilege level)
• DOS sessions have no Local Descriptor Table (LDT), and therefore cannot attach to Dynamic Link Libraries (DLLs)

For this purpose the DOS session Window Manager creates a thread that calls the virtual video device driver to wait for a video event from any of the currently windowed DOS sessions.

Design of Installable Virtual Video Device Drivers

A virtual video device driver is a base device driver, although a "DEVICE=" statement in the CONFIG.SYS file is used to specify one or more virtual video device drivers to load. The DOS session Manager and DOS session Window Manager identify a virtual video device driver by its registered name. For example, a virtual video device driver for the primary display would register as VVIDEO1$, a virtual video device driver for the secondary display device would register as VVIDEO2$, and so forth.

Note: Support of multiple DOS sessions is disabled if no virtual video device driver claims ownership of the primary display device after virtual video device driver loading and initialization is completed.

Supporting DOS-Standard Adapters and Modes

IBM-compatible CGA, EGA, VGA, XGA, and 8514/A adapters are supported as primary display devices; monochrome adapters are supported as secondary display devices. For these devices, the standard configurations (including the amount of video memory, type of monitor and so forth), are supported. However, there are a few exceptions. For example, other dual-adapter combinations such as EGA/monochrome with CGA/color, or VGA/monochrome with CGA/color are not supported.

All EGA monitor combinations (RGB, ECD, and monochrome) and VGA, XGA, 8514/ A monitor combinations (i512/8513, 8514, and 8515), as well as all EGA memory combinations (64KB, 128KB, 192KB, and 256KB) of the 8514/A monitor are supported. The type of monitor used with a monochrome or CGA adapter is immaterial; that is, the behavior of the adapter is not affected.

There are some limitations, however. For example, an EGA, VGA, or Super VGA with a 2xx port configuration, instead of the standard 3xx configuration, is not supported. Also, an EGA display with only 64KB of display memory cannot support high-resolution graphic modes in a window, due in part to the video mode used concurrently by Presentation Manager (640 x 200, 16 colors), which consumes nearly all of the 64KB of on-board video memory. In addition, blinking attributes (whether in text or graphics modes) cannot be emulated in a DOS window.

A significant portion of the primary virtual video device drivers involves communication with the DOS session Window Manager. This includes providing a set of services to fully describe a DOS session's video state and a set of notifications to signal when the video state changes, so that a DOS session being windowed remains relatively synchronized with its associated DOS session that is executing in the background.

Because the DOS session Window Manager, OS/2 Session Manager, and Presentation Manager display device driver execute in Ring 3, and while the virtual video device driver runs in Ring 0, a system entry point is necessary for these Ring 3 components to communicate with the virtual video device driver. The virtual video device driver provides the following DosRequestVDD service to:

• DOS session Window Manager

-Set Access

-Set Focus

-Set Lock

-Query Mode Info

-Query Cursor Info

-Query Palette Info

-Copy LVB Content

-Copy Bit Map Content

-Wait for Video Event

-Control Event

• PM Display Device Driver

-Set Display Requirements

-Request off-screen VRAM

-Free off-screen VRAM

-Request VGA Controller

-Free VGA Controller

-Query VRAM Status

Note: See the Display Device Driver Reference for a detailed explanation of the DosRequestVDD functions provided by the virtual video device driver.

There are two kinds of DOS session window support:

• Displaying a running image in a window
• Displaying a frozen image in a window

The latter is a subset of the former. The virtual video device driver always attempts to provide support for displaying a running image and for standard text and CGA graphics modes this is always possible, but there are graphics modes cases where that is not possible. One example is the 64KB EGA mode; other examples are the XGA and 8514/A modes.

Support for the XGA or 8514/A graphics modes is not a matter of sufficient memory but of the sheer complexity of virtualizing the 8514/A hardware. In addition, if a DOS application uses VGA graphics modes on an 8514/A system, it will not be able to use the VGA memory if a monitor being used as a secondary display by other tasks in the system is connected to the VGA.

There is no known, reliable method of determining whether a monitor is connected to the VGA or Super VGA. The 8514/A can detect a limited set of IBM-compatible, fixed-frequency monitors whereas the XGA, using DMQS, has the potential of identifying all monitor types, including OEMs.

In an 8514/A system, there is no architected way for the virtual video device driver to determine whether the VGA is in use by another process or session. Conversely, there is no way for the virtual video device driver to claim the device and prevent other processes or sessions from later acquiring the device.

Notes:

1. 256-color modes will not be accurately rendered in a window even when the PM display driver supports 256 colors, because the DOS session Window Manager does not provide Palette Manager support.
2. High-resolution graphics modes on a 64KB EGA currently will not be rendered properly in a DOS window because the memory organization is substantially different (planes 0 and 1 and planes 2 and 3 are chained together).

OS/2 provides a single, generic Super VGA virtual device driver that supports the majority of the Super VGA video adapters made with the above- mentioned Super VGA chip sets. However, there are a small number of adapters that cannot be reliably virtualized, due to the way they are designed. For example, adapters that require multiple OUTs to a specific port before permitting the extended clock bits to be programmed fall into that category.

Of the 8514/A graphics modes, only the 1024 x 768 256-color mode has been tested for accurate rendering in a window.

Virtual Video Device Drivers

The following list contains the installable virtual video device drivers that are included with the Developer's Toolkit for OS/2:

• Virtual CGA device driver (VCGA)
• Virtual EGA device driver (VEGA)
• Virtual MONO device driver (VMONO)
• Virtual VGA device driver (VVGA)
• Virtual XGA device driver (VXGA)
• Virtual 8514/A device driver (V8514A)

The architecture of the virtual video device driver adheres to the architecture defined for all virtual device drivers. However, some portions of the multiple DOS session architecture have been designed primarily for (or used by) virtual video device drivers:

• Foreground and background notification hooks
• Freeze and thaw services
• Title change and code-page change notification hooks

A significant portion of the primary display virtual device drivers involves communication with the DOS session Window Manager. This includes providing a set of services to fully describe a DOS session's video state and a set of notifications to signal selected changes in state, so that a window remains relatively synchronized with its associated DOS session.

Discussion

Because the DOS session Window Manager is a Ring 3 component, virtual device drivers run at Ring 0, and DOS sessions have no LDT (and therefore cannot attach to DLLs), a Remote Procedure Call (RPC) mechanism must be used to communicate between the DOS session Window Manager and a virtual device driver. The DOS session Window Manager creates a thread for this purpose, which calls the virtual video device driver to wait for a video event from any of the currently windowed DOS sessions.

Virtual video device drivers are base device drivers. "DEVICE=" statements in the CONFIG.SYS files are used to specify one or more virtual video device drivers to load. The DOS session Manager and DOS session Window Manager identify a virtual video device driver by its registered name (for example, a virtual video device driver for the primary display device would register as VVIDEO1$, one for the secondary display device would register as VVIDEO2$, and so forth). After virtual video device driver loading and initialization is complete, if no virtual device driver has registered for the primary display device, multiple DOS session support is disabled.

IBM-compatible CGA, EGA, VGA, XGA, and 8514/A adapters are supported as primary display devices, and MONO adapters are supported as secondary display devices. For these devices, all the standard configurations (that is, amount of video memory, type of monitor, and so forth) are supported. However, there are a few exceptions. For example, support for other dual-adapter combinations, such as EGA/monochrome with CGA/color, or VGA/ monochrome with CGA/color, are not specifically supported. In addition, all EGA monitor combinations (RGB, ECD, and monochrome), EGA memory combinations (64KB, 128KB, 192KB, and 256KB), VGA and 8514/A monitor combinations (8512, 8513, and 8514), and VGA and XGA monitor combinations (8512, 8513, 8514, and 8515) are supported. The type of monitor used with a monochrome or CGA adapter does not affect the behavior of the adapter.

Virtual and Nonvirtual Operation

For optimal performance and compatibility, the virtual video device drivers support full-screen operation. In this mode, there is no visual difference between DOS and DOS session operation. For convenience, an option appears on the DOS session system menu to convert the DOS session from windowed mode to full-screen mode and back. Virtual video device drivers support full-screen operation by performing the following operations:

• Registering foreground and background VIDEO_SWITCH_NOTIFICATION hooks with the DOS session Manager
• Allocating a save and restore video buffer
• Installing I/O hooks to shadow key video port accesses
• Mapping physical video memory into the appropriate video address space
• Compelling text-mode fonts to match the currently selected code page
• Providing pointer drawing services to the virtual mouse device driver to define, draw, and erase pointer images

When a DOS session does not own the physical display (that is, when it is background), the virtual video device drivers:

• Install I/O hooks to track and emulate all video port accesses.
• Map appropriate system memory to the active portions of the video address space.
• Report video events to the DOS session Window Manager (assuming the Presentation Manager is active and the DOS session is an unminimized window). This includes changes to:

-Mode

-Palette

-Cursor

-Video memory

-Input events

-Scroll or string events

-Paste continue or terminate (through the virtual keyboard device driver)

-Session title change

-Screen-switch or video memory allocation errors

At any time, the DOS session Window Manager (or other processes that have access to a DOS session's process ID) can update a DOS session's window state:

• Windowed or nonwindowed
• Focus or nonfocus
• Minimized or unminimized
• Lock or unlocked

as well as query any aspect of a DOS session's video state:

• Mode
• Palette
• Cursor
• Video memory
• Wait for video events
• Cancel wait for video event

Mouse-Independent Pointer Drawing Services

When the virtual video device driver creates a DOS session for the first time, it opens the virtual mouse device driver. If the open is successful, it provides the virtual mouse device driver with the following entry points:

• Show Pointer
• Hide Pointer
• Define Text Pointer
• Define Graphics Pointer
• Set Video Page
• Set Light-Pen Emulation

Also, whenever the DOS session changes video modes (including the initial mode change that takes place during DOS session creation), the virtual video device driver notifies the virtual mouse device driver of the new mode, the screen dimensions, and so forth.

Built-in Extended INT 10h and INT 2Fh Services

The EGA register interface is integrated into the virtual video device driver as part of its INT 10h interception logic. This interface is a set of INT 10h services that are used by applications to make drawing operations and simultaneous use of the mouse pointer possible on EGA and VGA hardware. The virtual video device driver's pointer drawing services are intended to replace this interface, but existing graphical applications still use it (generally when mouse support is also present), so the interface must be present or these applications will not function correctly.

The INT 2Fh services notify applications when they are about to be switched to full-screen or background mode. Applications can use this notification to stop accessing video memory, if they are using a video memory not supported for background operation. This will prevent them from freezing, and also redraw their screen in the event the virtual video device driver fails to fully restore it.

Summary of the 8514/A and XGA Virtual Device Drivers

DOS applications currently written to the 8514/A Adapter Interface (AI), the XGA AI, or directly to the 8514/A and XGA display adapters are able to run in a full-screen DOS session. This is due to the ability of each adapter's virtual device driver to:

• Grant I/O privilege
• Save or restore the video state
• Provide video bitmap images to the shield layer when the DOS session is being windowed

A DOS application is allowed to run only in a full-screen foreground DOS session, and is immediately frozen if it attempts to access the hardware when switched to the background.

The virtual 8514/A device driver statements, which are required in the CONFIG.SYS file, are added during installation when the presence of an 8514/A display adapter is noted:

DEVICE=C:\OS2\MDOS\VVGA.SYS
DEVICE=C:\OS2\MDOS\V8514A.SYS

The virtual XGA device driver statements, which are required in the CONFIG. SYS file, are added during installation when the presence of an XGA display adapter is noted:

DEVICE=C:\OS2\MDOS\VVGA.SYS
DEVICE=C:\OS2\MDOS\VXGA.SYS

The following items should be set in DOS to enable a DOS session:

• Enable I/O trapping to permit the virtual video device driver to save and restore the hardware instance used by a DOS application when the application switches away from the foreground DOS session. The virtual video device driver allocates a buffer to save the video image. The maximum size of this buffer is 1MB and is obtained each time a full-screen DOS session is created.

Enabling I/O trapping is the default. Although multiple instances of XGA can be present on a system, the virtual XGA device driver saves or restores only the state of the first instance used by a DOS application. It is the application's responsibility to save or restore the other XGA instances.

• Register for screen switch notification. This implies that a DOS application has hooked INT 2Fh so as to be notified when it is to be switched to full-screen foreground or background. This notification informs the application that it must restore the screen when switched to full- screen foreground, and must stop accessing video memory (to avoid freezing) when switched to background.

An application that uses more than one instance of XGA must specify this option to save and restore the states of the other XGA adapters. The default is no VIDEO_SWITCH_NOTIFICATION.

Any DOS session that is not saved or restored by the virtual video device driver cannot be displayed in a window. DOS 8514/A and XGA applications are not interactive in a window; they can only be viewed.