The Linux keyboard driver

When you press a key on the console keyboard, the corresponding character is not simply added to the tty (generic terminal handling) input buffers as if it had come in over a serial port. A lot of processing is required before the kernel knows what the correct characters are. Only after processing can the generic tty code, which handles all interactive terminal devices, take over.

Roughly speaking, the picture is this: the keyboard produces scancodes, the scancodes are assembled into keycodes (one unique code for each key), and keycodes are converted to tty input characters using the kernel keymaps. After that, the normal `stty' processing takes place, just as for any other terminal.

The usual PC keyboards are capable of producing three sets of scancodes. Writing 0xf0 followed by 1, 2 or 3 to port 0x60 will put the keyboard in scancode mode 1, 2 or 3. Writing 0xf0 followed by 0 queries the mode, resulting in a scancode byte 0x43, 0x41 or 0x3f from the keyboard. (Don't try this at home, kids. If you are not very careful, you will end up in a situation where rebooting is the only way out—and control-alt-delete will not be available to shut the computer down correctly. See the accompanying listing of kbd_cmd.c for details.)

Scancode mode 2 is the default. In this mode, a key press usually produces a value s in the range 0x01-0x5f and the corresponding key release produces s+0x80. In scancode mode 3, the only key releases that produce a scan code are of both Shift keys, and the left Ctrl and Alt keys; for all other keys only the key presses are noted. The produced scancodes are mostly equal to those for scancode mode 2.

In scancode mode 1 most key releases produce the same values as in scancode mode 2, but for key presses there are entirely different, unrelated values. The details are somewhat messy.

A program can request the raw scancodes by

ioctl(0, KDSKBMODE, K_RAW);

For example, X, dosemu, svgadoom, and showkey -s do this. The default keycode translation mode is restored by

ioctl(0, KDSKBMODE, K_XLATE);

See the keyboard FAQ (in kbd-0.90.tar.gz) for some advice about how to get out of raw scancode mode from the shell prompt. (At a shell prompt the commands kbd_mode [-s|-k|-a|-u] will set the keyboard mode to scancode mode, keycode mode, translation (`ASCII') mode and Unicode mode, respectively. But it is difficult to type this command when the keyboard is in raw scancode mode.)

Life would have been easy had there been a 1-1 correspondence between keys and scancodes. (And in fact there is, in scancode mode 3, but that does not suffice for Linux, since X requires both the key press and the key release events.)

But as it is, a single key press can produce a sequence of up to six scancodes, and the kernel has to parse the stream of scancodes and convert it into a series of key press and key release events. To this end, each key is provided with a unique keycode k in the range 1-127, and pressing key k produces keycode k, while releasing it produces keycode k+128. The assignment of key codes is in principle arbitrary (and has no relation to the key codes used by X), but at present the key code equals the scan code for those keys that produce a single scancode in the range 0x01-0x58.

The parsing works by

Since s can take 127 values (0 is a keyboard error condition, and the high order bit indicates press/release) this means that parsing could result in 1+127+126=254 distinct keycodes. However, at present keycodes are restricted to the range 1-127 and we have to work a little to make things fit. (No doubt sooner or later keycodes will be integers instead of 7-bit quantities, and the keymaps will be sparse, but for the time being we can avoid that—since to my knowledge no actual PC keyboard has more than 127 keys.) So, there are small tables that assign a keycode to a scancode pair 0xe0 s or to a single scancode in the range 0x59-0x7f. In the default setting everything works for most current keyboards, but in case you have some strange keyboard, you can get the kernel to recognize an otherwise unrecognized key by filling an entry in these tables using the KDSETKEYCODE ioctl; see setkeycodes(8).

Two keys are unusual in the sense that their keycode is not constant, but depends on modifiers. The PrintScrn key will yield keycode 84 when combined with either Alt key, but keycode 99 otherwise. The Pause key will yield keycode 101 when combined with either Ctrl key, but keycode 119 otherwise. (This has historic reasons, but might change, to free keycodes 99 and 119 for other purposes.)

