path: root/xc/programs/Xserver/hw/xfree86/doc/sgml/QStart.sgml

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

<article>

<title>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
<p>
	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
<p>
	There are three tools that can be used to set up XFree86:
	<itemize>
	 <item>XF86Setup
	 <item>xf86config
	 <item>xvidtune
	</itemize>
<p>
	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.
<p>
	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.
<p>
	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.
<p>	
	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.
<p>
	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>
<p>
	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
<p>
	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
<p>
	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.
<p>
	<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.
<p>
	<bf/Done/ should be selected when you've finished
	configuration in each of the various categories.
<p>
	The <bf/Help/ can be pressed at any time to get on-line
	help regarding the current configuration screen.
<p>
	You should start with configuring your mouse as it will make
	things a lot easier to perform the configuration of other
	categories.

<sect2>	Mouse
<p>
	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.
<p>
	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.
<p>
	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.
<p>
	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.
<p>
	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.
<p>
	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.
<p>
	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').
<p>
	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
<p>
	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.
<p>
	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/>).
<p>
	You can also pick from the options to the right, if you wish.

<sect2>	Card
<p>
	Pick your card from the list.
<p>
	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.
<p>
	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.
<p>
	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).
<p>
	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.
<p>
	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).
<p>
	Choose whatever options are appropriate (again,
	according to the README).
<p>
	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.
<p>
	Additionally, you can also specify the amount of RAM on your
	card, though the server will usually be able to detect this.


<sect2>	Modeselect
<p>
	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.
<p>
	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
<p>
	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.
<p>
	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
<p>
	You can probably just skip this one.

<sect2>	Completing the configuration
<p>
	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
<p>
	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
<p>
	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.
<p>
	The display will show an entry box and three buttons.
<p>
	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.
<p>
	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.
<p>
	And the third button causes the program to exit without
	saving any of the configuration settings.

<sect1>	Ending text
<p>
	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>
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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
<p>
	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/.
<!--  What else should be added here?  -->
	</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>
<p>
	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
<p>
	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
<p>
	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.
<p>
	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.
<p>
	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
<p>
	See the section on xvidtune.

<sect1>	I don't appear to have xf86config or xvidtune on my system
<p>
	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>

<!-- Lots of things still need to be added -->

<verb>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/QStart.sgml,v 3.7 1999/08/23 06:38:51 dawes Exp $
</verb>

</article>