<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN">

<!-- Id: README.Config.sgml,v 1.1 1994/10/05 23:31:42 klemme Exp  -->

<article>

<title>Configuring XFree86: A Step-By-Step Guide
<author>David Wexelblat and The XFree86 Project, Inc
<date>5 October 1994

<abstract>
	This document describes how to set up your XFree86 server and
the corresponding <tt>XF86Config</tt> 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 <tt>README</tt> file for your OS (e.g.
<tt>README.SVR4</tt>) and the card/chipset specific <tt>README</tt>
file for you video card (e.g. <tt>README.trident</tt>).
Where these specific files contradict this generic file, you should
follow the specific instructions (there shouldn't be much of that, though).
</abstract>



<toc>


<sect>Procedure Overview
<p>
	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 <tt>XF86Config</tt>
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 <tt>XF86Config</tt> file contains several sections; these
procedures will lead you through filling out each part.
There is a default/sample <tt>XF86Config</tt> file in
<tt>/usr/X11R6/lib/X11/XF86Config.sample</tt>; you should copy 
this to <tt>/usr/X11R6/lib/X11/XF86Config</tt>, and edit that file to your
specific configuration.  
The <it>XF86Config(4/5)</it> manual page describes the
<tt>XF86Config</tt> file contents and options in detail.  
Be sure to read through that manual page as you fill in your
<tt>XF86Config</tt> file. 
 
The sections of the <tt>XF86Config</tt> file are:
 <descrip>
	<tag> Files </tag> 
	  Sets the default font and RGB paths.
	<tag> Server Flags</tag> 
	  Sets a few general server options.  Refer to the
	  manual page to learn about these.
	<tag> Keyboard</tag> 
	  Sets up keyboard devices, and sets a few optional
	  parameters.
	<tag> Pointer</tag> 
	  Sets up the pointer devices, and sets a few optional
	  parameters.
	<tag> Monitor</tag> 
	  Describes your monitor(s) to the server.
	<tag> Graphics Device</tag> 
	  Describes your video hardware to the server.
	<tag> Screen.</tag>
	  Describes how the monitor and video hardware should
	  be used.
 </descrip>


<sect>Setting Up The Correct Default Server
<p>

The default server name is <tt>/usr/X11R6/bin/X</tt>.
This is a link to a specific server binary <tt>XF86_xxxx</tt>, located
in <tt>/usr/X11R6/bin/</tt>.  
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:
 <descrip>
	<tag>XF86_SVGA:</tag>   
	  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.
 	<tag>XF86_Mono:</tag>   (S)VGA monochrome, optionally Hercules
	  or other monochrome hardware support is linked in.
	<tag>XF86_VGA16:</tag>  Generic VGA 16-color server.
	<tag>XF86_S3:</tag>     S3 accelerated server.
	<tag>XF86_Mach32:</tag> ATI Mach32 accelerated server.
	<tag>XF86_Mach64:</tag> ATI Mach64 accelerated server.
	<tag>XF86_Mach8:</tag>  ATI Mach8 accelerated server.
	<tag>XF86_8514:</tag>   8514/A accelerated server.
	<tag>XF86_P9000:</tag>  P9000 accelerated server.
	<tag>XF86_AGX:</tag>    AGX accelerated server.
 </descrip>

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 <tt>/usr/X11R6/bin/X -showconfig</tt> to get a printout of the
configured drivers.  If you need to relink your server, refer to the
<tt>README</tt> file in the LinkKit for specific information.

<sect>The Easy Parts of XF86Config
<p>


The "Files" section of the <tt>XF86Config</tt> 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 <tt>XF86Config</tt>; 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 <it>XF86Config(4/5)</it> 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
<it>XF86Config(4/5)</it> 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&percnt; 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.

<sect>Configuring the Video Hardware
<p>

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
<tt>README</tt> 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:
<itemize>
	<item>Chipset
	<item>Amount of video memory
	<item>Dot-clocks available or clock chip used (if programmable)
	<item>Ramdac type (for some servers)
</itemize>
The server, in general, is capable of filling these on its own, but it
is best to fully specify things in the <tt>XF86Config</tt> 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 <tt>modeDB.txt</tt> 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 <tt>XF86Config</tt> 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 <tt>XF86Config</tt>
file to identify the type of clock generator.  (e.g. 'ClockChip
"icd2061a"', which would be used for a &num;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>&amp;1'
(for sh or ksh) or 'X -probeonly >&amp;/tmp/out' (for csh). Be sure that the
<tt>XF86Config</tt> file does <bf>not</bf> 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 <tt>XF86Config</tt> 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 <tt>README</tt> files will tell you if any are required for your
board.

<sect>Configuring the Monitor and its Modes
<p>

	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 <tt>XF86Config</tt> 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 <it>XF86Config(4/5)</it>
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
<tt>modeDB.txt</tt> 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 <tt>XF86Config</tt> file.  Verify that there is a clock listed on the
Clocks line in your <tt>XF86Config</tt> 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 <tt>XF86Config</tt>
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 <tt>XF86Config</tt> 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 <tt>XF86Config</tt> file.

<sect>Combining the Video Hardware and Monitor Data
<p>

	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 <tt>XF86Config</tt>
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).
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&percnt; 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.

<sect>Generic Video Modes
<p>
<code>
#
#  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


</code>

<verb>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/Config.sgml,v 3.13 1998/04/12 12:43:41 dawes Exp $ 





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

</article>
