Video Drivers Development

Source:

aux/vga: /sys/src/cmd/aux/vga/*
kernel drivers: /sys/src/9/pc/vga*

See also:

• /sys/src/cmd/aux/vga/notes.txt
• /n/sources/contrib/vga/notes (more recent but obsolete?)

Extracted from the 9fans archives: http://lists.cse.psu.edu/archives/9fans/2002-February/015741.html

The following is a sort of theory of operation for aux/vga and the kernel vga drivers.

--- aux/vga and basic kernel drivers

Aux/vga consists of a number of modules each of which conforms to an interface called a Ctlr. The Ctlr provides functions snarf, options, init, load, and dump, which are explained in more detail below. Video cards are internally represented as just a collection of Ctlrs. When we want to run one of the functions (snarf, etc.) on the whole card, we run it on each Ctlr piece in turn.

In the beginning of aux/vga, it was common for video cards to mix and match different VGA controller chips, RAMDACs, clock generators, and sometimes even hardware cursors. The original use for vgadb was to provide a recipe for how to deal with each card. The ordering in the ctlr sections was followed during initialization, so that if you said ctlr 0xC0076="Tseng Laboratories, Inc. 03/04/94 V8.00N" link=vga clock=ics2494a-324 ctlr=et4000-w32p ramdac=stg1602-135 when aux/vga wanted to run, say, snarf on this card it would call the snarf routines for the vga, ics2494a, et4000, and stg1602 Ctlrs, in that order. The special Ctlrs vga and ibm8514 take care of the generic VGA register set and the extensions to that register set introduced by the IBM 8514 chip. Pretty much all graphics cards these days still use the VGA register set with some extensions. The only exceptions currently in vgadb are the Ticket to Ride IV and the Neomagic (both LCD cards). The S3 line of chips tends to have the IBM 8514 extensions.

This "mix and match" diversity has settled down a bit, with one chip now usually handling everything. As a result, vgadb entries have become a bit more formulaic, usually listing only the vga link, a controller, and a hardware cursor. For example: ctlr 0xC0039="CL-GD540" link=vga ctlr=clgd542x hwgc=clgd542xhwgc

On to the controller functions themselves. The functions mentioned earlier are supposed to do the following.

void snarf(Vga *vga, Ctlr *ctlr) Read the ctlr's registers into memory, storing them either in the vga structure (if there is an appropriate place) or into a privately allocated structure, a pointer to which can be stored in vga->private (sic). (The use of vga->private rather than ctlr->private betrays the fact that private data has only been added after we got down to having cards with basically a single controller.)

void options(Vga *vga, Ctlr *ctlr) This step prepares to edit the in-memory copy of the registers to implement the mode given in vga->mode. It's really the first half of init, and is often empty. Basically, something goes here if you need to influence one of the other init routines and can't depend on being called before it. For example, the virge Ctlr rounds the pixel line width up to a multiple of 16 in its options routine. This is necessary because the vga Ctlr uses the pixel line width. If we set it in virge.init, vga.init would already have used the wrong value.

void init(Vga *vga, Ctlr *ctlr) Edit the in-memory copy of the registers to implement the mode given in vga->mode.

void load(Vga *vga, Ctlr *ctlr) Write all the ctlr's registers, using the in-memory values. This is the function actually used to switch modes.

void dump(Vga *vga, Ctlr *ctlr) Print (to the Biobuf stdout) a description of all the in-memory controller state. This includes the in-memory copy of the registers but often includes other calculated state like the intended clock frequencies, etc.

Now we have enough framework to explain what aux/vga does. It's easiest to present it as a commented recipe.

1. We sniff around in the BIOS memory looking for a match to any of the strings given in vgadb. (In the future, we intend also to use the PCI configuration registers to identify cards.)

2. Having identified the card and thus made the list of controller structures, we snarf the registers and, if the -p flag was given, dump them.

3. If the -i or -l flag is given, aux/vga then locates the desired mode in the vgadb and copies it into the vga structure. It then does any automatic frequency calculations if they need doing. (See the discussion of defaultclock in vgadb(6).)

For a good introduction to video modes, read Eric Raymond's XFree86 Video Timings HOWTO, which, although marked as obsolete for XFree86, is still a good introduction to what's going on between the video card and the monitor. http://en.tldp.org/HOWTO/XFree86-Video-Timings-HOWTO/

4. Having copied the vgadb mode parameters into the vga structure, aux/vga calls the options and then the init routines to twiddle the in-memory registers appropriately.

5. Now we are almost ready to switch video modes. We dump the registers to stdout if we're being verbose.

6. We tell the kernel (via the "type" vga ctl message) what sort of video card to look for. Specifically, the kernel locates the named kernel vga driver and runs its enable function.

7. If we're using a frame buffer in direct-mapped linear mode (see the section below), we express this intent with a "linear"; vga ctl message. In response, the kernel calls the vga driver's linear function. This should map the video memory into the kernel's address space. Conventionally, it also creates a named memory segment for use with segattach so that user-level programs can get at the video memory. If there is a separate memory-mapped i/o space, it too is mapped and named. These segments are only used for debugging, specifically for debugging the hardware acceleration routines from user space before putting them into the kernel.

8. We tell the kernel the layout of video memory in a "size" ctl message. The arguments are the screen image resolution and the pixel channel format string.

9. Everything is set; we disable the video card, call the loads to actally set the real registers, and reenable the card.

At this point there should be a reasonable picture on the screen. It will be of random memory contents and thus could be mostly garbage, but there should be a distinct image on the screen rather than, say, funny changing patterns due to having used an incorrect sync frequency.

10. We write "drawinit" into #v/vgactl, which will initialize the screen and make console output from now on appear on the graphics screen instead of being written to the CGA text video memory (as has been happening). This calls the kernel driver's drawinit function, whose only job is to initialize hardware accelerated fills and scrolls and hardware blanking if desired.

11. We write "hwgc <hwgcname>" into #v/vgactl, which calls the enable function on the named kernel hwgc driver. (Plan 9 does not yet support software graphics cursors.)

12. We set the actual screen size with an "actualsize" ctl message. The virtual screen size (which was used in the "size" message in step 8) controls how the video memory is laid out; the actual screen size is how much fits on your monitor at a time. Virtual screen size is sometimes larger than actual screen size, either to implement panning (which is really confusing and not recommended) or to round pixel lines up to some boundary, as is done on the ViRGE and Matrox cards. The only reason the kernel needs to know the actual screen size is to make sure the mouse cursor stays on the actual screen.

13. If we're being verbose, we dump the vga state again.

--- hardware acceleration and blanking

Hardware drawing acceleration is accomplished by calling the kernel-driver-provided fill and scroll routines rather than doing the memory operations ourselves. For >8-bit pixel depths, hardware acceleration is noticeably needed. For typical Plan 9 applications, accelerating fill and scroll has been fast enough that we haven't worried about doing anything else.

The kernel driver's drawinit function should sniff the card and decide whether it can use accelerated fill and scroll functions. If so, it fills in the scr->fill and scr->scroll function pointers with functions that implement the following:

int fill(VGAscr *scr, Rectangle r, ulong val); Set every pixel in the given rectangle to val. Val is a bit pattern already formatted for the screen's pixel format (rather than being an RGBA quadruple). Do not return until the operation has completed (meaning video memory has been updated). Usually this means a busy wait looping for a bit in some status register. Although slighty inefficient, the net effect is still much faster than doing the work ourselves. It's a good idea to break out of the busy loop after a large number of iterations, so that if the driver or the card gets confused we don't lock up the system waiting for the bit. Look at any of the accelerated drivers for the conventional method.

int scroll(VGAscr *scr, Rectangle r, Rectangle sr); Set the pixels in rectangle r with the pixels in sr. r and sr are allowed to overlap, and the correct thing must be done, just like memmove. Like fill, scroll must not return until the operation has completed.

Russ Cox <rsc@plan9.bell-labs.com> has a user-level scaffold for testing fill and scroll routines before putting them into the kernel. You can mail him for them.

Finally, drawinit can set scr->blank to a hardware blanking function. On 8-bit displays we can set the colormap to all black to get a sort of blanking, but for true-color displays we need help from the hardware.

int blank(VGAscr *vga, int isblank); If isblank is set, blank the screen. Otherwise, restore it. Implementing this function on CRT-based cards is known to mess up the registers coming out of the blank. We've had better luck with LCD-based cards although still not great luck. But there it is.

--- linear mode and soft screens

In the bad old days, the entire address space was only 1MB, but video memory (640x480x1) was only 37.5kB, so everything worked out. It got its own 64kB segment and everyone was happy. When screens got deeper and then bigger, the initial solution was to use the 64kB segment as a window onto a particular part of video memory. The offset of the window was controlled by setting a register on the card. This works okay but is a royal pain, especially if you're trying to copy from one area of the screen to another and they don't fit in the same window. When we are forced to cope with cards that require accessing memory through the 64kB window, we allocate our own copy of the screen (a so-called soft screen) in normal RAM, make changes there, and then flush the changed portions of memory to video RAM through the window. To do this, we call the kernel driver-provided page routine:

int pageset(VGAscr *scr, int page); Set the base offset of the video window to point page*64kB into video memory.

With the advent of 32-bit address spaces, we can map all of video memory and avoid the soft screen. We call this running the card in linear mode, because the whole video memory is mapped linearly into our address space. Aux/vga is in charge of deciding whether to do this. (In turn, aux/vga more or less respects vgadb, which controls it by having or not having "linear=1" in the controller entry.) If not, aux/vga doesn't do anything special, and we use a soft screen. If so, aux/vga writes "linear" and an address space size into vgactl in step #7 above. In response the kernel calls the kernel driver's linear function, whose job was described in step #7.

Most drivers only implement one or the other interface: if you've got linear mode, you might as well use it and ignore the paging capabilities of the card. Paging is typically implemented only when necessary.

--- from here

If you want to write a VGA driver, it's fairly essential that you get documentation for the video chipset. In a pinch, you might be able to get by with the XFree86 driver for the chipset instead. (The NVidia driver was written this way.) Another alternative is to use documentation for a similar but earlier chipset and then tweak registers until you figure out what is different. (The SuperSavage parts of the virge driver got written this way, starting with the Savage4 parts, which in turn were written by referring to the Savage4 documentation and the Virge parts.)

Even if you do get documentation, the XFree86 driver is good to have to double check. Sometimes the documentation is incomplete, misleading, or just plain wrong, whereas the XFree86 drivers, complicated beasts though they are, are known to work most of the time.

Another useful method for making sure you understand what is going on is dumping the card's registers under another system like XFree86 or Microsoft Windows. The Plan 9 updates page contains an ANSI/POSIX port of aux/vga that is useful only for dumping registers on various systems. It has been used under Linux, FreeBSD, and Windows 95/98. It's not clear what to do on systems like Windows NT or Windows 2000 that both have reasonable memory protection and are hardware programmer-unfriendly.

If you're going to write a driver, it's much easier with a real Plan 9 network or at least with a do-everything cpu/auth/file server terminal, so that you can have an editor and compiler going on a usable machine while you continually frotz and reboot the machine with the newfangled video card. Booting this latter machine from the network rather than its own disk makes life easier for you (you don't have to explicitly copy aux/vga from the compiling machine to the testing machine) and doesn't wreak havoc on the testing machine's local kfs.

It's nice sometimes to have a command-line utility to poke at the vga registers you care about. We have one that perhaps we can clean up and make available. Otherwise, it's not hard to roll your own.

The first step in writing an aux/vga driver is to write the snarf and dump routines for the controller. Then you can run aux/vga -p and see whether the values you are getting match what you expect from the documentation you have.

A good first resolution to try to get working is 640x480x8, as it can use one of the standard clock modes rather than require excessive clock fiddling.

/sys/src/cmd/aux/vga/template.c is a template for a new vga controller driver. There is no kernel template but any of the current drivers is a decent template. /sys/src/9/pc/vga3dfx.c is the smallest one that supports linear addressing mode.