Library Zone Articles
External Articles
Byte Size

Discovery Zone Catalogue
Diary
Links
Bookstore
Interactive Zone Ask the Gurus
Discussion Groups
Newsletters
Feedback
Etc Cartoons
Humour
COMpetition
Advertising ASP Web Ring ASP Web Ring
Click here
The Developer's Resource & Community Site
COM XML ASP Java & Misc. NEW: VS.NET
International This Week Forums Author Central Find a Job
Buy the Book: Running Linux in a Nutshell

Running Linux in a Nutshell, Chapter 10: Installing the X Window System

(Reproduced with kind permision of O'Reilly & Associates: www.oreilly.com)





Contents:
X Concepts
Hardware Requirements
Installing XFree86
Configuring XFree86
Filling in Video Card Information
Running XFree86
Running Into Trouble

We come now to the X Window System - one of the most powerful and important software packages available for Linux. If you've ever used X on a Unix system before, you're in luck; running X under Linux is almost no different from Unix systems. And, if you've never had the occasion to use it before, never fear: salvation is at hand.

It's difficult to describe the X Window System in a nutshell. X is a complete windowing graphics interface for Unix systems. It provides a huge number of options to both the programmer and the user. For instance, there are at least half a dozen window managers available for X, each one offering a different interface for manipulating windows. By customizing the attributes of the window manager, you have complete control over how windows are placed on the screen, the colors and borders used to decorate them, and so forth.

X was originally developed by Project Athena at MIT and Digital Equipment Corporation. The current version of X is Version 11 revision 6 (X11R6), which was first released in April 1994. Since the release of Version 11, X has virtually taken over as the de facto standard for Unix graphical environments. It is now developed and distributed by The Open Group, an association that is composed of many large computer manufacturers.

Despite its commercial use, the X Window System remains distributable under a liberal license from the X Consortium. As such, a complete implementation of X is freely available for Linux systems. XFree86, an implementation of X, originally for i386 Unix systems, is the version most often used by Linux. Today, this version supports not only Intel-based systems, but also Alpha AXP, MicroSPARC, PowerPC, and other architectures. Further architectures will follow. XFree86 is based on X386-1.2, which was part of the official X11R5 sources, but is no longer maintained and is therefore outdated. The current versions now have only a very little part in common with their ancestors. Support for innumerable graphics boards and many other operating systems (including Linux) has been added - and XFree86 implements the latest version X11R6.3.

In this chapter, we will tell you how to install and configure the X Window System, and in the next chapter, we will explore how to use X.

Linux distributions automatically install X (if you ask them to). If you're lucky, you won't need this chapter at all. But a large percentage of users aren't lucky - the distribution doesn't recognize some graphics hardware, writes a file to the wrong location so the X server can't start up, or has some other problem. One of the big advantages of this book is that we take you down to the depths of X configuration so you can get it running no matter what your distribution does. You may not need to read this chapter, but if you do need it, you'll appreciate everything that's here.

1 X Concepts

X is based on a client-server model in which the X server is a program that runs on your system and handles all access to the graphics hardware. An X client is an applications program that communicates with the server, sending it requests such as "draw a line" or "pay attention to keyboard input." The X server takes care of servicing these requests by drawing a line on the display or sending user input (via the keyboard, mouse, or whatever) to the client application. Examples of X clients are xterm (which emulates a terminal within a window) or xman (an X-based manual-page reader).

It is important to note that X is a network-oriented graphics system. That is, X clients can run either locally (on the same system that the server is running) or remotely (on a system somewhere on a TCP/IP network). The X server listens to both local and remote network sockets for requests from clients. This feature is obviously quite powerful. If you have a connection to a TCP/IP network, you can log in to another system over the network and run an X application there, directing it to display on your local X server.

Further advantages of X are security (if the user so desires), the modular separation of functions, and the support for many different architectures. All this makes the X Window System technically superior by far to all other window systems.

The X Window System makes a distinction between application behavior and window management. Clients running under X are displayed within one or more windows on your screen. However, how windows are manipulated (placed on the display, resized, and so forth) and how they are decorated (the appearance of the window frames) is not controlled by the X server. Instead, it is handled by another X client called a window manager that runs concurrently with the other X clients. Your choice of window manager will decide to some extent how X as a whole looks and feels. Most window managers are utterly flexible and configurable; the user can select the look of the window decoration, the focus policy, the meaning of the mouse buttons when the mouse is on the background part of the screen rather than on an application window, and many other things by editing the configuration files of the window manager. More modern systems even let you configure those aspects over a graphical user interface.

In order to fully understand the concept of window managers, you need to know that the window manager does not affect the presentation of the window created by the client. The window manager is only in charge of painting the window decoration, that is, the frame and the buttons that let you close, move, and resize windows.

There can be only one window manager on any X server. Theoretically, it is even possible to completely do away with window managers, but then you would not be able to move windows around the screen; put a hidden window on top; or minimize, maximize, or resize windows unless the programs themselves provide this functionality.

10.2 Hardware Requirements

As of XFree86 Version 3.3.3.1, released in January 1999, the video chipsets listed in this section are supported. The documentation included with your video adaptor should specify the chipset used. If you are in the market for a new video card, or are buying a new machine that comes with a video card, have the vendor find out exactly what the make, model, and chipset of the video card is. This may require the vendor to call technical support on your behalf; vendors usually will be happy to do this. Many PC hardware vendors will state that the video card is a "standard SVGA card" that "should work" on your system. Explain that your software (mention Linux and XFree86!) does not support all video chipsets and that you must have detailed information.

A good source for finding out whether your graphics board is supported and which X server it needs is https://www.xfree86.org/cardlist.html.

You can also determine your video card chipset by running the SuperProbe program included with the XFree86 distribution. This is covered in more detail later.

The following accelerated and nonaccelerated SVGA chipsets are supported:

  • 3DLabs GLINT 500TX, GLINT MX, Permedia, Permedia 2, Permedia 2v

  • 8514/A (and true clones)

  • Alliance AP6422, AT24

  • ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 68800-6, 68800AX, 68800LX, 88800GX-C, 88800GX-D, 88800GX-E, 88800GX-F, 88800CX, 264CT, 264ET, 264VT, 264GT, 264VT-B, 264VT3, 264GT-B, 264GT3 (includes the Mach8, Mach32, Mach64, 3D Rage, 3D Rage II and 3D Rage Pro)

  • ARK Logic ARK1000PV, ARK2000PV, ARK1000VL, ARK2000MT

  • Avance Logic ALG2101, ALG2228, ALG2301, ALG2302, ALG2308, ALF2401

  • Chips and Technology 65520, 65525, 65530, 65535, 65540, 65545, 65546, 65548, 65550, 65554, 65555, 68554, 69000, 64200, 64300

  • Cirrus Logic CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, CLGD5429, CLGD5430, CLGD5434, CLGD6205, CLGD6215, CLGD6225, CLGD6235, GLGD6410, CLGD6412, CLGD6420, CLGD6440, CLGD7541, CLGD7543, CLGD7548, CLGD7555

  • Compaq AVGA

  • Cyrix MediaGX, MediaGXm

  • Digital Equipment Corporation TGA

  • Epson SPC8110

  • Genoa GVGA

  • IBM XGA-2

  • IIT AGX-014, AGX-015, AGX-016

  • Matrox MGA2064W (Millenium), MGA1064SG (Mystique and Mystique 220), MGA2164W (Millenium II PCI and AGP), G100, G200

  • MX MX68000, MX680010

  • NCR 77C22, 77C22E, 77C22E+

  • NeoMagic 2200, 2160, 2097, 2093, 2090, 2070

  • Number Nine I128 (series I, II, and IV), Revolution 3D (T2R)

  • NVidia/SGS Thomson NV1, STG2000, Riva 128, Riva TNT

  • OAK OTI067, OTI077, OTI087

  • RealTek RTG3106

  • Rendition V1000, V2x00

  • S3 86C911, 86C924, 86C801, 86C805, 86C805i, 86C928, 86C864, 86C964, 86C732, 86C764, 86C765, 86C767, 86C775, 86C785, 86C868, 86C968, 86C325, 86C357, 86C375, 86C385, 86C988, 86CM65, 86C260

  • SiS 86C201, 86C202, 86C205, 86C215, 86C225, 5597, 5598, 6326

  • Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000, TVGA9000i, TVGA9100B, TVGA9200CXR, Cyber9320, TVGA9400CXi, TVGA9420, TGUI9420DGi, TGUI9430DGi, TGUI9440AGi, TGUI9660XGi, TGUI9680, ProVidia 9682, ProVidia 9685, Cyber 9382, Cyber 9385, Cyber 9388, 3DImage975, 3DImage985, Cyber 9397, Cyber 9520

  • Tseng ET3000, ET4000AX, ET4000/W32, ET4000/W32i, ET4000/W32p, ET6000, ET6100

  • Video 7/Headland Technologies HT216-32

  • Weitek P9000, P9100

  • Western Digital WD90C00, WD90C10, WD90C11, WD90C24, WD90C30, WD90C31, WD90C33, WD90C24A

  • Western Digital/Paradise PVGA1

Video cards using these chipsets are normally supported on all bus types, including the PCI and AGP.

All of these chipsets are supported in 256-color mode, some are supported in mono- and 16-color modes, and some are supported on higher color depths.

The monochrome server also supports generic VGA cards, using 64k of video memory in a single bank, the Hercules monochrome card, the Hyundai HGC1280, the Sigma LaserView, the Visa, and the Apollo monochrome cards.

The VGA16 server supports memory banking with the ET4000, Trident, ATI, NCR, OAK and Cirrus 6420 chipsets, allowing virtual display sizes up to about 1600x1200 (with 1 MB of video memory). The maximum display size for other chipsets and X servers varies, but you can get 1024x768 with most modern chipsets, often more (this also depends on the amount of video memory available and the color mode that you choose).

This list will undoubtedly expand as time passes. The release notes for the current version of XFree86 should contain the complete list of supported video chipsets. Please also always see the README file for your particular chipset.

Besides those chipsets, there is also support for the framebuffer device in the 2.2 kernel series via the FBDev server; this kernel has unaccelerated support for several chipsets for which there is not yet a dedicated server; it also supports acceleration on some hardware. If your graphics board is supported by any of the "ordinary" servers, you should use one of those, not the framebuffer server.

One problem faced by the XFree86 developers is that some video card manufacturers use nonstandard mechanisms for determining clock frequencies used to drive the card. Some of these manufacturers either don't release specifications describing how to program the card or require developers to sign a nondisclosure statement to obtain the information. This would obviously restrict the free distribution of the XFree86 software, something that the XFree86 development team is not willing to do.

The suggested minimum setup for XFree86 under Linux is a 486 machine with at least 16 MB of RAM and a video card with a chipset listed earlier. For optimal performance, we suggest using an accelerated card, such as an S3-chipset card. You should check the documentation for XFree86 and verify that your particular card is supported before taking the plunge and purchasing expensive hardware. Benchmark ratings comparisons for various video cards under XFree86 are posted to the Usenet newsgroups comp.windows.x.i386unix and comp.os.linux.misc regularly.

As a side note, one author's (Kalle's) personal Linux system is an AMD K6-2 with 128 MB of RAM and is equipped with a PCI Permedia II chipset card with 8 MB of DRAM. This setup is already a lot faster with respect to display speed than many workstations. XFree86 on a Linux system with an accelerated SVGA card will give you much greater performance than that found on commercial nix workstations (which often employ simple frame buffers for graphics and provide accelerated graphics hardware only as a high-priced add-on).

