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 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 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. <tag>XF86_W32:</tag> ET4000/W32 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 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% 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 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 #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 <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 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 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, 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. <sect> Generic Video Modes <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> $XConsortium: Config.sgml,v 1.3 95/01/23 15:34:40 kaleb Exp $ $XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/Config.sgml,v 3.5 1995/01/28 16:01:22 dawes Exp $ </verb> </article>