Ubuntu Wiki

Laptops have special functions such as sleep or brightness that are implemented through either buttons outside the main keyboard or key combinations using the Fn key. These are called "hotkeys", and are typically implemented in the laptop hardware and BIOS via the Advanced Configuration and Power Interface (ACPI).

NOTE: This document is a work in progress. ACPI is a complex subsystem and impossible for any one person to fully understand. Please take a few minutes to improve this document with the bits you know!

Hotkey Debugging Guide

Involved Components

ACPI events cross a lot of different layers, and determining the component that is handling them can take quite a bit of digging. Below is a non-comprehensive list of components which have been known to handle hotkey events:

Most commonly at fault:

• gnome-power-manager - handles brightness and power hotkeys. Displays a popup 'OCD' display
• pm-utils
• hotkey-setup
• acpi-support
• xserver-xorg-input-evdev

Less commonly at fault, but sometimes involved:

• acpid
• linux kernel
• gnome-settings-daemon
• hal
• xkeyboard-config
• gdm

Note that the 'acpi' source package is *not* involved in any of this, although many acpi/hotkey issues get (incorrectly) filed against it. 'acpi' is just a command line tool for listing info about acpi devices.

Common Classes of Hotkey Issues

• Performs no effect - Either the event is not being generated, nothing is listening for the event, or something has grabbed the event but failed to act on it.

• Fails when performing action - Something is definitely grabbing the event, but either it's the wrong thing to handle it, or is triggering the action in a way that causes a fault somewhere.

• Performs wrong action - Suggests the key is mapped incorrectly. There are several layers where these mappings are done.

Useful Information to Collect in Reports

• lshal -m

• sudo lsinput

• xkbcomp -xkb :0 - and setxkbmap -print - Important particularly if X is involved

Troubleshooting Tricks and Tips

• Testing: Before making changes, make a list of all your keys and hit each of them in turn, and record how they work. Repeat this after every change, so you'll know if a change fixed one thing but broke something else.
• Running acpid in debug mode: acpid -d. This should display output for software events when hitting hotkeys.
• Disable different suspects. If the issue goes away or changes behavior with one of these turned off, and comes back when it's on, then that strongly points to an issue in that particular component:
  • acpid: /etc/init.d/acpid stop
  • gnome-power-manager: pkill -9 gnome-power-manager
  • hotkey-setup: /etc/init.d/hotkey-setup stop
  • gdm: From console, /etc/init.d/gdm stop; startx

• Run acpi_listen, strike the hotkey, and see what gets printed out.

• Run input-events <device-number> (use lsinput to identify what event devices you have and which to look at)

• Log out of X to the console and run showkey -s to see the low level codes being sent by the keyboard

• Run gnome-power-manager in verbose mode to get detailed debug info

Hotkey Architecture

Here is the birds-eye view of how key mapping works: The kernel recognizes the key and establishes a raw scancode and maps it to an arbitrary kernel keycode (e.g. e06d -> 120). Xorg reads the kernel's keycode table, and generates it's own list of X keycodes (e.g. 120 -> 136). X then maps each X keycode to a keysym (e.g. 136 -> XF86AudioMedia). Finally, the window manager maps the keysym to a desired window manager shortcut action or an application command (e.g. XF86AudioMedia -> rhythmbox).

Part A: Kernel keyboard mapping

1. Find the "raw scancode" of the key in question. Typically for PS/2 keyboards this can be done from a tty console by hitting the key, and looking at dmesg output. For instance, if we are hitting the 'Media' key on a Dell Inspiron, we might see:

        atkbd.c: Unknown key pressed (translated set 2, code ... on isa0060/serio0).
        atkbd.c: Use 'setkeycodes e06d <keycode>' to make it known.

In the above, e06d is what we're looking for.

Another way to get the kernel keycodes is to shutdown X and hotkey-setup (e.g. /etc/init.d/gdm stop ; /etc/init.d/hotkey-setup stop) and then run showkey -s for raw scancodes or showkey -k for keycodes. Then restart hotkey-setup and gdm. This will give output for Media on a Dell Inspiron 1505N like:

0x9c
0x00 0x80 0xe2
0x80 0x81 0xe2

For USB controlled keys, an alternate approach is to run lshal -m from a console window and then hit the key. This should return something like:

    17:51:47.996: platform_i8042_i8042_KBD_port_logicaldev_input condition ButtonPressed = media

In this case, media is the key we're interested in. If ButtonPressed shows up as undefined, then the USB driver needs to be updated to support mapping this key to a Linux keycode (currently these are all compiled into the USB driver).