Your machine will need at least 8 MB of physical RAM, and 16 MB of virtual RAM (for example, 8 MB physical and 8 MB swap). Remember that the more physical RAM you have, the less the system will swap to and from disk when memory is low. Because swapping is inherently slow (disks are very slow compared to memory), having 8 MB of RAM or more is necessary to run XFree86 comfortably. A system with 8 MB of physical RAM could run much more slowly (up to 10 times more slowly) than one with 16 MB or more.

10.3 Installing XFree86

The Linux binary distribution of XFree86 can be found on a number of FTP sites. On ftp://ftp.xfree86.org, it is found in the directory /pub/XFree86/3.3.3.1/binaries; there you will find systems for Intel, m68k, PPC, and Alpha AXP in subdirectories. (At the time of this writing, the current version is 3.3.3.1; newer versions are released periodically).

It's quite likely you obtained XFree86 as part of a Linux distribution, in which case downloading the software separately is not necessary. If you are downloading XFree86 directly, the following tables list the files in the XFree86-3.3.3.1 distribution.

One of the following servers is required (not all of those are available for all platforms, but all are available for Intel systems):

File Description
X8514.tgz Server for 8514-based boards
XAGX.tgz Server for AGX-based boards
XMa32.tgz Server for Mach32-based boards
XMa64.tgz Server for Mach64-based boards
XMa8.tgz Server for Mach8-based boards
XMono.tgz Server for monochrome video modes
XP9K.tgz Server for P9000-based boards
XS3.tgz Server for S3-based boards
XSVGA.tgz Server for Super VGA-based boards
XVG16.tgz

