How to convert from 2.1 base video into 3.0 base video in order to take advantage of the monitor configuration feature of the 3.0 system icon

By IBM

From: IBM Solution Developer Support

DevCon DDK 2.0 Display Driver on-line reference contains the new PMI syntax as well as VIDEOPMI's and VIDEOCFG's calling interface.
 * Hint 1)

Run DevCon DDK's SVGA.EXE on any non ICD clock based S3 928, S3 864, or Tseng W32 for a working sample that contains all of the refresh programming within the file. Run it on any ICD based S3 or W32 or on any Cirrus 3x to get a sample which imports refresh programming from the IBMGPMI.DLL. Run it on Diamond Viper 9000 VLB for a sample of memory mapped PMI file.
 * Hint 2)

SVGADEFS.H header file features all of VIDEOPMI, VIDEOCFG API's as well as associated structures. It also contains chip-ID, DAC and other adapter related lists. The file is imported by BVHSVGA.DLL, PMDISPLAY.DLL, VIDEOPMI.DLL, VIDEOCFG.DLL, SVGA.EXE, VSVGA.SYS and any other component which wishes to use VIDEOCFG or VIDEOPMI's interfaces.
 * Hint 3)

Display driver reference lists the binary files that compose the base video subsystem and explains the difference in the installation between 3.0 and 2.1. Search for VIDEOCFG to see all references.
 * Hint 4)

Q. Why use System Icon monitor configuration vs custom configuration?
System Icon provides a large pool of legacy monitors and provides a consistent device independent resolution/refresh/monitor configuration. The OS/2 3.0 System icon configuration support can be installed on 2.1 and will be supported on future versions of OS/2. Its initial configuration reflects the configuration that was performed by the BIOS, but if that is modified, it can also under the covers be used to configure the BIOS for new configuration. VIDEOCFG, the binary module which owns the System's video pages also has a generic capability interface which allows for expansions of configuration, if a vendor needs additional pages, ie a page for font selection, orientation selection or any other discrete value configuration.

The interface description is attached to this document. As an addendum, there is also a sample of using the profiling services which allow drivers to modify WinOS/2 INI files.

Q. What is needed to get the System icon to display the monitor list?
A. The svgadata.pmi file has to have at least one graphics mode with a MonitorModeInfo section. This signifies that the base video system can take into account monitor capabilities.

Q. What is needed to get the System icon to display the Monitor size button?
A. The svgadata.pmi file has to have the [TuneDisplay] section and startup values for ScreenLeftEdge, ScreenRightEdge and so forth. The support for the monitor sizing may not have made it into the DDK, but a binary refresh of the VIDEOCFG is available on request.

Q. How are monitor's capabilities described in OS/2?
A. OS/2 has a prebuilt database of about 300 monitors. The list is ordered alphabetically (descending order) by monitor manufacturer name.

Each monitor is described in terms of the resolutions it supports and in terms of the maximum refresh value per each resolution. The syntax doesn't allow for optimum or multiple timing choices. The database is a flat file that can be modified, MONITOR.DIF. VIDEOCFG.DLL exports API's that allow for monitor database queries and expansion.

Q. Where is the current configuration stored?
A. Current monitor configuration capabilities as well as the current refresh for each mode and screen sizing information are stored in a flat file VIDEO.CFG whose syntax is very close to PMI. The content can be queried or changed by calling VIDEOCFG.DLL's configuration APIs.

Q. Where is the default monitor coming from?
A. SVGA.EXE formats the very first VIDEO.CFG which communicates to the configurator the current refresh configuration as left by the BIOS. We have assembled per-adapter information that lets us understand how each vendor records their refresh configuration. These values are formated into the VIDEO.CFG. If SVGA.EXE doesn't format the file, the very first monitor from the MONITOR.DIF database is chosen. Otherwise, the original VIDEO.CFG monitor (DEFAULT) capabilities are added to the MONITOR.DIF so that the customer can go back to the BIOS configured monitor capabilities.

