Input device configuration

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Document xorg.conf.d for F13, WIP)
(more F13 documentation, that should be it for a start)
Line 63: Line 63:
 
Beginning with Fedora 13, the X server uses udev instead of HAL for input device detection and xorg.conf InputClass configuration. Thus, any HAL-specific configuration is deprecated and users with custom configurations in fdi files need to change these configurations to the new format. The basics of the new configuration mechanism in X is outlined below. Generally, users should not (need to) configure udev or add udev rules to enable device detection in X. While supported, users are discouraged of putting X.org-specific configuration into udev rules files.
 
Beginning with Fedora 13, the X server uses udev instead of HAL for input device detection and xorg.conf InputClass configuration. Thus, any HAL-specific configuration is deprecated and users with custom configurations in fdi files need to change these configurations to the new format. The basics of the new configuration mechanism in X is outlined below. Generally, users should not (need to) configure udev or add udev rules to enable device detection in X. While supported, users are discouraged of putting X.org-specific configuration into udev rules files.
  
 +
== xorg.conf.d ==
 
Beginning with X server version 1.8, the X server supports two new configuration mechanism. The first is support for the configuration directory /etc/xorg.conf.d. Files with the suffix .conf in this directory are parsed by the X server on startup and treated like a part of the traditional xorg.conf configuration file. Files in this directory may contain one or more sections, the X server essentially treats it like one giant xorg.conf file. Files in the /etc/xorg.conf.d directory are parsed in-order ''after the xorg.conf has been parsed fully'' and precedence is given to the first configuration entry where applicable. Users are encouraged to put custom configuration into /etc/xorg.conf and leave the directory for snippets provided by the distribution.
 
Beginning with X server version 1.8, the X server supports two new configuration mechanism. The first is support for the configuration directory /etc/xorg.conf.d. Files with the suffix .conf in this directory are parsed by the X server on startup and treated like a part of the traditional xorg.conf configuration file. Files in this directory may contain one or more sections, the X server essentially treats it like one giant xorg.conf file. Files in the /etc/xorg.conf.d directory are parsed in-order ''after the xorg.conf has been parsed fully'' and precedence is given to the first configuration entry where applicable. Users are encouraged to put custom configuration into /etc/xorg.conf and leave the directory for snippets provided by the distribution.
  
  
 +
== InputClasses ==
 +
InputClasses are the X.org equivalent to HAL's fdi files previously used for configuration. Unlike an InputDevice section that may only apply to a single device, an InputClass section may apply to multiple devices, including hotplugged ones. An example InputClass section is provided below:
 +
 +
<pre>
 +
Section "InputClass"
 +
  Identifier      "touchpad generic class"
 +
  MatchIsTouchpad "on"
 +
  Driver          "synaptics"
 +
EndSection
 +
</pre>
 +
 +
If this snippet is present in the xorg.conf or xorg.conf.d, any touchpad present in the system is assigned the synaptics driver. Note that due to precedence order (xorg.conf first, then alphanumeric sorting of xorg.conf.d snippets) the Driver setting is only applied to devices that do not yet have a driver setting. Hence, the same section specified by the user in the xorg.conf with a Driver "evdev" line would force the evdev driver on all touchpads.
 +
 +
The match options specify which devices a section may apply to. To match a device, all match lines must apply. The following match lines are supported (with examples):
 +
* MatchIsPointer, MatchIsKeyboard, MatchIsTouchpad, MatchIsTouchscreen, MatchIsJoystick - boolean options to apply to a group of devices.
 +
* MatchProduct "foo|bar": match any device with a product name containing either "foo" or "bar"
 +
* MatchVendor "foo|bar|baz": match any device with a vendor string containing either "foo", "bar", or "baz"
 +
* MatchDevicePath "/dev/input/event*": match any device with a device path matching the given patch (see fnmatch(3) for the allowed pattern)
 +
* MatchTag "foo|bar": match any device with a tag of either "foo" or "bar". tags may be assigned by the config backend - udev in our case - to label devices that need quirks or special configuration.
 +
 +