Server for VGA/EGA-based boards (needed for XF86Setup)

XW32.tgz Server for ET4000/W32-based boards
X3DL.tgz Server for boards with 3Dlabs chipsets
XI128.tgz Server for I128-based boards

All of the following files are required:

File Description
Xbin.tgz The rest of the X11R6 binaries
Xcfg.tgz Configuration files for xdm and xinit
Xdoc.tgz Documentation
Xlib.tgz Shared X libraries and support files
Xfnts.tgz Basic fonts
Xman.tgz Manual pages
Xset.tgz Configuration utility XF86Setup
XVG16.tgz VGA server; needed by configuration utility XF86Setup
preinst.sh Pre-installation script
postinst.sh Post-installation script
extract Extraction utility

The following files are optional:

File Description
Xlkit.tgz Server link kit for customization
Xf100.tgz 100-dpi screen fonts
Xfscl.tgz Scaled fonts (Speedo, Type1)
Xfcyr.tgz Cyrillic fonts
Xfnon.tgz

Other fonts (Chinese, Japanese, Korean, and Hebrew)

Xfsrv.tgz Font server and configuration files
Xprog.tgz

X header files, configuration files, and libraries needed at compilation time

Xnest.tgz Nested X server
Xvfb.tgz X server that uses a virtual framebuffer
Xprt.tgz X Print server
Xps.tgz PostScript version of the documentation
Xhtml.tgz HTML version of the documentation
Xjdoc.tgz Japanese version of some documentation
Xjhtm.tgz Japanese HTML version of the documentation

The XFree86 directory should contain README files and installation notes for the current version.

Obtain these files and save them in the directory /var/tmp (you can use any other directory; just change the pathname accordingly in the following examples), and create the directory /usr/X11R6 as root. Copy the three files preinst.sh, postinst.sh and extract to /var/tmp. Change to the directory /usr/X11R6 and run:

sh /var/tmp/preinst.sh

Next, make sure the extract utility that you downloaded is executable:

chmod 755 extract

Now unpack the binaries by typing:

/var/tmp/extract /var/tmp/X*.tgz

Finally, run the post-installation script:

sh /var/tmp/postinst.sh

You need to make sure that /usr/X11R6/bin is on your path. This can be done by editing your system default /etc/profile or /etc/csh.login (based on the shell that you or other users on your system, use). Or you can simply add the directory to your personal path by modifying /etc/.bashrc or /etc/.cshrc, based on your shell.

You also need to make sure that /usr/X11R6/lib can be located by ld.so, the runtime linker. To do this, add the line:

/usr/X11R6/lib
to the file /etc/ld.so.conf, and run /sbin/ldconfig as root.

10.4 Configuring XFree86

Setting up XFree86 is not difficult in most cases. However, if you happen to be using hardware for which drivers are under development, or wish to obtain the best performance or resolution from an accelerated graphics card, configuring XFree86 can be somewhat time-consuming.

In this section, we describe how to create and edit the XF86Config file, which configures the XFree86 server. In many cases, it is best to start out with a "basic" XFree86 configuration - one that uses a low resolution. A good choice is 640x480, which should be supported on all video cards and monitor types. Once you have XFree86 working at a lower, standard resolution, you can tweak the configuration to exploit the capabilities of your video hardware. The idea is that you want to make sure XFree86 works at least minimally on your system and that something isn't wrong with your installation before attempting the sometimes difficult task of setting up XFree86 for real use. With current hardware, you should easily be able to get up to 1024x768 pixels.

