NAME
vgadb – VGA controller and monitor database

DESCRIPTION

The VGA database, /lib/vgadb, consists of two parts, the first describing how to identify and program a VGA controller and the second describing the timing parameters for known monitors to be loaded into a VGA controller to give a particular resolution and refresh rate. Conventionally, at system boot, the program aux/vga (see vga(8)) uses the monitor type in /env/monitor, the display resolution in /env/vgasize, and the VGA controller information in the database to find a matching monitor entry and initialize the VGA controller accordingly.

The file comprises multi–line entries made up of attribute/value pairs of the form attr=value or sometimes just attr. Each line starting without white space starts a new entry. Lines starting with # are comments.

The first part of the database, the VGA controller identification and programming information, consists of a number of entries with attribute ctlr and no value. Within one of these entries the following attributes are meaningful:
nnnnn      an offset into the VGA BIOS area. The value is a string expected to be found there that will identify the controller. For example, 0xC0068="#9GXE64 Pro" would identify a #9GXEpro VGA controller if the string #9GXE64 Pro was found in the BIOS at address 0xC0068. There may be more than one
identifier attribute per controller. If a match cannot be found, the first few bytes of the BIOS are printed to help identify the card and create a controller entry.
nnnnn–mmmmm
A range of the VGA BIOS area. The value is a string as above, but the entire range is searched for that string. The string must begin at or after nnnnn and not contain any characters at or after mmmmm. For example, 0xC0000–0xC0200="MACH64LP" identifies a Mach 64 controller with the string MACH64LP occurring anywhere in the first 512 bytes of BIOS memory.
ctlr      VGA controller chip type. This must match one of the VGA controller types known to /dev/vgactl (see vga(3)) and internally to aux/vga. Currently, ark2000pv, clgd542x, ct65540, ct65545, cyber938x, et4000, hiqvideo, ibm8514, mach32, mach64, mach64xx, mga2164w,
neomagic, s3801, s3805, s3928, t2r4, trio64, virge, vision864, vision964, vision968, and w30c516 are recognized.
ramdac    RAMDAC controller type. This must match one of the types known internally to aux/vga. Currently att20c490, att20c491, att20c492, att21c498, bt485, rgb524mn, sc15025, stg1702, tvp3020, tvp3025, and tvp3026 are recognized.
clock     clock generator type. This must match one of the types known internally to aux/vga. Currently ch9294, icd2061a, ics2494, ics2494a, s3clock, tvp3025clock, and tvp3026clock are recognized.
hwgc      hardware graphics cursor type. This must match one of the types known to /dev/vgactl and internally to aux/vga. Currently ark200pvhwgc, bt485hwgc, clgd542xhwgc, clgd546xhwgc, ct65545hwgc, cyber938xhwgc, hiqvideohwgc, mach64xxhwgc, mga2164whwgc,
neomagichwgc, rgb524hwgc, s3hwgc, t2r4hwgc, tvp3020hwgc, and tvp3026hwgc are recognized.
membw     Memory bandwidth in megabytes per second. Vga chooses the highest refresh rate possible within the constraints of the monitor (explained below) and the card's memory bandwidth.
linear    Whether the card supports a large (>64kb) linear memory window. The value is either 1 or 0 (equivalent to unspecified). The current kernel graphics subsystem requires a linear window; entries without linear=1 are of historic value only.
link      This must match one of the types known internally to aux/vga. Currently vga and ibm8514 are recognized. The type vga handles generic VGA functions and should almost always be included. The type Ibm8514 handles basic graphics accelerator initialization on controllers such as the early S3
family of GUI chips.

The clock, ctlr, link, and ramdac values can all take an extension following a '–' that can be used as a speed–grade or subtype; matching is done without the extension. For example, ramdac=stg1702–135 indicates the STG1702 RAMDAC has a maximum clock frequency of 135MHz, and clock=ics2494a–324 indicates that the frequency table numbered 324 should be used for the ICS2494A clock generator.

The functions internal to aux/vga corresponding to the clock, ctlr, link, and ramdac values will be called in the order given for initialization. Sometimes the clock should be set before the RAMDAC is initialized, for example, depending on the components used. In general, link=vga will always be first and, if appropriate, link=ibm8514 will be last.

