Quick-Start Guide to XFree86 Setup <author>Joe Moss <date>27 February 1998 <abstract> Current releases of XFree86 include several tools that can help to automate the process of server configuration. Much of the existing documentation, however, describes how to do the job manually, including many technical details. For those users with esoteric hardware or with the desire to get their hands dirty under the hood, this is great, but many users are using common hardware and just want to get X up and running quickly. This guide is for them. </abstract> <toc> <sect> Before You Start There are a few bits of information that you will need to have before you can setup the server: <descrip> <tag> The model name of your video card </tag> Make sure you know the exact model name of the card. It may help to also know the graphics chipset, RAMDAC, and clock chip used on your card. <tag> The amount of memory on your video card </tag> Find out how many megabytes of RAM are on your video card. <tag> Whether or not your card is VGA compatible </tag> Most cards these days are VGA compatible, but for example, if you have and older monochrome card, it might not be. <tag> Your monitor's specifications </tag> Specifically, you need to know the horizontal sync rate(s), and vertical refresh rate(s). These are <bf>important</bf>! Consult your monitor's manual. <tag> The protocol used by your mouse </tag> It will help speed up the process, if you know which protocol is used by your mouse to communicate. Some mice are capable of using two different protocols, although the method of switching between them varies. In some cases, with new Plug-n-Play mice, the protocol can be determined automatically. </descrip> <sect> What to Do - An Overview There are three tools that can be used to set up XFree86: <itemize> <item>XF86Setup <item>xf86config <item>xvidtune </itemize> XF86Setup primarily uses a graphical user interface and is the preferred tool for initial setup, but there are a few cases where it can't be used. If you are using a card that is not VGA compatible, have a fixed-frequency monitor, or are running OS/2, you'll not be able to use XF86Setup, read about xf86config instead. If you have limited RAM or a slow system, you might be better off using xf86config as well. The xf86config program is text based only, but works for almost any hardware combination. If you have a fixed frequency monitor that won't work with standard text modes, you will have to read the necessary documentation and do the configuration manually. To get things looking just right, you may need to use <tt>xvidtune</tt>, a program that allows you to make adjustments to the displayed image (e.g. make it wider, move it a little to the left, etc.). XF86Setup will allow you to run xvidtune at the appropriate time; if you use xf86config, you can use xvidtune afterwards. All of these are explained in detail in the following sections. If you're the type that doesn't like to read the documentation, but would rather just try and figure your way through things, you can just type <tt/XF86Setup/ now. If you have problems, the documentation will still be here. Although it is possible to use XF86Setup from within X to make changes to your existing configuration, such use is not specifically documented here. These instructions are primarily for those initially setting up XFree86 on their system. <sect> Using <tt>XF86Setup</tt> XF86Setup will first check around to make sure certain files are installed and that you are running as root. If a problem is found, it will display a message and exit. Correct the problem (e.g. install the missing files) and run it again. XF86Setup is internationalized. If you are Japanese and set the LANG environment variable to ja, japan, japanese, etc., XF86Setup's screen can be Japanized. But it is necessary that XF86Setup is built with Japanized Tcl/Tk. Other language can be added, if you prepare its own directory under the directory XF86Setup/texts. Please see under the directory XF86Setup/texts/generic. <sect1> Initial questions If you have an existing XF86Config file, you will be asked if you would like to use it to set the default values of various configuration settings. If you've already got an (at least somewhat) working configuration you will want to do this. If you are running on an OS which has a mouse driver in the kernel (e.g. SCO or SVR4), you may be asked if you'd like to use it. Once the questions (if any) are completed, you will see a message indicating that the program is ready to switch into graphics mode. Just press Enter. If you don't get a graphics screen saying <it/Welcome to XFree86 Setup/ within a minute, something has probably hung, you can try pressing Ctrl-Alt-Backspace to switch back to text mode and you'll probably have to use xf86config instead of XF86Setup. <sect1> Configuration areas Once the VGA16 server is started, and once the program has finished loading, you will see a screen with six buttons along the top and three along the bottom. The buttons along the top correspond to the general categories of configuration settings. They can be done in any order. Each of these areas is explained in detail below. The bottom row consists of the <bf/Abort/, <bf/Done/, and <bf/Help/ buttons. <bf/Abort/ does as it name implies. It exits the program without saving any changes that have been made. The one possible exception is the link to the mouse device. Any change to that is made as soon as <bf/Apply/ is selected. <bf/Done/ should be selected when you've finished configuration in each of the various categories. The <bf/Help/ can be pressed at any time to get on-line help regarding the current configuration screen. You should start with configuring your mouse as it will make things a lot easier to perform the configuration of other categories. <sect2> Mouse The mouse configuration screen is used to get the mouse working properly. There are key bindings for everything so that you can easily configure the mouse, if it's not already working. The screen includes a representation of a white mouse with three buttons. As you move your mouse it should show the pointer coordinates on the mouse and the buttons should turn black as you press the corresponding button on your mouse. If that is not happening, then your mouse is not correctly configured. Along the top are some rows of buttons corresponding to the various possible protocols. There will also be several buttons and a couple of sliders for other settings, a visual representation of the mouse, and a button to apply any changes. There may also be an entry box in which the device can be set along with a list of possible devices. First try moving your mouse around and see if the pointer moves correctly. If so, try testing that the buttons are working properly. If those are working as desired, go ahead and go on to another configuration area. If the mouse pointer doesn't move at all, you need to fix either the mouse device or the protocol (or both). You can press 'n' followed by a Tab, to move to the list of mouse devices and select a different one. Pressing 'p' will pick the next available protocol on the list (protocols that are not available on your OS will be greyed-out). If you have a PnP mouse, it may be easiest to just select "Auto" as the protocol. After changing these, press 'a' to apply the changes and try again. Repeat the process until you are getting some response from your mouse. If the mouse pointer or button indicators do something when you move the mouse, but the pointer is not moving properly, you probably have the wrong protocol selected. Try with a different one. Most mice these days use the <bf/Microsoft/ protocol, the second most common is <bf/MouseSystems/. Some mice do both. These <it/dual-protocol/ mice have various methods of switching between the two protocols. Some have a switch on the mouse itself. Some are switched by sending a certain signal to the mouse when opening a connection to the mouse. These signals can be controlled by using different combinations of the 'ClearDTR' and 'ClearRTS' settings. Other mice require a button to be depressed when the mouse is opened (when the mouse driver first tries to talk to it). If your mouse uses this method, hold down the appropriate button while selecting apply (pressing 'a'). Once the mouse pointer is moving correctly, test that all three buttons are working properly. If your mouse only has two buttons, select 'Emulate3Buttons' and you should be able to press both buttons simultaneously to emulate the missing middle button. If not all of the buttons are working, try changing the 'ChordMiddle' setting or you may be using a protocol that is similar to that of your mouse, but not quite right. <sect2> Keyboard You need to specify the model and layout of your keyboard (and press apply) if they are not already correct. The graphical representation of the keyboard will be updated when you choose a different model. For non-U.S. keyboards you may wish to choose a variant from the list (at this time there is only one available variant: <tt/nodeadkeys/>). You can also pick from the options to the right, if you wish. <sect2> Card Pick your card from the list. If there are README files that may pertain to your card the 'Read README file' button will then be usable (i.e. not greyed out). Please read them. If your card is not in the list, or if there are any special settings listed in the README file as required by your card, you can press the 'Detailed Setup' button to make sure that the required settings are selected. Otherwise, you're finished with configuring your card. To use 'Detailed Setup': First select the appropriate server for your card. Then read the README file corresponding to the selected server by pressing the 'Read README file' button (it won't do anything, if there is no README). Next, pick the chipset, and Ramdac of your card, if directed by the README file. In most cases, you don't need to select these, as the server will detect (probe) them automatically. The clockchip should generally be picked, if your card has one, as these are often impossible to probe (the exception is when the clockchip is built into one of the other chips). Choose whatever options are appropriate (again, according to the README). You can also set the maximum speed of your Ramdac. Some Ramdacs are available with various speed ratings. The max speed cannot be detected by the server so it will use the speed rating of the slowest version of the specified Ramdac, if you don't specify one. Additionally, you can also specify the amount of RAM on your card, though the server will usually be able to detect this. <sect2> Modeselect Use this one to pick which depth you prefer to use (this determines how many colors can be displayed at a time) and to select all of the modes you are interested in possibly using. Your hardware may not be able to support all of depth and mode combinations that can be selected. Any unsupported combinations will automatically be rejected by the server when it tries to startup. Note also that if you select multiple modes, you will get a virtual screen as large as the largest of the usable modes. <sect2> Monitor Enter the horizontal and vertical frequency ranges that your monitor supports in the corresponding entry boxes near the top of the screen. You can enter specific frequencies or ranges of frequencies (separated by hyphens). If the monitor supports several different frequencies or ranges, list them all, separated by commas. If you can not find this information in you monitor's manual, pick one of the choices from the list of common monitor capabilities. The program will use conservative values for each of these, so you'll get better performance if you type in the correct values from your monitor manual. <sect2> Other You can probably just skip this one. <sect2> Completing the configuration Once you've finished with the above, press the 'Done' button and then the 'Okay' button which will appear. You will then be switched back to text mode. <sect1> Back to text mode The program will now attempt to start the appropriate server for your card, with all of the configuration settings you selected. If for some reason it is unable to start the server, you have likely selected an improper setting and will be asked if you would like to return to the graphical configuration screen and try again. <sect1> The second server This is unlikely to happen, but if when the server starts, the display is unreadable, try pressing Ctrl-Alt-+ (using the plus on the numeric keypad) to switch to a different video mode. The display will show an entry box and three buttons. The first button allows you to run xvidtune to adjust your video modes. One important point to keep in mind when using xvidtune is that switching video modes with Ctrl-Alt-+ is disabled while xvidtune is running. You must use the 'Next' and 'Prev' buttons to switch modes. Because of this, you should be careful not to move the mouse when pressing either of these. If by some chance the mode you switch to doesn't produce a readable display on your monitor, you can then just press the mouse button again to move to the next (hopefully readable) mode. The second button causes the settings you've made to be written to the filename given in the entry box. After saving the settings a message will appear indicating that it has finished. Just press the 'Okay' button and you're done. And the third button causes the program to exit without saving any of the configuration settings. <sect1> Ending text You are returned to text mode and the program will print a `Configuration complete.' message. You should now have a usable configuration file and can start the X server by whichever method you wish (usually either the 'startx' command or via 'xdm'). <sect> Running <tt>xf86config</tt> From a text screen, run the <tt/xf86config/ program. This program should be run as <it/root/ (although not absolutely necessary, it will allow xf86config to do more of the work for you). You can press your interrupt character (usually Control-C or perhaps Delete), at any time to stop the program, if you need to. You can just start it over again. The <tt/xf86config/ program provides instructions on screen as to what you need to do. Following are some notes that document the various stages in the process. They should help you get through the process quickly and provide some documentation for those people who like to know what they're getting themselves into, before running a program. <sect1> The intro screen First, <tt/xf86config/ begins by telling you a few things like the fact that it can help you setup an XF86Config file or that you can do the job yourself with an editor. Just read what it says and press <sf/Enter/ when done. <sect1> Getting your <tt>PATH</tt> right The program will next check that you have the directory <tt>/usr/X11R6</tt> (the standard installation directory) on your system and tell you that it needs to be in your <tt/PATH/ environment variable. It will also check if you have the <tt>/usr/X386</tt> directory as used by older (pre 3.0) versions of XFree86. If by chance you do, it will warn you that <tt>/usr/X11R6</tt> must be before <tt>/usr/X386</tt> in your <tt/PATH/. If everything is okay, just press Enter and go on, otherwise press Control-C to exit and make any necessary changes and restart <tt/xf86config/. <sect1> Mouse setup Pick the mouse type from the menu and enter the name of the device to which mouse is connected, as directed. If you are using an OS (e.g. SVR4, SCO) that has a built in mouse driver that the Xserver could use, you'll need to edit the XF86Config file to setup your mouse, so just pick any mouse from the list and press enter when asked for the device. If you don't know which protocol your mouse uses, you'll just have to guess (the xf86config program will give you some hints as to which might be most likely) and then see the troubleshooting section if it doesn't work when you run the server. The xf86config program has not been updated to allow you to select the latest mouse protocols, so you may have to edit the config file by hand after xf86config has finished. <sect1> Keyboard setup Simply answer yes to the question regarding keyboard setup. If there is some reason you need to use the right-alt and control keys for something else, you can enter no. <sect1> Monitor setup Setting up a monitor consists of entering the specifications of your monitor and a description of the model and manufacturer. You are first asked for the horizontal sync rate. It is <bf/VERY/ important to enter the correct value(s) from the manual. If one of the ranges given matches the rate of your monitor, then pick it, otherwise pick <tt/custom/ and enter the values from your manual. Next is the vertical refresh rate. Again, it is <bf/VERY/ important that this parameter be specified correctly. Enter it in a manner similar to the horizontal sync rate. <it>If either rate is mis-specified, it can result in damage to your monitor.</it> Finally, you are asked for an "identifier", your monitor manufacturer, and model. You can just press enter to get through these quickly. <sect1> Selecting your card You are next asked if you would like to view the database of cards. Picking your card from the list will cause the answers to the questions in the next two sections to be filled in for you and so can save a little time. If your card does not appear in the list, just press <tt/q/ and enter to skip on to the next step - where you'll have to answer the questions yourself. <sect1> Server selection If you selected your card in the previous step, then server selection is easy - just use the recommendation from the database. If you have a card which uses one of the chipsets for which a specific server exists (Mach8, Mach32, Mach64, AGX/XGA, 8514/A, S3, I128, P9000) you'll want to pick the <tt/accel/ option. Otherwise you'll probably want to use the SVGA server. Next, answer yes when the program asks if you want it to set the symbolic link for you. If you picked the <tt/accel/ option, you'll also need to indicate which particular accelerated server to link to. <sect1> Screen/Video configuration Pick the appropriate option from the list to indicate the amount of memory on your video card. Then you are asked to provide and identifier, the manufacturer, and the model of your card. You can just press enter to skip through these, if you wish. Next, the program will ask for the type of RAMDAC and Clockchip on your card. If your card was in the database, you should just to tell it to use the values from the database. If you don't have one of the listed RAMDACs or Clockchips on your card, just press enter when asked what type you have. If you do not have a programmable clock chip, the program will next attempt to probe to find out what clock rates are supported by your clock chip. <sect1> Mode Selection Now you get to tell the program which video modes you would like to be able to run. The program will show you the common modes that should work with your card (some might not work with your monitor, but if you've correctly specified the monitor's sync rates, the X server will just ignore them when it runs). You could just accept the settings as they are given, but you'll probably wish to reverse the order. For example, if you have a card with 1 Meg RAM, it will list the modes <tscreen><verb> "640x480" "800x600" "1024x768" for 8bpp </verb></tscreen> Select <tt/1/ to change the settings for 8bpp and the type <tt/432/ to select the reverse order. When you've select the modes, in the order you wish, select option <tt/4/ to continue. <sect1> Creating the <tt>XF86Config</tt> file The program will now ask if you would like to write the configuration settings you've selected to the file <tt/XF86Config/. Answer yes. <sect1> Some final notes Lastly, the program tells you that it's finished its part of this process and counsels you to check the file before using it. The next section covers the changes that are most likely to be needed. <sect> Fixing the XF86Config file Use an editor to look at the <tt/XF86Config/ file. Here are some things that may need to be changed: <itemize> <item>If you are running an operating system which has built-in mouse support, you'll want to change the <tt/Pointer/ section. Specifically, you should set the <tt/Protocol/ to <tt/OSMouse/ (SCO) or <tt/Xqueue/ (SVR4, some SVR3) and you should remove the <tt/Device/ line. <item>If you are running a system with the Xqueue event driver and would like to use it, change the <tt/Protocol/ setting in the <tt/Keyboard/ section to <tt/Xqueue/.  </itemize> Once you are satisfied that the configuration is correct, copy the XF86Config file to <tt>/usr/X11R6/lib/X11</tt> and run the 'startx' command. You should now have a running X server. If it's running but the display doesn't look as good as you think it should (i.e. it doesn't fill the whole screen, it's off-center, it's wrapping around on one side, etc.) see the section on <tt/xvidtune/. If there is some other problem, see the troubleshooting section. <sect> Running <tt>xvidtune</tt> If you need to make adjustments to the video display, <tt/xvidtune/ is the tool to use. Simply enter the command <tt/xvidtune/ from a shell prompt within an xterm. Read the warning and click on <tt/OK/. Next click on the <tt/Auto/ button. Now click on whatever combination of <tt>Up/Down/Left/Right</tt> <tt>Shorter/Taller/Wider/Narrower</tt> is need to adjust the display to your liking. If you are using a recent S3-based card there will be some extra buttons and entries at the bottom (InvertVCLK, EarlySC, and Blank Delays). These can help solve problems of the display wrapping around a few pixels. Once the display has been adjusted properly, press the <tt/show/ button to printout the correct <tt/ModeLine/ to put in the <tt/XF86Config/ to make the server always use the current display settings. To aid in copying this information to your XF86Config file, the modeline is also made the current selection allowing you to just paste it into your editor. If you would like to adjust your other modes, you can click on the <tt/Next/ and <tt/Prev/ buttons to switch modes. When you are through using <tt/xvidtune/ simply press on the <tt/Quit/ button. <sect> Troubleshooting Since you're reading this, something must not have gone the way you had hoped (or else you just really enjoy reading). Below are listed some common problems that may occur during configuration and some hints for solving them. However, there are just too many different combinations of hardware and software configurations, and, well, just too many things that can go wrong, for this document and the tools it documents, to cover every case. If after trying the steps in the previous sections and checking the hints in this section, you still are unable to get your system working, you'll have to read the full documentation. Read the README file for your card and OS (if they exist), the XFree86 Configuration Guide (README.Config), and the XF86Config man page. You should also look at <url name="the XFree86 FAQ" url="http://www.XFree86.org/FAQ"> for more up-to-date information, especially if you are trying to configure a fairly new card. If all else fails, you can try posting a message to comp.windows.x.i386unix or comp.os.linux.x or send email to XFree86@XFree86.org. <sect1> The mouse doesn't move correctly, it stays in one area of the screen You've selected the wrong protocol for your mouse. Try a different one. <sect1> The server doesn't start, it says the mouse is busy. Well, it's probably right. This most often happens on Linux systems that have <tt/gpm/ running. Kill the <tt/gpm/ process and try <tt/startx/ again. <sect1> The middle button doesn't work. There's no easy answer to this one. It's a lot of trial and error. You need to make sure you're running the right protocol for your mouse. Many three button mice are "dual protocol" which means that they have both a 2-button and 3-button mode. The way to get the mouse to switch into 3-button mode (which usually then uses MouseSystems protocol) varies between different models. You may need to slide a switch on the mouse or hold down the middle button when starting the server. Other methods of switching modes can be done by the server, you just have to find the right combination of settings for your mouse. See the Pointer section of the XF86Config man page for a complete list of settings. <sect1> The display is shifted to the left/right/top/bottom See the section on xvidtune. <sect1> I don't appear to have xf86config or xvidtune on my system Hmmm. A couple of possibilities: <enum> <item>Your <tt/PATH/ is not set correctly. Make sure it includes the bin directory for the XFree86 binaries (usually, <tt>/usr/X11R6/bin</tt> <item>You don't have a complete installation of XFree86. Go back to wherever you got XFree86 and get the missing pieces. </enum>  <verb> $XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/QStart.sgml,v 3.7 1999/08/23 06:38:51 dawes Exp $ </verb> </article>