vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive boot process audit + archive stale plans

Browse Source 
BOOT-PROCESS-AUDIT-2026-05-03.md: full daemon-by-daemon review
of boot sequence from power-on to login prompt. Covers:
- 25+ daemons assessed (critical path, input, display, hardware,
  storage, network, audio, UI, system services)
- Hardware initialization completeness matrix
- ion shell analysis (strengths/gaps vs bash/dash)
- Stale documentation inventory

Archived 5 superseded plans to local/docs/archived/:
- ACPI-I2C-HID, BOOT-PROCESS-IMPROVEMENT, DEVICE-INIT,
  GREETER-LOGIN-ANALYSIS, INTEL-HDA-IMPLEMENTATION

Improvement plan: 5 phases (boot reliability, drivers, UX,
documentation, security) across 6 weeks
This commit is contained in:
Vasilito
2026-05-03 08:47:24 +01:00
parent 8cb90c97a5
commit 1c7ce83173
7 changed files with 267 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/docs/archived/ACPI-I2C-HID-IMPLEMENTATION-PLAN.md
+339
View File
@@ -0,0 +1,339 @@
# ACPI I2C / I2C-HID Implementation Plan
## Goal
Implement a real laptop-class ACPI I2C stack for Red Bear OS, with `I2C-HID via ACPI`
as the first user-visible deliverable. This is required for modern touchpads, keyboards,
and other embedded input devices that are no longer exposed via PS/2.
The shortest correct path is:
`ACPI _CRS decode` -> `I2C controller ownership` -> `I2C bus API/scheme` -> `i2c-hidd` ->
`inputd integration`
This work must be treated as bare-metal boot-critical substrate, not as optional polish.
## Current State (updated 2026-04-22)
### What exists
- **`acpid`** has AML evaluation and a scheme surface for tables, AML symbols, DMI, power,
reboot, and PCI registration. `acpid/src/resources.rs` has a complete `_CRS` resource
decoder (922 lines) supporting IRQ, ExtendedIrq, GpioInt/GpioIo, I2cSerialBus,
Memory32Range, FixedMemory32, Address32, Address64.
- **`/scheme/acpi/resources/<device>`** endpoint (IN PROGRESS) — acpid's `decode_resource_template()`
exists but is not yet wired into the scheme surface. This is the #1 remaining gap.
- **`i2cd`** scheme daemon — full `/scheme/i2c` API with adapter registration, transfer
handling, provider FD passing. Located at `drivers/i2c/i2cd/`.
- **`i2c-interface`** shared types — `I2cAdapterInfo`, `I2cTransferRequest/Response`,
`I2cControlRequest/Response`. Located at `drivers/i2c/i2c-interface/`.
- **Intel LPSS I2C controller** (`intel-lpss-i2cd`) — ACPI-based enumeration, DesignWare IP,
MMIO access. Registers as adapter with i2cd.
- **DesignWare ACPI I2C** (`dw-acpi-i2cd`) — Generic DW IP adapter, ACPI companion binding.
- **AMD MP2 I2C** (`amd-mp2-i2cd`) — AMD Picasso/Renoir platform I2C via MP2.
- **`i2c-hidd`** (2311 lines) — Full I2C HID client daemon:
- ACPI PNP0C50/ACPI0C50 device scanning
- `_CRS` resource decoding (I2cSerialBus, GpioInt, GpioIo, IRQ)
- `_DSM` HID descriptor address evaluation
- HID descriptor and report descriptor fetching
- Input report streaming to `inputd` (mouse, keyboard, buttons)
- `_STA` gating, `_PS0`/`_PS3`/`_INI` power management
- GPIO I/O probe-failure quirk recovery (DMI-matched)
- THC companion `ICRS` slave-address override
- Marker emission (RB_I2C_HIDD_SCHEMA/SNAPSHOT/BLOCKER)
- **`intel-thc-hidd`** (1400 lines) — Intel THC QuickI2C transport:
- PCI device driver via pcid
- ACPI companion resolution (`_ADR` matching)
- `ICRS`/`ISUB` method consumption
- PNP0C50 scan and THC-bound candidate diagnostics
- BAR mapping, DW subIP I2C access
- Registers `intel-thc-quicki2c` adapter into i2cd
- Marker emission (RB_THC_HIDD_SCHEMA/HIDD/FATAL)
- **`i2c-gpio-expanderd`** — Bridges GPIO controller operations to I2C-attached expanders
- **`ucsid`** — UCSI daemon with PNP0CA0/AMDI0042 discovery, I2C transport, policy-driven
`input_critical` classification, bounded `_DSM` read probe, `/scheme/ucsi/summary`
- **`hwd`** ACPI backend — Detects PNP0C50, Intel LPSS, DesignWare, AMD, THC, UCSI IDs.
Emits RB_THC_QUICKI2C, RB_UCSI_* markers. Consumes `/scheme/ucsi/summary`.
- **`amlserde`** — AML serialization/deserialization, including `AmlSerdeValue::Buffer`
(needed for `_CRS`), `RegionSpace::GenericSerialBus` for I2C/SMBus opregions.
- **Init services** — `redbear-mini.toml` wires `i2cd`, `i2c-hidd`, `i2c-dw-acpi`,
`i2c-gpio-expanderd`, `intel-gpiod`, `ucsid` with non-blocking startup ordering.
### What is missing (active gaps)
1. **`/scheme/acpi/resources/<device>` scheme endpoint** — `acpid` has the decoder
(`decode_resource_template()`) but does not expose it through the scheme. Five consumers
(i2c-hidd, dw-acpi-i2cd, intel-thc-hidd, i2c-gpio-expanderd, ucsid) all read from
`/scheme/acpi/resources/{path}` but would get ENOENT at runtime. This is the #1 blocker.
2. **Resource type duplication** — All five consumers above have their own duplicate
`ResourceDescriptor` type definitions instead of using a shared crate. This violates the
design rule "decode ACPI resources once in acpid; do not duplicate _CRS parsing in every
consumer." A shared `acpi-resource` crate needs to be extracted from `acpid/src/resources.rs`
and adopted by all consumers.
3. **`_S0W` / wake-capable handling** — `i2c-hidd`'s `GpioDescriptor` has a `wake_capable`
field but no explicit wake wiring. `_S0W` evaluation is not implemented. These are
sleep/resume features, not boot-critical.
4. **GenericSerialBus / SMBus opregion support** — Not yet implemented. Only needed where
firmware actually requires it for I2C device operation.
5. **Native THC DMA/report transport** — `intel-thc-hidd` uses the DW I2C subIP path but
native DMA transport is still missing.
6. **Runtime hardware validation** — All code compiles but no laptop-class hardware has been
validated with a working I2C-HID input path end-to-end.
### Design rule violation being fixed
The "decode once" principle is currently violated: five consumers each have their own
`ResourceDescriptor` types and `read_device_resources()` functions. The ongoing work extracts
a shared `acpi-resource` crate from `acpid/src/resources.rs` and refactors all consumers to
use it.
## Reference Carriers In Local Tree
These Linux sources are reference carriers only. They should guide design and descriptor
semantics, but should not be transliterated blindly.
- `build/linux-kernel-cache/linux-7.0/drivers/hid/i2c-hid/i2c-hid-acpi.c`
- `build/linux-kernel-cache/linux-7.0/drivers/hid/i2c-hid/i2c-hid-core.c`
- `build/linux-kernel-cache/linux-7.0/drivers/i2c/i2c-core-acpi.c`
- `build/linux-kernel-cache/linux-7.0/drivers/acpi/resource.c`
- `build/linux-kernel-cache/linux-7.0/drivers/mfd/intel-lpss-pci.c`
- `build/linux-kernel-cache/linux-7.0/drivers/mfd/intel-lpss-acpi.c`
- `build/linux-kernel-cache/linux-7.0/drivers/i2c/busses/i2c-designware-amdpsp.c`
- `build/linux-kernel-cache/linux-7.0/drivers/i2c/busses/i2c-amd-mp2-pci.c`
## Execution Order
### Phase A: ACPI `_CRS` substrate — IN PROGRESS
Deliverables:
- add decoded ACPI resource support in `acpid`
- expose decoded device resources through `/scheme/acpi/resources/<device>`
- support at minimum:
- IRQ
- Extended IRQ
- GPIO interrupt
- GPIO I/O
- `I2cSerialBus`
Current status:
- ✅ `acpid/src/resources.rs` — complete `_CRS` decoder (922 lines)
- ✅ `decode_resource_template()` function with all descriptor types
- 🚧 `/scheme/acpi/resources/<device>` endpoint — decoder exists but not wired into scheme
- 🚧 `acpi-resource` shared crate — extracting from acpid to eliminate duplication in 5 consumers
Acceptance:
- a consumer can query decoded resources for a device path without reimplementing AML
resource decoding
- known laptop devices show valid controller link, slave address, and interrupt metadata
### Phase B: Native I2C substrate — COMPLETE
Deliverables:
- add a small `i2cd` scheme / API
- support controller registration, transfers, and per-device addressing
- keep scope tight; do not clone Linux I2C core complexity
Current status:
- ✅ `i2cd` — full `/scheme/i2c` scheme with adapter registry, transfers, provider FD passing
- ✅ `i2c-interface` — shared types (I2cAdapterInfo, I2cTransferRequest, I2cControlRequest)
- ✅ Controller registration and transfer API working
Acceptance:
- ✅ a userspace daemon can open an adapter and issue I2C transfers using a stable Red Bear API
### Phase C: Intel laptop controller path — COMPLETE
Deliverables:
- add Intel LPSS / Serial IO I2C controller ownership first
Current status:
- ✅ `intel-lpss-i2cd` — Intel LPSS/SerialIO I2C controller with DesignWare IP
- ✅ `dw-acpi-i2cd` — DesignWare ACPI-bound I2C adapter
- ✅ Both register with i2cd and provide transfer capability
Acceptance:
- compile-visible: ✅ at least one Intel controller driver registers a usable I2C adapter
- runtime: ❌ no bare-metal validation yet
### Phase D: `i2c-hidd` — COMPLETE (compile-visible)
Deliverables:
- bind ACPI `PNP0C50` / `ACPI0C50`
- evaluate `_DSM` using the HID-over-I2C GUID to retrieve the HID descriptor address
- fetch HID descriptor and report descriptor via I2C
- stream input reports into `inputd`
Current status:
- ✅ `i2c-hidd` — 2311-line daemon with full ACPI scanning, _DSM, HID protocol, input streaming
- ✅ `intel-thc-hidd` — 1400-line THC QuickI2C transport daemon
- ✅ Both have marker emission for boot-log diagnostics
Acceptance:
- compile-visible: ✅ all code builds
- runtime: ❌ no laptop touchpad or keyboard has produced usable events yet (blocked by Phase A)
### Phase E: AMD controller path — COMPLETE (compile-visible)
Deliverables:
- add AMD laptop-class I2C controller support
- likely DesignWare / MP2 mediated paths depending on platform
Current status:
- ✅ `amd-mp2-i2cd` — AMD MP2 I2C controller driver
- ✅ `dw-acpi-i2cd` also handles AMD DesignWare IDs (AMDI0010, AMDI0019, AMDI0510)
Acceptance:
- compile-visible: ✅ AMD controller driver exists and registers with i2cd
- runtime: ❌ no AMD laptop validated
### Phase F: Remaining ACPI I2C functions — PARTIALLY COMPLETE
Deliverables and status:
| Feature | Status | Detail |
|---------|--------|--------|
| `_STA` gating before bind | ✅ | `i2c-hidd:prepare_acpi_device()` checks presence bit |
| `_INI` where required | ✅ | Evaluated after `_PS0` in `prepare_acpi_device()` |
| `_PS0` / `_PS3` power transitions | ✅ | `prepare_acpi_device()` and `recover_acpi_device()` |
| `GpioInt`/`GpioIo` reset | ✅ | DMI-matched GPIO I/O probe-failure quirk recovery |
| `_S0W` / wake-capable | ❌ | `wake_capable` field exists but not wired; `_S0W` not evaluated |
| GpioInt wake wiring | ❌ | Wake interrupt path not implemented |
| GenericSerialBus opregion | ❌ | Not needed for boot; only where firmware requires it |
Acceptance:
- boot-critical items (STA, PS0, PS3, GPIO reset): ✅
- sleep/resume items (S0W, wake, opregion): ❌ deferred until sleep/resume is in scope
## Design Rules
- prefer a small, explicit Red Bear userspace API over Linux-core emulation
- decode ACPI resources once in `acpid`; do not duplicate `_CRS` parsing in every consumer
- make controller ownership data-driven through decoded ACPI resources where possible
- keep laptop input as a boot-resilience feature, not a desktop-only feature
- treat Intel and AMD laptops as equal-priority hardware targets
## Other Boot-Relevant I2C Device Classes
`I2C-HID` is the first and most important I2C deliverable, but it is not the only I2C-related
surface that can matter during boot on modern bare metal.
### Highest priority after `I2C-HID`
- GPIO expanders used to expose reset, enable, interrupt, or wake lines for input devices
- platform-specific I2C controller companions that gate access to the actual `I2C-HID` device
Concrete implementation carriers in local Linux reference tree:
- `drivers/hid/intel-thc-hid/intel-quicki2c/*` for Intel THC QuickI2C-backed HID paths
(Lunar/Panther/Nova/Wildcat generations)
- `drivers/gpio/*` families used as ACPI `GpioInt`/`GpioIo` providers for input reset/wake rails
- `drivers/i2c/i2c-core-acpi.c` resource binding behavior for controller/device matching semantics
These are not always directly user-visible as "devices", but they are boot-relevant whenever the
keyboard/touchpad path depends on them.
### Sometimes boot-relevant
- USB-C / UCSI / PD related I2C-attached endpoints on platforms where a USB-C attached keyboard or
dock path is firmware-mediated and not available without those services
- embedded controller-adjacent I2C peripherals that gate keyboard/touchpad power or wake routing
These should be treated as platform-dependent bring-up work, not as universal phase-1 targets.
### Not first-order blockers for reaching login
- sensors (accelerometer, gyro, ambient light)
- battery / charger / fuel-gauge devices
- camera-side I2C devices
- most audio codecs and amplifier control devices
- thermal and fan-adjacent I2C sensors
These matter for full laptop support, but they do not outrank keyboard/touchpad bring-up for live
boot and recovery.
## Boot Priority Order
For boot-to-login on modern laptops, the correct priority is:
1. `I2C-HID` keyboards and touchpads
2. any GPIO-expander or companion I2C devices required to make those devices usable
3. platform-specific USB-C / UCSI I2C surfaces only on machines that actually depend on them for
input availability
4. all other I2C-attached peripherals
## Immediate Next Steps
1. ~~land `_CRS` decoding in `acpid`~~ ✅ (decoder exists)
2. expose decoded resources under `/scheme/acpi/resources/` ← **ACTIVE WORK**
3. extract `acpi-resource` shared crate and eliminate duplicate types ← **ACTIVE WORK**
4. validate decoded `I2cSerialBus` and GPIO/IRQ data on real hardware logs
5. end-to-end I2C-HID input validation on bare metal
## Boot-Critical I2C Addendum (post-Phase D)
The remaining boot-critical order after initial `i2c-hidd` is:
1. Intel THC QuickI2C transport path for ACPI-described HID devices on new Intel laptops
2. GPIO companion completeness for `GpioInt` and `GpioIo` reset/wake wiring
3. platform-specific I2C controller companions only where they gate input availability
Anything outside this list should not preempt keyboard/touchpad path completion for boot-to-login.
### Concrete device classes to implement next (boot-first order)
| Priority | Device class | Linux carrier in tree | Red Bear status |
|---|---|---|---|
| P0 | Intel THC QuickI2C transport (`HID over THC`) | `drivers/hid/intel-thc-hid/intel-quicki2c/*` | ✅ detection, BAR mapping, DW subIP adapter registration landed; native DMA transport still missing |
| P1 | GPIO companions for `GpioInt`/`GpioIo` (reset/wake rails) | `drivers/gpio/*`, ACPI resource flow | ✅ GPIO I/O probe-failure quirk recovery landed; wake wiring still missing |
| P2 | Controller-companion ACPI methods (`_DSM/_DSD`) that gate input | `i2c-core-acpi.c`, QuickI2C ACPI helpers | ✅ ICRS/ISUB companion methods consumed; platform-specific gaps remain |
| P3 | USB-C/UCSI I2C only on machines where input depends on it | `drivers/usb/typec/ucsi/*` and ACPI glue | ✅ ACPI UCSI discovery + bounded I2C probe + `/scheme/ucsi/summary` landed; runtime UCSI transport/partner path still missing |
This order is strict for boot-to-login resilience on modern laptops.
## Marker Emission Summary
The I2C stack uses structured marker lines for CI/log scraping:
| Producer | Marker | Purpose |
|----------|--------|---------|
| `hwd` | `RB_THC_QUICKI2K_SCHEMA` / `RB_THC_QUICKI2K` | THC companion readiness |
| `hwd` | `RB_UCSI_SCHEMA` / `RB_UCSI_SNAPSHOT` / `RB_UCSI_SUMMARY` / `RB_UCSI_HEALTH` / `RB_UCSI_DEVICE` | UCSI topology readiness |
| `i2c-hidd` | `RB_I2C_HIDD_SCHEMA` / `RB_I2C_HIDD_BLOCKER` / `RB_I2C_HIDD_SNAPSHOT` | HID bind progress and blockers |
| `intel-thc-hidd` | `RB_THC_HIDD_SCHEMA` / `RB_THC_HIDD` / `RB_THC_HIDD_FATAL` | THC transport bring-up status |
| `ucsid` | `RB_UCSID_SCHEMA` / `RB_UCSID_SUMMARY` / `RB_UCSID_DEVICE` / `RB_UCSID_HEALTH` | UCSI daemon diagnostics |
All markers carry `generation=<n>` for cycle-level correlation across producers.
## Service Boot Ordering
```
00_base.target
→ 40_pcid.service (PCI enumeration)
→ 41_acpid.service (ACPI tables + AML evaluation)
→ 40_hwd.service (hardware discovery + markers)
→ 00_i2cd.service (I2C adapter registry)
→ 00_i2c-dw-acpi.service (DesignWare I2C controllers)
→ 00_intel-gpiod.service (Intel GPIO controller)
→ 00_i2c-gpio-expanderd.service (GPIO expander companion)
→ 00_i2c-hidd.service (I2C HID devices — touchpads, keyboards)
→ 00_ucsid.service (UCSI USB-C topology)
```
All I2C services use non-blocking (`oneshot_async`) startup so the boot path is not blocked
by any single service's probe latency.