DDC support: DevCon DDK's SVGA.EXE and the configuration do support DDC1 standard. SVGA.EXE formats the VIDEO.CFG with the DDC1 queried capabilities and marks the monitor as DDC. This automatically excludes any monitor from the database, and the customer is not offered monitor selection page, but does have refresh choices per mode on Page 1. In order to change from a DDC monitor to a non-DDC monitor, the current VIDEO.CFG's monitor name has to be changed from the "DDC" keyword to anything else, or a SetCurrentCFG API has to be issued into the VIDEOCFG.DLL and a name other than DDC has to be specified for the current monitor's name.

Q. Where are the refresh values in the refresh listbox on Page 1 coming from?
A. Resolutions offered represent the resolutions returned by the display driver that are also available from the SVGADATA.PMI file (VIDEOPMI mode query is performed).

If at least one of the resolutions in this group has a [MonitorModeInfo] section, the refresh box will be offered. The content of the refresh box is tied into the currently selected resolution. The refresh values are those that are found in the SVGADATA.PMI (VIDEOPMI mode query list) that are within the range of the currently selected monitor. The highlite (default) is on the highest value in the listbox (unless over-riden by the customer). Changing the selected monitor affects the range and elicits immediatate change if the range has been diminished. If the range is increased, the configured refresh remains the same and has to be increased by the customer, if so desired.

Q. What does "DEFAULT" entry in the refresh listbox mean?
A. If the very first VIDEO.CFG has 0xFF for the resolutions vertical refresh, the entry "DEFAULT" will be highlited in the refresh box. The actual set mode will also pass the 0xFF in the mode structure, so that the selection of the refresh is entirely upto the PMI subsystem (PMI file or imported binary which handles the setmode function).

This can be used in places where startup configuration of an adapter is not known to begin with but the base video subsystem has ways of setting appropriate (non-harmfull) refresh values. If the svgadata.pmi contains [MonitorModeInfo] sections with refresh entries other than 0xFF, the refresh listbox will also contain those, but the customer would have to over-ride the default highlite.

As soon as an actual (non-DDC) monitor is chosen, the DEFAULT will no longer be a valid option in the refresh listbox. Going back to the original monitor "DEFAULT" would put the "DEFAULT" refresh entry into the listbox.

Q. How could a vendor be non-commital about the refresh values it supports?
A. The vendor could provide a single [MonitorModeInfo] section which represent its highest refresh capability. This will be filtered against the monitor's capabilities (the monitor's range is always the highest refresh entry). This will effectively notify the customer that only one (highest capability of the monitor) refresh can be offered.

The vendor could specify its [MonitorModeInfo] entry to be so high, that no monitor is discriminated against. However, we strongly urge that the monitor's refresh value passed into the setmode be respected and set as close as possible. There are possibly some legal troubles if the values requested are not within a margin. Such regulations, such as ISO 9000 specification are established and enforced by countries where our product is sold and not by IBM.

Q. Could OS/2 configuration serve to configure BIOS/WIN-OS2?
If the setmode function servicing the requested refresh also sets configuration registers used by the BIOS / WIN-OS2 driver before or after it changes the clock registers, this will affect non-OS2 mode sets as well. It is not recommended that non-OS2 application read the VIDEO.CFG as its format is open to change. The GetCurrentCFG and GetCurrentDesktopMode API's are exported by the VIDEOCFG.DLL for OS/2 apps so that the current monitor capabilities and current resolution/refresh/monitor sizing values can be read.

Q. How could new monitors be added to the list?
A. A new monitor can be added by using AddMonitor API exported by the VIDEOCFG or by manually editing the MONITOR.DIF file.

Q. Are customers configuring their monitor or the refresh in OS/2?
A. The answer is both if the vendor's PMI file has more than one [MonitorModeInfo] section per mode. Meaning that after selecting the monitor, the customer still has multiple refresh choices if the PMI file had multiple refresh entries for the current mode below the monitor's end-of-range. Some vendors have utilities which are geared towards monitor configuration (fairly limited monitor list is usually the problem) and some are geared towards the refresh value setting (most users have hard time understanding what the refresh means). We have a 2 pronged configuration which, in absence of DDC, lets user chose a monitor as a way of limiting the highest refresh and then still select one of the more standard timings for a given resolution.