But before you start to write a XF86Config file yourself, try one of the configuration programs that are available. In many cases, you can avoid going through the hassle that will be described on the next pages. Some programs that may help you are:

XF86Setup

This graphical configuration program is provided by the XFree86 team themselves. It starts up a VGA X server with 16 colors (which is quite sure to run on just about any display hardware) and then lets you select your graphics board, your monitor type, your mouse type, and other options. At the end, it tries to start up a server as configured, and if you are satisfied, it offers to write the configuration file for you. We have found this program to be very useful and reliable in many cases.

ConfigXF86

This is a text-based program that asks you a number of questions and then generates a configuration file from your answers. It is by no means as comfortable to use as XF86Setup (and is slightly outdated), but it has been reported to work in cases where XF86Setup has failed.

Distribution-specific configuration tools

Some distributions also have their own configuration tools. For example, SuSE has SaX and Red Hat has Xconfigurator. Caldera OpenLinux now even configures the mouse and the video board automatically during installation.

If one of these tools is able to configure your X server for you, you should use it and save yourself a lot of trouble. However, if all of the tools fail or if you really want to fine-tune your X server, you will have to know how to edit the XF86Config file yourself.

In addition to the information here, you should read the following documentation:

  • The XFree86 documentation in /usr/X11R6/lib/X11/doc (contained within the Xdoc package). You should especially see the file README.Config, which is an XFree86 configuration tutorial.

  • The README file for your video chipset, if one exists, in the directory /usr/X11R6/lib/X11/doc. These README files have names such as README.Cirrus and README.S3.

  • The manual page for XFree86.

  • The manual page for XF86Config.

  • The manual page for the particular server that you are using (such as XF86_SVGA or XF86_S3).

The main configuration file you need to create is /usr/X11R6/lib/X11/XF86Config (some distributions put this in /etc/XF86Config or /etc/X11 instead). This file contains information on your mouse, video card parameters, and so on. The file XF86Config.eg is provided with the XFree86 distribution as an example. Copy this file to XF86Config and edit it as a starting point.

The XF86Config manual page explains the format of this file in detail. Read this manual page now if you have not done so already.

We are going to present a sample XF86Config file, piece by piece. This file may not look exactly like the sample file included in the XFree86 distribution, but the structure is the same.

The XF86Config file format may change with each version of XFree86; this information is only valid for XFree86 Version 3.3.3.1.

Also, you should not simply copy the configuration file listed here to your own system and attempt to use it. Attempting to use a configuration file that doesn't correspond to your hardware could drive the monitor at a frequency that is too high for it; there have been reports of monitors (especially fixed-frequency monitors) being damaged or destroyed by using an incorrectly configured XF86Config file. The bottom line is this: make absolutely sure your XF86Config file corresponds to your hardware before you attempt to use it.

Each section of the XF86Config file is surrounded by the pair of lines Section " section-name"...EndSection. The first part of the XF86Config file is Files, which looks like this:

Section "Files"
    RgbPath     "/usr/X11R6/lib/X11/rgb"
    FontPath    "/usr/X11R6/lib/X11/fonts/misc/"
    FontPath    "/usr/X11R6/lib/X11/fonts/75dpi/"
EndSection

The RgbPath line sets the path to the X11R6 RGB color database, and each FontPath line sets the path to a directory containing X11 fonts. In general, you shouldn't have to modify these lines; just be sure there is a FontPath entry for each font type you have installed (i.e., for each directory in /usr/X11R6/lib/X11/fonts). If you add the string :unscaled to a FontPath, the fonts from this directory will not be scaled. This is often an improvement because fonts that are vastly scaled look ugly. In addition to FontPath and RgbPath, you can also add a ModulePath to this section, to point to a directory with dynamically loaded modules. Those modules are currently used for some special input devices, as well as the PEX and XIE extensions.

The next section is ServerFlags, which specifies several global flags for the server. In general this section is empty:

Section "ServerFlags"
# Uncomment this to cause a core dump at the spot where a signal is 
# received.  This may leave the console in an unusable state, but may
# provide a better stack trace in the core dump to aid in debugging
#    NoTrapSignals
# Uncomment this to disable the <Crtl><Alt><BS> server abort sequence
#    DontZap
EndSection
Here, we have all lines within the section commented out.

The next section is Keyboard:

Section "Keyboard"
    Protocol    "Standard"
    AutoRepeat  500 5
    ServerNumLock
EndSection
Other options are available as well: see the XF86Config file if you wish to modify the keyboard configuration. The previous example should work for most systems with U.S. keyboards. If you have another keyboard, you will have to add additional lines. For example, the following works for a standard German keyboard:

XkbRules	"xfree86"
XkbModel	"pc102"
XkbLayout	"de"
XkbVariants	""
XkbOptions	""

The next section is Pointer, which specifies parameters for the mouse device:

Section "Pointer"

    Protocol    "MouseSystems"
    Device      "/dev/mouse"

# Baudrate and SampleRate are only for some Logitech mice
#    BaudRate   9600
#    SampleRate 150

# Emulate3Buttons is an option for 2-button Microsoft mice
#    Emulate3Buttons

# ChordMiddle is an option for some 3-button Logitech mice
#    ChordMiddle

EndSection
The only options you should concern yourself with now are Protocol and Device. Protocol specifies the mouse protocol your mouse uses (not the make or brand of mouse). Valid types for Protocol (under Linux - there are other options available for other operating systems) are:
  • BusMouse

  • Logitech

  • Microsoft

  • MMSeries

  • Mouseman

  • MouseManPlusPS/2

  • MouseSystems

  • PS/2

  • MMHitTab

  • GlidePoint

  • GlidePointPS/2

  • IntelliMouse

  • IMPS/2

  • NetMousePS/2

  • NetScrollPS/2

  • SysMouse

  • ThinkingMouse

  • ThinkingMousePS/2

  • Xqueue

