Module hid 

USB HID boot-protocol decoding, shared by the USB host drivers (xhci, ehci, dwc2).

Pure logic - no syscalls, no I/O. Each driver reads the fixed 8-byte boot report from its controller’s DMA and hands it here; the side effects (pushing a character to the console, logging a mouse event) stay in the driver, passed in as closures. This is the controller-agnostic reuse §26.2 anticipated once both drivers existed: the report format is identical whether the bytes arrived over xHCI transfer-event rings or EHCI split qTDs.

Structs

KeyRepeat

Tracks the currently-held key so a driver can synthesise typematic auto-repeat. USB HID boot keyboards report only on change - a held key sends one down report and then nothing until release - so the host must synthesise repeat itself.

MouseTracker

Tracks mouse boot reports across calls: edge-detects button transitions and accumulates relative motion. There is no on-screen cursor in a text console (that belongs to a future display server), so the driver surfaces events by logging; this struct decides what is worth surfacing and hands it back via closures.

Constants

CTRL_ALT_DEL_SIGNAL

Console-stream signal for the Ctrl+Alt+Del secure-attention chord (the SEC-2 follow-up).

KEY_CAPS_LOCK

HID usage of the Caps Lock key. It is a host-tracked LATCH: the modifier byte never reports it, so the host toggles a caps flag on each fresh press (see decode_keyboard).

KEY_DELETE

HID usage of the Delete (forward-delete) key - the Del in Ctrl+Alt+Del.

MOUSE_LEFT

Left / right / middle button masks in a mouse boot report’s byte 0.

MOUSE_MIDDLE

MOUSE_RIGHT

MUTE_TOGGLE_SIGNAL

NOTICE_SIGNAL

Console-stream signal from a USB host: it has just printed a device notice (USB: WiFi dongle connected (xhci)) over whatever the console showed, and the program reading the console may want to put its own line back. The shell redraws its prompt with the half-typed line under the notice; anything else ignores it, because it is not a key. The hosts pushed a real Enter (\n) for this until 2026-10-24, and an Enter is an ANSWER: a plug while godspeed install asked [y/N] answered it N, and at the prompt it ran the half-typed line (the VisionFive card). Outside ASCII, so no typed key produces it, and read from here by both ends.

VOLUME_DOWN_SIGNAL

VOLUME_UP_SIGNAL

Console-stream signals for the audio shortcuts (docs/audio.md, “Keyboard shortcuts”): Ctrl+Alt+Up, Ctrl+Alt+Down and Ctrl+Alt+M. The Ctrl+Alt+Del pattern exactly: the keyboard driver only SAYS the chord happened, on the console stream, and the SHELL - which asks the audio driver - acts. The keyboard drivers gain no capability and never speak to the audio driver. Outside ASCII, so no typed key produces them, and read from here by both ends.

Functions

audio_chord

The audio shortcut a key press is, with these modifiers: either Ctrl (0x01 / 0x10) AND either Alt (0x04 / 0x40), with Up, Down or M. None for every other key, which then means what it always did.

button_name

Name a mouse button mask, for logging.

decode_keyboard

Decode a keyboard boot report (modifiers in byte 0, up to six keycodes in bytes 2..8) with N-key edge detection: emit(ascii) is called for every key that is down now but was not in last, so rolling onto a new key before releasing the previous one drops nothing and a held key fires exactly once. last is updated to this report’s keycodes for the next call.

hid_to_ascii

Decode a HID boot-keyboard usage code to ASCII (US layout, common keys). caps is the host’s Caps Lock toggle state (the HID modifier byte does NOT carry it - Caps Lock is a host-tracked latch, see decode_keyboard). Caps Lock XORs Shift, but only for letters - it never affects digits or symbols (that’s the difference from Shift).

is_ctrl_alt_del

True if a keyboard boot report is the Ctrl+Alt+Del chord: either Ctrl (left 0x01 / right 0x10) and either Alt (left 0x04 / right 0x40) held, with the Delete key down. This is the secure-attention combo - a driver checks it each poll for a keyboard device and, when true, pushes CTRL_ALT_DEL_SIGNAL for the shell to act on; the driver itself cannot reboot (SEC-2). (This said the driver “issues the reboot syscall”, which SEC-2 removed.) Apply this ONLY to keyboard reports: a mouse boot report’s button byte (byte 0) can alias the Ctrl/Alt modifier bits, so it must never be tested here.

report_is_valid

Is an 8-byte HID boot report real device data, or the all-0xff signature of a failed/stale DMA read (a device that vanished mid-transaction, or a buffer the controller never wrote)? Returns false only for an all-0xff report. This is the universal garbage check - safe for both keyboards and mice (a real mouse won’t send all-0xff; a keyboard never does) - which a driver uses to count a wedged endpoint toward disconnect and re-enumerate. (The keyboard decoder additionally rejects any report whose reserved byte 1 ≠ 0, a stricter check that only makes sense for keyboards.)