RedBear-OS/local/docs/HID-STUBS-AUDIT.md

HID Stack Stubs and Incomplete-Code Audit

Date: 2026-06-09
Scope: Red Bear OS HID stack — all input drivers, HID transport layers, evdev translation, and HID-to-evdev glue
Reference kernel: Linux 7.1 source at local/reference/linux-7.1/
Audited drivers: usbhidd, i2c-hidd, intel-thc-hidd, ps2d, inputd, evdevd, xhcid HID glue

---

1. Executive Summary

The Red Bear OS HID stack is a multi-layer system spanning USB HID transport, I2C HID devices, PS/2 input, an evdev producer library, and a full evdev consumer daemon. Several components are substantially complete; others are clearly incomplete stubs or have large functional gaps.

Driver	Status	Language	Lines	Rating
usbhidd	Partial — hardcoded keyboard only	Rust	895	Incomplete
i2c-hidd	Partial — boot protocol only	Rust	872	Incomplete
intel-thc-hidd	Stub — init + sleep loop only	Rust	434	Stub
ps2d	Moderate — keyboard OK, mouse incomplete	Rust	1188	Partial
inputd (lib)	Decent — evdev producer API	Rust	259	Adequate
evdevd	Substantial — gesture + translation	Rust	3463	Partial
xhcid (HID glue)	Unknown — needs audit	Rust	889	Unknown

Critical finding: The intel-thc-hidd daemon is a pure stub (270 lines, 1 TODO at line 96). The usbhidd driver handles only keyboard from Usage Page 0x07 with hardcoded KEY_* constants and no Report Descriptor parsing. The i2c-hidd driver implements only HID Boot Protocol (keyboard + PS/2-style pointer); Report Protocol HID parsing is absent. The ps2d mouse driver has 16 TODO comments concentrated in mouse.rs and cannot handle Intellimouse2 (4-byte scroll) or touchpad identification.

---

2. Line Counts

###2.1 Input Driver Source Files

File	Lines
local/sources/base/drivers/input/usbhidd/src/main.rs	456
local/sources/base/drivers/input/usbhidd/src/quirks.rs	330
local/sources/base/drivers/input/usbhidd/src/reqs.rs	109
local/sources/base/drivers/input/i2c-hidd/src/acpi.rs	307
local/sources/base/drivers/input/i2c-hidd/src/hid.rs	195
local/sources/base/drivers/input/i2c-hidd/src/input.rs	168
local/sources/base/drivers/input/i2c-hidd/src/main.rs	114
local/sources/base/drivers/input/i2c-hidd/src/quirks.rs	88
local/sources/base/drivers/input/intel-thc-hidd/src/main.rs	270
local/sources/base/drivers/input/intel-thc-hidd/src/quicki2c.rs	86
local/sources/base/drivers/input/intel-thc-hidd/src/thc.rs	78
local/sources/base/drivers/input/ps2d/src/controller.rs	389
local/sources/base/drivers/input/ps2d/src/keymap.rs	177
local/sources/base/drivers/input/ps2d/src/lib.rs	13
local/sources/base/drivers/input/ps2d/src/main.rs	125
local/sources/base/drivers/input/ps2d/src/mouse.rs	387
local/sources/base/drivers/input/ps2d/src/state.rs	377
local/sources/base/drivers/input/ps2d/src/vm.rs	107
local/sources/base/drivers/inputd/src/lib.rs	259
local/sources/base/drivers/inputd/src/main.rs	9
local/sources/base/drivers/usb/xhcid/src/driver_interface.rs	889
local/sources/base/drivers/usb/xhcid/src/lib.rs	30
local/sources/base/drivers/usb/xhcid/src/main.rs	227
Subtotal	5190

2.2 evdevd Source Files

File	Lines
local/recipes/system/evdevd/source/src/device.rs	687
local/recipes/system/evdevd/source/src/gesture.rs	299
local/recipes/system/evdevd/source/src/key_filter.rs	187
local/recipes/system/evdevd/source/src/main.rs	348
local/recipes/system/evdevd/source/src/quirks.rs	83
local/recipes/system/evdevd/source/src/scheme.rs	926
local/recipes/system/evdevd/source/src/translate.rs	539
local/recipes/system/evdevd/source/src/types.rs	394
Subtotal	3463

---

3. Detailed Component Audit

3.1 usbhidd — USB HID Daemon

Files: main.rs (456 lines), quirks.rs (330 lines), reqs.rs (109 lines)
HID parser dependency: rehid crate (report_desc, report_handler, usage_tables)
TODO count: 10

3.1.1 reqs.rs — USB HID Class Requests

