1. Introduction 1.1. Project/Component Working Name: Laptop ACPI Hotkey X Support 1.2. Name of Document Author/Supplier: Author: Henry Zhao 1.3 Date of This Document: March, 2009 4. Technical Description This project proposes a method of having X hotkey input device map kernel acpi driver(s) detected ACPI hotkey events and deliver them to applications. It is a part of project Laptop Hotkey Support [PSARC/2009/016]. Kernel acpi driver interfaces with libsysevent to publish ACPI hotkey events. The new X hotkey input device driver subscribes with libsysevent for "EC_acpiev" to receiving ACPI hotkey events, and when receiving such events, maps them to keycodes, and posts keycodes to X server. 4.1 Mapping methods Unlike regular key stroke, a hotkey event does not have a binding keycode. A keycode needs to be assinged and a mapping needs to be created. Any keycode can be assigned to a hotkey event mapping as long as the keycdoe assigned can uniquely identify the event. The candidates of keycodes to be selected for use in hotkey events mapping can only be those not being mapped (or used) in current keymap table. Xorg 1.5 and later supports multiple keyboards and input device hotplug. Each keyboard device has its own keymap, and keymap switches as keyboard switches. This creates some complexity. During investigation 3 mapping models were considered: 4.1.1 Model I Hotkey device driver creates a separate keymap of its own for hotkey events it may receive, that contains very limited entries for ACPI hotkey mappings. 4.1.2 Model II Patch keymap of each physical keyboard devices as well as "core keyboard" such that each keymap now contains original mapping and new mapping created for hotkeys. 4.1.3 Model III In Xorg 1.5, the effective keymap (the keymap that clients see) is the keymap of "core keyboard", which is updated every time keymap switches as a result of keyboard switch. In this model only keymap of "core keyboard" device is patched. Patching takes place during startup, and every time after the keymap of "core keyboard" is updated after a switch. No keymap of any physical keyboard device is patched. Model I is certainly the simplest implementaion. However it creates a race condition where clients always miss the first keystroke in switching to a new device, if the devices switched in and switched out have different mappings for that key. This is because X server switches keymap upon receiving the first keystroke from a new device but the delivery of the "first keystroke" is not based on keymap of the new device (still based on keymap of the old device) due to timing constraint. Model III works for Xorg 1.5. However as the input methods evolve at a rapid pace, with ideas such as client based effective keymap and multi core keyboard device on the way, patching "effective keymap" becomes more difficult. While device-based patching described in Model II is more resillient and can be relatively easily adapted to new mapping models. Model II is selected. 4.2 Implementation Keymap of a keyboard device is to be patched with a number of hotkey keysyms provided in HAL's fdi file with "input.x11_options.addmap" option under certain matching conditions. Keyboard driver does the patching after it loads basic keymap table. Hotkey device driver is to be launched by HAL using "input.x11_options.mdriver" option under certain matching conditions. Hotkey driver only patches keymap table of "core keyboard" device because the latter is not launched by HAL. To avoid race condition, hotkeys generated from hotkey device do not participate in keymap table switch. In driver code, a pipe is opened for communication between libsysevent handler and X server. The pipe's read file descriptor is added to the server events monitoring select list with AddEnabledDevice(). On receiving a libsysevent event, libsysevent handler writes to the pipe which unblocks read, and causes X server to wake up to process input events. In processing in input event, the driver reads from the pipe the last bype of keysym representing the event, looks for mapped keycode, and posts the keycode to X server's input queue. Imported Interfaces: -------------------- /usr/lib/(amd64)/libsysevent.so Volatile /kernel/drv/(amd64)/acpi_drv Volatile /kernel/drv/(amd64)/acpi_toshiba Volatile ACPI hotkey sub class: Volatile "ESC_acpiev_display_switch" Volatile "ESC_acpiev_sleep" Volatile "ESC_acpiev_screen_lock" Volatile "ESC_acpiev_audio_mute" Volatile Exported Interfaces: -------------------- /usr/X11/lib/modules/input/(amd64)/hotkey_drv.so Volatile input.x11_options.addmap (HAL) Volatile input.x11_options.mdriver (HAL) Volatile xf86PatchKeymap(DeviceIntPtr dev, char *keysymstr) Project Private PatchKeymap(DeviceIntPtr dev, KeySym *keysyms) Project Private keysyms: XF86ScreenSaver (To be consumed by GNOME) Volatile XF86Sleep (To be consumed by GNOME) Volatile XF86Display (To be consumed by GNOME) Volatile References: ----------- [PSARC/2009/016 ] Laptop Hotkey Support 6. Resources and Schedule 6.1. Projected Availability April 2008 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: X Consolidation (Desktop C-Team) 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open