Add dump scripts for clocks and LGA80D. add Rev2 clock support (5341)

AGENTS.md

@@ -218,7 +218,7 @@ reg = Registry(setup='tf')
 # providing clocks, LGA80Ds, the MCU, and both FPGA objects.
 
 # Access devices
-clock = reg.get_clock('R0A')          # Si5395 clock generator
+clock = reg.get_clock('R0A')          # Si5395 (Rev3) or Si5341 (Rev2)
 firefly = reg.get_firefly('F2_6')     # populated TF Firefly4 transceiver
 lga80d = reg.get_lga80d('F1VCCINT1') # LGA80D DC-DC converter
 mcu = reg.get_mcu()                   # ProgCom MC 0 client

EXAMPLES.md

@@ -240,6 +240,7 @@ for name, clock in reg.clocks.items():
 
 ```python
 # Method 1: Symbolic register names (RECOMMENDED)
+# Si5395 register; on Rev2, R0A is an Si5341 (use Si5341Reg there)
 status = clock.read_reg(Si5395Reg.LOL_HOLD_STATUS)
 mode = clock.mode
 
@@ -418,7 +419,7 @@ The same operations are available from the hardware exercise script:
 ```python
 # ✓ RECOMMENDED: Symbolic names
 from cm_interface.device.si5395 import Si5395Reg
-status = clock.read_reg(Si5395Reg.LOL_HOLD_STATUS)
+status = clock.read_reg(Si5395Reg.LOL_HOLD_STATUS)  # Si5395 only (not R0A on Rev2)
 
 # ✓ RECOMMENDED: Convenience methods
 if clock.is_locked():
@@ -537,7 +538,7 @@ example_disable_cdr_all_fireflies()
 | Method | Description |
 |--------|-------------|
 | `Registry(setup='tf')` | Create registry with board preset ('tf', 'it_dtc', or None) |
-| `get_clock(name)` | Get Si5395 clock by name (e.g., 'R0A') |
+| `get_clock(name)` | Get clock by name (e.g., 'R0A'); Si5341 or Si5395 by board revision |
 | `get_firefly(loc)` | Get a configured Firefly by location; raises `KeyError` when absent |
 | `get_lga80d(name)` | Get LGA80D converter by supply name |
 

MCU_REGISTER_MAP.md

@@ -89,7 +89,7 @@ different situation from Alarm/ADC, where dropping the counter was safe.
 | Offset | Size | Field |
 | --- | ---: | --- |
 | `0x00` | 4 | generation counter |
-| `0x04` | 1 | power FSM state (0-10, see state list below) |
+| `0x04` | 1 | power FSM state (0-11, see state list below) |
 | `0x05` | 1 | flags bitmap (see below) |
 | `0x06` | 2 | reserved |
 | `0x08` | 4 | live power-good mask (freshest reading each cycle) |
@@ -100,15 +100,19 @@ different situation from Alarm/ADC, where dropping the counter was safe.
 | `0x19` | 3 | reserved |
 | `0x1c` | 12 | per-supply state, one byte each, index = PG-pin index (state values below) |
 
-Power FSM states (offset `0x04`), in order 0-10:
+Power FSM states (offset `0x04`), in order 0-11:
 
 ```text
 0 POWER_FAILURE   4 POWER_L1ON   8  POWER_L5ON
 1 POWER_INIT      5 POWER_L2ON   9  POWER_L6ON
 2 POWER_DOWN      6 POWER_L3ON   10 POWER_ON
-3 POWER_OFF       7 POWER_L4ON
+3 POWER_OFF       7 POWER_L4ON   11 POWER_CONFIG
 ```
 
+`POWER_CONFIG` runs `LGA80D_init` with the supplies off on every power-up
+(`POWER_OFF` → `POWER_CONFIG` → `POWER_L1ON`); an init failure goes to
+`POWER_FAILURE`.
+
 Flags bitmap (offset `0x05`):
 
 | Bit | Name |

README.md

@@ -17,6 +17,7 @@ cm_interface/
 ├─ registry.py            # Global Registry for board devices
 ├─ examples.py            # Worked examples (see EXAMPLES.md)
 ├─ exercise_mcu.py        # Exercise the MCU pages; writes/control prompt unless --yes
+├─ mcu_dump.py            # Read-only MCU page dump (--out-dir)
 ├─ lga80d_dump.py         # LGA80D register dump script (--snapshot adds the SNAPSHOT read)
 ├─ MCU_REGISTER_MAP.md    # MCU wire contract (with MCU_Reg.h)
 ├─ TODO.md                # Open, deferred and dropped cm_interface work
@@ -27,7 +28,9 @@ cm_interface/
 ├─ device/
 │  ├─ __init__.py
 │  ├─ base.py             # Abstract Device class
-│  ├─ si5395.py           # Clock implementation
+│  ├─ clock.py            # Shared clock base (SiClock, ClockHealth)
+│  ├─ si5395.py           # Si5395 clock (all positions on Rev3)
+│  ├─ si5341.py           # Si5341 clock (R0A on Rev2)
 │  ├─ firefly.py          # Tx, Rx, and 4‑channel firefly classes
 │  ├─ lga80d.py           # LGA80D DC-DC converter implementation
 │  ├─ mcu.py              # Command-module MCU register interface

TODO.md

@@ -12,6 +12,11 @@ except where marked HW-verified. Delete an item when it lands.
   Phase 3 firmware lands.
 - **`FPGA.write_reg` has no guard**, against the refuse-by-default rule in `CLAUDE.md`.
   Open decision 3 in `FPGA_GENERIC_INTERFACE_PLAN.md` (`unsafe=True` opt-in vs warning).
+- **Rev2 Si5341 (R0A) alarm rules are only partly hardware-checked.** Board 210 (2026-10-16)
+  confirmed hw rev 2, PN 0x5341, the status/flag decode and the dump layout on a healthy,
+  locked R0A (now the test fixture). The `clock_checks.py` expected-alarm rules (LOS on an
+  unselected input, FB_IN outside zero delay mode, pin-selected reference) are still from
+  the reference manual only.
 
 ## LGA80D snapshot follow-ups
 
@@ -38,6 +43,7 @@ temporary DEBUG firmware build) and a capture on an absent or NACKing supply. Sn
 | TCA9555 layers B, C (`IO` device; gated writes or named `0x7f` commands) | same, §4.2-4.3 | firmware; C needs maintainer sign-off |
 | Clock `EE` device and load trigger (Phases 3-6) | `CLOCK_PROGRAMMING_PLAN.md` | firmware: the clock EEPROM (0x50, bus 2) needs a 2-byte address and ProgCom `CL` is 1-byte; `EE` unresolved against `MCU_CLI_GAP_PLAN.md` §3.4; page/code numbering stale |
 | Staleness metadata (`updateTick`/`isFFStale`) as page `0x06` extension at `0x20`+ | UART7 plan §5 | unscheduled |
+| LGA80D CLEAR_FAULTS (03h, global, 0 data bytes = SMBus Send Byte): `LGA80D.clear_faults()` and a script option | CM3001 F1VCCINT 2-phase test, 2026-10-13 | firmware: ProgCom rejects a `w DC` with no data (`ProgComTask.c:259`, "write with no data"). Workaround today, MCU CLI: `semaphore 1 take`; `i2cw 1 70 1 <mux bit>`; `i2cw 1 <addr> 1 03`; `semaphore 1 release` (mux bits and addresses in `pm_addrs_dcdc[]`, `LocalTasks.c:409`; untested on HW) |
 
 ## Deferred