HAL Keymap Quirks

Back to the main keymap page

Fixing non-mapped vendor buttons

Use case

Toby presses the multimedia buttons on his shiny new laptop keyboard. They do not work, and he is sad. Toby notices that everytime he presses the button he gets:

atkbd.c: Unknown key pressed (translated set 2, code 0x97 on isa0060/serio0).
atkbd.c: Use 'setkeycodes e017 ' to make it known.

in the dmesg output. He doesn't know what that means.

Other buttons don't display anything, but sometimes work using extra software like tpd and lineakd.


Some vendors use buttons that are not recognized by Linux, and a scancode to keycode mapping is not done. This means the button does not work in X, and instead prints the error to the system log.

Other (or even the same!) vendors push keys through the ACPI layer, which means they are not processed by X and thus do nothing unless you have a daemon polling or catching the ACPI events which is not setup by default. It also means having the policy code in two or more places.


For some Ubuntu users, the hotkey-setup package can be used to create the mapping, although this package is not integrated with any other distributions, and it is not easy to add new entries.

A cross-distro and better solution is to use HAL, so that DMI data (data specific to your machine type) is matched against a set of rules, and the keys are automatically mapped at boot time.

This means we can do the mapping for physical keyboards that are attached to the system permanently, i.e. are non removeable. For removable keyboards on desktop machines we have to use X keymaps as the user has to be able to select the keyboard model. The majority of funky buttons are present on laptops, and so this is where this site will focus.

New rules are being created every day, and updating the hal-info package might just get things working for you without doing anything else. This FAQ will explain how to use HAL to create the rule using DMI data, and then send the rule to the HAL list so that other Linux users with the same laptop model will have their buttons "just work".

Back to the main keymap page