Q. Who is responsible for setmode vs who could do the setmode?
A. In IBM shipped base video subsystem, all of the Set modes are issued by BVHSVGA using the VIDEOPMI subsystem. BVHSVGA contains no device specific code and it services both text mode and graphics modes. It takes into account any possible configuration by using VIDEOCFG.DLL's exported entry points and thus ensures that the customer configuration request reaches the device specific layer in the PMI subsystem.

There are vendor solutions which do not use BVHSVGA (or any other base video handler) to set the mode but do it directly in their display drivers. Some vendors have device specific code within the BVHSVGA or a PDD and also use alternate configuration methods to accomplish a setmode. Any of these combinations can be converted to the PMI based base video subsystem in order to take advantage of the common GUI interface for the monitor/ refresh configuration, thanks to the fact that the new PMI extensions allow for 32bit binary imports as well as inclusion of other PMI conforming flat files.

Q. How can the System Icon refresh support be installed on 2.1?
A. See display driver on-line reference for the explanation on the installation (list of binary files for either version as well as the explanation on what is what). video\bin directory on the CD contains all the binaries that don't need to be modified. bvhsvga.dll doesn't need to be modified either, but is not in this directory, it instead has to be built in the src\svdh.

You can also download the S3_864.ZIP from CompuServe, OS2SUP library 23 (search for 86C84 and UPGRADE keywords).

Q. What if my questions have not been answered?
Post your inquiry on the DUDE and ask for Senja Petrujkic and I'll address the issue.

BASIC PMI PREMISES
Mandatory sections: [Hardware],[TrapRegs] Used by the configuration and virtual video subsystem.

Mandatory if applicable (read the PMI spec more info): [Unlock],[Lock],[Cleanup],[SetBank] Used by base video subsytem and the virtual video subsystem.

Required if no other subsystem provides setmode function [ModeInfo],[SetMode] Used by the base video subsystem.

Required if monitor configuration desired [MonitorModeInfo] Used by the configuration.

Required if monitor sizing desired [TuneDisplay] Used by the configuration

How to modify IBM shipped SVGA.EXE for a new adapter
It is possible to use IBM shipped SVGA.EXE to format such PMI file, a new CHIPINFO has to be added and sAdapter structure and REGDATA structure has to be changed to reflect that a call into the imported DLL is to be issued. If no other IO is to be issued before or after the setmode, it is enough to set sAdapter.FormatSectionFlag = CALL_SET_MODE in which case a predefined pnfPMISetMode call is to be issued. In case when there are additional IO functions to be issued, the REGDATA array for each setmode can include PMICMD_CALL at the appropriate place. The name of the function can be arbitrary.

sAdapter.RefreshTable should point to the refresh table associated with each of the supported modes and which refresh entry to be formatted into the VIDEO.CFG as a default. The table can be modified at run time in the GetCurrentMonitorSelection, if need be.

sAdapter structure also defines most of the [Hardware] section entries and most of it is automated. SVGADEFS.H file has to be expanded to include the new adapter/chip ID and these serve as indecis into ADAPTERS and CHIPNAMES lists that are also defined in that header file. Memory size is queried by issuing a Vesa query. Many DACS are already automatically detected, provided that the pifnSVGADACGetType is taking care of possible novel DAC addressing modes (there is a huge pool of DAC code within SVGA.EXE for most contemporary DACs).

