                  Configuring XFree86: A Step-By-Step Guide

                David Wexelblat and The XFree86 Project, Inc

                               5 October 1994

                                  Abstract

          This document describes how to set up your XFree86 server and
     the corresponding XF86Config configuration file.  If you follow the
     procedures in this document, you should have no problems getting
     your server up and running quickly.       This document is designed
     to be generic.  Be certain to refer to the operating system spe-
     cific README file for your OS (e.g.  README.SVR4) and the
     card/chipset specific README file for you video card (e.g.
     README.trident).  Where these specific files contradict this
     generic file, you should follow the specific instructions (there
     shouldn't be much of that, though).

1.  Procedure Overview

There are two steps to getting things up and running.  The first is to select
the appropriate server that you will be using and set it up as the default
server.  The second step is to set up the XF86Config file.  This file is used
to configure the server for your pointer device (e.g. mouse, trackball),
video card, and monitor, as well as a few other things.

The XF86Config file contains several sections; these procedures will lead you
through filling out each part.  There is a default/sample XF86Config file in
/usr/X11R6/lib/X11/XF86Config.sample; you should copy this to
/usr/X11R6/lib/X11/XF86Config, and edit that file to your specific configura-
tion.  The XF86Config(4/5) manual page describes the XF86Config file contents
and options in detail.  Be sure to read through that manual page as you fill
in your XF86Config file.

The sections of the XF86Config file are:

      Files
            Sets the default font and RGB paths.

      Server Flags
            Sets a few general server options.  Refer to the manual page to
            learn about these.

      Keyboard
            Sets up keyboard devices, and sets a few optional parameters.

      Pointer
            Sets up the pointer devices, and sets a few optional parameters.

      Monitor
            Describes your monitor(s) to the server.

      Graphics Device
            Describes your video hardware to the server.

      Screen.
            Describes how the monitor and video hardware should be used.

2.  Setting Up The Correct Default Server

The default server name is /usr/X11R6/bin/X.  This is a link to a specific
server binary XF86_xxxx, located in /usr/X11R6/bin/.  You should check which
server the X link is connected to.  If it is not correct, remove it and make
a new link to the correct binary.  The server binaries are:

      XF86_SVGA:
            Super-VGA server.  Contains accelerated support for Cirrus
            542{0,2,4,6,8,9}, 543{0,4} and Western Digital 90C3{1,3} and Oak
            Technologies Inc. OTI087 chipsets, unaccelerated for the rest of
            the supported chipsets.

      XF86_Mono:
            (S)VGA monochrome, optionally Hercules or other monochrome hard-
            ware support is linked in.

      XF86_VGA16:
            Generic VGA 16-color server.

      XF86_S3:
            S3 accelerated server.

      XF86_Mach32:
            ATI Mach32 accelerated server.

      XF86_Mach64:
            ATI Mach64 accelerated server.

      XF86_Mach8:
            ATI Mach8 accelerated server.

      XF86_8514:
            8514/A accelerated server.

      XF86_P9000:
            P9000 accelerated server.

      XF86_AGX:
            AGX accelerated server.

      XF86_W32:
            ET4000/W32 and ET6000 accelerated server.

There is a manual page for each of these servers; refer to the manual page
for specific details on supported chipsets and server-specific configuration
options.

Note that it is possible to modify the drivers configured into a server via
the LinkKit; the server binary may not contain all of the possible drivers,
depending on how the distribution was assembled.  You can run
/usr/X11R6/bin/X -showconfig to get a printout of the configured drivers.  If
you need to relink your server, refer to the README file in the LinkKit for
specific information.

3.  The Easy Parts of XF86Config

The "Files" section of the XF86Config file contains the path to the RGB
database file (which should, in general, never need to be changed), and the
default font path.  You can have multiple FontPath lines in your XF86Config;
they are concatenated.  Ensure that each directory listed exists and is a
valid font directory.  If the server complains about "Can't open default font
'fixed'", it is because there is an invalid entry in your font path.  Try
running the 'mkfontdir' command in each directory if you are certain that
each one is correct.  The XF86Config(4/5) manual page describes other parame-
ters that may be in this section of the file.

Next comes the "Keyboard" section.  In this section, you can specify the key-
board protocol (Xqueue or Normal), the repeat rate, and the default mapping
of some of the modifier keys.  In general, nothing will need to be modified
here. Users of non-English keyboards might want to change the definitions of
the modifier keys. See the XF86Config(4/5) man page for details.

After this comes the "Pointer" section.  In this section you can specify the
pointer protocol and device.  Note that the protocol name does not always
match the manufacturer's name.  For example, some Logitech mice (especially
newer ones) require either the MouseMan or Microsoft protocols, not the Log-
itech protocol.  Some other mouse parameters can be adjusted here.  If you
are using a two-button mouse, uncomment the Emulate3Buttons keyword - in this
mode, pressing both mouse buttons simultaneously causes the server to report
a middle button press.

