			Configuring XFree86
			A Step-By-Step Guide
			--------------------

Contents
--------
	1) Introduction
	2) Procedure Overview
	3) Setting Up the Correct Default Server
	4) The Easy Parts of Xconfig
	5) Configuring the Video Hardware
	6) Configuring the Monitor Modes
	7) Generic Video Modes

1 - Introduction
----------------
	This document describes how to set up your XFree86 server and
the corresponding Xconfig 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.SVR3) 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).

2 - 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
Xconfig 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 Xconfig file contains several sections; these procedures 
will lead you through filling out each part.  There is a default/sample 
Xconfig file in /usr/X386/lib/X11/Xconfig.sample; you should copy this 
to /usr/X386/lib/X11/Xconfig, and edit that file to your specific 
configuration.  The Xconfig(4/5) manual page describes the Xconfig file 
contents and options in detail.  Be sure to read through that manual page 
as you fill in your Xconfig file.  The sections of the Xconfig file are:

	- Paths and generic server variables.  Sets the default font
	  path and a few other server configuration parameters.  Refer
	  to the manual page to learn about these.
	- Input devices.  Sets up keyboard and pointer devices, and sets
	  a few optional parameters.
	- Graphics setup.  Describes your video hardware to the server.
	- Video Mode setup.  Describes the physical display modes that
	  you will be using.

3 - Setting Up The Correct Default Server
-----------------------------------------
	The default server name is /usr/X386/bin/X.  This is a link
to a specific server binary XF86_xxxx, located in /usr/X386/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:   256-color Super-VGA server.  Contains accelerated
		     support for Cirrus 542{0,2,4,6,8} and Western
		     Digital 90C31 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 (experimental).
	XF86_S3:     S3 256-color accelerated server.
	XF86_Mach32: ATI Mach32 256-color accelerated server.
	XF86_Mach8:  ATI Mach8 256-color accelerated server.
	XF86_8514:   8514/A 256-color 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 Link Kit; the server binary may not contain all of
the possible drivers, depending on how the distribution was assembled.
You can run '/usr/X386/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 Link Kit for specific information.

4 - The Easy Parts of Xconfig
-----------------------------
	The first part of the Xconfig 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 Xconfig; 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 Xconfig(4/5) manual page describes other parameters that may be in
this section of the file.

	Next comes the Keyboard configuration section.  This begins
with the keyword "Keyboard" (the SVR3/4 xqueue driver is an exception;
refer to the Xconfig(4/5) man page).  In this section, you can specify
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 Xconfig(4/5) and XFree86kbd(1) man pages for details.

	After this comes the pointer-device configuration section.
This begins with the name of the mouse protocol to be used (note
"protocol", not "manufacturer" - the Logitech MouseMan uses the
MouseMan keyword, not the Logitech keyword, recent Logitech serial mice
use MicroSoft).  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.

5 - Configuring the Video Hardware
----------------------------------
	The video hardware section begins with one of the following
keywords: VGA256, VGA2, HGA2, BDM2, VGA16, ACCEL.  VGA256 parameters
are read by the XF86_SVGA server.  VGA2, HGA2, and BDM2 are read by
the appropriate drivers in the XF86_Mono server.  VGA16 parameters are
read by the XF86_VGA16 server.  The ACCEL parameters are read by
XF86_S3, XF86_Mach32, XF86_Mach8, and XF86_8514.  This last may seem
confusing, but a single Xconfig file will never be used for more than
one piece of hardware, and we anticipate merging all of those into a
single server at some point in the future.

	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.

	Once you decide which section you need to fill in, you need to
collect the data for your hardware, and make some configuration
decisions.  The hardware data you need is:

	- Chipset
	- Amount of video memory
	- Dot-clocks available

The server, in general, is capable of filling these on its own, but it
is best to fully specify things in the Xconfig 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 XF86_S3 has 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.
The first part of the 'modeDB.txt' file lists information for a myriad
of SVGA cards.  For accelerated cards, 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 Xconfig 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 the Clocks line in your Xconfig file will contain the name
of the programming algorithm in double-quotes 
(e.g. 'Clocks "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
Xconfig 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 Xconfig 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.

	You may need to specify some Option flags for your hardware
(these used to be called Vendor flags in old XFree86 releases).  The
server manual pages will describe these options, and the chipset-specific
README files will tell you if any are required for your board.

	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 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 this section 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
ModeDB section (described below).  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.

6 - Configuring the Monitor 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 first step is to check in the 'modeDB.txt' file to see if
there is a listing of modes for your specific monitor.  If there is,
copy those modes to the ModeDB section of your Xconfig file.  Verify
that there is a clock listed on the Clocks line in your Xconfig 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 ready to fire up your server.

	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 ModeDB section of your Xconfig 
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 couple of notes before you are done.  First - if the
same mode name occurs more than once in the ModeDB section of the
Xconfig file, the server will use the mode that comes last in the
file.  It is generally considered a bad idea to have more than one
mode with the same name in your Xconfig file.  The other note is
that there must be one mode in ModeDB for each mode specified in
the Modes line, otherwise the server will object.

	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 Sunc = 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


$XFree86: mit/server/ddx/x386/README.Config,v 2.4 1994/03/05 08:22:39 dawes Exp $
