Migrating Xorg to HAL on FreeBSD

Klaas Teschauer, 20090607


I recently completed the migration to HAL for my Xorg configuration. The process was a bit tricky and the info from Google only told half the story, missing out key pieces. This document summarizes the understanding I gained after suffering through the process and figuring out how to make things work again.

Note that this document includes some assumptions that seem to be reasonable, but that have not been confirmed by me to be correct. So all the usual disclaimers apply, i.e. YMMV, use at your own risk, blah, blah, ...


In version 1.6 the Xorg X server adds support for finding and configuring the keyboard and the mouse via HAL, the Hardware Abstraction Layer. To make things a bit more interesting, the default settings in Xorg will use HAL and ignore the configuration data in xorg.conf. However, the FreeBSD package does not perform or describe the necessary configuration changes so that the Xorg server can now see the same configuration info through HAL and things continue to work as before. As a result, without configuration changes, the keyboard and/or mouse stop working after upgrading to version 1.6. Furthermore, for those of us who use a keyboard layout different from American, we are left scratching our heads as to how to get our special keys back.

There are essentially two ways of dealing with the problem. Either we tell Xorg to ignore HAL or make HAL provide the configuration parameters that Xorg expects to see.

Option 1: Tell Xorg to ignore HAL

The Xorg server still finds almost all of its configuration information in the xorg.conf file, with the exception of the keyboard and mouse parameters. The configuration information for the mouse and keyboard is now expected to be available in HAL, but this can be switched off. The respective options are not clearly marked to apply to HAL, you have to read through the manpage. Here is an excerpt for the relevant settings which appear in the "ServerFlags" section:

       Option "AllowEmptyInput" "boolean"
              If enabled, don't add the standard keyboard and  mouse  drivers,
              if  there  are  no input devices in the config file.  Enabled by
              default if AutoAddDevices and AutoEnableDevices is enabled, oth-
              erwise  disabled.   If  AllowEmptyInput is on, devices using the
              kbd, mouse or vmmouse driver are ignored.

       Option "AutoAddDevices" "boolean"
              If this option is disabled, then no devices will be  added  from
              HAL events.  Enabled by default.

       Option "AutoEnableDevices" "boolean"
              If  this option is disabled, then the devices will be added (and
              the DevicePresenceNotify event  sent),  but  not  enabled,  thus
              leaving policy up to the client.  Enabled by default.
Frankly, I have no idea if it would make sense to allow the X server to add new devices from HAL events, but not enable them, so the function of "AutoEnableDevices" is a mystery to me.

Based on these descriptions, setting "AllowEmptyInput" to "off" or "false" should force Xorg to ignore HAL and use the information in the xorg.conf file. I have not explicitly tested disabling HAL in this way. While doing it, I would also set the other two knobs to "off", just to be on the safe side.

Option 2: Stick the necessary configuration data into HAL


I have not done a lot of research into HAL, dbus and PolicyKit. Actually, until now I completely ignored them even though they got installed on my machine as dependencies of various other packages. I was hoping someone would post a nice HOWTO document that would summarize the salient items about the whole pile and life would be good. So far I have not found such a document and in its absence I am putting this little patch in. Again, note that some of the following is based on reasonable assumptions and conclusions that may or may not be correct.

Making it Work

HAL seems to be designed as central database of all devices available in the system. It does not do anything with the data, just stores it in a tree-like structure and makes it available to clients for queries. Clients can also ask to be notified in the event of a new device becoming available or an existing one being removed, e.g. a USB device being plugged in or disconnected.

HAL is implemented in form of a demon that needs to be started when the system comes up. Consistent with FreeBSD conventions, it is enabled or disabled in /etc/rc.conf. So the first step is to ensure that the hald demon is enabled there:

HAL depends on dbus, so it needs to be enabled as well. If hald and/or dbus was disabled, they can now be started manually (as root):
# /usr/local/etc/rc.d/hald start
# /usr/local/etc/rc.d/dbus start

For querying the hal daemon, the lshal(1) tool has been included in the package. On my system, it lists 60 different devices, including the CPUs (I have an Athlon dual-core).

When starting up, Xorg connects to HAL and asks for all devices that have the "input" capability. HAL seems to assign capabilities to all devices, apparently this is a way to group them by functional categories. A separate command-line tool is available to dump what a client sees for such a query, it is called hal-find-by-capability(1).

The kicker is that Xorg will only use input devices that have the property "input.x11_driver" containing the name of the driver the Xorg should use for the device. The driver name corresponds to the value of the "Driver" option in the respective "InputDevice" section in xorg.conf; i.e. "kbd" or "mouse".

As expected, very few of the device entries in HAL - I would contend none - come with a pre-defined "input.x11_driver" property. But devices properties can be added to the HAL database by the system administrator via a configuration file. I did not investigate all the options, but Google searches suggested that the relevant one on FreeBSD is /usr/local/etc/hal/fdi/policy/10-x11-input.fdi (Linux distros will probably have this in /etc/hal). This file works by matching a device or group of devices and then adding property records to the record. I would suspect that there are options for changing or deleting properties as well, but I have not checked that.

Here is the 10-x11-input.fdi file that I am currently using:

<?xml version="1.0" encoding="ISO-8859-1"?>
<deviceinfo version="0.2">
    <!-- tag the keyboard -->
    <match key="info.capabilities" contains="input.keyboard">
      <merge key="input.x11_driver" type="string">kbd</merge>
      <merge key="input.xkb.layout" type="string">de</merge>
      <merge key="input.xkb.variant" type="string">nodeadkeys</merge>
    <!-- tag the mouse as well -->
    <match key="info.capabilties" contains="input.mouse">
      <merge key="input.x11_driver" type="string">mouse</merge>

For those of you who are new to XML, now is a good time to read up on it. Like it or not, it generated enough hype when it was hot so that it will be with us no matter what. Better get used to it.

As can be seen from the example, the keyboard layout is set via options that resemble the original option parameters in the xorg.conf, they were just migrated to the HAL device database.

After creating a suitable 10-x11-input.fdi file and saving it, hald needs to be either restarted or told to reload its configuration. Use lshal to verify that the new properties are now available with the respective device.

In theory, Xorg should now see the keyboad and mouse information in HAL when using its default settings, but it doesn't hurt to nail that down, especially for testing. In the xorg.conf file, the "ServerFlags" section should contain the settings:

Section "ServerFlags"
	Option "AllowEmptyInput" "on"
	Option "AutoAddDevices" "on"
	Option "AutoEnableDevices" "on"
Based on the manpage to xorg.conf, this just re-iterates the defaults. With this, the InputDevice options in the ServerLayout section of xorg.conf can be commented out. With AllowEmptyInput set to "on", the server is supposed to ignore devices that use the mouse or kbd drivers, but again, I think it is better to make things explicit. After restarting the X server, the mouse and keyboad should now work as desired.


As stated above, this just summarizes my current understanding of how Xorg uses HAL. If you find material errors in this document or have otherwise comments on it, feel free to send me them to klaas at kite ping de. Note that I will not provide support fixing your system.