vasilito
e586a44be6
BOOT-PROCESS-SECOND-AUDIT-2026-05-03.md: deep dive into: - D-Bus implementation honesty (15/19 login1 methods real, not stubs) - ion shell quality matrix (vs bash/dash) - Login prompt completeness (getty→login→ion chain) - Per-subsystem hardware init status (storage/display/input/network/USB/audio/ACPI) - Implementation plan Phases F1-F6 Archived 4 completed/deferred plans: GRUB, VFAT, USB-BOOT-INPUT, ZSH-PORTING
170 lines
6.3 KiB
Markdown
170 lines
6.3 KiB
Markdown
# USB Boot Input Plan
|
|
|
|
## Goal
|
|
|
|
Make external USB keyboards a reliable bare-metal boot fallback for Red Bear OS.
|
|
|
|
This is a boot-resilience requirement, not optional polish. A system that reaches early
|
|
boot but cannot accept keyboard input on modern hardware is not a complete live/recovery
|
|
environment.
|
|
|
|
## Current Assessment
|
|
|
|
### What works today
|
|
|
|
- `xhcid` is the only host-controller path with a real runtime device model.
|
|
- `xhcid` spawns `usbhubd` and `usbhidd` via class matching.
|
|
- `usbhidd` reads HID input reports and forwards keyboard/mouse events into `inputd`.
|
|
|
|
This means USB keyboard input can work today only when the keyboard is reached through the
|
|
`xHCI -> usbhubd/usbhidd -> inputd` path.
|
|
|
|
### What does not work today
|
|
|
|
- `ehcid` is still an ownership / handoff / port-state daemon, not a real runtime host stack.
|
|
- `uhcid` is still ownership + port reset + logging only; full scheduling/enumeration is explicitly
|
|
not implemented.
|
|
- `ohcid` is in the same state as `uhcid`.
|
|
|
|
The code is explicit about this:
|
|
|
|
- `ehcid`: connected EHCI-owned ports still fail with "EHCI enumeration is still not implemented"
|
|
- `uhcid`: connected ports still fail with "runtime enumeration is still not implemented"
|
|
- `ohcid`: connected ports still fail with "OHCI enumeration is still not implemented"
|
|
|
|
### Important practical consequence
|
|
|
|
An external USB keyboard on bare metal is **not guaranteed** to appear through `xHCI`.
|
|
|
|
It may instead land on:
|
|
|
|
- an EHCI root-hub path
|
|
- a UHCI/OHCI companion path after EHCI handoff
|
|
- a firmware/routing topology where low/full-speed devices do not end up on the `xHCI` runtime path
|
|
|
|
On such systems, the current code can detect controller ownership and connected ports, but still
|
|
cannot produce a real keyboard input path.
|
|
|
|
### LED state is a separate and weaker path
|
|
|
|
`usbhidd` now has a bounded best-effort HID output-report path for keyboard LEDs. It toggles
|
|
`Caps Lock`, `Num Lock`, and `Scroll Lock` locally on keydown and sends a one-byte HID output
|
|
report via `SET_REPORT`.
|
|
|
|
This is useful, but it is **not** the same as a complete global keyboard lock-state authority:
|
|
|
|
- it is per-device, not system-global
|
|
- it is best-effort and disables itself after the first device-side failure
|
|
- it does not solve missing USB enumeration on non-xHCI host-controller paths
|
|
|
|
So dead `Caps Lock` / `Num Lock` indicators still do **not** prove that keyboard transport is dead,
|
|
and working LEDs do **not** prove that the external USB keyboard fallback problem is solved.
|
|
|
|
## Root-Cause Summary For Current Bare-Metal Symptom
|
|
|
|
When a USB-attached keyboard does not bring up input during boot, the most likely causes are:
|
|
|
|
1. the keyboard is not on the `xHCI` runtime path
|
|
2. it lands on `EHCI/UHCI/OHCI`, where enumeration is not implemented yet
|
|
3. even if input later works, keyboard LEDs may still be misleading because LED sync is only a
|
|
bounded per-device best-effort path
|
|
|
|
## Current Structural Gap
|
|
|
|
There is also a policy gap:
|
|
|
|
- `ehcid`, `uhcid`, and `ohcid` contain `--strict-boot` logic
|
|
- and the current boot path still does **not** hardcode `--strict-boot` in initfs driver command lines
|
|
- however, strict mode can now be enabled through `REDBEAR_STRICT_USB_BOOT=1`, which is inherited by
|
|
`pcid-spawner` service units and then by legacy USB controller daemons
|
|
|
|
So the code contains a boot-guard concept that is currently not activated by the initfs spawn path.
|
|
|
|
This does not create input support by itself, but it does matter for observability and boot policy.
|
|
|
|
## Execution Order
|
|
|
|
### Phase U-B1: Make boot policy honest
|
|
|
|
Deliverables:
|
|
|
|
- decide whether initfs should pass `--strict-boot` to legacy USB host daemons
|
|
- provide a non-invasive runtime toggle for strict mode during bring-up
|
|
- if enabled, make the failure mode explicit and bounded
|
|
- if not enabled, log clearly that legacy USB ownership exists without runtime enumeration
|
|
|
|
Acceptance:
|
|
|
|
- the boot log makes it obvious whether the system has a usable USB keyboard path or only controller
|
|
ownership
|
|
- strict mode can be enabled without rewriting driver command lines
|
|
|
|
### Phase U-B2: Finish legacy host runtime enumeration
|
|
|
|
Deliverables:
|
|
|
|
- implement real device enumeration for `uhcid`
|
|
- implement real device enumeration for `ohcid`
|
|
- implement real runtime ownership of low/full-speed devices behind `ehcid` companion routing
|
|
|
|
Acceptance:
|
|
|
|
- a low/full-speed USB keyboard on bare metal can reach `usbhidd` through the legacy host path
|
|
|
|
### Phase U-B3: Keep one HID class path
|
|
|
|
Deliverables:
|
|
|
|
- avoid inventing a second HID stack just for legacy controllers
|
|
- make legacy host controllers feed the existing USB class-driver model
|
|
- keep `usbhidd` and `usbhubd` as the class daemons above controller-specific ownership
|
|
|
|
Acceptance:
|
|
|
|
- keyboard class handling is shared regardless of host controller family
|
|
|
|
### Phase U-B4: Implement keyboard LED output
|
|
|
|
Deliverables:
|
|
|
|
- keep the new HID output-report support in `usbhidd` bounded and non-fatal
|
|
- decide whether the current per-device local toggle model is sufficient, or whether Red Bear
|
|
later needs a system-authoritative lock-state surface
|
|
- preserve the rule that LED sync must never block or destabilize keyboard input
|
|
|
|
Acceptance:
|
|
|
|
- LED state tracks keyboard lock state on at least one supported USB keyboard in the current
|
|
bounded per-device model
|
|
|
|
### Phase U-B5: Validation
|
|
|
|
Deliverables:
|
|
|
|
- QEMU validation for xHCI remains
|
|
- add bounded validation for legacy host-controller paths where feasible
|
|
- require bare-metal validation on systems where external USB keyboard currently fails
|
|
|
|
Acceptance:
|
|
|
|
- one xHCI bare-metal proof
|
|
- one EHCI/UHCI/OHCI-involved bare-metal proof
|
|
- explicit evidence that external USB keyboard input reaches login
|
|
|
|
## Design Rules
|
|
|
|
- do not treat controller ownership as equivalent to device enumeration
|
|
- do not treat keyboard LED state as equivalent to keyboard input health
|
|
- reuse the existing HID class-driver path instead of splitting per-controller userland stacks
|
|
- prefer bounded boot-policy checks and explicit failure logs over silent partial bring-up
|
|
|
|
## Priority Judgment
|
|
|
|
For bare-metal boot resilience, the correct order is:
|
|
|
|
1. finish legacy USB host runtime enumeration
|
|
2. then add keyboard LED output reports
|
|
3. in parallel, continue `I2C-HID` for internal modern laptop keyboards/touchpads
|
|
|
|
External USB keyboard fallback and internal `I2C-HID` are complementary. Red Bear needs both.
|