In some cases, your keys may be generating ACPI events instead of standard keycodes. To check this, run sudo tail -f /var/log/acpid and then hit the key. You should see something like:

received event "ibm/hotkey HKEY 00000080 00001010"

The interesting bits here is the part between the quotes. [What do we do with this info?]

On IBM/Lenovo laptops, some keys are only accessible via /dev/nvram. hotkey-setup can handle these and feeds the key presses into /dev/input/uinput to simulate regular key presses.

2. Identify the kernel keycode to use by referring to /usr/share/hotkey-setup/key-constants. For example, browsing through the file we find KEY_MEDIA:

...
KEY_BRIGHTNESSDOWN=224
KEY_BRIGHTNESSUP=225
KEY_MEDIA=226
KEY_SWITCHVIDEOMODE=227
KEY_KBDILLUMTOGGLE=228
...

These codes are defined in /usr/include/linux/input.h.

3. Set up the kernel keycode mapping for the keyboard layout by finding the manufacturer's file in /usr/share/hotkey-setup (part of the hotkey-setup package):

# inspiron multimedia keys
setkeycodes     e001    $KEY_PLAYPAUSE  # Dell E Key    Play/Pause (e001)
setkeycodes     e002    $KEY_STOP       # Dell i Key    Stop (e002)
setkeycodes     e003    $KEY_PREVIOUSSONG # Dell 1 Key  Previous Song (e003)
setkeycodes     e004    $KEY_NEXTSONG   # Dell 2 Key    Next Song (e004)
setkeycodes     e022    $KEY_PLAYPAUSE  # front         Play/Pause (e022)
setkeycodes     e010    $KEY_PREVIOUSSONG # panel       Previous Song (e010)
setkeycodes     e019    $KEY_NEXTSONG   # media         Next Song (e019)
setkeycodes     e024    $KEY_STOPCD     # buttons       Stop (e024)
setkeycodes     e06d    $KEY_MEDIA      # (Inspiron)    Media (e06d)

Here this adds a mapping for e06d to $KEY_MEDIA (kernel keycode 226).

These can also be set up via HAL quirks. See Keymap Quirk Debugger for details. Essentially, you need to add or update a section in the appropriate FDI file in /usr/share/hal/fdi/information/10freedesktop/, such as 30-keymap-dell.fdi for a Dell Inspiron 1505N:

...
        <!-- Dell Inspiron 9400, 640m, E1505/6400 -->
        <match key="/org/freedesktop/Hal/devices/computer:system.hardware.product" prefix_outof="MP061;MXC061;MM061"> 
          <append key="input.keymap.data" type="strlist">e005:brightnessdown</append> <!-- Fn+Down arrow Brightness Down -->
          <append key="input.keymap.data" type="strlist">e006:brightnessup</append> <!-- Fn+Up arrow Brightness Up -->
          <append key="input.keymap.data" type="strlist">e007:battery</append> <!-- Fn+F3 battery icon -->
          <append key="input.keymap.data" type="strlist">e008:wlan</append> <!-- Fn+F2 Toggle WiFi -->
          <append key="input.keymap.data" type="strlist">e008:bluetooth</append> <!-- FIXME Bluetooth switch (same as wireless) -->
          <append key="input.keymap.data" type="strlist">e009:ejectclosecd</append> <!-- Fn+F10 Eject CD -->
          <append key="input.keymap.data" type="strlist">e00a:suspend</append> <!-- Fn+F1 hibernate -->
          <append key="input.keymap.data" type="strlist">e00b:switchvideomode</append> <!-- Fn+F8 CRT/LCD -->
          <append key="input.keymap.data" type="strlist">e012:media</append> <!-- MediaDirect button (house icon) -->
          <append key="info.capabilities" type="strlist">input.keymap</append>
        </match>
...

So for instance, to support the e06d code we found before, we'd create a new section like the above, substituting in e06d for e012 (and any other codes that need remapping), into a new product section.

Use lshal | grep system.hardware.product and lshal | grep system.hardware.vendor to determine the product name and vendor of your laptop.

To see if hal has picked up your keymaps, restart the hal daemon and use lshal | grep keymap, which gives output like:

  info.callouts.add = {'hal-setup-keymap'} (string list)
  info.capabilities = {'input', 'input.keyboard', 'input.keypad', 'input.keys', 'input.keymap', 'button'} (string list)
  input.keymap.data = {'e005:brightnessdown', 'e006:brightnessup', 'e007:battery', 'e008:wlan', 'e008:bluetooth', 'e009:ejectclosecd', 'e00a:suspend', 'e00b:switchvideomode', 'e012:media'} (string list)

