docs: keyboard/mouse protocol spec — LK401 (LK201 protocol) + VSXXX-AA mouse, sources, MAME lk201 device

Distils public docs into reference/keyboard-mouse/PROTOCOL.md for the level-1
Keyboard (27) / Mouse (26) device tests:
- keyboard: 4800 8N1 RS-423, self-test via FD -> 01 00 00 00 (errors 3D/3E)
- mouse: 4800 8O1 RS-232, self-test via 'T' -> 4-byte report (errors 3D/3E, >=0x20 fatal)
- separate ports: DUART2 A=keyboard, B=mouse (NOT daisy-chained)
MAME already has an LK201 device (src/mame/dec/lk201.cpp/.h) but no DEC mouse.

reference/keyboard-mouse/elkay/host/linux/README.md

@@ -0,0 +1,46 @@
+# Linux host setup
+
+elkay sends the LK401's F13–F20 as the standard USB keys F13–F20. The kernel reports them as
+`KEY_F13`–`KEY_F20`, but xkb's default symbols then turn them into other keys:
+
+| LK401 key | Default keysym | GNOME does |
+|-----------|----------------|------------|
+| F13 | XF86Tools | opens Settings |
+| F14 | XF86Launch5 | |
+| Help (F15) | XF86Launch6 | |
+| Do (F16) | XF86Launch7 | |
+| F17 | XF86Launch8 | |
+| F18 | XF86Launch9 | |
+| F19 | none | |
+| F20 | XF86AudioMicMute | mutes the microphone |
+
+GNOME acts on F13 and F20 before any application sees them, so veetee can't fix this on its
+own. The xkb option `elkay:fkeys` gives all eight keys the keysyms F13–F20, and veetee's default
+keymap already binds those.
+
+## Install
+
+```sh
+host/linux/install-xkb.sh
+```
+
+This copies `xkb/` to `~/.config/xkb/`, where libxkbcommon looks for user rules, and adds
+`elkay:fkeys` to GNOME's `xkb-options`, keeping any options already set. On other desktops, run
+it and then enable the option in the keyboard settings.
+
+The option applies to every keyboard. That's harmless: few PC keyboards have F13–F20, and the
+ones that do then send F13–F20 too.
+
+## Remove
+
+```sh
+gsettings reset org.gnome.desktop.input-sources xkb-options   # or remove just elkay:fkeys
+rm ~/.config/xkb/symbols/elkay ~/.config/xkb/rules/evdev
+```
+
+## Testing without the keyboard
+
+`xkb/` was checked by compiling `evdev / pc105 / us` keymaps with libxkbcommon, with and
+without the option. Keycodes FK13–FK20 resolve to F13–F20 only with it. The rules file includes
+the system rules *first*: rules apply in file order, and the option has to come after
+`inet(evdev)` to override it.

reference/keyboard-mouse/elkay/host/linux/install-xkb.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+# Installs the elkay xkb option for the current user and turns it on in GNOME.
+#
+# It makes the LK401's F13-F20 produce the keysyms F13-F20. Without it, xkb
+# sends XF86Tools for F13 (GNOME opens Settings) and XF86AudioMicMute for F20
+# (GNOME mutes the microphone). See README.md.
+set -eu
+
+here=$(cd "$(dirname "$0")" && pwd)
+xkb="${XDG_CONFIG_HOME:-$HOME/.config}/xkb"
+
+mkdir -p "$xkb/symbols" "$xkb/rules"
+cp "$here/xkb/symbols/elkay" "$xkb/symbols/elkay"
+
+if [ -e "$xkb/rules/evdev" ] && ! cmp -s "$here/xkb/rules/evdev" "$xkb/rules/evdev"; then
+    echo "$xkb/rules/evdev already exists; add these lines to it by hand:" >&2
+    sed -n '/^! option/,$p' "$here/xkb/rules/evdev" >&2
+    exit 1
+fi
+cp "$here/xkb/rules/evdev" "$xkb/rules/evdev"
+
+if command -v gsettings >/dev/null; then
+    options=$(gsettings get org.gnome.desktop.input-sources xkb-options)
+    case "$options" in
+        *elkay:fkeys*) ;;
+        "@as []") gsettings set org.gnome.desktop.input-sources xkb-options "['elkay:fkeys']" ;;
+        *) gsettings set org.gnome.desktop.input-sources xkb-options "${options%]}, 'elkay:fkeys']" ;;
+    esac
+    echo "elkay:fkeys is on. Log out and back in if F13 still opens Settings."
+else
+    echo "Installed to $xkb. Turn on the xkb option elkay:fkeys in your desktop's keyboard settings."
+fi

reference/keyboard-mouse/elkay/host/linux/xkb/rules/evdev

@@ -0,0 +1,9 @@
+// elkay: adds the option elkay:fkeys to the system's evdev rules.
+//
+// The include comes first: rules apply in file order, and the option has to
+// land after the base layout's inet(evdev) symbols to override them.
+
+! include %S/evdev
+
+! option = symbols
+  elkay:fkeys = +elkay(fkeys)

reference/keyboard-mouse/elkay/host/linux/xkb/symbols/elkay

@@ -0,0 +1,18 @@
+// elkay: DEC LK401 keys on a Linux desktop.
+//
+// xkb's default "inet" symbols turn F13-F18 into XF86Tools and XF86Launch5-9,
+// leave F19 without a symbol and turn F20 into XF86AudioMicMute; GNOME then
+// opens Settings on F13 and mutes the microphone on F20. The LK401 labels
+// these keys F13-F20, so give them those keysyms back.
+
+partial function_keys
+xkb_symbols "fkeys" {
+    key <FK13> { [ F13 ] };
+    key <FK14> { [ F14 ] };
+    key <FK15> { [ F15 ] };
+    key <FK16> { [ F16 ] };
+    key <FK17> { [ F17 ] };
+    key <FK18> { [ F18 ] };
+    key <FK19> { [ F19 ] };
+    key <FK20> { [ F20 ] };
+};