zaine/org_backend
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

initial

Browse Source
This commit is contained in:
Zaine Arch
2025-12-14 21:07:46 +00:00
commit 5db24213bd
281 changed files with 18445 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
#20251122223053-keyboard.org# Normal file
View File

@@ -0,0 +1,166 @@
:PROPERTIES:
:ID: 0217f537-442a-4593-8c69-d481f0d1f2a8
:END:
#+title: keyboard
#+filetags: :hardware:linux:
This all comes from the fact that a “key press” isn’t one thing — it’s a stack of specs and translations from **keyboard hardware → USB/HID → Linux kernel → userspace (XKB/Wayland) → Hyprland binds**.
Here are some structured notes you can keep / refer back to 👇
---
## 1. Big picture: what happens when you press a key?
When you hit a key (like your “lock” key), roughly this happens:
```text
Physical switch on keyboard
↓
Keyboard firmware → USB HID "usage" (e.g. 0x07:0xE3 = Left GUI)
↓
Linux kernel input subsystem (evdev) → KEY_LEFTMETA (code 125)
↓
libinput / xkbcommon → keysyms (like Super_L, L, etc.)
↓
Hyprland → your `bind = SUPER, L, exec, ...`
```
The “topic” we’ve been poking at is basically **understanding each layer in that stack**.
---
## 2. USB HID: where `700e3` comes from
Modern USB keyboards follow the **USB HID (Human Interface Device) specification**.
This spec defines **Usage Tables**: numerical codes for things like keys, buttons, axes, etc.
* The keyboard page is **Usage Page 0x07 (Keyboard/Keypad)**.
* In your `evtest` output, `MSC_SCAN value 700e3` means:
* `0x07` (Keyboard page)
* `0xE3` (Left GUI / “Windows/Super” key)
You can see the official tables here (PDF):
* **HID Usage Tables (includes Keyboard/Keypad page 0x07)**
[https://usb.org/sites/default/files/hut1_21.pdf](https://usb.org/sites/default/files/hut1_21.pdf) ([USB Implementers Forum][1])
If you scroll to the **Keyboard/Keypad Page (0x07)** section, it lists all the key usages: A, B, C, modifiers, function keys, etc. There’s also a standalone Keyboard/Keypad-page extract people mirror, like this PDF snippet: ([d1.amobbs.com][2])
So:
* `700e3` = Page `0x07`, Usage `0xE3` → *Keyboard Left GUI*
* `7000f` = Page `0x07`, Usage `0x0F` → *Keyboard L* key
That’s how we knew your lock key was sending **Super + L**.
---
## 3. Linux input subsystem: `EV_MSC`, `EV_KEY`, `KEY_LEFTMETA`
Linux has a dedicated **input subsystem** in the kernel (`drivers/input`, `drivers/hid` etc.) that takes those HID usages and turns them into a unified stream of **input events**. ([Linux Kernel Documentation][3])
Key ideas:
* Devices expose `/dev/input/eventX` nodes.
* Each event is a struct with:
* `type` (e.g. `EV_KEY`, `EV_MSC`, `EV_REL`, `EV_SYN`)
* `code` (e.g. `KEY_L`, `KEY_LEFTMETA`)
* `value` (pressed = 1, released = 0, repeat = 2)
Docs worth bookmarking:
* **Linux input subsystem overview**
[https://docs.kernel.org/input/input.html](https://docs.kernel.org/input/input.html) ([Linux Kernel Documentation][3])
* **Input event types and codes (`event-codes.txt`)**
[https://www.kernel.org/doc/Documentation/input/event-codes.txt](https://www.kernel.org/doc/Documentation/input/event-codes.txt) ([Kernel.org][4])
The **keycode definitions** (`KEY_L`, `KEY_LEFTMETA`, etc.) live in:
* `include/uapi/linux/input-event-codes.h` in the kernel source
Example mirror:
[https://raw.githubusercontent.com/torvalds/linux/master/include/uapi/linux/input-event-codes.h](https://raw.githubusercontent.com/torvalds/linux/master/include/uapi/linux/input-event-codes.h) ([GitHub][5])
When `evtest` prints:
```text
type 4 (EV_MSC), code 4 (MSC_SCAN), value 700e3
type 1 (EV_KEY), code 125 (KEY_LEFTMETA), value 0
```
that means:
* `EV_MSC / MSC_SCAN` → “Here is the raw hardware scancode” (from USB HID).
* `EV_KEY / KEY_LEFTMETA` → “Linux mapped that scancode to logical key LEFTMETA”.
## 4. XKB / xkbcommon: mapping to actual characters & modifiers
Above the kernel, you’ve got an extra mapping layer that says:
> For keycode N, with this layout, when Shift is held, produce this character/symbol.
On X11 this is handled by **XKB (X Keyboard Extension)**; on Wayland compositors (including Hyprland) the same ideas are implemented via **xkbcommon**.
Docs:
* **X Keyboard Extension (XKB) protocol spec**
[https://www.x.org/releases/X11R7.7/doc/kbproto/xkbproto.html](https://www.x.org/releases/X11R7.7/doc/kbproto/xkbproto.html) ([X.Org][6])
* **Arch Wiki: X keyboard extension** (good high-level intro)
[https://wiki.archlinux.org/title/X_keyboard_extension](https://wiki.archlinux.org/title/X_keyboard_extension) ([ArchWiki][7])
* A nice “practical” walkthrough of XKB concepts:
[https://medium.com/@damko/a-simple-humble-but-comprehensive-guide-to-xkb-for-linux-6f1ad5e13450](https://medium.com/@damko/a-simple-humble-but-comprehensive-guide-to-xkb-for-linux-6f1ad5e13450) ([Medium][8])
Hyprland, Sway, etc. all use libinput + xkbcommon under the hood to interpret those keycodes and translate them into keysyms and modifiers.
---
## 5. Hyprland / your config: where the bindings fit in
Hyprland sits at the top of this stack:
* It listens to the input events (via libinput).
* It sees keysyms/modifiers (e.g. `Super`, `L`).
* It matches them against your config:
```ini
bind = SUPER, L, exec, hyprlock
```
So your keyboard’s “lock” key:
1. Firmware sends HID usages `0xE3` (Left GUI) and `0x0F` (L).
2. Linux maps them to `KEY_LEFTMETA` (125) and `KEY_L` (38).
3. xkbcommon maps that to `Super` + `L`.
4. Hyprland says: “Ah, SUPER+L → run `hyprlock`”.
The “topic” you stumbled into is just **peeling back each abstraction layer**.
## 6. Handy tools & libraries if you want to go deeper
* `evtest`, `libinput debug-events`, `showkey`
→ To watch what your keyboard is actually sending.
* **Python-evdev** – Python bindings to read `/dev/input/event*` yourself:
[https://python-evdev.readthedocs.io/](https://python-evdev.readthedocs.io/) ([python-evdev.readthedocs.io][9])
* Linux input subsystem docs again:
[https://docs.kernel.org/driver-api/input.html](https://docs.kernel.org/driver-api/input.html) ([Linux Kernel Documentation][10])
---
[1]: https://usb.org/sites/default/files/hut1_21.pdf?utm_source=chatgpt.com "HID Usage Tables"
[2]: https://d1.amobbs.com/bbs_upload782111/files_47/ourdev_692986N5FAHU.pdf?utm_source=chatgpt.com "10 Keyboard/Keypad Page (0x07)"
[3]: https://docs.kernel.org/input/input.html?utm_source=chatgpt.com "1. Introduction — The Linux Kernel documentation"
[4]: https://www.kernel.org/doc/Documentation/input/event-codes.txt?utm_source=chatgpt.com "event-codes.txt"
[5]: https://raw.githubusercontent.com/torvalds/linux/master/include/uapi/linux/input-event-codes.h?utm_source=chatgpt.com "Input event codes - GitHub"
[6]: https://www.x.org/releases/X11R7.7/doc/kbproto/xkbproto.html?utm_source=chatgpt.com "The X Keyboard Extension: Protocol Specification"
[7]: https://wiki.archlinux.org/title/X_keyboard_extension?utm_source=chatgpt.com "X keyboard extension"
[8]: https://medium.com/%40damko/a-simple-humble-but-comprehensive-guide-to-xkb-for-linux-6f1ad5e13450?utm_source=chatgpt.com "A simple, humble but comprehensive guide to XKB for linux"
[9]: https://python-evdev.readthedocs.io/?utm_source=chatgpt.com "Introduction — Python-evdev - Read the Docs"
[10]: https://docs.kernel.org/driver-api/input.html?utm_source=chatgpt.com "Input Subsystem"