reqs.rs implements the standard USB HID class-specific requests (GET_REPORT, SET_REPORT, GET_IDLE, SET_IDLE, GET_PROTOCOL, SET_PROTOCOL). These are correctly implemented against the USB HID spec. No stubs here.

####3.1.2 main.rs — Hardcoded Keyboard Only

main.rs contains a hardcoded keyboard mapping from Usage Page 0x07 (Keyboard) at lines 21–130+. This maps scancodes directly to Linux KEY_* constants using a static array. The mapping covers only the standard104-key layout.

Critical gap: There is no Report Descriptor parsing. The driver does not call rehid to parse the device's Report Descriptor and extract the actual field layout. Instead, it assumes a fixed keyboard layout. This means:

• Any USB keyboard that uses a different Report Descriptor (e.g., media keys, keyboard with additional keys, non-104-key layouts) will not function correctly.
• Consumer Control applications (Usage Page 0x0C) are not handled at all.
• Mouse boot protocol is not implemented (only keyboard).
• Multitouch and digitizer devices are not handled.

Relevant TODO comments:

• Line 214: //TODO: should we do any filtering?
• Line 236: //TODO: do we need to set protocol to report? It fails for mice.
• Line 238: //TODO: dynamically create good values, fix xhcid so it does not block on each request
• Line 258: //TODO: should this be an index into interface_descs?
• Line 304: //TODO: get frequency from device
• Line 305: //TODO: use sleeps when accuracy is better
• Line 330: //TODO: should this be an index into interface_descs?
• Line 363: //TODO: what is X scroll?

3.1.3 quirks.rs — HID Quirk Helpers

quirks.rs defines a Quirks struct with methods for applying HID quirks. The file was read in full. It provides a reasonable quirk infrastructure (NO_INIT_REPORTS, ALWAYS_POLL, NOGET mapped from Linux HID_QUIRK_*). This is a solid foundation but the actual application of quirks is limited by the hardcoded keyboard approach upstream.

3.1.4 Assessment: usbhidd

Rating: Incomplete
The request-layer code (reqs.rs) is correct. The quirk infrastructure is adequate. The core problem is that main.rs does not use the rehid parser to process the device's Report Descriptor — instead it assumes a hardcoded keyboard layout. This is the root cause of all downstream functionality gaps.

---

3.2 i2c-hidd — I2C HID Daemon

Files: hid.rs (195 lines), input.rs (168 lines), main.rs (114 lines), acpi.rs (307 lines), quirks.rs (88 lines)
TODO count: 0 (none found)

3.2.1 hid.rs — I2C HID Transport

hid.rs implements the I2C HID protocol over an I2C transport client. It defines HidDescriptor, ReportDescriptor, and the I2cHid struct with start(), stop(), get_report(), and set_report() methods. This is a clean implementation of the I2C HID transport layer per the HID-I2C specification.

3.2.2 input.rs — Boot Protocol Only

input.rs reads the HID Report Descriptor to extract values but then switches to a hardcoded Boot Protocol interpretation:

• Lines 19–53: Reads HID descriptor fields (vendor ID, product ID, version)
• Lines 55–80: Reads Report Descriptor but only extracts report byte counts
• Lines 85–168: Implements BootKeyboard and BootMouse enums with hardcoded boot protocol parsing

Critical gap: The driver does not implement HID Report Protocol parsing. It falls back to the USB HID Boot Protocol interpretation (keyboard at offset 0, mouse at offset 0 with3-byte packets). Any device that uses Report Protocol (which is the default for modern HID devices) will not have its fields correctly interpreted.

Missing implementations:

• No extraction of Application/Physical/Logical collections from Report Descriptor
• No field enumeration — no mapping of report fields to Linux evdev event types
• Consumer Control (Usage Page 0x0C) not handled
• Digitizer/Multitouch not handled
• Gamepad, joystick, sensor reports not handled

3.2.3 acpi.rs — ACPI Integration

acpi.rs (307 lines) implements ACPI device enumeration for I2C HID devices. This is the most substantial file in the driver. It reads ACPI tables to find I2C HID devices and creates I2cHidDevice instances. This appears to be the most mature component of the i2c-hidd driver.

3.2.4 Assessment: i2c-hidd

Rating: Incomplete
The I2C transport layer (hid.rs) and ACPI integration (acpi.rs) are reasonably complete. The input.rs file implements only HID Boot Protocol — a fallback that was designed in 1996 for basic keyboard and mouse compatibility. Modern HID devices use Report Protocol by default and will not work correctly with this driver.

---

3.3 intel-thc-hidd — Intel THC HID Daemon

