DDDR/2 - 32-Bit VGA Display Driver

From EDM2
(Redirected from 32-Bit VGA Display Driver)
Jump to: navigation, search
Display Device Driver Reference
Chapters
  1. 16-Bit VGA Display Driver
  2. 8514/A Display Driver
  3. 32-Bit VGA Display Driver
  4. 32-Bit Super VGA Display Driver
  5. SVGA Base Video Subsystem
  6. Physical Video Device Drivers
  7. Virtual Video Device Drivers
  8. Seamless Windows Support
  9. PM Palette Management Support
  10. Distributed Console Access Facility (DCAF)
  11. DBCS Video Driver Support
  12. Installing and Configuring Display Device Drivers
  13. Graphics Test Suites
  14. Display Test Tool
  15. VIDEOCFG.DLL Exported Functions
  16. VIDEOPMI.DLL Exported Functions
  17. VIDEO Protect-Mode Interface
Appendixes
  1. Data Types
  2. S3 Display Driver

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

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: PMGRE.png

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

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_driver is 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_lct decrements the usage count in the logical color table.

When the usage count is 0, deselect_lct frees the memory of the logical_ color_table' 'by calling private_free with 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_init is 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.cb to the size of screen memory (64KB), gsspScreen.pPhysMem to 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 padBitmapFormats to 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_disable is called from Death, signifying a switch to a non-PM screen group. physical_disable saves 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 fInitMem does not equal INIT_VRAM.
Entry: fInitMem is a flag set by fill_phys_dev_blk or 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. cbDirty is the number of VRAM bytes to restore for a fast video restore. physical_enablereceives cbDirty from resurrection. cbDirty indicates 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 fInitMem contains 1. physical_disable saves 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_mode equals -1, Pixel returns the pel's IPC (Internal Physical Color). If mix_mode is 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 lPhysColor parameter, 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 GetPixel or 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)</cpde>
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: <code>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 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.

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 WIN-OS/2 32-Bit Functions in VGA Display Driver
far_unexclude16 far_unexclude
FAR_EXCLUDE16 far_exclude