Configuration Infrastructure

Introduction

Since 9th October 2003 the new configuration infrastructure is part of the main trunk of the DRI CVS repository. It introduces a consistent mechanism for configuring all DRI drivers using an XML-based configuration file. It further provides an interface for configuration GUIs to find out about the ConfigurationOptions of installed drivers. Option descriptions are available in multiple languages. The first GUI configuration tool that uses the new infrastructure is DriConf.

DriConf is by far the easiest and most user-friendly way to edit the configuration. On the page ConfigurationOptions you find more detailed descriptions of common configuration options. If instead you prefer to edit the configuration file with a text editor, then read on. ConfigurationForDevelopers describes how to make drivers configurable and how to add new options to drivers. For those interested in the technical details there is a design document.

System-wide and per-user configuration files

There is a system-wide configuration file /etc/drirc that applies to all users. Those settings can be overridden by a user's configuration file $HOME/.drirc. Both files have exactly the same format.

Example for a single-headed setup

Let's start with an example of a configuration file for a single-headed setup, where you have only one graphics card and one monitor installed.

<driconf>
   <device screen="0" driver="radeon">
      <application name="all">
         <!-- Always synchronize with vertical refresh to avoid tearing -->
         <option name="vblank_mode" value="3"/>
      </application>
      <application name="glxgears" executable="glxgears">
         <!-- glxgears should not synchronize with vertical refresh, show full fps -->
         <option name="vblank_mode" value="0"/>
      </application>
      <application name="tuxracer" executable="tuxracer">
         <!-- Tuxrace has some artifacts with hardware TCL -->
         <option name="tcl_mode" value="0"/>
      </application>
   </device>
</driconf>

Comments start with . Indentation is optional but makes the configuration file more readable. Each configuration file starts with and ends with .

Devices

Between the and tags there can be a device section for each graphics device you have installed in your system. In the example there is only one device section. The opening tag contains two attributes "screen" and "driver". They are used to identify the device that this section applies to. In most cases only one of them should be necessary but specifying both doesn't hurt. "screen" gives the X screen number. On a single-headed display this is always 0. "driver" specifies the name of the 3D driver. At the time of this writing the following drivers support the configuration infrastructure:

mga (Matrox cards)
r128 (ATI Rage 128 and some Mobility chips)
radeon (ATI Radeon 7000, 7200, 7500 and some Mobility chips)
r200 (ATI Radeon 8500, 9000, 9200) If you are not sure which driver is the correct one for you, then you can find out with xdriinfo. If you type xdriinfo in the shell, you will get a list of all direct rendering capable screens with their drivers.

Applications

In each device section there can be any number of application sections that contain the configuration of different applications. The opening tag can contain the attributes "name" and "executable". The name is merely a descriptive string. If no executable attribute is present then the section applies to all applications. Otherwise the section only applies to the specified application.

Caution: The executable that you specify in the executable attribute may differ from what you type in the shell. For instance the command q3demo is a shell script. The actual executable that runs the game is called q3demo.x86.

Options

Options are specified as empty element tags. This is indicated by the slash before the closing bracket. They have two attributes, "name" and "value". Their meaning should be obvious. The set of available options, their types and ranges of valid values depend on the driver and are subject to changes. Hopefully the most common change will be the addition of new options. But sometimes options may be removed or replaced by different options with different semantics.

An up-to-date description of available options can be obtained with the program xdriinfo, which is included in the DRI CVS repository and in recent binary snapshots. In the shell type

xdriinfo options <screen number or driver name>

You will see a rather long XML document that formally describes all available options and also includes verbal descriptions in multiple languages. This format is not exactly easily readable. Its main purpose is to be automatically processed by configuration GUIs. But it may also serve as a reference to the "power user".