Display Device Driver Reference for OS/2
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.
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:
- Disjointed (not special cased)
- Identical (not special cased)
- 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 \.
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 scratchfor 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
Virtual EGA device driverVEGA
Virtual MONO device driverVMONO
Virtual VGA device driverVVGA
Virtual XGA device driverVXGA
Virtual SVGA device driverSVGA
Virtual 8514/A device driverV8514A
The video devices for which OS/2 provides virtual video device drivers include:
�Western Digital
�ATI
�Cirrus Logic
�Headland
�IBM Super VGA
�Trident
�TSENG
�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
�Freezeand thawservices
�Title change and code-page change notification hooks
A significant amount of the primary virtual video device driver code involves communication with the DOS Session Window Manager. A Remote Procedure Call (RPC) mechanism must be used to communicate between the DOS Session Window Manager and a virtual video device driver under the following conditions:
�The DOS Session Window Manager is a Ring 3 component (lowest privilege level);
�Virtual device drivers run at Ring 0 (highest privilege level);
�DOS sessions have no Local Descriptor Table (LDT) and therefore cannot attach to Dynamic Link Libraries (DLLs).
For this purpose the DOS Session Window Manager creates a thread that calls the virtual video device driver to wait for a video event from any of the currently windowed DOS sessions.
Design of Installable Virtual Video Device Drivers
A virtual video device driver is a basedevice driver, although a "DEVICE=" statement in the CONFIG.SYS file is used to specify one or more virtual video device drivers to load. The DOS Session Manager and DOS Session Window Manager identify a virtual video device driver by its registered name. For example, a virtual video device driver for the primary display would register as VVIDEO1$; a virtual video device driver for the secondary display device would register as VVIDEO2$; and so forth.
Note:Support of multiple DOS sessions is disabled if no virtual video device driver claims ownership of the primary display device after virtual video device driver loading and initialization is completed.
Supporting DOS-Standard Adapters and Modes
IBM-compatible CGA, EGA, VGA, XGA, and 8514/A adapters are supported as primary display devices; monochrome adapters are supported as secondary display devices. For these devices, the standard configurations (including the amount of video memory, type of monitor and so forth), are supported. However, there are a few exceptions. For example, 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 2xxport configuration, instead of the standard 3xxAlso, 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 DosRequestVDDservice to:
�DOS Session Window Manager
-Set Access
-Set Focus
-Set Lock
-Query Mode Info
-Query Cursor Info
-Query Palette Info
-Copy LVB Content
-Copy Bit Map Content
-Wait for Video Event
-Control Event
�PM Display Device Driver
-Set Display Requirements
-Request off-screen VRAM
-Free off-screen VRAM
-Request VGA Controller
-Free VGA Controller
-Query VRAM Status
Note:See DOS Session Window Manager Servicesand Presentation Manager Display Driver Servicesfor a detailed explanation of the DosRequestVDDfunctions provided by the virtual video device driver.
There are two kinds of DOS session window support:
�Displaying a running image in a window
�Displaying a frozen image in a window
The latter is a subset of the former. The virtual video device driver always attempts to provide support for displaying a running image and for standard text and CGA graphics modes this is always possible, but there are graphics modes cases where that is not possible. One example is the 64KB EGA mode; other examples are the XGA and 8514/A modes.
Support for the XGA or 8514/A graphics modes is not a matter of sufficient memory but of the sheer complexity of virtualizing the 8514/A hardware. In addition, if a DOS application uses VGA graphics modes on an 8514/A system, it will not be able to use the VGA memory if a monitor, being used as a secondary display by other tasks in the system, is connected to the VGA.
There is no known reliable method of determining whether a monitor is connected to the VGA or Super VGA. The 8514/A can detect a limited set of IBM-compatible, fixed-frequency monitors, whereas the XGA, using DMQS, has the potential of identifying all monitor types, including OEMs.
In an 8514/A system, there is no architected way for the virtual video device driver to determine whether the VGA is in use by another process or session. Conversely, there is no way for the virtual video device driver to claim the device and prevent other processes or sessions from later acquiring the device.
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 framedevice.)
�Special consideration must be given to handling the passthrough-modecapability 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
�Allocating a Save and Restore video buffer
�Installing I/O hooks to shadow key video port accesses
�Mapping physical video memory into the appropriate video address space
�Coercing text-mode fonts to match the currently selected code page
�Providing pointer drawing services to the virtual mouse device driver to define, draw, and erase pointer images
When a DOS session does not own the physical display (that is, when it is in the background), the virtual video device drivers do the following:
�Install I/O hooks to track and emulate all video port accesses.
�Map appropriate system memory to the active portions of the video address space.
�Report video events to the DOS Session Window Manager (assuming the Presentation Manager is active and the DOS session is an unminimized window ). Such reporting includes changes to:
-Mode
-Palette
-Cursor
-Video memory
-Input events
-Scroll or string events
-Paste continue or terminate (through the virtual keyboard device driver)
-Session title change
-Screen-switch or video memory allocation errors
At any time, the DOS Session Window Manager (or other processes that have access to a DOS session's process ID) can update a DOS session's window state, as follows:
�Windowed or non-windowed
�Focused or non-focused
�Minimized or un-minimized
�Locked or unlocked
Any aspect of a DOS session's video state can be queried as follows:
�Mode
�Palette
�Cursor
�Video memory
�Wait for video events
�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 "C" 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
�Hide Pointer
�Define Text Pointer
�Define Graphics Pointer
�Set Video Page
�Set Light-Pen Emulation
Also, whenever the DOS session changes video modes (including the initial mode change 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.
/--- 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. | | | \----------------------------------------------------------/
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.
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. */
);
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).
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. */
);
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.
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. */
);
where VVPOST is a structure containing:
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 . * /
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 Releaseand Acceptdevice. In this case, the Save Restore request is supported by the VGA virtual video device driver.
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. */
);
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.
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. */
);
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.
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. */
);
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.
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 . * /
) ;
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.
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. */
);
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
�Save or restore the video state
�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:
DEVICE=C:\OS2\MDOS\VVGA.SYS
DEVICE=C:\OS2\MDOS\V8514A.SYS
The virtual XGA device driver statements, which are required in the CONFIG. SYS file, are added during installation when the presence of an XGA adapter is detected:
DEVICE=C:\OS2\MDOS\VVGA.SYS
DEVICE=C:\OS2\MDOS\VXGA.SYS
The following items should be set in DOS to enable a DOS session:
�Enable I/O trapping to permit the virtual video device driver to save and restore the hardware instance used by a DOS application when the application switches away from the foreground DOS session. The virtual video device driver allocates a buffer to save the video image. The maximum size of this buffer is 1MB and is obtained each time a full-screen DOS session is created.
Enabling I/O trapping is the default. Although multiple instances of XGA can be present on a system, the virtual XGA device driver saves or restores only the state of the first instance used by a DOS application. It is the application's responsibility to save or restore the other XGA instances.
�Register for screen switch notification. This implies that a DOS application has hooked INT 2Fh so as to be notified when it is to be switched to full-screen foreground or background. This notification informs the application that it must restore the screen when switched to full- screen foreground, and must stop accessing video memory (to avoid freezing) when switched to background.
An application that uses more than one instance of XGA must specify this option to save and restore the states of the other XGA adapters. The default is no VIDEO_SWITCH_NOTIFICATION.
Any DOS session that is not saved or restored by the virtual video device driver cannot be displayed in a window. DOS 8514/A and XGA applications are not interactive in a window; they can 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 VDHRequestVDDservices for the virtual keyboard device driver:
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. */
The PEEK and READ notifications occur prior to the actual operation; fAvailis 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, fContinueis 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.
/--- 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. | | | \----------------------------------------------------------/
Virtual Mouse Device Driver Services
For the virtual mouse device driver, the virtual video device driver provides a VDHRequestVDDfunction, as well as several direct interfaces for pointer drawing operations.
The following VDHRequestVDDservice is provided:
VDHRequestVDD
(
HVDD hvddVideo,
HVDM hvdm,
INT iFunc, /* Virtual video device */
/* driverEVREQ_POSTMOUSE (4) */
PVOID pReqIn, /* Undefined. */
PVOID pReqOut /* Undefined. */
); /* Returns TRUE. */
The virtual mouse device driver must return the address of a function that permits the virtual video device driver to obtain mouse position and button status during processing of the INT 10h, Query Light Pen function, when light pen emulation is enabled for the active DOS session. Also, whenever the DOS session changes video modes (including the initial mode change that takes place during DOS-session creation), the virtual video device driver notifies the virtual mouse device driver 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 VDHRequestVDDto 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.)
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 */
where VMREG is a structure containing all the direct-call addresses:
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;
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:
typedef struct vmfunc_s
{
ULONG nb; /* Size of structure, */
/* in bytes (8) */
PFNQUERYSTAT pfnQueryStatus; /* Ptr to query virtual */
/* status proc. */
} VMFUNC;
The virtual video device driver also uses VDHRequestVDDto notify the virtual mouse device driver of changes in video mode:
VDHRequestVDD
(
HVDD hvddMouse,
HVDM hvdm,
INT iFunc, /* VMDEVREQ_SETSIZE (2) */
PVMSS pvmss, /* Pointer to VMSS structure */
PVOID pReqOut /* Undefined */
);
where VMSS is a structure containing the following information:
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;
The direct-call interfaces supplied by virtual video device drivers are defined as follows:
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 * /
For reference, the function supplied by a virtual mouse device driver to a virtual video device driver is defined as follows:
BOOL FNQUERYSTAT VMQueryStatus
(
HVDM hvdm, /* DOS session handle, or */
/* CURRENT_VDM */
PVMSTAT pvmstat /* Pointer to VMSTAT info structure */
); /* Returns TRUE */
where VMSTAT is a structure containing:
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
/--- 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. | | | \----------------------------------------------------------/
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 DOSRequestVDDservices:
�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 refreshedevents so that all DOS-session windows are repainted.
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.)
�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.
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)
�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 VDHFreezeand VDHThawservices, instead of a lazylock, 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.
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 . )
�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.
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.)
where VVMODE is a structure containing:
/*
** 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 */
�The Query Cursor request returns current cursor position and shape information for the DOS session:
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.)
where VVCURSOR is a structure containing:
/*
** 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 ;
�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:
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.)
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:
typedef struct rgb_s
{
BYTE bBlue;
BYTE bGreen;
BYTE bRed;
} RGB;
�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:
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.)
where RECTL is a structure defining the region to be copied:
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;
and where pOutputpoints 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.
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.)
where VVRECT is a structure defining the region to be copied and how it is to be copied:
/*
** 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;
and where pOutputpoints 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.
ulDDFormatin 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 ulDDFormatin 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:
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.)
where VVEVENT is filled in with the following information:
/*
** 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 * /
and the buffer addressed by pInputis filled in with:
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)
For all the above events, nDatawill 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), nDatawill equal 0, as no additional data is returned with those notifications.
�The Control Eventrequest provides several subfunctions that control the event thread (that is, any thread dedicated to the WAITEVENT request).
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)
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 DOSRequestVDDservices 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 firsttime it initializes the display, during system initialization):
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.)
where VVDRQ is a structure defining the region to be copied and how it is to be copied:
/*
** 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 */
and in which the PVVREG pointer points to one or more structures (as indicated by nShadowRegs) containing:
/*
** 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;
pPhysVRAM
indicates the starting physical address for VGA VRAM that the display driver will use (for example, A0000h).
nbReserved
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 nbReservedyields the amount of off- screen memory to be managed by the virtual video device driver.
offLatchByte
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
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
is another 16:16 pointer-to-byte flag that is 0if the controller is currently unowned, or 1if 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 CtrlNotifybyte 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
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.
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.)
On successful return, pOutputpoints to an offset (relative to pPhysVRAM) of one or more contiguous pages of off-screen VGA memory.
/--- 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 . | | | \ ---------- ---------- ---------- ---------- ---------- -------- /
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.
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.)
�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 fCtrlOwnedbyte flag (see the VVDRQ data structure description in the section titled Presentation Manager Display Driver Services).
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.)
�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 fCtrlNotifybyte flag (see the VVDRQ data structure description in the section titled Presentation Manager Display Driver Services).
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.)
�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.
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.)
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 VDHRequestVDDservices for other virtual video device drivers. Some of the common services provided are listed below:
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 */
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 DosRequestVDDand VDHRequestVDDrequests 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:
/*
** 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 * /
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 suspendedstate, 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 cleanstate. 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:
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 Lockand 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 TrapRegssection 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 UnLocksections literally are used to perform the specified functions. Cleanupis 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-ahleFgndwhen the DOS session is foreground, and ahleBgndwhen 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 - apleAlland apleNoTrap, which contain port addresses and pointers to data areas for each indexed and non-indexed port. apleNoTraphas 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 apleAllarray 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 apleNoTraparray 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 guessas 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 Backgroundprocess 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.
Seamless Windows Support
Seamless support provides the ability to execute Windows applications in one or more windows on the OS/2 Desktop. The Windows applications run side by side with OS/2 Presentation Manager (PM) applications. To provide seamless support, you must modify both the PM and Windows display drivers.
Overview
Each seamless windows session is run as a protect-mode DOS session. The seamless session runs a copy of the Windows video display driver, modified to operate seamlessly. Seamless windows drivers write directly to the video display hardware, and must be modified to coordinate and serialize hardware access. As a result, a seamless windows driver actually "owns" a piece of the PM Desktop.
In addition to modifications to the PM and Windows drivers, the IBM Operating System/2 itself has been modified to support seamless operation. A special virtual device driver (VWIN) is used to establish limited addressability to a small set of key PM routines and data, as well as to provide services permitting hardware serialization and exchange of Windows state-change information.
[Artwork not shown]
Presentation Manager Display Device Driver
To enable a seamless session, the Presentation Manager display device driver must call the special virtual device driver, VWIN, using DOSRequestVDD. The PM driver passes initialization data to enable the seamless windows driver's access to necessary PM data and the shared data and code. After initialization, the PM driver again calls VWIN to define the current video mode and cursor size.
The PM display driver is responsible for initializing a fast safe RAM semaphore. (FSRamSemaphore) for synchronizing access to the video hardware. Both the PM and the seamless windows drivers must use the FSRamSemaphoreto coordinate video access. The PM driver can force release of this semaphore when necessary, for example, if the seamless DOS session stops with the Windows driver owning the semaphore. To avoid forcing an inappropriate semaphore release, heartbeat processinghas been incorporated into VWIN. The PM driver requests VWIN to initiate heartbeat processing when a timeout occurs on the PM driver's request for the FSRamSemaphore.
The PM Shield component, shown in the diagram in the previous figure, communicates with the PM driver, sending notifications whenever a seamless DOS session is created or destroyed. This enables the PM driver to modify its processing logic to be compatible with the seamless environment.
There are several other calls the PM video driver can issue to VWIN. At PM deathand resurrection(that is, on a switch to a full-screen DOS or WIN-OS /2 session), the driver calls VWIN to broadcast suspend/resume drawing messages to the seamless DOS sessions. These messages are transmitted to the DOS session's drivers by way of INT 2Fh.
Seamless Windows Display Device Driver
The seamless windows display device driver is usually derived from the standard Windows driver by conditional compilation. It must always start in the disabled state to establish all necessary addressability and data before beginning seamless operation. To start in a disabled state, the driver must simulate an INT 2Fh, Function 4001h, at startup. The seamless windows driver hooks INT 2Fh to receive all notifications of foreground- background switching. The Win Shieldcomponent, diagrammed in the previous figure, enables the seamless windows driver, using INT 2Fh, Function 4002h, when synchronized with the Presentation Manager Desktop.
Because the virtual display driver and the Win Shield have the ability to disable video output from the Windows driver (through INT 2FhH), a cumulative disable count must be kept in the driver. When a Disable occurs (INT 2Fh, AX=4001h), the count is incremented. On the first increment ( count = 1), output from the driver is disabled. Alternately, when an Enable occurs (INT 2Fh, AX=4002h), the count is decremented. When the count is 0, driver output can be enabled.
Most seamless processing and message handling is asynchronous; therefore, it is possible for multiple Disables to be received before any Enables take place. Events are posted to the DOS session and retained until a time sliceoccurs and they can be processed. As stated previously, a cumulative disable count is required.
At seamless windows driver startup, the driver must begin with a Disable count of 1 (in effect, forcing an INT 2Fh Disable on itself) to permit all the window shadowsfrom the desktop to be reflected to the DOS session's Win Shield. When this process is complete, the Win Shield enables the seamless windows driver by way of INT 2Fh.
When the first Enable() call is received, the seamless windows display driver must call VWIN, passing it a pointer to a WINDD_INIT structure. (The WINDD_INIT structure is described in detail later in the text.) VWIN completes this structure for the Windows driver.
It is critical for the seamless windows driver to coordinate all hardware access, using the video FSRamSemaphore, and it must always reset the video hardware to a default state upon release of the semaphore.
The seamless windows driver need not perform any cursor drawing operations, nor does it need to save and restore hardware registers when switched to the background. These functions are performed by the Presentation Manager driver. However, the seamless driver must call the PM cursor-exclusion routines when outputting to the screen, to protect the mouse pointer and prevent its erasure.
Presentation Manager Shield
The PM Shield maintains Workplace Shell windowing-state information, including that related to the seamless DOS sessions.
Upon creation of a seamless DOS session, the PM Shield notifies the virtual video device driver (for example, VVGA or VSVGA) to permit direct hardware access. Normally, the virtual video drivers control and intercept attempts to access the hardware. In a seamless DOS session, however, virtual video is modified to permit this hardware I/O.
As windowing-related events occur in the seamless DOS sessions, the PM Shield duplicates these events in the Workplace Shell to track the seamless DOS sessions. Examples of windowing events are:
�Create
�Destroy
�Move
�Resize
In addition to monitoring the seamless DOS sessions, the PM Shield registers with PMWIN to be posted whenever events occur that alter the state of the desktop. (Again, events such as Create and Destroy are monitored.) These events are forwarded to VWIN, which broadcasts them to the Win Shield in each seamless DOS session.
Windows Shield
The Windows (Win) Shield is the Windows counterpart of the PM Shield. It is both an executable file and a dynamic link library (WINSHELD.EXE and WINSMSG.DLL, respectively). Win Shield serves a complementary purpose, maintaining Workplace Shell windowing-state information for its DOS session .
Initial state information for the desktop is received when the Win Shield registers with VWIN. Subsequently, VWIN notifies the Win Shield whenever changes on the desktop occur. All the desktop information is received from the PM Shield and passed on by VWIN.
Additionally, the Win Shield registers with the Windows User component to obtain notification of internal Windows events. This information is then forwarded to VWIN to update the PM Shield.
VWIN Virtual Device Driver
VWIN is the special virtual device driver that lies at the heart of seamless operation. VWIN shares all Windows and PM Desktop windowing-state information, permits addressability to seamless data and code shared between the PM and Windows display drivers, and sends INT 2Fh notification to each seamless DOS session at PM death and resurrection, as described previously.
Interface to VWIN is achieved using the following two mechanisms:
�PM services are requested using DOSRequestVDD.
�Windows services are requested through INT 66h.
Note:The Windows services must be requested by an interrupt because VWIN executes at Ring 0 (the highest privilege level) and the seamless windows drivers do not.
Distributed Console Access Facility (DCAF)
Seamless Windows support is provided in DCAF for installations that require remote console functions between programmable workstations.
In OS/2 2.1, Seamless Windows is supported by allowing the Windows display driver to draw directly on the Presentation Manager (PM) screen. This means that Seamless Windows updates do not go through the PM drawing functions and, therefore, will not update the active screen change area (SCA) in the usual way. As a result, Seamless Windows requires special treatment.
Prior to drawing on the PM screen, the Seamless Windows driver calls the PM driver through an exported entry point, SeamlessExcludeCursor. This call excludes the PM cursor from the area in which the Seamless Driver is about to draw. The modified XGA display driver intercepts this call and passes the rectangle coordinates to AccumulateScreenBounds.
Under DCAF, during PM display driver initialization, Seamless Windows must be granted addressability to all data and code that it will access during the call to SeamlessExcludeCursor. In order to add the supplied rectangle to all active SCAs, which can reside anywhere in the display driver heap, there is a single, static SSA (Seamless Screen Area called scaSeamless) used for this purpose. All Seamless bounding rectangles will be accumulated in scaSeamless; then, this SCA is merged with the other active SCAs when a query is issued via GreGetScreenChangeArea.
As a result, at initialization (in InitializeSeamless), the Seamless Windows driver is given access to AccumulateScreenBounds, to scaSeamless and to the DDT display driver control block, in order to retrieve the screen dimension at seamless time. The addresses of this data are stored in the SeamlessAddresses control block, owned by the Windows driver.
Before writing to the PM screen, the Seamless Windows driver will call SeamlessExcludeCursor. The exclusion rectangle will be passed in the following registers in so-called AI coordinates (i.e., 16-bit inclusive; 0, 0 is top left of screen):
- Left cx
- Top dx
- Right si
- Bottom di
The display driver will determine whether the new bounds accumulation is needed by checking the value of the pStartSCA pointer and, in SeamlessExcludeCursor32, will call AccumulateSeamlessBounds to initiate the bounds accumulation. AccumulateSeamlessBounds converts the passed rectangle to EXCLUSIVE SCREEN coordinates, clips the rectangle to the screen dimensions and calls AccumulateScreenBounds. This causes the rectangle supplied to SeamlessExcludeCursor to be added to only scaSeamless. When an SCA is queried using GreGetScreenChangeArea, the Seamless SCA is merged with the active SCAs and then reset to NULL.
Seamless Design Issues
There are multiple design issues in the seamless environment. The critical issues (those generating the most questions), are documented in the following sections:
�Determination of code and data to be shared between the PM and Windows display drivers
�Coordination of off-screen video RAM
�Save/restore processing of the video hardware registers/environment
�Implementation of semaphore and heartbeatprocessing
�Conversion of Windows cursors and icons in the PM environment
�Palette handling
�Sharing of cursor exclusion and Enable/Disable code, including problems to be avoided
�Setup and sharing of a pointer to video RAM.
Each design of seamless PM and Windows driver pairsrequires its own shared data/code structure, because each driver implementation and its underlying video hardware are unique. The contents of the structure varies across implementations. The shared data/code structure for seamless XGA is included in the following example:
PMDD_IO_STRUC struc
LevelID dd ? ; 4 bytes to sync interface to PMDD.
; The following variables are in the PM DD's default data segment.
ulMemRegBase dd ? ; 16:16 addr of memory mapped XGA regs
usIORegBase dw ? ; Base of IO XGA regs
ulVramBase dd ? ; 32-bit physical memory addr of VRAM
ulVramSize dd ? ; Size of VRAM in bytes
bfUseExternalPolling db ? ; TRUE if external polling is supported
usScreenWidthMM dw ?
usScreenHeightMM dw ?
usScreenWidthPels dw ?
usScreenHeightPels dw ?
bBitsPerPel db ?
pSemaphore dd ? ; Flat pointer to FSRamSemaphore
pHeartBeat dd ? ; Flat pointer to heartbeat counter
pNumDefaultColors dd ? ; Flat ptr to # of default colors in use
pCursorStatus dd ? ; Byte ptr: bit 0x80 set if sfw cursor
pExcludeCursor dd ? ; 16:16 addr of exclude cursor function
pDisableCursor dd ? ; 16:16 addr of disable cursor function
pEnableCursor dd ? ; 16:16 addr of enable cursor function
WindowsPrivateArea db WINDOWS_PRIVATE_AREA_SIZE dup (?)
;------------------------------------------------------------------
; Information shared among the XGA Windows' drivers.
; Multiple Windows drivers can exist, running in multiple DOS sessions.
; SecondaryFontStart dd ?
; SecondaryFontEnd dd ?
;
; SystemFontTable dd 256 dup (?)
; SecondaryFontTable dd 256 dup (?)
;
; SystemFontHeight dw ?
; SystemFontPoints dw ?
; SystemFontWidth dw ?
; SystemFontCached db 0
;
; SecondaryFontName db 0
; db 32 dup (?) ; Max facename length=32.
;
; SecondaryFontNameLen dw 1
; SecondaryFontHeight dw 0
; SecondaryFontPoints dw 0
; SecondaryFontWidth dw 0
;
; SecondaryFontHdr db 32 dup(0)
; SystemFontHdr dw 16 dup(0)
; PaddedField db 32 dup(0) ; Remaining reserved.
;------------------------------------------------------------------
; Total 2200 bytes reserved by the PM driver for Windows' drivers.
bfPaletteIsFixed db ; TRUE if palette manager not enabled
ulLastPalUpdate dd ; Timestamp of last foreground realize
pHWPalette dd ; 16:16 ptr to HWPalette structure
PMKWSPhysicalBase dw ; Physical addr of 64KB kernel workspace for
; bus-mastering into/out of system memory
PMKWSLinearBAse dd ; Linear addr of 64KB workspace
PMDD_IO_STRUC ends
The initial entry in this shared structure must be a driver signature. For XGA, the signature is XG01. For VGA, the signature is VG01. This field must be checked by the Windows driver at initialization. If an incorrect entry is found, the Windows driver must report initialization failure to the GDI. This mechanism prohibits the running of non-compatible seamless driver pairs (for example, using a VGA seamless windows driver with a Presentation Manager XGA driver).
Coordination of Off-Screen Video RAM
A static division of off-screen video memory is typically employed to permit access to this resource for both the Presentation Manager and seamless windows drivers. Alternatively, dynamic allocation or total dedication of the memory to one driver is used. However, these alternatives could decrease performance.
At a minimum, both the PM and seamless windows drivers' character caches are maintained in off-screen video memory for the sake of performance.
Save/Restore Processing of Video Registers/Hardware
A straightforward approach to save/restore processing is to force both the PM and seamless windows drivers to explicitly set video hardware registers anytime the registers are required. Since the video FSRamSemaphoremust be used to coordinate hardware access, this semaphore can be obtained, the necessary register(s) set and used, and the semaphore released with no problem.
An alternative approach is to design the necessary save/restore processing and mark the associated registers and resources with handles(such as SessionIDs).
Implementation of Semaphore Processing
Most 16-bit presentation drivers use the FSRamSemaphoremechanism to serialize output. This same mechanism is used by the PM and seamless windows drivers in the 32-bit environment. FSRamSemaphoresuse the drivers' data area to store the semaphore. Therefore, the Presentation Manager driver must establish the semaphore and provide its address to the seamless windows driver in the shared data/code structure. This logic flow is true for both the 16-bit and 32-bit environments.
In the 32-bit environment, there are new FSRamSemaphoreentry points, and 16-bit drivers now have alternative entry points. The new entry points have been optimized for efficiency. The following is a list of both the new and alternative semaphore entry points:
/-------------------------------------------------------------\ |New and Alternative Entry |Original Entry Points | |Points | | |------------------------------+------------------------------| |RAMSEMREQUEST16 |FSRSemEnter | |------------------------------+------------------------------| |RAMSEMCLEAR16 |FSRSemLeave | |------------------------------+------------------------------| |RAMSEMREQUEST32 | | |------------------------------+------------------------------| |RAMSEMCLEAR32 | | \-------------------------------------------------------------/
The semaphore entry points all have one parameter-a pointer to a FSRamSemaphorestructure. The structure contains the following fields:
usLength Length of structure usPadding usProcessID ID of owning process usThreadID ID of owning thread usUsage Usage counter usClient Client field, see note below ulTimeout System default timeout value ulRamSem Semaphore
Note:The usClientfield is the only field that, for normal processing, the presentation driver should access directly. This field is initialized as 0 when the semaphore is first acquired and thereafter is controlled by the driver. The intention is to give a DC some way of flagging a semaphore to notify the driver's ExitList processing routine of any special action it needs to take when releasing the semaphores.
The RAMSEMREQUESTxx functions return 0 if successful, and a nonzero error code otherwise.
The RAMSEMCLEARxx functions have no return information, and are void functions.
To support FSRamSemaphores, 32-bit Presentation Manager drivers must link with the OS2386 library, and 16-bit drivers must link with the OS2286 library.
To use FSRamSemaphoresfor coordinating hardware access, the seamless windows drivers must implement request_semaphore() and clear_semaphore() code logic. The purpose of request_semaphore() is to own the semaphore; clear_semaphore() relinquishes ownership.
When requesting the semaphore (if it is already owned by the current process), the semaphore's usage count must be incremented. If the semaphore is available, it is marked as owned by the current process. However, if the semaphore is owned by a different process, a call is made (indirectly) to the OS/2 kernel to block the thread until the semaphore is released. The mechanism for calling the OS/2 block_semaphore function is to issue an INT 66h to VWIN with some parameters passed through registers. VWIN then calls OS/2 block_semaphore on behalf of the seamless windows driver to wait on the specified FSRamSemaphore. The following code section illustrates how to acquire the FSRamSemaphore:
mov ax, _DATA
mov ds, ax
assumes ds , Data
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; Get our process ID and thread ID
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
mov cx , init _ struct . thread _ id ; Get the current thread ID
mov dx , init _ struct . proc _ id ; and current process
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; Get addressability to the hardware semaphore structure
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
mov di , PMDD _ IO _ SEL ; PM selector
mov fs , di
mov edi , init _ struct . pmdd _ io ; FS : EDI - > pmdd _ io struct
mov edi , fs : [ edi ] . pSemaphore ; FS : EDI - > pSemaphore
sem _ retry :
mov ax , word ptr fs : [ edi ] . fs _ ProcID ; Touch the page
cli
mov ax , word ptr fs : [ edi ] . fs _ ProcID ; Is the semaphore owned ?
or ax , ax
jnz SHORT sem _ owned ; Yes , see if it is caller ?
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; Here , if the semaphore is currently unowned , marked as owned by the
; current process ID and thread ID ; set the usage count to 1 and mark
; the RAM semaphore as SET .
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
mov WORD PTR fs : [ edi ] . fs _ ProcID , dx
mov WORD PTR fs : [ edi ] . fs _ ThrdID , cx
mov ax , 1
mov fs : [ edi ] . fs _ Usage , ax ; Set usage count to 1 .
mov fs : [ edi ] . fs _ RAMSem . RamSemOwner , al ; Set RAM semaphore .
sti
jmp SHORT request _ semaphore _ exit
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; Here , if the semaphore is currently owned . Check to see if current
; owner is the caller .
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
sem _ owned :
cmp ax , dx ; Is the semaphore owned
by caller ?
; Essentially , pidOwner
= = pidCaller ?
jne SHORT sem _ owned2 ; No , go wait .
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; If the semaphore is already owned by the current process ID and
; thread ID , then nothing to do but increment the usage count .
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
inc fs : [ edi ] . fs _ Usage
sti
jmp SHORT request _ semaphore _ exit
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; If the semaphore is already owned by some other process ID and
; thread ID , then perform an INT 66h to request the VDD ( VWIN )
; to call the CPDOS RAM Semaphore mechanism on our behalf . When
; it returns , jump back to the beginning of this function to try
; to get the semaphore again .
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
sem _ owned2 :
sti
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; Block this thread until the semaphore is available .
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
; AH = 82H ( Function Code for VWIN )
xor ax , ax
mov ah , VWIN _ SEM _ BLOCK ; Block for semaphore function
; ECX - > Semaphore timeout
mov ecx , fs : [ edi ] . fs _ Timeout
; EBX - > CPDOS RAM Semaphore
; Thunk the high word of the 32 - bit offset in esi into 16 : 16 addr in ebx
; ie , multiply high word by 8 and set the LS 3 bits on .
lea esi , fs : [ edi ] . fs _ RAMSem
shld ebx , esi , 19
or bx , 7
shl ebx , 16
mov bx , si
; Set DS : SI to " VWIN "
mov si , OFFSET vwin _ id
; Block on the semaphore
pushf
call DWORD PTR init _ struct . pfvwin
; * * * * int 66h
jmp sem _ retry ; Go back and try to get it
request _ semaphore _ exit :
mov edi , Heartbeat
inc DWORD PTR fs : [ edi ] ; Increment the heartbeat counter
. . . . .
When clearing the semaphore, the seamless windows driver should decrement the FSRamSemaphore's usage count. When this usage count reaches 0 (after decrementing), the semaphore's RamSemFlagfield is saved, and then the entire semaphore structure is set as not owned. The saved RamSemFlagis checked (TRUE or FALSE) to determine whether any processes that are being blocked by the semaphore need to be unblocked. To unblock a requesting process, an INT 66h is issued to VWIN with the parameters passed in the appropriate registers. VWIN then invokes the OS/2 kernel wake_up function. The following code fragment shows how to clear the FSRamSemaphore:
mov ax, _DATA
mov ds, ax
assumes ds, Data
;---------------------------------------------------------------------
; Get our process ID and thread ID
;---------------------------------------------------------------------
mov cx, init_struct.thread_id ; Get current thread ID
mov dx, init_struct.proc_id ; and current process ID
;---------------------------------------------------------------------
; Get addressability to the Hardware Semaphore structure
;---------------------------------------------------------------------
mov di, PMDD_IO_SEL ; PM selector
mov fs, di
mov edi, Init_struct.pmdd_io ; FS:DI -> pmdd_io struct
mov edi, fs:[edi].pSemaphore ; FS:DI -> pSemaphore
mov ax, fs:[edi].fs_ProcID ; Touch the page
cli
;---------------------------------------------------------------------
; See if semaphore is owned by calling process/thread
;---------------------------------------------------------------------
cmp fs:[edi].fs_Usage, 0 ; See if owned
je SHORT sem_leavebad ; No, declare an error
mov ax, fs:[edi].fs_ProcID
cmp dx, ax ; pidOwner == pidCaller?
jne SHORT sem_leavebad ; No, declare an error
jmp SHORT sem_leaveok ; Yes, proceed
sem_leavebad:
sti
jmp SHORT exit_clear_semaphore
sem_leaveok:
;---------------------------------------------------------------------
; Decrement the usage count
;---------------------------------------------------------------------
dec fs:[edi].fs_Usage ; Decrement the usage count
jz SHORT release_sem
sti
jmp exit_clear_semaphore
;---------------------------------------------------------------------
; Release the semaphore by setting the process ID and thread ID
; fields to 0, clearing the RAM semaphore and remembering if any
; other threads were waiting on the RAM semaphore. If not, re-enable
; interrupts and return.
;---------------------------------------------------------------------
release_sem:
xor dx, dx
mov word ptr fs:[edi].fs_ProcID, dx ; Clear pid
mov word ptr fs:[edi].fs_ThrdID, dx ; Clear tid
mov fs:[edi].fs_Client, dx ; Clear client
mov fs:[edi].fs_RAMSem.RamSemOwner, dl ; Clear ramsemowner
xor cx, cx ; Clear the cx register
xchg fs:[edi].fs_RAMSem.RamSemFlag, cl ; and set it to the sem flag
or cx, cx ; Is the sem being requested?
jnz SHORT sem_waiting ; Yes, call wakeup
sti
jmp SHORT exit_clear_semaphore
;---------------------------------------------------------------------
; Some other process/thread is waiting for this semaphore. Perform an
; INT 66h with the appropriate function, which will call the CPDOS
; wakeup code (done through the VDD) to unblock all of the waiting
; threads. Non-deterministic as to which one will actually get the
; semaphore first. The others will have to wait again.
;---------------------------------------------------------------------
sem_waiting:
sti
;--------------------------------------------------------------------
; Issue the INT 66h call to wake up any threads that are blocked on
; the semaphore.
;--------------------------------------------------------------------
; AH = 83H ( Function Code for VWIN )
xor ax, ax
mov ah, VWIN_SEM_WAKE ; Wake function
; Set DI:SI to "VWIN"
mov si, OFFSET vwin_id
; EBX -> CPDOS RAM Semaphore
; Thunk the high word of the 32-bit offset in edit into 16:16 addr in ebx
; ie, multiply the high-word by 8 and set the LS 3 bits ON.
lea edi, fs:[edi].fs_RAMSem
shld ebx, edi, 19
or bx, 7
shl ebx, 16
mov bx, di
; Block on the semaphore. CX should contain the old RamSemFlag value.
pushf
call DWORD PTR init_struct.pfvwin
;**** int 66H
exit _ clear _ semaphore :
. . . . .
At times, the PM driver must free the video semaphore to continue processing. This might be required in the case of a DOS session failure when the seamless windows driver is the semaphore owner. Sample semaphore release processing is included in the following code fragment. It is important to note that, in freeing the semaphore, the PM driver's process ID and thread ID (PID/TID) must be placed in the semaphore structure.
VOID SeamlessForceSemRelease(VOID)
{
PTIB pThreadInfo;
PPIB pProcessInfo;
/***********************************************************/
/* Set the semaphore owner to be us. The changing of the */
/* semaphore owner must be atomic to avoid letting in any */
/* other threads. */
/***********************************************************/
DosGetInfoBlocks(&pThreadInfo,
&pProcessInfo);
// FSRDriverSem.ProcID = (USHORT) pProcessInfo->pib_ulpid;
// FSRDriverSem.ThrdID = (USHORT) pThreadInfo->tib_ptib2->tib2_ultid;
*((PULONG)&FSRDriverSem.ProcID) =
((pThreadInfo->tib_ptib2->tib2_ultid) << 16) |
(pProcessInfo->pib_ulpid);
/****************************************************************/
/* Free the semaphore. */
/****************************************************************/
while (FSRDriverSem.Usage != 0)
{
ReleaseDriverSemaphore();
}
}
Implementation of Heartbeat Processing
For seamless windows drivers, the only heartbeat processing required is to increment the heartbeat counter in the PM and Windows shared data/code structure. This counter must be incremented after obtaining the video hardware semaphore and prior to accessing the hardware.
The counter is checked by the PM driver as part of its semaphore timeout logic. Upon a second timeout, if the semaphore owner is unchanged and the heartbeat counter also is unchanged, the Presentation Manager driver will assume that the DOS session is hung and try to force release of the video semaphore. The following code sequence demonstrates this processing logic:
/********************************************************************/
/* This function carries out PM Heartbeat Processing. */
/* It detects when the Windows driver has stopped while */
/* holding the semaphore and tidies up if need be. */
/********************************************************************/
VOID SeamlessHeartbeat(VOID)
{
HVDD hSeamlessVDD;
ULONG ulReturnCode;
/******************************************************************/
/* If seamless windows is not enabled, we do nothing. */
/******************************************************************/
if (fSeamlessEnabled)
{
/**************************************************************/
/* See if we are timing out for the second time with the same */
/* PID, TID, and heartbeat. */
/**************************************************************/
if ( (usHeartBeatPID == FSRDriverSem.ProcID)
&& (usHeartBeatTID == FSRDriverSem.ThrdID)
&& (ulHeartBeat == 0))
{
/**********************************************************/
/* This is the second time we have timed out with the */
/* same PID and TID owning the semaphore and the heart */
/* beat has not changed. We must call VWIN to see if a */
/* clean up is required. */
/**********************************************************/
/**********************************************************/
/* Open the seamless VDD ("VWIN"). */
/**********************************************************/
ulReturnCode = DosOpenVDD("VWIN", &hSeamlessVDD);
if (ulReturnCode != 0)
{
/******************************************************/
/* The DosOpenVDD call encountered an error of some */
/* sort! */
/******************************************************/
LogDosError(ulReturnCode);
return;
}
/**********************************************************/
/* Send VWIN the timeout on semaphore signal. */
/**********************************************************/
ulReturnCode = DosRequestVDD(hSeamlessVDD,
NULL,
VWIN_HEARTBEAT,
FSRDriverSem.ProcID,
NULL,
FSRDriverSem.ThrdID,
NULL);
if ((ulReturnCode == 0) || (ulReturnCode == 2))
{
/******************************************************/
/* The return code indicates that we should clean up. */
/******************************************************/
SeamlessForceSemRelease();
/******************************************************/
/* Clean up other heartbeat stuff. */
/******************************************************/
usHeartBeatPID = 0;
usHeartBeatTID = 0;
ulHeartBeat = 0;
}
/**********************************************************/
/* Close the handle to VWIN. */
/**********************************************************/
DosCloseVDD(hSeamlessVDD);
}
else
{
/**********************************************************/
/* Just record the PID and TID of the semaphore owner and */
/* reset the heartbeat counter. */
/**********************************************************/
usHeartBeatPID = FSRDriverSem.ProcID;
usHeartBeatTID = FSRDriverSem.ThrdID;
ulHeartBeat = 0;
}
}
}
Windows Cursors and Icons in the PM Environment
The Windows standard cursors (crossbar, arrow, etc.) have been converted to PM resources as part of the seamless VGA and XGA development. These resources are used, unchanged, by the PM driver. It is important to notice that when the cursor is over a seamless windows application, Windows cursors should appear, not Presentation Manager resources. The converted standard Windows cursors are provided as PM resource files.
Non-standard Windows cursors and icons are passed by the Win Shield component to the PM Shield and, ultimately, to the PM driver, for conversion when they are created by an application.
Palette Handling
Seamless palette management is achieved using the existing seamless components, hardware synchronization, and event-flow mechanisms. Currently, the Windows GDI component handles all palette issues, calling the Windows driver only to actually set the hardware registers. This processing must be modified for seamless palette management. to permit only palette realizations by PM, using the PM driver palette logic.
Note:PM Palette Management is actually a superset of Windows Palette Management in that PM must coordinate logical color table processing ( default palette) as well as permit palette changes by way of the Palette Management interface. There is so much similarity in the PM and Windows palette application calls and processing that permitting PM to process a Windows palette realization is quite straightforward.
The Windows GDI has been modified to request palette entries and changes through normal OS/2 GPI/GRE processing. Also, the color mapping of the 20 Windows system colors must be supported in the PM driver palette. This requires a remapping of the PM palette, moving the 20 Windows colors to the top 10 slots and bottom 10 slots of the physical palette. Remapping the PM palette involves moving entries such that the closest entry to the Windows default color is at the specified location. Later, a translation table is used by PM when the driver selects a "closest fit" color, using its algorithms. The result of the algorithms is run through the translation table to determine the selected color's actual palette location. This has a negligible effect (fewer than 50 clock cycles) on performance.
The key item is that seamless palette management can exist because the Windows and PM palette APIs, and associated functionality are so similar. In both Windows and PM, an application creates, selects, and realizes a palette (in that order). In addition, there is a concept of palette animation in both Windows and PM. Animation permits a palette entry's color to be changed quickly, without affecting the rest of the palette or redrawing the image. Therefore, all Windows palette manipulation can be requested through normal GPI/PMWIN APIs, with the exception of animation. Animation is even simpler. It can be handled directly by the Windows GDI once PM has defined the animateable palette slot and returned this information to GDI.
The most straightforward way to describe the design of seamless palette management is to look at the processing flow:
1.At PM seamless startup, a PM and Windows shared memory area is established and initialized. Several entries are added to this shared area for seamless palette management, as follows:
�FixedPMPalette (Boolean, indicating a non-Palette Management PM Driver)
-If the PM Driver is not palette-aware, the GDI will operate, assuming a fixed palette. This assumption is accounted for in the GDI code, since Windows drivers exist for fixed palette hardware.
-For XGA and SVGA, because the drivers incorporate palette management, the flag is always FALSE.
�TimeLastPalUpdate(timestamp of the last reorganization of the palette due to focus change and resultant realize request)
-When the focus changes and the application now in focus realizes, the entire palette is reshuffled. This invalidates the current GDI palette entries. The time stamp is a mechanism for the GDI to be instantly aware of this change.
Note:For simplicity, this could also be implemented as a counter.
�PtrPhysicalPalette (Pointer to a shadow of the physical hardware palette)
2.After Windows driver initialization, the GDI issues a Driver Control() call requesting the address of the data described above. (A Control() call is really the end result of an application deviceescape. The GDI is responsible for translating Escape() calls to Windows Driver Control() functions.) After this call, the GDI has addressability to all the necessary PM palette information.
The format of the Control() function is:
rc = Control ( lpDevice, SEAMLESS_PAL_INIT, lpInDate, lpOutData)
where
lpDevice = a long pointer to a data structure of type PDEVICE,
the destination device bit map
SEAMLESS_PAL_INIT = a word of value 6010
lpInData = NULL
lpOut Data = a long pointer to a structure that contains:
bfPaletteIsfixed
ulLastPalUpdate
pHWPalette
(These are the palette-related entries in the PM/Windows shared
data/code area).
3.In the course of normal seamless processing, if the GDI requires a hardware palette change, the GDI requests this change through PM's GPI/GRE, using the Windows and PM Shields. However, the GDI also issues a standard call to OEMSetPalettein the seamless windows driver. In this call, a null pointer is passed, instead of a pointer to a valid palette, to notify the seamless windows driver that a palette change has occurred through PM. In this case, the seamless windows driver updates only its private image copy of the palette, using the data pointed to by the 16:16 hardware palette address (pHWPalette) in the PM and Windows shared data/code area.
Note:The first 10 entries and last 10 entries of the palette in the shared data/code area are not exact matches to the static Windows** colors set forth by Microsoft**. They are the closest fitcolors available in the PM default palette. Therefore, these 20 entries must never be modified in the seamless windows driver private image.
When the palette address pointer in OEMSetPaletteis not NULL (that is, when a valid color table is passed), the seamless windows driver must update the video hardware palette as usual, as well as update its private image copy of the palette. This only occurs in seamless processing when a Windows application is animating the palette. It is important that the seamless windows driver first requests the video semaphore and then clears the semaphore after updating the hardware palette.
4.The Win Shield and PM Shield are responsible for forwarding all RealizePaletterequests to the Windows DOS sessions and Presentation Manager applications. These requests are received and processed as usual.
5.On a palette realization for GDI, the PM Shield returns the logical-to- physical mapping of the requested color table to the DOS session's Windows GDI. This information is obtained from the PM driver using a GRE call that is hooked by the PM driver - GREQueryPaletteRealization. When the PM Shield calls this function and passes a device context and a pointer to an array of ULONGS, the PM driver returns the mapping from the logical color table to the hardware palette in the ULONG array. Seamless operation requires no special flags or different processing.
6.There is one additional requirement in seamless Presentation Manager. In the Windows OEMUpdateColorsfunction, the seamless windows driver must add the hardware serialization code to its processing logic before performing any video hardware access. The video FSRamSemaphoremust be requested, and cleared upon exit of this routine. If this is not done, screen and font damage can occur.
As always, before requesting the video fSRamSemaphore, the seamless windows driver should check the hardware access state. If the driver is not enabled , the Windows driver should call Win Shield, requesting a repaint of the Windows Desktop.
Sharing Cursor Exclusion and Enable/Disable Code
Cursor exclusion or disable code is always required when software cursors are in use. The seamless windows driver must use the PM cursor routines. Even when hardware cursors are used, it is recommended that the PM cursor routines be called by the seamless windows driver. This enables the PM driver to accumulate bounding rectangles of modified areas of the screen to support applications such as remote help-desk screen access.
The example of a PM and Windows shared data/code area given previously for XGA demonstrates how cursor exclusion and enable/disable can be implemented .
That example includes the following entries in the shared structure:
pCursorStatus dd ? ; Byte ptr: bit 0x80 set if sfw cursor
pExcludeCursor dd ? ; 16:16 addr of exclude cursor function
pDisableCursor dd ? ; 16:16 addr of disable cursor function
pEnableCursor dd ? ; 16:16 addr of enable cursor function
In this example, the seamless windows driver has the option of calling the PM cursor routines, but only when a software cursor is in use (by checking the CursorStatus byte). However, in the current XGA implementation, the seamless windows driver calls the PM routines whenever it requests the video FSRamSemaphore and the destination is the screen. (This enables the XGA PM driver to accumulate bounding rectangles of all screen windows.) The seamless windows driver calls the PM ExcludeCursor routine when a hardware cursor is in use, DisableCursor when a software cursor is in use, and EnableCursor whenever the video FSRamSemaphore is cleared and the destination is the screen. For XGA, the cursor exclusion rectangle coordinates are passed on the stack.
The PM cursor functions are accessed by a 16:16 address (entry point) that is exported by the PM driver. At this address is the PM thunk code and the call to the actual PM 32-bit cursor function. The thunk is not compiled but done by hand in the code itself. Sample code from the XGA PM driver is included in the following code fragment:
;-----------------------------------------------------------------------
;
; SeamlessExcludeCursor is the thunked entry point to eddm_ExcludeCursor.
; The exclusion rectangle is passed in the following registers in AI coords
; (that is, 0,0 is top left of screen).
;
; left top right bottom
; cx dx si di
;
;-----------------------------------------------------------------------
align 4
_SeamlessExcludeCursor proc far
; If we are not using a software cursor, we can go for a
; fast exit. We know that the Windows driver always has
; fs set up to be the flat selector, so we use it here to
; access our 32-bit data.
mov eax, offset FLAT:_cursor_data.cd_cursor_status
test byte ptr fs:[eax], CURSOR_SOFTWARE
jz short SEC_exit
; Save ds and es on the 16-bit stack.
push ds
push es
; Get the FLAT selector into ds and es.
mov ax, SEG FLAT:_DATA
mov ds, ax
mov es, ax
; Before we start using esp and eip, we must disable interrupts.
; An interrupt can damage the top half of the registers
; because it thinks we are 16-bit. Touch all the pages we might
; access before disabling interrupts (a page fault is non-maskable
; and will re-enable interrupts).
call SeamlessTouchPages
cli
; Save ss:sp (that is, 16-bit stack) in ebx.
mov bx, ss
rol ebx, 16
mov bx, sp
; Set up the 32-bit stack.
mov ax, SEG FLAT:_DATA
mov ss, ax
mov esp, offset FLAT:_SeamlessStack+SEAMLESS _ STACK _ SIZE
; Now on 32 - bit stack ,
; save the 16 - bit ss : sp on the 32 - bit stack .
push ebx
; Jump into the 32 - bit code , which will call the 32 - bit exclusion code .
jmp far ptr FLAT : SeamlessExcludeCursor32
ret _ from _ exclude32 :
pop eax
mov dx , ax
rol eax , 16
mov ss , ax
movzx esp , dx
; Now on 16 - bit stack
sti
pop es
pop ds
SEC _ exit :
retf
_ SeamlessExcludeCursor endp
Note:
Interrupts must be disabled before setting and using esp and eip. This is done to prevent entering 32-bit interrupt handling code when the current task, the DOS session, is known to be 16-bit. In this case, the ip and sp pointers would be set for a 16-bit environment, not 32-bit.
All code pages that might be required by the execution of the shared seamless functions must be present in memory before disabling interrupts. A page fault cannot be taken while in the seamless shared code.
Care must be taken that an STI instruction is not included in the PM cursor routines when executed by a DOS session. Interrupts must remain disabled ( when executed by a DOS session) until returning through the thunk logic and being enabled.
Care also must be taken not to cause any ring transitions (from Ring 3) within the PM code executed from a DOS session. Therefore, there cannot be any operating system calls, etc. executed.
Set Up and Sharing of a Pointer to Video RAM
A shared pointer to video memory might be required in a seamless environment.
To establish the pointer in a 32-bit environment, the PM display driver calls PMDD.SYS (using DOSDevIOCtl) at initialization. The PM driver passes in the physical address of video RAM and its size, and gets back a Ring 2- or Ring 3-accessible linear address for the video memory. This address is then included and initialized in the seamless shared data/code area. VWIN handles the sharing requests necessary to access the pointer from the seamless windows driver.
To support the allocation of the global pointer to VRAM, the function AllocGlobalVRAM has been added to PMDD.SYS:
AllocGlobalVRAM - (Function 0x7E)
Called via: DosDevIOCtl( pData, pParms, 0x7E, 3, hDev )
where:
pData points to a ULONG in which the flat address to
VRAM will be returned.
pParms points to a structure of the following type:
struct _PARMS {
ULONG PhysicalAddress;
ULONG Length;
ULONG Flags;
} PARMS;
where:
PhysicalAddress is the beginning of the
video RAM.
Length is the length of video RAM in bytes.
Flags is a field of flags of which only the
least significant bit is currently
defined. If the first bit is set, the
pointer returned will be shareable and
can be used to access VRAM at any
privilege level. If the first bit is
0, the pointer returned will be global
and only accessible from Ring 0. All
other bits are reserved and should be 0.
(For the seamless environment, Flags should be 1.)
hDev is the handle returned from a DosOpen call of the
SINGLEQ$ device.
Returns: 0 if successful, or a non-zero error code on failure.
As mentioned above, all addressability to the video memory for the seamless windows drivers is handled by VWIN. However, if additional PM processes also require addressability, they must issue an AccessGlobalVRAM call to PMDD.SYS. (Please note that the process that allocates the pointer does not require this AccessGlobal call. The AllocGlobalVRAM function performs all necessary processing to allow the calling process' access of video memory.)
AccessGlobalVRAM - (Function 0x7F)
Called via: DosDevIOCtl( NULL, pParms, 0x7F, 3, hDev )
Where:
pParms points to a structure of the following type:
struct _PARMS {
ULONG FlatAddress;
ULONG Length;
} PARMS;
where:
FlatAddress is a pointer that was returned
from a previous call to
AllocGlobalVRAM.
Length is the length of Video Memory in
bytes.
hDev is the handle returned from a DosOpen call of the
SINGLEQ$ device.
Returns: 0 if successful, or a non-zero error code on failure.
PM Driver Calls to VWIN - Accessed via DOSRequestVDD
�Function = Pass initialization structure
HVDD = Handle of VDD (returned from DosOpenVDD)
SGID = NULL
ULONG = 0x000000C0
ULONG = Number of array elements
PVOID = Pointer to array of SM_PMDISP structures
ULONG = 0
PVOID = NULL
typedef struct _SM_PMDISP
{
ULONG flOptions;/* BIT1 BIT0=xx ring level if BIT3=1 */
/* BIT2=0 for DATA BIT2=1 for CODE */
/* BIT3=0 for 16:16 BIT3=1 for 0:32 */
/* BIT4=0 for mapping BIT4=1 for */
/* passthru; if passthru, VWIN does */
/* not touch */
/* BIT5=1 to force linear addresses */
/* to match otherwise, 16:16 addrs */
are remapped in the DOS session */
/* BIT6 - BIT31 reserved (must be 0) */
ULONG ulLength; /* Length of the data in bytes */
union /* Pointer to the beginning address */
/* of shared memory structure */
{
PVOID p16; /* for 16:16 (BIT3=0) */
ULONG p32; /* for 0:32 (BIT3=1) */
} Start;
} SM_PMDISP;
�Function = Signal timeout of the hardware semaphore
HVDD = Handle of VDD (returned from DosOpenVDD)
SGID = NULL
ULONG = 0x000000C1
ULONG = PID to test/kill
PVOID = NULL
ULONG = TID to test/kill
PVOID = NULL
Returns 0 for "valid Seamless VDM PID/TID was killed"
1 for "valid PID/TID was not killed" (held by a PM driver)
2 for "non-valid PID/TID" (went away or is going away)
�Function = DOS session Dirtynotification (Send)
HVDD = Handle of VDD (returned from DosOpenVDD)
SGID = -1 indicates broadcast; the PM display driver
always broadcasts
ULONG = 0x000000C2
ULONG = Function code to use for the interrupt ( 0x4001
or 0x4002 )
PVOID = NULL
ULONG = Force Repaint ( 0 = NO, 1 = YES )
PVOID = NULL
Sends VWIN a DOS session Dirtynotification. This is used at PM death and resurrection to indicate to the DOS sessions to suspend drawing or resume redrawing and repainting.
�Function = Set VMOUSE Display Resolution
HVDD = Handle of VDD (returned from DosOpenVDD)
SGID = NULL
ULONG = 0x000000C4
ULONG = sizeof(VMSSIZE structure)
PVOID = pointer to VMSSIZE structure
ULONG = NULL
PVOID = NULL
typedef struct vmss_s {
ULONG vmss_nb; // Size of structure, in bytes (36)
LONG vmss_lMode; // Video mode (eg, 00h-13h, or -1)
ULONG vmss_ulWidth; // Width of screen, in pels
ULONG vmss_ulHeight; // Height of screen, in pels
ULONG vmss_ulCellWidth; // Width of screen cells, in pels
ULONG vmss_ulCellHeight; // Height of screen cells, in pels
ULONG vmss_ulPtrWidth; // Width of ptr drawing size, pels
ULONG vmss_ulPtrHeight; // Height of ptr drawing size, pels
ULONG vmss_ulPtrUnitWidth; // Width of ptr drawing unit, pels
} VMSSIZE;
Windows Driver Calls to VWIN - Accessed via INT 66h
�Windows DD - Initialization
Input:
AH = 0x81 - VWIN_INITIALIZE
DS:SI = "VWIN"
CX = SIZEOF windd_init
EBX = windd_init struc
WINDD_INIT struc
proc_id dw 0 ; (out) WinDD's process id
thread_id dw 0 ; (out) WinDD's thread id
pfvwin dd ? ; (out) VWIN's interrupt handler
pmdd_io dd 0 ; (out) pointer to pmdd_io structure
WINDD_INIT ends
Note:
After this initialization call, instead of issuing INT 66H, the seamless windows driver can call directly into VWIN's interrupt handler using the pfvwin function pointer, passed in the WINDD_INIT structure. If this mechanism is used, the seamless windows driver must first perform a "pushf" before calling VWIN's handler.
The pmdd_iofield is a pointer passed directly from the PM display driver. This pointer addresses a structure of values that are shared between the PM and seamless windows display drivers. The definition of this structure is set by the display driver pair. However, as noted above, the first four bytes of the structure must contain some type of signature value agreed on by the display driver pair.
Output:
AX = 0... success
n... failure code defined by VWIN
�Windows DD - Block on FSRamSemaphore
Input:
AH = 0x82 - VWIN_SEM_BLOCK
EBX = CPDOS RAM Semaphore
ECX = Timeout value
DS:SI = "VWIN"
Output:
AX = 0... success
n... failure
Note:Most of the driver semaphore handling is at Ring 3. However, this exception (interrupt) is necessary because the seamless windows driver DOS session cannot make a kernel call. When the video hardware semaphore is in use, the Driver must block, and this requires a call to the kernel through VWIN.
�Windows DD - Wakeup FSRamSemaphore request
Input:
AH = 0x83 - VWIN_SEM_WAKE
EBX = CPDOS RAM Semaphore
CX = old RamSemFlag value
DS:SI = "VWIN"
Note:When freeing and resetting the FSRamSemaphore, the seamless windows driver first checks whether RamSemFlag in the semaphore structure is 0. If the flag is nonzero, the seamless windows driver must call INT 66h, VWIN_ SEM_WAKE. The RamSemFlag value before being reset is the "old RamSemFlag value".
Output:
AX = 0. . . success (call cannot fail)
�Windows DD - Request hardware
Input:
AH = 0x84 - VWIN_REQUEST_VVIDEO
DS:SI = "VWIN"
Output:
AX = 0. . . success (call cannot fail; call will block
until hardware is available)
Note:In seamless processing, three components share the video hardware. These are:
VVIDEO
PM
Windows
PM and Windows coordinate access to the hardware via a FSRamSemaphore. However, virtual video drivers do not have this mechanism available. A virtual driver is never sure when a DOS application is finished accessing the screen; therefore, this interrupt exists to signal to VWIN (which forwards the request to the virtual video driver) that the seamless windows driver needs hardware access. Before making the call, the driver must obtain the hardware semaphore. Upon return, the seamless windows driver is guaranteed exclusive use of the video. (This mechanism of obtaining the semaphore and checking with VVIDEO already exists in the PM Driver code and is not unique to seamless operation.)
�Windows DD - Notify that hardware is available.
Input:
AH = 0x85 - VWIN_NOTIFY_VVIDEO
DS:SI = "VWIN"
Output:
AX = 0. . . success (call cannot fail)
�Windows DD - Critical section processing
Input:
AH = 0x86 - VWIN_WINDD_ENTERCRITSEC
DS:SI = "VWIN"
Output:
AX = 0. . . success (call cannot fail)
Input:
AH = 0x87 - VWIN_WINDD_EXITCRITSEC
DS:SI = "VWIN"
Output:
AX = 0. . . success (call cannot fail)
Note:The enter/exit critical section calls can be nested and, therefore, must come in pairs. This interrupt usually is issued as part of INT 2Fh processing, when nonreentrant code is being executed. It requests VWIN to temporarily stop sending interrupts to the DOS session.
Device Escapes() from Win Shield and GDI to Seamless Windows Driver
�rc = Escape( hDC, SEAMLESS_ESC_INIT, nCount, lpInData, lpOutData )
hDC = GetDC( hWnd )
nEscape = 6000 - SEAMLESS_ESC_INIT
nCount = 0
lpInData = Pointer to Win Shield "call-back" entry point
lpOutData = NULL
On Exit: rc = negative......Error
rc = positive......Success
The SEAMLESS_ESC_INIT call is made by Win Shield at initialization time. On input, Win Shield provides the address of a call-back entry point. The seamless windows driver uses this entry point, in addition to passing a clip region, to cause an area of the Windows Desktop to be repainted. This function is used whenever the seamless windows driver is disabled but must write to the screen. Win Shield is responsible for accumulating the clip regions passed to it.
Note:
1.This call is made before the screen is enabled by the Win Shield via INT 2Fh.
2.The seamless driver must always invalidate the Windows Desktop when OEMUpdateColorsis called and the driver is in the disabled state. Miscellaneous translation table and color-mapping problems can otherwise occur.
�rc = Escape( hDC, SEAMLESS_ESC_ENABLE, nCount, lpInData, lpOutData )
hDC = GetDC( hWnd )
nEscape = 6002 - SEAMLESS_ESC_ENABLE
nCount = 0
lpInData = NULL
lpOutData = Pointer to hw_access
On Exit: rc = negative......Error
rc = positive......Success
SEAMLESS_ESC_ENABLE permits a Windows program to determine the current hardware state. The escape returns the address of the driver's internal variable, hw_access, which reflects the hardware state at any time.
�rc = Escape( hDC, SEAMLESS_ESC_EXIT, nCount, lpInData, lpOutData )
hDC = GetDC( hWnd )
nEscape = 6001 - SEAMLESS_ESC_EXIT
nCount = 0
lpInData = NULL
lpOutData = NULL
On Exit: rc = negative......Error
rc = positive......Success
Win Shield issues this call, requesting the seamless windows driver to reset its Win Shield call-back entry point. This is performed when the seamless windows DOS session is closing.
�rc = Escape( hDC, SEAMLESS_ESC_REQSEM, nCount, lpInData, lpOutData )
hDC = GetDC( hWnd )
nEscape = 6004 - SEAMLESS_ESC_REQSEM
nCount = 0
lpInData = NULL
lpOutData = NULL
On Exit: rc = negative......Error
rc = positive......Success
SEAMLESS_ESC_REQSEM requests the seamless windows driver to obtain the FSRamSemaphore on behalf of Win Shield.
�rc = Escape( hDC, SEAMLESS_ESC_CLRSEM, nCount, lpInData, lpOutData )
hDC = GetDC( hWnd )
nEscape = 6005 - SEAMLESS_ESC_CLRSEM
nCount = 0
lpInData = NULL
lpOutData = NULL
On Exit: rc = negative......Error
rc = positive......Success
SEAMLESS_ESC_CLRSEM requests the seamless windows driver to clear the FSRamSemaphore on behalf of Win Shield.
�rc = Escape( hDC, SEAMLESS_ESC_PALINIT, nCount, lpInData, lpOutData )
hDC = GetDC( hWnd )
nEscape = 6010 - SEAMLESS_ESC_PALINIT
nCount = 0
lpInData = NULL
lpOutData = Pointer to the start of the palette-related data in the
PM and Windows shared data/code area
On Exit: rc = negative......Error
rc = positive......Success
SEAMLESS_ESCAPE_PALINIT permits the Windows GDI component to obtain the address of the palette-related data in the PM and Windows shared data/code area. There are three palette-related entries in this shared area, arranged in the following sequence:
bfPaletteIsFixed db ? ; TRUE if Palette Manager not enabled ulLastPalUpdate dd ? ; Timestamp of last foreground realize pHWPalette dd ? ; 16:16 ptr to HWPalette structure
Windows INT 2Fh Support
�Windows DD - Notify Background Switch
AX = 4001H
CX = Seamless identifier "SM"
DX = Seamless sub-function
0100H....disable hardware Write access
0101H....disable hardware Read/Write access
�Windows DD - Notify Foreground Switch
AX = 4002H
CX = Seamless identifier "SM"
DX = Seamless sub-function
0200H....enable hardware Write access
0201H....enable hardware Read/Write access
0202H....enable hardware Read/Write access and
force repaint
Miscellaneous Windows Driver Information
�In addition to the enabled and disabled states, the Windows driver also can be in a Read-onlystate, for example, when the Windows driver is disabled, yet can legitimately transfer bit-map data from video memory to system memory.
These various states are normally used to optimize execution speed, based on the needs of the calling application.
When processing INT 2Fh/disable from the PM Display Driver, it is important for the Windows driver to remain disabled until notified (again, via INT 2Fh) by the PM driver. The PM driver is notifying of its death and resurrection. Alternately, if enabled by the PM driver but otherwise INT 2Fh disabled, then the Windows driver can optimize processing and enter the read-only state.
�The seamless windows driver must always check the hardware state before requesting the video FSRamSemaphore. If the hardware is disabled or in the "read-only" state, and the output destination is the screen, the driver should call Win Shield, requesting Win Shield to accumulate the screen areas (rectangles) requiring update.
There are two options when calling Win Shield for a repaint:
SEAMLESS_FORCEPAINT To cause the entire Windows desktop to be repainted. SEAMLESS_POSTPAINT To repaint the accumulated area collected by Win Shield.
�Normally, when a Windows session is switched to the background, its output is disabled. Then, when switched to the foreground, a repaint is forced, even if no modifications were made to the current screen. This is acceptable when running a full-screen Windows session. However, when running seamlessly, the PM Driver automatically saves the contents of the screen when it is switched to the background.
When Presentation Manager returns to foreground, the whole screen is restored (including the seamless windows). As a result, no refreshes from the seamless windows will be necessary unless the Windows program attempted a repaint while output was disabled. As a performance improvement, a repaint flag is implemented in Win Shield, which is set initially to FALSE. When the seamless windows driver is in the background, this flag is set by Win Shield to TRUE if any refresh of the screen is attempted by the driver (for example, if the driver calls-back to the Win Shield, passing a clip region). When the seamless driver is switched to the foreground, a repaint is forced only if the flag is TRUE.
�Errors have been observed in seamless windows due to the Windows driver's failure to account for being in the Disabled state. For example, damage to the Min/Max buttons for a seamless window was observed. This occurred because the Min/Max button conversion was performed in the DIBtoScreenfunction. In some scenarios, when this function was invoked, the seamless windows driver was disabled. In this case, the Windows driver could not process the DIBtoScreenand ignored it. However, when finally enabled, the driver was told only to do a block logical transfer (Blt) and not a DIBtoScreen. The solution was for the seamless windows driver to store a flag indicating that the button conversion had not been performed, and to process it at a later time, when enabled.
�The SaveScreenBitmapentry in the seamless windows driver should be disabled because the driver does not have full information of the Desktop when running seamlessly.
�The seamless windows driver must not issue any INT 10h calls.
�Previous seamless windows design assumed that the FS and GS registers were not modified once loaded. Under Windows 3.1 this is no longer a valid assumption. The seamless windows driver must save the FS and GS contents to global variables when FS and GS are initially loaded. Then, before these registers are used, the seamless driver should compare the contents to the global variables. If the contents have been modified, the registers must be reloaded.
�It is important to modify the virtual video device driver, as well as the PM and Windows drivers, to operate seamlessly. The virtual video driver, which normally traps all hardware I/O, must be modified to permit the seamless windows driver to access the hardware. If the virtual video changes are not complete, you will see the following error message box:
�ååå Error Message åååååååååååååååååååååååååååååååà � � � System does not support this session's video mode in � � a window. The program cannot continue running in a � � window. � � � �ååååååååååååååååååååååååååååå�
Seamless Testing
The essence of seamless windows testing is to run both OS/2 Presentation Manager and Windows applications together on the OS/2 Desktop. The tests should execute as many different Windows functions and options as possible, to stress the seamless drivers and environment.
The following situations and scenarios should be considered for seamless testing:
�Execute standard Presentation Manager and Windows functionality - move, resize, minimize, maximize and overlay windows of both PM and Windows applications. When minimizing, minimize to the OS/2 Desktop, to the Minimized Window Viewer and hide the applications. Open and close several PM and Windows applications.
When closing applications, exercise various mechanisms (close from the Window List, double click in the window's upper left corner, etc.). For the Windows applications, test within the same DOS session and in different DOS sessions.
�Use the Window List, mouse pointer and hot-key sequences (for example, Alt +Esc) to change window focus. Include full-screen, and DOS and OS/2 windowed sessions in some test scenarios.
�Verify application functionality - pull-down and pop-up menus, control keys, radio buttons, and so on. Are text font and positioning correct? Are valid colors displayed?
Actual Windows and PM applications should be executed to exercise seamless modifications.
A verification of Windows driver functionality can be obtained using the driver test routines from the Microsoft Windows Device Driver Kit. These tests should execute seamlessly.
�Drag both PM and Windows icons and move the cursor over the application windows. Test both hardware and software cursors if available. Exercise various bit map formats - device dependent (DDB), device independent (DIB) and run length encoded (RLE).
�Transfer data between Presentation Manager and Windows applications using the Clipboard and DDE.
�Exercise all supported hardware resolutions and bits per pels. A different set of problems may be detected at different resolutions and numbers of colors.
Three possible test scenarios are outlined below:
�Scenario A(Initial seamless verification):
Two passes:
-Pass One uses a single instance of Windows Clock on the OS/2 Desktop
-Pass Two has multiple instances
Active Sessions:
-Windows Clock
Move, resize, attempt both analog and digital display, overlay OS/2 folder icon view, clip by icon view, minimize, maximize.
�Scenario B:
Two passes:
-Pass One with one DOS session for both Windows applications
-Pass Two uses separate DOS sessions.
Exercise the outlined functionality by performing some tasks within an application, then change focus to the next application and continue to test , ultimately returning to the first application.
Active Sessions:
-PM - Jigsaw
Minimize, maximize, move, resize, overlay Windows applications, clip by Windows applications, play the game.
-Windows - Excel
Change fonts, copy data to Clipboard, resize, display chart, minimize, maximize, move, close, cut/paste, overlay PM and Windows applications, clipped by Presentation Manager and Windows applications, change height and width of cells, change colors in cells.
-Windows - Paintbrush
Select color, draw, fill, cut/paste, rotate, edit palette, view bit map, minimize, maximize, move, resize, clipped by and overlay other windows.
�Scenario C:
This scenario includes multiple focus changes between the various windows, and exercises hardware palette updates and switching to/from a full-screen session.
The functionality discussed (minimize, maximize, resize, clipping, etc.) should be exercised while changing focus and performing the session switches.
Active Sessions:
-PM - PalDisp
Display hardware palette for verification.
-PM - PalTest
Display bit map using PM Palette Management, and verify palette update.
-PM - Solitaire
Continuous play.
-Windows - ShowDIB
Display bit map using seamless windows Palette Management, and verify palette update.
-Windows - Clock
Analog and digital display.
-DOS Window - batch file in loop, text mode
Run batch file printing text messages, coded in an endless loop.
-DOS Full-Screen - graphics application
Run graphics application program.
Checklist for Palette Management Support
To enable current Windows driver palette management support in a seamless display driver, follow the steps below:
1.Make sure that the following structure is part of the PM-SL share data, that is, the PMDD_IO_STRUC structure defined in IPC.INC.
SL_PaletteData struc
bfPaletteIsFixed db ? ;TRUE if palette manager not enabled.
ulLastPalUpdate dd ? ;Time stamp of last foreground realize.
pHWPalette dd ? ;16-bit pointer to HWPalette structure.
SL_PaletteData ends
2.Add SEAMLESS_ESC_PALINIT function support in Windows entry Control ( lpDevice, Function, lpInData, lpOutData), do the following:
a.Claim the support of SEAMLESS_ESC_PALINIT when this function is being queried.
b.When Function = SEAMLESS_ESC_PALINIT, return the address of init_Struct- >pmdd_io.SL_PaletteData in the buffer whose address is in lpOutData.
This address, &(init_Struct->pmdd_io.SL_PaletteData), must be in 16-bit sel :offset format.
Note:
If init_Struct->pmdd_io is a 32-bit address of the PM-SL share area, you have to thunk the &(init_Struct->pmdd_io.SL_PaletteData) 32-bit address to 16-bit sel:off format, using the following algorithm:
sel = (high word of the 32-bit address * 8) | 7
off = the low word of the 32-bit address.
If this function is not implemented, or not correctly implemented, a General Protection Fault will occur.
3.Change Windows entry SetPalette() as follows:
if( lpPalette != NULL ) {
a) Request_Semaphore(..)
b) Update the hardware palette in exactly the same way as you do in
regular Windows driver.
c) Clear_Semaphore(..)
} else {
Update the private copy of the hardware palette image if there is one being
kept in the data segment.
}
4.Change Windows entry UpdateColors() as follows:
�Call check_hw_access() for HW_FORCEREADWRITE hardware state before any screen update.
�If check_hw_access() returns Success, call request_semaphore() as you do before all hardware access and clear_semaphore() after you are done updating the screen.
5.Change check_hw_access() in IPC.ASM as follows:
Add HW_FORCEREADWRITE as one of the possible values in AL when this call is made. Here is an example of code needed to add to check_hw_access():
check_hw_access PROC FAR
.....
cmp al, HW_READWRITE ;Request for HW_READWRITE access?
jnz check_forcereadwrite ;No, go check for HW_FORCEREADWRITE
;access.
.....
check_forcereadwrite:
cmp al, HW_FORCEREADWRITE ;Request for HW_FORCEREADWRITE access?
jnz check_write_access ;No, go check for HW_WRITEONLY access.
VWIN_ENTER_CRITSEC ;Turn off interrupts from VWIN.
mov hw_virgin, HW_DOREPAINT ;Repaint when HW_READWRITE allowed.
mov ax, SEAMLESS_FORCEPAINT ;Paint the whole VDM.
call winshield_callback ;
VWIN_EXIT_CRITSEC ;Turn on interrupts from VWIN.
jmp check_exit_bad ;We are done. Exit.
....
check_hw_access ENDP
6.Remarks
Values for symbolic names used above are as follows:
SEAMLESS_ESC_PALINIT equ 6010 ;Pass back address of 1st entry of the
;palette-related data in PM-SL share
;area.
HW_FORCEREADWRITE equ 'F' ;Request R/W hardware state. If not
;available, ask winshield to do force
;repaint when the driver is once again
;allowed to draw the screen.
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