At present there is no way to tell X about strange key(board)s. The easiest solution would be to make X use keycodes instead of scancodes, so that the information about strange keys and the scancodes they produce is located a single place.

A program can request to get keycodes by doing

ioctl(0, KDSKBMODE,
K_MEDIUMRAW);

For example, showkey does this. Warning: the details of the function of both the KDSETKEYCODE ioctl and the K_MEDIUMRAW keyboard mode are likely to change in the future.

Keycodes are converted to keysymbols by looking them up on the appropriate keymap. There are eight possible modifiers (shift keys), and the combination of currently active modifiers and locks determines the keymap used.

Thus, what happens is approximately:

int shift_final = shift_state ^ kbd->lockstate;
 ushort *key_map = key_maps[shift_final];
 keysym = key_map[keycode];

The eight modifiers are known as Shift, AltGr, Control, Alt, ShiftL, ShiftR, CtrlL and CtrlR. These labels have no intrinsic meaning, and the modifiers can be used for arbitrary purposes, except that the keymap for the Shift modifier determines the action of CapsLock (and that the Shift key partially suppresses keyboard application mode). By default Shift is bound to both Shift keys and Control keys and Alt and AltGr are bound to the left and right Alt keys. The remaining four modifiers are unbound in the default kernel. X is able to distinguish ShiftL and ShiftR, etc.

Thus, there are 256 possible keymaps—for plain symbols, for Shift+symbol, for Ctrl+AltL+Shift+symbol, etc. Usually, not all of the keymaps will be allocated (combinations with more than three modifiers are rather unusual), and in fact the default kernel allocates only 7 keymaps, namely the plain, Shift, AltR, Ctrl, Ctrl+Shift, AltL and Ctrl+AltL maps. You can allocate more keymaps simply by filling some of their entries using loadkeys(1).

Key symbols are shorts, i.e., they consist of two bytes. In Unicode mode, this short is just the 16-bit value returned—or, to be precise, the returned byte string is the UTF-8 representation of this Unicode character. The keyboard is put into Unicode mode by

ioctl(0, KDSKBMODE, K_UNICODE);

When not in Unicode mode, the high order byte is viewed as a type, and the low order byte as a value, and we do:

type = KTYP(keysym);
 (*key_handler[type])(keysym & 0xff, up_flag);

The type selects a function from the array key_handler:

static k_hand key_handler[16] = {
     do_self, do_fn, do_spec, do_pad, do_dead,
     do_cons, do_cur, do_shift, do_meta, do_ascii,
     do_lock, do_lowercase, do_ignore, do_ignore,
     do_ignore, do_ignore
 };

As already mentioned, almost all of this can be changed dynamically by use of loadkeys(1). The current state is dumped by dumpkeys(1). A list of known symbols is provided by dumpkeys -l. The keycodes associated with the various keys can be found using showkey(1). These and many other utilities for keyboard and console can be found in kbd-0.90.tar.gz on ftp.funet.fi and its mirror sites.

Use loadkeys to change the code produced by the BackSpace key from Delete to BackSpace:

% loadkeys
keycode 14 = BackSpace

Assign the string “emacs\n” to the function key F12, and “rm *~\n” to Shift-F12 (the keycode 88 was found using showkey; the F66 is a random unused function key symbol):

% loadkeys
 keycode 88 = F12
 shift keycode 88 = F66
 string F12 = "emacs\n"
 string F66 = "rm *~\n"

Create the compose combination that will compose | and S into $:

% loadkeys
 compose '|' 'S' to '$'
 compose 'S' '|' to '$'

Reset to some default state:

% loadkeys -d

After the above handling, the obtained character(s) are put in the raw tty queue. Depending on the mode of the tty, they will be processed and transferred to the cooked tty queue. (Don't confuse raw mode as stty knows it, with the raw scancode mode discussed above.) Finally, the application will get them when it does getchar();.