Jump to content

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

From EDM2
← Older editNewer edit →
No edit summary
No edit summary
Line 23: Line 23:
[[#Physical Video Device Drivers]] This chapter describes the Video Device handlers, and lists functions used to read and write to the EGA registers. The DPRINTF Print Formatting Package information has been moved from the end of [[00039.htm|SVGA Base Video Subsystem]] to the end of this chapter.
[[#Physical Video Device Drivers]] This chapter describes the Video Device handlers, and lists functions used to read and write to the EGA registers. The DPRINTF Print Formatting Package information has been moved from the end of [[00039.htm|SVGA Base Video Subsystem]] to the end of this chapter.


[[#Virtual Video Device Drivers]] This chapter describes the design, implementation, and interfaces of virtual video device drivers, including the virtualization and windowing of DOS sessions on an OS/2 platform. A virtual video device driver is required when it is necessary for multiple DOS sessions to share one or more video devices. "Super VGA Virtual Video Device Driver Support" describes how to add support for an Super VGA capable chip set.
[[Virtual Video Device Drivers]] This chapter describes the design, implementation, and interfaces of virtual video device drivers, including the virtualization and windowing of DOS sessions on an OS/2 platform. A virtual video device driver is required when it is necessary for multiple DOS sessions to share one or more video devices. "Super VGA Virtual Video Device Driver Support" describes how to add support for an Super VGA capable chip set.


[[Seamless Windows Support]] This chapter provides information on how to execute Windows applications in one or more windows on the OS/2 desktop, and includes a Checklist for Palette Management Support in seamless display drivers. It also includes an overview of the Distributed Console Access Facility (DCAF), which provides remote console functions.
[[Seamless Windows Support]] This chapter provides information on how to execute Windows applications in one or more windows on the OS/2 desktop, and includes a Checklist for Palette Management Support in seamless display drivers. It also includes an overview of the Distributed Console Access Facility (DCAF), which provides remote console functions.
Line 6,048: Line 6,048:


\\ for \.
\\ for \.
=== Virtual Video Device Drivers ===
This chapter describes the design, implementation, and interfaces of a virtual video device driver, including the virtualization and windowing of DOS session on an OS/2 platform. It is assumed that you are familiar with the terms and concepts in the ''OS/2 Virtual Device Driver Reference''.
=== Overview ===
A virtual video device driver is used by the IBM Operating System/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 driverVCGA <br />Virtual EGA device driverVEGA <br />Virtual MONO device driverVMONO <br />Virtual VGA device driverVVGA <br />Virtual XGA device driverVXGA <br />Virtual SVGA device driverSVGA <br />Virtual 8514/A device driverV8514A
The video devices for which OS/2 provides virtual video device drivers include:
�Western Digital <br />�ATI <br />�Cirrus Logic <br />�Headland <br />�IBM Super VGA <br />�Trident <br />�TSENG <br />�Video 7**
'''Note:'''Specific Super VGA chip revision/model support can be found in VVDP. H.
=== Installable Virtual Video Device Driver Architecture ===
The architecture of a virtual video device driver conforms to the architecture defined for all virtual device drivers. However, some parts of the multiple DOS session's architecture have been designed primarily for virtual video device drivers, as follows:
�Foreground and background ''notification hooks''<br />�''Freeze''and ''thaw''services <br />�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); <br />�Virtual device drivers run at Ring 0 (highest privilege level); <br />�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 &quot;DEVICE=&quot; 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, support for 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 2''xx''port configuration, instead of the standard 3''xx''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 driver 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, 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 <br />-Set Access <br />-Set Focus <br />-Set Lock <br />-Query Mode Info <br />-Query Cursor Info <br />-Query Palette Info <br />-Copy LVB Content <br />-Copy Bit Map Content <br />-Wait for Video Event <br />-Control Event <br />�PM Display Device Driver <br />-Set Display Requirements <br />-Request off-screen VRAM <br />-Free off-screen VRAM <br />-Request VGA Controller <br />-Free VGA Controller <br />-Query VRAM Status
'''Note:'''See [[00398.htm|DOS Session Window Manager Services]]and [[00399.htm|Presentation Manager Display Driver Services]]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 <br />�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.
'''Note:'''
256-color modes will not be rendered accurately in a window even when the PM display driver supports 256 colors, because the DOS Session Window Manager does not provide Palette Manager support.
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. An example of this category is an adapter that requires multiple OUTs to a specific port before permitting the extended clock bits to be programmed.
Of the 8514/A graphics modes, only the 1024 x 768 256-color mode has been tested for accurate rendering in a window.
=== Virtualization Support Strategy ===
The virtualization support required for these devices varies, depending on the complexity, capability, and operational characteristics of the device. However, the approach to develop a high-level design should always be the same, regardless of the device involved. To illustrate, we will use the 8514/A and XGA devices as examples in the following sections.
=== Virtualization Support Requirements for 8514/A and XGA ===
The following sections describe the device description, functional requirements, and design tradeoffs for the 8514/A and XGA devices.
=== 8514/A Device Description ===
�The majority of the I/O ports are either read-only or write-only.
�There is a multi-function register that requires special considerations because the functionality characteristics are totally different from the other I/O registers.
�The 8514/A internal RGB index of the DAC is not readable.
�The VRAM cannot be accessed directly. (It is not a ''dumb frame''device.)
�Special consideration must be given to handling the ''passthrough-mode''capability of this device.
�Video memory size is assumed to be 1MB for the following reasons:
-The OS/2 PM Display Device Driver cannot function without it.
-It is not possible to configure a system with multiple 8514/A adapters.
�The 8514/A is not a Direct Memory Access (DMA) device.
=== XGA Device Description ===
�The I/O registers mostly are readable and writable, plus a few reserved registers.
�It is a BusMaster device, capable of DMA operations.
�DMA (co-processor) operations are initiated through memory-mapped I/O registers located in the adapter ROM area above C0000.
�The device can operate in a virtual memory (that is, a 386 environment).
�Video memory can be accessed by the DOS application through either an A0000 or B0000 aperture, without use of a co-processor.
�Multiple XGA configuration is possible.
�With built-in VGA hardware, the two operating environments are mutually exclusive even though they share the same DAC and VRAM.
�Planar VGA is disabled on a single display system (the display is attached to the XGA adapter).
�132-column text mode is supported.
�All graphics modes are ''packed-pel''.
=== 8514/A Functional Requirements ===
�Determine the existence of the device and the type of display attached.
�Trap all the write-only I/O ports, even if the DOS session executes in the foreground (full-screen); otherwise, the device cannot be saved or restored .
�No page-fault hook is required because the 8514/A is not a memory-mapped device.
�Establish a mechanism with the virtual VGA device driver to manage ownership of the shared device.
�Enable the DOS application that is INT 2Fh-aware to save and restore its own video state.
�Trap all I/O, whether or not I/O can be virtualized while the DOS session is executing in the background.
=== XGA Functional Requirements ===
�For every XGA configuration in the system, determine the physical location and size of VRAM, the type of display attached, and the location of the memory-mapped I/O registers.
�A page fault hook is required to detect the memory-mapped I/O registers used, because the affected system memory must be locked down before any DMA operations can occur.
�Notification of EMS, XMS, and DPMI memory allocations is required, so that the memory object can be locked down for DMA operations.
�Page-fault handling of A0000 and B0000 is not required because an I/O trap handler can be installed to monitor usage of the Aperture Control register.
Upon detection, the I/O handler can choose one of the following:
-When the DOS session is foreground, map the linear address to the physical location of the VRAM (that is, A000 or B000), giving a length of 64KB because that is the maximum size of the aperture.
This approach eliminates duplication of the page fault management logic of the virtual VGA device driver.
-When the DOS session is background, map the linear address to the appropriate location within the shadow buffer that was saved during the recent session switch. The displacement is 64KB-aligned, and it is computed using the content of the Aperture Index Register.
�The XGA-specific registers must be saved/restored to provide 132-column text mode support. The virtual VGA device driver is expected to handle the others. Enable the DOS application that is INT 2Fh-aware to save and restore its own video state.
=== 8514/A Design Tradeoffs ===
�When save/restore of the complete video state is required, you have two choices for saving the 1MB VRAM:
-Allocate the 1MB shadow buffer during creation of the virtual DOS session, thus eliminating a potential problem with resource allocation during session switching.
-Delay allocation of the shadow buffer at the time of session switch, but risk the possibility of session termination because the required memory is not available.
�Software emulation of any hardware-assist operations to the video memory probably is too complex to achieve successfully. The only alternative available is to freeze the DOS application whenever these I/O ports are accessed in the background. A frozen image can be presented in a window if the complete video state and VRAM were saved for the DOS window session.
=== XGA Design Tradeoffs ===
�It is impossible to anticipate what the DOS application might do when the memory-mapped I/O register is touched; assume the worst. To preserve the integrity of the system by not permitting the DOS application to interfere with system operations, lock down the affected memory regions.
Although there are numerous ways to do this, there are penalties involved with each one. Some of the methods (and their possible drawbacks) are described following this table.
�In a multiple XGA configuration system, saving and restoring every XGA probably is desirable. Instead, you can let the DOS application take care of it, or you can selectively save/restore only one XGA device.
�Software emulating the XGA hardware operations is not desirable.
�The only apparent alternative is to freeze the DOS application when the I/ O ports are accessed in the background. A frozen image can be presented in a window if the complete video state and VRAM are saved for the DOS window session.
=== Methods of Locking Down Memory Regions ===
�Assume each full-screen DOS session is started in physical memory below 1MB by OS/2. This has the advantage of not having to specifically lock down the 640KB DOS region, and the memory, by default, is continuous. This is ideal for any XGA-specific DOS applications that do not require any extended memory, while achieving performance equal to DOS. The drawback here is that this type of session is not supported by OS/2.
�Assume each full-screen DOS session is started anywhere in system memory with the 640KB DOS region locked down discontiguously by OS/2. Here, the virtual memory mode of the XGA must be used. EMS, XMS, and DPMI memory allocation can be locked dynamically through the extended memory allocation notification interface. Putting the XGA in VM mode would result in a 10 to 15 per cent degradation in performance, depending on the type of operations involved. OS/2 does not support this type of session start.
�Assume that XGA will be operating in VM mode. The 640KB DOS region gets locked down discontiguously only when access to the memory-mapped I/O register is detected. EMS, XMS, and DPMI memory allocation is handled as in the second case above.
�While operating in VM mode, the XGA has the ability to generate an interrupt to the system processor whenever the memory object being referenced is not present. Assuming that the 640KB region can be selectively forced into a not-present state, a physical device driver can be written to avoid such interrupt and post the event. Although the event is posted at interrupt time, the actual lockdown of memory cannot take place until the virtual device driver gets a chance to execute at task time , when it can resume the XGA operation after successfully locking down the memory object.
'''Note:'''The second and third assumptions above require the generation of a Page Directory and Page Table in order for the XGA to access the DOS session's linear address space and VRAM.
=== Virtual and Non-Virtual (Full-Screen) Operations ===
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's system menu to convert the DOS session from windowed mode to full-screen mode and back again. Virtual video device drivers support full-screen by performing the following operations:
�Registering foreground and background VIDEO_SWITCH_NOTIFICATION hooks with the DOS Session Manager <br />�Allocating a Save and Restore video buffer <br />�Installing I/O hooks to shadow key video port accesses <br />�Mapping physical video memory into the appropriate video address space <br />�Coercing text-mode fonts to match the currently selected code page <br />�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 in the background), the virtual video device drivers do the following:
�Install I/O hooks to track and emulate all video port accesses. <br />�Map appropriate system memory to the active portions of the video address space. <br />�Report video events to the DOS Session Window Manager (assuming the Presentation Manager is active and the DOS session is an unminimized window ). Such reporting includes changes to: <br />-Mode <br />-Palette <br />-Cursor <br />-Video memory <br />-Input events <br />-Scroll or string events <br />-Paste continue or terminate (through the virtual keyboard device driver) <br />-Session title change <br />-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, as follows:
�Windowed or non-windowed <br />�Focused or non-focused <br />�Minimized or un-minimized <br />�Locked or unlocked
Any aspect of a DOS session's video state can be queried as follows:
�Mode <br />�Palette <br />�Cursor <br />�Video memory <br />�Wait for video events <br />�Cancel wait for video events
=== I/O Handler Installation ===
I/O port handlers are installed during the creation of a DOS session This is always required if the target device requires virtualization. The assembler-language hook interface is faster than its &quot;C&quot; language counterpart.
Whenever possible, avoid simulation by a lower-level I/O handler. For example, if the device is capable of word I/O, do not install just the byte I/O handlers, because your byte I/O handlers will be called twice for each word I/O issued by the DOS application.
I/O ports can be enabled or disabled dynamically on a per-DOS session basis except when the VDHIIH_ALWAYS_TRAP option is specified at port installation .
I/O trapping can be removed at any time, provided that it is called using the same port arguments passed to install the I/O ports.
Currently, I/O handlers may be preempted for the following reasons:
�The code is swappable.
�The data referenced by the handlers is swappable.
�The OS/2 kernel portions that route I/O traps, page faults, and so forth, are swappable as well.
There is a remote possibility that a DOS session screen-switch might occur while an I/O handler is blocked, meaning that there is a slight risk of a shadowed DOS session's I/O operation accessing the hardware when it is no longer owner of that hardware. At present, there is no satisfactory means of removing that possibility. Making all the necessary code and data resident-both in kernel and virtual device driver-is not acceptable, nor is the overhead of calling semaphore services in the I/O handlers.
=== 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 <br />�Hide Pointer <br />�Define Text Pointer <br />�Define Graphics Pointer <br />�Set Video Page <br />�Set Light-Pen Emulation
Also, whenever the DOS session changes video modes (including the initial mode change during DOS-session creation), the virtual video device driver notifies the virtual mouse device driver of the new mode, 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 possible drawing operations and simultaneous use of the mouse pointer 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). 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 prevents them from freezing and redraws their screen in the event the virtual video device driver fails to fully restore it.
<br /><br />
<pre class="western">/--- IMPLEMENTATION NOTE ----------------------------------\
|                                                          |
|  The EGA Register interface has not been integrated    |
|  into the virtual video device drivers. Until and      |
|  unless this is done, EGA.SYS must be supplied with    |
|  the system and loaded by EGA/VGA users on an          |
|  as-needed basis.                                      |
|                                                          |
\----------------------------------------------------------/</pre>
=== Virtual Video Device Driver Services ===
Multiple virtual device drivers can be installed for the same adapter. Usually, the second virtual device driver detects that the adapter's address space is already reserved, and so, fails to install. However, virtual video device drivers can be written to take control of a device from an owning virtual device driver when a certain event occurs and then to relinquish control later. This is accomplished by supporting the Release Device and Accept Device inter-virtual device driver requests in both virtual video device drivers. An owning virtual video device driver must unmap all video pages and uninstall all page-fault and I/O hooks upon receipt of a Release request, and later must reinstall all hooks upon receipt of an Accept request.
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_DEVACCEPT (5)            */
      PVOID pReqIn,    /* Undefined.                        */
      PVOID pReqOut    /* Undefined.                        */
    );
    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_DEVRELEASE (6)          */
      PVOID pReqIn,    /* Undefined.                        */
      PVOID pReqOut    /* Undefined.                        */
    );</pre>
This support is provided for multiple virtual video device drivers installed for the same device but virtualizing different aspects of the hardware (for example, VGA and Super VGA virtual video device drivers for a single Super VGA adapter). A virtual video device driver that is not currently the owner must silently pass on any DosRequestVDD and VDHRequestVDD requests that it receives to the next virtual video device driver in the chain, using the VDDREQ_PASS return code.
In cases where multiple video adapters use the same physical monitor (such as VGA with 8514/A), there is no need to issue the device requests described previously because the devices are separate. Coordination of which virtual video device driver is currently the display owner must be accomplished by way of a similar pair of inter-virtual device driver requests: Release Display and Accept Display. Virtual video device drivers generally need not act except to update their own display ownership settings. Only the virtual video device driver that is currently the display owner for a given DOS session should respond to requests from the DOS Session Window Manager for that DOS session. The same is true of virtual mouse device driver pointer requests. For example, on a VGA and 8514/A single display system, only the virtual video device driver with display ownership should respond to certain system requests (that is, QUERYMODE, QUERYCURSOR, QUERYPALETTE, COPYLVB, and COPYBITMAP).
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_DSPACCEPT (7)            */
      PVOID pReqIn,    /* Undefined.                        */
      PVOID pReqOut    /* Undefined.                        */
    );
    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_RELEASE (8)              */
      PVOID pReqIn,    /* Undefined.                        */
      PVOID pReqOut    /* Undefined.                        */
    );</pre>
For the VGA and 8514/A combination, the VGA virtual video device driver still manages all video event communication with the DOS Session Window Manager. This eliminates major duplicate functionality with the 8514/A. However, because the 8514/A virtual video device driver still must be able to post its own video events, a post event inter-virtual device driver request is supported by the VGA virtual video device driver.
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDM hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_POSTEVENT (9)            */
      PVVPOST pvvp,    /* Pointer to a VVPOST structure      */
      PVOID pReqOut    /* Undefined.                        */
    );</pre>
where VVPOST is a structure containing:
<pre class="western">    typedef struct vvp_ { /* vvp (input for POSTEVENT request*/
      LONG  iEvent;    /* See the VVDEVENT_* constants below */
      PVOID pEvent;    /* Event data (varies by event type  */
      ULONG  flEvent;  /* See POSTEVENT_* constants below    */
    }VVPOST;
    #define VVDEVENT_NONE        0  / *  No  change                * /
      # define  VVDEVENT _ MODE          1  / *  Change  in  DOS          * /
                                        / *  session ' s  mode          * /
      # define  VVDEVENT _ PALETTE        2  / *  Change  in  DOS          * /
                                        / *  session ' s  palette      * /
      # define  VVDEVENT _ LVB            3  / *  Change  in  DOS          * /
                                        / *  session ' s  LVB          * /
      # define  VVDEVENT _ SCROLL        4  / *  Scroll  of  DOS          * /
                                        / *  session ' s  LVB          * /
      # define  VVDEVENT _ STRING        5  / *  String  output          * /
      # define  VVDEVENT _ CURSOR        6  / *  Cursor  position / type    * /
                                        / *  change                  * /
      # define  VVDEVENT _ INPUT          7  / *  DOS  session  is  check -  * /
                                        / *  ing  for  input  data      * /
      # define  VVDEVENT _ ENDPASTE      8  / *  DOS  session  has        * /
                                        / *    cancelled  pasting      * /
      # define  VVDEVENT _ PASTE          9  / *  DOS  session  is  ready    * /
                                        / *  for  additional  pasting * /
      # define  VVDEVENT _ SWITCHERROR  10  / *  DOS  session  cannot  be  * /
                                        / *    switched  foreground    * /
      # define  VVDEVENT _ TITLECHANGE  11  / *  DOS  session  title  has  * /
                                            changed                  * /
      # define  VVDEVENT _ DDE          12  / *  Set / Clear  DDE  flag      * /
      # define  POSTEVENT _ ADD      0x0001  / *  Add  given  event .        * /
      # define  POSTEVENT _ FLUSH    0x0002  / *  Flush  given  or          * /
                                            existing  event .        * /
      # define  POSTEVENT _ DELETE  0x0004  / *  Delete  existing  event . * / </pre>
The XGA device has VGA device capability built into the hardware, but it is physically impossible to activate the functionality of both devices at the same time without another VGA-capable device installed. The extra VGA device can come in a form of a planar VGA with a display monitor attached, a VGA adapter, or another XGA device. In the event that the XGA device being targeted for save/restore by the XGA virtual device driver is also the startup device (that is, it comes up in VGA mode on system startup), a fast path can be used to temporarily stop the VGA virtual device driver from doing the save/restore of the same device without going through the preferred way of ''Release''and ''Accept''device. In this case, the Save Restore request is supported by the VGA virtual video device driver.
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_SAVERESTORE (10)        */
      PVOID (0 or 1),  /* 1=yes, 0=no                        */
      PVOID pReqOut    /* Undefined.                        */
    );</pre>
The Repaint request is used by other virtual video device drivers (8514/A and XGA) to indicate whether the PM Desktop's screen image has been damaged by the full-screen DOS session. The virtual video device driver accepting this request must notify the PM display device driver, using QUERYVRAMSTATUS, that repaint of the Desktop is required when the PM becomes foreground.
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_REPAINT (11)            */
      PVOID(TRUE),    /* 1 = REPAINT required              */
      PVOID pReqOut    /* Undefined.                        */
    );</pre>
The Request Controller request is issued by the virtual Window device driver (VWIN.SYS) on behalf of the WIN-OS/2 display device driver to force the virtual video device driver to immediately release the VGA controller currently owned by a background or windowed DOS session.
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDD hvddVideo  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_REQCTRL (12)            */
      PVOID PReqIn,    /* Undefined.                        */
      PVOID PReqOut    /* Undefined.                        */
    );</pre>
The Free Controller request is issued by the virtual Window device driver ( VWIN.SYS) on behalf of the WIN-OS/2 display device driver to notify the virtual video device driver that the VGA controller is now available. This request is issued only when the virtual video device driver requests notification on completion of the current PM operation.
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_FREECTRL  ( 13 )              * /
        PVOID  PReqIn ,      / *  Undefined .                            * /
        PVOID  pReqOut      / *  Undefined .                            * /
      ) ; </pre>
The Set PM Window request is issued by the virtual Window device driver ( VWIN.SYS) to permit the specified windowed DOS session access to the video device. It is up to the virtual video device driver servicing this request to remove all I/O hooks, map VRAM to physical A0000H as needed, and remove all pending window events for the target DOS session.
<br /><br />
<pre class="western">    VDHRequestVDD(
      HVDD hvddVideo,  /* Virtual video device driver handle */
      HVDM hvdm,      /* Screen group ID of the DOS session */
      INT  iFunc,      /* VVDDEVREQ_PM_WINDOW (14)          */
      PVOID(TRUE),    /* 1 = Enable WIN-OS/2                */
      PVOID pReqOut    /* Undefined.                        */
    );</pre>
=== 8514/A and XGA Virtual Device Drivers ===
DOS applications currently written to the 8514/A adapter interface, XGA adapter interface, or directly to the 8514/A and XGA display adapters can 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 <br />�Save or restore the video state <br />�Provide video bit-map images to the shield layer when the DOS session is being windowed.
A DOS application is permitted to run only in a full-screen foreground DOS session; it is frozen immediately 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 detected:
<br /><br />
<pre class="western">        DEVICE=C:\OS2\MDOS\VVGA.SYS
        DEVICE=C:\OS2\MDOS\V8514A.SYS</pre>
The virtual XGA device driver statements, which are required in the CONFIG. SYS file, are added during installation when the presence of an XGA adapter is detected:
<br /><br />
<pre class="western">        DEVICE=C:\OS2\MDOS\VVGA.SYS
        DEVICE=C:\OS2\MDOS\VXGA.SYS</pre>
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 be viewed only.
=== 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. The virtual video device driver provides the following ''VDHRequestVDD''services for the virtual keyboard device driver:
<br /><br />
<pre class="western">    VDHRequestVDD
    (
        HVDD hvddVideo,
        HVDM hvdm,
        INT  iFunc,    /* Virtual video device              */
                        /* driverEVREQ_POSTPEEK (1)          */
        BOOL fAvail,    /* TRUE if ROM BIOS buffer is not    */
                        /* empty.                            */
        PVOID pReqOut  /* Undefined.                        */
    );                /* Returns TRUE.                      */
    VDHRequestVDD
    (
        HVDD hvddVideo,
        HVDM hvdm,
        INT  iFunc,    /* Virtual video device              */
                        /* driverEVREQ_POSTREAD (2)          */
        BOOL fAvail,    /* TRUE if ROM BIOS buffer is not    */
                        /* empty.                            */
        PVOID pReqOut  /* Undefined.                        */
    );                /* Returns TRUE.                      */
    VDHRequestVDD
    (
        HVDD hvddVideo,
        HVDM hvdm,
        INT  iFunc,    /* Virtual video device              */
                        /* driverEVREQ_POSTPASTE (3)          */
        BOOL fContinue, /* TRUE to continue pasting,          */
                        /* FALSE to end.                      */
        PVOID pReqOut  /* Undefined.                        */
    );                /* Returns TRUE.                      */</pre>
The PEEK and READ notifications occur prior to the actual operation; ''fAvail''is TRUE if the ROM BIOS input buffer contains data, and FALSE if empty. In addition to generating VVDEVENT_INPUT events for 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 changes in video context.
For the PASTE notification, ''fContinue''is TRUE if pasting can continue (that is, buffer space is now available), and FALSE if pasting should be terminated (that is, the user pressed ESC). In the first case, the virtual video device driver posts VVDEVENT_PASTE to the DOS Session Window Manager, and in the second case, VVDEVENT_ENDPASTE.
<br /><br />
<pre class="western">/--- DESIGN NOTE ------------------------------------------\
|                                                          |
|  In the current implementation, the fAvail parameters  |
|  are ignored by the virtual video device driver.  It    |
|  matters only whether a PEEK or READ is occurring.      |
|                                                          |
\----------------------------------------------------------/</pre>
=== 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:
<br /><br />
<pre class="western">    VDHRequestVDD
    (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT  iFunc,    /* Virtual video device              */
                        /* driverEVREQ_POSTMOUSE (4)          */
        PVOID pReqIn,  /* Undefined.                        */
        PVOID pReqOut  /* Undefined.                        */
    );                /* Returns TRUE.                      */</pre>
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 driver of the new mode and screen dimensions.
The POSTMOUSE notification is intended to be called whenever the mouse is about to record a button transition event (that is, button going down or button coming up). Its purpose is to notify the virtual video device driver that a video event is likely to occur.
The direct-call interfaces are exported by way of the following ''VDHRequestVDD''to the virtual mouse device driver during the creation of the first DOS session. (To avoid introducing a loading-order dependency, they are not exported during virtual device driver initialization.)
<br /><br />
<pre class="western">    VDHRequestVDD
    (
        HVDD  hvddMouse,
        HVDM  hvdm,
        INT  iFunc,    /* iFunc = VMDEVREQ_REGISTER (1)      */
        PVMREG pvmreg,  /* Pointer to VMREG structure        */
        PVMFUNC pvmfunc /* Pointer to VMFUNC structure        */
    );                /* Returns TRUE                      */</pre>
where VMREG is a structure containing all the direct-call addresses:
<br /><br />
<pre class="western">    typedef struct vmreg_s
    {
        ULONG    nb;              /* Size of structure, in  */
                                  /*  bytes (24)            */
        PFNSHOWPTR  pfnShowPtr;    /* Ptr to show pointer fn. */
        PFNHIDEPTR  pfnHidePtr;    /* Ptr to hide pointer fn. */
        PFNDEFTEXT  pfnDefTextPtr; /* Ptr to define text
                                  /*  pointer fn.            */
        PFNDEFGRAPH pfnDefGraphPtr;/* Ptr to define graphics
                                  /*  pointer fn.            */
        PFNSETPAGE  pfnSetPtrPage; /* Ptr to set pointer      */
                                  /*  page fn.              */
        PFNSETLPEN  pfnSetLPenEm;  /* Ptr to enable/disable  */
                                  /*  lpen fn.              */
    }  VMREG;</pre>
and where VMFUNC is a structure in which the virtual mouse device driver must return the address of its own exported function to return mouse position and button status:
<br /><br />
<pre class="western">    typedef struct vmfunc_s
    {
        ULONG      nb;              /* Size of structure,    */
                                    /* in bytes (8)          */
        PFNQUERYSTAT pfnQueryStatus; /* Ptr to query virtual  */
                                    /* status proc.          */
    }  VMFUNC;</pre>
The virtual video device driver also uses ''VDHRequestVDD''to notify the virtual mouse device driver of changes in video mode:
<br /><br />
<pre class="western">    VDHRequestVDD
    (
        HVDD  hvddMouse,
        HVDM  hvdm,
        INT  iFunc,              /* VMDEVREQ_SETSIZE (2)      */
        PVMSS pvmss,              /* Pointer to VMSS structure */
        PVOID pReqOut            /* Undefined                */
    );</pre>
where VMSS is a structure containing the following information:
<br /><br />
<pre class="western">    typedef struct vmss_s
    {
        ULONG nb;          /* Size of structure, in bytes (36)*/
        LONG  lMode;      /* Video mode (for example,        */
                          /* 00h-13h, or -1)                */
        ULONG ulWidth;    /* Width of screen, in pels        */
        ULONG ulHeight;    /* Height of screen, in pels      */
        ULONG ulCellWidth; /* Width of screen cells, in pels  */
        ULONG ulCellHeight;/* Height of screen cells, in pels */
        ULONG ulPtrWidth;  /* Width of pointer drawing size,  */
                          /* in pels                        */
        ULONG ulPtrHeight; /* Height of pointer drawing size, */
                          /* in pels                        */
        ULONG ulUnitWidth; /* Width of pointer drawing unit,  */
                          /* in pels                        */
    }  VMSS;</pre>
The direct-call interfaces supplied by virtual video device drivers are defined as follows:
<br /><br />
<pre class="western">    BOOL FNSHOWPTR VVShowPtr
    (
        HVDM hvdm,          /* DOS session handle,          */
                            /* or CURRENT_VDM                */
        ULONG xNew,          /* Horizontal pel (NOT cell)    */
                            /* coordinate                    */
        ULONG yNew          /* Vertical pel (NOT cell)      */
                            /* coordinate                    */
    );                      /* Returns TRUE unless ptr        * /
                                / *  drawing  disabled                * /
      BOOL  FNHIDEPTR  VVHidePtr
      (
        HVDM  hvdm              / *  DOS  session  handle ,  or          * /
                                / *  CURRENT _ VDM                      * /
      ) ;                          / *  Returns  TRUE  unless  ptr        * /
                                / *  drawing  disabled * /              * /
      BOOL  FNDEFTEXT  VVDefTextPtr
      (
        HVDM  hvdm ,              / *  DOS  session  handle ,  or          * /
                                / *  CURRENT _ VDM                      * /
        ULONG  ulANDMask ,      / *  Screen  mask                      * /
        ULONG  ulXORMask ,      / *  Pointer  mask                    * /
        BOOL  fHW                / *  TRUE  to  use  hardware  cursor    * /
      ) ;                          / *  Returns  TRUE                    * /
      BOOL  FNDEFGRAPH  VVDefGraphPtr
      (
        HVDM  hvdm ,              / *  DOS  session  handle ,  or          * /
                                / *  CURRENT _ VDM                      * /
        USHORT  ausMasks [ ] ,    / *  Screen  mask ,  followed  by        * /
                                / *  pointer  mask                    * /
        ULONG  xHot ,            / *  Relative  horizontal  hot - spot
                                / *  coordinate                      * /
        ULONG  yHot              / *  Relative  vertical  hot - spot      * /
                                / *  coordinate                      * /
      ) ;                          / *  Returns  TRUE                    * /
      BOOL  FNSETPAGE  VVSetPtrPage
      (
        HVDM  hvdm ,              / *  DOS  session  handle ,  or          * /
                                / *  CURRENT _ VDM                      * /
        ULONG  ulPage          / *  Video  page  number                * /
      ) ;                          / *  Returns  TRUE                    * /
      BOOL  FNSETLPEN  VVSetLPenEm
      (
        HVDM  hvdm ,              / *  DOS  session  handle ,  or          * /
                                / *  CURRENT _ VDM                      * /
        BOOL  fEnable          / *  TRUE  to  enable  emulation        * /
      ) ;                          / *  Returns  TRUE                    * / </pre>
For reference, the function supplied by a virtual mouse device driver to a virtual video device driver is defined as follows:
<br /><br />
<pre class="western">    BOOL FNQUERYSTAT VMQueryStatus
    (
        HVDM hvdm,      /* DOS session handle, or            */
                        /* CURRENT_VDM                      */
        PVMSTAT pvmstat  /* Pointer to VMSTAT info structure  */
    );                  /* Returns TRUE                      */</pre>
