View source for CID Installation of SVGA Display Support

''by [[Tim Moore]]''

Because Super VGA (SVGA) cards are relatively inexpensive, the majority of personal computers in the marketplace today include some kind of SVGA card. Many of our large customers want and need to install high-resolution display drivers without user interaction - using CID (configuration, installation, distribution).

How do you CID-install SVGA support on several systems, many with different SVGA configurations? Is it possible to make the system come up in the resolution you want? This article describes how to use the latest version of IBM's DSPINSTL.EXE, an OS/2 display driver installation and configuration tool (available in Version 3 of the [[Developer Connection Device Driver Kit]] (DDK) for OS/2).

Note: If you aren't familiar with IBM's OS/2 Display Installation utility, you can find detailed information and examples in Chapter 11 of the Display Device Driver Reference for OS/2, which is part of the Developer Connection DDK.

==What Is DSPINSTL.EXE?==
DSPINSTL.EXE is an OS/2 utility for installing display drivers, with the following features:
* Is extensible with action .DLLs
* Supports display drivers spanning multiple diskettes
* Updates CONFIG.SYS and both OS/2 and Windows .INI files
* Supports packed/unpacked files
* Can replace locked .DLLs and .EXEs
* Is profile driven (.DSC and .DSP files)

==Preparing for the Installation==
The installation of SVGA support using DSPINSTL.EXE requires the following:
* You must have Presentation Manager (PM) functions and the DOS utility SVGA.EXE installed before running DSPINSTL.EXE.
* OS/2 must be completely installed and rebooted before CID installation can occur.
* Because CID installation of SVGA was not supported in versions of OS/2 prior to OS/2 Warp, tools such as DSPINSTL.EXE, SVGA.DLL, and SVGAINST.DLL must be at the OS/2 Warp level or later.

Before you begin to CID-install SVGA drivers, it is important to have the correct information and tools. First, you must know the Display Configuration (.DSC) file you want to use that maps to the correct Display Profile (.DSP) you want DSPINSTL.EXE to process. The .DSC file is an ASCII file that serves as a front end to DSPINSTL.EXE processing. The .DSC files are the key to identifying the steps necessary to obtain the correct .DSP file. These steps are described by the .DSC file using chain elements. Each chain element describes an installation step to obtain the correct .DSP file; there is usually one chain element per diskette.

Each chain element includes the following information:
* DSP key - Identifies the .DSP to process.
* General prompt - The title used in the source directory window.
* Diskette prompt - The title used in the diskette insertion window.
* Volume label - Verifies the correct diskette or subdirectory.
* Resolution - An optional string used by the action .DLL.
Of these, the DSP key and the volume label are the most important pieces of information you need. When setting up the CID tree to install SVGA drivers, the correct directory structure must be created. The volume label denotes the subdirectory to create. For example, if the volume label is DISP 1, the correct subdirectory to create would be \DISP_1 off the source directory. The DSP key, which identifies the Display Profile (.DSP) to process, must be located in this subdirectory. Once the volume label is verified (in the case of a CID installation, the subdirectory is verified), the .DSPs are searched for a matching DSP key denoted in the chain element. Once a matching key is found, the .DSP describes the installation steps for that source directory, such as what files to unpack, CONFIG.SYS updates, .INI updates, and so on. All chain elements are processed one at a time in the same manner.

Once you have determined the .DSC file to use, you're halfway home. The next step is determining what is the name of the action routine .DLL. If empty quotes ('') appear on this line, this means the .DSC doesn't use an action routine.

Note: The action routine .DLL must be at the OS/2 Warp level or later to work with CID. IBM BBS display drivers use OS/2 Warp-level action routine .DLLs and are fully CID enabled. Most independent hardware vendors (IHVs) use IBM action routine .DLLs with no changes. In most cases, you can substitute OS/2 Warp's action routine .DLL with an IHV's .DLL to CID-install SVGA support.

==Running DSPINSTL.EXE==
OS/2 Warp's version of DSPINSTL.EXE runs with the following new command line parameters:
* /PD: The path\file name for the primary .DSC file to use.
* /SD: The path\file name for the secondary .DSC file to use.
* /RES: The resolution in which you want the system to come up.
* /U Returns NetView Distribution Manager/2 return codes.
For example, you could have a driver with the following specifications:
<PRE>
Adapter type Tseng
Chip type ET4000W32
Display Configuration file TLIW32.DSC (contains two chain elements)
Source directory X:\TSENG
Target drive C:
Resolution desired 1024x768x256
</PRE>
The chain elements for TLIW32.DSC are:
<PRE>
* DSP key
'TLIW32A'
* general prompt
'Tseng Laboratories ET4000/W32, /W32i, /W32p'
* diskette prompt
'Display Driver Diskette 1'
* volume label
'DISP 1'
* Multi-resolution driver
''

