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