DDDR/2 - 32-Bit VGA Display Driver

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation =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 table to 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:

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:

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

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.

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

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 Reference for 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 DeviceSetAVIOFont call from GRE. In the device-specific DLL, the function must be named DeviceSetAVIOFont2.

Refer to the Presentation Device Driver Reference for 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 scan means 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 scan''' means that the value in the register is a pointer to the memory location that contains the number of bytes per scan.


 * Routines Called:||
 * }
 * Video Semaphore Required for Processing:||No
 * }
 * Routines Called:||None
 * Video Semaphore Required for Processing:||No
 * }
 * Routines Called:||None
 * Video Semaphore Required for Processing:||No
 * }
 * }


 * Routines Called:||
 * }
 * Video Semaphore Required for Processing:||No
 * }
 * Routines Called:||
 * }
 * Video Semaphore Required for Processing:||No
 * }
 * }
 * Video Semaphore Required for Processing:||No
 * }
 * }


 * Routines Called:||
 * }
 * Video Semaphore Required for Processing:||No
 * }
 * 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 layer interfaces 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. 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.