BusMouse should be used for the Logitech busmouse. Note that older Logitech mice that are not bus mice should use Logitech, but newer Logitech mice that are not bus mice use either the Microsoft or the Mouseman protocol. This is a case where the protocol doesn't necessarily have anything to do with the make of the mouse.

If you have a modern serial mouse, you could also try to specify Auto, which will try to autoselect a mouse driver.

It is easy to check whether you have selected the correct mouse driver once you have started up X; when you move your mouse, the mouse pointer on the screen should follow this movement. If it does this, your setup is very likely to be correct. If it doesn't, try another driver, and also check whether the device you specified is correct.

Device specifies the device file where the mouse can be accessed. On most Linux systems, this is /dev/mouse. /dev/mouse is usually a link to the appropriate serial port (such as /dev/ttyS0) for serial mice or to the appropriate busmouse device for busmice. At any rate, be sure that the device file listed in Device exists.

The next section is Monitor, which specifies the characteristics of your monitor. As with other sections in the XF86Config file, there may be more than one Monitor section. This is useful if you have multiple monitors connected to a system, or use the same XF86Config file under multiple hardware configurations. In general though, you will need only a single Monitor section:

Section "Monitor"

    Identifier  "CTX 5468 NI"

    # These values are for a CTX 5468NI only! Don't attempt to use 
    # them with your monitor (unless you have this model)

    HorizSync    30-38,47-50
    VertRefresh  50-90

    # Modes: Name      dotclock  horiz                vert 

    ModeLine "640x480"  25       640 664 760 800      480 491 493 525
    ModeLine "800x600"  36       800 824 896 1024     600 601 603 625
    ModeLine "1024x768" 65       1024 1088 1200 1328  768 783 789 818

EndSection

The Identifier line is used to give an arbitrary name to the Monitor entry. This can be any string; you will use it to refer to the Monitor entry later in the XF86Config file.

HorizSync specifies the valid horizontal sync frequencies for your monitor in kHz. If you have a multisync monitor, this can be a range of values (or several comma-separated ranges), as seen in the Monitor section. If you have a fixed-frequency monitor, this will be a list of discrete values, such as:

    HorizSync    31.5, 35.2, 37.9, 35.5, 48.95
Your monitor manual should list these values in the technical specifications section. If you do not have this information, you should contact either the manufacturer or the vendor of your monitor to obtain it. There are other sources of information, as well; they are listed later.

You should be careful with those settings. While the settings VertRefresh and HorizSync (described next) help to make sure that your monitor will not be destroyed by wrong settings, you won't be very happy with your X setup if you get these values wrong. Unsteady pictures, flickering, or just plain snow can result.

VertRefresh specifies the valid vertical refresh rates (or vertical synchronization frequencies) for your monitor in Hz. Like HorizSync, this can be a range or a list of discrete values; your monitor manual should list them.

HorizSync and VertRefresh are used only to double-check that the monitor resolutions you specify are in valid ranges. This reduces the chance that you will damage your monitor by attempting to drive it at a frequency for which it wasn't designed.

The ModeLine directive is used to specify a single resolution mode for your monitor. The format of ModeLine is:

ModeLine 

name 

dot-clock 

horiz-values 

vert-values
name is an arbitrary string, which you will use to refer to the resolution mode later in the file. dot-clock is the driving clock frequency or dot clock associated with the resolution mode. A dot clock is usually specified in MHz and is the rate at which the video card must send pixels to the monitor at this resolution. horiz-values and vert-values are four numbers each; they specify when the electron gun of the monitor should fire and when the horizontal and vertical sync pulses fire during a sweep across the screen.

How can you determine the ModeLine values for your monitor? The file VideoModes.doc, included with the XFree86 distribution, describes in detail how to determine these values for each resolution mode your monitor supports. First of all, clock must correspond to one of the dot-clock values that your video card can produce. Later in the XF86Config file, you will specify these clocks; you can use only video modes that have a clock value supported by your video card.

Two files included in the XFree86 distribution may include ModeLine data for your monitor. These files are modeDB.txt and Monitors, both of which are found in /usr/X11R6/lib/X11/doc.

You should start with ModeLine values for the VESA standard monitor timings, which most monitors support. modeDB.txt includes timing values for VESA standard resolutions. In that file, you will see entries such as:

# 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
This is a VESA standard timing for a 640x480 video mode. It uses a dot clock of 25.175, which your video card must support to use this mode (more on this later).

To include this entry in the XF86Config file, you'd use the line:

ModeLine "640x480" 25.175  640 664 760 800  480 491 493 525

Note that the name argument to ModeLine (in this case "640x480") is an arbitrary string; the convention is to name the mode after the resolution, but name can technically be anything descriptive that describes the mode to you.

For each ModeLine used, the server checks that the specifications for the mode fall within the range of values specified with HorizSync and VertRefresh. If they do not, the server will complain when you attempt to start up X (more on this later).

