The Ubuntu 8.10 process highlighted the fact that we do not have a consistent architecture for how hotkeys work across different hardware in Ubuntu, and many of the developers do not have a clear understanding - or may have different understandings - of how the system is intended to work. This is intended to be the authoritative architecture description that developers can refer to when interacting with Ubuntu packages, to identify whether a given component is operating as intended.

This spec also identifies certain work that should be completed as part of the Ubuntu 9.04 process to eliminate certain extraneous components that unduly complicate the architecture, and to ease the process of debugging hotkey problems that do arise.

Release Note

Hotkey handling in Ubuntu has been consolidated in the latest release, leading to moving most functionality out of the hotkey-setup and acpi-support packages to the hal-info package.


This spec documents the cross-platform architecture that hotkey handling is intended to use in Ubuntu, serving as a guide for debugging hotkey problems. It should be kept up-to-date if this architecture changes.




  • hal handles mapping of hardware-specific scancodes to generic evdev keycodes where necessary, by calling setkeycodes for keymaps generated using fdi files in hal-info.

  • hal also handles enumeration of input devices for X
  • it should not be in between the kernel evdev device and X.


  • keycode events are read from the evdev devices, which use a flat namespace for keycodes
  • these keycodes differ from the pre-evdev keycodes
  • the keycodes are platform-agnostic and should not require any translation at a layer between the kernel and X


  • some events should be handled by hal and not read from X at all, if they should be available in contexts other than the current desktop session


  • Provide a living document at Hotkeys/Architecture describing the intended architecture for hotkey handling on Ubuntu, as well as identifying any areas where we are not currently consistent with this.

  • Provide a living document at Hotkeys/Troubleshooting explaining to users how to go about tracking down problems with their hotkeys so that they can file useful bug reports.

  • Add an apport hook for (hotkey-setup, acpi-tools, acpid, xserver-xorg-input-evdev) which gathers the "useful information" documented in Hotkeys/Troubleshooting.

  • hotkey-setup: should be obsolete
    • review all settings and confirm that they are present in hal-info, then drop from hotkey-setup
    • thinkpad-acpi module includes dmi: modaliases, so udev should handle this (confirmed with Keybuk, tested by mdz), test that this can be removed from hotkey-setup
    • Setting the in-kernel hotkey mask, which is currently done by the init script, should be done as a modprobe.d script, until the kernel does the right thing by default
    • package should be removed from ubuntu-desktop when it's confirmed to not be needed
  • acpi-support: try to clean up scripts as possible that are no longer necessary
    • acpi_fakekey should go away completely, after reviewing that it's handled elsewhere
    • acpi-support also includes handling of certain events that are not desktop-y and should not be moved to that layer; where do we move this? (ex: Thinkpad wireless key) pitti says: hal, DeviceKit add-on

  • input-events should be extended to be able to read from all devices simultaneously

  • input-events should be fixed to output to stdout, not stderr:

  • input-events should be extended to output the numeric keycode in addition to the symbolic name

Bugs of interest

  • bug #198214 thinkpad sleep suspend fn buttons do not work without g-p-m
  • bug #281284 No function keys for sleep and hibernation in Kubuntu on Thinkpad

Test/Demo Plan

It's important that we are able to test new features, and demonstrate them to users. Use this section to describe a short plan that anybody can follow that demonstrates the feature is working. This can then be used during testing, and to show off after release. Please add an entry to for tracking test coverage.

This need not be added or completed until the specification is nearing beta.


HotkeyArchitectureSpec (last edited 2009-12-01 23:43:45 by minbar)