An example section for user-specific configuration is:
 +
 +
<pre>
 +
Section "InputClass"
 +
  Identifier    "lasermouse slowdown"
 +
  MatchIsPointer "on"
 +
  MatchProduct  "Lasermouse"
 +
  MatchVendor    "LaserMouse Inc."
 +
  Option        "ConstantDeceleration" 20
 +
EndSection
 +
</pre>
 +
 +
This section would match a pointer device containing "Lasermouse" from "Lasermouse Inc." and apply a constant deceleration of 20 on this device - slowing it down by factor 20.
  
  
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Revision as of 00:51, 12 February 2010

Contents

Introduction

The X servers provided in Fedora 9 and later use HAL to retrieve the list of input devices. Whenever the X server is started, it asks HAL for the list of input devices and adds each of them with the respective driver. Whenever a new input device is plugged in or an existing input device is removed, HAL notifies the X server about the presence or removal of this device. Because of this notification system, some devices configured in the xorg.conf are ignored by the X server (all devices using the 'mouse', 'kbd' or 'vmmouse' driver).

In addition to signaling the presence of the new device, HAL also provides the X server with a number of options for each device. Most notably, this includes the driver the server should load and the device file to open. It also allows for additional, user-specific configuration options.


Device configuration

Fedora provides a list of default configurations in /usr/share/hal/fdi/policies/10osvendor/10-x11-input.fdi and some driver-specific configurations in e.g. /usr/share/hal/fdi/policies/20thirdparty/10-synaptics.fdi. Do not edit these files directly, as they will be overwritten in the next update. Instead, copy the file into /etc/hal/fdi/policy first and then edit as appropriate. For example, the fdi for a synaptics touchpad may look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<deviceinfo version="0.2">
  <device>
    <match key="info.capabilities" contains="input.touchpad">
        <merge key="input.x11_driver" type="string">synaptics</merge>
        <merge key="input.x11_options.TapButton1" type="string">1</merge>
    </match>
  </device>
</deviceinfo>

The above XML file defines the following: If the device is a touchpad (HAL assigns this capability automatically), then load the synaptics X11 driver for this device. The key input.x11_driver is interpreted by the server. The second merge command states that the option TapButton1 with a value of '1' should be passed to the driver. Any input.x11_options key is interpreted by the driver and is equivalent to the traditional form of Option "Option name" "Option value" in the xorg.conf. The man page of the respective driver lists the available options. Note that any input.x11_options key must have the type 'string' even if it denotes a number. Other types will be ignored by the server.

Merge commands are additive. For example, the fdi file provided by the xorg-x11-drv-synaptics package supplies the input.x11_driver key. User-specific configuration does not need to specify this key again and instead should only provide local configuration options (such as the TapButton1 setting above).

To remove an existing key, the following syntax may be used:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <deviceinfo version="0.2">
    <device>
      <match key="input.product" contains="Random String">
         <remove key="input.x11_driver"></remove>
      </match>
     </device>
  </deviceinfo>

This snipped removes the input.x11_driver key from all devices that include the string "Random String". As said above, input.x11_driver is a special key and removing it prevents the X server from adding this device. The same syntax may be used to remove other options.

Reviewing configuration changes

In the extreme case, a misconfiguration of input drivers may result in an X server with no input devices. It is advisable that changes to the fdi files are reviewed before restarting the server to ensure that at least some devices are available.

After editing the fdi files, the HAL daemon can be restarted with service haldaemon restart. Once the restart is successful, lshal may be used to list all devices and their configurations. As a general rule, at least one keyboard device should have input.x11_driver set to 'evdev' to allow keyboard input if all other configurations fail.


Disabling the use of HAL

Some users wish to disable the use of HAL. The X server provides two options to achieve this:

  • Option "AutoAddDevices" "false"

If this option is disabled, then no devices will be added from HAL events. Note that if this option is disabled, AllowEmptyInput is automatically disabled too unless explicitly enabled the user.

  • Option "AllowEmptyInput" "false"

