theater/cabletest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure docs: per-device directories under modules/ and nics/ with co-located datasheets, state centralized in state.md, prose tightened into lists and tables

Browse Source
This commit is contained in:
flamingcow
2026-08-12 19:23:02 -07:00
parent dc1fa6538d
commit c57816345f
24 changed files with 511 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules/README.md
+58
View File
@@ -0,0 +1,58 @@
# Modules
Per-module diagnostics: capabilities, register maps, hazards. Each device directory holds its doc plus its datasheets. NIC-side transports: [../nics/](../nics/README.md).
> ⚠ **Before touching any Wiitek/Marvell module, read the brick trap in [wiitek/](wiitek/README.md).** Two modules died permanently from register exploration.
## The modules
Counts and current placement: [../state.md](../state.md).
| Module | PHY | Doc | Role |
|---|---|---|---|
| FS SFP-10G-T-100 | Broadcom BCM84891L | [fs/](fs/README.md) | Test set; documented, robust |
| Wiitek UF-RJ45-10G-100 | Marvell CUX3610 (Alaska-M) | [wiitek/](wiitek/README.md) | Test set; **brick-prone** |
| Fibergaga SFP-10G-T-30M | Aquantia AQR | [fibergaga/](fibergaga/README.md) | The documented oracle |
| 10Gtek | (claims SFP-10G-SR) | — | Copper RJ45 despite the SR part number; filler, not in the test set |
## The media lies (mostly)
**Every test module is a copper RJ45 10GBASE-T module** — none are fiber, whatever the EEPROM claims; the real media is a 10GBASE-T PHY inside each module. EEPROM honesty varies by vendor, with driver consequences:
| Module | EEPROM claims | Stock ixgbe verdict |
|---|---|---|
| Wiitek | LC connector, 850 nm SR, multimode lengths, fake optical DOM (temperature real, "laser" powers theater) | Passes qualification |
| FS | Honest: RJ45 (0x22), 10GBASE-T Short Reach, 100 m copper, no fake DOM | **Rejected** — kills the whole port probe (error -95, no netdev) |
| 10Gtek | `SFP-10G-SR` part number | (not in the test set) |
- `allow_unsupported_sfp=1` is mandatory on the X520 — and it's the *truthful* module that requires it ([../nics/x520/](../nics/x520/README.md)).
- Physical-layer reasoning must use 10GBASE-T: PAM16, LDPC FEC, self-synchronizing scrambler, 4 twisted pairs, distance/temperature sensitive — never an optical model.
- The module PHYs keep the copper link trained on their own: an admin `ip link set down` does NOT drop the wire unless the i40e `link-down-on-close` priv flag is set (peer sees the drop in ~200 ms, relinks in ~0.9 s).
## IEEE 802.3an standard registers (safe on all copper module PHYs)
Proven on the CUX3610 (before the originals died) and the Fibergaga; the BCM notably does **not** populate the SNR set ([fs/](fs/README.md)).
| Registers | What | Notes |
|---|---|---|
| PMA 1.133–1.136 / 1.137–1.140 | Per-pair SNR margin, current / minimum | CUX3610 value = `reg − 0x8000` in 0.1 dB. Retrain-dependent — only compare within one training session |
| PCS 3.32/3.33 | Block-lock loss, BER saturate, errored blocks | Latched, clear-on-read |
| AN 7.33 | Link-partner status / master-slave | |
| PMA 1.147 | Fast retrain status/count | Per-run quality metric |
| AN 7.0 bit 9 | Restart AN — forces retrain, refreshes SNR minimums | Proven safe everywhere. An `ip link` bounce does not drop the copper line, so it won't retrain |
## RollBall protocol (Marvell and Aquantia modules)
Clause-45 access to the internal PHY over I2C A2h, all messages ≤ 4 B, offset-addressed:
1. Unlock: password 0xFF×4 at A2h 0x7B.
2. Page-select: A2h 0x7F → 3.
3. Mailbox: A2h 0x80 (cmd) / 0x81 (data), poll for DONE (0x04).
Split transactions (separate STOP per byte) are field-proven on both the Fibergaga and the original Wiiteks; the kernel `mdio-i2c` combined form is not required by the modules.
## Cable-length physics (applies to all vendors)
- **TDR** (classic VCT/CDT/ECD): locates opens/shorts both-ended. But *healthy-cable length* needs a far-end reflection, and a plugged-in terminated far end absorbs the pulse — "OK" pairs report no distance. Effectively single-ended for length; every kernel implementation only reports distance for *fault* results.
- **DSP estimate**: both vendors' PHYs compute linked-cable length continuously from insertion loss during training (Marvell "proactively determines cable length"; the BCM's limited-reach power mode switches "based on cable length" while linked). Works in the product's both-ends-plugged topology — the question is only whether the estimate is exposed in a readable register (Aquantia: yes, `1E.C884`; BCM/Marvell: not in documented space).
- **NIC timestamp path-delay** — the module-independent fallback: works linked, needs hardware timestamps and a short-cable calibration to cancel fixed PHY latency (~4.8 ns/m one way; 50 m ≈ 240 ns). Viability gated on PHY-latency stability across retrains ([../open-questions.md](../open-questions.md) §2).
docs/modules/fibergaga/README.md
+21
View File
@@ -0,0 +1,21 @@
# Fibergaga SFP-10G-T-30M (Aquantia AQR)
The documented oracle. RollBall module, PHY ID 0x31c31c13, proven over the i40e oracle path ([../../nics/x710/](../../nics/x710/README.md)). Its PHY family register reference is vendored in this directory (`aquantia-aqr107-aqr109-datasheet.pdf` — the AQR107-AQR109 register reference).
## Documented registers
| Registers | What |
|---|---|
| 3.E820/3.E821 | PCS Receive Vendor **Uncorrected** Frame Counter (post-FEC) |
| 3.E840–3.E84E | Corrected Frame N Iteration Counters, N = 1…10 LDPC iterations — the pre-FEC leading indicator ([../../open-questions.md](../../open-questions.md) §5) |
| 3.E816 | RS Corrected Error Frame Counter (system-side, secondary) |
| 1E.C884 bits 7:0 | **Estimated cable length in meters, ±1 m**, RO, from the cable diagnostic engine |
| 1E.C800 | Per-pair TDR fault verdicts (open/short/mismatch/cross-pair) |
| 1E.C801–C807 | Distances of the four worst reflections per pair, ±1 m |
| 1E.C880–C883 | Reflection impedance/magnitude |
| PMA 1.133–1.140, PCS 3.32/3.33 | Standard set ([../README.md](../README.md)), proven live |
## Open bench questions
- Whether `1E.C884` is continuously valid on a linked cable or only after an explicit diag run.
- The pre-FEC correlation experiment ([../../open-questions.md](../../open-questions.md) §5) — this module is its instrument.
docs/modules/fibergaga/aquantia-aqr107-aqr109-datasheet.pdf
BIN
View File
Binary file not shown.
docs/modules/fs/10GBase-T Coper SFP Registers Operation's Reference for BCM84891.pdf
BIN
View File
Binary file not shown.
docs/modules/fs/BCM84891L-MDIO Command Descriptions-.pdf
BIN
View File
Binary file not shown.
docs/modules/fs/README.md
+62
View File
@@ -0,0 +1,62 @@
# FS SFP-10G-T-100 (Broadcom BCM84891L)
Documented, robust — survived the whole poking campaign un-bricked. Honest EEPROM (RJ45/10GBASE-T codes), which is what trips stock ixgbe qualification ([../README.md](../README.md)).
References in this directory: [bcm84891l-mdio-commands.md](bcm84891l-mdio-commands.md) (command handler, transcribed), [bcm84891l-sfp-registers.md](bcm84891l-sfp-registers.md) (transport reference, transcribed), and their source PDFs.
## SMI transport (I2C→MDIO bridge)
PHY at I2C 8-bit **0xAC write / 0xAD read**.
| Op | Frames |
|---|---|
| Clause-45 write | one I2C write to 0xAC: `[000+DevAD, RegH, RegL, DataH, DataL]` |
| Clause-45 read | I2C write to 0xAC: `[001+DevAD, RegH, RegL]` → **delay >1 ms** (3 ms proven) → I2C read 2 B from 0xAD |
- Single-byte reads see the bridge as inert (returns 0) — the DevAD-prefixed frame + delay is mandatory. This is why early probing wrongly declared 0x56 dead. Treat 0x0000 reads as retry-with-longer-delay: 0 is also the bridge's not-ready signature.
- Recorded for a future multi-byte firmware transport (mlx5 MCIA shape): read = write `[001+devad,RegH,RegL]` offset_size=1, STOP, >1 ms, read 2 B offset_size=0; write = offset_size=2, addr = devad<<8|RegH, data = `[RegL,DataH,DataL]`.
## MDIO command handler
Protocol and full verified catalog: [bcm84891l-mdio-commands.md](bcm84891l-mdio-commands.md). Traps:
- **SET commands execute stale DATA1** — the handler never clears DATA registers; write every parameter register explicitly before any SET.
- Poll STATUS ~100 ms; frozen up to 2 s during 10GBASE-T training — only run after link-up.
## Proven diagnostics
| Capability | How | Observed |
|---|---|---|
| Per-pair SNR | `CMD_GET_SNR` 0x8030, **invoked bare** (writing the documented DATA1 display flag returns zeros; IEEE 1.133–1.140 never populate — constant 0x8080) | DATA2–5 = SNR A–D ×0.1 dB; ≈ 27–32 dB absolute on bench, 0.1–0.4 dB jitter. 10GBASE-T operating point ≈ 26.5 dB, so margin ≈ value − 26.5 |
| Die temperature | `CMD_GET_CURRENT_TEMP` 0x8031 | ~68–70 °C on bench |
| Supply rails | `GET_CURRENT_VOLTAGE` 0x802F | 0.8 V and 1.88 V rails, tenths of mV |
| Error counters | IEEE PCS 3.32/3.33 — block lock, latched errored-block/BER, clear-on-read | The noise-stress error proxy |
| Retrain on demand | IEEE AN restart `7.0 \|= bit9` | Relinks in ~5–6 s |
## Probed configuration states
| Item | Command | State |
|---|---|---|
| EEE / AutogrEEEn | 0x8008/0x8009 | Once read 0x0047 (10G AutogrEEEn variable latency + 5G/1G native — local-only, invisible in IEEE 7.60/7.61, which read 0); later reads 0. **Forced all-off** via SET with explicit params `(0, 0, 0x7A12, 0x480, 0)` + AN restart, verified. cabletest should apply this defensively at bringup |
| EEE wire-truth | arm 0x801A after link-up, read 0x801B | Zero LPI events/duration on idle link; repeat under traffic |
| Fast retrain | 0x800A (datasheet titles it EMI_MODE; description is fast retrain) | Enabled 10G/5G/2.5G; IEEE 1.147 = 0x0019, count bits zero. Keep enabled; read the 1.147 count per run — a marginal cable that fast-retrains still gets counted |
| Pair map | 0x8000 | DATA2 = 0x00E4 = identity (A/B/C/D straight through) — MDI wiring verification works |
| Fault pass-through | 0x800D | 0 = LF/RF pass to the line (0x8011/0x8010 could mask them as IDLE — leave off) |
| Host interface | 0x802B/0x802D/0x8027 | XFI polarity normal; TX FIR = main tap 0x3C only; MAC/PHY frequency locked; KR/SyncE/USXGMII/WOL disabled; jumbo on at 9K; temp warnings off |
| 1588 | 0x8004 | Disabled (engine registers undocumented — see asks below) |
| Limited reach | 0x8006 | Disabled — its DATA3 "linked in LR mode" bit, the only handler-visible trace of the DSP length estimate, is unavailable without a config change |
## Firmware-reliability caveat
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
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.
Asks, in value order:
1. The **ECD chapter** — shorts/opens/cable length invocation.
2. The **1588 operation chapter**.
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/modules/fs/bcm84891l-mdio-commands.md
+215
View File
@@ -0,0 +1,215 @@
# BCM84891L MDIO command handler — transcription
Transcribed (visually, tables intact) from the FS-provided excerpt of the Broadcom
datasheet `84891L-DS101` (`BCM84891L-MDIO Command Descriptions-.pdf`). The excerpt
keeps the cover, TOC, and datasheet pages 41–59. Chapters the TOC lists but the
excerpt **omits** — each a potential follow-up ask to FS:
- §1.17 EEE / AutogrEEEn (enable/disable, **monitoring EEE readiness**, fast retrain
modes: IEEE FR, Negotiated FR, BCM-proprietary FR)
- §1.18 Jumbo packets, §1.19 HiGig2
- §1.20 Loopback operation — per-speed PCS loopbacks and **copper line loopback at
PMD/PCS** (§1.20.2)
- §1.21 Management interface, §1.22 TRD (MDI) pair swapping, §1.23 SPI
- **Chapter 2: Register Summary** (p62+)
- Not in the TOC at all: the ECD chapter and the 1588 operation chapter.
Device headline features (cover page): IEEE 1588-2008 v2-compliant; IEEE fast retrain
and link monitoring; EEE with AutogrEEEn; enhanced cable diagnostics; detection and
correction of pair swaps (MDI crossover), pair skew, and pair polarity; line-side
loopback; jumbo to 18 KB; low-EMI; XFI/USXGMII/KR host interfaces.
## Handler protocol (§1.24)
Write the command code to CMD `1E.0x4005` with bit 15 set; firmware raises an
interrupt, services the command, and reports through STATUS `1E.0x4037`
(bidirectional — user-writable). Poll STATUS every ~100 ms. During the 2-second
10GBASE-T training phase STATUS freezes (returns SYSTEM_BUSY); only issue commands
after link-up.
| Register | Address |
|---|---|
| CMD | 1E.0x4005 |
| STATUS | 1E.0x4037 |
| DATA1–DATA5 | 1E.0x4038–1E.0x403C |
| STATUS code | Value |
|---|---|
| CMD_RECEIVED | 0x0001 |
| CMD_IN_PROGRESS | 0x0002 |
| CMD_COMPLETE_PASS / OPEN_FOR_CMDS | 0x0004 |
| CMD_COMPLETE_ERROR / OPEN_FOR_CMDS | 0x0008 |
| CMD_SYSTEM_BUSY | 0xBBBB |
Procedure: poll STATUS until neither IN_PROGRESS nor BUSY → write params to DATAn →
write code\|0x8000 to CMD → poll STATUS for PASS/ERROR → read DATAn results.
Provisioning changes generally require an AN restart to take effect.
**Field note (hardware-verified):** the handler does not clear DATA registers it
doesn't use — stale values persist across commands. GET_SNR must be invoked with
*no* DATA1 write (see its entry).
## Table 5 — command codes (verified against hardware)
| Command | Code | Notes |
|---|---|---|
| CMD_GET_PAIR_SWAP | 0x8000 | |
| CMD_SET_PAIR_SWAP | 0x8001 | needs AN restart |
| Reserved | 0x8002, 0x8003 | |
| CMD_GET_1588_ENABLE | 0x8004 | |
| CMD_SET_1588_ENABLE | 0x8005 | needs AN restart |
| GET_LIMITED_REACH_MODE_ENABLE | 0x8006 | |
| SET_LIMITED_REACH_MODE_ENABLE | 0x8007 | |
| CMD_GET_EEE_MODE | 0x8008 | |
| CMD_SET_EEE_MODE | 0x8009 | needs AN restart |
| CMD_GET_EMI_MODE_ENABLE | 0x800A | **description says: gets SW fast-retrain enable** |
| CMD_SET_EMI_MODE_ENABLE | 0x800B | **sets fast-retrain enables; needs AN restart** |
| CMD_GET_SUB_LF_RF_STATUS | 0x800D | |
| GET_KR_MODE_ENABLE | 0x800E | |
| SET_KR_MODE_ENABLE | 0x800F | |
| CMD_CLEAR_SUB_LF_RF | 0x8010 | |
| CMD_SET_SUB_LF_RF | 0x8011 | |
| GET_SYNC_E_ENABLE | 0x8012 | |
| SET_SYNC_E_ENABLE | 0x8013 | |
| GET_XFI_2P5G_5G_MODE | 0x8016 | |
| SET_XFI_2P5G_5G_MODE | 0x8017 | |
| SET_EEE_STATISTICS | 0x801A | arm counters; issue after link-up |
| GET_EEE_STATISTICS | 0x801B | |
| GET_JUMBO_PACKET | 0x801D | note: GET is 1D |
| SET_JUMBO_PACKET | 0x801C | note: SET is 1C |
| GET_PAUSE_FRAME_MODE | 0x801F | WAP/idle-stuffing niche only |
| SET_PAUSE_FRAME_MODE | 0x8020 | WAP/idle-stuffing niche only |
| GET_LED_TYPE | 0x8021 | |
| SET_LED_TYPE | 0x8022 | |
| GET_WAP_MODE_FRAME_TYPE | 0x8023 | |
| SET_WAP_MODE_FRAME_TYPE | 0x8024 | |
| SET_USXGMII | 0x8026 | |
| GET_USXGMII | 0x8027 | |
| GET_XFI_TX_FILTERS | 0x802B | |
| SET_XFI_TX_FILTERS | 0x802C | |
| GET_XFI_POLARITY | 0x802D | |
| SET_XFI_POLARITY | 0x802E | |
| GET_CURRENT_VOLTAGE | 0x802F | |
| CMD_GET_SNR | 0x8030 | |
| CMD_GET_CURRENT_TEMP | 0x8031 | |
| CMD_SET_UPPER_TEMP_WARNING_LEVEL | 0x8032 | |
| CMD_GET_UPPER_TEMP_WARNING_LEVEL | 0x8033 | |
| CMD_SET_LOWER_TEMP_WARNING_LEVEL | 0x8034 | |
| CMD_GET_LOWER_TEMP_WARNING_LEVEL | 0x8035 | |
| SET_WOL_ENABLE | 0x805A | |
| GET_WOL_ENABLE | 0x805B | |
## Command semantics
### CMD_GET_PAIR_SWAP (0x8000) / CMD_SET_PAIR_SWAP (0x8001)
GET: DATA1 = forced/requested swap value, DATA2 = current swap value.
SET: DATA2 = value to force; needs AN restart.
Encoding (Table 8): bits [7:6] PAIR_D_SEL, [5:4] PAIR_C_SEL, [3:2] PAIR_B_SEL,
[1:0] PAIR_A_SEL; each 2-bit field: 00=Pair A, 01=B, 10=C, 11=D.
### CMD_GET/SET_1588_ENABLE (0x8004/0x8005)
DATA1: 0 = IEEE 1588 disabled, 1 = enabled. Set prior to link-up (or bounce the
link via AN restart). The 1588 engine's own registers are not documented in this
excerpt.
### GET/SET_LIMITED_REACH_MODE_ENABLE (0x8006/0x8007)
DATA1: 0 = LR mode disabled, 1 = enabled.
DATA2 (when enabled): 0 = dynamically switch to LR power-saving level 2 **based on
cable length**; 1/2/3 = forced level 1 (most saving) / 2 / 3 (least).
GET-only DATA3: 1 = currently linked in limited-reach mode — the sole
handler-visible consequence of the DSP's internal length estimate.
### CMD_GET_EEE_MODE (0x8008) / CMD_SET_EEE_MODE (0x8009)
Per-speed EEE mode fields in DATA1 — 10G in bits [1:0], 1G/100M in [3:2]
(interpreted per bits [11:10]), 2.5G in [5:4], 5G in [7:6]:
0 = EEE disabled, 1 = native EEE, 2 = AutogrEEEn fixed latency,
3 = AutogrEEEn variable latency.
DATA2 = AutogrEEEn high threshold, DATA3 = low threshold (default 0x7A12),
DATA4 = AutogrEEEn latency (default 0x480); shared across 2.5/5/10G, ignored at 10G
native. SET needs AN restart.
### CMD_GET/SET_EMI_MODE_ENABLE (0x800A/0x800B)
Datasheet titles say EMI; both descriptions read "SW Fast Retrain enable":
DATA1 = 10G fast retrain (0/1), DATA2 = 5G, DATA3 = 2.5G. SET needs AN restart.
### CMD_GET_SUB_LF_RF_STATUS (0x800D), CLEAR (0x8010), SET (0x8011)
Substitution of local/remote fault codes with IDLE toward the line direction.
GET DATA1: 0 = copper-TX LF/RF passes through, 1 = LF/RF replaced with IDLE.
SET enables substitution, CLEAR disables it.
### GET/SET_KR_MODE_ENABLE (0x800E/0x800F)
DATA1: KR mode on the host interface, 0/1. (KR unsupported when 2500X/5000X mode
is enabled.)
### GET/SET_SYNC_E_ENABLE (0x8012/0x8013)
DATA1 SyncE enable; DATA2/DATA3 M0/M1 recovered-clock mux select (P0 10G, P1–P3
10G/1G, or P0 1G); DATA4 FW-vs-user control; DATA5 bits [1:0] M0/M1 output
disable.
### GET/SET_XFI_2P5G_5G_MODE (0x8016/0x8017)
Rate adaptation for 2.5G/5G on the host side: 0 = 10G idle-stuffing, 1 = X mode,
2 = R mode (per speed in DATA1/DATA2).
### SET_EEE_STATISTICS (0x801A) / GET_EEE_STATISTICS (0x801B)
SET arms the statistics (no params; issue after link-up). GET input selector:
0 = event counters, 1 = time durations. Returns TX(LOC) counter/time in
DATA2 (low 16) / DATA3 (high 16) and RX(REM) in DATA4/DATA5. PHY picks the
10G or 1G counter bank from current link speed.
### GET/SET_JUMBO_PACKET (0x801D/0x801C)
DATA1 enable; DATA2 size option 0 = 10K, 1 = 18K, 2 = 9K.
### GET/SET_PAUSE_FRAME_MODE (0x801F/0x8020)
DATA1: 0 = no pause frame, 1 = enabled. **Only valid for 2.5/5G idle-stuffing in
10G XFI WAP mode** — inert in plain 10G operation.
### GET/SET_LED_TYPE (0x8021/0x8022)
DATA1: 0 = firmware control, 1 = user control.
### GET/SET_WAP_MODE_FRAME_TYPE (0x8023/0x8024)
GET: DATA1 = 1 when priority protocol is IEEE 802.3bz; DATA2 current link frame
type (1 = 802.3bz, 2 = NBASE-T). SET: DATA1 frame-type priority.
### SET/GET_USXGMII (0x8026/0x8027)
DATA1 enable; DATA2 USXGMII autoneg; DATA3 [2:0] single_max_speed (1 = 2.5G,
2 = 5G, 4 = 10G); DATA5: 1 = MAC/PHY frequency unlocked, 0 = locked.
### GET/SET_XFI_TX_FILTERS (0x802B/0x802C)
Host-side XFI TX FIR taps. GET (for the current link speed; invalid if link
down): DATA2 [7:0] pre tap / [15:8] main tap; DATA3 [7:0] post1 / [15:8] post2;
DATA4 [15:8] TX HPF. SET adds DATA1 [15:8] speed selector (0 = 10G
backward-compat, 1 = 100BT, 2 = 1G, 3 = 10G, 4 = 2.5G, 5 = 5G).
### GET/SET_XFI_POLARITY (0x802D/0x802E)
DATA2 TX polarity, DATA3 RX polarity.
### GET_CURRENT_VOLTAGE (0x802F)
DATA1/DATA2 = 0.8 V rail measurements, DATA3 = 1.88 V rail. (Observed: tenths of
mV — 0x1E47 ≈ 775.1 mV, 0x49BC ≈ 1887.6 mV.)
### CMD_GET_SNR (0x8030)
Documented: DATA1 input 0/1 = display SNR in IEEE registers; returns DATA2–5 =
SNR for channels A–D in dB×10. **Hardware-verified behavior: write nothing to
DATA1** — writing the display flag (either value) makes this firmware return
zeros, and the IEEE registers 1.133–1.140 never populate (constant 0x8080)
regardless. Bare invocation returns live per-pair SNR (~27–32 dB on a bench
cable, 0.1–0.4 dB jitter per read). Values are absolute receiver SNR.
### CMD_GET_CURRENT_TEMP (0x8031)
DATA1 = die temperature (°C; observed ~68–70 on bench).
### Temp warning levels (0x8032–0x8035)
Upper/lower limit in °C (two's complement) in DATA1, margin in DATA2, enable in
DATA3.
### SET/GET_WOL_ENABLE (0x805A/0x805B)
DATA1: 0/1. SET takes effect immediately; soft-reset the PHY afterward. Only
relevant at 2.5G and above.
## LED programmability (§1.26)
LED control words live in top-level vendor registers **1.0xA83B (LED Control)**
and **1.0xA83C (LED Control Source)** — five programmable LEDs, per-LED source
masks, 2-bit mode fields (off / blink-on-source / on-on-source), activity
sources: bit 1 RX activity, bit 2 TX activity, with a stretch enable for
visibility. (First documented vendor registers outside the handler; the SMI
example in the registers reference writes another one, 1.0xA820.)
docs/modules/fs/bcm84891l-sfp-registers.md
+79
View File
@@ -0,0 +1,79 @@
# FS SFP-10G-T-100 transport reference — transcription
Transcribed (visually, tables intact) from the FS-provided 4-page
`10GBase-T Coper SFP Registers Operation's Reference for BCM84891.pdf`
(an ODM document — PDF metadata titles it "ABCU-5710RZ / ABCU-5700RZ").
## 1. Serial ID memory (A0h)
Standard SFP MSA serial ID at I2C A0h. Notable factory values (the module is
honest about copper — cf. ../README.md):
| Addr | Field | Value | Meaning |
|---|---|---|---|
| 0 | Identifier | 03 | SFP |
| 1 | Ext. identifier | 04 | MOD4 |
| 2 | Connector | 21 | Copper pigtail (the shipped unit reads 22 = RJ45) |
| 3–10 | Transceiver | 02 00 00 00 00 08 00 00 | 10G Base-XFI to copper / SGMII to copper |
| 11 | Encoding | 00 | 64B/66B (or 8B/10B) |
| 12 | BR, nominal | 67 | 10.3125 GBd |
| 18 | Length (copper) | 64 | 100 m; 30 m minimum in-spec copper length |
| 20–35 | Vendor name | "OEM " | shipped unit reads "FS" |
| 40–55 | Vendor PN | "10GBase-T C100m" | shipped unit reads "SFP-10G-T-100" |
| 64–65 | Options | 00 12 | TX_DISABLE and RX_LOS implemented (shipped: 00 1A) |
| 92 | Diag monitoring | 00 | **no A2h DOM implemented** |
| 93 | Enhanced options | 00 | |
| 94 | SFF-8472 compliance | 00 | digital diagnostics not included |
| 96–127 | Vendor specific | all 00 | |
## 2–3. SMI (I2C→MDIO) protocol for the PHY, with timing
The PHY is a 2-wire device at 8-bit address **0xAC write / 0xAD read**
(`1010110x`). Clause-45 access frames:
**Write (one I2C frame, 6 bytes):**
`S [0xAC] [000+DEVAD] [Reg_H] [Reg_L] [Data_H] [Data_L] P`
**Read (two I2C frames):**
`S [0xAC] [001+DEVAD] [Reg_H] [Reg_L] P` → **delay > 1 ms** →
`S [0xAD] [Data_H] [Data_L] P`
Bit-level example diagrams confirm: every byte is slave-ACKed except the final
read data byte, which the master **NAKs** before STOP. Worked examples: write
0x55AA to 1.0xA820; read 0x8542 from 1.0x0003.
## 4. PHY MMD map
Clause-45 MMDs behind the bridge:
| DEVAD | Block |
|---|---|
| 1 | 10GBASE-T PMA/PMD |
| 3 | 10GBASE-T PCS; XFI_M (XGMII) block also on DEVAD 3 |
| 7 | AN; SGMII block and 10/100/1000BASE-T PCS/PMA/PMD at 7.0xFFE0–0xFFFF |
| 30 | Top level (user-defined) |
Side blocks: JTAG, SPI, BSC, PLL/clock, LED controller.
## 5. Reference access commands and 10G bring-up sequence
The ODM's host-side primitives are exactly our `sff_i2c` ops:
`Write_XGPHY_Register 0xAC [000+DEVAD] RegH RegL DataH DataL` and
`Read_XGPHY_Register 0xAC [001+DEVAD] RegH RegL, >1 ms, 0xAD DataH DataL`.
Reference sequence "set PHY to work in 10GBE rate" (write in order):
| Frame | Register = value | Meaning |
|---|---|---|
| AC 01 00 00 20 40 | 1.0 = 0x2040 | PMA control: 10G speed select |
| AC 01 00 07 00 09 | 1.7 = 0x0009 | PMA control 2: 10GBASE-T type |
| AC 07 00 10 10 01 | 7.16 = 0x1001 | AN advertisement |
| AC 07 00 20 10 03 | 7.32 = 0x1003 | 10GBASE-T AN control |
| AC 07 00 3C 00 08 | 7.60 = 0x0008 | **EEE advertisement — advertises 10GBASE-T EEE** |
| AC 07 00 40 00 00 | 7.64 = 0x0000 | |
| AC 07 80 00 00 10 | 7.0x8000 = 0x0010 | vendor AN register |
| AC 07 00 00 B2 00 | 7.0 = 0xB200 | AN control: enable + restart |
The EEE-advertisement line means the reference bring-up (and possibly the module
firmware's own defaults) leaves 10GBASE-T EEE negotiable — verify and disable
for measurement runs (see the probe results in README.md).
docs/modules/wiitek/README.md
+45
View File
@@ -0,0 +1,45 @@
# Wiitek UF-RJ45-10G-100 (Marvell CUX3610)
Test-set module; lying fake-SR EEPROM (passes stock ixgbe qualification). Reached over RollBall ([../README.md](../README.md)).
## ⚠ DANGER: bricks permanently on certain reads
Both original Wiiteks were bricked **permanently** by register exploration — the death survives cold power cycles and reseats.
- The CUX3610's integrated microcontroller (Marvell Alaska-M, PHY ID 0x002B0BF4, firmware 12.1.5.0) boots from onboard non-volatile storage. The high vendor register windows (3.0x8000+, 31.0xF000+) reached over RollBall are **µC-mapped peripheral space, not PHY-core MDIO**. A read of a trapped peripheral crashes the µC mid-operation and corrupts its persistent boot state; it comes up FATAL forever after.
- **The trap: any register whose low byte is 0x64 in a high window (register high-byte ≥ 0x80), on any devad.** Module 1 died reading 3.0x8064, module 2 reading 31.0xF064. The mailbox writes the address bytes, then the µC dies executing the access — the command never needs to complete. 3.0x8064 is a known QCA808x CDT status register; the ODM firmware appears to emulate/intercept a CDT block there and crash on a cold read. A sloppy `(reg & 0xFF) == 0x64` decode explains both deaths with one bug.
- Rules for any Marvell/RollBall module:
- **Never sweep vendor register windows. Never read `*.0x??64` (high-byte ≥ 0x80).**
- Single targeted reads only, on registers with a documented reason.
- Recovery needs a vendor firmware image + the boot-download protocol (1.0xC050 boot status, 1.0xD0F0–D0F3 download) — we have no CUX3610 image, so bricks are effectively dead. A ghost I2C device at 7-bit 0x57 (returns zeros) is the ROM bootloader waiting for a download.
The `rollball_ixgbe.py` client hard-guards the blacklist and raises *before* touching hardware — it structurally cannot repeat the kill.
## Safe register set
The shared IEEE 802.3an set ([../README.md](../README.md)) — SNR margin (offset-0x8000 encoding; saw A 9.1 / B 7.1 / C 7.7 / D 8.9 dB), PCS latches, AN status, retrain. Plus, proven safe in vendor space:
| Registers | What |
|---|---|
| 1.0xC011/12 | Firmware version |
| 1.0xC050 | Boot status |
Not available in safe space: pre-FEC counter, cable length — those live in the µC vendor space that killed the modules.
## VCT/TDR candidates (unverified; single-shot, sacrificial unit only)
Templates from kernel drivers for sibling parts — never a sweep, never near `*.0x??64`:
- **88Q2220 TDR recipe** (`marvell-88q2xxx.c`, same 0x002b0bXX family, cited from "the Marvell API"), all MMD 3:
| Register | Value / meaning |
|---|---|
| TDR_RESET 0xFECA | init 0x0D90, clear 0x1D90 |
| 0xFED9 / 0xFEDA / 0xFEDE | Calibration: 0x010E / 0x00EB / 0x0058 |
| TDR_STATUS 0xFEDD | Write 0x0002 to start; ~500 ms test. Read: bits[1:0]=01 done; [7:4] verdict (0x7 OK / 0xE open / 0x3 short / 0x5 noise); [15:8] distance in meters |
Single-pair on the Q2220; the 4-pair CUX3610 likely has per-pair variants nearby. Low bytes nowhere near the 0x64 trap.
- **QCA-style CDT** (`qcom/qcom.h`): 3.0x8064 CDT_STATUS, 3.0x8065–0x8068 per-pair results, 3.0x8074–0x807E thresholds. **This IS the trap address** — only ever entered via the full start sequence, never a cold status read; treat as off-limits absent strong evidence.
- Doc-mining lead for the 4-pair pattern: `gtAdvVct.c` in the Marvell qd-dsdt GPL dumps (e.g. github.com/andy928/xpenology `arch/arm/plat-feroceon/mv_hal/qd-dsdt/`).
The Marvell 88E151x datasheet PDF in this directory is family reference material.
docs/modules/wiitek/marvell-ethernet-phys-alaska-88e151x-datasheet.pdf
BIN
View File
Binary file not shown.