XF86keysym.h: reserve a range for Linux kernel keysyms

The Linux kernel adds a few evdev keycodes roughly every other release. These
aren't available as keysyms through XKB until they have been added as keycode
in xkeyboard-config and mapped there to a newly defined keysym in the X11
proto headers.

In the past, this was done manually,  a suitable keysym was picked at
random and the mapping updated accordingly. This doesn't scale very well and,
given we have a large reserved range for XF86 keysyms anyway, can be done
easier.

Let's reserve the range 0x10081XXX range for a 1:1 mapping of Linux kernel
codes. That's 4095 values, the kernel currently uses only 767 anyway. The
lower 3 bytes of keysyms within that range have to match the kernel value to
make them easy to add and search for. Nothing in X must care about the actual
keysym value anyway.

Since we expect this to be parsed by other scripts for automatic updating, the
format of those #defines is quite strict. Add a script to generate keycodes as
well as verify that the existing ones match the current expected format.

The script is integrated into the CI and meson test, so we will fail if an
update breaks the expectations.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 40 insertions, 0 deletions

diff --git a/include/X11/XF86keysym.h b/include/X11/XF86keysym.h
index 8310fe3..26f9c39 100644
--- a/include/X11/XF86keysym.h
+++ b/include/X11/XF86keysym.h
@@ -232,3 +232,43 @@
 #define XF86XK_Prev_VMode	0x1008FE23   /* prev. video mode available */
 #define XF86XK_LogWindowTree	0x1008FE24   /* print window tree to log   */
 #define XF86XK_LogGrabInfo	0x1008FE25   /* print all active grabs to log */
+
+
+/*
+ * Reserved range for evdev symbols: 0x10081000-0x10081FFF
+ *
+ * Key syms within this range must match the Linux kernel
+ * input-event-codes.h file in the format:
+ *     XF86XK_CamelCaseKernelName	_EVDEVK(kernel value)
+ * For example, the kernel
+ *   #define KEY_MACRO_RECORD_START	0x2b0
+ * effectively ends up as:
+ *   #define XF86XK_MacroRecordStart	0x100812b0
+ *
+ * For historical reasons, some keysyms within the reserved range will be
+ * missing, most notably all "normal" keys that are mapped through default
+ * XKB layouts (e.g. KEY_Q).
+ *
+ * CamelCasing is done with a human control as last authority, e.g. see VOD
+ * instead of Vod for the Video on Demand key.
+ *
+ * The format for #defines is strict:
+ *
+ * #define XF86XK_FOO<tab...>_EVDEVK(0xABC)<tab><tab> |* kver KEY_FOO *|
+ *
+ * Where
+ * - alignment by tabs
+ * - the _EVDEVK macro must be used
+ * - the hex code must be in uppercase hex
+ * - the kernel version (kver) is in the form v5.10
+ * - kver and key name are within a slash-star comment (a pipe is used in
+ *   this example for technical reasons)
+ * These #defines are parsed by scripts. Do not stray from the given format.
+ *
+ * Where the evdev keycode is mapped to a different symbol, please add a
+ * comment line starting with Use: but otherwise the same format, e.g.
+ *  Use: XF86XK_RotationLockToggle	_EVDEVK(0x231)		   v4.16 KEY_ROTATE_LOCK_TOGGLE
+ *
+ */
+#define _EVDEVK(_v) (0x10081000 + _v)
+#undef _EVDEVK