docs/README.md

# cabletest docs

Project knowledge that moves and versions with the repo.

General:

- [goals.md](goals.md) — what cabletest is for and what it must output.
- [state.md](state.md) — where things are now: the box and what's in it, out-of-repo artifacts, every-boot steps. **All current-placement state lives here and only here.**
- [hardware.md](hardware.md) — host rules: interface conventions, tuning, how to run.
- [measurement.md](measurement.md) — how to measure correctly; performance results and dead ends.
- [xdp.md](xdp.md) — the AF_XDP datapath experiment: what it proved, what rebuilding it needs, why it can't run on the X520.
- [open-questions.md](open-questions.md) — the genuinely open problems, as pointers into the docs that hold their detail.

Per-device (each directory: device doc + its datasheets):

- [nics/](nics/README.md) — the transport rule, the comparison table, and one directory per NIC: [x520](nics/x520/README.md), [connectx-5](nics/connectx-5/README.md), [x710](nics/x710/README.md), [e810](nics/e810/README.md).
- [modules/](modules/README.md) — module inventory, media-lies table, the shared IEEE register set, RollBall protocol, cable-length physics, and one directory per module: [fs](modules/fs/README.md), [wiitek](modules/wiitek/README.md), [fibergaga](modules/fibergaga/README.md).
Add in-repo project docs: goals, state, hardware, module-PHY transports, module diagnostics, and measurement lessons 2026-08-10 10:34:26 -07:00			`# cabletest docs`

			`Project knowledge that moves and versions with the repo.`

Restructure docs: per-device directories under modules/ and nics/ with co-located datasheets, state centralized in state.md, prose tightened into lists and tables 2026-08-12 19:23:02 -07:00			`General:`

Add in-repo project docs: goals, state, hardware, module-PHY transports, module diagnostics, and measurement lessons 2026-08-10 10:34:26 -07:00			`- [goals.md](goals.md) — what cabletest is for and what it must output.`
All three stashes distilled into docs and dropped: xdp.md carries the AF_XDP record (ixgbe's 3 KB single-buffer XDP cap excludes the locked jumbo mix; XSK need_wakeup TX as the spin-free flow control, zero-copy-or-die, the stray-RX fill-ring trap, BTF-resolved stamp kfunc, wire-weighted size schedule as an unadopted option); connectx-5 README gains the PCICONF/ICMD/MCIA gateway constants so a rebuild needs no mstflint re-mine; e810 keeps the read-side transport map (cage-cache, bus=port, bus-5 phantom, 16-bit-addr hazard, latency as wire-truth) and NVM rollback pointers; x710 the >=30 ms EEPROM write pacing; fibergaga the empirical vendor-space finds; fs the inert-I2C-surface map; state.md stash section now empty 2026-08-19 14:42:13 -07:00			`- [state.md](state.md) — where things are now: the box and what's in it, out-of-repo artifacts, every-boot steps. All current-placement state lives here and only here.`
Restructure docs: per-device directories under modules/ and nics/ with co-located datasheets, state centralized in state.md, prose tightened into lists and tables 2026-08-12 19:23:02 -07:00			`- [hardware.md](hardware.md) — host rules: interface conventions, tuning, how to run.`
Add in-repo project docs: goals, state, hardware, module-PHY transports, module diagnostics, and measurement lessons 2026-08-10 10:34:26 -07:00			`- [measurement.md](measurement.md) — how to measure correctly; performance results and dead ends.`
All three stashes distilled into docs and dropped: xdp.md carries the AF_XDP record (ixgbe's 3 KB single-buffer XDP cap excludes the locked jumbo mix; XSK need_wakeup TX as the spin-free flow control, zero-copy-or-die, the stray-RX fill-ring trap, BTF-resolved stamp kfunc, wire-weighted size schedule as an unadopted option); connectx-5 README gains the PCICONF/ICMD/MCIA gateway constants so a rebuild needs no mstflint re-mine; e810 keeps the read-side transport map (cage-cache, bus=port, bus-5 phantom, 16-bit-addr hazard, latency as wire-truth) and NVM rollback pointers; x710 the >=30 ms EEPROM write pacing; fibergaga the empirical vendor-space finds; fs the inert-I2C-surface map; state.md stash section now empty 2026-08-19 14:42:13 -07:00			`- [xdp.md](xdp.md) — the AF_XDP datapath experiment: what it proved, what rebuilding it needs, why it can't run on the X520.`
Dissolve resolved analyses into standalone device docs; open-questions.md keeps only the four live problems; discard NIC-timestamp length path (BCM ECD is proven) and Aquantia length trivia (30m part, oracle-only) 2026-08-12 21:30:16 -07:00			`- [open-questions.md](open-questions.md) — the genuinely open problems, as pointers into the docs that hold their detail.`
Restructure docs: per-device directories under modules/ and nics/ with co-located datasheets, state centralized in state.md, prose tightened into lists and tables 2026-08-12 19:23:02 -07:00
			`Per-device (each directory: device doc + its datasheets):`
Add in-repo project docs: goals, state, hardware, module-PHY transports, module diagnostics, and measurement lessons 2026-08-10 10:34:26 -07:00
Remove WX1820: never had the hardware, evaluation was paper-only 2026-08-12 21:10:38 -07:00			`- [nics/](nics/README.md) — the transport rule, the comparison table, and one directory per NIC: [x520](nics/x520/README.md), [connectx-5](nics/connectx-5/README.md), [x710](nics/x710/README.md), [e810](nics/e810/README.md).`
Restructure docs: per-device directories under modules/ and nics/ with co-located datasheets, state centralized in state.md, prose tightened into lists and tables 2026-08-12 19:23:02 -07:00			`- [modules/](modules/README.md) — module inventory, media-lies table, the shared IEEE register set, RollBall protocol, cable-length physics, and one directory per module: [fs](modules/fs/README.md), [wiitek](modules/wiitek/README.md), [fibergaga](modules/fibergaga/README.md).`