Note that if the server complains about being unable to open your mouse
device, this is NOT a server problem.  It has been a very common misconfigu-
ration error on several of the OSs, and 99.999% of the time it is because the
device is not correctly configured in the OS.  Hence don't bug us until after
you prove that your OS level support is correct.

4.  Configuring the Video Hardware

The video hardware is described in the "Device" sections.  Multiple device
sections are permitted, and each section describes a single graphics board.

Be sure to read the server manual pages and the chipset-specific README files
for any non-generic information that may apply to your setup.

To create a Device section you need to collect the data for your hardware,
and make some configuration decisions.  The hardware data you need is:

   o Chipset

   o Amount of video memory

   o Dot-clocks available or clock chip used (if programmable)

   o Ramdac type (for some servers)

The server, in general, is capable of filling these on its own, but it is
best to fully specify things in the XF86Config file, so that no mistakes are
made.  The 'Chipset' is one of the keyword strings for a configured driver
(which can be displayed by running 'X -showconfig').  Of the accelerated
servers, only some have chipset drivers currently.  The amount of memory is
specified in KBytes, so 1M of memory would be specified as 1024.

The dot-clocks are the trickiest part of card configuration.  Fortunately a
large database of collected dot-clocks is available.  A list of Device
entries for some graphics boards can be found in the `Devices' file.  If you
find one for your card, you can start with that.  Also, the first part of the
modeDB.txt file lists information for a myriad of SVGA cards.  For acceler-
ated cards, you can also look in the `AccelCards' file.  If you are fortu-
nate, your card is listed in one place or the other.  If you find your card,
copy the numbers from the database to the Clocks line in your XF86Config
file, exactly as they appear in the database, without sorting, and leaving
any duplicates.  Note that some of the newer accelerated cards use a pro-
grammable clock generator, in which case a ClockChip line is used in your
XF86Config file to identify the type of clock generator.  (e.g. 'ClockChip
"icd2061a"', which would be used for a #9 GXe board).

If you can't find a listing for your board, you can attempt to have the
server detect them.  Run the command 'X -probeonly >/tmp/out 2>&1' (for sh or
ksh) or 'X -probeonly >&/tmp/out' (for csh). Be sure that the XF86Config file
does not contain a Clocks line at this point. Running this will cause your
monitor to freak out for a couple of seconds, as the server cycles through
the clocks rapidly.  It should not damage your monitor, but some newer moni-
tors may shut themselves off because things may go out of spec.  Anyhow, when
this gets done, look in the file /tmp/out for the detected dot-clocks.  Copy
these to the Clocks line in your XF86Config file, exactly as they appear in
/tmp/out.  Don't sort them or rearrange them in any way.

It is possible that your board has a programmable clock generator.  A symptom
of this will be a printout of only 2 or 3 clock values, with the rest all
zeros.  If you run into this, and your board is not listed in the databases,
contact the XFree86 team for help, or post a message to comp.win-
dows.x.i386unix.  Note that most current Diamond hardware falls into this
category, and Diamond will not release the programming details, so we can't
help you.  There are some ethically questionable solutions available that you
can inquire about on netnews; we do not advocate these methods, so do not
contact us about them.

Some servers (S3 and AGX) require you to identify the type and speed of the
RAMDAC your board uses in order to get the most out of the hardware.  This is
done by adding 'Ramdac' and 'DacSpeec' entries.  For details of the supported
RAMDACs, refer to the appropriate server manual page.  Note, in previous ver-
sions of XFree86 the RAMDAC type was specified with an Option flag.

You may need to specify some Option flags for your hardware The server manual
pages will describe these options, and the chipset-specific README files will
tell you if any are required for your board.

5.  Configuring the Monitor and its Modes

Configuring monitor modes can be a trying experience, unfortunately, because
of the lack of standardization in monitor hardware.  We have attempted to
simplify this by collecting databases of specific monitor information, and
assembling a set of "generic" modes that should get pretty much any monitor
up and functional.  For all the gory details of mode generation and tuning,
refer to the `VideoModes.doc' document by Eric Raymond.

The monitor specs and video modes are described in the "Monitor" sections in
the XF86Config file.  To create a Monitor section, you need to know your mon-
itor's specifications.  In particular, you need to know what range of hori-
zontal sync and vertical sync (refresh) rates it supports and what its video
bandwidth is.  This information should be available in the monitor's user
manual.  Also check the 'Monitors' file to see if it has an entry for your
monitor.  See the XF86Config(4/5) manual page for details of how this infor-
mation is entered into the Monitor section.

Next, you need to provide a set of video modes that are suitable for the mon-
itor.  The first step is to check in the 'Monitors' and modeDB.txt files to
see if there is a listing of modes for your specific monitor.  If there is,
copy those modes to the Monitor section of your XF86Config file.  Verify that
there is a clock listed on the Clocks line in your XF86Config that matches
the dot-clock in the 2nd parameter of each mode line; delete any mode line
that does not have a matching clock on your card.  If you still have modes
left, you are in good shape.

If you don't find any specific modes, or need more modes for the resolutions
you want to use, refer to the Generic Video Modes listing below.  Match the
mode specification against your monitor's specifications; pick the highest-
refresh mode that is within specs, and make sure you have a matching dot-
clock on your Clocks line.  Try the VESA modes before any corresponding
alternate mode setting.  Copy the mode specification to the Monitor section
of your XF86Config file.  Note that these modes are likely not optimal; they
may not be sized perfectly, or may not be correctly centered.  But they
should get you up and running.  If you want to tune the mode to your monitor,
you can read the 'Fixing Problems with the Image' section of the Video-
Modes.doc file.

A note before you are done.  If the same mode name occurs more than once in
the Monitor section of the XF86Config file, the server will use the first
mode with a matching clock.  It is generally considered a bad idea to have
more than one mode with the same name in your XF86Config file.

6.  Combining the Video Hardware and Monitor Data

Once you have given a description of your monitor and graphics hardware you
need to specify how they are to be used by the servers.  This is done with
the "Screen" sections in the XF86Config file.  You need to supply a Screen
section for each of the server driver types you will be using.  The driver
types are "SVGA" (XF86_SVGA), "VGA16" (XF86_VGA16), "VGA2" (XF86_Mono),
"MONO" (XF86_Mono, XF86_VGA16), and "ACCEL" (XF86_S3, XF86_Mach32,
XF86_Mach8, XF86_Mach64, XF86_8514, XF86_P9000, XF86_AGX, XF86_W32).  Each
Screen section specifies which Monitor description and Device description are
to be used.

The Screen sections include one or more "Display" subsections.  One Display
subsection may be provided for each depth that the server supports.  In the
Display subsection you can specify the size of the virtual screen the server
will use.  The virtual screen allows you to have a "root window" larger than
can be displayed on your monitor (e.g.  you can have an 800x600 display, but
a 1280x1024 virtual size).  The Virtual keyword is used to specify this size.
Note that many of the new accelerated server use non-displayed memory for
caching.  It is not desirable to use all of your memory for virtual display,
as this leaves none for caching, and this can cost as much as 30-40% of your
server performance.

The last thing you specify in Display subsection is the display modes.  These
are the physical display resolutions that the server will use.  The name is
arbitrary, but must match something in the appropriate Monitor section.  In
general, these names are the display resolution (e.g. "1024x768"), but need
not be.  You can list as many as desired; the first is the default/starting
display, and you can cycle through the list with Ctrl-Alt-Keypad+ or Ctrl-
Alt-Keypad- hotkey sequences.

That's it.  Now you're ready to test out your new XFree86 installation.

7.  Generic Video Modes

     #
     #  Mode       Refresh  Hor. Sync  Dot-clock  Interlaced?  VESA?
     #  ------------------------------------------------------------
     #  640x480     60Hz      31.5k     25.175M       No         No
     #  640x480     60Hz      31.5k     25.175M       No         No
     #  640x480     63Hz      32.8k     28.322M       No         No
     #  640x480     70Hz      36.5k     31.5M         No         No
     #  640x480     72Hz      37.9k     31.5M         No        Yes
     #  800x600     56Hz      35.1k     36.0M         No        Yes
     #  800x600     56Hz      35.4k     36.0M         No         No
     #  800x600     60Hz      37.9k     40.0M         No        Yes
     #  800x600     60Hz      37.9k     40.0M         No         No
     #  800x600     72Hz      48.0k     50.0M         No        Yes
     #  1024x768i   43.5Hz    35.5k     44.9M        Yes         No
     #  1024x768    60Hz      48.4k     65.0M         No        Yes
     #  1024x768    60Hz      48.4k     62.0M         No         No
     #  1024x768    70Hz      56.5k     75.0M         No        Yes
     #  1024x768    70Hz      56.25k    72.0M         No         No
     #  1024x768    76Hz      62.5k     85.0M         No         No
     #  1280x1024i  44Hz      51kHz     80.0M        Yes         No
     #  1280x1024i  44Hz      47.6k     75.0M        Yes         No
     #  1280x1024   59Hz      63.6k    110.0M         No         No
     #  1280x1024   61Hz      64.24k   110.0M         No         No
     #  1280x1024   74Hz      78.85k   135.0M         No         No

     #
     # 640x480@60Hz Non-Interlaced mode
     # Horizontal Sync = 31.5kHz
     # Timing: H=(0.95us, 3.81us, 1.59us), V=(0.35ms, 0.064ms, 1.02ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "640x480"     25.175  640  664  760  800    480  491  493  525

     #
     # Alternate 640x480@60Hz Non-Interlaced mode
     # Horizontal Sync = 31.5kHz
     # Timing: H=(1.27us, 3.81us, 1.27us) V=(0.32ms, 0.06ms, 1.05ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "640x480"     25.175  640  672  768  800    480  490  492  525

     #
     # 640x480@63Hz Non-Interlaced mode (non-standard)
     # Horizontal Sync = 32.8kHz
     # Timing: H=(1.41us, 1.41us, 5.08us) V=(0.24ms, 0.092ms, 0.92ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "640x480"     28.322  640  680  720  864    480  488  491  521

     #
     # 640x480@70Hz Non-Interlaced mode (non-standard)
     # Horizontal Sync = 36.5kHz
     # Timing: H=(1.27us, 1.27us, 4.57us) V=(0.22ms, 0.082ms, 0.82ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "640x480"     31.5    640  680  720  864    480  488  491  521

     #
     # VESA 640x480@72Hz Non-Interlaced mode
     # Horizontal Sync = 37.9kHz
     # Timing: H=(0.76us, 1.27us, 4.06us) V=(0.24ms, 0.079ms, 0.74ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "640x480"     31.5    640  664  704  832    480  489  492  520

     #
     # VESA 800x600@56Hz Non-Interlaced mode
     # Horizontal Sync = 35.1kHz
     # Timing: H=(0.67us, 2.00us, 3.56us) V=(0.03ms, 0.063ms, 0.70ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "800x600"     36      800  824  896 1024    600  601  603  625

     #
     # Alternate 800x600@56Hz Non-Interlaced mode
     # Horizontal Sync = 35.4kHz
     # Timing: H=(0.89us, 4.00us, 1.11us) V=(0.11ms, 0.057ms, 0.79ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "800x600"     36      800  832  976 1016    600  604  606  634

     #
     # VESA 800x600@60Hz Non-Interlaced mode
     # Horizontal Sync = 37.9kHz
     # Timing: H=(1.00us, 3.20us, 2.20us) V=(0.03ms, 0.106ms, 0.61ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "800x600"     40      800  840  968 1056    600  601  605  628 +hsync +vsync

     #
     # Alternate 800x600@60Hz Non-Interlaced mode
     # Horizontal Sync = 37.9kHz
     # Timing: H=(1.20us, 3.80us, 1.40us) V=(0.13ms, 0.053ms, 0.69ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "800x600"     40      800 848 1000 1056     600  605  607  633

     #
     # VESA 800x600@72Hz Non-Interlaced mode
     # Horizontal Sync = 48kHz
     # Timing: H=(1.12us, 2.40us, 1.28us) V=(0.77ms, 0.13ms, 0.48ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "800x600"     50      800  856  976 1040    600  637  643  666  +hsync +vsync

     #
     # 1024x768@43.5Hz, Interlaced mode (8514/A standard)
     # Horizontal Sync = 35.5kHz
     # Timing: H=(0.54us, 1.34us, 1.25us) V=(0.23ms, 0.23ms, 0.93ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1024x768i"   44.9   1024 1048 1208 1264    768  776  784  817  Interlace

     #
     # VESA 1024x768@60Hz Non-Interlaced mode
     # Horizontal Sync = 48.4kHz
     # Timing: H=(0.12us, 2.22us, 2.58us) V=(0.06ms, 0.12ms, 0.60ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1024x768"    65     1024 1032 1176 1344    768  771  777  806 -hsync -vsync

     #
     # 1024x768@60Hz Non-Interlaced mode (non-standard dot-clock)
     # Horizontal Sync = 48.4kHz
     # Timing: H=(0.65us, 2.84us, 0.65us) V=(0.12ms, 0.041ms, 0.66ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1024x768"    62     1024 1064 1240 1280   768  774  776  808

     #
     # VESA 1024x768@70Hz Non-Interlaced mode
     # Horizontal Sync=56.5kHz
     # Timing: H=(0.32us, 1.81us, 1.92us) V=(0.05ms, 0.14ms, 0.51ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1024x768"    75     1024 1048 1184 1328    768  771  777  806 -hsync -vsync

     #
     # 1024x768@70Hz Non-Interlaced mode (non-standard dot-clock)
     # Horizontal Sync=56.25kHz
     # Timing: H=(0.44us, 1.89us, 1.22us) V=(0.036ms, 0.11ms, 0.53ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1024x768"    72     1024 1056 1192 1280    768  770  776 806   -hsync -vsync

     #
     # 1024x768@76Hz Non-Interlaced mode
     # Horizontal Sync=62.5kHz
     # Timing: H=(0.09us, 1.41us, 2.45us) V=(0.09ms, 0.048ms, 0.62ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1024x768"    85     1024 1032 1152 1360    768  784  787  823

     #
     # 1280x1024@44Hz, Interlaced mode
     # Horizontal Sync=51kHz
     # Timing: H=(0.02us, 2.7us, 0.70us) V=(0.02ms, 0.24ms, 2.51ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1280x1024i"  80     1280 1296 1512 1568   1024 1025 1037 1165  Interlace

     #
     # Alternate 1280x1024@44Hz, Interlaced mode (non-standard dot-clock)
     # Horizontal Sync=47.6kHz
     # Timing: H=(0.42us, 2.88us, 0.64us) V=(0.08ms, 0.12ms, 0.96ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1280x1024i"  75     1280 1312 1528 1576   1024 1028 1034 1080  Interlace

     #
     # 1280x1024@59Hz Non-Interlaced mode (non-standard)
     # Horizontal Sync=63.6kHz
     # Timing: H=(0.36us, 1.45us, 2.25us) V=(0.08ms, 0.11ms, 0.65ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1280x1024"  110     1280 1320 1480 1728   1024 1029 1036 1077

     #
     # 1280x1024@61Hz, Non-Interlaced mode
     # Horizontal Sync=64.25kHz
     # Timing: H=(0.44us, 1.67us, 1.82us) V=(0.02ms, 0.05ms, 0.41ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1280x1024"  110     1280 1328 1512 1712   1024 1025 1028 1054

     #
     # 1280x1024@74Hz, Non-Interlaced mode
     # Horizontal Sync=78.85kHz
     # Timing: H=(0.24us, 1.07us, 1.90us) V=(0.04ms, 0.04ms, 0.43ms)
     #
     # name        clock   horizontal timing     vertical timing      flags
      "1280x1024"  135     1280 1312 1456 1712   1024 1027 1030 1064

     Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/Config.sgml,v 3.11.2.1 1998/04/29 04:18:28 dawes Exp $

     $XConsortium: Config.sgml /main/7 1996/10/19 18:03:03 kaleb $