where VMSTAT is a structure containing:
<br /><br />
<pre class="western">    typedef struct vmstat_s
    {
        BOOL  fPtrHidden;    /* Visual pointer status        */
        ULONG x;            /* Current virtual x position    */
        ULONG y;            /* Current virtual y position    */
        ULONG flButtons;    /* Current button status        */
    }  VMSTAT;
    /*
    ** Button status bit definitions
    */
    #define BUTBIT_LEFT    0x0001
    #define BUTBIT_RIGHT    0x0002
    #define BUTBIT_CENTER  0x0004</pre>
<br /><br />
<pre class="western">/--- DESIGN NOTE ------------------------------------------\
|                                                          |
|  The POSTMOUSE notification currently is not supplied by |
|  the virtual mouse device driver, nor is it currently    |
|  monitored by the virtual video device driver.          |
|                                                          |
\----------------------------------------------------------/</pre>
=== Virtual Video Device Driver Services for OS/2 Applications (DosRequestVDD) ===
The following services are intended to provide a method for any OS/2 Ring 3 application to manage or obtain the video state of a DOS session.
=== DOS Session Window Manager Services ===
For the DOS Session Window Manager, the virtual video device driver provides the following ''DOSRequestVDD''services:
�The Set Access request informs the virtual video device driver that the caller is interested in receiving video events for the requested DOS session, preventing future callers from obtaining the same privilege. It also declares the DOS session to be ''windowed''. Under the cover, the virtual video device driver can initiate a global timer hook for the purpose of video event checking upon creation of the first DOS session. In addition, the same interface can be used by the OS/2 Session Window Manager to help the virtual video device driver track which sessions are being windowed by PM so that events are not reported when PM is not foreground. When PM returns to foreground, it is up to the virtual video device driver to post ''refreshed''events so that all DOS-session windows are repainted.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETACCESS (1)            */
        ULONG cbInput,  /* See the ACCESS_ constants          */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput  /* Undefined                          */
    );
    #define ACCESS_RELEASE  0 /* Release access            */
    #define ACCESS_REQUEST  1 /* Request access            */
    #define ACCESS_PMREQUEST 2 /* Request access made by PM  */
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_ACCESS_DENIED (Access already has been taken.)
        ERROR_INVALID_FUNCTION (iFunc invalid, or access
        already set.)</pre>
�The Set Focus request records the current DOS session as having or not having focus. Unlike the foreground/background notification hooks provided by the DOS Session Manager (which are supported only by the Session Manager ), this function is called by the DOS Session Window Manager as the user gives or takes focus to or from DOS sessions.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS Session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETFOCUS (2)            */
        ULONG cbInput,  /* TRUE if gaining focus,            */
                        /*  FALSE if losing                  */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput  /* Undefined                          */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid)</pre>
�The Set Lock request suspends and resumes the DOS session's video state. The virtual video device driver guarantees that the video state will not change following a LOCK until a corresponding UNLOCK is issued. Moreover, if a DOS session is locked multiple times, it must be unlocked an equivalent number of times before it is truly unlocked.
Implementation of this service currently is based on the ''VDHFreeze''and ''VDHThaw''services, instead of a ''lazy''lock, to avoid additional overhead in the interrupt and I/O handlers, and to make the lock implementation simple for both background and foreground DOS sessions. Consequently, callers should use the lock service sparingly and for as brief a time as possible to avoid communication problems due to line drop.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETLOCK (3)              */
        ULONG cbInput,  /* TRUE if locking,                  */
                        /*  FALSE if unlocking              */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput  /* Undefined                          */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid)
        ERROR_BUFFER_OVERFLOW (Too  many  freezes
          outstanding . ) </pre>
�The Query Mode request returns current mode information for the DOS session, such as screen dimensions, whether or not the DOS session is suspended, code-page ID, and so forth.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYMODE (4)            */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Sizeof(VVMODE)                    */
        PVOID pOutput  /* Pointer to a VVMODE structure      */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                          yet.)
        ERROR_ACCESS_DENIED        (User buffer could not
                                          be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                          outstanding.)</pre>
where VVMODE is a structure containing:
<br /><br />
<pre class="western">    /*
    ** Output for MODE event
    */
    typedef struct vvm_s
    {
        ULONG ulAdapter;    /* See the ADAPTER_* constants.  */
        ULONG ulFormat;    /* See the FORMAT_* constants.    */
        ULONG ulDDFormat;  /* See the DDFORMAT_* constants.  */
        ULONG flMode;      /* Mode descriptors (See MODE_*  */
                            /*  constants.)                  */
        ULONG nRows;        /* Height of screen in rows      */
                            /* (or y pels)                    */
        ULONG nCols;        /* Width of screen in columns    */
                            /* (or x pels)                    */
        ULONG nPlanes;      /* Number of planes (Must be 1    */
                            /*  for OS/2 2.0.)                */
        ULONG nBitCount;    /* If TEXT, zero;  if BITMAP,    */
                            /*  bits per pel).                */
        ULONG ulCellWidth;  /* Width of cells (normally 8;    */
                            /*  1 for BITMAPs)                */
        ULONG ulCellHeight; /* Height of cells (1 for        */
                            /*  BITMAPs)                      */
        ULONG fSuspended;  /* See the SUSPEND_* constants.  */
        ULONG cpID;        /* Current code-page ID          */
        ULONG FormatID;    /* Current format ID              */
    }  VVMODE;
    #define ADAPTER_MONO  0  /* Adapters supported          */
    #define ADAPTER_CGA  1  /* (Same as VioGetConfig      */
                              /*  constants)                */
    #define ADAPTER_EGA  2
    #define ADAPTER_VGA  3
    #define ADAPTER_8514A 7
    #define FORMAT_CGA    2  /* LVB formats supported      */
    #define FORMAT_4BYTE  4
    #define FORMAT_BITMAP 0
    #define DDFORMAT_4PLANE 1 /* Display driver formats      */
                              /* supported                  */
    #define MODE_MONO        0x0001 /* Monochrome mode in    */
                                        effect                */
    #define MODE_UNDERLINE  0x0002 /* Underlining in effect */
    #define MODE_SUP_XSCALE2 0x1000 /* X scaling supported  */
                                    /* by factor of 2        */
    #define MODE_SUP_YSCALE2 0x2000 /* Y scaling supported  */
                                    /* by factor of 2        */
    #define MODE_SUP_PARTIALSCAN 0x4000 /* Partial scan line */
                                  /* copy requests supported */
    #define SUSPEND_NONE            0 /* DOS session running*/
                                          normally          */
    #define SUSPEND_OUT_OF_MEMORY    1 /* DOS session sus-  */
                                          pended due to low  */
                                        /* memory            */
    #define SUSPEND_UNSUPPORTED_MODE 2 /* DOS session sus-  */
                                          pended due to      */
                                        /* unsupported mode  */</pre>
�The Query Cursor request returns current cursor position and shape information for the DOS session:
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYCURSOR (5)          */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Sizeof(VVCURSOR)                  */
        PVOID pOutput  /* Pointer to a VVCURSOR structure    */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                    yet.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)</pre>
where VVCURSOR is a structure containing:
<br /><br />
<pre class="western">    /*
    ** Output for CURSOR event
    */
    typedef struct vvc_s
    {
        ULONG row;          /* Row (Y position) of DOS        */
                            /* session's cursor              */
        ULONG col;          /* Column (X position) of DOS    */
                            /* session's cursor              */
        ULONG ulScanStart;  /* Starting scan line for DOS    */
                            /* session's cursor              */
        ULONG ulScanEnd;    /* Ending scan line for DOS      */
                            /* session's cursor              */
        ULONG fVisible;    /* TRUE if DOS session cursor    */
                            /* visible,                      */
                            /* FALSE  if  not                      * /
      }  VVCURSOR ; </pre>
�The Query Palette request returns the RGB array for the DOS session. The RGB array contains 16 RGB entries for text modes and (2(n) bits per pel) entries for graphics modes:
<br /><br />
<pre class="western">    DosRequestVDD(
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYPALETTE (6)        */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Size of RGB array, in bytes        */
        PVOID pOutput  /* Pointer to RGB array              */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                    yet.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)</pre>
where the RGB array contains 16 RGB entries for text modes (FORMAT_CGA) and (2(n)BitCount) entries for graphics modes. RGB entries are packed on byte boundaries and have the following structure:
<br /><br />
<pre class="western">    typedef struct rgb_s
    {
        BYTE bBlue;
        BYTE bGreen;
        BYTE bRed;
    }  RGB;</pre>
�The Copy LVB request copies a rectangular portion of the DOS session's logical video buffer (that is, text-based LVB) to the specified output LVB. Using this call, the DOS Session Window Manager can keep a private copy of the LVB in sync with the virtual video device driver's LVB for a given DOS session:
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo /* virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_COPYLVB (7)              */
        ULONG cbInput,  /*  Sizeof(RECTL)                    */
        PVOID pInput,  /* Pointer to RECTL structure        */
        ULONG cbOutput, /* Size of output LVB                */
        PVOID pOutput  /* Pointer to output LVB              */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (DOS session has no video
                                    state yet.)
        ERROR_INVALID_DATA        (DOS session has changed
                                    video modes.)
        ERROR_NOT_LOCKED          (Caller must lock DOS
                                    session)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)</pre>
where RECTL is a structure defining the region to be copied:
<br /><br />
<pre class="western">    typedef struct rcl_s
    {
        LONG xLeft;    /* Left column (leftmost is 0)        */
        LONG yBottom;  /* Bottom row                        */
        LONG xRight;    /* Right column                      */
        LONG yTop;      /* Top row (topmost is 0)            */
    }  RECTL;</pre>
and where ''pOutput''points to an output LVB. Using this call, the DOS Session Window Manager keeps a private LVB in sync with the virtual video device driver's LVB for a given DOS session. Arbitrary rectangles of the source LVB are copied to the same relative position in the target LVB.
ERROR_INVALID_DATA is returned to callers that have exclusive event access when a DOS session is in the process of changing video modes. It alleviates the need for a caller to constantly lock and unlock the DOS session to ensure a reliable transfer. Callers without exclusive event access have no alternative but to lock and unlock for each copy; otherwise, they run the risk of obtaining incorrect or obsolete information. The virtual video device driver enforces this, and will return ERROR_NOT_LOCKED if called without exclusive access and the DOS session unlocked.
�The Copy Bit Map request copies a rectangular portion of the DOS session's graphics video buffer to the specified output buffer. The output buffer is interpreted either as a ''device-dependent bit map''(DDB) into which the requested region is copied at the same relative position, or as a ''device-independent bit map''(DIB) intermediate buffer into which the region always is copied, starting at offset 0.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_COPYBITMAP (8)          */
        ULONG cbInput,  /* Sizeof(VVRECT)                    */
        PVOID pInput,  /* Pointer to VVRECT structure        */
        ULONG cbOutput, /* Size of output graphics buffer    */
        PVOID pOutput  /* Pointer to output graphics buffer  */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid)
        ERROR_INVALID_PARAMETER    (Pointers are invalid)
        ERROR_NOT_READY            (DOS session has no video
                                    state yet)
        ERROR_INVALID_DATA        (DOS session has changed
                                    video modes)
        ERROR_NOT_LOCKED          (Caller must lock DOS
                                    session)
        ERROR_ACCESS_DENIED        (User buffer could not
                                    be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)</pre>
where VVRECT is a structure defining the region to be copied and how it is to be copied:
<br /><br />
<pre class="western">    /*
    ** Input for COPYBITMAP request
    */
    typedef struct vvr_s
    {
        ULONG  ulDDFormat;  /* Display driver format          */
                            /* (0 if DIB used)                */
        ULONG  cx;          /* Target bit map width          */
        ULONG  cy;          /* Target bit map height          */
        RECTL  rcl;        /* Rectangle being requested      */
        PBYTE  pbColorXlate;/* Display driver color          */
                            /* translation table              */
    }  VVRECT;</pre>
and where ''pOutput''points to an output graphics buffer. Using this call, the DOS Session Window Manager keeps a private bit map in sync with the virtual video device driver's graphics buffer for a given DOS session.
''ulDDFormat''in the VVRECT structure determines whether the request is a DIB transfer (zero) or a DDB transfer (nonzero). DIB transfers are supported for whole scan lines only (that is, xLeft and xRight are ignored). The first requested scan line must be copied to offset 0 of the bit-map buffer, and so on.
Only one DDB format, DDFORMAT_4PLANE (1), has been defined for the current release, but third parties that provide both new virtual video device drivers and new PM display drivers can define their own formats. The DOS Session Window Manager, in its capacity as mediator between the virtual video device driver and the Presentation Manager display driver, makes no interpretation of ''ulDDFormat''in the VVMODE structure other than to initiate device-independent bit-map transfers for a zero format and device-dependent transfers for nonzero formats.
The DDFORMAT_4PLANE format requires a bit-map buffer that matches the dimensions of the DOS session's current graphics mode and has exactly four color planes (16 colors). The first scan line of the first plane is at offset 0, followed by the first scan line of the second plane at the next DWORD boundary, and so on. In addition, none of the four planes of data for a particular scan line can cross a 64KB boundary; instead, they must start at the next 64KB boundary.
For example, if the DOS session is in a 640 x 480 x 16 mode (that is, four planes of 480 80-byte scan lines), then only 204 complete scan lines will fit in each 64KB section of the buffer. The buffer must therefore be 128KB, plus 22.5KB for the 72 remaining scan lines, for a total of 150.5KB.
For this version of OS/2, DDFORMAT_4PLANE bit-map transfers are supported only for whole scan lines (vvr.rcl.xLeft and vvr.rcl.xRight are ignored). The buffer is assumed to be as large as the DOS session's current graphics screen dimensions, and the requested scan lines must be copied to the same relative position within the target buffer.
ERROR_INVALID_DATA is returned to callers that have exclusive event access when a DOS session is in the process of changing video modes. It alleviates the need to constantly lock and unlock the DOS session to ensure a reliable transfer. Callers without exclusive event access have no alternative but to lock and unlock for each copy; otherwise, they run the risk of obtaining incorrect or obsolete information. The virtual video device driver enforces this, and will return ERROR_NOT_LOCKED if called without exclusive access when the DOS session is unlocked.
�The Wait Event request returns the next windowed DOS session video event. The DOS Session Window Manager uses this interface to obtain video state changes for any unminimized windowed DOS sessions and calls the appropriate graphics engine or PM Window Manager interfaces to realize the changes:
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_WAITEVENT (9)            */
        ULONG cbInput,  /* Size of buffer for event data      */
        PVOID pInput,  /* Pointer to event buffer            */
        ULONG cbOutput, /* Sizeof(VVEVENT)                    */
        PVOID pOutput  /* Pointer to VVEVENT structure      */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)</pre>
where VVEVENT is filled in with the following information:
<br /><br />
<pre class="western">    /*
    ** Output for VVDSYSREQ_WAITEVENT
    */
    typedef struct vve_s
    {
        LONG  iEvent;  /* One of the VVDEVENT_constants      */
        ULONG sgID;    /* Screen group ID of DOS session      */
        ULONG nData;  /* # of entries of information returned*/
    }  VVEVENT;
    /* Event IDs for VVDSYSREQ_WAITEVENT.                    */
    #define VVDEVENT_NONE    0  /* No change                */
    #define VVDEVENT_MODE      1    / *  Mode  change                  * /
      # define  VVDEVENT _ PALETTE    2    / *  Palette  change              * /
      # define  VVDEVENT _ LVB        3    / *  Text  or  graphics  buffer
                                      / *  change                      * /
      # define  VVDEVENT _ SCROLL    4    / *  Scroll  change                * /
      # define  VVDEVENT _ STRING    5    / *  String  output  change        * /
      # define  VVDEVENT _ CURSOR    6    / *  Cursor  position / type
                                      / *  change                      * /
      # define  VVDEVENT _ INPUT      7    / *  DOS  session  is  input  ready * /
      # define  VVDEVENT _ ENDPASTE  8    / *  Cancelled  pasting          * /
      # define  VVDEVENT _ PASTE      9    / *  Start  pasting                * /
      # define  VVDEVENT _ SWITCHERROR  10    / *  Session  switch  error    * /
      # define  VVDEVENT _ TITLECHANGE  11    / *  Session  title  change    * /
      # define  VVDEVENT _ DDE          12    / *    Set / Clear  DDE  flag    * / </pre>
and the buffer addressed by ''pInput''is filled in with:
<br /><br />
<pre class="western">    VVMODE structure,      if (iEvent == VVDEVENT_MODE)
    VVLVB structure(s),    if (iEvent == VVDEVENT_LVB)
    VVSCROLL structure,    if (iEvent == VVDEVENT_SCROLL)
    VVSTRING structure,    if (iEvent == VVDEVENT_STRING)
    VVCURSOR structure,    if (iEvent == VVDEVENT_CURSOR or
                                VVDEVENT_INPUT)
    null-terminated string, if (iEvent == VVDEVENT_TITLECHANGE)</pre>
For all the above events, ''nData''will equal 1 (with the exception of the LVB event, which will return the number of VVLVB structures provided). For those events not listed (PALETTE, PASTE, ENDPASTE, SWITCHERROR, and NONE), ''nData''will equal 0, as no additional data is returned with those notifications.
�The ''Control Event''request provides several subfunctions that control the event thread (that is, any thread dedicated to the WAITEVENT request).
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_CONTROLEVENT (10)        */
        ULONG cbInput,  /* See the CONTROL_constants          */
        PVOID pInput,  /* Pointer to event buffer            */
        ULONG cbOutput, /* Sizeof(VVEVENT)                    */
        PVOID pOutput  /* Pointer to VVEVENT structure      */
    );
    #define CONTROL_RELEASE        0 /* Release event thread */
    #define CONTROL_VDMMINIMIZED    1 /* Disable video events */
                                      /* for DOS session      */
    #define CONTROL_VDMUNMINIMIZED  2 /* Enable video events  */
                                      /* for DOS session      */
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION  (iFunc is invalid)
        ERROR_INVALID_PARAMETER (parameter(s) are invalid)</pre>
The RELEASE function is used to unblock any threads blocked in the WAITEVENT request. The resulting event is NONE. The VDMMINIMIZED and VDMUNMINIMIZED functions disable and enable event reporting for the DOS session, respectively.
=== Presentation Manager Display Driver Services ===
The virtual device driver provides the following ''DOSRequestVDD''services for the PM display driver.
�The Set Display Requirements request is issued by a PM display driver whenever PM switches to or from full-screen operation (including the ''first''time it initializes the display, during system initialization):
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* NULL (that is, none)              */
        ULONG iFunc,    /* VVDSYSREQ_SETDRQ (11)              */
        ULONG cbInput,  /* Sizeof(VVDRQ)                      */
        PVOID pInput,  /* Pointer to VVDRQ structure        */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput  /* Undefined                          */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Parameters are invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)</pre>
where VVDRQ is a structure defining the region to be copied and how it is to be copied:
<br /><br />
<pre class="western">    /*
    ** Structure for VVDSYSREQ_SETDRQ
    */
    typedef struct vvdrq_s
    {
        PBYTE  pPhysVRAM;  /* Physical address of VRAM      */
        ULONG  nbReserved;  /* Number of reserved bytes      */
        ULONG  offLatchByte;/* Offset of available latch
                            /* storage                        */
        PBYTE  pfbDRQFlags; /* Pointer to flags (see DRQ_*    */
                            /* constants)                    */
        PBYTE  pfCtrlOwned; /* Addr. of display.dll's        */
                            /* fCtrlOwned flag                */
        PBYTE  pfCtrlNotify;/* Addr. of display.dll's        */
                            /* fCtrlNotify flag              */
        ULONG  nShadowRegs; /* Number of registers to shadow  */
        PVVREG pShadowData; /* Address of first entry in      */
                            /* shadow list                    */
    }  VVDRQ;
    #define DRQ_DIRTYREGS 0x01 /* Video controller registers */
                                /* modified                  */</pre>
and in which the PVVREG pointer points to one or more structures (as indicated by ''nShadowRegs'') containing:
<br /><br />
<pre class="western">    /*
    ** Shadow entry for VVDSYSREQ_SETDRQ
    */
    typedef struct vvreg_s
    {
        USHORT port;    /* Port number                        */
        CHAR  indx;    /* Register index # (-1 if index reg)  */
        BYTE  value;  /* Last value written to register      */
                        /* by virtual video device driver      */
    } VVREG;</pre>
''pPhysVRAM''<br />indicates the starting physical address for VGA VRAM that the display driver will use (for example, A0000h).
''nbReserved''<br />is the number of bytes of display memory reserved exclusively for the PM display driver. It includes all the visible on-screen memory required, which must start at offset 0 from ''pPhysVRAM'', as well as any off-screen memory needed for mouse pointer manipulation, latch storage, and so forth, immediately following. 64KB minus ''nbReserved''yields the amount of off- screen memory to be managed by the virtual video device driver.
''offLatchByte''<br />is the offset (relative to ''pPhysVRAM'') of a byte of video memory that the virtual video device driver can use at any (non-interrupt) time to temporarily save or restore VGA latches to and from system memory.
''pfbDRQFlags''<br />is a 16:16 pointer (Global Descriptor Table (GDT) alias selector:offset) to a byte of resident data containing inter-device driver communication bits. Currently, only one bit (bit 0) is defined, and it is set whenever the virtual video device driver has modified VGA Sequencer or Graphics Data Controller (GDC) registers. The PM display driver uses the bit to determine whether or not it must reinitialize any Sequencer or GDC registers it uses prior to the next PM drawing operation, after it has claimed ownership of the VGA controller.
''pfCtrlOwned''<br />is another 16:16 pointer-to-byte flag that is '''0'''if the controller is currently unowned, or '''1'''if owned. When either party sets the flag, the test and set must be done atomically (for example, XCHG and CMP) to avoid race conditions. If the PM display driver cannot set the flag, it must issue the REQCTRL function to force the virtual video device driver to clear the flag immediately. Similarly, if the virtual video device driver cannot set the flag, it must set the ''CtrlNotify''byte flag (the 16:16 address of which is in ''pfCtrlNotify'') and wait for the PM display driver to finish the current drawing operation and issue the FREECTRL function.
''pShadowData''<br />is a 16:16 pointer to an array of entries specifying a VGA port (for example, 3C0H, 3CEH), a register index or -1 for the index itself, and a shadow byte in which any changes to that register or index must be stored. The virtual video device driver must update the shadow bytes in parallel with the actual OUT instructions, uninterrupted, so that interrupt-time PM pointer operations are not affected. The PM display driver also updates the shadow bytes, but it has no obligation to do so.
�The Request Off-screen Memory request is issued by a PM display driver when it wants to use some of the non-reserved off-screen memory.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* NULL (that is, none)              */
        ULONG iFunc,    /* VVDSYSREQ_REQMEM (12)              */
        ULONG cbInput,  /* 1 implies WAIT, 0 implies NOWAIT  */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* # of bytes of off-screen memory    */
                        /* needed                            */
        PVOID pOutput  /* Address of DWORD to receive offset */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)
        ERROR_NOT_ENOUGH_MEMORY    (Off-screen memory
                                    allocation failed.)</pre>
On successful return, ''pOutput''points to an offset (relative to ''pPhysVRAM'') of one or more contiguous pages of off-screen VGA memory.
<br /><br />
<pre class="western">/--- IMPLEMENTATION NOTE ----------------------------------\
|                                                          |
|  The WAIT-NOWAIT parameter is not honored.  If suf-    |
|  ficient memory is not immediately available ,  an  error    |
|    is  returned  ( that  is ,  behavior  is  always  NOWAIT ) .        |
|    Current  display  driver  technology  uses  only  NOWAIT .      |
|                                                                |
\ ---------- ---------- ---------- ---------- ---------- -------- / </pre>
In the current virtual video device driver implementation, the request always fails if any DOS sessions currently exist. This way, if any background or windowed DOS sessions switch to a planar graphics mode, they will not be starved for VGA memory due to indeterminate memory consumption by PM (for example, Task Manager popped up, pull-down menu active, and so forth).
�The Free Off-screen Memory request is issued by a PM display driver to free memory allocated by the above request. It should do so in a timely manner, particularly if the memory was allocated by way of a WAIT request.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* NULL (that is, none)              */
        ULONG iFunc,    /* VVDSYSREQ_FREEMEM (13)            */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* # of bytes of off-screen memory    */
                        /*  freeing                          */
        PVOID pOutput  /* Address of DWORD containing offset */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not
                                    be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)</pre>
�The Request VGA Controller request is issued by a PM display driver to force the virtual video device driver to immediately release ownership of the VGA controller. Ownership is indicated by the ''fCtrlOwned''byte flag (see the VVDRQ data structure description in the section titled [[00399.htm|Presentation Manager Display Driver Services]]).
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* NULL (that is, none)              */
        ULONG iFunc,    /* VVDSYSREQ_REQCTRL (14)            */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput  /* Undefined                          */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid.)</pre>
�The Free VGA Controller request is issued by a PM display driver to notify the virtual video device driver that the VGA controller is now available. This request is not issued every time the display driver completes an operation, but rather when the virtual video device driver has requested notification by setting the ''fCtrlNotify''byte flag (see the VVDRQ data structure description in the section titled [[00399.htm|Presentation Manager Display Driver Services]]).
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* NULL (that is, none)              */
        ULONG iFunc,    /* VVDSYSREQ_FREECTRL (15)            */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput  /* Undefined                          */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)</pre>
�The Query VRAM Status request is issued by the PM Session Manager during screen-switches back to PM. It indicates whether or not any intermediate full-screen switches to DOS sessions might possibly have invalidated PM's last video image. If no invalidation occurred, then certain expensive PM application repaints are avoided.
<br /><br />
<pre class="western">    DosRequestVDD
    (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,    /* NULL (that is, none)              */
        ULONG iFunc,    /* VVDSYSREQ_QUERYVRAMSTATUS (16)    */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,  /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput  /* Undefined                          */
    );
    Returns:
        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION    (iFunc is invalid.)
        ERROR_INVALID_DATA        (Video memory has been invalidated.)</pre>
Success indicates that PM's memory image is intact; failure means that the image may or may not be intact.
=== Other Virtual Video Device Driver Services ===
A virtual video device driver provides many ''VDHRequestVDD''services for other virtual video device drivers. Some of the common services provided are listed below:
<br /><br />
<pre class="western">    VDHRequestVDD
    (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT  iFunc,    /* VVDDEVREQ_DEVACCEPT (5)            */
        PVOID pReqIn,  /* Undefined                          */
        PVOID pReqOut  /* Undefined                          */
    );                /* Returns TRUE                      */
    VDHRequestVDD
    (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT  iFunc,    /* VVDDEVREQ_DEVRELEASE (6)          */
        PVOID pReqIn,  /* Undefined                          */
        PVOID pReqOut  /* Undefined                          */
    );                /* Returns TRUE                      */
    VDHRequestVDD
    (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT  iFunc,    /* VVDDEVREQ_DSPACCEPT (7)            */
        PVOID pReqIn,  /* Undefined                          */
        PVOID pReqOut  /* Undefined                          */
    );                /* Returns TRUE                      */
    VDHRequestVDD
    (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT  iFunc,    /* VVDDEVREQ_DSPRELEASE (8)          */
        PVOID pReqIn,  /* Undefined                          */
        PVOID pReqOut  /* Undefined                          */
    );                /* Returns TRUE                      */
    VDHRequestVDD
    (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT  iFunc,    /* VVDDEVREQ_POSTEVENT (9)            */
        PVVPOST pvvp,  /* Pointer to event structure        */
        PVOID pReqOut  /* Undefined                          */
    );                /* Returns TRUE                      */</pre>
Any virtual video device driver receiving a DEVRELEASE request that owns its respective device should release ownership (that is, uninstall all associated I/O hooks, page-fault hooks, page mappings, and so forth), so that an accompanying virtual device driver can manage the device in its stead.
This support is provided for multiple virtual video device drivers installed for the same device, but virtualizing different aspects of the hardware (for example, standard VGA and Super VGA virtual video device drivers for a single Super VGA adapter). A virtual video device driver that is not currently the owner must silently pass on any ''DosRequestVDD''and ''VDHRequestVDD''requests that it receives, using the VDDREQ_PASS return code.
Similarly, any virtual video device driver receiving a DEVACCEPT request that does not already own its respective device and can currently accept ownership should take it (that is, install appropriate I/O hooks, page- fault hooks, page mappings, and so forth).
The DSPACCEPT and DSPRELEASE requests are similar to the preceding requests but much more restricted in scope. They are generally intended to determine which virtual video device driver (for one or more adapters) is managing the image currently displayed. For example, on VGA and 8514/A single- display systems, the display owner is the virtual video device driver that responds to certain system requests (that is, QUERYMODE to COPYBITMAP) and virtual mouse device driver drawing requests.
The Post Event request also passes the following structure:
<br /><br />
<pre class="western">    /*
    ** Input for POSTEVENT request
    */
    typedef struct vvp_s
    {
        LONG  iEvent;  /* See the VVDEVENT_* constants      */
        PVOID  pEvent;  /* Event data (varies from one event  */
                        /* to another)                        */
        ULONG  flEvent; /* Event posting flags                */
                                  /*  (See POSTEVENT_*
                                  /*    constants)          */
    }  VVPOST;
    #define VVDEVENT_NONE        0 /* No change              */
    #define VVDEVENT_MODE        1 /* Change in VDM's mode  */
    #define VVDEVENT_PALETTE    2 /* Change in VDM's palette*/
    #define VVDEVENT_LVB        3 /* Change in VDM's LVB    */
    #define VVDEVENT_SCROLL      4 /* Scroll of VDM's LVB    */
    #define VVDEVENT_STRING      5 /* String output          */
    #define VVDEVENT_CURSOR      6 /* Cursor position/type  */
                                    /* change                */
    #define VVDEVENT_INPUT      7 /* DOS session is checking*/
                                    /* for input data        */
    #define VVDEVENT_ENDPASTE    8 /* DOS session has        */
                                    /* cancelled pasting      */
    #define VVDEVENT_PASTE      9 /* DOS session is ready  */
                                    /* for additional pasting */
    #define VVDEVENT_SWITCHERROR 10 /* DOS session cannot be */
                                    /* switched foreground  */
    #define VVDEVENT_TITLECHANGE 11 /* DOS session title has */
                                    /* changed              */
    #define VVDEVENT_DDE          12  / *  Set / Clear  DDE  flag      * /
      # define  POSTEVENT _ ADD      0x0001  / *  Add  given  event .        * /
      # define  POSTEVENT _ FLUSH    0x0002  / *  Flush  given  ( or        * /
                                        / *  existing )  event        * /
      # define  POSTEVENT _ DELETE  0x0004  / *  delete  existing  event  * / </pre>
