DDDR/2 - SVGA Base Video Subsystem

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation =SVGA Base Video Subsystem= The base video handler (BVHx) display drivers handle all non-graphical primitive video device functions, such as mode set, palette loading, and all of the text-related functions. Base video handler architecture is described in full detail in Physical Video Device Drivers

Overview
The application interface to take advantage of the base video handler functions is the 16-bit VIO interface, which is also available to 32-bit applications via a thunking layer. Because most of the text-mode related functions are "VGA legacy," there is little need for customizing that part of the base video handler for each new device.

Most of the need for customization comes from the fact that set mode functions are widely different on today's SVGA devices, even across different adapter implementations of the same SVGA chip set. Historically, there was no system support for invoking the real-mode video BIOS for the purposes of the set mode. As a result, customization of the base video handler to handle different SVGA chip sets and their adapter implementations became a norm. The goal then became to externalize the device-specific programming into another 32-bit interface, which was done by the introduction of the VIDEOPMI handler and the SVGADATA.PMI file.

Hence, the SVGA base video handler (BVHSVGA) is a generic driver that imports device-specific functions from VIDEOPMI. VIDEOPMI's interface is also available to any other 16- or 32-bit application. For a full description of the VIDEOPMI's procedural interface, see VIDEOPMI.DLL Exported Functions. For a full description of the PMI subsystem see VIDEO Protect-Mode Interface.

Resolution, monitor, and refresh configuration in OS/2 are standardized and handled by the System icon's first two pages. Monitor and refresh configuration are available for both legacy and DDC-compliant monitors. The function is internally handled by a component called VIDEOCFG. The full specification of the VIDEOCFG's function and exported procedural interface is provided in VIDEOCFG.DLL Exported Functions.

Although most of today's display drivers rely on the VIO subsystem (BVH) to set the mode, that is not mandatory. The new display driver architecture (GRADD) does use the VIDEOPMI's interface directly. When using VIDEOPMI's interface directly, the display driver is responsible for setting all of the mode parameters (there is a considerable difference in mode parameters between the VIO and VIDEOPMI). In such a case, the display driver has to do the following:
 * Invoke VIDEOCFG to retrieve the current configuration
 * Transverse the mode table as returned by the VIDEOPMI
 * Find the most appropriate entry
 * When setting the mode, supply any dynamic mode entry values in the VIDEO_ ADAPTER.MODEINFO structure on the call to VIDEOPMI's PMIREQUEST_SETMODE

Display drivers using the traditional VIO mode set do not need to use VIDEOCFG, provided that their base video support is using the generic IBM BVHSVGA and has externalized the device support via the PMI subsystem.

A display driver vendor may also opt to issue the mode set by using VIDEOPMI's software interrupt services (VIDEO BIOS mode set) without any customization of the PMI subsystem. This approach, however, does not allow for monitor and timing configuration, because VIDEOCFG bases the configuration on the existence of a mode table that includes timing parameters, which is imported from the PMI subsystem. For sample source on how to use VIDEOPMI's software interrupt, see src\oempmi sources and search for PMIREQUEST_SOFTWAREINT. For more specific information on the software interrupt service, see VIDEOPMI.DLL Exported Functions and.

Note: The PMI subsystem, including the video configurator VIDEOCFG, will run on both OS/2 Warp, Version 3 and the OS/2 2.x base. See Video Subsystem Binary Files as well as Installing Video Configuration Manager for OS/2 in VIDEOCFG.DLL Exported Functions.

How to Customize the PMI Subsystem for Your Device
The VIDEO PMI subsystem consists of VIDEOPMI - the main PMI handler, a flat PMI file, and optional imported library modules. The imported library modules may optionally chain into VIDEOPMI and provide a filter or replacement for VIDEOPMI's entry points. Such a library is called a META-PMI handler. Although the VIDEO PMI subsystem places no requirements on the existence of a flat PMI file (it is possible to provide all functions with a META-PMI handler alone), the SVGA installation, SVGA virtual video driver, BVHSVGA, and VIDEOCFG all make assumptions that the PMI subsystem is represented by SVGADATA.PMI.

With the new feature install (OS/2 Warp, Version 3, PowerPC Edition) and GRADD architecture, these assumptions will be removed; that is, the SVGADATA.PMI file will no longer be assumed to exist. Existing support for flat PMI files remains intact and these files are fully supported as described in VIDEO Protect-Mode Interface.

The VIDEOPMI handler is maintained by IBM; it is shipped in the IBM Developer Connection Device Driver Kit for OS/2 as a binary file. See Video Subsystem Binary Files. The SVGADATA.PMI file is either provided or can be created at install time by running a utility. The SVGA installation action routine DLL (SVGA.DLL) assumes that a DOS utility called SVGA.EXE is used to generate the SVGADATA.PMI. A vendor wishing to modify the SVGADATA.PMI can provide its own action routine DLL or create the SVGA.EXE DOS utility. DDK sources include two different sources of a utility that generates the SVGADATA.PMI file, as follows:
 * src\svdh\svgautil\svga.exe

