Add in-repo project docs: goals, state, hardware, module-PHY transports, module diagnostics, and measurement lessons

docs/goals.md

@@ -0,0 +1,16 @@
+# Goals
+
+cabletest finds Ethernet cables that misbehave under sustained full-duplex 10 Gbit load. It exchanges raw Ethernet frames (no IP, no ARP) across a variety of sizes and payloads between two directly-cabled ports on one host, and attributes every problem it can to the cable rather than the host. It runs as PID 1 on a dedicated appliance with a framebuffer UI; development happens on the same machine under Arch.
+
+The target of measurement is the cable, not throughput. Line rate is a means to stress the physical layer. The outputs that matter, roughly in order:
+
+1. **Loss and error attribution** — reception gaps, link errors, NIC/driver counters as first-class output alongside application loss. Baseline loss must be exactly zero before a run counts; any host-side loss masks real cable faults.
+2. **Noise tolerance** — a deliberately-bad "noise" cable intertwined with the test cable, driven by link up/down cycling, stresses the cable under test with alien crosstalk.
+3. **Per-pair SNR margin** from the module PHYs (IEEE 802.3an standard registers) — the leading indicator of a marginal cable before it drops frames.
+4. **Cable length** — sanity check and fault localization. Sources, in preference order:
+   - Module PHY DSP estimate — works on a linked cable.
+   - PHY TDR — localizes opens/shorts both-ended; healthy-cable length only single-ended.
+   - NIC timestamp path-delay — works linked, module-independent; needs per-packet or PTP-latch hardware timestamps and a short-cable calibration.
+5. **Pre-FEC error visibility** — corrected-error counters that move before post-FEC loss appears. Vendor-specific; still unlocated on the module PHYs we can talk to. Standard latched PCS counters (errored blocks, BER, block-lock loss) are the working proxy under noise stress.
+
+Design preferences that shaped the tool: plain sockets first, escalate only after measuring (AF_PACKET reached line rate on the shipping mix; the AF_XDP experiment is parked); pre-populated frame contents; goroutine-heavy is fine (many cores to burn); DPDK is off the table — it would kill the sysfs counters and link management the tester depends on.