I have recently explored (again) the possibility of writing a high-res display driver for virtualized OS/2. But I ran (again) into a dizzying array of possible solutions, each with its own advantages and a good deal of drawbacks.
OS/2 display drivers underwent something of a rapid evolution in the 1992-1996 timeframe. The OS/2 Warp 4 DDK comes with no fewer than four significantly different display driver code bases, which reflect this evolution.
Warning: This article is long! It contains notes from research into the evolution of OS/2 display drivers, DDK sample code, and accompanying documentation. Much of the article is something of a signpost, showing where to find what.
OS/2 1.x
In the days of OS/2 1.x, things were simple. Display drivers were 16-bit, written in assembler (out of necessity more than anything else), and there was only one driver model. The drivers for OS/2 Presentation manager (PM, code name Winthorn) were circa 1987 cloned from Windows 2.x display drivers, since the inner workings (bitmaps, patterns, brushes, fonts, ROPs, and all that jazz) were very similar. Like Windows drivers, OS/2 display drivers worked by “compiling” (dynamically constructing) code to implement various drawing functions.
OS/2 1.1 (1988) supported device driver interface (DDI) version 1.0, being the first Presentation Manager release. The interface resembled Windows 2.x and was just as ugly.
In OS/2 1.x, the Presentation Manager shell (PMSHELL.EXE) directly linked against the display driver, which had to be named DISPLAY.DLL–much like in Windows 3.x and earlier the display driver had to be called DISPLAY.DRV.
The 1989 release of OS/2 1.2 looked much easier on the eyes than 1.1 and visually resembled the not-yet-released Windows 3.0. The DDI was upgraded to version 1.2. The newer DDI supported color icons and cursors (OS/2 1.1 was limited to monochrome icons), and the driver needed to supply lots more icon and bitmap resources. However, the driver model was essentially unchanged and the driver code was correspondingly largely identical.
The Presentation Driver (this encompasses both display and printer drivers) documentation from the OS/2 1.x era is available, with some overlap between Microsoft and IBM documentation. Sadly, neither Microsoft nor IBM bothered documenting the display driver interface changes between OS/2 1.1 and 1.2. If one has the source code to an OS/2 1.1 display driver, it will not work well on OS/2 1.2 or 1.3, but finding out what exactly needs to be changed is… challenging.
Microsoft published a DDK with display driver sample code for OS/2 1.1. However, it is unclear if such a DDK existed for OS/2 1.2 or 1.3; if it did (which seems likely), it hasn’t been found. Since IBM only supported IBM hardware at the time, there was no need for IBM to provide a driver development kit; supporting OEMs was Microsoft’s job back then.
OS/2 2.0
The initial release of OS/2 2.0 was in some ways an odd duck, a not-quite-finished hybrid. The Graphics Engine (GRE) was still 16-bit, and display drivers were too. Although they were architecturally unchanged from OS/2 1.x drivers, the OS/2 2.0 display drivers had a number of additions and modifications.
This primarily included support for VDDs (Virtual Device Drivers) needed to support DOS sessions, especially full-screen and background ones (windowed DOS boxes were standard applications from the PM display driver’s perspective).
There were also other changes; for example, in OS/2 1.x the display driver was responsible for managing a code segment for dynamically generated code, and its corresponding read-write alias. In OS/2 2.0, the PMDD.SYS driver took over much of the work and could allocate a “magic” segment with the right attributes.
The OS/2 2.0 Presentation Driver reference from March 1992 describes 32-bit display drivers, but it also comes with a rather interesting disclaimer saying that it is “for planning purposes only”:
As far as I’ve been able to establish, there was no actual support for 32-bit display drivers in OS/2 2.0. Out of the box support was provided for IBM adapters such as EGA, VGA, and 8514/A, but also XGA; all these drivers were 16-bit, effectively upgraded OS/2 1.3 drivers.
OS/2 2.00.1 and Service Pak XR06055
Just a few months after the April 1992 release of OS/2 2.0, circa in August/September 1992, IBM shipped Service Pak XR06055 and started preloading OS/2 2.00.1 on some systems. These updates versions came with a new 32-bit Graphics Engine (GRE), something that IBM clearly wasn’t able to get done in time for OS/2 2.0.
The 32-bit GRE continued to support existing 16-bit drivers, but naturally also worked with new 32-bit drivers. The updated GRE also implemented a few additions that had nothing to do with the 32-bit rewrite.
For 256-color drivers, the new GRE supported the Palette Manager. This gave applications more control over the hardware color palette. Additionally, OS/2 drivers now could support seamless Win-OS/2 operation. To implement seamless Win-OS/2 (that is, Windows 3.x applications running on the OS/2 desktop), IBM chose to use slightly modified Windows drivers running in the Win-OS/2 session. Which meant that a Windows driver and an OS/2 driver had to draw on the screen at more or less the same time, cooperating with each other. While this approach was perhaps technically questionable, it did work, but required a bit of extra work on the OS/2 driver side.
To support the 32-bit GRE, IBM wrote with not just one but two new drivers, or rather driver sets.
One was IBMVGA32. This was a driver supporting VGA and SVGA-style hardware, written entirely in 32-bit assembler. The driver was split into two parts: Hardware independent (IBMVGA32) and hardware dependent. IBM supplied two hardware dependent implementations: IBMDEV32 supporting 16-color VGA, and SVGA256 supporting a number of SVGA chips running in 256 colors.
The SVGA256 driver was shipped in three variants for different resolutions (all in 256 colors): 640×480 (SV480256.DLL), 800×600 (SV600256.DLL), and 1024×768 (SV768256.DLL).
The 256-color driver supported several then-common SVGA chips from ATI, Video 7, WD, IBM (“Speedway”), Tseng, Trident, and Cirrus Logic.
The other 32-bit driver was a merged XGA and 8514/A driver. This driver was written in a mix of C and assembler. IBM soon adapted the 8514/A driver to support S3 chips, which were themselves 8514/A derivatives (but not strictly compatible with the 8514/A). This driver became the basis for many OEM accelerated drivers.
Device Driver Kit
Around May 1993, IBM published the first iteration (version 1.0) of the OS/2 2.x DDK. This included sample code for the above described 32-bit drivers, as well as the older 16-bit VGA and 8514/A drivers that evolved from the original OS/2 1.1 drivers.
The DDK CD-ROM came with on-line documentation in the OS/2 INF format. This included the same Presentation Drivers Reference (S10G6267.INF) labeled First Edition (March 1992), presumably publication S10G-6267-00.
But there was also a new document titled Display Device Support for OS/2 (S71G1896.INF), which was labeled as Second Edition (March 1993), likely publication S71G-1896-00. This document described the sample code shipped on the DDK and explained how to adapt it for OEM hardware. It is not clear if and how the first edition of the document was published. It was possibly part the pre-release presentation driver development program.
In February 1994, IBM published the OS/2 DDK version 1.2 (there was also a version 1.1, but its whereabouts are unknown). This included a renamed Presentation Driver Reference (now PDRREF.INF), unfortunately with no information as to which edition it is. In any case it is an updated version, slightly reorganized and with a new chapter about Software Motion Video Support in display drivers.
The Display Device Driver Reference (now DISPLAY.INF) is not obviously different but unfortunately also contains no edition information.
To make matters more interesting, IBM also published the driver documentation in BookManager format. Some editions were preserved on IBM Softcopy Library CD-ROMs.
The December 1994 OS/2 Library includes the OS/2 2.1 Presentation Driver Reference book (EJ5A8A01.BOO), document number S10G-6267-01. This is labeled Third Edition (March 1994). There is also the corresponding OS/2 2.1 Display Driver Reference (EJ5A5A00.BOO), document number S71G-1896-01, labeled Second Edition (March 1994).
OS/2 Warp 3
In OS/2 Warp (1994), IBM did what they (and Microsoft) arguably should have done from the very beginning: The Graphics Engine now supported SOFTDRAW (capitalized in IBM documentation), a software rasterizer.
Previously, every display driver had to implement code to draw lines, rectangles, text, or perform bit blits. This code was used not only for screen output but also for drawing to memory bitmaps, completely unrelated to hardware. Perhaps Microsoft did this to make the interface more abstract and give drivers more control… but that was the opposite of what users wanted. Consistent behavior across devices was what users actually desired.
Here’s how IBM put it in the Warp DDK documentation: All presentation display drivers have two major but only marginally related functions: drawing to the display, and drawing to memory bit maps. This dual-mode drawing architecture was resolved by having the bit-map drawing code emulate the XGA hardware. Note that XGA was about the only graphics chip which was capable of drawing to the screen and to system memory bitmaps.
It is notable that printer drivers also needed to implement all the drawing functions, with the caveat that since the beginning, printer drivers had the option to call into the display driver to do the hard work. Which of course could cause “interesting” interactions with particular combinations of printer and display drivers.
IBM’s SOFTDRAW allowed drivers to let OS/2 handle all the complexity of drawing to memory bitmaps. For hardware that provided a linear framebuffer, SOFTDRAW could draw on the screen as well–since the screen was just another bitmap.
The overall structure of a display driver was still the same as before, but SOFTDRAW greatly reduced the difficulty of implementing a display driver. SOFTDRAW made it much easier to accelerate certain operations and fall back on the software rasterizer for anything complex.
For example, a driver might decide to not deal with text output and just let the GRE turn text into bitmaps. But the driver could then still use accelerated bit blits when SOFTDRAW went on to draw the bitmap on the screen.
Warp DDK
In April 1995, IBM published the OS/2 DDK version 2.0. The Presentation Device Driver Reference for OS/2 (PDRREF.INF) now called itself Fifth Edition (April 1995) and includes a summary of changes since the Fourth Edition (March 1994).
The same DDK also includes an updated Display Driver Reference for OS/2 (DISPLAY.INF) which calls itself Fourth Edition (April 1995) and includes a summary of changes since the Third Edition (March 1995)—published only one month earlier.
The Fourth Edition adds primarily information about DCAF (Distributed Console Access Facility, IBM’s remote desktop implementation) support. The missing Third Edition added much information about the S3 accelerated display driver.
Just to make things confusing, the June 1995 edition of the IBM OS/2 Softcopy Library includes Presentation Device Driver Reference for OS/2, Volume I (EJ5A8A02.BOO), document number S10G-6267-02. This document calls itself Fourth Edition (June 1995), but includes a summary of changes since Fourth Edition (March 1994). Based on the contents, this is what the PDRREF.INF from 2.0 DDK refers to as Third Edition (March 1995). The document number (S10G-6267-02) would also imply third edition (the last two digits being -00, -01, and -02 for the first, second, and third editions, respectively).
I have no idea what to believe. In any case, the BookManager document (and likely the printed hardcopy) was split into two volumes, with Presentation Device Driver Reference for OS/2, Volume II (EJ5G1A00.BOO) being document number S30H-2367-00.
The same June 1995 Softcopy Library also comes with Display Driver Reference for OS/2 (EJ5A5A01.BOO), document number S71G-1896-02. This book calls itself Fourth Edition (June 1995), and includes a summary of changes since Second Edition (March 1994). Again, based on the DISPLAY.INF in the 2.0 DDK, this should really be the Third Edition (March 1995). Which, again, would match the -02 document number.
Clearly, IBM’s documentation versioning was a bit of a mess.
OS/2 for the PowerPC
When IBM started porting OS/2 to the ill-fated PowerPC, none of the existing drivers were a good fit due to high complexity and significant to complete dependence on x86 assembler.
IBM decided to develop a new, simplified, and far more modern driver model. The new model was called GRADD (Graphics Adapter Device Driver). The actual device-specific driver was quite simple and all the complexity of GRE driver implementation was centralized in an IBM-provided SOFTDRAW library (described above).
The GRADD model was quite different and even simpler than SOFTDRAW-based drivers. In the classic presentation driver model, display drivers had to implement a large number of mandatory functions. SOFTDRAW allowed drivers to point to an implementation inside SOFTDRAW rather than in the driver proper, but the functions still needed to be implemented.
GRADD drivers worked the other way around and a basic driver did almost nothing except provide a dumb framebuffer and indirectly let SOFTDRAW do all the work. An accelerated driver could hook out certain operations that hardware could do much faster than software, such as screen-to-screen copies, hardware cursors, or bit blits with color conversion. Anything the driver didn’t explicitly ask to handle was done by SOFTDRAW.
A big plus of GRADD was that IBM provided a generic Win-OS/2 driver, which meant that OEMs were no longer required to ship their own Win-OS/2 driver at all.
Warp 4
On the Intel platform, the GRADD driver model was shipped in OS/2 Warp 4 (1996), and also eventually backported to Warp 3 in FixPacks. The initial GRADD support in Warp 4 was somewhat buggy, but stabilized over time.
Since about 1999, more or less all new OS/2 drivers used the GRADD model. This simplified everyone’s life because there was only one set of bugs to deal with (in SOFTDRAW), rather than different drivers from different vendors all having their own idiosyncrasies and quirks.
Warp 4 DDK
IBM finalized the OS/2 Warp 4 DDK in September 1996. The DDK now included sample GRADD drivers (which were mentioned in the Warp 3 DDK but no sample code was provided).
The Warp 4 DDK shipped with four significantly different sample display drivers:
- The old 16-bit VGA assembler driver for 16-color VGA and 8514/A
- 32-bit assembler driver for 16-color VGA and 256-color SVGA
- 32-bit C/assembly driver for XGA, 8514/A, and S3 accelerators
- 32-bit C generic and S3 accelerated GRADD drivers
To give a sense of the complexity of the drivers, the 16-bit VGA driver was over 5 MB of assembler code, heavily macro-ized. The 32-bit VGA driver was over 6 MB of assembler, again using lots of macros. The 32-bit accelerated driver was about 1.5 MB of assembler and 3.6 MB of C code.
In contrast, the accelerated S3 GRADD driver was a little over 200 KB of C code, and the generic unaccelerated GRRADD driver was only 30 KB of C code!
An updated edition of the Presentation Device Driver Reference for OS/2 (PDRREF.INF) was included in the DDK. There is no longer any clear edition information, only a note that certain “updates were made for Version 4 of the DDK”.
The Display Driver Reference for OS/2 (DISPLAY.INF) says that “there were no major changes to this release”. However, there is a new Graphics Adapter Device Driver Reference (GRADD.INF) book which describes the GRADD model on the OS/2 Intel platform. This reflects the fact that IBM effectively switched to GRADD for new development.
Post-Warp 4 DDKs
IBM kept releasing online updates to the OS/2 DDK until 2004. However, there were no longer any formal versioned releases and individual components were updated on an ad-hoc basis. It appears that DISPLAY.INF was no longer updated after the Warp 4 DDK release. However, PDRREF.INF was last updated in 1997 and GRADD.INF in 1999. The GRADD sample code kept being updated until 2003, and similarly the SVGA base support was maintained to keep up with hardware supported by IBM.
Which Way To Go
For supporting OS/2 1.x or 2.0, there’s no real choice. The original 16-bit driver model is the only game in town. Unfortunately, there is no SVGA sample code available, for any bit depth.
Although that isn’t entirely true–the OS/2 1.1 DDK includes a 16-color driver for certain Video 7 (Microsoft’s favorite at the time) models running at 800×600 resolution. Unfortunately the driver can’t be easily modified to support higher resolutions because it doesn’t do any bank switching. That is also the reason why Windows 3.1 and Windows NT came with generic 800x600x16 display drivers—although there is no standard VGA 800×600 mode, once the mode is set (using INT 10h mode 6Ah), drawing can be accomplished using only standard VGA registers.
For OS/2 2.1 (really OS/2 2.00.1 or OS/2 with Service Pak XR06055 and later), there is the option of using a 32-bit display driver. The DDK offers sample code for a 256-color SVGA driver which is not difficult to adapt for other graphics hardware. While this driver should be also reasonably easy to adapt to resolutions higher than 1024×768, it is much harder to support color depths other than 8-bits.
IBM’s OS/2 Warp DDK documentation recommends taking the S3 driver as a basis for developing new drivers. The S3 driver was derived from the 32-bit XGA and 8514/A drivers shipped with OS/2 2.1 (as noted earlier, the original S3 hardware, while not fully compatible with the 8514/A, was architecturally very similar). A major advantage of the S3 driver over the 32-bit SVGA driver is that the S3 driver handles multiple resolutions and multiple color depths in a single binary (whereas the SVGA driver needs a different DLL for each resolution and only supports 256 colors).
The evolution of the S3 driver is documented in the OS/2 Display Device Driver Reference, and further insight can be gleaned from the source code. The driver was originally written for the IBM XGA, in a mix of C and assembler, for OS/2 1.x. The code was then converted to 32-bit for OS/2 2.0. The driver was subsequently cloned and adapted to support the 8514/A (IBM already had an older 16-bit 8514/A driver); to a significant extent, the 8514/A hardware acceleration is a subset of the XGA capabilities. The hardware access code in the driver was split out, which made it easier to deal with the XGA and 8514/A differences. In turn, this rework made it easier to support the S3 accelerators, and the driver was further adapted to ease porting to different hardware dissimilar from the 8514/A or XGA. The S3 driver was also enhanced to support 24bpp modes (the XGA only supported 8 and 16 bpp).
On closer look, the DDK sample code for the XGA / 8514/A / S3 seems to have been designed for maximum confusion. In the 1993 (version 1.0) DDK, there were two drivers, XGA32 and XGA8514. Most likely the XGA32 driver was cloned to XGA8514 and adapted for the 8514/A. In the 1994 (version 1.2) DDK, the XGA and 8514/A drivers were merged again, and support for S3 accelerators was added. The merged driver was under DDK\SRC\PMVIDEO\32BIT and additionally supported 24bpp video modes.
The 1995 OS/2 Warp DDK (version 2.0) added a DDK\SRC\PMVIDEO\S3TIGER sample driver, which was largely identical to the merged ’32BIT’ driver. The difference was that the S3TIGER driver supported EnDIVE, IBM’s software video offloading framework. This framework (circa 1995) did not support any true video decoding, but it did support color conversion and stretching, a feature available in the better graphics chips at the time (such as the S3 Vision 868 and 968).
Developers could be misled into thinking that the S3TIGER driver was the right one to use as a basis for porting. But no! Although IBM kept shipping the S3TIGER sample driver, it was not maintained. On the other hand, the 32BIT driver kept getting minor fixes and sometime in 1998 or 1999, also had support for 32bpp modes added. While 32bpp modes did not visually look any different from 24bpp, and needed more video memory, most graphics chips did not support accelerated 24bpp drawing—while 32bpp acceleration became standard.
IBM also merged DBCS support into the 32BIT driver in late 1999 or early 2000. This coincided with Warp Server for e-Business which was capable of supporting both SBCS and DBCS environments, unlike older OS/2 versions which required separate, modified DBCS drivers.
It is clear that the ’32BIT’ driver and not ‘S3TIGER’ sample driver was the right basis for porting, a fact that is not at all clear from IBM’s documentation.
For Warp 4 and later, GRADD drivers are by far the easiest to develop, and completely avoid any hassle with Win-OS/2 drivers. At the same time, the GENGRADD driver which ships with OS/2 usually offers reasonable resolutions and color depths, and performs well in emulated environments; therefore the need to create a new GRADD driver is quite limited.
Matrox Mystery
While going through the combined XGA / 8514/A / S3 driver source code, curious Matrox references popped up (along with a strange WOLVES.H header file). When the macro ‘MATROX’ is defined at compile time, the XGA driver adds several strategically placed tests where it checks whether it is RunningOnMatrox(). This is done by checking whether the current (MCA) adapter ID equals 80EEh.
The Matrox support is even mentioned in the OS/2 Display Device Driver Reference manual and used as an example of implementing certain techniques.
The sample XGA driver has included the Matrox code since the first OS/2 2.x DDK in 1993, and it survived until the last DDK update in 2004. The only problem? The Matrox-specific code is never built, because the ‘MATROX’ macro is never defined and the MATROX.C support module is never compiled. It is also incomplete.
The adapter in question is (based on the 80EEh ID) a rather obscure Matrox Illuminator-16/MC. The card clearly supported 16bpp modes, using a pixel format different from the XGA. I could not find out if the Illuminator-16 has accelerated drawing. In any case, the Matrox-enabled XGA driver does not use it—it appears to use purely software drawing.
I could not find any actual IBM XGA OS/2 driver that would include this Matrox support. But the Illuminator-16 was reportedly supported under OS/2 and used for video production. Whether Matrox shipped the modified IBM XGA driver or something altogether different, or if the combined XGA/Matrox driver was ever shipped at all, is entirely unknown.
Summary
For supporting OS/2 2.00.1 and later, the 32-bit merged S3 driver should be by far the best starting point for developing a Presentation Manager display driver. It is a full-featured driver written largely in C and meant to be relatively easily adaptable to different graphics hardware.
For any earlier OS/2 versions (including OS/2 2.0 GA), display drivers must be 16-bit. The only available samples are written entirely in assembler and do not support SVGAs, which would necessitate major surgery.