src\svdh\svgautil sources are those of the SVGA.EXE as shipped by IBM. It is a very large and complex source that generates a .PMI file for all of the devices supported by the IBM BBS display driver packages at the time the IBM Developer Connection Device Driver Kit for OS/2 was shipped.

It is not recommended that vendors modify this source; it is shipped so that vendors can create sample .PMI files for legacy hardware. .PMI files created by this utility use IBMGPMI.DLL as an imported PMI library. The source for IBMGPMI.DLL is not available for vendor modification, but a binary file can be extracted from the most current IBM BBS video driver package. An older version of IBMGPMI can be found in previous DDKs.

For purposes of documenting an imported PMI library, an alternate library source in src\oempmi for OEMPMI.DLL is provided. This PMI library exemplifies both internal PMI calls and the META-PMI interface (chaining into VIDEOPMI). It also provides an example of using the VIDEOPMI's software interrupt API to call the VIDEO BIOS directly.
 * src\oempmi\svgautil\svgaoem.exe

src\oempmi\svgautil sources are the recommended sources for vendor modification. The makefile will generate an SVGAOEM.EXE, which should be renamed to SVGA.EXE if the SVGA.DLL action routine DLL is to be used. The utility will create a generic SVGADATA.PMI file based solely on VESA mode support without any vendor modifications. This generic .PMI file depends on the OEMPMI.DLL META-PMI handler, referred to in the previous bullet, for successful VESA BIOS calls. If there is no VESA support for the adapter, or vendors wish to add refresh support or customize the generic sections, the SetupChipInfo function in SVGAOEM.C needs to be modified. The header of the SVGAOEM.C source file includes the "ROADMAP to CHANGES" instructions.

src\oempmi sources are open to vendor modification, and its headers also include extensive instructions on the recommended changes. However, for a vendor with VESA mode set support and a display driver that can run on top of the hardware state as left by the VESA mode set, the quickest results are obtained by doing the following:
 * Install all of the Base Video Subsystem files
 * Create a .PMI file by running the unmodified SVGAOEM.EXE with command line argument "ON".

Device Detection
Device detection is built into both SCREENx.SYS PDD and SVGA(OEM).EXE. SVGA (OEM).EXE does not need to have device detection added if the generic .PMI file is sufficient. However, as a courtesy to the customer running the drivers and a safeguard against running inappropriate drivers, some device detection should be built into either or both of the modules.

SCREENx.SYS PDD does not have to be modified to add device detection, unless the vendor wishes to use the default .DSC file-selection feature of the display driver installation utility. SVGADEFS.H contains _ADAPTER IDs that are reserved for vendor use for this purpose. For vendors who would like to have a new _ADAPTER ID allocated, a call to DUDE with the request and the name of the vendor is required. When adding device detection to SCREENx.SYS PDD, the allocated ID should be returned. Detection function IdentifySVGA in svgaid.asm is common to both SCREENx.SYS and SVGAOEM.EXE (SVGA.EXE), with the exception that the PCI detection is invoked only in the PDD, not in the utility. The PCI interface, as used by the SCREENx.SYS, is exported by the OS/2 loader's OEMHLP PDD. Its full interface is documented in inc\pci.inc and samples PCITEST.C and PCITEST.H in src\oempmi. As code is added to SVGAID.ASM, it should be propagated to both SVGA.EXE and SCREENx.SYS PDD. The makefiles will take care of conditional compilation for both modules.

Video Subsystem Binary Files
The following is a complete list of base video modules. Those shipped in their source format, which can be optionally modified, are to be compiled by a vendor and are marked as such. Modules that do not require any vendor modification are also provided because they either did not exist in all of the previous OS/2 versions or they have been upgraded.

SVGADEFS.H
This is the main header file for SVGA video support. It contains VIDEOPMI's structures and function table, VIDEOCFG structures, and function prototypes. It also contains the SCREEN PDD structures and function numbers, as well as device detection ID lists (Adapters and Chipsets structure). A vendor needs to update this file and add detection to SCREEN PDD only if automatic (machine key) selection of the .DSC file is desired during the display install. If a new device ID needs to be allocated, a request for new ID should be submitted to DUDE.

SCREEN01.SYS
This is the base video physical device driver. Source can be found on src\ dev\screendd. This driver provides device detection and additional video services, such as linear buffer memory mapping. These services are part of Category 80 IOCTL functions. The list of functions and associated structures can be found in the OS/2 Physical Device Driver Reference, Chapter 11, "General IOCTL Commands" under "Category 80h Screen IOCTL Commands".

PCI processing in this physical device driver is limited only to finding devices of video class and their vendor IDs. For vendors who need to examine more of the PCI header, there is no need to expand this PDD - OEMHLP PDD IOCTLs, which provide the PCI functionality, can be called at ring3. See sample source src\oempmi\pcitest.c.