If AllowEmptyInput is false, the server checks the xorg.conf for core devices (Option "CorePointer" and Option "CoreKeyboard"). If none are present and referenced in the ServerLayout section, the server automatically adds the first mouse and keyboard device in the xorg.conf or (if neither are present) the hard-coded default input devices. Disabling AllowEmptyInput also forces the server to honor devices using the 'mouse', 'kbd' and 'vmmouse' drivers (these devices are ignored by default).

In most cases, simply disabling AutoAddDevices is the correct way to disable the use of HAL. Note that if AllowEmptyInput is off and AutoAddDevices is on, then devices may be added multiple times (once as specified in the xorg.conf, and once as listed by HAL). This leads to duplicate button presses and triplicate key presses.

Fedora 13

The following configuration guide is work-in-progress. Do not follow it, the X server packages in F-13 do not support the following configuration yet.

Beginning with Fedora 13, the X server uses udev instead of HAL for input device detection and xorg.conf InputClass configuration. Thus, any HAL-specific configuration is deprecated and users with custom configurations in fdi files need to change these configurations to the new format. The basics of the new configuration mechanism in X is outlined below. Generally, users should not (need to) configure udev or add udev rules to enable device detection in X. While supported, users are discouraged of putting X.org-specific configuration into udev rules files.

xorg.conf.d

Beginning with X server version 1.8, the X server supports two new configuration mechanism. The first is support for the configuration directory /etc/xorg.conf.d. Files with the suffix .conf in this directory are parsed by the X server on startup and treated like a part of the traditional xorg.conf configuration file. Files in this directory may contain one or more sections, the X server essentially treats it like one giant xorg.conf file. Files in the /etc/xorg.conf.d directory are parsed in-order after the xorg.conf has been parsed fully and precedence is given to the first configuration entry where applicable. Users are encouraged to put custom configuration into /etc/xorg.conf and leave the directory for snippets provided by the distribution.


InputClasses

InputClasses are the X.org equivalent to HAL's fdi files previously used for configuration. Unlike an InputDevice section that may only apply to a single device, an InputClass section may apply to multiple devices, including hotplugged ones. An example InputClass section is provided below:

Section "InputClass"
   Identifier      "touchpad generic class"
   MatchIsTouchpad "on"
   Driver           "synaptics"
EndSection

If this snippet is present in the xorg.conf or xorg.conf.d, any touchpad present in the system is assigned the synaptics driver. Note that due to precedence order (xorg.conf first, then alphanumeric sorting of xorg.conf.d snippets) the Driver setting is only applied to devices that do not yet have a driver setting. Hence, the same section specified by the user in the xorg.conf with a Driver "evdev" line would force the evdev driver on all touchpads.

The match options specify which devices a section may apply to. To match a device, all match lines must apply. The following match lines are supported (with examples):

  • MatchIsPointer, MatchIsKeyboard, MatchIsTouchpad, MatchIsTouchscreen, MatchIsJoystick - boolean options to apply to a group of devices.
  • MatchProduct "foo|bar": match any device with a product name containing either "foo" or "bar"
  • MatchVendor "foo|bar|baz": match any device with a vendor string containing either "foo", "bar", or "baz"
  • MatchDevicePath "/dev/input/event*": match any device with a device path matching the given patch (see fnmatch(3) for the allowed pattern)
  • MatchTag "foo|bar": match any device with a tag of either "foo" or "bar". tags may be assigned by the config backend - udev in our case - to label devices that need quirks or special configuration.

An example section for user-specific configuration is:

Section "InputClass"
   Identifier     "lasermouse slowdown"
   MatchIsPointer "on"
   MatchProduct   "Lasermouse"
   MatchVendor    "LaserMouse Inc."
   Option         "ConstantDeceleration" 20
EndSection

This section would match a pointer device containing "Lasermouse" from "Lasermouse Inc." and apply a constant deceleration of 20 on this device - slowing it down by factor 20.