Files: main.rs (270 lines), quicki2c.rs (86 lines), thc.rs (78 lines)
TODO count: 1
Status: STUB

intel-thc-hidd is a stub daemon. The main.rs file contains only initialization code and a sleep loop. The single TODO at line 96 states:

// TODO(intel-thc-hidd): decode HID reports from i2cd transfers and

The thc.rs file implements MMIO register access to the Intel THC (Targeted Hardware Compatibility) controller — this is low-level hardware access code and appears complete. The quicki2c.rs file implements a Quick I2C transaction helper.

Critical gap: The daemon does not decode any HID reports. It initializes the THC hardware and then sleeps forever. No HID parsing, no input event generation, no evdev production.

Assessment: Stub
This is a placeholder daemon. The TODO comment explicitly states the missing functionality. This is a legitimate stub — the hardware register definitions are present but the HID report decoding logic is entirely absent.

---

3.4 ps2d — PS/2 Controller Daemon

Files: controller.rs (389 lines), keymap.rs (177 lines), lib.rs (13 lines), main.rs (125 lines), mouse.rs (387 lines), state.rs (377 lines), vm.rs (107 lines)
TODO count: 16

3.4.1 keymap.rs — Scancode Set 1 Only

keymap.rs provides ps2_scancode_to_linux_keycode() and ps2_extended_scancode_to_linux_keycode() functions. These map PS/2 scancode Set 1 and its extended prefix (0xE0) to Linux keycodes. This covers the vast majority of PS/2 keyboards.

Gap: Scancode Sets 2 and 3 are not implemented. Most modern PS/2 keyboards support Set 1 only, but some specialized keyboards may use Set 2 or Set 3.

3.4.2 mouse.rs — Intellimouse2 Not Supported

mouse.rs has extensive TODO comments indicating incomplete mouse support:

Line	TODO
84	//TODO: support this mouse type (Intellimouse2, 0x04)
143	//TODO: retry reset?
158	//TODO: reset mouse?
173	//TODO: reset mouse instead?
187	//TODO: reset mouse instead?
246	//TODO: enable port in this case, mouse hotplug may send 0xAA 0x00
284	//TODO: handle touchpad identification
307	//TODO: check response
325	//TODO: handle this separately?
337	//TODO: handle response ok/error
363	//TODO: retry?
368	//TODO: retry?
382	//TODO: limit number of retries

Critical gap: Intellimouse2 (4-byte mouse packets with scroll wheel and buttons 4/5) is explicitly marked as unsupported at line 84. This is a significant functional gap for modern mice.

3.4.3 controller.rs — Single unimplemented!() at Line 132

controller.rs has one unimplemented!() at line 132. All other code is implemented. The controller implements the full PS/2 command/response protocol including keyboard and mouse channels.

3.4.4 state.rs — VMMouse Partial Implementation

state.rs handles VMMouse (VMware mouse) absolute pointer emulation. The implementation appears partial — only relative mode is enabled (line 62: vmmouse_relative = false is set but the field is unused). The absolute pointer path is present but gated behind vmmouse_relative = false.

3.4.5 Assessment: ps2d

Rating: Partial
Keyboard support is solid. Mouse support is functional for basic 3-byte mice but Intellimouse2 (4-byte scroll mice) is explicitly unimplemented. The VMMouse absolute pointer has partial implementation. The16 TODO comments indicate ongoing work rather than abandoned stubs.

---

3.5 inputd — Evdev Producer Library

Files: lib.rs (259 lines), main.rs (9 lines, deprecated)
TODO count: 0

inputd is a library that provides the EvdevProducerHandle API for drivers to write evdev events. The lib.rs defines event type constants (EV_KEY, EV_REL, EV_ABS, EV_SYN), key constants (KEY_, BTN_, REL_, ABS_), and the producer handle interface.

Assessment: Adequate
The producer API is a clean abstraction. The main.rs is a deprecated no-op (9 lines). The library itself is the relevant artifact.

---

3.6 evdevd — Evdev Consumer Daemon

Files: device.rs (687 lines), gesture.rs (299 lines), key_filter.rs (187 lines), main.rs (348 lines), quirks.rs (83 lines), scheme.rs (926 lines), translate.rs (539 lines), types.rs (394 lines)
TODO count: Unknown (grep not run)

evdevd is the most substantial daemon in the HID stack. The scheme.rs (926 lines) implements the scheme handler for /scheme/input/event*. The device.rs (687 lines) manages device state. The translate.rs (539 lines) handles HID-to-evdev translation. The gesture.rs (299 lines) handles gesture recognition. The key_filter.rs (187 lines) handles key filtering.

