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