HAL Register Introspection#

Kleidos ships an in-house register-introspection engine: every I2C chip the firmware drives (PMICs, the RTC, the I/O expander) carries a compile-time register-map descriptor table (*_regmap.h) that names each register, its access mode, its bit fields, and — critically — whether writing it can drop a power rail, stop the clock, or disable a protection. The engine turns those tables into decoded register dumps, named-field reads, a policed write path, and a live telemetry sampler, all reachable from the serial debug console. Since Phase 3.5 the same engine also describes one MMIO SoC peripheral — the RTC controller (RTC_CNTL) on the internal-RTC boards — via BusKind::Mmio, strictly read-only (see rtc-cntl.md). The pattern also extends to a UART device: the u-blox M10 GNSS receiver on the T-Deck carries the same compile-time, ///-documented descriptor table over its UBX-CFG configuration space (gps_config_map.h), consumed by the GPSCFG/GPSMON/GPSPROBE console commands (see gps-ublox-m10.md).

This subtree documents the engine and one page per chip. The chip pages are generated from the *_regmap.h headers themselves — the header /// doc lines are the source of truth; nothing here is invented beyond them.

What the engine is#

A driver registers its table on the success path of begin() (e.g. axp192.cpp:62, bm8563.cpp:54), so REGS? lists exactly the chips that actually probed on this board — never a chip that is merely compiled in.

Console command surface#

The commands below are exposed by *_debug builds over the serial console (DEBUG_SERIAL_BUTTONS). Output is key=value for machine parsing by the qa/ suite.

dev= vs addr= key convention#

Two distinct address keys appear in the output, and they must not be confused:

• dev=0x.. — the device address: the chip's 7-bit I2C bus address (e.g. dev=0x51 for the BM8563). Printed by REGS?.
• addr=0x.. — the register address: the offset of one register inside that chip (e.g. addr=0x02 = the VL/seconds register). Printed by REGR / REGS? <chip> on every REG … line.
• base=0x.. — the MMIO block base (ChipRegmap::mmioBase): printed by REGS? instead of dev= for bus=mmio chips (e.g. base=0x60008000 for rtccntl on the S3). Per-register addr=0x.. is then the byte offset added to that base.

A decoded register line is:

REG chip=<name> addr=0x<reg> name=<REG_NAME> val=0x<hex> [<field>=<v>[(label)] …]

Enum-decoded fields carry a parenthesized label, e.g. fd=3(1Hz).

Critical-write blocklist + bang override#

Each RegDesc carries a critical flag. A register is critical=true when a write to it can drop a rail, power off / reset the device, stop the timekeeping clock, change charger behavior, or disable a detection/protection. The write path enforces a policy:

• REGW to a non-critical register writes normally.
• REGW to a critical register is refused by the gate.
• REGW! (bang) forces the write, first printing the decoded target (chip, register, critical flag) so the operator sees exactly what they override.
• Write-only registers reject REGR (REGR_ERR: write-only); read-only registers reject REGW.

QA write-back-safe rule. Automated HIL tests never send bang-writes. When a test must exercise a critical register it performs a read-back write: it reads the current value and writes back that exact value, so the chip state is unchanged. Plain writes to critical registers are refused by design; only a human operator, deliberately, uses REGW!.

Curated accessor layer#

Above the raw register tables sits a typed accessor layer on the driver contracts IPmic (src/drivers/power/i_pmic.h) and IRtc (src/drivers/rtc/i_rtc.h), surfaced device-agnostically through the HAL facades (PowerManager, rtc::). These return decoded, unit-bearing values — battery percent/millivolts, PMIC die temperature (°C), coulomb charge (mAh), the RTC VL flag, alarm, countdown timer and CLKOUT — computed by the pure conversion helpers in pmic_common.h / the BM8563 codec.

Unlike the REGS?/REGR console surface (debug builds only), the curated accessors are compiled into every build, including production. Optional capabilities default to return false so a chip that lacks a feature (no die-temp ADC, no coulomb counter, no RTC backend) needs no override and the caller can render na.

Documented chips#

Board presence is verified against each variants/<board>/variant.h feature macro (HAS_BM8563_RTC, HAS_AXP2101, HAS_M5PM1, PMIC_I2C_ADDR, DISPLAY_RESET_AW9523). HAS_AXP2101=1 is a code-path selector, not a literal AXP2101 — on m5stickc_plus1 and core2_v13 it drives an AXP192, and on m5stack_gray an IP5306. Each page states the real silicon.

RTC backends#

The rtc:: facade has two mutually-exclusive backends, selected per board by HAS_BM8563_RTC, each with its own page:

The RTC? snapshot carries a trust= field derived from rtc::clockTrust() (none | volatile | backed), emitted on both the ok=1 and ok=0 lines so an unset internal clock is still observable as trust=none. It is the single discriminator the RTC HIL suite asserts against. See rtc-internal.md for the ClockTrust model and the fail-closed volatile-clock lockout policy.

See also#

• bm8563-rtc.md — the battery-backed RTC backend register map.
• rtc-internal.md — the ESP32 internal-RTC (volatile) backend, ClockTrust model, and fail-closed lockout policy.
• rtc-cntl.md — the SoC RTC controller (RTC_CNTL) MMIO register map behind the internal-RTC backend (read-only introspection).
• ../devices/README.md — per-device hardware reference (specs, pin maps, chip inventory).
• ../../testing/serial-debug-commands.md — every serial command in *_debug builds.
• ../../testing/qa-system.md — the qa/ pytest HIL system that drives these commands.