BCM ECD recovered from OpenBCM SDK and proven: 1E.4006 start, 1.A896 verdicts, 1.A897-9A per-pair meters -- meter-accurate on a 45m cable, healthy pairs report length

docs/modules/fs/README.md

@@ -50,13 +50,26 @@ Protocol and full verified catalog: [bcm84891l-mdio-commands.md](bcm84891l-mdio-
 
 Several documented DATA1 returns on this ODM firmware are untrustworthy: die-temperature-like values (0x43/0x44/0x46/0x47) appear in DATA1 of commands that should return modes, and repeat reads of the same GET disagree. Corroborate anything load-bearing through IEEE registers (7.60/7.61 for EEE advertisement) or wire behavior (EEE statistics under traffic), and write every DATA register explicitly before any SET.
 
-## No cable length — and the asks to FS
+## ECD — recovered from the OpenBCM SDK, proven on hardware
 
-The handler catalog is complete (§1.25.1.1–45) and contains no ECD, length, or skew command. Cable length, opens/shorts, pair skew, and polarity live in the separate ECD register mechanism whose chapter FS hasn't sent; the 1588 engine is the same story (one-command enable, undocumented operation — in-PHY timestamping would measure path delay at the MDI, removing PHY-pipeline latency from the length equation; [../../open-questions.md](../../open-questions.md) §2). Until either chapter lands, FS-side length comes only from the NIC timestamp path.
+The ECD register mechanism is absent from the handler catalog and from FS's docs, but the OpenBCM SDK's copper-XGPHY driver (`sdk-6.5.27/src/soc/phy/phy8481.c` `phy_8481_cable_diag` + `phy8481.h`) carries it for the 8483x/8485x/8488x family — and the same SDK drives the identical command-handler registers (1E.0x4005/0x4037/0x4038–3C) as the BCM84891L datasheet, confirming the shared map. Validated on the FS:
 
-Asks, in value order:
+| Register | Role |
+|---|---|
+| `1E.0x4006` | Control/status. Write under mask {15,14,13,12,10}: bit 15 = run now, bit 14 = run at AN, bit 12 = break link, bit 10 = length in meters (SDK writes value 0x8400 = run now + meters). Bit 11 = busy — poll until clear (SDK allows up to 50 s; observed < 0.5 s) |
+| `1.0xA896` | Verdicts, 4 bits per pair: 1 = OK, 2 = open, 3 = short, 4 = inter-pair short |
+| `1.0xA897–0xA89A` | Per-pair lengths (pairs 1/2, 3/4, 5/6, 7/8), meters |
 
-1. The **ECD chapter** — shorts/opens/cable length invocation.
+Observed on a plugged, linked, healthy cable: verdicts OK×4 and per-pair lengths of [45, 45, 41, 46] on a ~45 m cable — **meter-accurate with no calibration**, and this ECD reports length for healthy pairs, not just faults, resolving the terminated-far-end concern in [../README.md](../README.md). Caveats:
-2. The **1588 operation chapter**.
+
+- The run blips the link (PMA 1.1 latch-low catches a drop even with the break-link bit clear) — do not run mid-measurement until the disturbance is characterized.
+- Fault verdicts (open/short/inter-pair) are unexercised — deliberately: the product is a closed-loop tester, both ends always plugged.
+- Family constraints from the SDK: port must be enabled; unsupported at forced 100M.
+- `bcm_ecd_probe.py` in phydiag-work implements the recipe.
+
+## Remaining asks to FS
+
+1. The **ECD chapter** — now for confirming bit meanings rather than unblocking.
+2. The **1588 operation chapter** (in-PHY timestamping would measure path delay at the MDI, removing PHY-pipeline latency from the length equation; [../../open-questions.md](../../open-questions.md) §2).
 3. Datasheet **§1.20 loopback** (copper line loopback) and **§1.17 EEE/fast-retrain monitoring**.
 4. **Chapter 2 register summary.** The excerpt's TOC names them all.

docs/open-questions.md

@@ -61,17 +61,16 @@ The path crosses two 10GBASE-T PHYs (~2–3 µs pipeline each); the timestamp le
 
 ## 3. Cable-length strategy
 
-**Status: consolidated — PHY features are the product path, NIC timestamps the fallback.**
+**Status: consolidated — PHY features are the product path, NIC timestamps the fallback. The BCM path works.**
 
 | Path | Status |
 |---|---|
-| BCM ECD/DSP | Real, but the ECD chapter is missing from FS's docs (modules/fs/ ask list). The handler exposes only a 1-bit trace of the DSP estimate (limited-reach linked bit, and only with LR mode enabled) |
+| BCM ECD | **Working on the bench** — recipe recovered from the OpenBCM SDK (`phy8481.c` cable-diag, same register family as the 84891L's command handler) and validated: per-pair verdicts + per-pair lengths in meters on a plugged healthy cable. Calibration and run-disturbance characterization remain (modules/fs/) |
-| Aquantia DSP/TDR (oracle only) | **Fully documented**: `1E.C884` length ±1 m, per-pair TDR verdicts and reflection distances (modules/fibergaga/). Proves at least one vendor exposes DSP length in a plain register — precedent for the FS ask |
+| Aquantia DSP/TDR (oracle only) | **Fully documented**: `1E.C884` length ±1 m, per-pair TDR verdicts and reflection distances (modules/fibergaga/) |
-| Marvell VCT (Wiiteks) | Undocumented and gated behind the brick trap; sacrificial-unit-only single-shot templates (modules/wiitek/) |
+| Marvell VCT (Wiiteks) | Undocumented and gated behind the brick trap; sacrificial-unit-only single-shot templates (modules/wiitek/). The BCM ECD result layout (verdict nibbles + per-pair length registers) is a fresh analogy for future targeted probes |
 | NIC timestamp path-delay | Module-independent; gated on the §2 retrain-stability experiment |
 
-- Fallback doc-mining, checked: OpenBCM's `phy8481.c` covers the copper XGPHY family only through BCM8488x — no 84891, no ECD code in the retrievable portion; the kernel's Broadcom ECD (`bcm-phy-lib`) is the BCM54xx GbE register model. Neither transfers; SDK/patent mining looks low-yield. FS delivering the ECD chapter stays the primary route.
+- **Decision:** product path = the PHY's own length machinery (BCM ECD, `1E.C884` on the oracle); NIC timestamp path-delay = fallback, pursued only if the §2 experiment passes. The ECD run blips the link, so length measurement is a between-runs operation, not a during-run one, unless characterization says otherwise.
-- **Decision:** product path = the PHY's own length machinery (BCM ECD when FS delivers; `1E.C884` on the oracle); NIC timestamp path-delay = fallback, pursued only if the §2 experiment passes.
 
 ## 4. Two-master I2C safety and the once-untested client assumptions
 

docs/state.md

@@ -68,6 +68,6 @@ Fallbacks if raw-L2 steering can't work: minimal bare-IPv4 framing steered by IP
 
 ## Open items
 
-- **ECD register chapter** from FS — the one missing document for BCM cable length; the wider ask list is in modules/fs/.
+- **BCM ECD works** (recipe recovered from the OpenBCM SDK, validated on the FS — modules/fs/): per-pair lengths meter-accurate against a known ~45 m cable. Remaining work is characterizing the link blip the run causes (length is a between-runs operation until then). The FS ECD-chapter ask is now confirmation, not unblocking.
 - **Pre-FEC verification** on the Aquantia — counters documented (modules/fibergaga/); needs the graded-noise correlation run (open-questions.md §5).
 - **X710 PTP path-delay length measurement**: viable fallback for linked-cable length (PTP-latch timestamps both ports, same oscillator, short-cable calibration); scoped but unbuilt — the committed `probe.go` is the *filter-all* variant (raw-frame probes, needs all-packet rx stamping, E810-only); the X710/X520 variant means PTP-shaped probes. Superseded for the product if PHY DSP length pans out.