  A Step-By-Step Guide

  Configuring XFree86
  David Wexelblat and The XFree86 Project, Inc

  5 October 1994

  This document describes how to set up your XFree86 server and the cor-
  responding XF86Config configuration file.  If you follow the proce-
  dures 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 configuration.  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
        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 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 parameters that may be
  in this section of the file.
  Next comes the "Keyboard" section.  In this section, you can specify
  the keyboard 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 Logitech 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
  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 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 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.windows.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 versions 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 monitor'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 monitor.  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.


  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

  ______________________________________________________________________



  $XConsortium: Config.sgml,v 1.3 95/01/23 15:34:40 kaleb Exp $
  Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/Config.sgml,v 3.5 1995/01/28 16:01:22 dawes Exp $
































