How to modify base video modules

 * Scenario 1)
 * Base video support (set mode function) provided by a PDD.


 * Solution
 * Write a private real mode DOS utility SVAG.EXE which formats a SVGADATA.PMI file that contains mandatory sections and [ModeInfo] hdaders for all of the supported graphics modes. For each graphics modeinfo provide a number of [MonitorModeInfo] sections which list all of the possible (or desired, or single end-of-range) vertical refresh values. Let a [SetMode] (one for all [MonitorModeInfo] sections) provide a single function call into a 32bit DLL which calls the PDD to set the mode.  If the PDD interface does take care of the refresh, add the refresh value to it, if not, program the clock registers either in the DLL or in the PMI file after the PDD's setmode returns.


 * New Binaries
 * your (IBMGPMI) DLL, your PDD, your (IBM) SVGA.EXE, IBM BVHSVGA, IBM VSVGA


 * Scenario 2)
 * Base video support (set mode function) provided by a BVH or by the PM driver.


 * Solution
 * As in above, a PMI file with correct sections has to be formatted either by providing your own SVGA.EXE or by modifying IBM's SVGA.EXE. The body of code which handled setmode has to be moved either into the imported 32bit DLL (your own or modified IBMGPMI).  If the function was provided by the PM driver, the driver needs to issue GetCurrentDesktopMode and PMIREQUEST_SETMODE call into the VIDEOPMI(see VIDEOPMI's API interface)


 * New Binaries
 * your (IBMGPMI) DLL, your (IBM) SVGA.EXE, IBM VSVGA


 * Optional
 * IBM BVHSVGA : if PM driver doing the setmode directly, the old BVH can be kept (if it is not using 2.1 PMI file).


 * Scenario 3)
 * Base video support is being developed from scratch or some support existed in the IBM shipped 3.0 modules.


 * Solution
 * Modify or write a new SVGA.EXE to create/enhance the PMI file. Use any combination of internal/external function calls that achieves your goals the best.  If external functions are preffered, IBMGPMI source in src\refresh can be modified or used as a model.  This component unfortunatelly uses IBM C-Set2 compiler (unlike the rest which use cl386), so its modification requires that the compiler be installed.


 * BVHSVGA doesn't need to be mofified, instead the one on src\svdh can be built and shipped.

Q. What if a chip vendor wishes to keep the PMI flat file and the imported DLL as generic chip support and let individual adapter vendors take care of adapter specifics?
A. The delegation of adapter specifics can be done by including an adapter-provided flat file containing internal sections (functions) which define the adapter specifics that are otherwise not covered. The inclusion of a flat file is only allowed if such file contains entire sections, splitting a single section into two PMI files is not supported. Use #include directive in the svgadata.pmi and a standard name. The PMI file to be included must be in the datapath. If the loading fails, the sections defined in it are ignored where refferenced and the rest of the SVGADATA.PMI is processed as if the failure didn't occur.

The adapter-specifics could also be provided in an imported DLL by invoking exported functions where appropriate. However, failure to load such DLL will fail the loading of the PMI file altogether.

Here is an example of how to let individual adapter manufacturers specify the refresh configuration and possible refresh modifications outside of the main body of the setmode. // SVGADATA.PMI [Hardware] bla-bla
 * 1) includecode "MYDLL.DLL"               //exports pfnPMISetMode
 * 2) include "REFRESH.PMI"                 //defines ConfigureRefresh (optional!)
 * 3) include "REFRESH.DLL"                 //exports pfnFixRefresh    (optional!)

... [ModeInfo] bla-bla [MonitorModeInfo] [MonitorModeInfo] [MonitorModeInfo] ... [SetMode] ConfigureRefresh;              //optinal, for demo purposes only call pfnPMISetMode; call pfnFixRefresh;            //optinal, for demo purposes only

EOF //REFRESH.PMI [ConfigureRefresh]             //definition of the function bla-bla

Q. What if a vendor has a binary it wishes to keep which has dependencies on the 2.1 style PMI file?
A. It is possible to use bvhsvga, vsvga and videopmi from 3.0 on top of 2.1 PMI files as both VIDEOPMI and IBM shipped vsvga support the old syntax and bvhsvga uses the VIDEOPMI interface directly and is thus shielded from PMI syntax changes.

However, no advantage can be taken from the new PMI extensions (configuration support will be inactive).

In order to take care of the extensions, the syntax of the PMI file has to be upgraded. Once upgraded, it is not possible to use IBM shipped 2.1 level BVHSVGA or VSVGA!!! as they do not understand the new syntax and would fail to process the PMI file. Non-PMI based 2.1 virtual driver can be used. Non-PMI based base video handler can also be used, if the PM driver is taking care of the mode set via VIDEOPMI instead of VioSetMode call. Otherwise, the best bet is the 3.0 bvhsvga which is solely VIDEOPMI based and requires no modifications for new devices.