This gives a virtual video device driver (for example, 8514/A) that is operating cooperatively with another virtual video device driver (for example, CGA/EGA/VGA) the ability to post events to the DOS Session Window Manager without having to duplicate the event management.
=== Super VGA Virtual Video Device Driver Support ===
This section describes how to add support for a new chip set with Super VGA capability. The source code used is compiled conditionally to produce all the virtual video device drivers; care should be taken to ensure that additions are inserted into the appropriate driver.
=== Overview ===
The first goal of virtual video device driver support is to maintain the integrity of the operating system, and then to maintain the integrity of the DOS session. A DOS session has almost total access to the video hardware when running full-screen (foreground) and can put it into a state that prevents successful return to the desktop. An application can program registers into any state and use on-chip hardware-assist or coprocessed capabilities. A DOS session with full access to the video hardware can make use of all the capabilities provided.
While the DOS session remains full-screen, none of this is a problem. However, when a user wants to switch to another session, the adapter state must be saved and then restored accurately when it is brought into the foreground again. (Requirements for the application to continue to execute in the background will be addressed later in this chapter.) Assume that if the DOS session application is operating in an enhanced mode (above standard VGA), it is put into a ''suspended''state, that is, it is not permitted to execute while in the background.
A virtual video device driver works hardest when switching from background to foreground, or the reverse. At these times, the entire state of the adapter, register, and video memory contents must be saved and restored.
In addition, if the base video subsystem is not adapter- or chip set-aware, the adapter must be placed (by default) into a ''clean''state. A problem could occur if the new foreground session, after leaving an enhanced-mode DOS session, is a protect-mode session and no base video support exists for protect mode. Notice that the desktop is just another protect mode session that also might be running in an enhanced mode. This enhanced-mode support might be localized to the desktop display driver. ''Do not confuse this with protect-mode support''.
'''CAUTION: <br />'''Anytimeavirtualvideodevicedriverrequiresregisteraccesstodeterminechip revisions ,orforwhateverreason ,thatprocesscanoccurinthebackground .All registersreadfromorwrittentoshouldberestored ,includingtheirindexes ,if appropriate .
=== Initial Considerations ===
The existing virtual video device driver, which forms the base for the new support, is aware of all VGA registers. Therefore, the first consideration is to identify the ranges of port addresses that are not part of the register set. All extended registers must be shadowed when a DOS session is in the background and saved/restored, including extensions to indexed registers already in the VGA range and non-indexed registers.
Currently, most chip sets have some means of mapping the video buffer into the A000-BFFF address range, or alternatively, access to video memory through port I/O. If the buffer is memory-mapped into some other region below 1MB, that part of the DOS session address space must be reserved by the virtual video device driver to handle the page faults generated as a result of access to those addresses by the DOS session.
Support for coprocessed chip sets requires even further consideration. A DOS session can switch from foreground to background at any time. If a DOS session application has initiated a coprocessor operation that has not completed when the virtual video device driver receives control to perform a switch to the background, some strategy must be adopted to ensure that, for instance, no data is lost by the DOS session. Obviously, this is relevant only if data is required from the application in a system memory- to-video memory transfer, or the reverse. Foreground and background switches are further described later in this chapter.
=== Initialization ===
During the creation of a DOS session, the virtual video device driver is called to perform certain tasks before the DOS session is permitted to execute.
=== Chip Set Identification ===
Before creating the first DOS session the chip set on which the device driver is running should be identified to ensure that virtual video support is provided for that chip set. (This task must be done only once and is not required for subsequent DOS sessions.)
=== Process PMI File ===
If this method is employed, the file must be read at this time. This is a once-only operation. Again, this cannot be performed during virtual video device driver initialization because the virtual device helper (VDH) services required to read the file are available only at DOS session task time.
The sections of the file required by the virtual video device driver are ''AdapterType'', ''ChipSet'', ''TrapRegs'', ''Cleanup'', and ''Lock''and ''UnLock''. A check against the adapter/chip set entries is used to confirm that the file is valid for the current configuration.
The list of entries in the ''TrapRegs''section specifies the I/O port addresses and indexed ports that are to be saved and restored by the virtual video device driver. A bit mask for indexed registers is created and used for this purpose.
The ''Cleanup'', ''Lock'', and ''UnLock''sections literally are used to perform the specified functions. ''Cleanup''is required to put the adapter into a default clean state.
=== Install I/O Hooks ===
If the chip set uses port addresses that are not in the VGA range, I/O handlers must be installed to handle access to these ports when the DOS session is in the background. Otherwise, any Read or Write will be passed directly to the hardware or to a default handler. Hooks must be provided to take care of the accesses.
Registers with addresses outside the VGA range require individual treatment . Two arrays-''ahleFgnd''when the DOS session is foreground, and ''ahleBgnd''when the DOS session is background-use a list of ports and their associated functions to handle Reads and Writes to the specified ports.
=== Initialize Shadow Register Data ===
The virtual video device driver retains sets of data on a per-DOS session basis. Copies of the contents of all the adapter registers should be stored in this area. All this data must be initialized, including data for extended registers. If the DOS session creation occurs while the DOS session is in the background, the same processing occurs as that for foreground, except that I/O port Reads and Writes are shadowed to and from instance data.
The first video-related operation is a BIOS call to set the initial video mode of the DOS session. If the BIOS expects certain configuration registers to contain information that is required when setting a mode, the shadow data must reflect this; therefore, before the DOS session executes, this shadow data must be set to some defaults - usually a simple case of reading the contents of all registers into the shadow data. This could occur while the hardware is set up in any particular mode; however, mode- specific data should be irrelevant.
=== Foreground/Background Processing ===
There are two main functions to be performed here: saving and restoring the contents of registers and video memory. All the information necessary to be able to restore a DOS session to the state at which it last executed should be available.
The ability to save and restore registers is dependent on two arrays of variable length - ''apleAll''and ''apleNoTrap'', which contain port addresses and pointers to data areas for each indexed and non-indexed port. ''apleNoTrap''has entries for I/O ports not trapped when the DOS session is foreground. For example, if a write-only port address is always trapped, even when the DOS session is foreground, this permits its value to be restored from shadow data that is already valid; there is no need (or, in this case, possibility) to read the hardware. These entries in ''apleNoTrap'', then, are for ports that must be read from the hardware. In contrast, the ''apleAll''array contains all port addresses and is used to restore the hardware state .
New port addresses that have not already been handled must be added to these array lists. Registers are restored in the order specified in the array. If there is some dependency as to the order of the programming registers on a restore, the array entries must reflect this dependency.
A number of flags are available when reading or writing registers, which is performed by a non-preemptible routine. One of the flags permits the Sequencer to be reset around the operation. This flag should be used where appropriate.
In any of the enhanced video modes, a shadow video buffer is required also to store all or part of video memory. The decision as to whether to save the entire contents of video memory, or only what is deemed to be in use, depends on two factors: what is known about the video mode in effect, or the default memory organization for that particular mode.
An additional problem that can be encountered when an enhanced mode is set and the DOS session is foreground is that there is no way to determine how much video memory the application has actually used. The only way to accurately determine this is to invalidate the address region occupied by video memory, trap bank selected registers, and handle page faults when this region is touched, invalidating the region with each change in bank. This constitutes background virtualization and is too costly for a foreground DOS session in terms of performance.
Saving all of the video memory all of the time could introduce a significant performance penalty: 1MB of shadow buffer must be kept somewhere and, with multiple DOS sessions in enhanced modes, this could become significant. Currently, a viable compromise is to save as much video memory as is calculated to be in use, using the ''mode data''. (Mode data is determined by inspecting register values to get the display resolution. If this is not reflected in standard VGA registers, special handling is required.)
Upon notification that the DOS session is going into the background, that is, the DOS session is currently full-screen and has full hardware access, the DOS session is frozen to ensure that no further execution takes place. A snapshot of all the registers is thus saved by reading the hardware. As described previously, the ''apleNoTrap''array triggers the saving of appropriate registers. Any special-case processing required to save register states should be a part of this process.
The video buffer contents are then saved in one of two ways:
�Linear modes are handled as straight transfers, 64KB at a time, by setting the appropriate bank and copying from video memory to the shadow buffer.
�Planar modes are copied, one plane at a time, and the 8514/A uses the graphics engine for the transfer.
The method used depends on the hardware capabilities. Some registers might need to be placed in a specific state before the video-memory transfer takes place to ensure that the memory organization does not interfere with what is saved. This shadow buffer will be used to create a bit map for the desktop, on request, if the DOS session becomes windowed.
Bringing a DOS session to the foreground is almost the reverse process. Registers first are restored to the saved state, and then video memory is restored, followed by another restore of the registers. Part of the memory transfer process involves setting registers to an appropriate state for transfer and could destroy the restored state.
Another important part of this foreground-background processing is the requirement to update data with only a ''best guess''as to the current state of the DOS session. If the DOS session was permitted to run while in the background, its state could have changed from a text mode to graphics mode, or the type of graphics mode may have changed. It is important to be aware of this in order to successfully restore the state of the DOS session. VGA modes indicate their state through use of standard GDC, CRTC, or Sequencer registers, but such might not be the case for a particular chip set. Enhanced mode support could be enabled by the programming of some extended register. Awareness of this functionality must be included as part of updating the state information.
The situation that can arise when switching a DOS session that is using a graphics coprocessor to the background was described previously. The coprocessor could be in the process of accepting data from or passing data to the DOS session application. If, at this point, the DOS session is put into a suspended state, the coprocessor cannot complete the operation, and the DOS session will lose data. Any further attempt to use the DOS session will probably result in an error. The virtual video device driver could complete the operation on behalf of the application, but this might be too complex, unpredictable, or frankly impossible.
The most secure solution is to permit the DOS session to continue to execute until the coprocessor operation has completed. At that stage, before the DOS session is frozen, it is still going to be given an execution time slice. Therefore, you can block the virtual video device driver with a semaphore, effectively pausing the ''Set Background''process until the DOS session has completed its operation. One method of being notified that the operation is complete is to install I/O hooks for all ports and use them to clear the semaphore that blocked the virtual video device driver. Any subsequent port access then will permit the virtual video device driver to regain control to complete the background switch. Any number of hook types can be employed by the virtual video device driver. A coprocessor interrupt could be used, but that requires the use of a physical device driver and a communication mechanism between it and the virtual video device driver.
=== VGA Virtualization ===
In order for a DOS session to continue executing in the background while an enhanced video mode is set, some form of hardware emulation for that mode is required, if the hardware is not available. This might not always be possible. In the case of a coprocessed chip, some register accesses might be allowed, such as setting parameters for an impending coprocessor operation. The DOS session can be permitted to continue while this is the case; but if an operation is initiated requiring the coprocessor, DOS session execution must be suspended until the DOS session is brought to the foreground.
Dumb-frame buffer chip sets are easier to emulate in enhanced modes, particularly linear (packed-pel or 256-color) modes. Generally, any planar mode requires use of the hardware to achieve acceptable performance. VGA virtualization utilizes this when off-screen video memory is available. Linear modes can be virtualized as long as no hardware-assist functions are required. If the application restricts its operations to simply updating video memory by selecting banks and reading or writing data, it can continue to execute. All that is required in this case is to map the appropriate portion of the shadow video buffer to the expected part of the DOS session address space, usually the A000 region. Some level of support to achieve this already exists.
It is also possible that two or more distinct pieces of video hardware are available. If the desktop used one chip and a DOS session required use of a secondary chip, this would be possible. Multiple chip set scenarios such as this have many possibilities-beyond the scope of this document. If non- overlapping registers are used for each chip set, two distinct virtual video device drivers can be used; otherwise, the solution is more complex.
=== Chip Set-Specific Code ===
Although the PMI File attempts to encapsulate as much chip set-specific data as possible, some chip set-specific code is still required. Two elements, one to get or set the current video memory bank and another to determine the lock state of extended registers, are required.
The main function required is the ability to select banks of video memory for Save, Restore, and Memory-Management operations, requiring two routines : one to set a given bank, another to get the current bank. These routines must be operable from both the current hardware register state and shadow data, depending on whether called in a foreground or background context.
A similar problem involves determining the state of registers used to lock extended functionality, if applicable. The PMI File contains a sequence of I/O operations to be used to lock or unlock extended registers, but the current state of these register also must be determined. Often there is no direct mapping of what is written to these registers to lock or unlock them and what is read back when in either state. A necessary part of the save/ restore process is to retain the lock state.
=== Summary and Suggestions ===
The following is a guideline and list of files, with a brief summary of points as to what functionality, as described previously, is required in each.
vvuser.c
�Chip identification, PMI-File processing.
�Reserve the address space for mapping into other than A000-BFFF range.
vvstate.c
�Chip-specific Restore/UpdateSVGAIOState(), for example, Trident old and new register definitions that cannot be handled by way of PMI entries.
�Update memory state. If chip uses enhanced modes, use extended registers to determine if it is in enhanced mode.
�Check for greater than 16-color mode determination.
�Mode data structure setup, determining the number of horizontal and vertical scanlines and number of colors for current mode.
�Video memory state detection, 16-color, 256-color, or other modes.
�Restoring I/O state. Check if register ordering is important. Is Sequencer reset required around extended register update?
vvsvga.c
�Code routines for getting the register lock state.
�Code get and set bank routines.
�Ensure vvMaxBanks() routine returns appropriate data for allocating and saving the shadow video buffer.
vvdata.c
�Add entries to ahleFgnd, ahlBgnd, apleAll, apleNoTrap.
�Add get/set bank routine entries to apfnGetBank and apfnSetBank.
vvmode.c
�Cleanups, anything not handled by PMI-File ''cleandata''.
vvpmi.c
�Add new token entries for PMI-File parsing.
vvport.c
�Install I/O hooks.
vvsvgaio.asm
�Routines to be called for new ports hooked in background.
vvsvgaid.asm
�Chip Set/Board identification code.
vvdp.h
�Create definitions for new adapter type and chip set.
�Add function prototypes for new functions defined.




Revision as of 18:01, 25 April 2016

By IBM

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

About this Book

The device drivers described in the Display Device Driver Reference provide information and code to enable you to start developing your own OS/2 display device drivers.

Note: To verify that your driver signature is unique, contact the IBM Driver Development Support Center (DDSC) Bulletin Board System (the DUDE) on (407) 982-4239.

How This Book Is Organized

#16-Bit VGA Display Driver This chapter presents the 16-bit VGA driver, a dynamic link library that converts device-independent graphics calls into VGA-specific device instructions.

#8514/A Display Driver This chapter covers the differences between the 16- bit VGA display driver and the 8514.

#32-Bit VGA Display Driver This chapter presents the 32-bit VGA driver, contained in two Dynamic Link Libraries: one hardware-independent, the other hardware-dependent.

Also described are the responsibilities of the driver to the Presentation Manager graphics engine, which loads the Dynamic Link Libraries for the display driver.

#32-Bit Super VGA Display Driver This chapter discusses the differences between the VGA and the Super VGA device drivers.

#SVGA Base Video Subsystem This chapter has been rewritten and now describes how the SVGA base video subsystem handles all non-graphical primitive video device functions. It also describes how to handle the mode set function.

#Physical Video Device Drivers This chapter describes the Video Device handlers, and lists functions used to read and write to the EGA registers. The DPRINTF Print Formatting Package information has been moved from the end of SVGA Base Video Subsystem to the end of this chapter.

Virtual Video Device Drivers This chapter describes the design, implementation, and interfaces of virtual video device drivers, including the virtualization and windowing of DOS sessions on an OS/2 platform. A virtual video device driver is required when it is necessary for multiple DOS sessions to share one or more video devices. "Super VGA Virtual Video Device Driver Support" describes how to add support for an Super VGA capable chip set.

Seamless Windows Support This chapter provides information on how to execute Windows applications in one or more windows on the OS/2 desktop, and includes a Checklist for Palette Management Support in seamless display drivers. It also includes an overview of the Distributed Console Access Facility (DCAF), which provides remote console functions.

PM Palette Management Support This chapter describes Presentation Manager Palette Management, special code that enables applications to specify exact color values for a drawing or image on a particular device. The application's color requests are mapped as closely as possible to the actual colors available in the device's hardware color palette. When possible, the hardware palette is modified to exactly provide the requested RGB values.

Distributed Console Access Facility (DCAF) This chapter discusses the design and purpose of DCAF within the OS/2, DOS and WINDOWS environments.

DBCS Video Driver Support This chapter describes double-byte character set (DBCS) video driver support.

Installing and Configuring Display Device Drivers This chapter describes the OS/2 display driver installation utility program (DSPINSTL.EXE), which provides all the facilities for installing and configuring the IBM Operating System/2 and Presentation Manager display device drivers. This installation utility program also can install and configure WIN-OS/2 (both full-screen and windowed) display drivers, and can install base video service (VIO) and DOS virtual device drivers. A sample DSPINSTL Script is included to assist you in SVGA BBS installations.

Graphics Test Suites This chapter describes test suites that are designed for System Verification Test and Function Verification Test.

Display Test Tool This chapter describes the Display Test Tool, a Presentation Manager application that enables the user to select one or more display tests and execute them.

VIDEOCFG.DLL Exported Functions This chapter describes the VIDEOCFG syntax as working samples, adhering to the style of the "C" programming language. The VIDEOCFG.DLL exported functions, formerly in Chapter 5, are now in this revamped and revised chapter. Also covered is a section on a Generic Video Configuration Interface.

VIDEOPMI.DLL Exported Functions This chapter presents the VIDEOPMI syntax as working samples, adhering to the style of the "C" programming language.

VIDEO Protect-Mode Interface This chapter discusses the format and syntax used to define the necessary data for setting a video mode while in OS/2 protect mode, and to enable virtualization in multiple DOS sessions. The objective is to achieve a protect-mode interface to Super VGA hardware.

Appendixes

Appendix A. 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.

Appendix B. GRE Function Tests (by Function Name) This appendix consists of a table that lists the various GRE function tests, organized by function name.

Appendix C. GRE Function Tests (by Test-Case Name) This appendix consists of a table that lists the various GRE function tests, organized by test-case name.

Appendix D. Graphics Engine Functions This appendix consists of several tables, each of which lists a different type of graphics engine function.

Appendix E. DTT Script File Command Summary This appendix contains a summary of the commands used in a DTT script file.

Appendix F. DTT Command-Line Options Summary This appendix contains a summary of the command-line options.

Appendix G. Sample DTT Script File This appendix contains the code for a sample script file.

Appendix H. Glyph Codes This appendix contains a table that lists the reserved glyph codes and the relationship between glyph pattern and glyph code ID in code page 932.

Appendix I. S3 Display Driver This appendix contains a discussion on the architecture of the S3 Display Device Driver and covers the portions of the driver that require modification in order to support other graphics accelerator chip sets.

Appendix J. S3.DSP (Sample File for Installation and Configuration) This appendix consists of a sample S3 display (DSP) file that contains DSPINSTL installation and configuration commands.

Appendix K. Deciphering File Names in the S3 Driver This appendix consists of a list of S3 file names with an explanation of how the file names are derived.

Appendix L. Color Palette Default Values This appendix contains tables listing the default values for VGA (4bpp), XGA (8bpp) and XGA (16bpp) color palettes.
Miscellaneous

A glossary and index are included.

Notices

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
�The Storage Device Driver Reference
�The Input/Output Device Driver Reference
�The Pen for OS/2 Device Driver Reference
�The Virtual Device Driver Reference
�The Presentation Device Driver Reference
�The Display Device Driver Reference
�The Printer Device Driver Reference
�The Graphics Adapter Device Driver Reference
�The MMPM/2 Device Driver Reference (Multimedia)
To order the DDK call: 

/----------------------------------------------------------------\
|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         |
\----------------------------------------------------------------/

What's New

There were no major changes to this release of the Display Device driver Reference.

The table that appears in #OS/2 Version Compatibility Considerations identifies any compatibility issues associated with updates made to this book.

Try Our New Improved Model!

Are you tired of device-driving late into the night? You may want to consider using the new GRADD (short for GRaphics Adapter Device Driver) model to write your next video driver on OS/2 Warp, Beta Version 99.99.

The GRADD driver model, provided on this DDK CD, requires 10 times less lines of code than previously required to write an OS/2 video device driver. Some of the advantages incorporated in the GRADD model include the following:

  • Simplifies development effort
  • Reduces cycle time
  • Allows incremental development; requires fewer mandatory functions
  • Both This eliminates the need to write a seamless WinOS/2 driver.

If you are writing new video drivers for OS/2 Warp, Beta Version 99.99, you can take advantage of these development savings. Refer to the GRADD Device Driver Reference and code samples on this CD to get started today.

16-Bit VGA Display Driver

The 16-bit VGA display driver provides hardware independence to the application code that performs I/O to a display device. An application program need not be concerned with the hardware-specific requirements of the adapter card.

Overview

The 16-bit VGA display driver is a set of special-purpose I/O routines, operating at privilege level 2 (Ring 2). This driver, along with other presentation drivers, provides the link between the internal interface to display devices and the OS/2* interfaces to the kernel device drivers at Ring 0 (the highest privilege level) and the screen.

When an application needs to perform I/O to the screen, it calls a system DLL, which in turn calls the Presentation Manager* (PM) graphics engine, contained in PMGRE.DLL. The graphics engine then calls the display driver, contained in DISPLAY.DLL. The display driver can then access the adapter hardware directly through memory-mapped I/O, or can call the OS/2 kernel by way of the standard driver mechanism to perform the I/O.

When the display driver is loaded, the graphics engine allocates an internal dispatch table to process the functions. The dispatch table is an array of pointers to function-handling routines. The low-order byte of the function number identifies the member of the array that contains the pointer for the function. The first time that the display driver is called at its OS2_PM_DRV_ENABLE entry point, it replaces the graphics engine pointers in the dispatch table with pointers to the corresponding functions supported by the display driver. Some of the pointer replacements are mandatory; others are optional.

The graphics engine pointer to the dispatch table is passed to the display driver by way of a FillLogicalDeviceBlock call.

16-Bit VGA Architecture

The 16-bit VGA display driver consists of one component (DISPLAY.DLL). DISPLAY.DLL contains all entry points-both device-dependent and device-independent functions (including seamless support) - that the graphics engine calls.

All the fonts, cursors, and bit maps are included in a binary resource file (.RES) that is built and added to the driver by the resource compiler.

Functions

The following is a list of the functions in the graphics engine that are hooked by the 16-bit VGA display driver.

  • Graphics Engine Attribute Functions
  • Graphics Engine AVIO Functions
  • Graphics Engine Bit-Map Functions
  • Graphics Engine Color Table Functions
  • Graphics Engine Device Functions
  • Graphics Engine Escape Functions
  • Graphics Engine Line Functions
  • Graphics Engine Marker Functions
  • Graphics Engine Miscellaneous Device Functions
  • Graphics Engine Miscellaneous Screen Functions
  • Graphics Engine Query Functions
  • Graphics Engine String Functions

For more information about these functions and their descriptions, see #Graphics Engine Functions.

Debugging Support

Debugging support is provided through a macro, color_puts<>, contained in seamless.inc. This macro sends data through the kernel debugger port to a serial port. The kernel debugger and its related documentation is provided with the OS/2 2.X Toolkit. The input for the macro is foreground color, background color <string>, as follows: 

ifdef FIREWALLS

        color_puts  BLUE,BLACK,< This message will be output to
                                        the debugging terminal >

endif ;FIREWALLS

Current debugging messages in the code are placed inside the conditional compilation ifdef FIREWALLS. This value is defined when compiling the debug version of the driver. Another example of this macro can be found in init.asm.

The BITBLT Function

One of the most important functions used in Presentation Manager is BITBLT (Bit Block Logical Transfer), which draws the rectangles that make up the PM Desktop, icons, and other bit maps. BITBLT is similar to a byte-block move operation except that blocks are moved on bit boundaries instead of byte boundaries. This could require that the bits of the source be aligned to the bits of the target (phase alignment). An example is moving all bits of a bit map left two pels. Once the bits are aligned, they are combined with an optional pattern and the target, as specified by the raster operation (ROP).

For arbitrary BLT processing, code is derived dynamically and written to a data segment. This segment is then aliased to a code segment, and executed. BITBLT functionality is the same for 16-bit VGA, 32-bit VGA, and 32-bit Super VGA.

For detailed information on BITBLT functionality, see VGA32\IBMDEV32\BITBLT .ASM and VGA32\IBMDEV32\CBLT.ASM.

The innermost functionality of BITBLT can be pictured as follows:

Bytes are fetched from a source. Color conversion is applied if the source and target are of different color formats. (See Color Conversionand XGA Support for Palette Management - Dithering and BITBLTingfor detailed information about color conversion.) The source bits then are aligned with the target. Bits from a previous phase alignment and the current phase alignment are combined to form one byte's worth of data. The unused bits from the phase alignment are saved for the next phase alignment.

The ROP is applied against the source bits, pattern, and target, as needed; the result replaces the target byte.

Overlapping BLTs

The following illustrations show possible overlaps that can occur when a BLT is performed. Since the source and target can overlap, the order in which bytes are processed must be chosen with care. If the order is wrong, a byte of the source might be overwritten (as a target) before the byte is used as a source. (You might remember propagating spaces through a field on the IBM* 360s and 370s).

In the following figures, S is the source, D is the target, and x is the corner from where the first byte will be fetched. The comments (on the right) tell in which directions (X and Y) the BLT must be performed to prevent the overwriting of a source byte before it is used as a source. The possible cases of overlap are as follows:

  1. Disjointed (not special cased)
  2. Identical (not special cased)
  3. Overlapping

The following four examples are degenerate cases (along with identical and disjoint) and the directions are as shown:

Phase Relationship Between Source and Target Bit Maps

Since BLTs are performed on bit boundaries instead of byte boundaries, rotations of the source bit map bytes might have to be performed. Source data is always rotated to align with the target. The following describes how the phase relationship is determined and how to start the BLT. (Some phase relationships require a different number of initial source bit map fetches to acquire enough bits to satisfy the first store.)

The number of bytes separating the source and target in the following examples is irrelevant; only the relationship of the bits within the bytes is important. Saved and used masks are applied after rotating the source byte.

Saved bits mask A mask that gives the bit that must be carried over to the next byte BLTed.

Used bits mask A mask that gives the bits that are to be used for the current byte BLTed.

Old unused bits Bits that were not used in the last byte BLTed and, therefore, bits that must be used for the current byte BLTed.

First byte mask A mask that is used to mask the bits (of the very first byte BLTed) that are to be altered. The complement of this mask gives the bits of the target byte that are to remain unaltered.

The BLT is started based on the cases of overlap as previously specified.

For box cases 3, 4, 5, 6, 8, disjoint, and same (as shown previously), BLTs start at the left, stepping right. Calculations are based on the left side of the source and target rectangles. The starting mask is based on the leftmost byte of the target; the ending mask is based on the rightmost byte of the target, as follows:

For box cases 1, 2, and 7, BLT starting at the right, stepping left. Calculations are performed on the right side of the source and target rectangles. The starting mask is based on the rightmost byte of the target , and the ending mask is based on the leftmost byte of the target.

Raster Operation Codes And Definitions

Each raster operation code represents a Boolean operation in which the source, currently selected brush, and target are combined.

The operands used in the operations are:

S Source bit map
P Currently selected brush (also called pattern)
D Target bit map

The Boolean operators used in these operations are:

o Bitwise OR
x Bitwise Exclusive OR
a Bitwise AND
n Bitwise NOT (inverse)

All Boolean operations are presented in reverse Polish notation. For example, the operation:

PSo

replaces the target with a combination of the source and brush.

The operation:

DPSoo

combines the source and brush with the target. Because there are alternate spellings of the same function, although a particular spelling might not be in the list, an equivalent form will be.

Each raster operation code is an 8-bit integer value that represents the result of the Boolean operation on predefined brush, source, and target values. For example, the operation indexes for the PSoand DPSoooperations are:

In this case, PSohas the operation index 00FC (read from the bottom up); DPSoohas the index 00FE.

Color Conversion

Color conversion applies when the source and target color formats are not the same. Color conversion takes place prior to any mix mode. For additional information, see XGA Support for Palette Management - Dithering and BITBLTing.

�Mono � Color Conversion

Applied when the source is monochrome and the target is color.

When going from monochrome to color, 1 bits are converted to the target image foreground color, and 0 bits are converted to the target image background color.

�Color � Mono Conversion

Applied when the source is color and the target is monochrome.

When going from color to monochrome, all pels that match the passed background IPC (obba_bgndIPC) are converted to the target image background color; all other pels are converted to the target image foreground color.

8514/A Display Driver

The IBM 8514/A display driver shares its basic functionality with the 16- bit VGA display driver. See 16-Bit VGA Display Driverfor details about privilege levels, graphics engine interface, graphics engine functions, dispatch tables, and debugging. For the most part, these topics, as covered in that chapter, apply also to the 8514/A display driver.

Overview

This chapter covers the differences between the 16-bit VGA display driver and the 8514/A display driver, followed by 8514/A device-specific programming information.

Operating Modes

The 8514/A graphics adapter operates in the following modes:

  • Video-graphics array (VGA)

This is the power-on mode; the functionality of the 16-bit VGA display driver is available.

  • Advanced-function

This mode provides a programming interface for the adapter. The primary advantage of the 8514/A display driver over the 16-bit VGA display driver is that the advanced-mode adapter interface handles much of the hardware programming for you. Instead of programming directly into the bit-plane memory, the adapter provides an interface supporting most of the required display functions.

Both modes of operation are selectable under program control.

Macros for Utilizing Available Hardware Capabilities

The 8514/A display driver includes a set of macros to access the adapter interface. When called by the driver, through the entry points, the interface provides a set of functions to utilize the hardware capabilities of the display adapter. Each of the macros is addressed in detail in the sections that follow. 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitIO                                                |
|                                                          |
\----------------------------------------------------------/

Tests an I/O port for a particular value, as follows:

Port The port number to be polled. If not present, it is assumed that the port number is already loaded into the DX register.

Sense The sense of jump needed to remain in the polling loop.

Mask If present, the value that will be ANDed with the polled contents of Port.

EquVal If present, the value that must match the Portcontents, after masking (if Maskis present).

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitIO macro Port,Sense,Mask,EquVal,SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQIN                                               |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A graphics adapter output queue to contain available data.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQIN macro SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQOUT                                              |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A graphics adapter input queue to be ready to accept data.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQOUT macro SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    ChkERRSTATUS                                          |
|                                                          |
\----------------------------------------------------------/

Check for the underrun or overrun state after execution of a variable data command to the 8514/A graphics adapter.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

ChkERRSTATUS macro SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQ                                                 |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A adapter input queue to have a minimum number of words of free space. The queue may contain up to eight words. The number of words still to be dequeued can be ascertained at any time.

MinQSpaceIf at least this many words are available in the queue, fall out of wait loop. This parameter must be present.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQ macro MinQSpace,SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    outwQ                                                 |
|                                                          |
\----------------------------------------------------------/

Outputs a word value to the 8514/A input queue.

Port The port number for which written data will be queued. If this parameter is not present, it will be assumed that the port number is already loaded into the DX register.

Data The immediate or indirect specification of data that will be output to Port. If this parameter is not present, it will be assumed that the data is already loaded into the AX register.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

outwQ macro Port,Data,SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    outbQ                                                 |
|                                                          |
\----------------------------------------------------------/

Outputs a byte value to the 8514/A input queue. This macro differs from outwQin that it is assumed that only the low half of the AX register needs to be loaded. A slight saving in code size is achieved thereby.

Port A port number for which written data will be queued. If this parameter is not present, it will be assumed that the port number is already loaded into the DX register.

Data An immediate or indirect specification of data that will be output to Port. If this parameter is not present, it will be assumed that the data is already loaded into the AX register.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

outbQ macro Port,Data,SaveRegs

Bit-Plane Model

The bit-plane memory in the adapter is arranged in planes of 1024 x 1024 bits. The displayed data is taken from the low 1024 x 768 or 640 x 480 bits . The undisplayed bit-plane memory is used by the adapter as auxiliary storage for functions, like area-fill working storage, as a cache for programmable character sets and marker drawing.

The number of planes available depends on the adapter mode and the amount of video RAM installed, up to a maximum of 32 planes. They are numbered from 0 to 31, with plane 0 associated with bit 0 of the color index. The 8514 display driver provides the following memory mapping for high- resolution mode: 

     /--------------------------------------------------------\
     |                                                        |
     |                                                        |
     |                   onscreen area                        |
     |                                                        |
     |                                                        |
     | (32x32)   64      128      196                         |
     | (40x40)   80      160      240                         |
     | (64x64)  128      256                                  |
 768 |--------------------------------------------------------|
     | ptr   | ptr   | ptr   | ptr   | work  |                |
     | and   | xor   | save  | color | area  | SaveScreenBits |
     | mask  | mask  | area  | bitmp |       | area           |
 848 |--------------------------------------------------------|
     |                      Pattern Cache                     |
 864 |--------------------------------------------------------|
     |                                                        |
     |                                                        |
     |     Font storage area and 3-op BLT temporary space     |
     |                                                        |
     |                                                        |
1023 \--------------------------------------------------------/


32-Bit VGA Display Driver

The 32-bit VGA display driver, like all display drivers, provides hardware independence for OS/2 application programs needing to perform I/O to a display device.

Overview

The 32-bit VGA display driver is contained in a pair of DLLs, which are divided into hardware-dependent and hardware-independent sections. When an application needs to perform I/O to a display device, it calls a system DLL , which in turn calls the OS/2 Presentation Manager graphics engine, PMGRE. DLL. PMGRE is the component that loads the display-driver DLLs.

The display driver has certain responsibilities to the graphics engine (GRE ). Specifically, there are a number of entry points (external functions) in the graphics engine that the display driver is required to hook and support . There are other entry points in the graphics engine that can be optionally hooked by the display driver, when required, for special processing.

Each entry point is a 32-bit pointer to a specific routine in the graphics engine. The graphics engine uses a dispatch tableto call the entry points within the display driver. Essentially, the dispatch table is a block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. The graphics engine then refers to the dispatch table anytime it calls a function in the display driver.

Initially, however, the dispatch table entries point back to routines in the graphics engine. Therefore, the display driver must replace some of the existing pointers with new pointers that point to corresponding routines in the display driver. This action is mandatory for some routines, optional for others. The display driver hooks the entry points in the dispatch table the first time the driver is called at its OS2_PM_DRV_ENABLE entry point for the first subfunction, FillLogicalDeviceBlock.

The ring level(privilege level) of all the entries in the dispatch table can be selected by exporting a table called OS2_PM_DRV_RING_LEVELS. If this table is not exported, all 32-bit functions are dispatched as conforming to Ring 2.

32-Bit VGA Display Driver Architecture

The 32-bit VGA display driver consists of two fundamental components. They are:

  • IBMVGA32.DLL
  • IBMDEV32.DLL.

This architecture was chosen to make the driver more easily portable among various hardware video cards. Super VGA support is provided by using this architecture.

The device-independent functions of the driver are contained in the base DLL, IBMVGA32.DLL. This DLL satisfies entry points common to different hardware cards. The device-specific functions are contained in the device- specific DLL, IBMDEV32.DLL. This DLL satisfies entry points specific to video adapter cards. The graphics engine calls entry points in both DLLs. Also, the two DLLs call exported entry points within each other. In order to port this driver to other video cards, you must write code that supplies the functionality for the entry points in the device-specific DLL. Fonts are now built in a separate DLL, DSPRES.DLL.

DSPRES.DLL is the dynamic link library that supplies the resources such as fonts, pointers, etc. to the display driver. DSPRES.DLL includes resources for both high resolution and low resolution. The IBMDEV32.DLL exports the pointers to the structures for FONT_RES, defFontChar, and defFontMarker, which have the resource IDs of the necessary resources. IBMVGA32.DLL loads DSPRES.DLL, gets the resources with DosGetResource (using the resource ID in defFontXX imported from IBMDEV32.DLL) and saves the pointer to the resources in defFontXX.

The architecture of the 32-bit VGA display driver is illustrated in the following figure: [Artwork not shown]

Base DLL Function Imports

The GRE uses entry points in both IBMVGA32.DLL and IBMDEV32.DLL. IBMVGA32. DLL also calls entry points in IBMDEV32.DLL. The device-specific DLL contains a number of entry points required by the GRE and a number of device-specific API calls.

These device-specific API calls supply the functionality expected by the base DLL. In order to port this driver to other video cards, the developer must write code which supplies the functionality for the entry points in the device-specific API. These routines are discussed in the following pages.

Note:All functions in the base and device-specific DLLs run at Ring 2 with the exception of QueryDeviceBitmaps, QueryDeviceCaps, QueryHardcopyCaps,and QueryDevResource2, which run at Ring 3.

The following functions are imported by the base DLL from the device-specific DLL:

init_hw_regs =IBMDEV32.4000
rgb_to_ipc =IBMDEV32.4004
physical_enable =IBMDEV32.4011
physical_disable =IBMDEV32.4012
device_specific_init =IBMDEV32.4013
device_specific_post_init =IBMDEV32.4014
copy_bits_to_pattern =IBMDEV32.4017
PolyShortLine =IBMDEV32.4023
SaveScreenBits =IBMDEV32.4026
PolyScanline =IBMDEV32.4028
RestoreScreenBits =IBMDEV32.4030
Pixel =IBMDEV32.4034
far_exclude =IBMDEV32.4037
far_unexclude =IBMDEV32.4038
SetColorCursor =IBMDEV32.4039
DeviceSetCursor =IBMDEV32.4040
SetScreenBusy =IBMDEV32.4041
CharRect =IBMDEV32.4200
CharStr =IBMDEV32.4201
DeviceSetAVIOFont2 =IBMDEV32.4202
ScrollRect =IBMDEV32.4204
UpdateCursor =IBMDEV32.4205
DeviceSeamlessInit =IBMDEV32.4206
deselect_bitmap =IBMDEV32.4301
save_bitmap =IBMDEV32.4302
DeviceCreateBitmap =IBMDEV32.4303
DeviceSelectBitmap =IBMDEV32.4304
DeviceDeleteBitmap =IBMDEV32.4305
GetBitmapBits =IBMDEV32.4306
SetBitmapBits =IBMDEV32.4307
DrawLinesInPath =IBMDEV32.4308
DisJointLines =IBMDEV32.4309
PolyLine =IBMDEV32.4310
GetCurrentPosition =IBMDEV32.4311
SetCurrentPosition =IBMDEV32.4312
CharString =IBMDEV32.4313
Drawbits =IBMDEV32.4314
ImageData =IBMDEV32.4315
CharMarkerPos =IBMDEV32.4316
CharStringPos =IBMDEV32.4317
Bitblt =IBMDEV32.4318
DrawBorder =IBMDEV32.4319
PolyMarker =IBMDEV32.4320
alloc_brush =IBMDEV32.5201
free_brush =IBMDEV32.5202
copy_brush =IBMDEV32.5203
QueryRealColors =IBMDEV32.5300
QueryColorIndex =IBMDEV32.5301
QueryNearestColor =IBMDEV32.5302
QueryColorData =IBMDEV32.5303
UnrealizeColorTable =IBMDEV32.5304
RealizeColorTable =IBMDEV32.5305
deselect_lct =IBMDEV32.5306
QueryLogColorTable =IBMDEV32.5307
save_lct =IBMDEV32.5308
QueryRGBColor =IBMDEV32.5309
CreateLogColorTable =IBMDEV32.5310
PropagateSysClrChange =IBMDEV32.5311
MakeColorsValid =IBMDEV32.5312
MakeBrushValid =IBMDEV32.5313
MakePassedColorsValid =IBMDEV32.5314
device_enter_driver =IBMDEV32.5315
ResetLogColorTable =IBMDEV32.5316

Base DLL Function Exports

The following functions are exported by the base DLL. Exports beyond @1001 are also imported by the device-specific DLL.

MoveCursorDescription @103
OS2_PM_DRV_ENABLE @1 RESIDENTNAME
OS2_PM_DRV_ENABLE_LEVELS @998
OS2_PM_DRV_RING_LEVELS @999
CheckCursor @104
SEAMLESSTERMINATE @350 RESIDENTNAME 2
private_alloc @1000
private_free @1001
enter_driver @1002
leave_driver @1003
save_that_error @1004
perform_rip @1005
ddc_validate @1006
enter_driver_sem @1007
GetVRAMR0Pointer @1008
ring3_CriticalError @1010
InnerAccumulateBounds @1014
correlate_for_point_si @1016
enter_driver_sem_only @1017
leave_driver_sem_only @1018
do_sl_corr @1019
check_sem @1029
get_clip_rects @1031
ShortlineCorrelate @1032
far_clip_line @1033
ComputeShortlineBounds @1034
save_that_warning @1042
Force_Valid_CP @1202
Vio32SetState @3000
Vio32SetMode @3001
free_bm @4100
alloc_bm @4101
AllocMem @4102
FreeMem @4103
recalc_correlate_rect @4104
pfnDefDisJointLines @4105
pfnDefPolyLine @4106
pfnDefSetCurrentPosition @4107
convert_world_screen @4108
convert_screen_world @4109
pfnDefRectVisible @4110
pfnDefCharStringPos @4111
pfnDefBitblt @4112
pfnDefGetClipRects @4113
pfnDefQueryTextBox @4114
double_enter_driver @4115
validate_rectl @4116
intersect_rcl @4117
intersect_with_corr @4118
AccumBoundsInDevCoords @4119
pfnDefDrawbits @4120
convert_rectl @4121
pfnDefPolyMarker @4122

Device-Specific DLL Function Imports

The following functions are duplicates of the base DLL exports beyond @1001 . They are imported by the device-specific DLL from the base DLL.

enter_driver =IBMVGA32.1002
leave_driver =IBMVGA32.1003
save_that_error =IBMVGA32.1004
perform_rip =IBMVGA32.1005
ddc_validate =IBMVGA32.1006
enter_driver_sem =IBMVGA32.1007
GetVRAMR0Pointer =IBMVGA32.1008
ring3_CriticalError =IBMVGA32.1010
InnerAccumulateBounds =IBMVGA32.1014
correlate_for_point_si =IBMVGA32.1016
enter_driver_sem_only =IBMVGA32.1017
leave_driver_sem_only =IBMVGA32.1018
do_sl_corr =IBMVGA32.1019
check_sem =IBMVGA32.1029
get_clip_rects =IBMVGA32.1031
ShortlineCorrelate =IBMVGA32.1032
far_clip_line =IBMVGA32.1033
ComputeShortlineBounds =IBMVGA32.1034
save_that_warning =IBMVGA32.1042
Force_Valid_CP =IBMVGA32.1202
Vio32SetState =IBMVGA32.3000
Vio32SetMode =IBMVGA32.3001
free_bm =IBMVGA32.4100
alloc_bm =IBMVGA32.4101
AllocMem =IBMVGA32.4102
FreeMem =IBMVGA32.4103
recalc_correlate_rect =IBMVGA32.4104
pfnDefDisJointLines =IBMVGA32.4105
pfnDefPolyLine =IBMVGA32.4106
pfnDefSetCurrentPosition =IBMVGA32.4107
convert_world_screen =IBMVGA32.4108
convert_screen_world =IBMVGA32.4109
pfnDefRectVisible =IBMVGA32.4110
pfnDefCharStringPos =IBMVGA32.4111
pfnDefBitblt =IBMVGA32.4112
pfnDefGetClipRects =IBMVGA32.4113
pfnDefQueryTextBox =IBMVGA32.4114
double_enter_driver =IBMVGA32.4115
validate_rectl =IBMVGA32.4116
intersect_rcl =IBMVGA32.4117
intersect_with_corr =IBMVGA32.4118
AccumBoundsInDevCoords =IBMVGA32.4119
pfnDefDrawbits =IBMVGA32.4120
convert_rectl =IBMVGA32.4121
pfnDefPolyMarker =IBMVGA32.4122

Device-Specific DLL Function Exports

The following functions are duplicates of the base DLL import functions. They are exported by the device-specific DLL.

init_hw_regs @4000
rgb_to_ipc @4004
physical_enable @4011
physical_disable @4012
device_specific_init @4013
device_specific_post_init @4014
copy_bits_to_pattern @4017
PolyShortLine @4023
SaveScreenBits @4026
PolyScanline @4028
RestoreScreenBits @4030
Pixel @4034
far_exclude @4037
far_unexclude @4038
SetColorCursor @4039
DeviceSetCursor @4040
SetScreenBusy @4041
CharRect @4200
CharStr @4201
DeviceSetAVIOFont2 @4202
ScrollRect @4204
UpdateCursor @4205
DeviceSeamlessInit @4206
deselect_bitmap @4301
save_bitmap @4302
DeviceCreateBitmap @4303
DeviceSelectBitmap @4304
DeviceDeleteBitmap @4305
GetBitmapBits @4306
SetBitmapBits @4307
DrawLinesInPath @4308
DisJointLines @4309
PolyLine @4310
GetCurrentPosition @4311
SetCurrentPosition @4312
CharString @4313
Drawbits @4314
ImageData @4315
CharMarkerPos @4316
CharStringPos @4317
Bitblt @4318
DrawBorder @4319
PolyMarker @4320
alloc_brush @5201 NONAME
free_brush @5202 NONAME
copy_brush @5203 NONAME
QueryRealColors @5300
QueryColorIndex @5301
QueryNearestColor @5302
QueryColorData @5303
UnrealizeColorTable @5304
RealizeColorTable @5305
deselect_lct @5306
QueryLogColorTable @5307
save_lct @5308
QueryRGBColor @5309
CreateLogColorTable @5310
PropagateSysClrChange @5311
MakeColorsValid @5312
MakeBrushValid @5313
MakePassedColorsValid @5314
device_enter_driver @5315
ResetLogColorTable @5316

Base GRE Entry Points

The base DLL supplies functionality for the following calls from the Graphics Engine. For further information see the Presentation Device Driver Reference.

AccumulateBounds
Death
DeviceGetAttributes
DeviceInvalidateVisRegion
DeviceQueryFontAttributes
DeviceQueryFonts
DeviceSetAttributes
DeviceSetDCOrigin
DeviceSetGlobalAttribute
ErasePS
Escape
GetBoundsData
GetCodePage
GetCurrentPosition
GetDCOrigin
GetLineOrigin
GetPairKerningTable
GetPel
GetPickWindow
GetScreenBits
GetStyleRatio
LockDevice
NotifyClipChange
NotifyTransformChange
QueryDeviceBitmaps
QueryDeviceCaps
QueryDevResource2
QueryHardcopyCaps
RealizeFont
ResetBounds
Resurrection
SetCodePage
SetCurrentPosition
SetLineOrigin
SetPel
SetPickWindow
SetScreenBits
SetStyleRatio
UnLockDevice

Device-Specific GRE Entry Points

The device-specific DLL also supplies functionality for the following calls from the Graphics Engine.

Refer to the Presentation Device Driver Referencefor additional information on these calls.

Bitblt
CharRect
CharStr
CharString
CharStringPos
CreateLogColorTable
DeviceCreateBitmap
DeviceDeleteBitmap
DeviceSelectBitmap
DeviceSetCursor
DrawBits
DrawBorder
DrawLinesInPath
GetBitmapBits
ImageData
MoveCursor
Polyline
PolyMarker
PolyScanline
PolyShortLine
PropagateSysClrChange
QueryColorData
QueryColorIndex
QueryLogColorTable
QueryNearestColor
QueryRealColors
QueryRGBColor
RealizeColorTable
RestoreScreenBits
SaveScreenBits
ScrollRect
SetBitmapBits
SetColorCursor
StretchBlt
UnrealizeColorTable
UpdateCursor

The device-specific DLL also supplies functionality for the DeviceSetAVIOFontcall from GRE. In the device-specific DLL, the function must be named DeviceSetAVIOFont2.

Refer to the Presentation Device Driver Referencefor additional information.

The Device-Specific API

These are functions that are created by the developer of the device- specific driver:

copy_bits_to-pattern
deselect_bitmap
device_enter_driver
deselect_lct
device_specific_post_init
device_specific_init
far_exclude
far_unexclude
init_hw_regs
physical_disable
physical_enable
Pixel
PropagateSysClrChange
save_bitmap
save_lct

Each of these functions must behave exactly as described.

For the descriptions of the register contents, the equal " = " sign means that the register contains the value named. For example:

ECX = number of bytes per scanmeans that the register contains the actual number of bytes per scan.

The arrow " � " sign means that the register contains a pointer to the value, and not the actual value itself. For example:

ECX � number of bytes per scanmeans that the value in the register is a pointer to the memory location that contains the number of bytes per scan. 

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    copy_bits_to_pattern                                  |
|                                                          |
|    void copy_bits_to_pattern(void)                       |
|                                                          |
\----------------------------------------------------------/

Description: Copy a source pattern bit map to a destination pattern bit map .

Entry: 

AL  = Number of color planes in source bit map
AH  = Width of bit map in pels (significance through eight)
EBX � DDC
ECX = Number of bytes per scan of source bit map
EDX = Height of bit map
ESI � First byte of the destination buffer
EDI � First byte of the source buffer

Return Values: None

Error Returns: None

Registers Preserved: EBX, EBP, ESP

Registers Preserved: EAX, ECX, EDX, ESI, EDI, FLAGS

Invoked From: 

SetPatternFont         (Winattrs.asm)

Routines Called: None

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    deselect_bitmap                                       |
|                                                          |
|    void deselect_bitmap(void)                            |
|                                                          |
\----------------------------------------------------------/

Description: Decrements selection count in the bit map, clears the pointer to the surface device, and clears the following DDC bits:

�DDC_PRESENT - indicating that there is no surface.
�DDC_CLIP_NOTIFY - indicating clipping is invalid
�DDC_VISIBLE - indicating nothing is showing.

If the selection count is 0, it clears the handle to DDC, indicating a free bit map.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, ECX, EDX, ESI, EDI, ESP, EBP

Registers Destroyed: EBX, FLAGS

Invoked From: 