Assessment: Partial
This daemon has significant structure and real implementation. The gesture.rs and key_filter.rs modules suggest non-trivial functionality. However, the translate.rs module (which was not read in full) is the critical path for HID-to-evdev translation — gaps there would mean incorrect event mapping even if HID parsing were complete.

---

3.7 xhcid — USB HID Glue in xHCI Driver

File: local/sources/base/drivers/usb/xhcid/src/driver_interface.rs (889 lines)
TODO count: Unknown (grep not run)

driver_interface.rs is part of the xHCI USB host controller driver. This file handles USB HID class devices at the xHCI level. The HID-specific glue code was not read in detail during this audit session. This is a critical gap — the xhcid driver is the transport layer for USB HID devices and any bugs or missing HID handling there would prevent devices from being detected at all.

Assessment: Unknown
This file needs dedicated audit time. The xHCI driver handles USB device enumeration, endpoint management, and bulk/interrupt transfers. HID-specific handling (interface selection, interrupt IN endpoint polling) lives here.

---

4. HID-to-evdev Translation Analysis

4.1 Linux Reference: hid-input.c

Linux hid-input.c implements the standard HID-to-evdev translation layer. Key patterns:

1. Report Descriptor parsing: Linux parses the Report Descriptor using hid_parse_report() to extract field collections, usages, and value ranges.

2. Usage page mapping: Each Usage Page has a dedicated handler:

   • 0x01 (Generic Desktop) → keyboard, mouse, joystick, gamepad, tablet
   • 0x02 (Simulation) → steering wheels, rudder pedals
   • 0x06 (Telephony) → phone keys
   • 0x07 (Keyboard) → keyboard key mapping (full)
   • 0x08 (LEDs) → output-only, no evdev events
   • 0x09 (Button) → BTN_* events
   • 0x0C (Consumer Control) → consumer control keys (volume, play/pause, etc.)
   • 0x0F (Digitizers) → tablet, touchpad, smart card readers
   • 0x10 (Barcode scanners, etc.)
   • 0x11 (Mouse) → mouse-specific BTN_* events
   • 0x12 (Joystick) → joystick mapping
   • 0x13 (Game Pad) → gamepad mapping
   • 0x14 (Tablet) → tablet mapping
   • 0x80 (Monitor) → monitor controls
   • 0x81 (Computer System) → system controls
   • 0x82 (Power Device) → power management

3. Consumer Control mapping: Linux maps consumer control usages (Usage Page 0x0C) to a fixed consumer control map (音量、静音、再生、停止 etc.) via hidinput_map_usage().

4. Field handling: Linux tracks field state (previous value vs current value) to generate KEY_UP/KEY_DOWN events rather than raw values.

4.2 Red Bear OS Gaps vs Linux

HID Feature	Linux (hid-input.c)	Red Bear OS
Report Descriptor parsing	Full (hid_parse_report)	Partial (rehid available but not used in usbhidd)
Usage Page 0x01 (Generic Desktop)	Full keyboard/mouse/joystick	Hardcoded keyboard only
Usage Page 0x07 (Keyboard)	Full (104-key + international)	Hardcoded 104-key
Usage Page 0x09 (Button)	Full	Not implemented
Usage Page 0x0C (Consumer Control)	Full	Not implemented
Usage Page 0x0F (Digitizer)	Full	Not implemented
Usage Page 0x11 (Mouse)	Full	Not implemented
Multitouch (Protocol A/B)	Full (hid-multitouch.c)	Not implemented
System Control (Power, Sleep)	Full	Not implemented
Joystick/Gamepad	Full	Not implemented
HID LEDs	Output only	Not implemented
HID sensors (Usage Page 0x20)	Partial	Not implemented

---

5. Stubs Summary

###5.1 Confirmed Stubs

Component	File	Line	Description
intel-thc-hidd main loop	intel-thc-hidd/src/main.rs	96	// TODO(intel-thc-hidd): decode HID reports from i2cd transfers and — entire HID decoding path missing
ps2d Intellimouse2	ps2d/src/mouse.rs	84	//TODO: support this mouse type —4-byte scroll mouse not implemented
ps2d controller	ps2d/src/controller.rs	132	unimplemented!() — one command path not implemented
ps2d VM mouse	ps2d/src/vm.rs	68	unimplemented!() — VM mouse interface stub

5.2 Functional Gaps (Not Stubs, But Missing Features)