4. If there isn't a hotkey-setup file for your keyboard's manufacturer, you'll need to add a new one, and also add a reference to that file (and any associated logic) in the /etc/init.d/hotkey-setup script.

Part B: Xorg keyboard mapping

1. Xorg internally maps the kernel's keycodes into X keycodes, which apparently have nothing to do with kernel keycodes. To figure out what key was picked, run from a terminal window:

    xev

and hit the key in question. You should see output like this:

    KeyRelease event, serial 28, synthetic NO, window 0x3200001,
        root 0xb7, subw 0x0, time 137355697, (401,146), root:(413,264),
        state 0x10, '''keycode 136''' (keysym 0x0, NoSymbol), same_screen YES,
        XLookupString gives 0 bytes:

Note the keycode it specifies (136 in this example). Here's a way to filter the output more clearly:

xev | sed -n 's/^.*state \([0-9].*\), keycode *\([0-9]\+\) *\(.*\), .*$/keycode \2 = \3, state = \1/p'

Alternately, you can look up the scancode directly via /usr/share/X11/xkb/keycodes/xfree86. For instance, if the raw scancode is 'e06d', this corresponds to <I6D>:

    ...
    <I6D> =   237;
    ...

[To be honest, the above is a big guess at this mapping - can anyone confirm/deny the correctness of this?]

2. Now select a "keysym" to map. A listing of all available keysyms is in /usr/share/X11/XKeysymDB (or /usr/lib/X11/XKeysymDB before Edgy). Test the mapping:

    xmodmap -e "keycode <I6D> = XF86AudioMedia"

3. Next update or create a layout for the keyboard, by the appropriate file in /etc/X11/xkb/symbols/ (for media/internet keys, typically /etc/X11/xkb/symbols/inet:

// Laptop/notebook Dell Inspiron 8xxx
partial alphanumeric_keys
xkb_symbols "inspiron" {
    include "inet(media_common)"
    key <I02>   {       [ XF86AudioStop         ]       };
    key <I04>   {       [ XF86AudioNext         ]       };
    key <I21>   {       [ XF86Eject             ]       };
    key <I56>   {       [ XF86Display           ]       };
    key <I6D>   {       [ XF86AudioMedia        ]       };
    key <NFER>  {       [ XF86AudioPrev         ]       };
    key <XFER>  {       [ XF86AudioPlay, XF86AudioPause ] };
};

Then add the appropriate reference to /etc/X11/xkb/rules/xorg if it's not there already as is the case with inspiron, in the $inetkbds variable:

! $inetkbds = a4techKB21 a4techKBS8 a4_rfkb23 \
              acer_c300 acer_ferrari4k acer_laptop \
              acpi airkey \
              ...
              hpi6 hpxe3gc hpxe3gf hpxe4xxx hpxt1000 hpzt11xx \
              ipaq inspiron intel latitude \
              logiaccess logicd logicda logicink \
              ...
              toshiba_s3000 trust trustda \
              yahoo

and add a human description to /etc/X11/xkb/rules/xorg.lst:

! model
  pc101           Generic 101-key PC
  pc102           Generic 102-key (Intl) PC
  ...
  inspiron        Dell Laptop/notebook Inspiron 6xxx/8xxx
  precision_m     Dell Laptop/notebook Precision M series
  ...

and finally the localizable description to /etc/X11/xkb/rules/xorg.xml:

    <model>
      <configItem>
        <name>inspiron</name>
        <description>Dell Laptop/notebook Inspiron 6xxx/8xxx</description>
        <vendor>Dell</vendor>
      </configItem>
    </model>

After this, restart X, and the new keyboard layout can be selected in the usual manner.

Part C: Gnome/KDE hotkey mapping

At this point, gnome-keybinding-properties should now be able to detect your key. Check this by setting it for "Launch help browser" for example.

See Also

• man xmodmap

• Laptop Keycodes

• Hotkey Research

• Multimedia Keys in Ubuntu

• Multimedia Keys in Kubuntu

• Multimedia Keys in Xfce

• KeyTouch - GUI tools for keyboard configuration

• Gentoo's Multimedia Key Page

• USB HID Usage Tables (pdf)

• Quirking keymaps in HAL

• KeyTouch utility

• The Linux USB Input Subsystem

• whot's blog - upstream X input developer