* * DSP key
'TLIW32B'
* general prompt
'Tseng Laboratories ET4000/W32, /W32i, /W32p'
* diskette prompt
'Display Driver Diskette 2'
* volume label
'DISP 2'
* Multi-resolution driver
''
</PRE>
You would also need to create two subdirectories off the X:\TSENG directory, as follows:
 md X:\TSENG\DISP_1
 md X:\TSENG\DISP_2
Then copy the display driver diskettes to these new subdirectories, as follows:
 copy a:\*.* X:\TSENG\DISP_1
 copy a:\*.* X:\TSENG\DISP_2
Finally, set up DSPINSTL.EXE in a REXX command file with the following parameters (these are not case sensitive):
<PRE>
DSPINSTL.EXE
/PD:C:\OS2\INSTALL\TLIW32.DSC
/S:X:\TSENG
/T:C:
/RES:1024X768X256
/L1:C:\OS2\INSTALL\DSPINSTL.LOG 
</PRE>

==DSPINSTL Processing==
When the .DSC file is read, the action routine .DLL is processed. If a resolution string is passed to DSPINSTL.EXE with the /RES: parameter, DSPINSTL.EXE passes it to the action routine .DLL for processing. The resolution string tells the action routine .DLL to bypass the Monitor Configuration panel and run SVGA.EXE ON INIT, which generates an SVGADATA.PMI file in a DOS session. The SVGADATA.PMI file contains information about the resolutions supported by the SVGA card. The .PMI file is scanned for each resolution by searching for the [Graphics Mode] sections. The /RES: string is validated in the .PMI file by finding a matching resolution in the [Graphics Mode] sections. If the resolution is valid and supported, the following is written to the OS2.INI file to indicate the default resolution to the SVGA driver:
<PRE>
PM_DISPLAYDRIVERS The application name
DEFAULTSYSTEMRESOLUTION Key name
(5 ULONGS in HEX)
Value:
height 0x400 = 1024
width 0x300 = 768
colors 0x100 = 256
planes 0x001 = 1 (always)
options 0x040 = 64 (always)
</PRE>
Note: A /RES: parameter is required for CID installation of SVGA.

If the /RES: parameter is not valid or it is not supported by the .PMI file, then nothing is written to OS2.INI and the driver defaults to low resolution (640x480x256). If the /RES: parameter is not specified, the Monitor Configuration panel appears (which requires user interaction).

Once the action routine .DLL has finished processing, each chain element in the .DSC file is processed, as follows: DSPINSTL.EXE searches in the subdirectory specified by the volume label for a matching DSP key. For example, in the example shown above, the key TLIW32A is searched for in the X:\TSENG\DISP_1 directory to find the correct .DSP file to process. Once it is found, the .DSP file is processed. Then the next chain element is processed - the key TLIW32B is searched for in the X:\TSENG\DISP_2 directory for a matching .DSP. When it is found, the .DSP file is processed. Each chain element is processed in the same manner.

==Debugging Hints==
If you encounter problems during the CID installation of SVGA support, try the following:
*First, look in the log file. (You can create a log file by specifying the /L1: parameter, or use the default log file \OS2\INSTALL\ DSPINSTL.LOG.) The log file indicates what parameters were passed in and what .DSC and .DSP files were used. It also logs any errors that were encountered during the installation.
*If the display driver defaults to low resolution, check the SVGADATA.PMI file to see if, in fact, the resolution passed with the /RES: parameter is a valid one.
*Lastly, after installing the device driver and before rebooting the system, look in the OS2.INI file for the values PM_DISPLAYDRIVERS DEFAULTSYSTEMRESOLUTION (value). Check the value to make sure the proper hex values were written. If you cannot find these values in the OS2.INI file, chances are you are using a down-level (pre-OS/2 Warp) version of an action routine .DLL. If so, replace the action routine .DLL with a compatible OS/2 Warp version of the action routine .DLL and try again.

==Using a REXX Program to Identify the .DSC File==
What do you do if you have to install many different kinds of PCs with different SVGA cards? Which .DSC file do you use? Currently, DSPINSTL.EXE doesn't autodetect a .DSC file for you when running in a CID environment. But if you know REXX, the following example is a procedure to query the adapter type. From a DOS prompt, run SVGA STATUS and redirect the output to a file. This program returns information about the Adapter Type and Chip Type of the SVGA card installed. You then look up the Adapter Type and Chip Type (in Figure 1) to determine which .DSC file to use.
<PRE>
/****************************************************************/
/* Example REXX program to read output from svga status */
/* SYNTAX: getdsc drive:\path\filename */
/****************************************************************/

