xorgproto: Branch 'master' - 3 commits
GitLab Mirror
gitlab-mirror at kemper.freedesktop.org
Wed Jul 23 06:10:52 UTC 2025
include/X11/XF86keysym.h | 116 ++++++++++++++++++++++++++++++++++++--------
scripts/keysym-generator.py | 42 ++++++++++-----
2 files changed, 123 insertions(+), 35 deletions(-)
New commits:
commit 7fc33fe6d9cf0abc9b62ee976e5cb7ddcd050d1f
Author: Pierre Le Marre <dev at wismill.eu>
Date: Sun Jul 20 20:26:36 2025 +0200
keysyms: Add aliases for media keys
Part-of: <https://gitlab.freedesktop.org/xorg/proto/xorgproto/-/merge_requests/93>
diff --git a/include/X11/XF86keysym.h b/include/X11/XF86keysym.h
index b30a128..db823ba 100644
--- a/include/X11/XF86keysym.h
+++ b/include/X11/XF86keysym.h
@@ -108,6 +108,7 @@
#define XF86XK_ApplicationRight 0x1008ff51 /* switch to application, right*/
#define XF86XK_Book 0x1008ff52 /* Launch bookreader */
#define XF86XK_CD 0x1008ff53 /* Launch CD/DVD player */
+#define XF86XK_MediaSelectCD 0x1008ff53 /* Alias for XF86XK_CD */
#define XF86XK_Calculater 0x1008ff54 /* Launch Calculater */
#define XF86XK_Clear 0x1008ff55 /* Clear window, screen */
#define XF86XK_Close 0x1008ff56 /* Close window */
@@ -275,6 +276,8 @@
* The format for #defines is strict:
*
* #define XF86XK_Foo<spaces…>_EVDEVK(0xABC)<spaces…> |* kver KEY_FOO *|
+ * #define XF86XK_Foo<spaces…>_EVDEVK(0xABC)<spaces…> |* Alias for XF86XK_Bar *|
+ * #define XF86XK_Foo<spaces…>_EVDEVK(0xABC)<spaces…> |* Deprecated alias for XF86XK_Bar *|
*
* Where
* - alignment by spaces
@@ -348,13 +351,14 @@
#define XF86XK_MediaSelectVCRPlus _EVDEVK(0x17c) /* v2.5.26 KEY_VCR2 */
#define XF86XK_MediaSelectSatellite _EVDEVK(0x17d) /* v2.5.26 KEY_SAT */
/* TODO: unclear media selector _EVDEVK(0x17e) v2.5.26 KEY_SAT2 */
-/* Use: XF86XK_CD _EVDEVK(0x17f) v2.5.26 KEY_CD */
+/* Use: XF86XK_MediaSelectCD _EVDEVK(0x17f) v2.5.26 KEY_CD */
#define XF86XK_MediaSelectTape _EVDEVK(0x180) /* v2.5.26 KEY_TAPE */
#define XF86XK_MediaSelectRadio _EVDEVK(0x181) /* v2.5.26 KEY_RADIO */
#define XF86XK_MediaSelectTuner _EVDEVK(0x182) /* v2.5.26 KEY_TUNER */
#define XF86XK_MediaPlayer _EVDEVK(0x183) /* v2.5.26 KEY_PLAYER */
#define XF86XK_MediaSelectTeletext _EVDEVK(0x184) /* v2.5.26 KEY_TEXT */
#define XF86XK_DVD _EVDEVK(0x185) /* v2.5.26 KEY_DVD */
+#define XF86XK_MediaSelectDVD _EVDEVK(0x185) /* Alias for XF86XK_DVD */
#define XF86XK_MediaSelectAuxilliary _EVDEVK(0x186) /* v2.5.26 KEY_AUX */
/* TODO: unclear media selector _EVDEVK(0x187) v2.5.26 KEY_MP3 */
#define XF86XK_Audio _EVDEVK(0x188) /* v2.5.26 KEY_AUDIO */
diff --git a/scripts/keysym-generator.py b/scripts/keysym-generator.py
index 486e68c..cd1a439 100755
--- a/scripts/keysym-generator.py
+++ b/scripts/keysym-generator.py
@@ -191,11 +191,14 @@ def verify(ns):
# This is the full pattern we expect.
expected_pattern = re.compile(
- r"#define XF86XK_\w+ +_EVDEVK\(0x([0-9A-Fa-f]{3})\) +/\* (v[2-6]\.[0-9]+(\.[0-9]+)?)? +KEY_\w+ \*/"
+ r"#define XF86XK_\w+ +_EVDEVK\(0x([0-9A-Fa-f]{3})\) +"
+ r"/\* (?:(?P<kernel_version>v[2-6]\.[0-9]+(\.[0-9]+)?)? +KEY_\w+|"
+ r"(?P<alias>Alias for XF86XK_\w+)) \*/"
)
# This is the comment pattern we expect
expected_comment_pattern = re.compile(
- r"/\* Use: (?P<name>\w+) +_EVDEVK\(0x(?P<value>[0-9A-Fa-f]{3})\) + (v[2-6]\.[0-9]+(\.[0-9]+)?)? +KEY_\w+ \*/"
+ r"/\* Use: (?P<name>\w+) +_EVDEVK\(0x(?P<value>[0-9A-Fa-f]{3})\) + "
+ r"(v[2-6]\.[0-9]+(\.[0-9]+)?)? +KEY_\w+ \*/"
)
# Some patterns to spot specific errors, just so we can print useful errors
@@ -204,8 +207,11 @@ def verify(ns):
space_check = re.compile(r"#define \w+(\s+)[^\s]+(\s+)")
hex_pattern = re.compile(r".*0x([a-f0-9]+).*", re.I)
todo_pattern = re.compile(r"^/\* TODO.*\*/$")
- comment_format = re.compile(r".*/\* ([^\s]+)?\s+(\w+)")
+ comment_format = re.compile(
+ r".*/\* (?:(?:Deprecated a|A)lias for (\w+)|([^\s]+)?\s+(\w+))"
+ )
kver_format = re.compile(r"v[2-6]\.[0-9]+(\.[0-9]+)?")
+ alias_format = re.compile(r"(?:Deprecated a|A)lias for XF86XK_\w+")
in_evdev_codes_section = False
had_evdev_codes_section = False
@@ -292,17 +298,20 @@ def verify(ns):
comment = re.match(comment_format, line)
if not comment:
error("Invalid comment format", line)
- kver = comment.group(1)
- if kver and not re.match(kver_format, kver):
- error("Invalid kernel version format", line)
+ if alias_target := comment.group(1):
+ alias = True
+ else:
+ alias = False
+ if (kver := comment.group(2)) and not re.match(kver_format, kver):
+ error("Invalid kernel version format", line)
- keyname = comment.group(2)
- if not keyname.startswith("KEY_") or keyname.upper() != keyname:
- error("Kernel keycode name invalid", line)
+ keyname = comment.group(3)
+ if not keyname.startswith("KEY_") or keyname.upper() != keyname:
+ error("Kernel keycode name invalid", line)
- # This could be an old libevdev
- if keyname not in [c.name for c in libevdev.EV_KEY.codes]:
- logger.warning(f"Unknown kernel keycode name {keyname}")
+ # This could be an old libevdev
+ if keyname not in [c.name for c in libevdev.EV_KEY.codes]:
+ logger.warning(f"Unknown kernel keycode name {keyname}")
# Check the full expected format, no better error messages
# available if this fails
@@ -313,7 +322,7 @@ def verify(ns):
keycode = int(match.group(1), 16)
if keycode < last_keycode:
error("Keycode must be ascending", line)
- if keycode == last_keycode:
+ if keycode == last_keycode and not alias:
error("Duplicate keycode", line)
# May cause a false positive for old libevdev if KEY_MAX is bumped
commit d466a25c875ffd3da755b1a47b151e21d7df4d03
Author: Oliver Gerlich <oliver.gerlich at gmx.de>
Date: Thu Dec 19 21:54:58 2024 +0100
keysyms: add missing keys that were added in Linux kernel 2.5.26
Some keysyms were renamed compared to their Linux kernel counterparts,
to avoid names that are too ambiguous. Names are inspired by the “HID
usage table for USB”.
Some keys were left unmapped due to their ambiguous function.
Also fixed the keysyms script to handle minor new use cases.
Miscellaneous notes:
- `KEY_CHANNEL`: Described as “Go to the next favorite channel” in the
Linux RC tables, thus mapped to `XF86XK_NextFavorite`.
- `KEY_PVR`: The accronym means “personal video recorder”, but there
are multiple comments in the kernel refering to it as “Media Select
Home”.
- `KEY_MODE`: Described as labelled "MONO/STEREO" with the function
"Change sound mode" in the Linux RC tables, thus mapped to the more
explicit `XF86XK_AudioChannelMode`.
- `KEY_DIGITS`: Describe as “Use more than one digit for channel”, it
denotes various number entry modes that depend on the device, thus
mapped to the more explicit `XF86XK_NumberEntryMode`, inspired by its
entry in the CEC protocol.
Resources:
- Linux Remote controller tables:
https://www.kernel.org/doc/html/v6.14/userspace-api/media/rc/rc-tables.html
- Linux HID key mmappings:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/hid/hid-input.c
- HID Usage Tables for USB:
https://usb.org/sites/default/files/hut1_6.pdf
- Kodi: https://github.com/xbmc/xbmc
Co-authored-by: Oliver Gerlich <oliver.gerlich at gmx.de>
Co-authored-by: Pierre Le Marre <dev at wismill.eu>
Part-of: <https://gitlab.freedesktop.org/xorg/proto/xorgproto/-/merge_requests/93>
diff --git a/include/X11/XF86keysym.h b/include/X11/XF86keysym.h
index 6631917..b30a128 100644
--- a/include/X11/XF86keysym.h
+++ b/include/X11/XF86keysym.h
@@ -317,18 +317,70 @@
/* Use: XF86XK_WWAN _EVDEVK(0x0f6) v3.13 KEY_WWAN */
/* Use: XF86XK_RFKill _EVDEVK(0x0f7) v2.6.33 KEY_RFKILL */
/* Use: XF86XK_AudioMicMute _EVDEVK(0x0f8) v3.1 KEY_MICMUTE */
-#define XF86XK_Info _EVDEVK(0x166) /* KEY_INFO */
-/* Use: XF86XK_CycleAngle _EVDEVK(0x173) KEY_ANGLE */
+#define XF86XK_OK _EVDEVK(0x160) /* v2.5.26 KEY_OK */
+/* Use: XF86XK_Select _EVDEVK(0x161) v2.5.26 KEY_SELECT */
+#define XF86XK_GoTo _EVDEVK(0x162) /* v2.5.26 KEY_GOTO */
+/* Use: XF86XK_Clear _EVDEVK(0x163) v2.5.26 KEY_CLEAR */
+/* TODO: Unclear function _EVDEVK(0x164) v2.5.26 KEY_POWER2 */
+/* Use: XF86XK_Option _EVDEVK(0x165) v2.5.26 KEY_OPTION */
+#define XF86XK_Info _EVDEVK(0x166) /* v2.5.26 KEY_INFO */
+/* Use: XF86XK_Time _EVDEVK(0x167) v2.5.26 KEY_TIME */
+#define XF86XK_VendorLogo _EVDEVK(0x168) /* v2.5.26 KEY_VENDOR */
+/* TODO: unclear function _EVDEVK(0x169) v2.5.26 KEY_ARCHIVE */
+#define XF86XK_MediaSelectProgramGuide _EVDEVK(0x16a) /* v2.5.26 KEY_PROGRAM */
+/* Use: XF86XK_NextFavorite _EVDEVK(0x16b) v2.5.26 KEY_CHANNEL */
+/* Use: XF86XK_Favorites _EVDEVK(0x16c) v2.5.26 KEY_FAVORITES */
+/* Use: XF86XK_MediaSelectProgramGuide _EVDEVK(0x16d) v2.5.26 KEY_EPG */
+#define XF86XK_MediaSelectHome _EVDEVK(0x16e) /* v2.5.26 KEY_PVR */
+/* TODO: Multimedia Home Platform _EVDEVK(0x16f) v2.5.26 KEY_MHP */
+#define XF86XK_MediaLanguageMenu _EVDEVK(0x170) /* v2.5.26 KEY_LANGUAGE */
+#define XF86XK_MediaTitleMenu _EVDEVK(0x171) /* v2.5.26 KEY_TITLE */
+/* Use: XF86XK_Subtitle _EVDEVK(0x172) v2.5.26 KEY_SUBTITLE */
+/* Use: XF86XK_CycleAngle _EVDEVK(0x173) v2.5.26 KEY_ANGLE */
/* Use: XF86XK_FullScreen _EVDEVK(0x174) v5.1 KEY_FULL_SCREEN */
+#define XF86XK_AudioChannelMode _EVDEVK(0x175) /* v2.5.26 KEY_MODE */
+/* Use: XF86XK_Keyboard _EVDEVK(0x176) v2.5.26 KEY_KEYBOARD */
#define XF86XK_AspectRatio _EVDEVK(0x177) /* v5.1 KEY_ASPECT_RATIO */
-#define XF86XK_DVD _EVDEVK(0x185) /* KEY_DVD */
-#define XF86XK_Audio _EVDEVK(0x188) /* KEY_AUDIO */
-/* Use: XF86XK_Video _EVDEVK(0x189) KEY_VIDEO */
-/* Use: XF86XK_Calendar _EVDEVK(0x18d) KEY_CALENDAR */
-#define XF86XK_ChannelUp _EVDEVK(0x192) /* KEY_CHANNELUP */
-#define XF86XK_ChannelDown _EVDEVK(0x193) /* KEY_CHANNELDOWN */
-/* Use: XF86XK_AudioRandomPlay _EVDEVK(0x19a) KEY_SHUFFLE */
-#define XF86XK_Break _EVDEVK(0x19b) /* KEY_BREAK */
+#define XF86XK_MediaSelectPC _EVDEVK(0x178) /* v2.5.26 KEY_PC */
+#define XF86XK_MediaSelectTV _EVDEVK(0x179) /* v2.5.26 KEY_TV */
+#define XF86XK_MediaSelectCable _EVDEVK(0x17a) /* v2.5.26 KEY_TV2 */
+#define XF86XK_MediaSelectVCR _EVDEVK(0x17b) /* v2.5.26 KEY_VCR */
+#define XF86XK_MediaSelectVCRPlus _EVDEVK(0x17c) /* v2.5.26 KEY_VCR2 */
+#define XF86XK_MediaSelectSatellite _EVDEVK(0x17d) /* v2.5.26 KEY_SAT */
+/* TODO: unclear media selector _EVDEVK(0x17e) v2.5.26 KEY_SAT2 */
+/* Use: XF86XK_CD _EVDEVK(0x17f) v2.5.26 KEY_CD */
+#define XF86XK_MediaSelectTape _EVDEVK(0x180) /* v2.5.26 KEY_TAPE */
+#define XF86XK_MediaSelectRadio _EVDEVK(0x181) /* v2.5.26 KEY_RADIO */
+#define XF86XK_MediaSelectTuner _EVDEVK(0x182) /* v2.5.26 KEY_TUNER */
+#define XF86XK_MediaPlayer _EVDEVK(0x183) /* v2.5.26 KEY_PLAYER */
+#define XF86XK_MediaSelectTeletext _EVDEVK(0x184) /* v2.5.26 KEY_TEXT */
+#define XF86XK_DVD _EVDEVK(0x185) /* v2.5.26 KEY_DVD */
+#define XF86XK_MediaSelectAuxilliary _EVDEVK(0x186) /* v2.5.26 KEY_AUX */
+/* TODO: unclear media selector _EVDEVK(0x187) v2.5.26 KEY_MP3 */
+#define XF86XK_Audio _EVDEVK(0x188) /* v2.5.26 KEY_AUDIO */
+/* Use: XF86XK_Video _EVDEVK(0x189) v2.5.26 KEY_VIDEO */
+/* TODO: unclear function _EVDEVK(0x18a) v2.5.26 KEY_DIRECTORY */
+/* TODO: unclear function _EVDEVK(0x18b) v2.5.26 KEY_LIST */
+/* Use: XF86XK_Memo _EVDEVK(0x18c) v2.5.26 KEY_MEMO */
+/* Use: XF86XK_Calendar _EVDEVK(0x18d) v2.5.26 KEY_CALENDAR */
+/* Use: XF86XK_Red _EVDEVK(0x18e) v2.5.26 KEY_RED */
+/* Use: XF86XK_Green _EVDEVK(0x18f) v2.5.26 KEY_GREEN */
+/* Use: XF86XK_Yellow _EVDEVK(0x190) v2.5.26 KEY_YELLOW */
+/* Use: XF86XK_Blue _EVDEVK(0x191) v2.5.26 KEY_BLUE */
+#define XF86XK_ChannelUp _EVDEVK(0x192) /* v2.5.26 KEY_CHANNELUP */
+#define XF86XK_ChannelDown _EVDEVK(0x193) /* v2.5.26 KEY_CHANNELDOWN */
+/* TODO: unclear function _EVDEVK(0x194) v2.5.26 KEY_FIRST */
+/* TODO: unclear function _EVDEVK(0x195) v2.5.26 KEY_LAST */
+/* TODO: unclear function _EVDEVK(0x196) v2.5.26 KEY_AB */
+/* TODO: unclear function _EVDEVK(0x197) v2.5.26 KEY_NEXT */
+/* TODO: unclear function _EVDEVK(0x198) v2.5.26 KEY_RESTART */
+#define XF86XK_MediaPlaySlow _EVDEVK(0x199) /* v2.5.26 KEY_SLOW */
+/* Use: XF86XK_AudioRandomPlay _EVDEVK(0x19a) v2.5.26 KEY_SHUFFLE */
+#define XF86XK_Break _EVDEVK(0x19b) /* v2.5.26 KEY_BREAK */
+/* TODO: unclear function _EVDEVK(0x19c) v2.5.26 KEY_PREVIOUS */
+#define XF86XK_NumberEntryMode _EVDEVK(0x19d) /* v2.5.26 KEY_DIGITS */
+/* TODO: unclear function _EVDEVK(0x19e) v2.5.26 KEY_TEEN */
+/* TODO: unclear function (Twenties?) _EVDEVK(0x19f) v2.5.26 KEY_TWEN */
#define XF86XK_VideoPhone _EVDEVK(0x1a0) /* v2.6.20 KEY_VIDEOPHONE */
/* Use: XF86XK_Game _EVDEVK(0x1a1) v2.6.20 KEY_GAMES */
/* Use: XF86XK_ZoomIn _EVDEVK(0x1a2) v2.6.20 KEY_ZOOMIN */
diff --git a/scripts/keysym-generator.py b/scripts/keysym-generator.py
index bdcecdc..486e68c 100755
--- a/scripts/keysym-generator.py
+++ b/scripts/keysym-generator.py
@@ -48,7 +48,9 @@ def all_keysyms(directory):
them as list.
"""
keysym_names = []
- pattern = re.compile(r"^#define\s+(?P<name>\w+)\s+(0x[0-9A-Fa-f]+)")
+ pattern = re.compile(
+ r"^#define\s+(?P<name>\w+)\s+(0x[0-9A-Fa-f]+|_EVDEVK\(0x([0-9A-Fa-f]{3}))"
+ )
for path in directory.glob("*keysym*.h"):
with open(path) as fd:
for line in fd:
@@ -201,6 +203,7 @@ def verify(ns):
name_pattern = re.compile(r"#define (XF86XK_[^\s]*)")
space_check = re.compile(r"#define \w+(\s+)[^\s]+(\s+)")
hex_pattern = re.compile(r".*0x([a-f0-9]+).*", re.I)
+ todo_pattern = re.compile(r"^/\* TODO.*\*/$")
comment_format = re.compile(r".*/\* ([^\s]+)?\s+(\w+)")
kver_format = re.compile(r"v[2-6]\.[0-9]+(\.[0-9]+)?")
@@ -257,7 +260,7 @@ def verify(ns):
name = match.group("name")
if name not in all_keysym_names:
error(f"Unknown keysym {name}", line)
- elif re.match(hex_pattern, line):
+ elif re.match(hex_pattern, line) and not todo_pattern.match(line):
logger.warning(f"Unexpected hex code in {line}")
continue
commit ba0d32820bc0c1eef4529551459ec46570abef2f
Author: Pierre Le Marre <dev at wismill.eu>
Date: Thu Jul 3 17:04:31 2025 +0200
keysyms: Relax evdev keysyms naming convention
Try to follow the X11 general guidelines more closely:
> Keysyms identify characters or *functions* associated with each key.
> […] This file assigns *mnemonic* macro names for these keysyms.
> [Keysym design] makes it easier to write a *portable* application.
Key points:
- Better naming is better self-documentation: abstruse keynames and
jargon (e.g. acronyms) may lead to misuse.
- Keysyms share a common namespace: generic names should be reserved
to actual generic functions, else it is better to use a relevant
prefix, e.g. `XF86XK_OK` is acceptable but `XF86XK_Title` is ambiguous
and better renamed with the prefix `Media`: `XF86XK_MediaTitleMenu`.
- Lookup the evdev keys is kept simple thanks to the strict formatting
rules.
Part-of: <https://gitlab.freedesktop.org/xorg/proto/xorgproto/-/merge_requests/93>
diff --git a/include/X11/XF86keysym.h b/include/X11/XF86keysym.h
index 57a1056..6631917 100644
--- a/include/X11/XF86keysym.h
+++ b/include/X11/XF86keysym.h
@@ -237,27 +237,47 @@
/*
* 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)
+ * Key symbols within this range are intended for a 1:1 mapping to the
+ * Linux kernel input-event-codes.h file:
+ * - Keysym value: `_EVDEVK(kernel value)`
+ * - Keysym name: it must be prefixed by `XF86XK_`. The recommended *default*
+ * name uses the following pattern: `XF86XK_CamelCaseKernelName`. CamelCasing
+ * is done with a human control as last authority, e.g. see VOD instead of Vod
+ * for the Video on Demand key. In case that the kernel key name is too
+ * ambiguous, it is recommended to create a more explicit name with the
+ * following guidelines:
+ * 1. Names should be mnemonic.
+ * 2. Names should avoid acronyms, unless sufficiently common and documented
+ * in a comment.
+ * 3. Names should identify a function.
+ * 4. Keysyms share a common namespace, so keys with a generic name should
+ * denote a generic function, otherwise it should be renamed to add context.
+ * E.g. `KEY_OK` has the associated keysym `XF86XK_OK`, while `KEY_TITLE`
+ * (used to open a menu to select a chapter of a media) is associated to
+ * the keysym `XF86XK_MediaTitleMenu` to avoid ambiguity.
+ * 5. Keysyms should support designing *portable* applications, therefore
+ * their names should be self-explaining to facilitate finding them and
+ * to avoid misuse.
+ * 6. The “HID usage tables for USB” can be used if there is an unambiguous
+ * mapping. See:
+ * - Reference document: https://usb.org/document-library/hid-usage-tables-16
+ * - Mapping in the Linux source file: `drivers/hid/hid-input.c` as of 2025-07
+ *
* For example, the kernel
- * #define KEY_MACRO_RECORD_START 0x2b0
+ * #define KEY_MACRO_RECORD_START 0x2b0
* effectively ends up as:
- * #define XF86XK_MacroRecordStart 0x100812b0
+ * #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 *|
+ * #define XF86XK_Foo<spaces…>_EVDEVK(0xABC)<spaces…> |* kver KEY_FOO *|
*
* Where
- * - alignment by tabs
+ * - alignment by spaces
* - the _EVDEVK macro must be used
* - the hex code must be in uppercase hex
* - the kernel version (kver) is in the form v5.10
More information about the xorg-commit
mailing list