diff options
Diffstat (limited to 'public')
| -rw-r--r-- | public/kbd-xmodmap.md | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/public/kbd-xmodmap.md b/public/kbd-xmodmap.md new file mode 100644 index 0000000..80012d8 --- /dev/null +++ b/public/kbd-xmodmap.md @@ -0,0 +1,244 @@ +GNU/Linux Keyboard Maps: xmodmap +================================ +--- +date: "2018-02-09" +--- + +The modmap subsystem is part of the core [X11 protocol][xproto]. +However, it has been replaced by the [X Keyboard (XKB) +Extension][kbproto] to the protocol, which defines a facade that +emulates the legacy modmap subsystem so that old programs still +work---including those that manipulate the modmap directly! + +[xproto]: https://www.x.org/releases/current/doc/xproto/x11protocol.html +[kbproto]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html + +For people who like to Keep It Stupid Simple, the XKB extension looks +horribly complicated and gross---even ignoring protocol details, the +configuration syntax is a monstrosity! There's no way to say +something like "I'd like to remap Caps-Lock to be Control", you have +to copy and edit the entire keyboard definition, which includes +mucking with vector graphics of the physical keyboard layout! So it's +very tempting to pretend that XKB doesn't exist, and it's still using +modmap. + +However, this is a leaky abstraction; for instance: when running the +`xmodmap` command to manipulate the modmap, if you have multiple +keyboards plugged in, the result can depend on which keyboard you used +to press "enter" after typing the command! + +Despite only existing as a compatibility shim today, I think it is +important to understand the modmap subsystem to understand modern XKB. + +Conceptual overview +------------------- + +There are 3 fundamental tasks that the modmap subsystem performs: + + 1. `keyboard: map keycode -> keysym` (client-side) + 2. `keyboard: map keycode -> modifier bitmask` (server-side) + 3. `pointer: map physical button -> logical button` (server-side) + +You're thinking: "Great, so the X server does these things for us!" +Nope! Not entirely, anyway. It does the keycode->modifier lookup, +and the mouse-button lookup, but the keycode->keysym lookup must be +done client-side by querying the mapping stored on the server. +Generally, this is done automatically inside of libX11/libxcb, and the +actual client application code doesn't need to worry about it. + +So, what's the difference between a keycode and a keysym, and how's +the modifier bitmask work? + + - keycode: A numeric ID for a hardware button; this is as close the + the hardware as X11 modmaps let us get. These are conceptually + identical to Linux kernel keycodes, but the numbers don't match + up. Xorg keycodes are typically `linux_keycode+8`. + + - keysym: A 29-bit integer code that is meaningful to applications. + A mapping of these to symbolic names is defined in + `<X11/keysymdef.h>` and augmented by `/usr/share/X11/XKeysymDB`. + See: `XStringToKeysym()` and `XKeysymToString()`. We will + generally use the symbolic name in the modmap file. The symbolic + names are case-sensitive. + + - Modifier state: An 8-bit bitmask of modifier keys (names are + case-insensitive): + + 1 << 0 : shift + 1 << 1 : lock + 1 << 2 : control + 1 << 3 : mod1 + 1 << 4 : mod2 + 1 << 5 : mod3 + 1 << 6 : mod4 + 1 << 7 : mod5 + +With that knowledge, and the libX11/libxcb API docs, you can probably +figure out how to interact with the modmap subsystem from C, but who +does that? Everyone just uses the `xmodmap(1)` command. + +The X11 protocol +---------------- + +As I said, the modifier and button lookup is handled server-side; each +of the [input events][] ({Key,Button}{Press,Release}, and +MotionNotify) and [pointer window events][] ({Enter,Leave}Notify) +include a bitmask of active keyboard modifiers and pointer buttons. +Each are given an 8-bit bitmask---hence 8 key modifiers. For some +reason, only up to Button5 is included in the bitmask; the upper 3 +bits are always zero; but the Button{Press,Release} events will +happily deliver events for up to Button255! + +[input events]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#events:input +[pointer window events]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#events:pointer_window + +The X11 protocol has 6 request types for dealing with these 3 +mappings; an accessor and a mutator pair for each. Since the 2 of the +mappings are done server-side, of these, most clients will only use +GetKeyboardMapping. Anyway, let's look at those 6 requests, grouped +by the mappings that they work with (pardon the Java-like pseudo-code +syntax for indicating logical argument and return types): + + 1. `keyboard: map keycode -> keysym` + + - [GetKeyboardMapping][] :: `List<keycode> -> Map<keycode,List<keysym>>` + - [ChangeKeyboardMapping][] :: `Map<keycode,List<keysym>> -> ()` + + `GetKeyboardMapping` returns the keycode->keysym mappings for the + requested keycodes; this way clients can choose to look up only + the keycodes that they need to handle (the ones that got sent to + them). Each keycode gets a list of keysyms; which keysym they + should use from that list depends on which modifiers are pressed. + `ChangeKeyboardMapping` changes the mapping for the given + keycodes; not all keycodes must be given, any keycodes that aren't + included in the request aren't changed. + + 2. `keyboard: map keycode -> modifier bitmask` + + - [GetModifierMapping][] :: `() -> Map<modifier,List<keycode>>` + - [SetModifierMapping][] :: `Map<modifier,List<keycode>> -> ()` + + The modifiers mapping is a lot smaller than the keysym mapping; + you must operate on the entire mapping at once. For each modifier + bit, there's a list of keycodes that will cause that modifier bit + to be flipped in the events that are delivered while it is + pressed. + + 3. `pointer: map physical button -> logical button` + + - [GetPointerMapping][] `() -> List<logicalButton>` (indexed by `physicalButton-1`) + - [SetPointerMapping][] `List<logicalButton> -> ()` (indexed by `physicalButton-1`) + + Like the modifier mapping, the button mapping is expected to be + small, most mice only have 5-7 buttons (left, middle, right, + scroll up, scroll down, scroll left, scroll right---that's right, + X11 handles scroll events as button presses), though some fancy + gaming mice have more than that, but not much more. + +[ChangeKeyboardMapping]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:ChangeKeyboardMapping +[SetModifierMapping]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:SetModifierMapping +[SetPointerMapping]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:SetPointerMapping + +[GetKeyboardMapping]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:GetKeyboardMapping +[GetModifierMapping]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:GetModifierMapping +[GetPointerMapping]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:GetPointerMapping + +I mentioned earlier that the keycode->keysym mapping isn't actually +done by the X server, and is done in the client; whenever a client +receives a key event or pointer button event, it must do a +`Get*Mapping` request to see what that translates to. Of course, +doing a that for every keystroke would be crazy; but at the same time, +the each client is expected to know about changes to the mappings that +happen at run-time. So, each of the "set"/"change" commands generate +a [MappingNotify][] event that is sent to all clients, so they know +when they must dump their cache of mappings. + +[MappingNotify]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#events:MappingNotify + +For completeness, if you are looking at this as background for +understanding XKB, I should also mention: + + - [GetKeyboardControl][] + - [ChangeKeyboardControl][] + - [GetPointerControl][] + - [ChangePointerControl][] + +[GetKeyboardControl]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:GetKeyboardControl +[ChangeKeyboardControl]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:ChangeKeyboardControl +[GetPointerControl]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:GetPointerControl +[ChangePointerControl]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#requests:ChangePointerControl + +The `xmodmap` command +--------------------- + +The `xmodmap` command reads a configuration file and modifies the maps +in the X server to match. The `xmodmap` config file has its own +little quirky syntax. For one, the comment character is `!` (and +comments may only start at the *beginning* of the line, but that's +fairly common). + +There are 8 commands that `xmodmap` recognizes. Let's look at those, +grouped by the 3 tasks that the modmap subsystem performs: + + 1. `keyboard: map keycode -> keysym` + + - `keycode KEYCODE = PLAIN [SHIFT [MODE_SWITCH [MODE_SWITCH+SHIFT ]]]` + + Actually takes a list of up to 8 keysyms, but only the first + 4 have standard uses. + + - `keysym OLD_KEYSYM = NEW_KEYSYMS...` + + Takes the keycodes mapped to `OLD_KEYSYM` and maps them to + `NEW_KEYSYM`. + + - `keysym any = KEYSYMS...` + + Finds an otherwise unused keycode, and has it map to the + specified keysyms. + + 2. `keyboard: map keycode -> modifier bitmask` + + - `clear MODIFIER` + - `add MODIFIERNAME = KEYSYMS...` + - `remove MODIFIERNAME = KEYSYMS...` + + Wait, the modmap subsystem maps *keycodes* to modifiers, but the + commands take *keysyms*? Yup! When executing one of these + commands, it first looks up those keysyms in the keyboard map to + translate them in to a set of keycodes, then associates those + keycodes with that modifier. But how does it look up + keysym->keycode; the protocol only supports querying + keycode->keysym? It + [loops](https://cgit.freedesktop.org/xorg/app/xmodmap/tree/handle.c?h=xmodmap-1.0.9#n59) + over *every* keycode finding all the matches. + + 3. `pointer: map physical button -> logical button` + + - `pointer = default` + + This is equivalent to `pointer = 1 2 3 4 5 6...` where the + list is as long as the number of buttons that there are. + + - `pointer = NUMBERS...` + + `pointer = A B C D...` sets the physical button 1 to logical + button A, physical button 2 to logical button B, and so on. + Setting a physical button to logical button 0 disables that + button. + +Appendix: +--------- + +I use this snippet in my Emacs configuration to make editing xmodmap +files nicer: + + ;; http://www.emacswiki.org/emacs/XModMapMode + (when (not (fboundp 'xmodmap-mode)) + (define-generic-mode 'xmodmap-mode + '(?!) + '("add" "clear" "keycode" "keysym" "pointer" "remove") + nil + '("[xX]modmap\\(rc\\)?\\'") + nil + "Simple mode for xmodmap files.")) |