Component	Gap	Severity
usbhidd	No Report Descriptor parsing — hardcoded keyboard only	High
usbhidd	No Consumer Control (Usage Page 0x0C) support	High
usbhidd	No mouse boot protocol	High
usbhidd	No multitouch/digitizer support	High
i2c-hidd	No Report Protocol HID parsing — boot protocol only	High
i2c-hidd	No Consumer Control support	High
ps2d	Scancode Sets 2 and 3 not implemented	Low
ps2d	Touchpad identification not implemented	Medium
evdevd	translate.rs not audited — translation gaps unknown	Medium
xhcid	HID glue not audited — detection gaps unknown	High

---

6. Recommendations

###6.1 Immediate (1–2 weeks)

1. intel-thc-hidd: Either implement the HID report decoding path or remove the daemon and add a comment that it awaits THC hardware.
2. usbhidd mouse: Implement USB HID boot protocol mouse handling (separate from keyboard path).
3. ps2d Intellimouse2: Implement4-byte mouse packet parsing for scroll wheel and buttons 4/5.

6.2 Short-term (1–3 months)

4. usbhidd Report Descriptor parsing: Integrate rehid Report Descriptor parsing into usbhidd's main.rs to dynamically extract field layouts instead of hardcoding keyboard-only.
5. Consumer Control support: Add Usage Page 0x0C handling to both usbhidd and i2c-hidd to support media keys (volume, play/pause, etc.).
6. i2c-hidd Report Protocol: Extend input.rs to parse HID Report Protocol reports, not just boot protocol.
7. ps2d Scancode Sets 2 and 3: Add keymap entries for scancode sets 2 and 3 as fallback for non-standard keyboards.

6.3 Medium-term (3–6 months)

8. evdevd translate.rs audit: Full code review of translate.rs against Linux hid-input.c to identify missing usage page handlers.
9. xhcid HID glue audit: Full code review of xhcid driver_interface.rs for HID-specific handling.
10. Multitouch support: Implement HID Multitouch (Protocol A and B) in a new driver or by extending usbhidd/i2c-hidd.
11. Digitizer support: Add Usage Page 0x0F (Digitizers) support for tablets and touchscreens.

---

Appendix A: File Locations

local/sources/base/drivers/input/usbhidd/src/
  main.rs       —456 lines — hardcoded keyboard HID parsing
  quirks.rs     — 330 lines — HID quirk helpers
  reqs.rs       — 109 lines — USB HID class requests

local/sources/base/drivers/input/i2c-hidd/src/
  main.rs       — 114 lines — daemon entry point
  hid.rs        — 195 lines — I2C HID transport layer
  input.rs      — 168 lines — boot protocol only (GAP)
  acpi.rs       — 307 lines — ACPI device enumeration
  quirks.rs     —  88 lines — HID quirk helpers

local/sources/base/drivers/input/intel-thc-hidd/src/
  main.rs       — 270 lines — STUB: init + sleep only
  quicki2c.rs   —  86 lines — Quick I2C transaction helper
  thc.rs        —  78 lines — THC MMIO register access

local/sources/base/drivers/input/ps2d/src/
  main.rs       — 125 lines — daemon entry point
  controller.rs — 389 lines — PS/2 controller (1 unimplemented!)
  keymap.rs     — 177 lines — scancode set 1 only (GAP)
  mouse.rs      — 387 lines — 16 TODOs, Intellimouse2 missing
  state.rs      — 377 lines — VMMouse partial
  vm.rs         — 107 lines — 1 unimplemented!()

local/sources/base/drivers/inputd/src/
  lib.rs        — 259 lines — evdev producer API
  main.rs       —   9 lines — deprecated no-op

local/recipes/system/evdevd/source/src/
  main.rs       — 348 lines — daemon entry point
  device.rs     — 687 lines — device state management
  scheme.rs     — 926 lines — scheme handler
  translate.rs  — 539 lines — HID-to-evdev translation (needs audit)
  gesture.rs    — 299 lines — gesture recognition
  key_filter.rs — 187 lines — key filtering
  quirks.rs     —  83 lines — evdev quirks
  types.rs      — 394 lines — type definitions

local/sources/base/drivers/usb/xhcid/src/
  main.rs               — 227 lines — xHCI daemon
  lib.rs                —  30 lines — library interface
  driver_interface.rs   — 889 lines — USB HID glue (needs audit)

---

Appendix B: Reference Source Paths

local/reference/linux-7.1/drivers/hid/hid-core.c
local/reference/linux-7.1/drivers/hid/hid-input.c
local/reference/linux-7.1/drivers/hid/hid-quirks.c
local/reference/linux-7.1/drivers/hid/hid-multitouch.c
local/reference/linux-7.1/drivers/hid/usbhid/hid-core.c
local/reference/linux-7.1/drivers/hid/i2c-hid/i2c-hid-core.c