restore_ddc_state      (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_enter_driver                                   |
|                                                          |
|    void device_enter_driver(void)                        |
|                                                          |
\----------------------------------------------------------/

Description: device_enter_driveris a null function.

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: EAX, ECX, EDX, ESI, EDI, ESP, EBP, FLAGS

Registers Preserved: None

Invoked From: 

enter_driver (enter.asm)

Routines Called: Dependent on processing

Video Semaphore Required for Processing: Dependent on processing 

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    deselect_lct                                          |
|                                                          |
|    void deselect_lct(void)                               |
|                                                          |
\----------------------------------------------------------/

Description: deselect_lctdecrements the usage count in the logical color table.

When the usage count is 0, deselect_lct frees the memory of the logical_ color_tableby calling private_freewith the ECX pointing to the memory to be released and sets the default color table.

private_freeis an exported function contained in IBMVGA32.DLL.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, EDX, ESI, EDI, ESP, EBP, FLAGS

Registers Preserved: EBX, ECX

Invoked From: 

disable_ddc            (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_specific_post_init                             |
|                                                          |
|    void device_specific_post_init(void)                  |
|                                                          |
\----------------------------------------------------------/

Description: device_specific_post_initis a null function.

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, ESP, EBP, FLAGS

Registers Preserved: None

Invoked From: 

one_time_init       (init.asm)

Routines Called: Dependent on processing

Video Semaphore Required for Processing: Dependent on processing 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_specific_init                                  |
|                                                          |
|    void device_specific_init(void)                       |
|                                                          |
\----------------------------------------------------------/

Description: Initializes gsspScreen.cbto the size of screen memory (64KB), gsspScreen.pPhysMemto the address of screen memory (0A0000h). Sets the marker width and height in the device capabilities buffer (adDevCapsData[ CAPS_MARKER_WIDTH ], adDevCapsData[ CAPS_MARKER_HEIGHT ]). See the Presentation Manager Programming Reference, Volume 1, "DevQueryCaps", for additional information.

Set padBitmapFormatsto the address of the table containing bit map format types.

The table is in the form (# planes, bits/pel). The first pair in the table must be the format that most closely resembles the device.

(For additional information see the Presentation Device Driver Reference, " GreQueryDeviceBitmaps").

Get a Ring 0 alias for screen memory pointer and save in Curdata.pVRAMRing0 .

The following code segment illustrates the sequence described above:

Basically, you open PMDD.SYS via DosOpen and communicate with PMDD.SYS via DosDevIOCtl. 

GetVRAMR0Pointer PROC SYSCALL USES EDI
        LOCAL   hSVGA:DWORD
        LOCAL   ulAction:DWORD
        LOCAL   scrnTx:SCRNTX
        LOCAL   scrnRx:SCRNRX
        LOCAL   fAttach:BYTE

        INVOKE  DosOpen,
                ADDR szSQ,         ;lpDevice � device
                                     name string
                ADDR hSVGA,        ;pass � handle
                                     return value
                ADDR ulAction,     ;dAction return value
                0,                 ;filesize (zero)
                0,                 ;file attribute (zero)
                1,                 ;open flag (open
                                     existing file)
                0000000011000000b, ;open mode
                0                  ;reserved
        or      eax,eax
        jnz     getvram_error
        mov     eax,gsspScreen.pPhysMem
        mov     scrnTx.stx_Address,eax
        mov     eax,gsspScreen.cb
        mov     scrnTx.stx_Size,eax
        mov     scrnTx.stx_flFlag,1
        INVOKE  DosDevIOCtl,
                hSVGA,             ;hDevice
                03h,               ; ulCat
                7eh,               ; ulFunction
                ADDR scrnTx,       ; pParmList
                SIZEOF scrnTx,     ; cbParmList
                0,                 ; plReserved
                ADDR scrnRx,       ; pData
                SIZEOF scrnRx,     ; cbData
                0                  ; plReserved
        mov     ebx,eax            ;save return code
        INVOKE  DosClose, hSVGA
        mov     eax,scrnRx.srx_ScrnPtr
@@:
;/*
;** check return from dosdevioctl call
;*/
        or      ebx,ebx
        jz      getvram_exit
getvram_error:
        mov     eax,0              ;error return
getvram_exit:
        ret

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: ESP, EBP

Registers Destroyed: EAX, EBX, ECX, EDX, ESI, EDI, FLAGS

Invoked From: 

DllLoadProc            (Init.asm)

Routines Called: 

CursorInit             (Cursor2.asm)

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    far_exclude                                           |
|                                                          |
|    void far_exclude(void)                                |
|                                                          |
\----------------------------------------------------------/

Description: Removes the pointer image if the exclusion area of the screen currently includes the pointer.

Entry: 

ECX = X coordinate of left edge
EDX = Y coordinate of top edge
ESI = X coordinate of right edge (inclusive)
EDI = Y coordinate of bottom edge (inclusive)

Return Values: None

Error Returns: None

Registers Preserved: ESP, EBP

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, FLAGS

Invoked From: 

OemBitblt              (Bitblt.asm)
InvertClippedRect      (Celldraw.asm)
OEMDrawBits            (Drawbits.asm)
SaveScreenBits         (Ssb.asm)
OEMStretchBlt          (Strchblt.asm)
output_o_rect          (Strdraw.asm)
Pixel                  (Pixel.asm)
RELDrawBits            (Rlebm.asm)
scanline_device_init   (Scanline.asm)
PolyShartLine          (Shortln.asm)
DrawImageRect          (Cellscan.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine               (Major01.asm)

Routines Called: 

pointer_off            (Pointer.asm)

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    far_unexclude                                         |
|                                                          |
|    void far_unexclude(void)                              |
|                                                          |
\----------------------------------------------------------/

Description: Removes the exclusion rectangle defined by far_exclude. Do not redraw the cursor because it might have to be removed for the next call. Redrawing the pointer is the responsibility of MoveCursor.

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, FLAGS

Registers Preserved: None

Invoked From: 

OemBitblt              (Bitblt.asm)
InvertClippedRect      (Celldraw.asm)
OEMDrawBits            (Drawbits.asm)
SaveScreenBits         (Ssb.asm)
OEMStretchBlt          (Strchblt.asm)
output_o_rect          (Strdraw.asm)
Pixel                  (Pixel.asm)
RELDrawBits            (Rlebm.asm)
scanline_device_init   (Scanline.asm)
PolyShartLine          (Shortln.asm)
DrawImageRect          (Cellscan.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine               (Major01.asm)

Routines Called: None

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    init_hw_regs                                          |
|                                                          |
|    void init_hw_regs(void)                               |
|                                                          |
\----------------------------------------------------------/

Description: Initializes the state required to save and restore the VGA's registers and processor latches, and the default VGA state assumed by the rest of the display driver code. Call this code immediately after the VGA has been programmed for graphics mode and the palette registers set. This code is called at initialization, resurrection, and after a DOS session to ensure a known state of the VGA.

Entry: None

Return values: None

Error Returns: None

Registers Destroyed: EAX, ECX, EDX, FLAGS

Registers Preserved: EBX, ESI, EDI, EBP, ESP

Invoked From: 

physical_enable        (Egainit.asm)
req_controller         (Enter.asm)

Routines Called: 

set_test_locs          (Egastate.asm)
set_misc_regs          (Egastate.asm)

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    physical_disable                                      |
|                                                          |
|    void physical_disable(void)                           |
|                                                          |
\----------------------------------------------------------/

Description: Inhibits all drawing to the screen by the VDD and VDM and PM. physical_disableis called from Death, signifying a switch to a non-PM screen group. physical_disablesaves the physical screen and hardware state .

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: ESI, EDI, EBP, ESP

Registers Destroyed: EAX, EBX, ECS, EDX, FLAGS

Invoked From: 

Death                  (Winattrs.asm)

Routines Called: 

enter_driver_sem_only  (Enter.asm)
leave_driver_sem_only  (Enter.asm)
notify_vdd             (Egainit.asm)
notify_vwin            (Egainit.asm)
save_textvram          (Egainit.asm)

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    physical_enable                                       |
|                                                          |
|    DWORD physical_enable (DWORD fInitMem, DWORD cbDirty) |
|                                                          |
\----------------------------------------------------------/

Description: Enables the appropriate graphics mode. Attempts a fast video ram restore if fInitMemdoes not equal INIT_VRAM.

Entry: fInitMemis a flag set by fill_phys_dev_blkor Resurrection.

A value of 1 indicates original initialization procedures, indicating that screen memory should be initialized to zeros. Any other value indicates restoration from a previously saved state. cbDirtyis the number of VRAM bytes to restore for a fast video restore. physical_enablereceives cbDirtyfrom resurrection. cbDirtyindicates the number of bytes of video RAM damaged since Death. If the amount dirtied is less than the amount saved at Death then a fast video RAM restore is performed.

Ignore this value if fInitMemcontains 1. physical_disablesaves the physical screen and hardware state to improve screen restoration performance. If the screen state remains unchanged at resurrection time, the driver can display a saved state quicker than it can reconstruct and redraw the previous state (fast video ram restore).

Return Values: EAX = 0 if successful

Error Returns: 

EAX = Vio Error code if not successful (EAX <> 0)
      or result of video RAM restoration if fInitMem was FALSE

Registers Preserved: ESI, EDI, EBP, ESP

Registers Destroyed: EAX, EBX, ECX, EDX, FLAGS

Invoked From: 

fill_phys_dev_blk      (Enable.asm)
Resurrection           (Winattrs.asm)

Routines Called: 

Vga32CallBack          (32callbk.asm)
restore_textvram       (Egainit.asm)
init_hw_regs           (Egastate.asm)
notify_vdd             (Egainit.asm)
notify_vwin            (Egainit.asm)

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    Pixel                                                 |
|                                                          |
\----------------------------------------------------------/



LONG Pixel (LONG lX, LONG lY, LONG lPhysColor,
                     LONG lMixMode);



lx:                    x coordinate of pel
ly:                    y coordinate of pel
lPhysColor:            Physical color to set pel to
lMixMode:              Raster operation code or -1 if get pel

Description: Sets a pel to a given color or returns a pel's internal physical color. The physical device may be the screen, or a monochrome or color bit map.

If mix_modeequals -1, Pixel returns the pel's IPC (Internal Physical Color ). If mix_modeis any other value, the value indicates the Raster operation (ROP).

During a set pel operation, Pixel sets the pel to the color that corresponds to the internal physical color indicated in the lPhysColorparameter, combined with the internal physical color of the pel currently at that location. Pixel combines the colors according to the ROP in mix_ mode. Background and clipping are not a consideration.

Entry: 

ESI � DDC
VGA registers in default state

Return Values: EAX = IPC if GetPixelor Positive if SetPixel

Error Returns: EAX = 080000000H

Registers Preserved: ESI, EDI, EBP, ESP

Registers Destroyed: EAX, EBX, ECX, EDX, FLAGS

Invoked From: 

GetPel                 (Pelsup.asm)
SetPel                 (Pelsup.asm)

Routines Called: 

far_exclude            (Cursor2.asm)
far_unexclude          (Cursor2.asm)
ipc_to_index           (Clrconv.asm)

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    PropagateSysClrChange                                 |
|                                                          |
|    void PropagateSysClrChange(void)                      |
|                                                          |
\----------------------------------------------------------/

Description: Called after at least one system color changes. Since the driver has no way of knowing which color changed, it must assume that all system colors have changed. Color table indices 0 and 7 default to certain system colors.

If these system colors change and the default mapping is still in effect, the driver must update the corresponding IPC (internal physical color) from the default color table.

The default mapping is in effect unless the driver explicitly changes it. In that case, DDC_CLR_0_USERS or DDC_CLR_7_USERS is set, as appropriate. The driver must update any attribute bundle that has a system color selected, by marking the IPC as invalid so that it won't be realized again until necessary.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EBX, ECX, EDX, ESI, EDI, EBP, ESP

Registers Destroyed: EAX, FLAGS

Invoked From: 

GetPel                 (Pelsup.asm)
SetPel                 (Pelsup.asm)
DrawBorder             (Drawbord.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine               (Polyline.asm)
Bitblt                 (Winbits . asm ) 
ImageData                 ( Winbits . asm ) 
CharStringPos            ( Winstr . asm ) 
CharMarkerPos            ( Winstr . asm ) 
CharString                ( Winstr . asm ) 
ipc _ to _ index              ( Clrconv . asm ) 
RGBToNearestIndex        ( Colortbl . asm ) 
QueryLogColorTable       ( Colortbl . asm ) 
QueryRGBColor            ( Colortbl . asm ) 
PolyScanline              ( Scanline . asm ) 
PolyShortline            ( Shortln . asm )

Routines Called: None

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    save_bitmap                                           |
|                                                          |
|    void save_bitmap(void)                                |
|                                                          |
\----------------------------------------------------------/

Description: Increments the select count in the bit map.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, ECX, EDX, ESI, EDI, EBP, ESP

Registers Destroyed: EBX, FLAGS

Invoked From: 

save_ddc_state         (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No 



/--- FUNCTION ---------------------------------------------\
|                                                          |
|    save_lct                                              |
|                                                          |
|    void save_lct(void)                                   |
|                                                          |
\----------------------------------------------------------/

Description: Increments the usage count in the logical color table.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP

Registers Destroyed: FLAGS

Invoked From: 

save_ddc_state         (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No


GRE Functions

The following is a list of the functions in the graphics engine that are hooked by the 32-bit VGA display driver.

�Graphics Engine Attribute Functions

�Graphics Engine AVIO Functions

�Graphics Engine Bit-Map Functions

�Graphics Engine Color Table Functions

�Graphics Engine Device Functions

�Graphics Engine Escape Functions

�Graphics Engine Line Functions

�Graphics Engine Marker Functions

�Graphics Engine Miscellaneous Device Functions

�Graphics Engine Miscellaneous Screen Functions

�Graphics Engine Query Functions

�Graphics Engine String Functions

For more information about these functions and their descriptions, see Graphics Engine Functions.


Debugging Support

Debugging support is provided through a macro that sends data through the kernel debugger port to a serial port. The kernel debugger and its related documentation is provided with the Developer's Toolkit for OS/2. By inserting the DebugMsg2<> macro, the supplied string will be routed to the debugging port. 

ifdef FIREWALLS

        DebugMsg2       < This will be printed at the debugging terminal. >

endif ;FIREWALLS

Current debug messages in the code are placed inside the conditional compilation ifdef FIREWALLS. This value is defined when compiling the debug version of the driver.


Thunking

Although the display driver is written in 32-bit flat model, there still is a need to call certain 16-bit routines. To accommodate this need, thunk layerinterfaces are provided. The thunk layer converts 32-bit parameters to 16-bits, and maps linear addresses to segmented addresses. For detailed information about thunking and thunk layers, see the OS/2 Application Design Guide.

Thunk layers are provided for the 16-bit functions listed in the table below, so that they can be available to the 32-bit display driver. 

/-------------------------------------------------------------\
|16-Bit Function         |32-Bit Function from VGA Display    |
|                        |Driver                              |
|------------------------+------------------------------------|
|VIS16REGIONCALLBACK     |Vis32RegionCallBack                 |
|------------------------+------------------------------------|
|GetPmddCodeSelector     |Get32PmddCodeSelector               |
|------------------------+------------------------------------|
|GetScreenSelector       |Get32ScreenSelector                 |
|------------------------+------------------------------------|
|VioGetPhysBuf           |Vio32GetPhysBuf                     |
|------------------------+------------------------------------|
|VioSetState             |Vio32SetState                       |
|------------------------+------------------------------------|
|VioSetMode              |Vio32SetMode                        |
|------------------------+------------------------------------|
|VioGetConfig            |Vio32GetConfig                      |
|------------------------+------------------------------------|
|VioGetPSAddress         |VioGetPSAddress32                   |
|------------------------+------------------------------------|
|FSRSemEnter             |FSRSemEnter32                       |
|------------------------+------------------------------------|
|FSRSemLeave             |FSRSemLeave32                       |
|------------------------+------------------------------------|
|FSRSemExit              |FSRSemExit32                        |
|------------------------+------------------------------------|
|FSRSemCheck             |FSRSemCheck32                       |
\-------------------------------------------------------------/

The 32-bit display driver functions listed in the table below have 16-bit thunk interfaces that are provided to the 16-bit WIN-OS/2 display driver so that it can cooperate with the 32-bit VGA display driver. 

/-------------------------------------------------------------\
|16-bit Functions Called by    |32-Bit Functions in VGA       |
|WIN-OS/2                      |Display Driver                |
|------------------------------+------------------------------|
|far_unexclude16               |far_unexclude                 |
|------------------------------+------------------------------|
|FAR_EXCLUDE16                 |far_exclude                   |
\-------------------------------------------------------------/


32-Bit Super VGA Display Driver

The 32-bit Super VGA display driver, like all display drivers, provides hardware- independence for OS/2 application programs needing to perform I/O to a display device. While the general architecture and functionality of the Super VGA driver are the same as the 32-bit VGA driver, there are differences between the two. This chapter concentrates on those differences . See 32-Bit VGA Display Driverfor detailed information about 32-bit VGA display drivers.


Overview

The 32-bit Super VGA display driver dynamically supports the following chip sets: 

/-------------------------------------------------------------\
|Vendor                  |Chip Set                            |
|------------------------+------------------------------------|
|ATI Technologies, Inc.**|ATI28800                            |
|------------------------+------------------------------------|
|Cirrus Logic, Inc.**    |CL-GD5422 and CL-GD5424             |
|------------------------+------------------------------------|
|Headland Technology,    |HT209 (VRAM II)                     |
|Inc.**                  |                                    |
|------------------------+------------------------------------|
|IBM Corporation         |VGA 256C or SVGA-NI                 |
|------------------------+------------------------------------|
|Trident Microsystems,   |TVGA 8900B and 8900C                |
|Incorporated**          |                                    |
|elink.                  |                                    |
|------------------------+------------------------------------|
|TSENG Laboratories,     |ET4000                              |
|Inc.**                  |                                    |
|------------------------+------------------------------------|
|Western Digital         |WD90C11 (PVGA1C), WD90C30 (PVGA1D), |
|Corporation**           |WD90C31 (in WD90C30 compatibility   |
|                        |mode)                               |
\-------------------------------------------------------------/

The hardware is queried at runtime, and separate code paths for each chip set are taken.

The Super VGA driver supports multiple resolutions for each chip set, including 640 x 480, 800 x 600, and 1024 x 768. Each of these resolutions is supported in 256-color mode. A separate driver is built for each resolution using conditional compilation.

The 32-bit Super VGA display driver also supports several new features:

�OS/2 Presentation Manager (PM) Palette Manager

�Two new background mix options:

-BM_SRCTRANSPARENT
-BM_DESTTRANSPARENT

These new functions permit transparent overlay and transparent underlay of BitBlt operations. See New Background Mix Supportfor details.


32-Bit Super VGA Display Driver Architecture

The 32-bit Super VGA display driver consists of two components: IBMVGA32. DLL and IBMDEV32.DLL. This architecture was chosen to make the driver more easily portable among various hardware video cards. The device-independent functions of the driver are contained in the base DLL, IBMVGA32.DLL; the device-specific functions are contained in the device-specific DLL, IBMDEV32.DLL. In order to be used in the system, individual Super VGA drivers must be renamed to IBMDEV32.DLL when they are built.

The graphics engine calls entry points in both DLLs. The two DLLs also call exported entry points within each other. If you want to port this driver to other video cards, you must write code that supplies the functionality for the entry points in the device-specific DLL. Notice that fonts are now built in the separate DLL called DSPRES.DLL. The following figure shows the 32-bit Super VGA display driver architecture. [Artwork not shown]


Building the 32-Bit Super VGA Display Driver

The supplied display drivers can be built using the NMAKE Utility in the IBM Developer Connection Device Driver Kit for OS/2. (The NMAKE Utility is particularly useful in programs consisting of several source files because it builds only those components that have changed since the program was compiled last.) The following six drivers can be built from the same source set: 



640 x 480    256 colors   Debug version
640 x 480    256 colors   Retail version

800 x 600    256 colors   Debug version
800 x 600    256 colors   Retail version

1024 x 768   256 colors   Debug version
1024 x 768   256 colors   Retail version

Each of the drivers supports all six of the previously-mentioned chip sets. The debug versions of each driver have enabled all code within the ifdef FIREWALLS conditional compilation, which provides some extra error checking and messages through the kernel debugger.

By default, all the drivers are built just by typing the NMAKE command. Individual drivers can be built by passing the following parameters to NMAKE: 



    NMAKE  [vertical resolution].[debug or retail flag]

    for example:

        NMAKE 768.ret
        - builds the 1024 x 768 retail driver.

        NMAKE 600.deb
        - builds the 800 x 600 debug driver.

        NMAKE 480
        - builds both the debug and retail 640 x 480 drivers.

        NMAKE retail
        - builds all resolutions of retail drivers.


New Background Mix Support

The background mix, BM_SRCTRANSPARENT, is used in calls to GpiBitBlt and GpiDrawBits so that pels in a source bit map that match pels in the target presentation space background color are not copied to the output bit map. Where source bit-map pels match the background color, target bit-map pels are left unchanged, which provides a transparent overlay function.

The background mix, BM_DESTTRANSPARENT, also is used in calls to GpiBitBlt and GpiDrawBits, to permit pels from the source bit map to be copied to only the target pels that match the background color of the presentation space. Pels in the target are changed where the source bit-map pels match the background color of the target, thus providing a transparent underlay function.


OS/2 PM Palette Manager Support

The supplied driver supports the OS/2 PM Palette Manager, which is a set of application-level APIs that enable an application to change a video board's palette look-up table. Refer to PM Palette Management Supportfor additional information. The driver must deal with logical color tables ( LCTs), as well as palettes, and must be able to convert between memory- memory, memory-screen, and screen-memory bit maps.

Screen bit-map pelsare physical indexes into the hardware palette, whether you are dealing with a device context (DC)that is using a palette or an LCT.

Memory bit-map pelscan be any of the following:

�Logical indexes into a palette if you are dealing with a DC that is using a palette

�Physical indexes into the device default palette if you are dealing with a DC that is using an LCT

�Physical indexes into the hardware palette if you are dealing with a DC that is using a realizableLCT


SVGA Base Video Subsystem

The base video handler (BVHx) display drivers handle all non-graphical primitive video device functions, such as mode set, palette loading, and all of the text-related functions. Base video handler architecture is described in full detail in Physical Video Device Drivers


Overview

The application interface to take advantage of the base video handler functions is the 16-bit VIO interface, which is also available to 32-bit applications via a thunking layer. Because most of the text-mode related functions are "VGA legacy," there is little need for customizing that part of the base video handler for each new device.

Most of the need for customization comes from the fact that set mode functions are widely different on today's SVGA devices, even across different adapter implementations of the same SVGA chip set. Historically, there was no system support for invoking the real-mode video BIOS for the purposes of the set mode. As a result, customization of the base video handler to handle different SVGA chip sets and their adapter implementations became a norm. The goal then became to externalize the device-specific programming into another 32-bit interface, which was done by the introduction of the VIDEOPMI handler and the SVGADATA.PMI file.

Hence, the SVGA base video handler (BVHSVGA) is a generic driver that imports device-specific functions from VIDEOPMI. VIDEOPMI's interface is also available to any other 16- or 32-bit application. For a full description of the VIDEOPMI's procedural interface, see VIDEOPMI.DLL Exported Functions. For a full description of the PMI subsystem see VIDEO Protect-Mode Interface.

Resolution, monitor, and refresh configuration in OS/2 are standardized and handled by the System icon's first two pages. Monitor and refresh configuration are available for both legacy and DDC-compliant monitors. The function is internally handled by a component called VIDEOCFG. The full specification of the VIDEOCFG's function and exported procedural interface is provided in VIDEOCFG.DLL Exported Functions.

Although most of today's display drivers rely on the VIO subsystem (BVH) to set the mode, that is not mandatory. The new display driver architecture ( GRADD) does use the VIDEOPMI's interface directly. When using VIDEOPMI's interface directly, the display driver is responsible for setting all of the mode parameters (there is a considerable difference in mode parameters between the VIO and VIDEOPMI). In such a case, the display driver has to do the following:

�Invoke VIDEOCFG to retrieve the current configuration

�Transverse the mode table as returned by the VIDEOPMI

�Find the most appropriate entry

�When setting the mode, supply any dynamic mode entry values in the VIDEO_ ADAPTER.MODEINFO structure on the call to VIDEOPMI's PMIREQUEST_SETMODE

Display drivers using the traditional VIO mode set do not need to use VIDEOCFG, provided that their base video support is using the generic IBM BVHSVGA and has externalized the device support via the PMI subsystem.

A display driver vendor may also opt to issue the mode set by using VIDEOPMI's software interrupt services (VIDEO BIOS mode set) without any customization of the PMI subsystem. This approach, however, does not allow for monitor and timing configuration, because VIDEOCFG bases the configuration on the existence of a mode table that includes timing parameters, which is imported from the PMI subsystem . For sample source on how to use VIDEOPMI's software interrupt, see src\oempmi sources and search for PMIREQUEST_SOFTWAREINT. For more specific information on the software interrupt service, see VIDEOPMI.DLL Exported Functionsand VIDEO Protect- Mode Interface.

Note:The PMI subsystem, including the video configurator VIDEOCFG, will run on both OS/2 Warp, Version 3 and the OS/2 2.x base. See Video Subsystem Binary Filesas well as Installing Video Configuration Manager for OS/2in VIDEOCFG.DLL Exported Functions.


How to Customize the PMI Subsystem for Your Device

The VIDEO PMI subsystem consists of VIDEOPMI-the main PMI handler, a flat PMI file, and optional imported library modules. The imported library modules may optionally chain into VIDEOPMI and provide a filter or replacement for VIDEOPMI's entry points. Such a library is called a META- PMI handler. Although the VIDEO PMI subsystem places no requirements on the existence of a flat PMI file (it is possible to provide all functions with a META-PMI handler alone), the SVGA installation, SVGA virtual video driver , BVHSVGA, and VIDEOCFG all make assumptions that the PMI subsystem is represented by SVGADATA.PMI.

With the new feature install (OS/2 Warp, Version 3, PowerPC Edition) and GRADD architecture, these assumptions will be removed; that is, the SVGADATA.PMI file will no longer be assumed to exist. Existing support for flat PMI files remains intact and these files are fully supported as described in VIDEO Protect-Mode Interface.

The VIDEOPMI handler is maintained by IBM; it is shipped in the IBM Developer Connection Device Driver Kit for OS/2as a binary file. See Video Subsystem Binary Files. The SVGADATA.PMI file is either provided or can be created at install time by running a utility. The SVGA installation action routine DLL (SVGA.DLL) assumes that a DOS utility called SVGA.EXE is used to generate the SVGADATA.PMI. A vendor wishing to modify the SVGADATA.PMI can provide its own action routine DLL or create the SVGA.EXE DOS utility. DDK sources include two different sources of a utility that generates the SVGADATA.PMI file, as follows:

�src\svdh\svgautil\svga.exe

src\svdh\svgautil sources are those of the SVGA.EXE as shipped by IBM. It is a very large and complex source that generates a .PMI file for all of the devices supported by the IBM BBS display driver packages at the time the IBM Developer Connection Device Driver Kit for OS/2was shipped.

It is not recommended that vendors modify this source; it is shipped so that vendors can create sample .PMI files for legacy hardware. .PMI files created by this utility use IBMGPMI.DLL as an imported PMI library. The source for IBMGPMI.DLL is not available for vendor modification, but a binary file can be extracted from the most current IBM BBS video driver package. An older version of IBMGPMI can be found in previous DDKs.

For purposes of documenting an imported PMI library, an alternate library source in src\oempmi for OEMPMI.DLL is provided. This PMI library exemplifies both internal PMI calls and the META-PMI interface (chaining into VIDEOPMI). It also provides an example of using the VIDEOPMI's software interrupt API to call the VIDEO BIOS directly.

�src\oempmi\svgautil\svgaoem.exe

src\oempmi\svgautil sources are the recommended sources for vendor modification. The makefile will generate an SVGAOEM.EXE, which should be renamed to SVGA.EXE if the SVGA.DLL action routine DLL is to be used. The utility will create a generic SVGADATA.PMI file based solely on VESA mode support without any vendor modifications. This generic .PMI file depends on the OEMPMI.DLL META-PMI handler, referred to in the previous bullet, for successful VESA BIOS calls. If there is no VESA support for the adapter, or vendors wish to add refresh support or customize the generic sections, the SetupChipInfo function in SVGAOEM.C needs to be modified. The header of the SVGAOEM.C source file includes the "ROADMAP to CHANGES" instructions.

src\oempmi sources are open to vendor modification, and its headers also include extensive instructions on the recommended changes. However, for a vendor with VESA mode set support and a display driver that can run on top of the hardware state as left by the VESA mode set, the quickest results are obtained by doing the following:

-Install all of the Base Video Subsystem files

-Create a .PMI file by running the unmodified SVGAOEM.EXE with command line argument "ON".


Device Detection

Device detection is built into both SCREENx.SYS PDD and SVGA(OEM).EXE. SVGA (OEM).EXE does not need to have device detection added if the generic .PMI file is sufficient. However, as a courtesy to the customer running the drivers and a safeguard against running inappropriate drivers, some device detection should be built into either or both of the modules.

SCREENx.SYS PDD does not have to be modified to add device detection, unless the vendor wishes to use the default .DSC file-selection feature of the display driver installation utility. SVGADEFS.H contains _ADAPTER IDs that are reserved for vendor use for this purpose. For vendors who would like to have a new _ADAPTER ID allocated, a call to DUDE with the request and the name of the vendor is required. When adding device detection to SCREENx.SYS PDD, the allocated ID should be returned. Detection function IdentifySVGA in svgaid.asm is common to both SCREENx.SYS and SVGAOEM.EXE ( SVGA.EXE), with the exception that the PCI detection is invoked only in the PDD, not in the utility. The PCI interface, as used by the SCREENx.SYS, is exported by the OS/2 loader's OEMHLP PDD. Its full interface is documented in inc\pci.inc and samples PCITEST.C and PCITEST.H in src\oempmi. As code is added to SVGAID.ASM, it should be propagated to both SVGA.EXE and SCREENx.SYS PDD. The makefiles will take care of conditional compilation for both modules.


Video Subsystem Binary Files

The following is a complete list of base video modules. Those shipped in their source format, which can be optionally modified, are to be compiled by a vendor and are marked as such. Modules that do not require any vendor modification are also provided because they either did not exist in all of the previous OS/2 versions or they have been upgraded.

�SVGADEFS.H

This is the main header file for SVGA video support. It contains VIDEOPMI's structures and function table, VIDEOCFG structures, and function prototypes . It also contains the SCREEN PDD structures and function numbers, as well as device detection ID lists (Adapters and Chipsets structure). A vendor needs to update this file and add detection to SCREEN PDD only if automatic (machine key) selection of the .DSC file is desired during the display install. If a new device ID needs to be allocated, a request for new ID should be submitted to DUDE.

�SCREEN01.SYS

This is the base video physical device driver. Source can be found on src\ dev\screendd. This driver provides device detection and additional video services, such as linear buffer memory mapping. These services are part of Category 80 IOCTL functions. The list of functions and associated structures can be found in the OS/2 Physical Device Driver Reference, Chapter 11, "General IOCTL Commands" under "Category 80h Screen IOCTL Commands".

PCI processing in this physical device driver is limited only to finding devices of video class and their vendor IDs. For vendors who need to examine more of the PCI header, there is no need to expand this PDD - OEMHLP PDD IOCTLs, which provide the PCI functionality, can be called at ring3. See sample source src\oempmi\pcitest.c.

�BVHSVGA.DLL

The generic SVGA base video handler. This module is provided in source format in src\svdh directory. Modification is not required.

Attention

Do not mix this BVHSVGA with a VIDEOPMI from an older DDK. Some structures in h\svgadefs.h have been expanded; the modules using VIDEOPMI's structures -VIDEOCFG, VIDEOPMI, BVHSVGA and OEMPMI-should all be at the same level.

If a vendor needs to build BVHSVGA compatible with an older VIDEOPMI, a macro, VIDEOPMI_30_LEVEL, should be defined before including h\svgadefs.h and the component should be rebuilt.

�SVGAOEM.EXE

The generic SVGA.EXE utility for creation of an SVGADATA.PMI file. It is provided in source format in src\oempmi\svgautil directory. Modification is not required unless refresh support or a non-generic feature is desired.

�OEMPMI.DLL

A sample imported PMI library. It works with the SVGADATA.PMI file as created by SVGAOEM.EXE. OEMPMI.DLL is provided in source format on src\ oempmi directory. Modification is not required unless a vendor wishes to add refresh support. The source exemplifies the META-PMI chaining as well as usage of VIDEOPMI's software interrupt services.

�VIDEOPMI.DLL

The main PMI handler. Originally just a PMI language interpreter, it is now expanded to handle imported PMI libraries as well as META-PMI chaining. The driver is shipped as a binary file only and can be found in the video\bin directory. This version is the first to provide software interrupt services (calling real-mode BIOS). and should not be mixed with older BVHSVGA, IBMGPMI, or VIDEOCFG, due to changes in some structures in h\svgadefs.h.

�VPRPMI.SYS

A private PMI virtual device driver providing software interrupt services. It should be installed in CONFIG.SYS as DEVICE=X:\OS2\MDOS\VPRPMI.SYS. If a vendor is using software interrupt services, but has to ship its drivers to a customer who prefers to not install DOS support, a private kernel upgrade is available upon request to provide an alternate VDM service. In that case , the VPRPMI.SYS driver is not required. The driver is shipped as a binary file only and can be found in the video\bin directory.

�VIDEOCFG.DLL

The video configurator. This module handles the System icon notebook page 1 and page 2. These pages allow for monitor configuration, resolution and refresh configuration, as well as generic display driver settings configuration. The module is shipped as a binary file in the video\bin directory. The rest of the modules in this list are are support modules for VIDEOCFG.DLL. For a full functional description of VIDEOCFG, see VIDEOCFG.DLL Exported Functions.

Attention

Due to changes in some PMI structures in h\svgadefs.h, this module needs to be at the same level as the VIDEOPMI. As a result, an older VIDEOCFG, when mixed with a new VIDEOPMI, will not generate page 2 and refresh listbox. The same is true when a new VIDEOCFG is mixed with an older VIDEOPMI. Note that resolution dialog should not be affected in either case. No execution exceptions are expected when mixing components, only functional failures.

Note:Prior to the November 1995 IBM Developer Connection Device Driver Kit for OS/2, there was a VIDEOCFG.206 module that represented the 2.x version of VIDEOCFG.DLL. The VIDEOCFG.206 module is no longer needed, because its function has been consolidated into a single VIDEOCFG.DLL. Vendors who have already set up their install procedures to assume the existence of VIDEOCFG.206 should copy VIDEOCFG.DLL as VIDEOCFG.206. Using the older VIDEOCFG.206 will cause the incompatibility problem covered in Attentionabove.

�VCFGMRI.DLL

The resource module for VIDEOCFG.

�WPVIDSYS.DLL

This module is used when installing VIDEOCFG.DLL on OS/2 2.x. It replaces the class of WPSYSTEM in order to transfer ownership of the System icon pages from the Workplace shell to VIDEOCFG.DLL. Required only on 2.x. The subclassing becomes active only after this module is installed and the system is rebooted. The binary file is available in the video\bin directory .

�VCFGINST.EXE

This module is used to install WPVIDSYS.DLL on OS/2 2.x. VIDEOCFG.DLL will not be active on 2.x unless this utility is executed, WPVIDYS.DLL and VIDEOCFG.DLL are in the LIBPATH, and the system is rebooted following the execution of the utility. The binary file is available in the video\bin directory.

�MONITOR.DIF

The monitor database. This flat file contains timing descriptions for a large percentage of today's non-DDC-compliant monitors. The timings were obtained from the manufacturers' user manuals, and are not guaranteed to be correct or the most optimal. The entries can be added to or edited and, if new entries are submitted to the DUDE, they will be added to the master copy of the MONITOR.DIF. For vendors doing SID or RIPL install, new entries also can be placed in PRIVATE.DIF, which would leave MONITOR.DIF as read-only. MONITOR.DIF is available in the video\bin directory and should be placed into DPATH.


Physical Video Device Drivers

Video devices are accessed by using Base Video Handlers (BVHs). These BVHs consist of one or more Dynamic Link Libraries (DLLs). In the representative case of the VGA, BVHVGA.DLL manages the device for full-screen sessions, while DISPLAY.DLL (renamed from IBMVGA.DLL) manages the device for the Presentation Manager interface. Although these device handlers are initialized by different sections of the system at this time, they are architecturally compatible and can easily be combined at a later date.


Video Device Handler Identification

The list of the active video device handlers and their components resides in the CONFIG.SYS file as environment variables. To conserve environment space, these variables are removed from the environment during Shell Initialization. The VIDEO_DEVICES environment variable lists the names of the environment variables that describe each of the video device handlers. Commas are used to separate the names in this list. The following is an example of how to specify the environment variables ARTICHOKE and WATERMELON as those defining the active video device handlers, with ARTICHOKE used as configuration number one, and WATERMELON used as configuration number two. 



      SET VIDEO_DEVICES=ARTICHOKE,WATERMELON

The value of each environment variable that describes a video device handler is composed of three keywords and the values associated with them. These keywords are separated by blanks and can be specified in any order and in any combination of upper and lower case characters. The DEVICE() keyword defines the list of names of the dynamic link libraries and physical device drivers which are combined to create the video device handler. The names are separated by commas, and their order determines the order in which the components will be initialized. These names represent only those parts of the BVH that need to be called to initialize the Call Vector Table. That is, physical device drivers should not be included in the list if they are only called by the dynamic link libraries and do not directly modify the Call Vector Table.

The default initialization entry point name for the dynamic link libraries is DEVENABLE. An alternate entry point name can be specified by following any DLL name with +AltName, where AltName is the entry point name.

The default initialization IOCtl for physical device drivers is Function 73h. An alternate function number and category can be specified by following the device name by +Func+Cat, where "Func" is the function number and "Cat" is the category. Both numbers must be specified in hexadecimal form. For details, see Function 73h under "Physical Device Driver Initialization" later in this chapter.

The following is an example of a device handler that is composed of two physical device drivers, DEV1 and DEV2, and three dynamic link libraries, DYN1 through DYN3. The second physical device driver uses an alternate initialization IOCtl and the third dynamic link library uses an alternate initialization entry point. POINTER$ is the default physical pointer device driver. 

      SET ARTICHOKE=DEVICE(DEV1,DYN1,DEV2+74+05,DYN2,DYN3+OTHERENT)

DosOpenis called for each name in the list to check if it is a device driver with an associated "DEVICE=" statement in the CONFIG.SYS file. If the call fails, DosLoadModuleis called to check if it is a dynamic link library. If both of these calls fail for any name in the list, the entire device is ignored.

If the optional PTRDEVP() keyword is specified, it defines the names of the physical pointer device drivers. If it is not specified, it defaults to PTRDEVP(POINTER$). The following is an example of a device with only one dynamic link library component and a unique physical pointer device driver for protect mode. 

      SET WATERMELON=DEVICE(SEEDLESS) PTRDEVP(PPOINT)

Note:This design is not limited strictly to physical video devices. By writing a device handler, video data could be written to any device, such as a printer or a plotter. In addition, by using alternate initialization entry points, multiple devices can be handled by the same physical device handler.

All of the video device handlers shipped with OS/2 2.1 are dynamic link libraries. They can be defined by the following environment variables, which use the default keywords of PTRDEVP(POINTER$) and PTRDEVR(POINTER$). 

      SET VIO_IBMMPA=DEVICE(BVHMPA)
      SET VIO_IBMCGA=DEVICE(BVHCGA)
      SET VIO_IBMEGA=DEVICE(BVHEGA)
      SET VIO_IBMVGA=DEVICE(BVHVGA)
      SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)
      SET VIO_IBM8514A=DEVICE(BVH8514A)
      SET VIO_IBMXGA=DEVICE(BVHXGA)

The following statements define a system with an 8514 display attached to an 8514/A as the only active video device: 

      SET VIDEO_DEVICES=VIO_IBM8514A
      SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)

However, the statement below defines a system with an 8514 display attached to an 8514/A, and another PS/2* display attached to the VGA connector, as independent video devices. 

      SET VIDEO_DEVICES=VIO_IBMVGA,VIO_IBM8514A
      SET VIO_IBMVGA=DEVICE(BVHVGA)
      SET VIO_IBM8514A=DEVICE(BVH8514A)

Two other device handlers are provided with OS/2. The names of these device drivers are fixed. The Base Video Subsystem loads them automatically as they are needed.

BVHINIT.DLL is the generic device handler used by system installation and system initialization. It provides the minimum function necessary to support installation of the system and reporting of system errors during startup. It is loaded only if no other BVHs are successfully loaded.

BVHWNDW.DLL is the device handler that can support VIO window sessions and that provides the interface to the Presentation Manager interface by treating the PM interface as a virtual video device driver. BVHWNDW.DLL is loaded only for VIO window sessions.

Video Device Chaining

Video device handlers (BVHs) can be chained together when multiple BVHs share the responsibility of supporting a specific video adapter. This is accomplished by allowing previously loaded BVHs to attempt the handling of BVH functions. BVH8514A and BVHXGA are chained BVHs shipped with the product that provides this support.


A VGA and 8514A Scenario

During system initialization, BVHVGA is first called to initialize the Call Vector Table, that is, the table used by BVS to give control to the BVH routines. BVHVGA functions as though no other BVH will be handling the device. Next, BVH8514A is called to initialize the same Call Vector Table. However, BVH8514A saves a copy of the Call Vector Table before changing it.

When calls are made to this chained BVH, BVH8514A receives the call and passes it to the BVHVGA routine through the saved Call Vector Table. If an error occurs or if the results of the routine need to be modified, BVH8514A handles the call. Thus, BVH8514A uses the BVHVGA routines to perform all common functions. Device chainingcan be viewed as a mechanism to allow one BVH to filter function calls to another BVH.


Primary Display Identification

The primary display is the default display chosen by VIO for full-screen sessions. It is also the display on which VIO and hard error pop-ups are shown. Notice that the primary display used by VIO is not necessarily the display on which the Presentation Manager environment runs. The Presentation Manager interface normally runs on the highest resolution display. In a dual-display configuration, the highest resolution display is not necessarily a display that can be used in text mode.

The primary display is the pop-up display. A physical video device driver must determine if it represents the pop-up display. If so, the video device driver must specify that it represents the pop-up display configuration in Query Config Info.


WrtToScrn/Panic Write Support

Before the video subsystem is loaded, and when the system is about to abnormally terminate, messages are sent to the screen by the WrtToScrnfunction, also known as Panic Write. This function switches to real mode and executes the INT 10h function to set the video mode to a text mode ( BIOS mode 3). It then uses BIOS INT 10h, "Write TTY", to display the message.

However, adapters such as the 8514/A have native modes that cannot be changed by INT 10h. In such cases, the BVH must include a Level 0 device driver that hooks INT 10h to provide extended set mode support. This hook must force the adapter out of its native mode, and then pass control to the previous INT 10h support. If these conditions are not satisfied, the adapter should not drive the power up display.


System Installation

The generic device handler, BVHINIT.DLL, is used primarily by system installation. It is also used for those situations when video devices have not been identified in the CONFIG.SYS file. It provides only the functions required for system installation and is otherwise device-independent.

Through VioGetConfigBVHINIT.DLL reports the highest function video adapter and display it can identify. It can identify only the MPA, CGA, EGA, VGA, 8514A, and XGA, along with their respective displays. Although it does not support mode and font setting, it attempts to load the 850 code page for the current EGA or VGA mode during system initialization.

If video devices have not been identified in the CONFIG.SYS file, the generic device handler attempts to load each of the following devices, until one is successfully loaded: 

        GENERIC=DEVICE(BVHVGA,BVH8514A)
        GENERIC=DEVICE(BVHVGA)
        GENERIC=DEVICE(BVHEGA)
        GENERIC=DEVICE(BVHCGA)
        GENERIC=DEVICE(BVHINIT)


Loadable Device Drivers

Loadable device drivers present a unique problem when used to support video devices because some video support can be required before the DEVICE= statements have been processed by system initialization. To handle this problem, two different initialization calls are made.

The Enable subfunction determines which type of initialization is to be done. If the subfunction is 1 (Fill Logical Device Block), the DevEnablefunction is requested to add all of the functions supported by the device handler to the Call Vector Table. If the subfunction is 3 (Fill Initialization Device Block), the InitEnablefunction is requested to add only those functions, that can be supported without the use of a loadable device driver to the Call Vector Table.

Regardless of the success of the InitEnablefunction, the DevEnablefunction is called at Shell Initialization time. See DevEnable, and InitEnablefor more information.


Video Device Handler Interfaces

The functions that follow are video primitives reserved for use by OS/2 system components. Unexpected results can occur if these functions are started by applications. All of the video device handler functions described below (except for the DLL Initialization function) use the same calling sequence. Parameters are passed to the routines on the stack. The entry point is found in the BVH Call Vector Table at the index of the function number. The calling sequence used to invoke all the routines is as follows: 

     PUSH@    OTHER    Environment        ; Environment buffer
     PUSH@    OTHER    ParmBlock          ; Parameter block
     PUSH     DWORD    Function           ; Function number

     CALL     FAR      BVH Routine Entry Point

Environment:

The environment buffer. The format of this buffer is defined by the BVH developer. The selector is a huge selector.

ParmBlock:

A data structure containing all of the parameters of the operation to be performed. The general format of this structure is: 

    Length of parameter block in bytes (=NN)  WORD
    Flags                                     WORD

    Bit 0 indicates whether the physical hardware is updated.

        OFF = Initialize only the environment buffer
        ON  = Initialize the environment buffer and the hardware state

    Bits 1 through 15 are reserved and must be OFF.

The length of the parameter block is the total length, including the length field itself. The number in parentheses ( =NN ) represents the value of this field, if it is a constant.

The first flag bit always indicates a background versus foreground state for this function. If the bit is ON, the adapter is actually updated, as it is when an application is in the foreground. If the bit is OFF, only the buffer that is used to shadow the adapter when an application is in the background is actually updated. All bits that are not currently defined as reserved must be OFF.

Function:

The function identifier for this routine. This corresponds to the offset into the Call Vector Table, and can be used to determine the number of parameters on the stack. This is consistent with the existing DDI used by the Presentation Manager interface. All routines are expected to return with AX = 0 if no error was detected. Otherwise, an error code is returned in AX. The following errors are common to all commands: 

    ERROR_VIO_INVALID_LENGTH, if the parameter block length is incorrect.
    ERROR_VIO_INVALID_PARMS,  if a reserved flag bit is non-zero, or if
                              the function number does not match the routine.


DevEnable

This function fills the entries in the Call Vector Table for all of the functions supported by this BVH. It is called as a subfunction of the Presentation Manager enable function entry point. To initialize the Call Vector Table for dynamic link libraries: 

    PUSH  DWORD   Parameter2    ; Variable parameter 2
    PUSH  DWORD   Parameter1    ; Variable parameter 1
    PUSH  DWORD   Subfunction   ; Enable subfunction

    CALL  FAR     DevEnable

Parameters

Parameter2 for Subfunction=1

A far pointer to this structure: 

    DWORD   Flags Pointer
    DWORD   Call Vector Table

Flags Pointer

Pointer to where the flags that control calls to the Fill Physical Device Block function go.

Call Vector Table

Pointer to the default dispatch table containing the addresses of the default handler functions and the functions supported by this component. Each entry in the Call Vector Table is the far address of a Video Device Handler function, which must be callable from both Ring 2 and Ring 3. The far address of the nth BVH function is the nth DWORD in the table, beginning with Function 0.

The functions listed below are defined as follows:

000h-0FFh (000-255) Reserved for Presentation Manager interface

100h-11Fh (256-287) Reserved for BVS

120h-12Fh (288-303) Reserved for IBM JAPAN

130h-13Fh (304-319) Reserved for MSKK

100h (256) Function 100hText Buffer Update

101h (257) Function 101hInitialize Environment

102h (258) Function 102hSave Environment

103h (259) Function 103hRestore Environment

104h (260) Function 104hQuery Config Info

105h (261) Function 105hDBCS Display Info

106H (262) Function 106hQuery Color Lookup Table

107H (263) Function 107hSet Color Lookup Table

108H (264) Function 108hQuery Cursor Info

109H (265) Function 109hSet Cursor Info

10AH (266) Function 10AhQuery Font

10BH (267) Function 10BhSet Font

10CH (268) Function 10ChQuery Mode

10DH (269) Function 10DhSet Mode

10EH (270) Function 10EhQuery Palette Registers

10Fh (271) Function 10FhSet Palette Registers

110H (272) Function 110hQuery Physical Buffer

111H (273) Function 111hFree Physical Buffer

112H (274) Function 112hQuery Variable Info

113H (275) Function 113hSet Variable Info

114H (276) Function 114hTerminate Environment

115H (277) Function 115hPrint Screen

116H (278) Function 116hWrite TTY

117H (279) Function 117hQuery LVB Info
Parameter1 for Subfunction=1

Far pointer to this structure: 

    DWORD   Engine Version
    DWORD   Count of Table Functions

Engine Version

Version of the Presentation Manager Graphics Engine.

Count of Table Functions

The number of entries in the passed dispatch table. The driver can write only this many entries into the table.

Subfunction

The Presentation Manager enable subfunction number. Its value must be 1 to start the Presentation Manager Fill Logical Device Block subfunction. All pieces of the BVH must support this function. Pieces of the BVH that do not support the Presentation Manager interface do not need to support the other functions. Any function not supported will return PMERR_DEV_FUNC_NOT_INSTALLED.

Remarks

This function is supported by the video dynamic link functions and is called only once for each adapter supported by the physical device driver. A video device handler determines if the display adapter and that which the adapter supports is present. If not present, this function returns an error . Every part of a BVH must successfully initialize the Call Vector Table for that device to be usable by the OS/2 operating system.


InitEnable

This function fills the entries in the Call Vector Table for all of the functions supported by this BVH using only SCREEN$ device driver. It is called with parameters similar to the DevEnableentry point specified in DevEnable, except for the Subfunction parameter.

To initialize the Call Vector Table for dynamic link libraries: 

    PUSH  DWORD   Parameter2    ; Variable parameter 2
    PUSH  DWORD   Parameter1    ; Variable parameter 1
    PUSH  DWORD   Subfunction   ; Enable subfunction

    CALL  FAR     InitEnable

Parameters

Parameter2 for Subfunction=3

See DevEnable.

Parameter1 for Subfunction=

See DevEnable. Subfunction is the Presentation Manager enable subfunction number. Its value must be 3 to start the Presentation Manager Fill Initialization Device Block subfunction. The default entry point of DevEnablecan be overridden by specifying an alternate name in the DEVICE() parameter describing this BVH in the CONFIG.SYS file.

Remarks

This function is called only if video functions are required before Shell Initialization.

The BVH must be able to support the following subfunctions:

100h (256) Function 100hText Buffer Update

101h (257) Function 101hInitialize Environment

102h (258) Function 102hSave Environment (settable environment only)

103h (259) Function 103hRestore Environment (settable environment only)

104h (260) Function 104hQuery Config Info

105h (261) Function 105hDBCS Display Info

108H (264) Function 108hQuery Cursor Info

109H (265) Function 109hSet Cursor Info

10CH (268) Function 10ChQuery Mode (80x25 text or equivalent only)

10DH (269) Function 10DhSet Mode (80x25 text or equivalent only)

112H (274) Function 112hQuery Variable Info (code page only)

113H (275) Function 113hSet Variable Info (code page only)

See DevEnable.


Text Buffer Update - Function 100h

Category:

Function:
100h
Description:
Text Buffer Update

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function performs text updates to the logical and physical video buffers. All references to the buffer are made through the text row and column of each cell affected by the called function.


Function 100h - Description

This function performs text updates to the logical and physical video buffers. All references to the buffer are made through the text row and column of each cell affected by the called function.


Function 100h - Parmlength

Parmlength

Length of the data structure in bytes (greater than, or equal to, 26), including the Lengthfield itself. The maximum length is 44 bytes. Values not passed are assumed to be the default values for the environment.


Function 100h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical video buffer needs to be updated.

      OFF = The physical video buffer must not be updated.
      ON  = The physical video buffer must be updated.

Bit 1 indicates whether the logical video buffer needs to be updated.

      OFF = The logical video buffer may optionally be updated.
      ON  = The logical video buffer must be updated.

Bit 2 indicates that attribute information in the user buffer is in CGA
format and might need to be translated into the format used by the device.
This bit is set for VioWrtTTY calls any time that ANSI is active, because
ANSI recognizes only CGA format attributes.

      OFF = Use attributes in existing format.
      ON  = Translation to or from CGA format required.

Bits 3-15 are reserved and must be OFF.




Function 100h - Selector/Offset of the Application Data Area

Selector/Offset of the Application Data Area

Pointer to the application's data area, which provides either the source or the destination for the buffer operation.


Function 100h - Selector/Offset of the Secondary Data Area

Selector/Offset of the Secondary Data AreaPointer to the additional parameter required by this type of update operation. It is used to define, at most, one cell of information that is used repetitively as filler. This is used only with Index = 3, 4, 5, 6, or 9.


Function 100h - Index

Index

Defined as follows: 



     0 = Read Cell Types from (Row,Col) as word of flags:

         Bit 0 indicates whether the cell is part of a single or
               double cell character.

               OFF = The cell represents a single cell character.
               ON  = The cell represents part of a double cell
                       character.  Bit 1 is examined for more
                       information.

         Bit 1 indicates whether the cell is a trailing cell of
               a double cell character.

               OFF = The cell represents the leading or only cell of a
                       character.
               ON  = The cell represents the trailing cell of a double
                       cell character.

         Bits 2 thru 15 are reserved and must be OFF.

     1 = Read Characters from (Row,Col)
     2 = Read Cells from (Row,Col)
     3 = Scroll (Row,Col) through (Row2,Col2) Up
     4 = Scroll (Row,Col) through (Row2,Col2) Down
     5 = Scroll (Row,Col) through (Row2,Col2) Left
     6 = Scroll (Row,Col) through (Row2,Col2) Right
     7 = Write Cells to (Row,Col)
     8 = Write Characters to (Row,Col)
     9 = Write Characters with Constant Attr to (Row,Col)
    10 = Write Repeated Character to (Row,Col)
    11 = Write Repeated Attribute to (Row,Col)
    12 = Write Repeated Cell to (Row,Col)
    13 = Copy LVB Rect to PVB




Function 100h - Starting Row

Starting Row

Defines the text location (row) in the Video Buffer at which the update is to be started. For Function 13, this is the upper-left corner of the rectangle to be written.


Function 100h - Starting Column

Starting Column

Defines the text location (column) in the Video Buffer at which the update is to be started. For Function 13, this is the upper-left corner of the rectangle to be written.


Function 100h - Secondary Row

Secondary Row

Defines the text location (row) in the Video Buffer to which cells will be moved. This is used only when moving cells from one location to another ( Index=3-6). For Function 13, this is the lower-right corner of the rectangle to be written.


Function 100h - Secondary Column

Secondary Column

Defines the text location (column) in the Video Buffer to which cells will be moved. This is used only when moving cells from one location to another (Index=3-6). For Function 13, this is the lower-right corner of the rectangle to be written.


Function 100h - Repeat Factor

Repeat Factor

Repeat factor used when updating the buffer. It represents the number of character cells to be updated, or the number of rows or columns to be scrolled. This is used for both input and output.


Function 100h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.


Function 100h - TouchXLeft

TouchXLeft

The X-coordinate of the upper-left corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched (as in a Read), -1 is returned. Collectively, this field and the next three fields form an area of influence for the call. This field is returned by the BVH.


Function 100h - TouchYTop

TouchYTop

The Y-coordinate of the upper-left corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched, -1 is returned. This field is returned by the BVH.


Function 100h - TouchXRight

TouchXRight

The X-coordinate of the lower-right corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched, -1 is returned. This field is returned by the BVH.


Function 100h - TouchYBottom

TouchYBottom

The Y-coordinate of the lower-right corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched, -1 is returned. This field is returned by the BVH.


Function 100h - LVBRowOff

LVBRowOff

The row offset of the upper-left corner of the LVB in PVB coordinates. All reads, writes, and scrolls are done in PVB coordinates.


Function 100h - LVBColOff

LVBColOff

The column offset of the upper-left corner of the LVB in PVB coordinates. All reads, writes, and scrolls are done in PVB coordinates.


Function 100h - LVBWidth

LVBWidth

The width of the LVB in cells. Must be greater than 0.


Function 100h - LVBHeight

LVBHeight

The height of the LVB in cells. Must be greater than 0.


Function 100h - LVBFormatID

LVBFormatID

The format ID of the LVB. If this value and attribute count are both 0, the Format ID and attribute count for the current mode are used.


Function 100h - LVBAttrCount

LVBAttrCount

The attribute count for the LVB.


Function 100h - Parameter Packet Format



/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Selector/Offset of the         DWORD     |
|Application Data Area                    |
|-----------------------------------------|
|Selector/Offset of the         DWORD     |
|Secondary Data Area                      |
|-----------------------------------------|
|Index                          WORD      |
|-----------------------------------------|
|Starting Row                   WORD      |
|-----------------------------------------|
|Starting Column                WORD      |
|-----------------------------------------|
|Secondary Row                  WORD      |
|-----------------------------------------|
|Secondary Column               WORD      |
|-----------------------------------------|
|Repeat Factor                  WORD      |
|-----------------------------------------|
|Logical Buffer Selector        WORD      |
|-----------------------------------------|
|TouchXLeft                     WORD      |
|-----------------------------------------|
|TouchYTop                      WORD      |
|-----------------------------------------|
|TouchXRight                    WORD      |
|-----------------------------------------|
|TouchYBottom                   WORD      |
|-----------------------------------------|
|LVBRowOff                      WORD      |
|-----------------------------------------|
|LVBColOff                      WORD      |
|-----------------------------------------|
|LVBWidth                       WORD      |
|-----------------------------------------|
|LVBHeight                      WORD      |
|-----------------------------------------|
|LVBFormatID                    BYTE      |
|-----------------------------------------|
|LVBAttrCount                   BYTE      |
\-----------------------------------------/


Function 100h - Returns

The Text Buffer Update routine returns with AX = 0, if no error was detected. Otherwise, the following error codes are returned in AX: 



    ERROR_VIO_COL,              if an invalid column number was specified
    ERROR_VIO_INVALID_LENGTH,   if the ParmLength was incorrect
    ERROR_VIO_INVALID_PARMS,    if the Index was incorrect
    ERROR_VIO_MODE,             if updates are not supported in the
                                  current video mode
    ERROR_VIO_ROW,              if an invalid row number was specified.


Function 100h - Remarks

The Touchxxxxfields circumscribe the area of the LVB, or PVB, for a rectangle that was potentially changed by the given operation. For example, a Write that included the cells (10,12) to (79,12), (0,13) to (79,13), and (0,14) to (8,14) returns TouchXLeft=0, TouchYTop=12, TouchXRight=79, and TouchYBottom=14. Any new functions added to the BVH interface that can affect the data in the PVB or LVB must include a return area for the rectangle of the video buffer that was affected by the given call.

The LVBxxxxfields indicate that an LVB can differ from the normal LVB format. The information about the LVB is taken from these fields, if they are included. Notice that these fields allow an LVB to begin at a location other than (0,0) and allow LVBs of different row and column dimensions.


Function 100h -

Category:

Function:
100h
Description:
Text Buffer Update

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Initialize Environment - Function 101h

Category:

Function:
101h
Description:
Initialize Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function causes the Environment Buffer and the video adapter (optional ) to be initialized.


Function 101h - Description

This function causes the Environment Buffer and the video adapter (optional ) to be initialized.


Function 101h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.


Function 101h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware is
      updated.

      OFF = Initialize only the environment buffer.
      ON  = Initialize the environment buffer and the
            hardware state.

Bit 1 indicates whether the 3xBox is being
      initialized.

      OFF = The 3xBox is not being initialized.
      ON  = The 3xBox is being initialized.

Bits 2 thru 15 are reserved and must be OFF.




Function 101h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.


Function 101h - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/


Function 101h - Returns

This routine always returns with AX = 0.


Function 101h - Remarks

It must be possible to call Restore Environment before Save Environment.


Function 101h -

Category:

Function:
101h
Description:
Initialize Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Save Environment - Function 102h

Category:

Function:
102h
Description:
Save Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function is used to save all aspects of the video adapter, including the hardware state and the video buffers.


Function 102h - Description

This function is used to save all aspects of the video adapter, including the hardware state and the video buffers.


Function 102h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.


Function 102h - Flags

Flags

Defined as follows: 

Bit 0 is reserved and must be Off.

Bit 1 indicates whether hardware state (mode,
      CLUT, everything except the buffer) is saved.

      OFF = The hardware state is not saved.
      ON  = The hardware state is saved.

Bit 2 indicates whether the physical display
      is fully saved for session switching.

      OFF = The physical display is not fully saved.
      ON  = The physical display is fully saved.

Bit 3 indicates whether the physical display
      is partially saved for pop-ups.

      OFF = The physical display is not partially saved.
      ON  = The physical display is partially saved.

Bits 4 thru 15 are reserved and must be OFF.




Function 102h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.


Function 102h - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/


Function 102h - Returns

The Save Environment routine returns with AX = 0 if it can successfully save the environment to the Environment Block and the Logical Video Buffer. Otherwise, it returns with AX = ERROR_VIO_MODE.


Function 102h - Remarks

Bits 2 and 3 are mutually exclusive. If both are specified, bit 3 will be ignored. Bit 4 is used in combination with bits 2 and 3. The code and data segments referenced or accessed to perform the functions selected by bits 1 and 3 must be locked during device driver initialization. The format of the data saved in the segments passed as input is determined by the device handler.

Partial saves are started on VIO and hard error pop-ups. Pop-ups appear on the primary display configuration. The device driver must save whatever portion of the physical display buffer that is overlaid by the pop-up. To display a pop-up, OS/2 2.1 switches to the highest resolution 80 x 25 text mode supported by the primary display configuration (mode 3 or 7, whichever is listed first in the list of modes supported by the display configuration ). Alternatively, if a device driver's physical display buffer is not overlaid by a pop-up, the physical device driver returns zero for partial save size.

When a hard error pop-up occurs before a VIO pop-up has cleared, the Save Environment function is called twice before the Restore Environment is called. Therefore, the device handler must be prepared to handle both a partial save of a graphics mode and a full save of the text mode of the user pop-up.

OS/2 allocates the buffer in which the physical display buffer is saved by using DosAllocHuge. The selector to the Data Packet addresses the first of nsegments in which the physical display buffer is saved. (The offset to the Data Packet should be ignored.) The selector to the second segment can be calculated by adding the DosAllocHugeincrement to the first selector value. The third selector can similarly be calculated by adding the DosAllocHugeincrement to the second selector value, and so forth. Enough selectors are allocated to meet the full/partial buffer requirement specified by the physical device driver. The selectors each address 64KB except the last selector, which addresses the remainder.

Function 102h -

Category:

Function:
102h
Description:
Save Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Restore Environment - Function 103h

Category:

Function:
103h
Description:
Restore Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function is used to restore all aspects of the video adapter, including the hardware state and the video buffers.


Function 103h - Description

This function is used to restore all aspects of the video adapter, including the hardware state and the video buffers.


Function 103h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.


Function 103h - Flags

Flags

Defined as follows: 

Bit 0 is reserved and must be Off.

Bit 1 indicates whether hardware state (mode,
      CLUT, everything except the buffer) is saved.

      OFF = The hardware state is not restored.
      ON  = The hardware state is restored.

Bit 2 indicates whether the physical display
      is fully restored for session switching.

      OFF = The physical display is not fully restored.
      ON  = The physical display is fully restored.

Bit 3 indicates whether the physical display
      is partially restored for pop-ups.

      OFF = The physical display is not partially restored.
      ON  = The physical display is partially restored.

Bits 4 thru 15 are reserved and must be OFF.




Function 103h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.


Function 103h - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/


Function 103h - Returns

The Restore Environment routine returns with AX = 0 if it can successfully restore the environment to the Environment Block and the Logical Video Buffer. Otherwise, it returns with AX = ERROR_VIO_MODE. See Function 102hfor more information.


Function 103h - Remarks

None.


Function 103h -

Category:

Function:
103h
Description:
Restore Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Query Config Info - Function 104h

Category:

Function:
104h
Description:
Query Config Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function returns all of the information necessary to identify the current video adapter and display.


Function 104h - Description

This function returns all of the information necessary to identify the current video adapter and display.


Function 104h - Parmlength

Parmlength

Length of parameter block in bytes (=8) passed on input.


Function 104h - Flags

Flags

Must be zero.


Function 104h - Parameter Packet Format



/-------------------------\
|Field          Length    |
|-------------------------|
|Parmlength     WORD      |
|-------------------------|
|Flags          WORD      |
\-------------------------/


Function 104h - Returns

This function returns with AX = ERROR_VIO_INVALID_LENGTH only if the Length specified is less than 2.


Function 104h - Remarks

The Environment Buffer is not used by this function. The Environment Buffer address is passed as a DWORD of zero. If the Length specified in the Config Data is larger than the maximum possible length, or if the Length is specified as 2 (the length of Length field itself), it is replaced by the largest valid length.


Function 104h -

Category:

Function:
104h
Description:
Query Config Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


DBCS Display Info - Function 105h

Category:

Function:
105h
Description:
DBCS Display Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function returns various forms of DBCS information used by the display .


Function 105h - Description

This function returns various forms of DBCS information used by the display .


Function 105h - Parmlength

Parmlength

Length of parameter block in bytes. If Length is specified as 2, only the maximum length of the parameter block is returned in the length field. If the length is not 2, it defines the maximum amount of data returned.


Function 105h - Flags

Flags

Must be zero.


Function 105h - DBCS Table Length

DBCS Table Length

Length of double cell character table.


Function 105h - DBCS Table Offset

DBCS Table Offset

Offset of double-cell character table, which consists of WORD pairs that define the low and high limits (inclusive) of ranges of double-cell characters.


Function 105h - Parameter Packet Format



/--------------------------------\
|Field                 Length    |
|--------------------------------|
|Parmlength            WORD      |
|--------------------------------|
|Flags                 WORD      |
|--------------------------------|
|DBCS Table Length     WORD      |
|--------------------------------|
|DBCS Table Offset     WORD      |
\--------------------------------/


Function 105h - Returns

This function is used to get the DBCS display information associated with the given environment buffer, and returns with AX = ERROR_VIO_INVALID_ LENGTH if the Length specified is less than 2 or the buffer was too short to return all of the DBCS display information. Otherwise, Query DBCS Display Info returns with AX = 0.


Function 105h - Remarks

None.


Function 105h -

Category:

Function:
105h
Description:
DBCS Display Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Query Color Lookup Table - Function 106h

Category:

Function:
106h
Description:
Query Color Lookup Table

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function reads the definitions of the colors from the Color Lookup Table.


Function 106h - Description

This function reads the definitions of the colors from the Color Lookup Table.


Function 106h - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.


Function 106h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bits 1-15 are reserved and must be OFF.




Function 106h - Color Lookup Table Far Address

Color Lookup Table Far Address

Far address of Color Lookup Table. The Table format is device-dependent. Three-byte table entries are returned for the VGA. Each table entry contains a red, green, and blue color index, respectively.


Function 106h - Index

Index

Index of the first table entry to get.


Function 106h - Table Entry Quantity

Table Entry Quantity

Number of table entries to get. Three-byte table entries are returned for the VGA. Each table entry contains a red, green, and blue color index, respectively.


Function 106h - Parameter Packet Format



/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Color Lookup Table Far Address DWORD     |
|-----------------------------------------|
|Index                          WORD      |
|-----------------------------------------|
|Table Entry Quantity           WORD      |
\-----------------------------------------/


Function 106h - Returns

This function returns with AX = 0 if it can successfully get all of the requested registers from the Color Lookup Table. Otherwise, this routine returns with AX = ERROR_VIO_INVALID_PARMS if an invalid color register was requested, or AX = ERROR_VIO_INVALID_LENGTH if too many registers were requested.

Function 106h - Remarks

None.

Function 106h -

Category:

Function:
106h
Description:
Query Color Lookup Table

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

Set Color Lookup Table - Function 107h

Category:

Function:
107h
Description:
Set Color Lookup Table

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function loads the definitions of the colors from the Color Lookup Table.

Function 107h - Description

This function loads the definitions of the colors from the Color Lookup Table.

Function 107h - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.

Function 107h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware is
      updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bits 1-15 are reserved and must be OFF.

Function 107h - Color Lookup Table Far Address

Color Lookup Table Far Address

Far address of Color Lookup Table. The Table format is device-dependent. The VGA format has three bytes containing the red, green and blue indices, respectively, for each color being set.

Function 107h - Index

Index

Index of the first table entry to set.

Function 107h - Table Entry Quantity

Table Entry Quantity

Number of table entries to set.

Function 107h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Color Lookup Table Far Address DWORD     |
|-----------------------------------------|
|Index                          WORD      |
|-----------------------------------------|
|Table Entry Quantity           WORD      |
\-----------------------------------------/


Function 107h - Returns

This function returns with AX = 0 if it can successfully set all of the registers in the Color Lookup Table. Otherwise, it returns with AX = ERROR_ VIO_INVALID_PARMS if an invalid color register was requested, or AX = ERROR _VIO_INVALID_LENGTH if too many registers were requested.


Function 107h - Remarks

None.


Function 107h -

Category:

Function:
107h
Description:
Set Color Lookup Table

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Query Cursor Info - Function 108h

Category:

Function:
108h
Description:
Query Cursor Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function returns all of the information related to the cursor.


Function 108h - Description

This function returns all of the information related to the cursor.


Function 108h - Parmlength

Parmlength

Length of parameter block in bytes (=16) passed on input.


Function 108h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

The remaining flags select the information to be
returned:

Bit 1 selects cursor position.
Bit 2 selects cursor type.
Bits 3-15 are reserved and must be Off.




Function 108h - Row

Row

0 is the top row.


Function 108h - Column

Column

0 is the left column.


Function 108h - Top Cursor Scan Line

Top Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.


Function 108h - Bottom Cursor Scan Line

Bottom Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.


Function 108h - Cursor Width

Cursor Width

Cursor width in columns, if text mode; in pels, if graphics mode.


Function 108h - Cursor Attribute

Cursor Attribute

Cursor attribute: -1 = hidden, if text mode; other values = color attribute, if graphics mode.


Function 108h - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Row                         WORD      |
|--------------------------------------|
|Column                      WORD      |
|--------------------------------------|
|Top Cursor Scan Line        WORD      |
|--------------------------------------|
|Bottom Cursor Scan Line     WORD      |
|--------------------------------------|
|Cursor Width                WORD      |
|--------------------------------------|
|Cursor Attribute            WORD      |
\--------------------------------------/


Function 108h - Returns

This function returns with AX = 0 if it can successfully get all of the cursor information requested. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS.


Function 108h - Remarks

None.


Function 108h -

Category:

Function:
108h
Description:
Query Cursor Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Set Cursor Info - Function 109h

Category:

Function:
109h
Description:
Set Cursor Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function sets all of the information related to the cursor.


Function 109h - Description

This function sets all of the information related to the cursor.


Function 109h - Parmlength

Parmlength

Length of parameter block in bytes (=16) passed on input.


Function 109h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware is
      updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

The remaining flags select the options to be set:

Bit 1 selects cursor position.
Bit 2 selects cursor type.
Bits 3-15 are reserved and must be OFF.




Function 109h - Row

Row

0 is the top row.


Function 109h - Column

Column

0 is the left column.


Function 109h - Top Cursor Scan Line

Top Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.


Function 109h - Bottom Cursor Scan Line

Bottom Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.


Function 109h - Cursor Width

Cursor Width

Cursor width in columns, if text mode; in pels, if graphics mode.


Function 109h - Cursor Attribute

Cursor Attribute

Cursor attribute: -1 = hidden, if text mode; other values = color attribute, if graphics mode.


Function 109h - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Row                         WORD      |
|--------------------------------------|
|Column                      WORD      |
|--------------------------------------|
|Top Cursor Scan Line        WORD      |
|--------------------------------------|
|Bottom Cursor Scan Line     WORD      |
|--------------------------------------|
|Cursor Width                WORD      |
|--------------------------------------|
|Cursor Attribute            WORD      |
\--------------------------------------/


Function 109h - Returns

This function returns with AX = 0 if it can successfully set all of the cursor information requested. Otherwise, it returns with AX equal to: 

     ERROR_VIO_MODE if it cannot support the function
       in the current mode
     ERROR_VIO_ROW if the row number is out of range
     ERROR_VIO_COL if the column number is out of range


Function 109h - Remarks

None.

Function 109h -

Category:

Function:
109h
Description:
Set Cursor Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Query Font - Function 10Ah

Category:

Function:
10Ah
Description:
Query Font

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function returns the current active font or a selected font for the current code page. The format of the font definition is determined by the type of adapter.


Function 10Ah - Description

This function returns the current active font or a selected font for the current code page. The format of the font definition is determined by the type of adapter.


Function 10Ah - Parmlength

Parmlength

Length of parameter block in bytes (=14) passed on input.


Function 10Ah - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer
            only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bit 1 indicates whether a specific font is to be
      returned instead of the current font.

      OFF = Return the current font.
      ON  = Return the selected font for the current code
            page.  Setting this flag indicates that the pel
            columns and rows are used as input to select
            the font.

Bits 2-15 are reserved and must be OFF.




Function 10Ah - Font Buffer Far Address

Font Buffer Far Address

Data area in which the font definition is returned.


Function 10Ah - Data Area Length

Data Area Length

Length of data area in which font table is returned.


Function 10Ah - Pel Columns

Pel Columns

Pel columns.


Function 10Ah - Pel Rows

Pel Rows

Pel rows.


Function 10Ah - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Font Buffer Far Address     DWORD     |
|--------------------------------------|
|Data Area Length            WORD      |
|--------------------------------------|
|Pel Columns                 WORD      |
|--------------------------------------|
|Pel Rows                    WORD      |
\--------------------------------------/


Function 10Ah - Returns

If the Length is specified as 0, no font is returned. Instead, the Length field returns the size needed to hold the font. Query Font returns with AX = 0 if it can successfully read the font. Otherwise, it returns with AX = ERROR_VIO_INVALID_PARMS.


Function 10Ah - Remarks

None.


Function 10Ah -

Category:

Function:
10Ah
Description:
Query Font

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Set Font - Function 10Bh

Category:

Function:
10Bh
Description:
Set Font

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function sends a user font definition to the device handler. If the font is appropriate for the current mode, it is loaded into the adapter. If not, it is saved for possible use on subsequent calls to SetMode. The format of the font definition is determined by the type of adapter.


Function 10Bh - Description

This function sends a user font definition to the device handler. If the font is appropriate for the current mode, it is loaded into the adapter. If not, it is saved for possible use on subsequent calls to SetMode. The format of the font definition is determined by the type of adapter.


Function 10Bh - Parmlength

Parmlength

Length of parameter block in bytes (=14) passed on input.


Function 10Bh - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bits 1-15 are reserved and must be OFF.




Function 10Bh - Font Buffer Far Address

Font Buffer Far Address

Far address of the font buffer containing the font set in compact form.


Function 10Bh - Data Area Length

Data Area Length

Length of data area containing the font table to be set.


Function 10Bh - Pel Columns

Pel Columns

Pel columns.


Function 10Bh - Pel Rows

Pel Rows

Pel rows.


Function 10Bh - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Font Buffer Far Address     DWORD     |
|--------------------------------------|
|Data Area Length            WORD      |
|--------------------------------------|
|Pel Columns                 WORD      |
|--------------------------------------|
|Pel Rows                    WORD      |
\--------------------------------------/


Function 10Bh - Returns

This function returns with AX = 0 if it can successfully load the font. Otherwise, it returns with AX = ERROR_VIO_INVALID_PARMS.


Function 10Bh - Remarks

None.


Function 10Bh -

Category:

Function:
10Bh
Description:
Set Font

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Query Mode - Function 10Ch

Category:

Function:
10Ch
Description:
Query Mode

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function returns all of the information pertaining to the current video mode.


Function 10Ch - Description

This function returns all of the information pertaining to the current video mode.


Function 10Ch - Parmlength

Parmlength

Length of parameter block in bytes (=8) passed on input.


Function 10Ch - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware is to
      be read.

      OFF = Return data from the environment buffer only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bits 1-15 are reserved and must be OFF.




Function 10Ch - Mode Data Structure Far Address

Mode Data Structure Far Address

Far Address of the Mode data structure defined by VioGetMode.


Function 10Ch - Parameter Packet Format



/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Mode Data Structure Far        DWORD     |
|Address                                  |
\-----------------------------------------/


Function 10Ch - Returns

If the Length specified in the Config Data is larger than the maximum possible length or if the Length is specified as 2, it is replaced by the largest valid length. This function returns with AX = ERROR_VIO_INVALID_ LENGTH only if the Length specified is less than 2.


Function 10Ch - Remarks

None.


Function 10Ch -

Category:

Function:
10Ch
Description:
Query Mode

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Set Mode - Function 10Dh

Category:

Function:
10Dh
Description:
Set Mode

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function sets the video mode of the video adapter. For text modes, it considers not only what display characteristics it can support but also what ROM, code page, and user-defined fonts it has available.


Function 10Dh - Description

This function sets the video mode of the video adapter. For text modes, it considers not only what display characteristics it can support but also what ROM, code page, and user-defined fonts it has available.

Function 10Dh - Datalength

Datalength

Length of the data structure in bytes, including Length itself (=8).

Function 10Dh - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bit 1 indicates whether the mode is changed
      or only validated.

      OFF = Perform normal mode setting.
      ON  = Perform only mode validation.

Bits 2-15 are reserved and must be OFF.




Function 10Dh - Mode Data Structure Far Address

Mode Data Structure Far Address

Far Address of the Mode data structure defined by VioSetMode.


Function 10Dh - Parameter Packet Format



/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Datalength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Mode Data Structure Far        DWORD     |
|Address                                  |
\-----------------------------------------/


Function 10Dh - Returns

Set Mode returns with AX = 0 if it can set the requested mode. Otherwise, it returns with AX = ERROR_VIO_MODE.


Function 10Dh - Remarks

This function must validate the mode data without using the environment buffer, because it might not have been initialized or might not be valid for this device. This function implicitly initializes the environment buffer if it has not already been done.


Function 10Dh -

Category:

Function:
10Dh
Description:
Set Mode

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

Query Palette Registers - Function 10Eh

Category:

Function:
10Eh
Description:
Query Palette Registers

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function queries the relationship between the text attributes and the color registers.

Function 10Eh - Description

This function queries the relationship between the text attributes and the color registers.

Function 10Eh - Datalength

Datalength

Length of parameter block in bytes (=12) passed on input.

Function 10Eh - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer
            only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bits 1-15 are reserved and must be OFF.

Function 10Eh - Palette Buffer Far Address

Palette Buffer Far Address

Data area where a 1-WORD entry for each register containing its color value is returned.

Function 10Eh - Palette Register Index

Palette Register Index

Index of first palette register to get.

Function 10Eh - Register Quantity

Register Quantity

Number of registers to return.

Function 10Eh - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Datalength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Palette Buffer Far Address     DWORD     |
|-----------------------------------------|
|Palette Register Index         WORD      |
|-----------------------------------------|
|Register Quantity              WORD      |
\-----------------------------------------/

Function 10Eh - Returns

This function returns with AX = 0 if it can successfully get all of the requested palette registers. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS if an invalid color register was requested, or AX = ERROR_VIO _INVALID_LENGTH if too many registers were requested.

Function 10Eh - Remarks

None.

Function 10Eh -

Category:

Function:
10Eh
Description:
Query Palette Registers

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

Set Palette Registers - Function 10Fh

Category:

Function:
10Fh
Description:
Set Palette Registers

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function defines the relationship between the text attributes and the color registers.

Function 10Fh - Description

This function defines the relationship between the text attributes and the color registers.

Function 10Fh - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.

Function 10Fh - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bits 1-15 are reserved and must be OFF.

Function 10Fh - Palette Buffer Far Address

Palette Buffer Far Address

Far address of palette register buffer. Data area with 1 WORD, containing the color value for each register set.

Function 10Fh - Palette Register Index

Palette Register Index

Index of first palette register to set. Data area with 1 WORD, containing the color value for each register set.

Function 10Fh - Register Quantity

Register Quantity

Number of registers to set.

Function 10Fh - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Palette Buffer Far Address     DWORD     |
|-----------------------------------------|
|Palette Register Index         WORD      |
|-----------------------------------------|
|Register Quantity              WORD      |
\-----------------------------------------/


Function 10Fh - Returns

This function returns with AX = 0 if it can successfully set all of the requested palette registers. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS if an invalid color register was requested, or AX = ERROR_VIO _INVALID_LENGTH if too many registers were requested.

Function 10Fh - Remarks

None.

Function 10Fh -

Category:

Function:
10Fh
Description:
Set Palette Registers

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

Query Physical Buffer - Function 110h

Category:

Function:
110h
Description:
Query Physical Buffer

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function returns an LDT selector that can be used to access the physical video buffer. The current physical video buffer is returned unless a specific address range is requested.

Function 110h - Description

This function returns an LDT selector that can be used to access the physical video buffer. The current physical video buffer is returned unless a specific address range is requested.

Function 110h - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.

Function 110h - Flags

Flags

Must be zero.

Function 110h - Query Physical Buffer Far Address

Query Physical Buffer Far Address

Far Address of the Query Physical Buffer data structure defined by VioGetPhysBuf.

Function 110h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Query Physical Buffer Far      DWORD     |
|Address                                  |
\-----------------------------------------/

Function 110h - Returns

Query Physical Buffer returns with AX = 0 if it can successfully allocate the LDT selector. Otherwise, it returns with AX set by the PhysToUVirtdevice helper function or with AX = ERROR_VIO_INVALID_PARMS if the requested buffer resides outside the valid range for the device.

Function 110h - Remarks

If the physical display buffer address and length passed on input are 0, this subfunction returns an LDT selector, that corresponds to the current mode.

A physical video device driver must provide Read/Write access to the physical address range where the physical display buffer is located. The physical device driver must provide Read-only access to the physical address range where the ROM fonts are located. If the physical address passed on input is not within the physical display buffer or ROM font ranges, an error is returned.

Function 110h -

Category:

Function:
110h
Description:
Query Physical Buffer

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

Free Physical Buffer - Function 111h

Category:

Function:
111h
Description:
Free Physical Buffer

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function deallocates an LDT selector that was acquired by a call to the Query Physical Buffer routine.

Function 111h - Description

This function deallocates an LDT selector that was acquired by a call to the Query Physical Buffer routine.

Function 111h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.

Function 111h - Flags

Flags Must be zero.

Function 111h - LDT Selector

LDT Selector

LDT Selector.

Function 111h - Parameter Packet Format

/---------------------------\
|Field            Length    |
|---------------------------|
|Parmlength       WORD      |
|---------------------------|
|Flags            WORD      |
|---------------------------|
|LDT Selector     DWORD     |
\---------------------------/


Function 111h - Returns

This function always returns with AX = 0.

Function 111h - Remarks

None.

Function 111h -

Category:

Function:
111h
Description:
Free Physical Buffer

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

Query Variable Info - Function 112h

Category:

Function:
112h
Description:
Query Variable Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function reads various minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.

Function 112h - Description

This function reads various minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.


Function 112h - Parmlength

Parmlength

Length of parameter block in bytes (=26) passed on input.


Function 112h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer
            only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

The remaining flags select the information to be
returned:

Bit 1 selects blink versus background color.
Bit 2 selects overscan (border) color.
Bit 3 selects scan line for underscore.
Bit 4 selects video enable.
Bit 5 selects the display mask.
Bit 6 selects code page.
Bit 7 forces a code page set (used with 6).
Bit 8 gets the scrollable rectangle.
Bits 9-15 are reserved and must be OFF.




Function 112h - Blink/Background Intensity

Blink/Background Intensity

Blink versus background intensity: 

        0 = blink.
        1 = background intensity.




Function 112h - Overscan (border) Color

Overscan (border) ColorOverscan (border) Color.


Function 112h - Scan Line

Scan Line

Scan line for underscore (0-31); 32 = no underscore.


Function 112h - Video Enable

Video Enable

Video enable: 0 = OFF and 1 = ON. OFF means off until the physical device driver is told to turn it back on. If the video signal is turned off and then the mode is set, the signal must remain off.


Function 112h - Display Mask

Display Mask

Display mask: 

   bit 0  = plane 0
     �         �
     �         �
     �         �
   bit 31 = plane 31

   bit state = 0, plane disabled for display.
   bit state = 1, plane enabled for display.

   (Planes disabled for display result in 0 to palette.)




Function 112h - Code Page

Code Page

Code Page.


Function 112h - Scrollable Rectangle - Left

Scrollable Rectangle - Left

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 112h - Scrollable Rectangle - Top

Scrollable Rectangle - Top

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 112h - Scrollable Rectangle - Right

Scrollable Rectangle - Right

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 112h - Scrollable Rectangle - Bottom

Scrollable Rectangle - Bottom

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 112h - Screen Rows

Screen Rows

The number of text rows in the current mode.


Function 112h - Screen Columns

Screen Columns

The number of text columns in the current mode.


Function 112h - Parameter Packet Format



/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Blink/Background Intensity     WORD      |
|-----------------------------------------|
|Overscan (border) Color        WORD      |
|-----------------------------------------|
|Scan Line                      WORD      |
|-----------------------------------------|
|Video Enable                   WORD      |
|-----------------------------------------|
|Display Mask                   DWORD     |
|-----------------------------------------|
|Code Page                      WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Left    WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Top     WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Right   WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Bottom  WORD      |
|-----------------------------------------|
|Screen Rows                    WORD      |
|-----------------------------------------|
|Screen Columns                 WORD      |
\-----------------------------------------/


Function 112h - Returns

Query Variable Info returns with AX = 0 if it can successfully get the selected variable information. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS.


Function 112h - Remarks

None.


Function 112h -

Category:

Function:
112h
Description:
Query Variable Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Set Variable Info - Function 113h

Category:

Function:
113h
Description:
Set Variable Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function sets the minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.


Function 113h - Description

This function sets the minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.


Function 113h - Parmlength

Parmlength

Length of parameter block in bytes (=26) passed on input.


Function 113h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

The remaining flags select the information to be set:

Bit 1 selects blink versus background color.
Bit 2 selects overscan (border) color.
Bit 3 selects scan line for underscore.
Bit 4 selects video enable.
Bit 5 selects the display mask.
Bit 6 selects code page.
Bit 7 forces a code page set (used with 6).
Bit 8 gets the scrollable rectangle.
Bits 9-15 are reserved and must be OFF.




Function 113h - Blink/Background Intensity

Blink/Background Intensity

Blink versus background intensity: 

        0 = blink.
        1 = background intensity.




Function 113h - Overscan (border) Color

Overscan (border) Color

Overscan (border) Color.


Function 113h - Scan Line

Scan Line

Scan line for underscore (0-31); 32 = no underscore.


Function 113h - Video Enable

Video Enable

Video enable: 0 = OFF and 1 = ON. OFF means off until the physical device driver is told to turn it back on. If the video signal is turned off and then the mode is set, the signal must remain off.


Function 113h - Display Mask

Display Mask

Display mask: 

   bit 0  = plane 0
     �         �
     �         �
     �         �
   bit 31 = plane 31

   bit state = 0, plane disabled for display.
   bit state = 1, plane enabled for display.

   (Planes disabled for display result in 0 to palette.)




Function 113h - Code Page

Code Page

Code Page.


Function 113h - Scrollable Rectangle - Left

Scrollable Rectangle - Left

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 113h - Scrollable Rectangle - Top

Scrollable Rectangle - Top

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 113h - Scrollable Rectangle - Right

Scrollable Rectangle - Right

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 113h - Scrollable Rectangle - Bottom

Scrollable Rectangle - Bottom

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.


Function 113h - Screen Rows

Screen Rows

The number of text rows in the current mode. Reserved (0).


Function 113h - Screen Columns

Screen Columns

The number of text columns in the current mode. Reserved (0).


Function 113h - Parameter Packet Format



/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Blink/Background Intensity     WORD      |
|-----------------------------------------|
|Overscan (border) Color        WORD      |
|-----------------------------------------|
|Scan Line                      WORD      |
|-----------------------------------------|
|Video Enable                   WORD      |
|-----------------------------------------|
|Display Mask                   DWORD     |
|-----------------------------------------|
|Code Page                      WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Left    WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Top     WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Right   WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Bottom  WORD      |
|-----------------------------------------|
|Screen Rows                    WORD      |
|-----------------------------------------|
|Screen Columns                 WORD      |
\-----------------------------------------/


Function 113h - Returns

Set Variable Info returns with AX = 0 if it can successfully set the selected variable information. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS.


Function 113h - Remarks

There are two types of code page sets. The first code page set allows a code page to be set while the mode of the display (as used by Function 10Dh ) remains the same. The other type of code page set causes a change in the display mode. This occurs when switching between DBCS and non-DBCS code pages.

If bit 6 of the flags WORD is set and bit 7 is clear, the code page is set when the adapter can use the code page without changing from DBCS mode to SBCS mode, or vice versa. The mode should be changed if both bits 6 and 7 of the flags WORD are set, and the code page is used when the mode is changed from SBCS mode to DBCS mode. Bit 7 is ignored if bit 6 is not set. This applies only to text modes. Graphics modes are not set to text modes by forcing a code page.

The BVH need not support any scrollable region other than the entire display area. The adapter may support any scrollable rectangle up to the size of the entire screen. All coordinates are in text display cells. This scrollable rectangle data is undefined for graphics modes.


Function 113h -

Category:

Function:
113h
Description:
Set Variable Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Terminate Environment - Function 114h

Category:

Function:
114h
Description:
Terminate Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function is used to notify the BVH that the environment is about to be freed so that any required cleanup can be performed by the BVH. If no Terminate Environment processing is required, this function can be omitted. PMERR_DEV_FUNC_NOT_INSTALLED is then returned in AX, but it is ignored by the video subsystem.


Function 114h - Description

This function is used to notify the BVH that the environment is about to be freed so that any required cleanup can be performed by the BVH. If no Terminate Environment processing is required, this function can be omitted. PMERR_DEV_FUNC_NOT_INSTALLED is then returned in AX, but it is ignored by the video subsystem.


Function 114h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.


Function 114h - Flags

Flags

Reserved, must be off.


Function 114h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.


Function 114h - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/


Function 114h - Returns

None.


Function 114h - Remarks

None.


Function 114h -

Category:

Function:
114h
Description:
Terminate Environment

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

Print Screen - Function 115h

Category:

Function:
115h
Description:
Print Screen

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function causes the contents of the current screen to be written to the printer handle provided. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.


Function 115h - Description

This function causes the contents of the current screen to be written to the printer handle provided. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.


Function 115h - Parmlength

Parmlength

Length of parameter block in bytes (=8) passed on input.


Function 115h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical video
      buffer should be printed.

      OFF = Print only the contents of the logical
            video buffer.
      ON  = Print the contents of the physical
            video buffer, if appropriate.

Bits 1-15 are reserved and must be OFF.




Function 115h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.


Function 115h - Print Device Handle

Print Device Handle

Print Device Handle. File handle of the print device to be used.


Function 115h - Parameter Packet Format



/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
|--------------------------------------|
|Print Device Handle         WORD      |
\--------------------------------------/


Function 115h - Returns

None.


Function 115h - Remarks

None.


Function 115h -

Category:

Function:
115h
Description:
Print Screen

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Write TTY - Function 116h

Category:

Function:
116h
Description:
Write TTY

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function performs the functions of the call to VioWrtTTY. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.


Function 116h - Description

This function performs the functions of the call to VioWrtTTY. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.


Function 116h - Parmlength

Parmlength

Length of parameter block in bytes (=14) passed on input.


Function 116h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical video
      buffer needs to be updated.

      OFF = The physical video buffer must not be
            updated.
      ON  = The physical video buffer must be updated.

Bit 1 indicates whether the logical video buffer
      needs to be updated.

      OFF = The logical video buffer can optionally be
            updated.
      ON  = The logical video buffer must be updated.

Bit 2 indicates whether ANSI is active.

      OFF = ANSI is not active.  Escape sequences should
            be considered as text data.
      ON  = ANSI is active.  Escape sequences must be
            handled locally or passed to the default
            routine in BVS through device chaining.

Bit 3 indicates whether Ctrl_PrtSc is active.

      OFF = Ctrl_PrtSc is not active.
      ON  = Ctrl_PrtSc is active.  Characters need to
            be echoed to the printer locally or by the
            default routine in BVS through device chaining.

Bits 4-15 are reserved and must be OFF.




Function 116h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.


Function 116h - Character String Far Address

Character String Far Address

Far Address of character string to be written.


Function 116h - Character String Length

Character String Length

Length of character string to be written.


Function 116h - Print Device Handle

Print Device Handle

Print Device Handle. The file handle of the print device used for Ctrl_ PrtSc.

Function 116h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Logical Buffer Selector        WORD      |
|-----------------------------------------|
|Character String Far Address   DWORD     |
|-----------------------------------------|
|Character String Length        DWORD     |
|-----------------------------------------|
|Print Device Handle            WORD      |
\-----------------------------------------/


Function 116h - Returns

None.


Function 116h - Remarks

None.


Function 116h -

Category:

Function:
116h
Description:
Write TTY

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Query LVB Info - Function 117h

Category:

Function:
117h
Description:
Query LVB Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks

This function returns information associated with the LVB, such as the allocation size and default attribute for a specified LVB.


Function 117h - Description

This function returns information associated with the LVB, such as the allocation size and default attribute for a specified LVB.


Function 117h - Parmlength

Parmlength

Length of parameter block in bytes (=20) passed on input.

Function 117h - Flags

Flags

Defined as follows: 

Bit 0 indicates whether the physical
      hardware is to be read.

      OFF = Read from the environment buffer.
      ON  = Read from the current state of the
            hardware state.

Bits 1-15 are reserved and must be OFF.

Function 117h - LVB Format ID

LVB Format ID

Format ID for LVB. If this and the attribute count are both 0, the current mode values are used.

Function 117h - LVB Attribute Count

LVB Attribute Count

Attribute Count for the LVB. If this and the format ID are both 0, the current mode values are used.

Function 117h - LVB Width

LVB Width

LVB Width in cells.


Function 117h - LVB Height

LVB Height

LVB Height in cells.


Function 117h - LVB Allocation Size

LVB Allocation Size

Allocation size of the LVB is returned here.


Function 117h - Attribute Return Buffer Size

Attribute Return Buffer Size

Size of the default attribute return buffer.


Function 117h - Attribute Return Buffer Pointer

Attribute Return Buffer Pointer

Pointer to the default attribute return buffer (passed). The default attribute is returned if the buffer is large enough. If this value is 0, the attribute is not returned.


Function 117h - Parameter Packet Format



/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|LVB Format ID                  BYTE      |
|-----------------------------------------|
|LVB Attribute Count            BYTE      |
|-----------------------------------------|
|LVB Width                      WORD      |
|-----------------------------------------|
|LVB Height                     WORD      |
|-----------------------------------------|
|LVB Allocation Size            DWORD     |
|-----------------------------------------|
|Attribute Return Buffer Size   WORD      |
|-----------------------------------------|
|Attribute Return Buffer        DWORD     |
|Pointer                                  |
\-----------------------------------------/


Function 117h - Returns

This function returns with AX = 0 if it can successfully calculate the LVB size and return the attribute information. Otherwise, it returns with AX = ERROR_VIO_INVALID_PARMS.


Function 117h - Remarks

None.


Function 117h -

Category:

Function:
117h
Description:
Query LVB Info

Select an item: 

Description
Parameter Packet Format 
Returns 
Remarks


Level 0 Physical Device Driver Interfaces

The strategy portion of the Level 0 physical device drivers that can be a component of any video device handler is called to handle I/O requests through a request packet interface with the OS/2 kernel. The strategy routine executes at task-time as a result of an application VIO request. The strategy routine is called with ES:BX pointing to the request packet ( the pointer is valid in both a DOS session and an OS/2 session). Only three command codes (passed in the request packet) are required to be supported by a video device driver. For any other command code the physical device driver does not support, the physical video device driver must return Unsupported Command and Done in the request packet status field.

The following are the physical device driver commands that are supported by the physical video device driver (the command codes are in parentheses):

INIT (00h) - Initialize the Device

On entry, the request block contains the following fields as inputs to the physical video device driver:

  • Pointer to the DevHlp entry point
  • Pointer to the INIT arguments

On exit, the physical video device driver sets the first pointer to the offsets of the code and data segments to release code and data needed only by the initialization routine. The second pointer is set to 0. If initialization is successful, the request packet status field is set to indicate No Error and Done; otherwise, the status is set to General Failure .

The physical video device driver can perform the following initialization:

�Obtain the DevHlp address from the request packet.
�Verify that the display adapter and the display that it supports are present. If not, it can fail initialization.


OPEN (0Dh) - Open the Device

This service routine does nothing but return with No Error status.


GENERIC IOCtl (10h) - Send I/O Requests to the Device

On entry, the request packet has the IOCtl category code and function code set. The parameter buffer and the data buffer addresses are set as virtual addresses. The physical video device driver performs the physical device driver initialization, when requested.

Physical Device Driver Initialization

The IOCtl described below supports the same class of functions as the Presentation Manager dynamic link enable entry point. It is called to fill in the Call Vector Table for the BVH. The call returns an error if the physical device driver detects that the adapter is not present.

Category 3

Function 73h

Purpose

To initialize the Call Vector Table.

Parameter Block Format

None.

Data Packet Format 



     DWORD   Subfunction
     DWORD   Parameter1
     DWORD   Parameter2
     WORD    ReturnCode

Subfunction

The Presentation Manager enables the subfunction number. Its value must be 1 to start the Presentation Manager Fill Logical Device Block subfunction. All pieces of the BVH must support this function. Pieces of the BVH that do not support the Presentation Manager interface do not need to support the other functions. Any function not supported should return PMERR_DEV_FUNC_ NOT_INSTALLED.

Parameter1 for Subfunction = 1

Far pointer to this structure: 

     DWORD   Engine Version
     DWORD   Count of Table Functions

Engine Version Version of the Presentation Manager Graphics Engine

Count of Table Functions Number of entries in the passed dispatch table. The physical device driver can only write this many entries into the table.

Parameter2 for Subfunction=1

Far pointer to this structure: 

     DWORD   Flags Pointer
     DWORD   Call Vector Table

Flags Pointer Pointer to where the flags controlling calls to the Fill Physical Device Block function go.

Call Vector Table Pointer to the default dispatch table containing the addresses of the default handler functions and the functions supported by this component. Each entry in the Call Vector Table is the far address of a Video Device Handler function, which must be callable from Ring 3. The address of the nth BVH function is the nth DWORD in the table, beginning with Function 0. Refer to the DLL Initialization function for a description of the function numbers.

Remarks

This function is supported by the video device drivers and is called only once for each adapter to be supported by the BVH. A video device handler should determine if the display adapter and that which it supports is present. If not present, this function must return an error. Every part of a BVH must successfully initialize the Call Vector Table for that device to be used by OS/2.

EGA.SYS and INT 2Fh Screen Switch Notification

For some DOS EGA applications, OS/2 is not able to switch from a DOS session to an OS/2 session and then back again. Upon return to the DOS application, the screen will be incorrect. The DOS EGA applications that do not run successfully are:

  • Applications that download fonts into a character generator block other than Block 0. Character Generator Block 0 is supported.
  • Graphic mode applications that use more than one display page.
  • Advanced graphics mode applications that write directly to the registers on the EGA adapter.

To supplement OS/2 screen switching support, a DOS application can be written to use the EGA register interface. Alternatively, a DOS application can be notified on a screen switch through multiplex interrupt 2Fh, AH = 40h. These two mechanisms are described in the following sections.

Note:On an IBM PS/2 personal computer the registers on the adapter are both readable and writable. For these configurations, OS/2 reads and saves the registers on a screen switch away from a DOS session, and restores the registers upon return to a DOS session.

For configurations including the IBM PS/2 Display Adapter 8514/A when the 8514/A display adapter is in an advanced function mode, the OS/2 operating system does not save the physical display buffer when switching away from a DOS session. Therefore, end users are cautioned to complete any 8514/A advanced function mode application before switching to OS/2 mode.

EGA.SYS Device Driver

EGA.SYS is a physical device driver that provides support for the EGA register interface in a DOS session. To support advanced graphics modes D, E, F, and 10 in a DOS session, the Mouse Pointer Draw device driver must save or restore the EGA registers. Because the EGA registers are not readable, this can be done only if the application assists in setting the registers initially. Rather than performing I/O directly to the registers on the adapter, the application sets the registers through the EGA register interface.

EGA Register Interface

The EGA register interface is a library of ten functions supported for a DOS session, advanced graphics applications (modes D, E, F, and 10). These functions do the following:

  • Read from, or write to, one or more of the EGA write-only registers
  • Define default values for the EGA write-only registers, reset the EGA registers to these default values, or return the default values
  • Check whether the EGA register interface is present and, if so, return its version number.

When the application uses the EGA register interface, OS/2 2.1 maintains a backup copy or shadowshow the EGA registers are set. Then, if the operator switches away from (and later returns to) the application, the registers are restored properly. It is not necessary to use the EGA register interface to set the mode, color palette, or palette registers. Instead, use ROM BIOS function INT 10h with AH = 00h, 0Bh, or 10h, respectively.

Calling The EGA Register Interface

To call EGA register interface functions from an assembly language program, the following actions must be performed:

1.Load the registers with the required parameter values
2.Execute software interrupt 10h.

Values returned by the EGA register interface functions are placed in registers.


EGA Register Interface Restrictions

A list of areas where restrictions apply for the EGA Register Interface are shown below:

�Functions not supported
�Attribute Controller registers
�Sequencer Memory Mode register
�Input Status registers
�Graphics Controller Miscellaneous register

Functions Not Supported

Multiple display pages in graphics modes are not supported. Fonts can be loaded (by using ROM BIOS INT 10h with AH = 11h) only into Character Generator Block 0.

Attribute Controller Registers

Before your application program uses the Attribute Controller registers (I/ O address 3C0h) in an extended interrupt 10h call, it must set the flip- flopthat selects the address or data register so that it selects the address register (by doing an input from I/O port 3BAh or 3DAh). The flip- flop is always reset to this state upon return from the extended INT 10h call. Interrupt routines that access the attribute chip must also leave the flip-flop set to the address register upon return from the interrupt.

Note:If the application program sets the flip-flop so that it selects the Data register, and expects the flip-flop to remain in this state, the application must disable interrupts between the time it sets the flip-flop to the Data register state and the last time the flip-flop is assumed to be in this state.

Sequencer Memory Mode Register

When the Sequencer Memory Mode register (I/O address 3C5H, data register 4) is accessed, the sequencer produces a faulton the CAS lines that can cause problems with video random access memory. As a result, the application cannot use the EGA Register Interface to read from, or write to, this register. Instead, use the following procedure to safely alter this register:

1.Disable interrupts
2.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 0
3.Read/modify/write the Sequencer Memory Mode register
4.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 1
5.Enable interrupts

Input Status Registers

The application cannot use the EGA Register Interface to read Input Status registers 0 (I/O address 3C2h) and 1 (I/O address 3BAh or 3DAh). If the program must read these registers, it must do so directly.

Graphics Controller Miscellaneous Register

When the Graphics Controller Miscellaneous register (I/O address 3CFh, data register 6) is accessed, a glitchon the CAS lines occurs that can cause problems with video random access memory. As a result, the application should not use the EGA Register Interface to read from or write to this register.

EGA Register Interface Function F6h does not alter the state of the Graphics Controller Miscellaneous register. Instead, use the following procedure to safely alter this register:

1.Disable interrupts
2.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 0
3.Read/modify/write the Graphics Controller Miscellaneous register
4.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 1
5.Enable interrupts


EGA Register Interface Functions

This section describes each EGA Register Interface function in detail. The following list shows these functions by function number (hex):

F0 Read One Register
F1 Write One Register
F2 Read Register Range
F3 Write Register Range
F4 Read Register Set
F5 Write Register Set
F6 Revert to Default Registers
F7 Define Default Register Table
F8 Read Default Register Table
FA Interrogate Driver

Note:Function F9h, and Functions FBh through FFh are reserved.

Each function description includes:

�The parameters required to make the call (input) and the expected return values (output)
�Any special considerations regarding the function

If the function description does not specify an input for a parameter, it is not necessary to supply a value for that parameter before making the call. If the function description does not specify an output value for a parameter, the parameter's value is the same before and after the call.

Note:The EGA Register Interface does not check input values, so be sure that the values loaded into the registers before making a call are correct.


Function F0H - Read One Register

This function reads data from a specified register on the EGA.

Input

AH = F0h

BX = Pointer for:

Pointer/data chips

BH = 0

BL = Pointer

Single registers

BX ignored.

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

Output

AX: Restored
BH: Restored
BL: Data
DX: Restored

All other registers are restored.

Example

The following example saves the contents of the Sequencer Map Mask register in myvalue: 



myvalue db   ?
        mov  ah, 0f0h        ; f0 = read one register
        mov  bx, 0002h       ; bh = 0 / bl = map mask index
        mov  dx, 0008h       ; dx = sequencer
        int  10h             ; get it!
        mov  myvalue, bl     ; save it!

The example below saves the contents of the Miscellaneous Output register in myvalue: 



myvalue db   ?
        mov  ah, 0f0h        ; f0 = read one register
        mov  dx, 0020h       ; dx = miscellaneous output register
        int  10h             ; get it!
        mov  myvalue, bl     ; save it!


Function F1H - Write One Register

This function writes data to a specified register on the EGA. When an application program returns from a call to Function F1, the contents of registers BH and DX are not restored. The program must save and restore these registers.

Input

AH = F1h

BL = Pointer for pointer/data chips. Data for single registers.

BH = Data for pointer/data chips. Ignored for single registers.

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes or D for color modes

Output

AX: Restored
BL: Restored
BH: Not restored
DX: Not restored

All other registers are restored.

Example

The following example writes the contents of myvalueinto the CRT Controller Cursor Start register: 



myvalue db   3h
        mov  ah, 0f1h        ; f1 = write one register
        mov  bh, myvalue     ; bh = data from myvalue
        mov  bl, 000ah       ; bl = cursor start index
        mov  dx, 0000h       ; dx = crt controller
        int  10h             ; write it!

The example below writes the contents of myvalueinto the Feature Control register: 



myvalue db   2h
        mov  ah, 0f1h        ; f1 = write one register
        mov  bl, myvalue     ; bl = data from myvalue
        mov  dx, 0028h       ; dx = feature control register
        int  10h             ; write it!


Function F2H - Read Register Range

This function reads data from a specified range of registers on the EGA. A range of registers is defined to be several registers that have consecutive indexes, on a single chip. This function is applicable for pointer/data chips.

Input

AH = F2h

CH = Starting pointer value

CL = Number of registers (must be >1)

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

? = B for monochrome modes, or D for color modes

ES:BX = Points to table of one-byte entries (length = value in CL). On return, each entry is set to the contents of the corresponding register.

Output

AX: Restored
BX: Restored
CX: Not restored
DX: Restored
ES: Restored

All other registers are restored.

Example

The following example saves the contents of the Attribute Controller Palette registers in paltable: 

paltable db  16 dup (?)
         mov  ax, ds               ; assume paltable in data segment
         mov  es, ax               ; es = data segment
         mov  bx, offset paltable  ; es:bx = paltable address
         mov  ah, 0f2h             ; f2 = read register range
         mov  cx, 0010h            ; ch = start index of 0
                                   ; cl = 16 registers to read
         mov  dx, 0018h            ; dx = attribute controller
         int  10h                  ; read them!


Function F3H - Write Register Range

This function writes data to a specified range of registers on the EGA. A range of registers is defined to be several registers that have consecutive indexes, on a single chip. This function is applicable for the pointer/data chips.

Input

AH = F3h

CH = Starting pointer value

CL = Number of registers (must be >1)

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

? = B for monochrome modes, or D for color modes

ES:BX = Points to table of one-byte entries (length = value in CL). Each entry contains the value to be written to the corresponding register.

Output

AX: Restored
BX: Not restored
CX: Not restored
DX: Not restored
ES: Restored.

All other registers are restored.

Example

The following example writes the contents of curslocinto the CRT Controller Cursor Location High and Cursor Location Low registers. 



cursloc db   01h, 00h            ; cursor at page offset 0100h
        mov  ax, ds              ; assume cursloc in data segment
        mov  es, ax              ; es = data segment
        mov  bx, offset cursloc  ; es:bx = cursloc address
        mov  ah, 0f3h            ; f3 = write register range
        mov  cx, 0e02h           ; ch = start index of 14
                                 ; cl = 2 registers to write
        mov  dx, 0000h           ; dx = crt controller
        int  10h                 ; write them!


Function F4H - Read Register Set

This function reads data from a set of registers on the EGA. A set of registers is defined to be several registers that might have consecutive indexes and that might not be on the same chip.

Input

AH = F4h

CX = Number of registers (must be >1)

ES:BX = Points to table of records with each entry in this format:

Bytes 1-2: Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

Byte 3: Pointer value (0 for single registers)

Byte 4: EGA Register Interface fills in data read from register specified in bytes 1-3.

Output

AX: Restored
BX: Restored
CX: Not restored
ES: Restored.

All other registers are restored.

Example

The following example saves the contents of the Miscellaneous Output register, Sequencer Memory Mode register, and CRT Controller Mode Control register in results: 



outvals dw   0020h               ; miscellaneous output register
        db   0                   ; 0 for single registers
        db   ?                   ; returned value
        dw   0008h               ; sequencer
        db   04h                 ; memory mode register index
        db   ?                   ; returned value
        dw   0000h               ; crt controller
        db   17h                 ; mode control register index
        db   ?                   ; returned value

results db   3 dup (?)
        mov  ax, ds              ; assume outvals in data segment
        mov  es, ax              ; es = data segment
        mov  bx, offset outvals  ; es:bx = outvals address
        mov  ah, 0f4h            ; f4 = read register set
        mov  cx, 3               ; number of entries in outvals
        int  10h                 ; get values into outvals
        mov  si, 3               ; move the returned values from
        add  si, offset outvals  ;  outvals
        mov  di, offset results  ;  to results
        mov  cx, 3               ; 3 values to move

loop:   mov  al, [si]            ; move one value from
        mov  [di], al            ;  outvals to results
        add  si, 4               ; skip to next source byte
        inc  di                  ; point to next destination byte
        loop loop


Function F5H - Write Register Set

This function writes data to a set of registers on the EGA. A set of registers is defined to be several registers that might have consecutive indexes, and that might be on the same chip.

Input

AH = F5h

CX = Number of registers (must be >1)

ES:BX = Points to table of values with each entry in this format:

Bytes 1-2: Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

Byte 3: Pointer value (0 for single registers)

Byte 4: Data to be written to register specified in bytes 1-3.

Output

AX: Restored
BX: Restored
CX: Not restored
ES: Restored.

All other registers are restored.

Example

The following example writes the contents of outvalsto the Miscellaneous Output register, Sequencer Memory Mode register, and CRT Controller Mode Control register: 



outvals dw   0020h               ; miscellaneous output register
        db   0                   ; 0 for single registers
        db   0a7h                ; output value
        dw   0008h               ; sequencer
        db   04h                 ; memory mode register index
        db   03h                 ; output value
        dw   0000h               ; crt controller
        db   17h                 ; mode control register index
        db   0a3h                ; output value
        mov  ax, ds              ; assume outvals in data segment
        mov  es, ax              ; es = data segment
        mov  bx, offset outvals  ; es:bx = outvals address
        mov  ah, 0f5h            ; f5 = write register set
        mov  cx, 3               ; number of entries in outvals
        int  10h                 ; write the registers!


Function F6H - Revert to Default Registers

This function restores the default settings of any registers that the application program has changed through the EGA Register Interface. The default settings are defined in a call to Function F7 (described in the next section).

Input

AH = F6h

Output

All registers are restored.

Example

The following example restores the default settings of the EGA registers: 



        mov  ah, 0f6h    ; f6 = revert to default registers
        int  10h         ; do it now!


Function F7H - Define Default Register Table

This function defines a table containing default values for any pointer/ data chip or single register. If default values are defined for a pointer/ data chip, they must be defined for all registers within that chip.

Input

AH = F7h

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

ES:BX = Points to table of one-byte entries. Each entry contains the default value for the corresponding register. The table must contain entries for all registers.

Output

AX: Restored
BX: Not restored
DX: Not restored
ES: Restored

All other registers are restored.

Example

The following example defines default values for the Attribute Controller: 



attrdflt db  00h, 01h, 02h, 03h, 04h, 05h, 06h, 07h
         db  10h, 11h, 12h, 13h, 14h, 15h, 16h, 17h
         db  08h, 00h, 0fh, 00h
         mov  ax, ds              ; assume attrdflt in data segment
         mov  es, ax              ; es = data segment
         mov  bx, offset attrdflt ; es:bx = attrdflt address
         mov  ah, 0f7h            ; f7 = define default register table
         mov  dx, 0018h           ; dx = attribute controller
         int  10h                 ; do it!

The example below defines a default value for the Feature Control register: 



featdflt db  00h
         mov  ax, ds              ; assume featdflt in data segment
         mov  es, ax              ; es = data segment
         mov  bx, offset featdflt ; es:bx = featdflt address
         mov  ah, 0f7h            ; f7 = define default register table
         mov  dx, 0028h           ; dx = feature control register
         int  10h                 ; do it!


Function F8H - Read Default Register Table

This function reads the table containing default register values for any pointer/data chip or single register.

Input

AH = 0F8H

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

ES:BX = Points to a table into which the default values are returned. The table must have room for the full set of values for the pointer/data chip or single register specified.

Output

AX: Restored
BX: Not restored
DX: Not restored
ES: Restored

All other registers are restored.

Example

The following example reads the default values for the Miscellaneous Output register: 



regdflt  db
         mov  ax, ds
         mov  es, ax               ; es = data segment
         mov  bx, offset regdflt   ; es:bx = regdflt address
         mov  ah, 0f8h             ; f8 = read default register table
         mov  dx, 0020h            ; dx = miscellaneous output register
         int  10h                  ; do it!

The following example reads the default values for the CRT Controller register: 



regdflt  db   25 dup (?)
         mov  ax, ds
         mov  es, ax               ; es = data segment
         mov  bx, offset regdflt   ; es:bx = regdflt address
         mov  ah, 0f8h             ; f8 = read default register table
         mov  dx, 0000h            ; dx = crt controller register
         int  10h                  ; do it!


Function FAH - Interrogate Driver

This function returns a value specifying whether the EGA.SYS device driver is present.

Input

AH = FAh

BX = 0

Output

AX: Restored
BX: 0, if EGA.SYS driver is not present
ES:BX: Pointer to EGA Register Interface version number, if present
Byte 1: Major release number
Byte 2: Minor release number (in 1/100ths)

Example

The following example interrogates the driver and displays the results: 



gotmsg  db   "EGA.SYS driver found", 0dh, 0ah, 24h
nopmsg  db   "EGA.SYS driver not found", 0dh, 0ah, 24h
revmsg  db   "revision $"
crlf    db   0dh, 0ah, 24h
ten     db   10
        mov  bx, 0              ; must be 0 for this call
        mov  ah, 0fah           ; fa = interrogate driver
        int  10h                ; interrogate!
        or   bx, bx             ; bx = 0 ?
        jnz  found              ; branch if driver present
        mov  dx, offset nopmsg  ; assume nopmsg in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output not found message
        jmp  continue           ; that's all for now
found:  mov  dx, offset gotmsg  ; assume gotmsg in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output found message
        mov  dx, offset revmsg  ; assume revmsg in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output "revision "
        mov  dl, es:[bx]        ; dl = major release number
        add  dl, "0"            ; convert to ASCII
        mov  ah, 2              ; 2 = display character
        int  21h                ; output major release number
        mov  dl, "."            ; dl = "."
        mov  ah, 2              ; 2 = display character
        int  21h                ; output a period
        mov  al, es:[bx+1]      ; al = minor release number

        xor  ah, ah             ; ah = 0
        idiv ten                ; al = 10ths, ah = 100ths
        mov  bx, ax             ; save ax in bx
        mov  dl, al             ; dl = 10ths
        add  dl, "0"            ; convert to ASCII
        mov  ah, 2              ; 2 = display character
        int  21h                ; output minor release 10ths
        mov  dl, bh             ; dl = 100ths
        add  dl, "0"            ; convert to ASCII
        mov  ah, 2              ; 2 = display character
        int  21h                ; output minor release 100ths
        mov  dx, offset crlf    ; assume crlf in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output end of line
continue:                       ; the end


INT 2Fh Screen Switch Notification

A new Multiplex Interrupt (INT 2Fh) is issued by OS/2 to signal either of the following two events:

�Switching the DOS application to the background (AX = 4001H)
�Switching the DOS application to the foreground (AX = 4002H)

A DOS application that receives this signal must hookthe Multiplex Interrupt vector. That is, when the application is started, it must save the current INT 2Fh vector and set this vector to point to the application' s interrupt handler.

When the notification is received, the application must save all registers, perform whatever processing is required, restore all registers, and issue the IRET instruction to return to the operating system. Only the following forms of processing are supported:

�Modifying application or video memory (or both)
�Issuing ROM BIOS video service calls (INT 10h)
�Issuing EGA Register Interface calls (INT 10h)
�Programming the EGA video card directly

Note:When an application is being switched to the background, and the application's INT 2Fh handler uses the EGA Register Interface to save the EGA registers, these registers are restored automatically when the application is returned to the foreground.

An application can receive notification that it is being switched to the background at any time. Code sequences that are sensitive to interruption can be protected with CLI/STI instructions. When the switch notification occurs, the application (other than its INT 2Fh handler) is frozen until it is returned to the foreground.

When an application's INT 2Fh handler receives notification with a value in AH other than 40H, the application must issue the JMP FAR instruction to branch to the previous INT 2Fh vector.


Using Extended Screen and Keyboard Control (ANSI.SYS, ANSICALL)

This section explains how to issue special control character sequences to:

�Control the position of the cursor
�Erase text from the screen
�Set the display mode
�Redefine the meaning of keyboard keys

ANSI extended screen and keyboard control sequences are supported in DOS sessions by ANSI.SYS, an installable device driver. In OS/2 sessions, these control sequences are supported by the ANSICALL component within OS/2 CHAR. DLL.

Note:In this section, unless otherwise specified, ANSI refers to both ANSI.SYS and ANSICALL.


Limitations and Restrictions

ANSI operates on a per-session basis. OS/2-mode ANSI is affected when keys are reassigned in a code page environment. ANSI does not provide code page support for key reassignment in a DOS session.


Control Sequence Syntax

Each of the cursor control sequences is in the format: 

     ESC [ parameters COMMAND

A cursor control sequence is defined as follows: 

/-------------------------------------------------------------\
|Sequence            |Description                             |
|--------------------+----------------------------------------|
|ESC                 |The 1-byte ASCII code for ESC (1BH). It |
|                    |is not the three characters ESC.        |
|--------------------+----------------------------------------|
|[                   |The character [.                        |
|--------------------+----------------------------------------|
|parameters          |The numeric values specified for #. The |
|                    |# represents a numeric parameter that is|
|                    |an integer value specified with ASCII   |
|                    |characters. If a parameter value is not |
|                    |specified, or if a value of 0 (zero) is |
|                    |specified, the default value for the    |
|                    |parameter is used.                      |
|--------------------+----------------------------------------|
|COMMAND             |An alphabetic string that represents the|
|                    |command. It is case-specific.           |
\-------------------------------------------------------------/

For example, ESC [2;10Hcould be created using BASIC as shown below. Notice that "CHR$(27)" is ESC. 

The IBM Personal Computer Basic Version 3.00 Copyright IBM Corp. 1981, 1982, 1983, 1984
xxxxx Bytes free

OK
open "sample" for output as 1
OK
print #1, CHR$(27);"[2;10H";"x row 2 col 10"
OK
close #1
OK

Cursor Control Sequences

The following tables contain the cursor control sequences used to control cursor positioning: 

/-------------------------------------------------------------\
|Cursor Position     |Function                                |
|--------------------+----------------------------------------|
|ESC [#;#H           |Moves the cursor to the position        |
|                    |specified by the parameters. The first  |
|                    |parameter specifies the row number and  |
|                    |the second parameter specifies the      |
|                    |column number. The default value is 1.  |
|                    |If no parameter is given, the cursor is |
|                    |moved to the home position.             |
\-------------------------------------------------------------/

This example copies the file SAMPLE from the previous example to CON, that places the cursor on row 2, column 10 of the screen: 



type sample



/-------------------------------------------------------------\
|Cursor Up           |Function                                |
|--------------------+----------------------------------------|
|ESC [#A             |Moves the cursor up one or more rows    |
|                    |without changing the column position.   |
|                    |The value of # determines the number of |
|                    |lines moved. The default value for # is |
|                    |1. This sequence is ignored if the      |
|                    |cursor is already on the top line.      |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Cursor Down         |Function                                |
|--------------------+----------------------------------------|
|ESC [#B             |Moves the cursor down one or more rows  |
|                    |without changing the column position.   |
|                    |The value of # determines the number of |
|                    |lines moved. The default value for # is |
|                    |1. The sequence is ignored if the cursor|
|                    |is already on the bottom line.          |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Cursor Forward      |Function                                |
|--------------------+----------------------------------------|
|ESC [#C             |Moves the cursor forward one or more    |
|                    |columns without changing the row        |
|                    |position. The value of # determines the |
|                    |number of columns moved. The default    |
|                    |value for # is 1. This sequence is      |
|                    |ignored if the cursor is already in the |
|                    |rightmost column.                       |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Cursor Backward     |Function                                |
|--------------------+----------------------------------------|
|ESC [#D             |Moves the cursor back one or more       |
|                    |columns without changing the row        |
|                    |position. The value of # determines the |
|                    |number of columns moved. The default    |
|                    |value for # is 1. This sequence is      |
|                    |ignored if the cursor is already in the |
|                    |leftmost column.                        |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Horizontal and      |Function                                |
|Vertical Position   |                                        |
|--------------------+----------------------------------------|
|ESC [#;#f           |Moves the cursor to the position        |
|                    |specified by the parameters. The first  |
|                    |parameter specifies the line number and |
|                    |the second parameter specifies the      |
|                    |column number. The default value is 1.  |
|                    |If no parameter is given, the cursor is |
|                    |moved to the home position.             |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Cursor Position     |Function                                |
|Report              |                                        |
|--------------------+----------------------------------------|
|ESC [#;#R           |The cursor sequence report reports the  |
|                    |current cursor position through the     |
|                    |standard input device. The first        |
|                    |parameter specifies the current line and|
|                    |the second parameter specifies the      |
|                    |current column.                         |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Device Status Report|Function                                |
|--------------------+----------------------------------------|
|ESC [6n             |The console driver gives a cursor       |
|                    |position report sequence on receipt of  |
|                    |device status report.                   |
\-------------------------------------------------------------/

Note:Do not use the Device Status Report as part of a prompt.

This example tells ANSI to put the current cursor position (row and column) in STDIN. Then the program reads it from STDIN and outputs it to STDOUT. 



PROGRAM dsr(INPUT,OUTPUT);

  VAR
    f:FILE OF CHAR;
    key:CHAR;

  FUNCTION inkey:CHAR;                    { read character  }
    VAR                                   { from the  /Using a File
      ch:CHAR;                            { keyboard buffer }
    BEGIN
      READ(f,ch);
      inkey:=ch
    END;

  BEGIN
    ASSIGN(f,'user');
    RESET(f);
        WRITE(CHR(27),'[6n');             { issue a DSR,  }
        key:=inkey;                       { read up to    }
        key:=inkey;                       { first digit   }
        key:=inkey;                       { of the row    }
        WRITE('row ',inkey,inkey,'  column ');
        key:=inkey;                       { skip to column}
        WRITE(inkey,inkey)                { write column  }
  END.



/-------------------------------------------------------------\
|Save Cursor Position|Function                                |
|--------------------+----------------------------------------|
|ESC [s              |The current cursor position is saved.   |
|                    |This cursor position can be restored    |
|                    |with the restore cursor position        |
|                    |sequence (see below).                   |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Restore Cursor      |Function                                |
|Position            |                                        |
|--------------------+----------------------------------------|
|ESC [u              |Restores the cursor to the value it had |
|                    |when the console driver received the    |
|                    |save cursor position sequence.          |
\-------------------------------------------------------------/


Erasing

The following tables contain the control sequences used to erase text from the screen: 

/-------------------------------------------------------------\
|Erase in Display    |Function                                |
|--------------------+----------------------------------------|
|ESC [2J             |Erases all of the screen, and the cursor|
|                    |goes to the home position.              |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Erase in Line       |Function                                |
|--------------------+----------------------------------------|
|ESC [K              |Erases from the cursor to the end of the|
|                    |line and includes the cursor position.  |
\-------------------------------------------------------------/


Controlling the Display Mode

The following tables contain the control sequences used to set the mode of operation:

�Set Graphics Rendition (SGR)
�Set Mode (SM)
�Reset Mode (RM) 



/-------------------------------------------------------------\
|Set Graphics    |Function                                    |
|Rendition (SGR) |                                            |
|----------------+--------------------------------------------|
|ESC [#;...;#m   |Sets the character attribute specified by   |
|                |the parameters.  All of the following char- |
|                |acters have the attribute according to the  |
|                |parameters until the next occurrence of SGR.|
|                |                                            |
|                |Parameter  Meaning                          |
|                |                                            |
|                |    0      All attributes off (normal white |
|                |           on black                         |
|                |    1      Bold on (high intensity)         |
|                |    4      Underscore on (monochrome-       |
|                |           compatible modes)                |
|                |    5      Blink on                         |
|                |    7      Reverse video on                 |
|                |    8      Canceled on (invisible)          |
|                |   30      Black foreground                 |
|                |   31      Red foreground                   |
|                |   32      Green foreground                 |
|                |   33      Yellow foreground                |
|                |   34      Blue foreground                  |
|                |   35      Magenta foreground               |
|                |   36      Cyan foreground                  |
|                |   37      White foreground                 |
|                |   38      Reserved                         |
|                |   39      Reserved                         |
|                |   40      Black background                 |
|                |   41      Red background                   |
|                |   42      Green background                 |
|                |   43      Yellow background                |
|                |   44      Blue background                  |
|                |   45      Magenta background               |
|                |   46      Cyan background                  |
|                |   47      White background                 |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Set Mode (SM)   |      Function                              |
|----------------+--------------------------------------------|
|   ESC [=#h     |Invokes the screen width or type specified  |
|or ESC [=h      |by the parameter.                           |
|or ESC [=0h     |                                            |
|or ESC [?7h     |                                            |
|                |Parameter  Meaning                          |
|                |                                            |
|                |    0       40 x 25 black and white         |
|                |    1       40 x 25 color                   |
|                |    2       80 x 25 black and white         |
|                |    3       80 x 25 color                   |
|                |    4      320 x 200 color                  |
|                |    5      320 x 200 black and white        |
|                |    6      640 x 200 black and white        |
|                |    7      Wrap at end of line. Typing past |
|                |           end-of-line results in new line. |
\-------------------------------------------------------------/



/-------------------------------------------------------------\
|Reset Mode (RM) |      Function                              |
|----------------+--------------------------------------------|
|   ESC [=#l     |      Parameters are the same as Set Mode   |
|or ESC [=l      |      (SM) except that parameter 7 resets   |
|or ESC [=0l     |      wrap at end-of-line mode (characters  |
|or ESC [?7l     |      past end-of-line are discarded).      |
\-------------------------------------------------------------/


Keyboard Key Reassignment

The ANSI system can be used to reassign keys on the keyboard. When an application calls KbdStringIn, the reassigned key's ASCII code is converted to the specified string and is passed back to the calling application. For example, replace a with q so that whenever the a key is pressed, a q is passed to the application that is reading input.

In OS/2 2.1, keyboard remapping can be done only from an application calling KbdStringIn. In DOS, keyboard remapping must be done from the command line.

Note:Keyboard reassignment works only with OS/2 applications that use the KbdStringIncall to get input.

OS/2 mode ANSI is affected when keys are reassigned in a code-page environment. ANSI "remembers" the code page under which a key is reassigned . The keyboard subsystem checks for reassigned keys when the application calls the KbdStringInfunction. When a reassigned key is detected, the ANSI support:

1.Checks to see what code page the requestor is running under
2.Looks internally to see if the key has been reassigned under that code page
3.If there is a key reassignment for that code page, gives the reassignment string
4.Otherwise, gives the original ASCII codes.

A maximum storage of 64KB can be allocated to OS/2 mode ANSI-reassigned key definitions. The table shown below contains the control sequences used to redefine the meaning of keyboard keys: 

/--------------------------------------------------------------\
| The control sequence is:     |Function                       |
|------------------------------+-------------------------------|
|    ESC [#;#;...#p            |The first ASCII code in the    |
|or  ESC ["string"p            |control sequence defines which |
|or  ESC [#;"string";#;#;      |code is being mapped.  The     |
|    "string";#p               |remaining numbers define the   |
|or  any other combination     |sequence of ASCII codes        |
|    of strings and decimal    |generated when this key is     |
|    numbers                   |intercepted.  However, if the  |
|                              |first code in the sequence is  |
|                              |0 (NULL), the first and second |
|                              |code make up an extended ASCII |
|                              |redefinition.                  |
\--------------------------------------------------------------/

To execute the examples below, either create a file that contains the following statements and then use the TYPE command to display the file that contains the statement, or execute the command at the OS/2 prompt:

�Assign the Aand akey to the Qand qkey, respectively.

�Assign the Qand qkey to the Aand akey, respectively:

Using a File: 



ESC [65;8lp          A becomes Q
ESC [97;113p         a becomes q
ESC [81;65p          Q becomes A
ESC [113;97p         q becomes a

At the OS/2 Prompt: 



prompt $e[65;8lp     A becomes Q
prompt $e[97;113p    a becomes q
prompt $e[81;65p     Q becomes A
prompt $e[113;97p    q becomes a

�Reassign the F10 key to a DIR command followed by a carriage return:

Using a File: 



ESC [0;68;"dir";13p

At the OS/2 Prompt: 



  prompt $e[0;68;"dir";13p

The $e is the prompt command characters for ESC. The 0;68 is the extended ASCII code for the F10 key; 13 decimal is a carriage return.

�The following example sets the prompt to display the current directory on the top of the screen and the current drive on the current line: 

    prompt $e[s$e[1;30f$e[K$p$e[u$n$g

If the current directory is C:\FILES, and the current drive is C, this example would display: 



             C:\FILES
C>

�The following DOS-compatible assembly language program reassigns the F10 key to a DIR B: command followed by a carriage return: 



        TITLE SET ANSI.ASM - SET F10 TO STRING FOR ANSI.SYS 

CSEG      SEGMENT   PARA   PUBLIC   ' CODE ' 
         ASSUME   CS : CSEG , DS : CSEG 
         ORG       100H 
ENTPT :    JMP       SHORT   START 
STRING    DB        27 , ' [ 0 ; 68 ; " DIR   B : " ; 13P '   ; Redefine   F10   key 
STRSIZ    EQU       $ - STRING                   ; Length   of   above   message 
HANDLE    EQU       1                           ; Pre - defined   file . 
                                            ; Handle   for   standard   output 

START     PROC      NEAR 
         MOV       BX , HANDLE                  ; Standard   output   device 
         MOV       CX , STRSIZ                  ; Get   size   of   text   to   be   sent 
         MOV       DX , OFFSET   STRING          ; Pass   offset   of   string 
                                            ; To   be   sent 
         MOV       AH , 40H                     ; Function = " write   to   device " 
         INT       21h                         ; Call   DOS 
         RET                                 ; Return   to   DOS 
START     ENDP 

CSEG      ENDS 
         END       ENTPT




DPRINTF Print Formatting Package

DPRINTF is a kernel-debugging print-formatting package. You can include this function in the code to test your display driver.

To use the DPRINTF function, you must have a second device attached to COM1 or COM2. Due to difficulties passing variable-length argument lists through a call-gate transition, only one argument, a 0-terminated string, is passed to this routine. The string is sent to either COM1 or COM2 depending on how the variable, UR_DAT, is defined.

The only checking that this routine performs is to process XON/XOFF characters from the equipment attached to the debug port. This guarantees that the output does not overrun the receiving device. However, after receiving XOFF, this routine spins in a loop, waiting for XON.

The string to be output is ASCIIZ. It may contain literal characters.

A literal character is defined as any character that is not part of a format specification. Special non-printing characters are listed as follows :

\n for CRLF (carriage return/linefeed)

\t for tab

\b for bell

\\ for \.




This chapter is based in part on the VESA SVPMI (Video Electronics Standards Association Super VGA Protect Mode Interface) proposal.

Display Device Driver Reference for OS/2:OS/2 Version Compatibility Considerations

Retrieved from "https://www.edm2.com/index.php?title=Display_Device_Driver_Reference_for_OS/2&oldid=26858"