Ubuntu Wiki

This page details the process of debugging the behavior of hotkeys/media keys in Ubuntu. See Hotkeys/Architecture for an overview of the architecture used for handling hotkey events.

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:

Packages involved in acting on hotkey events:

• gnome-power-manager - handles brightness and power hotkeys. Displays a popup 'OCD' display
• gnome-settings-daemon (handles visual feedback of volume changes, display toggling)
• gnome-control-center (gnome-sound-properties, gnome-keybinding-properties)
• pm-utils
• acpi-support
• gdm

Packages involved in propagating hotkey events to where they belong:

• hotkey-setup
• xserver-xorg-input-evdev
• linux kernel
• hal
• xkeyboard-config

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.

Step-by-step Troubleshooting

• if gnome-settings-daemon or gnome-power-manager is running, stop it first with killall gnome-settings-daemon gnome-power-manager; these daemons grab some X events exclusively and prevent them from being seen with `xev'.

• run xev to test whether a keypress event is seen:

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

• if there's a keypress event:

  • if the keycode is right, it's a desktop issue; see the list of packages that act on hotkey events for further diagnosis (gnome-settings-daemon, gnome-power-manager, ...)

    • in some cases the keybindings may be wrong, perhaps due to a legacy (i.e., pre-evdev) keymap. You can check your keymap using gconf-editor and looking under /apps/gnome_settings_daemon/keybindings. Bindings without sensible key names are probably bugs.

  • if the keycode itself is wrong, this is a bug in xkeyboard-config.

• if there's no keypress event, it's an issue with lower-level systems; switch to the console to troubleshoot further.

• enumerate the available input devices as seen by hal:

  hal-find-by-capability --capability input | xargs -n1 lshal -u

• look at the names of the input devices (info.product) and look for likely names and names that can be ruled out

• attach to the devices one by one using sudo input-events <devnum>, using the number returned by lshal as part of input.device, and press the hotkey to see if an event is generated

• if the event is found with input-events:

  • if lshal shows input.keys for the device and input.x11_driver is set to evdev, but X doesn't see it, this is a bug in X

  • if lshal does *not* show both input.keys and input.x11_driver="evdev", this is a bug in hal or in some desktop component that should be listening for that event via hal

• if not found with input-events, use acpi_listen to determine whether the key is coming through as an ACPI event instead of a keypress

• if there is an ACPI event but no keypress, this is a bug in the kernel (Ubuntu linux package) for not translating the ACPI event to an input event

• if there is neither an ACPI event nor an input event, this is probably also a kernel bug, though probably harder to diagnose (WMI, perhaps?)

Useful Information to Collect in Reports

• hal-find-by-capability --capability input | xargs -n1 lshal -u > lshal.log

• dmesg > dmesg.log

• sudo lsinput > lsinput.log

• xkbcomp -xkb :0 - > xkbcomp.txt

• setxkbmap -print > xkbmap.txt

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.

• Run gnome-power-manager in verbose mode (gnome-power-manager --no-daemon --verbose) to get detailed debug info

• Experiment with the scripts in /etc/acpi/. These come into play only for *some* hardware and are being phased out, so may not be relevant for your case.

• To test sleep modes directly, echo S3 > /proc/acpi/sleep

• Switch to a virtual terminal and back (e.g. ctrl+alt+F1 ; ctrl+alt+f7) and see if that resets things
• Switch to the Guest Account and see if the issue can be reproduced.
• Boot a LiveCD and try reproducing it there. If you can't, it suggests either a modification to your system or a software update not present on the LiveCD.
• Create a test user account, log out of all sessions and into that one. If you can't reproduce the issue there, then suspect some stored gconf or other settings in your dot files. (This is less likely if you've recently done a fresh install, vs. upgraded from past versions of Ubuntu.)
• If the key used to work properly at one time, and you've narrowed the problem to a specific component, then try testing different past versions of that package to try to bracket where the regression first started. This can help narrow down what patch might have caused the problem.

• Check if a proper keyboard shortcut is mapped to the action in gnome-keybinding-properties. A working shortcut looks like XF86AudioMute or Ctrl+Alt+Tab. An unknown key mapping looks like 0xed.

• For audio hotkey problems see which mixer device and which mixer tracks are set as default in gnome-audio-properties. The volume step can be changed in /apps/gnome_settings_daemon/volume_step with gconf-editor.