The entries in the second part of /lib/vgadb have as attribute the name of a monitor type and the value is conventionally a resolution in the form XxY, where X and Y are numbers representing width and height in pixels. The monitor type (i.e. entry) include has special properties, described below and shown in the examples. The remainder of the entry contains timing information for the desired resolution. Within one of these entries the following attributes are meaningful:
clock       the video dot–clock frequency in MHz required for this resolution. The value 25.175 is known internally to vga(8) as the baseline VGA clock rate. defaultclock the default video dot–clock frequency in MHz used for this resolution when no memory bandwidth is specified for the card or when vga
cannot determine the maximum clock frequency of the card.
shb         start horizontal blanking, in character clocks.
ehb         end horizontal blanking, in character clocks.
ht          horizontal total, in character clocks.
vrs         vertical refresh start, in character clocks.
vre         vertical refresh end, in character clocks.
vt          vertical total, in character clocks.
hsync       horizontal sync polarity. Value must be + or –.
vsync       vertical sync polarity. Value must be + or –.
interlace   interlaced mode. Only value v is recognized.
alias       continue, replacing the alias line by the contents of the entry whose attribute is given as value.
include     continue, replacing this include line by the contents of the previously defined include monitor type with matching value. (See the examples.) Any non–zero attributes already set will not be overwritten. This is used to save duplication of timing information. Note that value is not parsed, it is only
used as a string to identify the previous include=value monitor type entry.

The values given for shb, ehb, ht, vrs, vre, vt, hsync, and vsync are beyond the scope of this manual page. See the book by Ferraro for details.

EXAMPLES
Basic ctlr entry for a laptop with a Chips and Technology 65550 controller:
ctlr                        # NEC Versa 6030X/6200MX
0xC0090="CHIPS 65550 PCI & VL Accelerated VGA BIOS"
link=vga
ctlr=hiqvideo linear=1
hwgc=hiqvideohwgc
A more complex entry. Note the extensions on the clock, ctlr, and ramdac attributes. The order here is important: the RAMDAC clock input must be initialized before the RAMDAC itself. The clock frequency is selected by the ET4000 chip.
ctlr                          # Hercules Dynamite Power
0xC0076="Tseng Laboratories, Inc. 03/04/94 V8.00N"
link=vga
clock=ics2494a–324
ctlr=et4000–w32p
ramdac=stg1702–135
Monitor entry for type vga (the default monitor type used by vga(8)) and resolution 640x480x[18].
include = 640x480@60Hz                   # 60Hz, 31.5KHz
clock=25.175
shb=664 ehb=760 ht=800
vrs=491 vre=493 vt=525
vga = 640x480                      # 60Hz, 31.5KHz
include=640x480@60Hz
Entries for multisync monitors with video bandwidth up to 65MHz.
#
# Multisync monitors with video bandwidth up to 65MHz.
#
multisync65 = 1024x768          # 60Hz, 48.4KHz
include=1024x768@60Hz
multisync65 = 1024x768i         # 87Hz, 35.5KHz (interlaced)
include=1024x768i@87Hz
multisync65
alias=vga
Note how this builds on the existing vga entries.

FILES
/lib/vgadb

SEE ALSO
ndb(2), vga(3), ndb(6), vga(8)
Richard E. Ferraro, Programming Guide to the EGA, VGA and Super VGA Cards, Third Edition

BUGS
The database should provide a way to use the PCI bus as well as BIOS memory to identify cards.

ADDING A NEW MONITOR
Adding a new monitor is usually fairly straightforward, as most modern monitors are multisync and the only interesting parameter is the maximum video bandwidth. Once the timing parameters are worked out for a particular maximum video bandwidth as in the example above, an entry for a new monitor with that limit is simply
#
# Sony CPD–1304
# Horizontal timing:
#      Allowable frequency range: 28–50KHz
# Vertical timing:
#      Allowable frequency range: 50–87Hz
#
cpd–1304
alias=multisync65
Even this is not necessary, as the monitor type could simply be given as multisync65.

ADDING A NEW VGA CONTROLLER
While the use of this database formalizes the steps needed to program a VGA controller, unless you are lucky and all the important components on a new VGA controller card are interconnected in the same way as an existing entry, adding a new entry requires adding new internal types to vga(8). Fortunately, the unit of variety has, for the most part, shifted from individual components to entire video chipsets. Thus in lucky cases all that is necessary is the addition of another 0xNNNNN= line to the entry for the controller. This is particularly true in the case of the ATI Mach 64 and the S3 Virge.

If you need to actually add support for a controller with a different chipset, you will need the data sheets for the VGA controller as well as any RAMDAC or clock generator (these are commonly integrated into the controller). You will also need to know how these components interact. For example, a common combination is an S3 86C928 VGA chip with an ICD2061A clock generator. The ICD2061A is usually loaded by clocking a serial bit–stream out of one of the 86C928 registers. Similarly, the RAMDAC may have an internal clock–doubler and/or pixel–multiplexing modes, in which case both the clock generator and VGA chip must be programmed accordingly. Hardware acceleration for rectangle fills and block copies is provided in the kernel; writing code to handle this is necessary to achieve reasonable performance at high pixel depths.