PDRREF:Display Drivers
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
This chapter describes video cursor support and the installation utility program used by OS/2 display drivers.
Exported Entry Points (Cursor)
The following entry point is exported by the dynamic link library of a display driver:
EXPORTS MoveCursorBlock @103
MoveCursorBlock
Display drivers must export an entry point for the MoveCursorBlock table. This table contains information about the display driver's MoveCursor routine (code) and data areas. The table values are checked after the display driver is initialized. This allows the driver to determine the correct values.
typedef struct _MCDESCRIPTION {
PVOID pMoveCursor;
ULONG ulCodeLength;
PVOID pCursorData;
ULONG ulDataLength;
} MCDESCRIPTION;
typedef MCDESCRIPTION * PMCDESCRIPTION;
The fields in the MCDESCRIPTION data structure are described below:
- pMoveCursor
- Flat address of the MoveCursor routine in the display driver.
- ulCodeLength
- Length in bytes of the MoveCursor routine
- pCursorData
- Flat address of the data area used by the MoveCursor routine
- ulDataLength
- Length in bytes of the data area used by the MoveCursor routine
This routine supports calls from the system timer (at interrupt time). The strategy for the MoveCursor routine is that the pointer is checked and, if necessary, redrawn or excluded at timed intervals.
The PMDD.SYS physical device driver creates a privilege level 0 alias for the data address and passes the alias to the routine in the EAX register when MoveCursor is called at interrupt time. Therefore, all data addressing within the routine must be performed relative to this address.
At entry to the MoveCursor routine, the stack contains the following:
VOID MoveCursor(LONG abs_x, LONG abs_y, PVOID pCursorData)
Using the C calling convention, the stack contains two LONGs, which hold the X- and Y-coordinates of the cursor hot spot, and a PVOID that is a pointer to the cursor data area that is valid in the current context. All references to this data area must be done relative to the address passed in. If the X- and Y-coordinates are set to 0x80000000, this signifies a CheckCursor call.
Regular timer interrupts give the presentation driver an opportunity to check whether the pointer is valid. For example, the driver can check the following:
- Have new X- and Y- coordinates been set?
- Is the pointer excluded because of a drawing operation? If so, has that operation been completed?
- Is the pointer currently visible (although it should be excluded) because it is in an area that is being redrawn?
At the end of the MoveCursor routine, a check is performed to see if a new location was given for the pointer while it was being drawn. If the pointer has moved again, it must be drawn at the new location or be excluded because it has moved into the protection rectangle. This implies that the routine needs to track both real (X,Y) and pointer (X,Y) coordinates.
Programming Considerations
Typical cursors are an arrow or a cross with an action point called the hot spot at the point of the arrow or the center of the cross. When the presentation driver draws a cursor, the origin of the image must be offset to place the action point at the required (X,Y) position. The required offset is specified in the call to GreSetCursor. Because the cursor entry point can be called at various times from many different places, the cursor routine uses semaphores to protect itself (protection is the responsibility of the presentation driver). Similarly, because cursor drawing can be a time-consuming operation, the display driver must also protect itself against re-entrance.
The display driver must resolve all interactions between cursor drawing at interrupt time and access to video hardware. While in the background, the display driver does not draw any cursor image.
Caution should be used when the display is a buffered device and the cursor is drawn into a bit map in the buffer. In this case, the display driver deletes the cursor and excludes it when a draw operation occurs at the cursor location. To do this, the driver does a "hit test" for each output operation to see if the cursor location is in the drawing area and to set a protection rectangle that is used to exclude the cursor.
Introduction to Display Driver Installation
The OS/2 2.0 Display Driver Installation utility program (DSPINSTL.EXE) provides all the facilities necessary to install and configure OS/2 display drivers. The OS/2 display driver installation installs and configures PM display drivers. It might also include the installation and configuration of WIN-OS/2 display drivers, and the installation of base video service (VIO) drivers and DOS virtual device drivers (VDDs).
Display driver installation and configuration is more complex than standard device driver installation. It typically includes the following activities:
- Allowing the user to select OS/2 display characteristics - Specification of the type and resolution of the display driver to be installed. (See Allowing the User to Select OS/2 Display Driver Characteristics)
- Copying display driver-related files - Copying display driver-related files from source directories (usually on diskettes) to target directories on the user's hard disk (see Copying Display Driver-Related Files).
- Updating system configuration files - Appropriately updating various OS/2 and WIN-OS/2 configuration files to ready the new display driver for subsequent execution when the user's system is restarted (see Updating System Configuration Files).
Allowing the User to Select OS/2 Display Driver Characteristics
The user needs to specify whether the display driver to be installed will be used as the primary display adapter or as the secondary display adapter.
The user must then specify the type of display driver to install. This is important because many types of display adapter hardware can support a number of different display drivers. For instance, extended graphics array
XGA display adapter hardware can be operated using either the high-resolution XGA display driver or other lower resolution standard display drivers such as video graphics array (VGA) or enhanced graphics adapter (EGA) display drivers.
Finally, because some display drivers can support operation at more than one graphics resolution, the user might have to specify the display resolution at which the driver is to be operated. Display resolutions are typically specified by supplying the width and height of the display (in pels) and the maximum number of colors that can be simultaneously displayed. The user's choices for display resolution are often affected by the type of video hardware attached to the user's system. For example, both the size and type of the user's display and the amount of video RAM on the display adapter can affect which display resolutions can be run.
Copying Display Driver-Related Files
There are several factors that can complicate the copying of display driver-related files from source directories to target directories. First, display driver files might be sufficiently large and numerous to span more than one source diskette. This can easily occur when several display drivers that support different display resolutions are bundled together on the same diskettes (along with their associated font and resource files). Second, to save space within the source directory, it might be desirable to place packed files within the source directory. If so, the packed files should be unpacked when they are copied to the target directory. Third, the display driver packager might wish to specify file version checks that are to take place before file copying is performed. Such checks are valuable because they can prevent the inadvertent replacement of updated display driver files by older versions of the files.
Updating System Configuration Files
After display driver-related files have been copied to the user's system it is necessary to update different system configuration files to complete the installation process. Frequently, the CONFIG.SYS and OS2.INI files need to be updated to complete PM display driver installation and the SYSTEM.INI and WIN.INI files need to be updated to complete the WIN-OS/2 display driver installation. Depending on the display driver to be installed, other configuration files might also have to be updated.
Display Driver Installation Utility Program
DSPINSTL, the display driver installation utility program, is similar in some ways to the OS/2 Device Driver Installation utility program, DDINSTAL.EXE. DSPINSTL contains extensions that are specifically geared to simplify the steps that the user must perform to install and configure OS/2 display drivers. Because different types of OS/2 display drivers can have radically different installation and configuration requirements, DSPINSTL contains a set of features that allows a display driver developer to customize the installation process to meet the developer's special needs.
DSPINSTL consists of the following six major components:
- DSPINSTL Configuration File (DSC file) Interpreter
- Initial User Interface PM Panels - A standard set of PM panels that serve as a basic front-end user interface (see User Interface PM Panels).
- Action Routine Interface - An interface that allows the display driver developer to (optionally) add custom control logic (see Action Routine Interface).
- Service Functions - A set of standard service functions that can be called from within an action routine (see reference to service functions under Action Routine Interface and DSPINSTL Service Functions).
- Command Language PM Panels - A standard set of PM panels that act as the front end to the DSPINSTL Command Language Interpreter (see Command Language Presentation Manager Panels).
- Command Language Interpreter - The final stage of DSPINSTL that executes the installation and configuration commands that are packed in Display Driver Profile files (DSP files) (see DSPINSTL Command Language Interpreter).
DSPINSTL Configuration File Interpreter
The DSPINSTL Configuration file (DSC file) interpreter allows the display driver developer to specify, within the DSC files, the high level knowledge that characterizes one or more display driver packages. The information contained in the DSC files determines the contents of some of the fields in the standard set of PM panels. It also initializes a chain of data elements that will subsequently be passed to the DSPINSTL Command Language Interpreter that executes as the final stage of DSPINSTL operation.
Display Configuration Files
The DSC files are the key to DSPINSTL's ability to act as a generalized installation tool that can install many different types of display drivers. The display driver developer packages a set of drivers by placing the drivers on a diskette, creating one or more DSP files containing DSPINSTL installation and configuration commands. The developer then creates a configuration file entry within a DSC file that summarizes the key points concerning that display driver package. DSC files should be placed either in the directory that contains the DSPINSTL utility program or in a directory that is contained in the user's DPATH. DSPINSTL checks its directory first, and then if it cannot find a DSC file it searches the DPATH, stopping when it finds a directory that contains one or more DSC files. DSPINSTL reads all the DSC files it finds in that directory. DSC files are distinguished by a file-name extension of .DSC. A configuration file entry includes the following types of information:
- A title string that identifies the driver within the initial DSPINSTL PM panels (Primary Video Adapter and Secondary Video Adapter). These two panels are provided so that users can explicitly select which display drivers to install.
- The name of the dynamic link library (DLL) module (if any) that contains action routines specific to the installation of that display driver package.
- A keyword string that identifies whether the display drivers handle a standard type of display adapter. The following is a list of supported standard-type keyword strings:
ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³Type of Adapter ³Keyword Type String ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³Color Graphics Adapter ³ CGA ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³Enhanced Graphics Adapter ³ EGA ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³Video Graphics Adapter ³ VGA ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³Display Adapter 8514/A ³ 8514 ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³Extended Graphics Adapter ³ XGA ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³Super Video Graphics Adapter ³ SVGA ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
These standard-type strings are provided so that DSPINSTL can create a logical association with a display driver as a default type. This association is used if the user accepts DSPINSTL's default selection in the Video Display Configuration PM panel (the initial DSPINSTL PM panel). For example, suppose the panel shows that the user's system has an 8514 adapter as its primary display. If a DSC file entry contains a standard-type string of "8514" and the user accepts the default choice by selecting the OK push button, then that file entry will be chosen automatically. If more than one DSC file entry contains standard-type strings of "8514", then DSPINSTL would display a PM panel to allow the user to resolve the ambiguity. If the user checks either the primary or secondary check box, to indicate the desire to override the default logic and explicitly choose a driver, then the PM panel that follows will include list box entries for all the entries in the DSC files that DSPINSTL has read.
- A default chain of data elements that characterize a sequence of installation and configuration steps which, in total, constitute the entire installation and configuration process. Each chain element can include the following data:
- A required default keyword string that will trigger the interpretation of one or more DSP files in a given source directory.
- A required default prompt string that will be displayed in a PM panel informing the user of the purpose of the next installation step. This prompt string is included to help the user decide which device or directory to point the utility program toward to accomplish that portion of installation.
- An optional default prompt string that is used to tell the user which diskette to insert (if the next portion of installation is being performed from a diskette). This feature allows the driver package developer to inform the user of the exact title that is written on a diskette.
- An optional diskette volume label that allows DSPINSTL to verify that the user has inserted the correct diskette.
- An optional display resolution string that can be used by the developer to display a default display resolution for installation. This string can be passed by an action routine to the Select_Video_Resolution service function.
Typically, there will be one data element within the chain for each diskette in the package. However, the display driver developer can use the chain as desired. For example, one data element in the chain might handle file copy commands, while the next might be used for configuration file updates. The chain of data elements is first passed to the action routines (if any) and is then interpreted by the DSPINSTL Command Language Interpreter in the last part of the process. In this manner a developer can create a default series of installation steps, dynamically modify those steps, and then have the DSPINSTL command interpreter execute all the substeps that constitute each step.
DSC files are composed of lines containing character string entries. The following syntax rules govern the lines within a DSC file:
All character strings in the file are enclosed in double quotation marks. �
The \" pair can be used to embed a double-quotation character within a character string. �
Comment lines start with an asterisk (*).
DSC files contain one or more display driver package entries. Each entry contains a header section containing general information about the display driver package. The header section is followed by one or more subsections that define the default values for a data chain element. The format of the header section is shown in the following diagram:
<Adapter Type Title string> /* Title strings are up to 256 characters */
<DLL Module Name string> /* DLL module, containing action routines */
/* for that type of adapter */
<Standard Type Key string> /* Key string that DSPINSTL uses to identify*/
/* a type of adapter that it recognizes. */
/* Can be NULL, see below for the complete*/
/* set of standard keys */
"1" /* Required parameter, must be set to 1 */
"0" /* Required parameter, must be set to 0 */
<# of Parameter Sets in Entry>/* 'n' */
The format of the data chain element subsection is as follows:
<Default Key String> /* Initial key string assigned to this */
/* DSPINSTL data chain element */
<Default General Prompt String> /* User prompt string displayed in the */
/* Specify Source Directory panel when */
/* the DSPINSTL data chain element is
/* interpreted */
<Default Diskette Prompt String>/* User prompt displayed in the Insert */
/* Diskette panel displayed by the */
/* Specify Source Directory panel logic */
<Default Volume Label> /* Optional volume label string used by */
/* the Specify Source Directory panel */
/* logic to verify that an inserted */
/* diskette is the correct diskette */
<Resolution String> /* Optional string, which indicates a */
/* display driver resolution. */
/* The string can be passed to the */
/* Select_Display_Resolutions */
/* service function or can be left NULL. */
/* SVGA display driver sets have one */
/* resolution to a DSP file. */
/* Resolution strings should always */
/* be of the form, ####x####x####, where */
/* each #### field is a separate integer */
There is no data element parameter provided to indicate a choice of default source directory. It is always assumed to be the logical A: drive. DSPINSTL provides a Specify Source Directory PM panel that allows the user to override the default source directory. The <Default General Prompt String> is displayed in the PM panel so that the user will know the purpose of the source directory about to be searched.
If the user changes the source directory to a nonremovable device, the source files can exist in the specified directory or in a subdirectory under the specified directory. The subdirectory name must be the same as the volume label for the entry with the underscore character (_) replacing spaces. To do this, volume labels must be limited to eight characters.
The following example shows a typical SVGA display adapter parameter entry:
"XYZ SVGA video adapter"
"XYZ.DLL"
"SVGA"
"1"
"0"
"3"
"XYZ1"
"XYZ SVGA display drivers (part 1)"
"XYZ SVGA drivers diskette #1"
"XYZ 1"
"640x480x256"
"XYZ2"
"XYZ SVGA display drivers (part 2)"
"XYZ SVGA drivers diskette #2"
"XYZ 2"
"1024x786x256"
"XYZ3"
"XYZ SVGA display drivers (part 3)"
"XYZ SVGA drivers diskette #3"
"XYZ 3"
"1024x768x256"
The above example includes three resolution strings, which can be displayed in the scrolling list box in the Select Display Resolutions panel.
If DSPINSTL cannot identify the type of graphics adapter, it displays a default type of Other and also sets the default internal key to "Other". The user can then go to the Primary Video Adapter PM panel or the Secondary Video Adapter PM panel and select a display type that is included in one of the DSC file entries.
If DSPINSTL can identify the type of graphics adapter but finds no matching configuration file entry with a matching standard-type keyword string, it displays the default type-name for the adapter in the Video Display Configuration panel (such as VGA) but does not allow the user to accept the default selection. The user must use either the primary display check box or the secondary display check box in order to override default DSPINSTL processing. This will cause a secondary PM panel to be displayed that will allow the user to select a display driver package from a list that includes all the packages described in the DSC files.
User Interface PM Panels
The front-end PM panels allow the user to specify whether primary or secondary display driver installation is desired. The panels also allow the user to override the default display driver type and specify which display driver package to install (based on the set of packages defined in the relevant DSC files on the user's system).
Action Routine Interface
The action routine interface allows the display driver developer to (optionally) add custom control logic that is executed after the user makes an initial selection. Action routines are supported so that the installation process can ask the user specialized questions (through the use of PM panels) or perform internal inquiries concerning the state of the hardware or software system. For example, an action routine can be used to ask the user what display resolution should be configured. Action routines are packaged in OS/2 Dynamic Link Library files (DLL files).
The action routines tailor a display driver installation by modifying the chain of data elements that are initialized by the DSPINSTL Configuration File Interpreter. The display driver developer packages DSPINSTL action routines in a DLL file and then includes the name of the DLL file in the DSC file entry for that display driver package. The DLL itself should be placed in a directory within the user's LIBPATH or in the directory containing the DSPINSTL.EXE file.
DSPINSTL will call specifically named action routines (if they are provided in the DLL that can be specified within the controlling configuration file entry) during the installation when the user:
- Accepts the selection of the primary display (in the initial Video Display Configuration PM panel)
- Accepts the selection of the secondary display (in the initial Video Display Configuration PM panel)
- Overrides the selection of the primary display and explicitly selects a primary display (through the use of a Primary Video Adapter PM panel)
- Overrides the selection of the secondary display and explicitly selects a secondary display (through the use of a Secondary Video Adapter PM panel)
The four action routines must have the following names:
- Default_Primary()
- Default_Secondary()
- Selected_Primary()
- Selected_Secondary()
The display driver developer can provide any subset of the four action routines that is deemed appropriate. When DSPINSTL reaches one of the points at which it tries to call an action routine, it uses the DosLoadModule API to attempt to load the DLL module. If successful, it then uses DosGetProcAddr API to try to obtain the address of the action routine. If this is successful, DSPINSTL passes control to the action routine. If this is not successful, DSPINSTL continues.
DSPINSTL aids the function of the action routines by providing them with a set of service functions that enable them to perform various standard actions such as data chain maintenance. In this manner, the individual action routine does not have to be aware of the specific structure of the data element chain. Again, DSPINSTL is designed to insulate the action routine from the details of the utility program's internal structure. This greatly simplifies the creation of an action routine.
Each action routine is passed a pointer to a global DSPINSTL data structure, which contains values that can be used by the action routine. This data structure includes a revision field, which is always set to 1 by the utility program. The revision field is provided so that future revisions of DSPINSTL will be able to grow and evolve the data structure. Action routines should always check the revision field to determine how to access the data structure.
Procedure Call Interface for Action Routines
All four action routines follow the same procedure call interface, which is illustrated under Default_Primary.
DSPINSTL Service Functions
A set of standard service functions is provided to keep the action-routine developer from having to program commonly used functions. Service functions enable the user to examine and modify the DSPINSTL chain of data elements.
The global DSPINSTL data structure contains pointers to a set of DSPINSTL service functions that are available to all action routines. These service functions, listed below, are described on the pages that follow.
- Link_Chain_Element
- Unlink_Chain_Element
- Next_Chain_Element
- Select_Display_Resolutions
Link_Chain_Element
Unlink_Chain_Element
Next_Chain_Element
Select_Display_Resolutions
Command Language Presentation Manager Panels
===DSPINSTL Command Language Interpreter===
====DSPINSTL Command Language====
====DSPINSTL Commands====
====KEY====
====FILES====
=====File Version Field Checking=====
=====Date/Time Checking =====
====CONFIG====
====OS2INI====
====WININI====
====RUN====
====SET_DRIVER====
====SET_RESOLUTION ====