VGADB(6)                                                 VGADB(6)

     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 con-
          troller 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 moni-
          tor 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 identifi-
          cation 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 iden-
                   tify 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 iden-
                   tifier 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 con-
                   troller 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,

     Page 1                       Plan 9             (printed 3/28/24)

     VGADB(6)                                                 VGADB(6)

                   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 recog-
                   nized.
          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 (equiva-
                   lent 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 recog-
                   nized.  The type vga handles generic VGA functions
                   and should almost always be included.  The type
                   Ibm8514 handles basic graphics accelerator initial-
                   ization 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.

     Page 2                       Plan 9             (printed 3/28/24)

     VGADB(6)                                                 VGADB(6)

          The entries in the second part of /lib/vgadb have as
          attribute the name of a monitor type and the value is con-
          ventionally a resolution in the form XxY, where X and Y are
          numbers representing width and height in pixels.  The moni-
          tor 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 reso-
          lution.  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 fre-
                     quency 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 con-
                     tents of the entry whose attribute is given as
                     value.
          include    continue, replacing this include line by the con-
                     tents 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,

     Page 3                       Plan 9             (printed 3/28/24)

     VGADB(6)                                                 VGADB(6)

          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), 9load(8), 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 moni-
          tor with that limit is simply
          #
          # Sony CPD-1304

     Page 4                       Plan 9             (printed 3/28/24)

     VGADB(6)                                                 VGADB(6)

          # 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.

     Page 5                       Plan 9             (printed 3/28/24)