If the VESA standard timings do not work for you (you'll know after trying to use them later when the screen is unsteady, flickers, or shows snow), the files modeDB.txt and Monitors include specific mode values for many monitor types. You can create ModeLine entries from the values found in those two files as well. Be sure to use values only for your specific model. Note that many 14- and 15-inch monitors cannot support higher-resolution modes and often can support resolutions of 1024x768 at low dot clocks only or not at all. This means that if you can't find high-resolution modes for your monitor in these files, your monitor probably does not support those resolution modes.

If you are completely at a loss, and can't find working ModeLine values for your monitor, you can follow the instructions in the VideoModes.doc file included in the XFree86 distribution to generate ModeLine values from the specifications listed in your monitor's manual. While your mileage will certainly vary when attempting to generate ModeLine values by hand, this is a good place to look if you can't find the values you need. VideoModes.doc also describes the format of the ModeLine directive and other aspects of the XFree86 server in gory detail.

Lastly, if you do obtain ModeLine values that are almost, but not quite, right, it may be possible to simply modify the values slightly to obtain the desired result. For example, if while running XFree86 the image on the monitor shifts slightly or seems to "roll," you can follow the instructions in the VideoModes.doc file to try to fix these values. Also, be sure to check the knobs and controls on the monitor itself! In many cases it is necessary to change the horizontal or vertical size of the display after starting up XFree86 in order for the image to be centered and of the appropriate size. Having these controls on the front of the monitor can certainly make life easier. Another option is to use the program xvidtune (see the manual page for how to use it) that can help you to get all the numbers for the modeline, lets you try your changes, and even allows you to undo them if you did something wrong.

You shouldn't use monitor timing values or ModeLine values for monitors other than the model you own. If you attempt to drive the monitor at a frequency for which it was not designed, you can damage or even destroy it.

The next section of the XF86Config file is Device, which specifies parameters for your video card. Here is an example:

Section "Device" 
        Identifier "#9 GXE 64"

        # Nothing yet; we fill in these values later.

EndSection

This section defines properties for a particular video card. Identifier is an arbitrary string describing the card; you will use this string to refer to the card later.

Initially, you don't need to include anything in the Device section, except for Identifier. This is because we will be using the X server itself to probe for the properties of the video card and entering them into the Device section later. The XFree86 server is capable of probing for the video-card chipset, clocks, RAMDAC (one of the chips on the video board), and amount of video RAM on the board.

Before we do this, however, we need to finish writing the XF86Config file. The next section is Screen, which specifies the monitor/video card combination to use for a particular server:

 Section "Screen"
     Driver     "Accel"
     Device     "#9 GXE 64"
     Monitor    "CTX 5468 NI"
     Subsection "Display"
         Depth      16
         Modes      "1024x768" "800x600" "640x480"
         ViewPort   0 0
         Virtual    1024 768
     EndSubsection
 EndSection

The Driver line specifies the X server you will be using. The possible values for Driver are:

Accel

For the XF86_S3, XF86_S3V, XF86_Mach64, XF86_Mach32, XF86_Mach8, XF86_8514, XF86_P9000, XF86_AGX, XF86_I128, XF86_TGA, and XF86_W32 servers

SVGA

For the XF86_SVGA server

VGA16

For the XF86_VGA16 server

VGA2

For the XF86_Mono server

Mono

For the non-VGA monochrome drivers in the XF86_Mono and XF86_VGA16 servers

Be sure that /usr/X11R6/bin/X is a symbolic link to your server; you might have to create this link yourself if you install XFree86 for the first time. Make a link with a command like the following:

ln -s /usr/X11R6/bin/XF86_SVGA /usr/X11R6/bin/X

Of course, you have to replace the first pathname with that of another server binary if you don't use the SVGA server.

The Device line specifies the Identifier from the Device section. Earlier, we created a Device section with the line:

Identifier "#9 GXE 64"
Therefore, we use "#9 GXE 64" on the Device line here.

Similarly, the Monitor line specifies the name of the Monitor section to be used with this server. Here, "CTX 5468 NI" is the Identifier used in the Monitor section described earlier.

Subsection "Display" defines several properties of the XFree86 server corresponding to your monitor/video-card combination. The XF86Config file describes all these options in detail; most of them are icing on the cake and are not necessary to get the system working.

The options you should know about are:

DefaultColorDepth

Specifies the color depth to use in case the X server supports several color depths.

Depth

Defines the number of color planes - the number of bits per pixel. Usually, Depth is set to 8. For the VGA16 server, you would use a depth of 4, and for the monochrome server a depth of 1. If you are using an accelerated video card or one of the better SVGA cards with enough memory to support more bits per pixel, you can set Depth to 16, 24, or 32. If you have problems with depths higher than 8, set it back to 8 and attempt to debug the problem later.

Modes

Lists of video mode names that have been defined using the ModeLine directive in the Monitor section. In the previous section, we used ModeLines named "1024x768", "800x600", and "640x480", so we use a Modes line of:

        Modes    "1024x768" "800x600" "640x480"
The first mode listed on this line will be the default when XFree86 starts up. After XFree86 is running, you can switch between the modes listed here using Ctrl-Alt with the plus or minus on the numeric keypad.

It might be best, when initially configuring XFree86, to use lower resolution video modes, such as 640x480, which tend to work on most systems. Once you have the basic configuration working, you can modify XF86Config to support higher resolutions.

Virtual

Sets the virtual desktop size. XFree86 has the ability to use any additional memory on your video card to extend the size of your desktop. When you move the mouse pointer to the edge of the display, the desktop scrolls, bringing the additional space into view. Therefore, even if you are running at a lower video resolution, such as 800x600, you can set Virtual to the total resolution your video card can support. A 1 MB video card can support 1024x768 at a depth of 8 bits per pixel, while a 2 MB card can support 1280x1024 at depth 8, or 1024x768 at depth 16. Of course, the entire area will not be visible at once, but it can still be used.

The Virtual option is a nice way to utilize the memory of your video card, but it is rather limited. If you want to use a true virtual desktop, we suggest using a window manager like kwm or fvwm2 instead. Both allow you to have rather large virtual desktops (implemented by such software techniques as hiding windows instead of actually storing the entire desktop in video memory at once). See the next chapter for more details about this; most Linux systems use kwm, which is a part of the K Development Environment, by default.

ViewPort

If you are using the Virtual option described earlier, ViewPort sets the coordinates of the upper-left corner of the virtual desktop when XFree86 starts up. ViewPort 0 0 is often used, putting the screen at the top left corner of the desktop; if this is unspecified, the desktop is centered on the virtual desktop display (which may be undesirable to you).

Many other options for this section exist; see the XF86Config manual page for a complete description. In practice, these other options are not necessary to get XFree86 working initially.

10.5 Filling in Video Card Information

Your XF86Config file is now ready to go with the exception of complete information on the video card. What we're going to do is use the X server to probe for the rest of this information and fill it into XF86Config.

Instead of probing for this information with the X server, you can find the XF86Config values for many cards in the files modeDB.txt, AccelCards, and Devices. These files are all in /usr/X11R6/lib/X11/doc. In addition, there are various README files for certain chipsets. You should look in these files for information on your video card, and use that information (the clock values, chipset type, and any options) in the XF86Config file. Unfortunately, some manufacturers put out a graphics board with a new chipset without changing the board's name. If any information is missing, you can probe for it as described here.

In these examples, we will demonstrate configuration for a #9 GXE 64 video card, which uses the XF86_S3 chipset. This card happens to be the one that used by one of the authors, but the discussion here applies to any video card.

The first thing to do is to determine the video chipset used on the card. Running SuperProbe (found in /usr/X11R6/bin) will tell you this information, but you need to know the chipset name as it is known to the X server.

To do this, run the command:

# X -showconfig
This lists the chipset names known to your X server. (The manual pages for each X server list these as well.) For example, with the accelerated XF86_S3 server, we obtain:
XFree86 Version 3.3.3.1 / X Window System
(protocol Version 11, revision 0, vendor release 6000)
Release Date: March 2 1998
        If the server is older than 6-12 months, or if your card is newer
        than the above date, look for a newer version before reporting
        problems.  (see https://www.XFree86.Org/FAQ)
Operating System: Linux 2.0.33 i686 [ELF]
Configured drivers:
  S3: accelerated server for S3 graphics adaptors (Patchlevel 0)
      newmmio, mmio_928, s3_generic           

The valid chipset names for this server are newmmio, mmio_928, and s3_generic. The XF86_S3 manual page describes these chipsets and which video cards use them. In the case of the #9 GXE 64 video card, mmio_928 is appropriate.

If you don't know which chipset to use, the X server can probe it for you. To do this, run the command:

# X -probeonly > /tmp/x.out 2>&1
if you use bash as your shell. If you use csh, try:
% X -probeonly >& /tmp/x.out

You should run this command while the system is unloaded, that is, while no other activity is occurring on the system. This command also probes for your video-card dot clocks (as seen later), and system load can throw off this calculation.

The output from this command (in /tmp/x.out) should contain lines such as the following:

XFree86 Version 3.3.3.1 / X Window System 
(protocol Version 11, revision 0, vendor release 6000) 
Operating System: Linux  

Configured drivers: 
  S3: accelerated server for S3 graphics adaptors (Patchlevel 0) 
      newmmio, mmio_928, s3_generic 
         .
         .
         .
(--) S3: card type: 386/486 localbus 
(--) S3: chipset:   864 rev. 0 
(--) S3: chipset driver: mmio_928 
Here, we see that the three valid chipsets for this server (XF86_S3) are newmmio, mmio_928 and s3_generic. The server probed for and found a video card using the mmio_928 chipset driver.

In the Device section of the XF86Config file, add a Chipset line containing the name of the chipset you determined earlier. For example:

Section "Device" 
        # We already had Identifier here...
        Identifier "#9 GXE 64"  
        # Add this line:
        Chipset "mmio_928"
EndSection

Now we need to determine which dot clocks are made available by the video card. First, you should look into the files (modeDB.txt and so forth) mentioned at the beginning of this section and see if your card's clocks are listed there. The dot clocks will usually be a list of 8 or 16 values, all of which are in MHz. For example, when looking at mode-DB.txt, we see an entry for the Cardinal ET4000 video board, which looks like this:

# chip    RAM   virtual   clocks   default-mode  flags
 ET4000   1024  1024 768   25  28  38  36  40  45  32   0  "1024x768"    
As we can see, the dot clocks for this card are 25, 28, 38, 36, 40, 45, 32, and 0 MHz.

In the Devices section of the XF86Config file, you should add a Clocks line containing the list of dot clocks for your card. For example, for the clocks in this example, we would add the line:

         Clocks 25 28 38 36 40 45 32 0
to the Devices section of the file, after Chipset. The order of the clocks is important! Don't re-sort the list of clocks or remove duplicates.

If you cannot find the dot clocks associated with your card, the X server can probe for these as well. Using the X -probeonly command described earlier, the output should contain lines that look like the following:

(--) S3: clocks:  25.18  28.32  38.02  36.15  40.33  45.32  32.00  00.00
We could then add a Clocks line containing all of these values, as printed. You can use more than one Clocks line in XF86Config if all the values (sometimes there are more than eight clock values printed) don't fit onto one line. Again, be sure to keep the list of clocks in the order that they are printed.

Be sure there is no Clocks line (or that it is commented out) in the Devices section of the file when using X -probeonly to probe for the clocks. If there is a Clocks line present, the server will not probe for the clocks; it will use the values given in XF86Config.

Note that some accelerated video boards use a programmable clock chip. (See the XF86_Accel manual page for details; this generally applies to S3, AGX, and XGA-2 boards.) This chip essentially allows the X server to tell the card which dot clocks to use. If this is the case, you may not find a list of dot clocks for the card in any of the files mentioned earlier. Or the list of dot clocks printed when using X -probeonly will contain only one or two discrete clock values, with the rest being duplicates or zero.

For boards that use a programmable clock chip, you would use a ClockChip line, instead of a Clocks line, in your XF86Config file. ClockChip gives the name of the clock chip as used by the video card. But in most cases, the X server can detect your clock chip automatically and find the correct entry itself.

If you are not so lucky, the manual pages for each server describe the possible values for your server. For example, in the file README.S3, we see that several S3-864 video cards use an ICD2061A clock chip, and that we should use the line:

ClockChip "icd2061a" 
instead of Clocks in the XF86Config file. As with Clocks, this line should go in the Devices section after Chipset.

Similarly, some accelerated cards require you to specify the RAMDAC chip type in the XF86Config file, using a Ramdac line. The XF86_Accel manual page describes this option. Usually, the X server will correctly probe for the RAMDAC.

Some video card types require you to specify several options in the Devices section of XF86Config. These options will be described in the manual page for your server, as well as in the various files (such as README.cirrus or README.S3). These options are enabled using the Option line. For example, the #9 GXE 64 card requires the option:

Option "number_nine" 
Usually, the X server works without these options, but they are necessary to obtain the best performance. There are too many such options to list here, and they each depend on the particular video card being used. If you must use one of these options, fear not: the X server manual pages and various files in /usr/X11R6/lib/X11/doc will tell you what they are.

So when you're finished, you should end up with a Devices section that looks something like this:

Section "Device"  
        # Device section for the #9 GXE 64 only !
        Identifier "#9 GXE 64" 
        Chipset "mmio_928" 
        ClockChip "icd2061a" 
        Option "number_nine" 
EndSection 
This Device entry is valid only for a particular video card, the #9 GXE 64; it is given here only as an example. Most video cards require a Clocks line, instead of ClockChip.

There are other options you can include in the Devices entry. Check the X server manual pages for the gritty details, but the explanation in this section should suffice for most systems.

10.6 Running XFree86

With your XF86Config file configured, you're ready to fire up the X server and give it a spin. First, be sure that /usr/X11R6/bin is on your path.

The command to start up XFree86 is:

startx
This is a frontend to xinit (in case you're used to using xinit on other Unix systems). You can still use xinit, which gives you precise control about what exactly is started but requires you to start all needed programs manually.

This command starts the X server and runs the commands found in the file .xinitrc in your home directory. .xinitrc is just a shell script containing X clients to run. If this file does not exist, the system default /usr/X11R6/lib/X11/xinit/xinitrc will be used.

You can change the initial display when starting up the X Window System by providing a different .xinitrc in your home directory. The next chapter tells you what you can put in this file.

If you are new to the X Window System environment, we strongly suggest picking up a book such as The X Window System User's Guide by Valerie Quercia and Tim O'Reilly.

10.7 Running Into Trouble

Often, something will not be quite right when you initially fire up the X server. This is almost always caused by a problem in your XF86Config file. Usually, the monitor timing values are off or the video-card dot clocks are set incorrectly. If your display seems to roll, or the edges are fuzzy, this is a clear indication that the monitor timing values or dot clocks are wrong. Also be sure you are correctly specifying your video card chipset, as well as other options for the Device section of XF86Config. Be absolutely certain that you are using the right X server and that /usr/X11R6/bin/X is a symbolic link to this server.

If all else fails, try to start X "bare"; that is, use a command such as:

X > /tmp/x.out 2>&1 
You can then kill the X server (using the Ctrl-Alt-Backspace key combination) and examine the contents of /tmp/x.out. The X server reports any warnings or errors - for example, if your video card doesn't have a dot clock corresponding to a mode supported by your monitor. This output can be very helpful in diagnosing all kinds of problems. Examine it closely if your X server does not start up at all, does not provide the resolutions you wanted, or shows a flaky, snowy, or otherwise insufficient picture. Even if everything works to your satisfaction, you might want to check this file for interesting information that the X server has found out about your hardware. The lines starting with (**) contain data that you provided yourself in the configuration file, while lines starting with (--) contain data that the X server has found out itself.

The file VideoModes.doc included in the XFree86 distribution contains many hints for tweaking the values in your XF86Config file.

Remember that you can use Ctrl-Alt with the plus or minus on the numeric keypad to switch between the video modes listed on the Modes line of the Screen section of XF86Config. If the highest-resolution mode doesn't look right, try switching to lower resolutions. This lets you know, at least, that the configurations for those lower resolutions in your X configuration are working correctly.

Also, check the vertical and horizontal size/hold knobs on your monitor. In many cases it is necessary to adjust these when starting up X. For example, if the display seems to be shifted slightly to one side, you can usually correct this using the monitor controls.

The Usenet newsgroup comp.windows.x.i386unix is devoted to discussions about XFree86. It might be a good idea to watch that newsgroup for postings relating to your video configuration; you might run across someone with the same problems as your own. If this fails, please contact your Linux distributor; their support staff should be able to help you as well.


iDevJobs.com - Jobs for Professional Developers

Contribute to IDR:

To contribute an article to IDR, a click here.

To contact us at IDevResource.com, use our feedback form, or email us.

To comment on the site contact our webmaster.

Promoted by CyberSavvy UK - website promotion experts

All content © Copyright 2000 IDevResource.com, Disclaimer notice

WTL Architecture by Richard Grimes

Code Project

Visit the IDR Forums

Visit the IDR Bookstore!

Join the Developers Webring