parse upper arg datafile
if datafile == '' then do
exit 1
end

/* make sure we can open the filename */
if (lines(datafile) == 0) then do
say 'ERROR: The file ' datafile 'could not be opened.'
exit 2
end

/* table for S3 and TRIDENT, Adapter names, chip names and */
/* .DSC files NOTE: to complete add the rest of the */
/* information in Figure 1 and update the */
/* numofadapters, maxnumberofchips */

adapter.1 = 'S3' /* S3 Incorporated */
adapter.1.1 = 'S386C80X'
adapter.1.1.1 = 'PSS3.DSC'
adapter.1.2 = 'S386C928'
adapter.1.2.1 = 'PSS3.DSC'
adapter.1.3 = 'S386C864'
adapter.1.3.1 = 'S3864.DSC'
adapter.1.4 = 'S386C964'
adapter.1.4.1 = 'S3864.DSC'

adapter.2 = 'TRIDENT' /* Trident Microsystems */
adapter.2.1 = 'TR8800'
adapter.2.1.1 = 'PSTRID.DSC'
adapter.2.2 = 'TR8900'
adapter.2.2.1 = 'PSTRID.DSC'

numofadapters = 2
maxnumberofchips = 4
dscfilename = 'NONE'

error = 3 /* assume SVGA not supported */

/* while lines exist in the data file */
do while lines(datafile) > 0

/* read a line from the data file */
parse upper value linein(datafile) with
AdapterType AdapterName ChipType ChipName.

/* find the correct line for AdapterType */
if compare('ADAPTERTYPE:', AdapterType) == 0 then do
nameofadapter = STRIP(AdapterName, 't', ',')
nameofchip = STRIP(ChipName, 't', ',')
error = 0
leave
end
end

if error == 3 then do
say 'ERROR: SVGA.EXE did not detect SVGA on this machine'
exit error
end

error = 4 /* assume adapter not found */
do name = 1 to numofadapters
if compare(adapter.name, nameofadapter) == 0 then do
error = 0
leave
end
end

if error == 4 then do
say 'ERROR: Adapter type ' nameoradapter ' was not found'
exit error
end

error = 5 /* assume Chip type is not found */
do cname = 1 to maxnumberofchips
if compare(adapter.name.cname, nameofchip) == 0 then do
dscfilename = adapter.name.cname.1
say 'DSC file to use ' dscfilename
error = 0
leave
end
end

if error == 5 then do
say 'ERROR: Lookup failed, a .DSC was not found'
say 'ChipType ' nameofchip 'was not found'
exit error
end

exit error
</PRE>
The table below contains adapter and chip information for the .DSC files that are part of OS/2 Warp:
<PRE>
.DSC File Name Adapter Type Chip Type Name

PSHEAD.DSC VIDEO7 HT205
HT208
HT209

PSTRID.DSC TRIDENT TR8800
TR8900

PSTSENG.DSC TSENG ET3000
ET4000

TLIW32.DSC TSENG ET4000W32
ET4000W32IREVA
ET4000W32IREVB
ET4000W32IREVC
ET4000W32PREVA
ET4000W32PREVB
ET4000W32PREVC
ET4000W32IREVD
ET4000W32PREVD

PSWD.DSC WESTERNDIGITAL PVGA1A
PVGAB
PVGA1C
PVGA1D
WD90C26
WD90C27

PSWDC31.DSC WESTERNDIGITAL WD90C31

PSWDC24.DSC WESTERNDIGITAL WD90C24

WDC33.DSC WESTERNDIGITAL WD90C33

PSATI.DSC ATI ATI18800
ATI28800

ATIM32.DSC ATI ATI68800MACH32

ATIM64.DSC ATI ATI88800MACH64

PSSPDW.DSC IBM IBMSVGA

PSC1.DSC CIRRUS GD5420
GD5422
GD5424

C154X.DSC CIRRUS GD5426
GD5428
GD5429
GD543X
GD5434

PSS3.DSC S3 S386C80X
S386C928

S3864.DSC S3 S386C864
S38641M.DSC S386C964

WP9000.DSC WEITEK P9000

WP9100.DSC WEITEK W5186
W5286
P9100
</PRE>
''Figure 1.''

Note: Resolutions supported by each driver depend on the amount of video memory available.

==Summary==
CID-installing SVGA support is straightforward if you know what to look for. Make sure you are using the latest version of DSPINSTL.EXE and action routine .DLLs. In addition, you must run DSPINSTL.EXE as a post-installation method using the correct parameters. You'll need to know what .DSC file to use, and then create the proper CID tree structure based off the chain elements in the .DSC.

This information should help you better understand the procedures for CID installation of SVGA display drivers.

{{IBM-Reprint}}
[[Category:Developer Connection News Volume 9]]