








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


Configuring XFree86: A Step-By-Step Guide                                     1





Configuring XFree86: A Step-By-Step Guide                                     2



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









Configuring XFree86: A Step-By-Step Guide                                     3



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, depend-
ing on how the distribution was assembled.  You can run /usr/X11R6/bin/X -show-
config 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 run-
ning the 'mkfontdir' command in each directory if you are certain that each one
is correct.  The XF86Config(4/5) manual page describes other parameters 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 mod-
ifier 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 Logitech pro-
tocol.  Some other mouse parameters can be adjusted here.  If you are using a
two-button mouse, uncomment the Emulate3Buttons keyword - in this mode, press-
ing both mouse buttons simultaneously causes the server to report a middle but-
ton 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 misconfiguration 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 sec-
tions 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








Configuring XFree86: A Step-By-Step Guide                                     4



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 accelerated cards, you
can also look in the `AccelCards' file.  If you are fortunate, 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 programmable 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 monitors 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 cate-
gory, 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








Configuring XFree86: A Step-By-Step Guide                                     5



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 func-
tional.  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 moni-
tor's specifications.  In particular, you need to know what range of horizontal
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 information is entered into
the Monitor section.

Next, you need to provide a set of video modes that are suitable for the moni-
tor.  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 VideoModes.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.











Configuring XFree86: A Step-By-Step Guide                                     6



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 dis-
play, and you can cycle through the list with Ctrl-Alt-Keypad+ or Ctrl-Alt-Key-
pad- hotkey sequences.

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


7.  Generic Video Modes




























Configuring XFree86: A Step-By-Step Guide                                     7



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








Configuring XFree86: A Step-By-Step Guide                                     8



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

     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 $












Configuring XFree86: A Step-By-Step Guide                                     9





































































                                   CONTENTS



1. Procedure Overview ....................................................... 1

2. Setting Up The Correct Default Server .................................... 2

3. The Easy Parts of XF86Config ............................................. 3

4. Configuring the Video Hardware ........................................... 3

5. Configuring the Monitor and its Modes .................................... 5

6. Combining the Video Hardware and Monitor Data ............................ 6

7. Generic Video Modes ...................................................... 6







































                                       i


