docs/nics/x710/README.md

# Intel X710 (i40e)

## Module I2C: 1-byte-offset only — dead end for BCM SMI

- `reg_address > 0xFF` returns AQ retval 14 (hard boundary).
- Emits at most `[dev, offset, data]` (2 payload bytes); the BCM SMI needs 3–5 byte frames in one transaction.
- MDIO interface modes don't reach the module — no PHY on the NIC MDIO pins; copper SFPs wire only I2C.
- Single-byte **writes work** (unlike the E810) — which is what makes the oracle path below possible.

## AQ oracle path (stock driver) — proved the RollBall client logic

- Transport: `/sys/kernel/debug/i40e/<pci>/command`, `send aq_cmd <flags> <opcode> 0 0 0 0 <param0> <param1> <param2> 0`, flags 0x2000.
- Opcode 0x0629 get / 0x0628 set PHY register. param0 = phy_interface | dev_addr<<8 | cmd_flags<<16 (phy_interface 2 = EXTERNAL_MODULE, dev_addr 0xA2); param1 = reg offset; param2 = value.
- Result comes back in the dmesg "AQ desc WB" line, 9th field.
- Proven on the Fibergaga, link up: per-pair SNR (PMA 1.133–1.136), PCS 3.32/3.33, the 3.E820 counter ([../../modules/fibergaga/](../../modules/fibergaga/README.md)).
- **Write pacing**: single-byte writes issued ~7 ms apart can land inside the EEPROM's internal write cycle and be silently dropped — no AQ error, stale readback. Space writes ≥30 ms when framing a protocol; a client whose per-op cost is ≥11 ms (page-select + poll sleeps) never trips it, which is why the RollBall path did not.

## Timestamping

- Rejects `HWTSTAMP_FILTER_ALL` with -ERANGE (verified in upstream `i40e_ptp.c`) — PTP-only, so no committed-path bucketing here.
- Genuinely shared PHC across ports (one oscillator) + PTP latches — no committed use: NIC-timestamp length measurement is discarded (length strategy: [../../modules/README.md](../../modules/README.md)).
- No EEE on i40e/X710.
-											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
+								# Intel X710 (i40e)
 								## Module I2C: 1-byte-offset only — dead end for BCM SMI
 								- `reg_address > 0xFF` returns AQ retval 14 (hard boundary).
 								- Emits at most `[dev, offset, data]` (2 payload bytes); the BCM SMI needs 3–5 byte frames in one transaction.
 								- MDIO interface modes don't reach the module — no PHY on the NIC MDIO pins; copper SFPs wire only I2C.
 								- Single-byte **writes work** (unlike the E810) — which is what makes the oracle path below possible.
 								## AQ oracle path (stock driver) — proved the RollBall client logic
 								- Transport: `/sys/kernel/debug/i40e/<pci>/command`, `send aq_cmd <flags> <opcode> 0 0 0 0 <param0> <param1> <param2> 0`, flags 0x2000.
 								- Opcode 0x0629 get / 0x0628 set PHY register. param0 = phy_interface | dev_addr<<8 | cmd_flags<<16 (phy_interface 2 = EXTERNAL_MODULE, dev_addr 0xA2); param1 = reg offset; param2 = value.
 								- Result comes back in the dmesg "AQ desc WB" line, 9th field.
 								- Proven on the Fibergaga, link up: per-pair SNR (PMA 1.133–1.136), PCS 3.32/3.33, the 3.E820 counter ([../../modules/fibergaga/](../../modules/fibergaga/README.md)).
-											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
+								- **Write pacing**: single-byte writes issued ~7 ms apart can land inside the EEPROM's internal write cycle and be silently dropped — no AQ error, stale readback. Space writes ≥30 ms when framing a protocol; a client whose per-op cost is ≥11 ms (page-select + poll sleeps) never trips it, which is why the RollBall path did not.
-											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
 								## Timestamping
 								- Rejects `HWTSTAMP_FILTER_ALL` with -ERANGE (verified in upstream `i40e_ptp.c`) — PTP-only, so no committed-path bucketing here.
-											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
+								- Genuinely shared PHC across ports (one oscillator) + PTP latches — no committed use: NIC-timestamp length measurement is discarded (length strategy: [../../modules/README.md](../../modules/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
+								- No EEE on i40e/X710.