WHAT IS NEXT ON PMI FROM IBM
1) At the Technical Interchange in New Orleans this month, we will demonstrate a PMI generation/debugging tool as well as execution of the video BIOS code for the purposes of the setmode in the PMI, for both Intel and PPC platforms. No commitment to any particular DDK release for vendor's use has been made but we are working on it.  Execution of the BIOS code can be proceeded or followed by any other PMI command in order to perform configuration or fix-ups.  Thus, the BIOS is incorporated into the PMI execution by a virtue of an imported function call, the usage of which is at the discretion of the vendor.

2) VIDEOPMI (PMI) specification will be expanded to allow us to handle more of the configuration features (extensions to IdentifyAdapter, EnableController) and power saving functions (new). Planned for next release of the Intel OS/2, but once supported in Intel will be supported on PPC as well.  Any future syntax upgrades will not affect the support of the existing PMI syntax.

3) The long-term goal is to keep narrowing the device-specific specification and have interfaces that are general enough to be taken from one operating system/host chip platform to another. Base video handlers will not exist in the new display driver architecture (based on the GRADD model) and virtual driver specification has been reduced greatly.  The new architecture will be supported on the first OS/2 for PPC and future releases of OS/2 for Intel.  The issue of whether the old (current Intel OS/2 architecture) will be supported along with the new architecture on the future releases of the Intel OS/2 has not been resolved yet.  The vendors which have based their current base video support on the current PMI architecure will automatically be supported on any future release of the Intel platform.  Their flat PMI files will also be supported on any PPC OS/2, but their imported Intel PMI .DLL's will have to be recompiled for the PPC platform.

GENERIC PM DRIVER CAPABILITY CONFIGURATION INTERFACE SPECIFICATION
Video configuration manager supports a generic video configuration interface, that allows any display driver to interface with the user via notebook settings in the System icon. The driver needs to export DevEscape calls which identify the capability and provide DevEscape calls which allows the VIDEOCFG to query the current value and notify the driver when the user sets the value. The DevEscape functions are invoked as Ring3. The method of recording the current setting as well as default values are at the drivers discretion.

DevEscape command codes :


 * 1) define DEVESC_QUERYDRIVERCAPS      40010L
 * 2) define DEVESC_QUERYDRIVERCAPSLIST  40011L
 * 3) define DEVESC_SETDRIVERCAPSVALUE   40012L

1) DEVESC_QUERYDRIVERCAPS: This function returns the capabilities descriptions. The values for each capability are not allocated yet and are queried later.


 * LONG lInCount :Not used.


 * PBYTE pbInData : Not used.


 * PLONG plOutCount : The number of bytes of data pointed to by pbOutData. On return, this is updated to the number of bytes returned.


 * PBYTE pbOutData : The address of a buffer, which on return contains a ULONG variable specifying the number of capabilities that the driver supports, immediately followed by array of DRIVERCAPS structures.

Note: this allows a driver to export multiple capabilities (each in turn gets its own page in the System icon). typedef struct _DRIVERCAPS {    ULONG ulCb;                  /* length of the source structure in bytes */ CHAR szCapsDesc[256];       /* capability description                  */ CHAR szHelpFileName[256];   /* help file name                          */ ULONG ulHelpId;             /* help resource id                        */ ULONG ulCapsType;           /* define the data type that will be       */ /* returned in pValueList, pCurrentValue  */ /* and pDefaultValue                      */ ULONG ulValueMemberSize;    /* size of each member                     */ ULONG ulNumValueMember;     /* number of members if aggregate          */ PVOID pValueList;           /* pointer to storage for the members data */ PVOID pCurrentValue;        /* pointer to the current selected value   */ PVOID pDefaultValue;        /* pointer to the default (reset) value    */ /* if driver supports default setting     */ BOOL bDefaultValueSupported;/* return TRUE if driver supports default  */ /* value                                  */ BOOL bStaticCaps;           /* return TRUE if system needs a reboot    */ /* for the new capability to take effect  */ } DRIVERCAPS, *PDRIVERCAPS; pValueList, pCurrentValue and pDefaultValue should not be set in this call. Video Configuration Manager will allocate memory for them and the driver will fill them on the next function DEVESC_QUERYDRIVERCAPSLIST.