BVHSVGA.DLL
The generic SVGA base video handler. This module is provided in source format in src\svdh directory. Modification is not required.

Attention

Do not mix this BVHSVGA with a VIDEOPMI from an older DDK. Some structures in h\svgadefs.h have been expanded; the modules using VIDEOPMI's structures - VIDEOCFG, VIDEOPMI, BVHSVGA and OEMPMI - should all be at the same level.

If a vendor needs to build BVHSVGA compatible with an older VIDEOPMI, a macro, VIDEOPMI_30_LEVEL, should be defined before including h\svgadefs.h and the component should be rebuilt.

SVGAOEM.EXE
The generic SVGA.EXE utility for creation of an SVGADATA.PMI file. It is provided in source format in src\oempmi\svgautil directory. Modification is not required unless refresh support or a non-generic feature is desired.

OEMPMI.DLL
A sample imported PMI library. It works with the SVGADATA.PMI file as created by SVGAOEM.EXE. OEMPMI.DLL is provided in source format on src\oempmi directory. Modification is not required unless a vendor wishes to add refresh support. The source exemplifies the META-PMI chaining as well as usage of VIDEOPMI's software interrupt services.

VIDEOPMI.DLL
The main PMI handler. Originally just a PMI language interpreter, it is now expanded to handle imported PMI libraries as well as META-PMI chaining. The driver is shipped as a binary file only and can be found in the video\bin directory. This version is the first to provide software interrupt services (calling real-mode BIOS). and should not be mixed with older BVHSVGA, IBMGPMI, or VIDEOCFG, due to changes in some structures in h\svgadefs.h.

VPRPMI.SYS
A private PMI virtual device driver providing software interrupt services. It should be installed in CONFIG.SYS as DEVICE=X:\OS2\MDOS\VPRPMI.SYS. If a vendor is using software interrupt services, but has to ship its drivers to a customer who prefers to not install DOS support, a private kernel upgrade is available upon request to provide an alternate VDM service. In that case, the VPRPMI.SYS driver is not required. The driver is shipped as a binary file only and can be found in the video\bin directory.

VIDEOCFG.DLL
The video configurator. This module handles the System icon notebook page 1 and page 2. These pages allow for monitor configuration, resolution and refresh configuration, as well as generic display driver settings configuration. The module is shipped as a binary file in the video\bin directory. The rest of the modules in this list are support modules for VIDEOCFG.DLL. For a full functional description of VIDEOCFG, see VIDEOCFG.DLL Exported Functions.

Attention

Due to changes in some PMI structures in h\svgadefs.h, this module needs to be at the same level as the VIDEOPMI. As a result, an older VIDEOCFG, when mixed with a new VIDEOPMI, will not generate page 2 and refresh listbox. The same is true when a new VIDEOCFG is mixed with an older VIDEOPMI. Note that resolution dialog should not be affected in either case. No execution exceptions are expected when mixing components, only functional failures.

Note: Prior to the November 1995 IBM Developer Connection Device Driver Kit for OS/2, there was a VIDEOCFG.206 module that represented the 2.x version of VIDEOCFG.DLL. The VIDEOCFG.206 module is no longer needed, because its function has been consolidated into a single VIDEOCFG.DLL. Vendors who have already set up their install procedures to assume the existence of VIDEOCFG.206 should copy VIDEOCFG.DLL as VIDEOCFG.206. Using the older VIDEOCFG.206 will cause the incompatibility problem covered in Attention above.

VCFGMRI.DLL
The resource module for VIDEOCFG.

WPVIDSYS.DLL
This module is used when installing VIDEOCFG.DLL on OS/2 2.x. It replaces the class of WPSYSTEM in order to transfer ownership of the System icon pages from the Workplace shell to VIDEOCFG.DLL. Required only on 2.x. The subclassing becomes active only after this module is installed and the system is rebooted. The binary file is available in the video\bin directory.

VCFGINST.EXE
This module is used to install WPVIDSYS.DLL on OS/2 2.x. VIDEOCFG.DLL will not be active on 2.x unless this utility is executed, WPVIDYS.DLL and VIDEOCFG.DLL are in the LIBPATH, and the system is rebooted following the execution of the utility. The binary file is available in the video\bin directory.

MONITOR.DIF
The monitor database. This flat file contains timing descriptions for a large percentage of today's non-DDC-compliant monitors. The timings were obtained from the manufacturers' user manuals, and are not guaranteed to be correct or the most optimal. The entries can be added to or edited and, if new entries are submitted to the DUDE, they will be added to the master copy of the MONITOR.DIF. For vendors doing SID or RIPL install, new entries also can be placed in PRIVATE.DIF, which would leave MONITOR.DIF as read-only. MONITOR.DIF is available in the video\bin directory and should be placed into DPATH.