cabletest/docs/state.md

# Current state

## Where the code is right now

**The committed tree is the X520 product implementation**: AF_PACKET datapath with read-time rate buckets and the backward excess-fill smear (nics/x520/ — rate is a headline, never a verdict; `smearWindow` 4 buckets = 64 ms display latency, resize after measuring the stall distribution: open-questions), the mixed FS+Wiitek diagnostics with the BCM ECD length path, `testDriver` = ixgbe. No hardware-timestamp machinery anywhere. The CX-5 is retired (nics/connectx-5/, "Status") and the E810 bit-bang investigation with it (nics/e810/).

## Stashes

Indices shift as stashes are pushed/popped — match by message, not number.

- **"CX-5 Wiitek: MCIA transport…"** (currently `stash@{0}`) — the whole Wiitek-pair rewrite for the CX-5, kept as a parts bin: `phy_mcia.go` (VSC/ICMD MCIA transport), transport-interface `phy.go` (the same RollBall logic over either patched-ixgbe `sff_i2c` or MCIA), dual-end per-pair SNR from both modules (headline: worst pair across both ends), mlx5 ntuple steering + PHY RMON counters, test interfaces at MTU 9000 with a 9018-byte jumbo in the size mix; BCM/ECD/length dropped. Technical record: nics/connectx-5/. Carries live debug instrumentation and `rbCmdPoll` lowered to 2 ms from the mailbox-latency investigation — **not shippable as-is**, clean it before committing — plus the pre-existing uncommitted `ui.go`/`ui_test.go` edits that were entangled in the same files.
- **"AF_XDP both directions…"** (currently `stash@{1}`) — AF_XDP conversion (hand-rolled XSK + XDP program, per-frame MAC-stamp buckets via rx metadata). Built for the E810-era datapath. An experiment, not a requirement.
- **"phydiag campaign…"** (currently `stash@{2}`) — python transport clients (`i40e_aq.py`, `rollball_i40e.py`, `sff.py`), scanners, campaign log. Working copies live in `~/work/phydiag-work/`; the knowledge is in these docs; the code should eventually move into the repo properly.

## The box

- Single usable PCIe slot (Gen4 x8): holds the **X520-DA2** (dual SFP+). Verify 5 GT/s ×8 trained at bringup (`lspci -vv`). The ConnectX-5 is out of the box.
- X710 on a CPU x4 port (Gen3 x4, ~31.5 Gbps/dir — enough for 2×10G full duplex despite the driver's worst-case bandwidth warning).
- Many CPU cores; goroutine-heavy designs welcome.
- mstflint (AUR — not in the Arch repos) provides `mstlink`/`mstreg`/`mstconfig` for the CX-5, if it ever returns.

| Interface | Device | Role (rules: hardware.md) |
|---|---|---|
| `enp1s0f0` + second port | X520 (ixgbe) | Test pair — FS + Wiitek, dispatched by EEPROM PN so either port may hold either module. **Stock ixgbe refuses the FS's honest EEPROM and its port has no netdev until `./load-ixgbe`** (allow_unsupported_sfp=1 + the sff_i2c/ETQF patches); the tool needs exactly 2 ixgbe interfaces |
| `enp3s0f0np0` / `enp3s0f1np1` | X710 (i40e) | Noise pair (has been `enp4s0f*` across reboots) — two Wiiteks, both qualified by the X710. The FS cannot live here (firmware rejects the honest EEPROM, no `allow_unsupported_sfp` in i40e) |
| `enp88s0` | igc | LAN uplink, default route; sibling `enp89s0` is dark |

## Hardware

| Item | Status | Notes |
|---|---|---|
| X520-DA2 | **Installed** in the single PCIe slot — **the product NIC** (nics/x520/) | Unmediated bit-bang I2C (patched-ixgbe `sff_i2c`), <25 ms RollBall, FS links and the ECD length path is proven; the smoothed-bucket rate design removes the need for hardware RX stamps |
| ConnectX-5 | Out of the box — retired | Ran the two-Wiitek pair at near line rate with dual-end SNR (stashed `phy_mcia.go` MCIA transport), but the firmware quantizes every module mailbox read to ~150 ms steps and the FS never links behind mlx5 — nics/connectx-5/, "Status" |
| FS SFP-10G-T-100 ×2 | One in the X520 test pair, one on the shelf | BCM84891L, documented, robust; ixgbe-only (unlinkable behind mlx5 — host-interface deadlock, confirmed module-typed, nics/connectx-5/ — and rejected by the X710). The FS+Wiitek mixed pair (FS length via ECD + Wiitek SNR) is the product configuration |
| Replacement Wiiteks | One in the X520 test pair, two in the X710 noise pair, rest on the shelf | Originals bricked by register exploration — modules/wiitek/ trap first. IEEE-standard registers only (modules/README.md safe set); VCT templates are single-shot candidates on a sacrificial unit only |
| Fibergaga SFP-10G-T-30M | On the shelf | Aquantia, RollBall, the documented oracle; the alternate length path if the pair mix ever changes |
| 10Gtek | In hand | Claims SFP-10G-SR, still copper RJ45; filler, not in the test set |
| E810 | Out of the box | Patched ice + `sff_i2c` remains useful only if it returns for read-side work |

## Diagnostics artifacts outside the repo

In `~/work/`, ready to fold into the repo's `kernel/`:

- **Patched ixgbe** (`~/work/ixgbe-sff/`) — the `sff_i2c` raw-I2C debugfs transport, ETQF steering, `reg_ops`/`ts_bench`; `./load-ixgbe` rebuilds + swaps the module with `allow_unsupported_sfp=1`. Details: nics/x520/.
- **Bench tools and clients** (`~/work/phydiag-work/`) — `etqfbench/`, `x520poke/`, `compound_test.py`, `bcm_mcia_emu.py`, `bcm_ixgbe.py`, `bcm_explore.py`/`bcm_eee_off.py`, `bcm_ecd_probe.py`, `bcm_phaselock_bench.py`, `rollball_ixgbe.py`, `rb_forensic.py`. What each proved lives in modules/fs/, modules/wiitek/ and nics/x520/.

## Every boot

1. `./load-ixgbe` — until then the FS port has no netdev (stock driver, error -95) and `driverPair("ixgbe")` cannot find 2 interfaces. Verify `sff_i2c` present for both ports.
2. Re-apply host tuning (hardware.md) before trusting results.