There are three kind of data types that we are supporting at the present time. They are boolean, aggregate of int values and aggregate of strings. They are defined below.

#define CAPSTYPE_BOOLEAN           1L #define CAPSTYPE_AGGREGATE_INT     2L #define CAPSTYPE_AGGREGATE_STRING  3L

2) DEVESC_QUERYDRIVERCAPSLIST: This fills the pValueList, pCurrentValue and pDefaultValue. The members must be 0 padded up to the ulValueMemberSize in the pValueList.


 * LONG lInCount : Number of bytes pointed to by pbInData.


 * PBYTE pbInData : Pointer to a DRIVERCAPS structure specifying the driver capability to query, storage is already allocated for pValueList, pCurrentValue and pDefaultValue.


 * PLONG plOutCount : Not used.


 * PBYTE pbOutData : Not used.

when ulCapsType = CAPSTYPE_BOOLEAN then driver does not have to fill pValueList.

3) DEVESC_SETDRIVERCAPSVALUE: This will set the value that user has selected. The new value is specified in pCurrentValue.


 * LONG lInCount : Number of bytes pointed to by pbInData.


 * PBYTE pbInData : Pointer to a DRIVERCAPS structure specifying the driver capability to set.


 * PLONG plOutCount : Not used.


 * PBYTE pbOutData : Not used.

When the Video Configuration Manager presents the interface to the user, each capability will be presented in one window page of the capabilities notebook in System Object. The window layout will depend on the capability type.

Boolean type will be presented by a check box, aggregate type will be presented by a listbox. The capability description will appear as the title for that control.

If the driver is going to support these capabilities in multiple languages, then it must get the capability description (szCapsDesc) and capability aggreate strings (if applicable) from a resource module.

Driver developer needs to create help file for the new capability the driver supports.

HOW TO UPDATE WINDOWS INI FILE FROM AN OS/2 DLL
Note: this code can execute on Ring3 only! /// /// sample code to update the Windows INI files ///

typedef ULONG APIENTRY WPF1(VOID); typedef WPF1 *PWPF1; typedef BOOL APIENTRY WPF2(ULONG, BOOL); typedef WPF2 *PWPF2; typedef BOOL APIENTRY WPF3(ULONG, PSZ); typedef WPF3 *PWPF3;

BOOL UpdateWindowsIniFiles(VOID) { BOOL   result = TRUE; BOOL   res1; ULONG  hWpf; CHAR   szUpdateString[256]; PWPF1  pWpfOpenProfileList; PWPF2  pWpfCloseProfileList; PWPF3  pWpfWriteProfileListLine; HMODULE hMod;

if (DosLoadModule(NULL,0,"WINPRF", &hMod) ||   DosQueryProcAddr(hMod,0,"WPFOPENPROFILELIST", (PFN *)&pWpfOpenProfileList) ||   DosQueryProcAddr(hMod,0,"WPFCLOSEPROFILELIST", (PFN *)&pWpfCloseProfileList) ||   DosQueryProcAddr(hMod,0,"WPFWRITEPROFILELISTLINE", (PFN *)&pWpfWriteProfileListLine)) {   return FALSE; }

// Open the profile handler. if (hWpf = (*pWpfOpenProfileList)) {

/* ** szUpdateString has the following format ** **      [value] ** ** ex.  "system.ini boot sdisplay.drv wd3116sl.drv"  will insert the line **   sdisplay.drv=wd3116sl.drv in the boot section of system.ini ** ** if [value] is omitted, the is deleted from the section */

if (!(*pWpfWriteProfileListLine)(hWpf, szUpdateString)) {      result = FALSE;          // Win Ini update failed! }

res1 = (*pWpfCloseProfileList)(hWpf, result); // Close or abort the updates result &= res1; } else {   result = FALSE; }

return result; }