From 9cb82ca3fa1bc817d1c9223f244433eb9f167746 Mon Sep 17 00:00:00 2001 From: flamingcow Date: Wed, 12 Aug 2026 21:02:30 -0700 Subject: [PATCH] Re-transcribe BCM84891L MDIO command and SFP register excerpts in full (all 45 commands, complete serial-ID table); scrub doc-provenance attribution and label all our interjections as field notes --- docs/modules/fs/README.md | 6 +- docs/modules/fs/bcm84891l-mdio-commands.md | 787 ++++++++++++++++----- docs/modules/fs/bcm84891l-sfp-registers.md | 188 +++-- 3 files changed, 744 insertions(+), 237 deletions(-) diff --git a/docs/modules/fs/README.md b/docs/modules/fs/README.md index cddffe2..b5e26c5 100644 --- a/docs/modules/fs/README.md +++ b/docs/modules/fs/README.md @@ -52,7 +52,7 @@ Several documented DATA1 returns on this ODM firmware are untrustworthy: die-tem ## ECD — recovered from the OpenBCM SDK, proven on hardware -The ECD register mechanism is absent from the handler catalog and from FS's docs, but the OpenBCM SDK's copper-XGPHY driver (`sdk-6.5.27/src/soc/phy/phy8481.c` `phy_8481_cable_diag` + `phy8481.h`) carries it for the 8483x/8485x/8488x family — and the same SDK drives the identical command-handler registers (1E.0x4005/0x4037/0x4038–3C) as the BCM84891L datasheet, confirming the shared map. Validated on the FS: +The ECD register mechanism is absent from the handler catalog and the datasheet excerpts here, but the OpenBCM SDK's copper-XGPHY driver (`sdk-6.5.27/src/soc/phy/phy8481.c` `phy_8481_cable_diag` + `phy8481.h`) carries it for the 8483x/8485x/8488x family — and the same SDK drives the identical command-handler registers (1E.0x4005/0x4037/0x4038–3C) as the BCM84891L datasheet, confirming the shared map. Validated on the FS: | Register | Role | |---|---| @@ -67,7 +67,9 @@ Observed on a plugged, linked, healthy cable: verdicts OK×4 and per-pair length - Family constraints from the SDK: port must be enabled; unsupported at forced 100M. - `bcm_ecd_probe.py` in phydiag-work implements the recipe. -## Remaining asks to FS +## Missing datasheet chapters + +Chapters the datasheet TOC lists but the excerpts here omit — to source elsewhere: 1. The **ECD chapter** — now for confirming bit meanings rather than unblocking. 2. The **1588 operation chapter** (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). diff --git a/docs/modules/fs/bcm84891l-mdio-commands.md b/docs/modules/fs/bcm84891l-mdio-commands.md index f2a6d9d..f2788aa 100644 --- a/docs/modules/fs/bcm84891l-mdio-commands.md +++ b/docs/modules/fs/bcm84891l-mdio-commands.md @@ -1,215 +1,646 @@ # 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: +Full visual transcription (tables intact) of an excerpt of the Broadcom +datasheet `84891L-DS101` (rev July 9, 2019), file `BCM84891L-MDIO Command Descriptions-.pdf`. +The excerpt contains the cover, the table of contents, and datasheet pages 41–59: +§1.24 MDIO Command Handler Function, §1.25 Command Descriptions (all 45 commands), +and the start of §1.26 General-Purpose LED Programmability (the excerpt ends there). -- §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. +Cabletest field notes discovered on hardware are called out inline as **Field note** +and are distinct from the datasheet text. -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. +Device headline features (cover page): single-chip transceiver-MAC to magnetics for +10GBASE-T (802.3an) / 5GBASE-T / 2.5GBASE-T (802.3bz) / 1000BASE-T (802.3ab) / +100BASE-TX (802.3u) on Cat 6/6A/7 (5G/2.5G/1G/100M also on Cat 5e); IEEE 802.3z, 802.3az; +XFI/10GBASE-KR, USXGMII, 5000BASE-R/X, 2500BASE-R/X, 1000BASE-X (SGMII) MAC interface; +IEEE 1588-2008 v2-compliant; IEEE fast retrain and link monitoring; EEE with AutogrEEEn; +trace-matched output impedance; line-side loopback; low EMI; enhanced cable diagnostics; +jumbo packets up to 18 KB; detection/correction of pair swaps (MDI crossover), pair skew, +pair polarity; autonegotiation with next-page; JTAG/AC-JTAG boundary scan; 0.8 V CMOS core; +1.2/1.8/2.5/3.3 V MDIO I/O; 8 mm × 8 mm BGA. -## Handler protocol (§1.24) +## Chapters the TOC lists but the excerpt omits -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. +**Field note (our analysis, not datasheet text):** the excerpt's own table of contents names +chapters absent from these pages — gaps to source elsewhere. -| Register | Address | -|---|---| -| CMD | 1E.0x4005 | -| STATUS | 1E.0x4037 | -| DATA1–DATA5 | 1E.0x4038–1E.0x403C | +- §1.17 EEE / AutogrEEEn narrative (enabling/disabling AutogrEEEn, **monitoring EEE + readiness** §1.17.5, fast-retrain modes §1.17.6: IEEE FR, Negotiated FR (NFR), + BCM-proprietary FR) +- §1.18 Jumbo Packets, §1.19 HiGig2 Messages Support +- §1.20 Loopback Operation — per-speed PCS/PMA system loopbacks (§1.20.1.1–1.20.1.5) and + **§1.20.2 Copper Line Loopback at PMD/PCS of XFI/10GBASE-KR** +- §1.21 Management Interface, §1.22 TRD (MDI) Interface Pair Swapping, §1.23 SPI Interface + (modes, functional description, READ, memory power-up sequence) +- §1.26 remainder (LED source table / register-bit detail), §1.27 Power Supplies, §1.28 Reset +- **Chapter 2: Register Summary** (datasheet p62+) +- Not in this TOC at all: the ECD (cable-diagnostics) register chapter and the 1588 + operation chapter. -| 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. +## §1.24 MDIO Command Handler Function -**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). +The MDIO Command Handler is a handshake process to provision and monitor features and +guarantee the feature is set properly. The command CODE is written to the Command register +CMD (`0x1E.0x4005`). During the 2-second training phase the status returns +`CMD_SYSTEM_BUSY`; wait up to 2 seconds for the command to execute. -## Table 5 — command codes (verified against hardware) +### Table 5: Features/Commands Using MDIO Command Handler Process -| Command | Code | Notes | +| Feature/Command Name | Description | Command Code | |---|---|---| -| 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 | | +| CMD_GET_PAIR_SWAP | — | 0x8000 | +| CMD_SET_PAIR_SWAP | — | 0x8001 | +| Reserved | — | 0x8002 | +| Reserved | — | 0x8003 | +| CMD_GET_1588_ENABLE | — | 0x8004 | +| CMD_SET_1588_ENABLE | — | 0x8005 | +| GET_LIMITED_REACH_MODE_ENABLE | Gets limited reach mode setting. | 0x8006 | +| SET_LIMITED_REACH_MODE_ENABLE | Enables or disables limited reach mode setting. | 0x8007 | +| CMD_GET_EEE_MODE | — | 0x8008 | +| CMD_SET_EEE_MODE | — | 0x8009 | +| CMD_GET_EMI_MODE_ENABLE | — | 0x800A | +| CMD_SET_EMI_MODE_ENABLE | — | 0x800B | +| CMD_GET_SUB_LF_RF_STATUS | — | 0x800D | +| GET_KR_MODE_ENABLE | Gets KR mode setting. | 0x800E | +| SET_KR_MODE_ENABLE | Enables or disables KR mode setting. | 0x800F | +| CMD_CLEAR_SUB_LF_RF | — | 0x8010 | +| CMD_SET_SUB_LF_RF | — | 0x8011 | +| GET_SYNC_E_ENABLE | Get SyncE enable status | 0x8012 | +| SET_SYNC_E_ENABLE | Set SyncE enable | 0x8013 | +| GET_XFI_2P5G_5G_MODE | — | 0x8016 | +| SET_XFI_2P5G_5G_MODE | — | 0x8017 | +| SET_EEE_STATISTICS | — | 0x801A | +| GET_EEE_STATISTICS | — | 0x801B | +| GET_JUMBO_PACKET | — | 0x801D | +| SET_JUMBO_PACKET | — | 0x801C | +| GET_PAUSE_FRAME_MODE | — | 0x801F | +| SET_PAUSE_FRAME_MODE | — | 0x8020 | +| 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 | Enable/disable wake-on-LAN | 0x805A | +| GET_WOL_ENABLE | Get wake-on-LAN settings | 0x805B | -## Command semantics +To execute a feature, write the associated code (command CODE) in the CMD register. -### 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. +### Table 6: MDIO Command Handler Register Set -### 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. +| Register Name | Description | Address | +|---|---|---| +| CMD | Command | 0x1E.0x4005 | +| STATUS | Status of command | 0x1E.0x4037 | +| DATA1_REG | Data 1 register | 0x1E.0x4038 | +| DATA2_REG | Data 2 register | 0x1E.0x4039 | +| DATA3_REG | Data 3 register | 0x1E.0x403A | +| DATA4_REG | Data 4 register | 0x1E.0x403B | +| DATA5_REG | Data 5 register | 0x1E.0x403C | -### 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. +The STATUS register is a special bidirectional register that reports the status and can be +written by the user. -### 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. +### Table 7: STATUS Codes -### 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. +| STATUS Code Name | Set by | Description | Code Value | +|---|---|---|---| +| CMD_RECEIVED | FW | A command has been received. | 0x0001 | +| CMD_IN_PROGRESS | FW | A command is being serviced. | 0x0002 | +| CMD_COMPLETE_PASS / CMD_OPEN_FOR_CMDS | FW | Last command has been executed successfully. | 0x0004 | +| CMD_COMPLETE_ERROR / CMD_OPEN_FOR_CMDS | FW | Execution of the last command produced an error. | 0x0008 | +| CMD_SYSTEM_BUSY | FW | System is not ready to accept commands. | 0xBBBB | -### 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. +### §1.24.1 Theory of Operation -### GET/SET_KR_MODE_ENABLE (0x800E/0x800F) -DATA1: KR mode on the host interface, 0/1. (KR unsupported when 2500X/5000X mode -is enabled.) +After boot, firmware initializes STATUS to `CMD_COMPLETE_PASS/CMD_OPEN_FOR_CMDS` and CMD to +0x0 (no-op). The user polls STATUS to check handler availability. If STATUS is +`CMD_IN_PROGRESS` or `SYSTEM_BUSY`, wait and check again. Otherwise the user writes the +command to CMD; if CMD bit 15 is written as 1, an interrupt is generated and firmware sets +STATUS to `CMD_RECEIVED` and sends a message to the Service thread to execute the command. -### 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. +The Service thread calls the MDIO Command Handler, which uses the command value as an index +into a command array and returns a function pointer that executes the command. Each command +function sets STATUS to `CMD_IN_PROGRESS`, processes, then returns +`CMD_COMPLETE_PASS/CMD_OPEN_FOR_CMDS` or `CMD_COMPLETE_ERROR/CMD_OPEN_FOR_CMDS` so the user +can poll and read the register results. -### 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). +### §1.24.2 Command Procedure -### 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. +1. Poll STATUS until the previous command is neither `CMD_IN_PROGRESS` nor `SYSTEM_BUSY`. +2. If parameters are required, write them to the DATA registers (see §1.25). +3. When firmware is ready, write the command code/value from Table 5 to the CMD register. +4. Poll STATUS until `CMD_COMPLETE_PASS/CMD_OPEN_FOR_CMDS` or + `CMD_COMPLETE_ERROR/CMD_OPEN_FOR_CMDS`. +5. Read the specified DATA registers for saved results, if applicable. +6. For provisioning features that alter port configuration, restart autonegotiation to + reestablish link with the new parameters (most provisioning processes require this step). -### GET/SET_JUMBO_PACKET (0x801D/0x801C) -DATA1 enable; DATA2 size option 0 = 10K, 1 = 18K, 2 = 9K. +**NOTE:** The recommended STATUS polling period is 100 ms. During the 10GBASE-T training +phase the handler status register does not change for up to two seconds; avoid issuing +commands during training or start polling only after link is up. -### 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. +### §1.24.3 Provisioning and Monitoring Sequences (Figure 15) -### GET/SET_LED_TYPE (0x8021/0x8022) -DATA1: 0 = firmware control, 1 = user control. +Provisioning flow: **Start** → *Read Status Register* → is Status = +`CMD_IN_PROGRESS || CMD_SYSTEM_BUSY`? If **Yes**, loop back to read again. If **No** → +*Write Data Register* → *Write Command Register* → *Read Status Register* → is Status = +`CMD_COMPLETE_PASS || CMD_COMPLETE_ERROR`? If **No**, loop back to read again. If **Yes** → +**End**. -### 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. +### Handler field notes (hardware-verified) -### 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. +- The handler does **not** clear DATA registers it does not use — stale values persist + across commands. Write every parameter register explicitly before any SET, and see + `CMD_GET_SNR` for a GET that must be issued with no DATA1 write. -### 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. +## §1.25 Command Descriptions -### 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.) +### §1.25.1.1 CMD_GET_PAIR_SWAP (0x8000) -### 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. +- **Description:** Gets pair swap values. +- **Input Parameters:** None. +- **Return Results:** DATA1_REG = Forced/requested current swap pair value. DATA2_REG = + Current swap pair value. -### CMD_GET_CURRENT_TEMP (0x8031) -DATA1 = die temperature (°C; observed ~68–70 on bench). +### §1.25.1.2 CMD_SET_PAIR_SWAP (0x8001) -### Temp warning levels (0x8032–0x8035) -Upper/lower limit in °C (two's complement) in DATA1, margin in DATA2, enable in -DATA3. +- **Description:** Sets pair swap values. +- **Input Parameters:** DATA2_REG = Swap pair value to be forced. +- **Return Results:** None. +- **NOTE:** CMD_SET_PAIR_SWAP requires autonegotiation to take place in order to take effect. -### 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. +### §1.25.1.3 Pair Swap Values (Table 8) -## 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.) +| Bits | Description | +|---|---| +| [15:8] | Reserved. | +| [7:6] | PAIR_D_SEL: 00 = Pair A, 01 = Pair B, 10 = Pair C, 11 = Pair D | +| [5:4] | PAIR_C_SEL: 00 = Pair A, 01 = Pair B, 10 = Pair C, 11 = Pair D | +| [3:2] | PAIR_B_SEL: 00 = Pair A, 01 = Pair B, 10 = Pair C, 11 = Pair D | +| [1:0] | PAIR_A_SEL: 00 = Pair A, 01 = Pair B, 10 = Pair C, 11 = Pair D | + +**Field note:** on the FS, reading 0x8000 returns DATA2 = 0x00E4 = identity map (A/B/C/D +straight through), which verifies MDI wiring. + +### §1.25.1.4 CMD_GET_1588_ENABLE (0x8004) + +- **Description:** Returns current value set for internal variable used to enable/disable + IEEE 1588 functionality. +- **Input Parameters:** None. +- **Return Results:** DATA1: 0 = IEEE 1588 is disabled, 1 = IEEE 1588 is enabled. + DATA2 to DATA5: Not used. + +### §1.25.1.5 CMD_SET_1588_ENABLE (0x8005) + +- **Description:** Sets internal variable used to enable/disable IEEE 1588 functionality. + Setting to 1 enables IEEE 1588, 0 disables it. Enable or disable prior to link up. If + changing while the link is already up, bring the link down and back up using an AUTONEG + restart or similar mechanism. +- **Input Parameters:** DATA1: 0 = Disable IEEE 1588, 1 = Enable IEEE 1588. + DATA2 to DATA5: Not used. +- **Return Results:** None. +- **NOTE:** CMD_SET_1588_ENABLE requires autonegotiation to take place to take effect. + +### §1.25.1.6 GET_LIMITED_REACH_MODE_ENABLE (0x8006) + +- **Description:** Returns current value set for internal variable used to enable/disable + limited reach mode functionality. +- **Input Parameters:** None. +- **Return Results:** + - DATA1: 0 = Limited reach mode is disabled, 1 = enabled. + - DATA2 (only valid when DATA1 = 1): 0 = Dynamically switch to LR power saving mode level 2 + based on cable length; 1 = Always forced to LR power saving mode level 1 (most power + saving); 2 = Always forced to level 2 (less saving); 3 = Always forced to level 3 + (least saving). + - DATA3 (valid only when DATA1 = 1): 0 = Currently not linked in limited reach mode, + 1 = Currently linked in limited reach mode. + - DATA4 to DATA5: Not used. + +**Field note:** DATA3 = "currently linked in LR mode" is the only handler-visible trace of +the DSP's internal cable-length estimate. + +### §1.25.1.7 SET_LIMITED_REACH_MODE_ENABLE (0x8007) + +- **Description:** Enables/disables limited reach mode functionality. +- **Input Parameters:** + - DATA1: 0 = Exit limited reach mode, 1 = Enter limited reach mode. + - DATA2 (only valid when DATA1 = 1): 0 = Dynamically switch to LR power saving mode level 2 + based on cable length; 1 = level 1 (most saving); 2 = level 2 (less saving); 3 = level 3 + (least saving). + - DATA3 to DATA5: Not used. +- **Return Results:** None. + +### §1.25.1.8 CMD_GET_EEE_MODE (0x8008) + +- **Description:** Gets AutogrEEEn parameters. +- **Input Parameters:** None. +- **Return Results:** + +| Register | Field | 5G | 2.5G | 1G/100M | 10G | +|---|---|---|---|---|---| +| DATA1_REG | Bits | 7:6 | 5:4 | 3:2 | 1:0 | +| | EEE Disabled | 0 | 0 | 0 | 0 | +| | Native EEE | 1 | 1 | 1 | 1 | +| | AutogrEEEn Fixed Latency | 2 | 2 | 2 | 2 | +| | AutogrEEEn Variable Latency | 3 | 3 | N/A | 3 | +| DATA2_REG | AutogrEEEn High Threshold | 0 | 0 | N/A | 0 | +| DATA3_REG | AutogrEEEn Low Threshold | 0x7A12 | 0x7A12 | N/A | 0x7A12 | +| DATA4_REG | AutogrEEEn Latency | 0x480 | 0x480 | N/A | 0x480 | +| DATA5_REG | Reserved | 0 | 0 | 0 | 0 | + +- **NOTE:** + - DATA1_REG bit[11:10] defines how bit[3:2] works: 0 = bit[3:2] for 1G/100TX EEE; + 1 = bit[3:2] for 100TX EEE only; 2 = bit[3:2] for 1G EEE only; 3 = bit[3:2] for 1G/100TX EEE. + - Although the EEE modes can differ between speeds, the AutogrEEEn parameters for 2.5G/5G/10G + in DATA2_REG–DATA4_REG are shared. The 1G/100M AutogrEEEn parameters are not programmable + and are unaffected by DATA2_REG–DATA4_REG. DATA1_REG[15:8] = Reserved. + - **Example:** When DATA1_REG is 0x00B1, 5G EEE is fixed latency, 2.5G EEE is variable + latency, 1G/100M does not advertise EEE, and 10G is native EEE mode. If the data rate is + 10G, DATA2_REG–DATA4_REG are ignored. If 5G, DATA4_REG is ignored. If 2.5G or 5G, the + AutogrEEEn threshold applies. + +### §1.25.1.9 CMD_SET_EEE_MODE (0x8009) + +- **Description:** Configures IEEE-EEE and AutogrEEEn. +- **Input Parameters:** Same DATA1–DATA5 layout as CMD_GET_EEE_MODE (Table above): DATA1_REG + per-speed mode fields (5G [7:6], 2.5G [5:4], 1G/100M [3:2], 10G [1:0]; 0 = EEE disabled, + 1 = native EEE, 2 = AutogrEEEn fixed latency, 3 = AutogrEEEn variable latency); + DATA2_REG = AutogrEEEn high threshold; DATA3_REG = low threshold (default 0x7A12); + DATA4_REG = AutogrEEEn latency (default 0x480); DATA5_REG = Reserved. Same NOTE and example + as GET. +- **Return Results:** None. +- **NOTE:** CMD_SET_EEE_MODE requires autonegotiation to take place to take effect. + +### §1.25.1.10 CMD_GET_EMI_MODE_ENABLE (0x800A) + +- **Description:** Gets SW Fast Retrain current enable status. +- **Input Parameters:** None. +- **Return Results:** + - DATA1: 10G fast retrain enable — 0 = disabled, 1 = enabled. + - DATA2: 5G fast retrain enable — 0 = disabled, 1 = enabled. + - DATA3: 2.5G fast retrain enable — 0 = disabled, 1 = enabled. + +### §1.25.1.11 CMD_SET_EMI_MODE_ENABLE (0x800B) + +- **Description:** (titled EMI; body reads) Gets/sets SW Fast Retrain enable status. +- **Input Parameters:** + - DATA1: 10G fast retrain — 0 = Disable, 1 = Enable. + - DATA2: 5G fast retrain — 0 = Disable, 1 = Enable. + - DATA3: 2.5G fast retrain — 0 = Disable, 1 = Enable. +- **Return Results:** None. +- **NOTE:** CMD_SET_EMI_MODE_ENABLE requires autonegotiation to take place to take effect. + +### §1.25.1.12 CMD_GET_SUB_LF_RF_STATUS (0x800D) + +- **Description:** Gets current status on the substitution of FAULTS with IDLE going to the + line direction. +- **Input Parameters:** None. +- **Return Results:** Status. DATA1: 0 = Copper TX direction LF/RF is passing through, + 1 = Copper TX direction LF/RF is replaced with IDLE. DATA2 to DATA5: Not used. + +### §1.25.1.13 CMD_CLEAR_SUB_LF_RF (0x8010) + +- **Description:** Disables substitution of FAULTS with IDLE going to the line direction. +- **Input Parameters:** None. +- **Return Results:** None. + +### §1.25.1.14 CMD_SET_SUB_LF_RF (0x8011) + +- **Description:** Enables substitution of FAULTS with IDLE going to the line direction. +- **Input Parameters:** None. +- **Return Results:** None. + +### §1.25.1.15 GET_KR_MODE_ENABLE (0x800E) + +- **Description:** Gets KR mode status setting (enable/disable). +- **Input Parameters:** None. +- **Return Results:** DATA1: 0 = BCM84891L KR mode is disabled, 1 = enabled. + DATA2 to 5: Reserved. + +### §1.25.1.16 SET_KR_MODE_ENABLE (0x800F) + +- **Description:** Sets KR mode status setting (enable/disable). +- **Input Parameters:** DATA1: 0 = BCM84891L KR mode is disabled, 1 = enabled. + DATA2 to 5: Reserved. +- **Return Results:** None. + +### §1.25.1.17 GET_SYNC_E_ENABLE (0x8012) + +- **Description:** Get SyncE enable setting. +- **Input Parameters:** None. +- **Return Results:** + - DATA1: SyncE enable — 0 = disabled, 1 = enabled. + - DATA2: M0 mux select — 0 = P0 10G clock/lock on M0; 1 = P1 10G/1G; 2 = P2 10G/1G; + 3 = P3 10G/1G; 8 = P0 1G clock/lock on M0. + - DATA3: M1 mux select — 0 = P0 10G clock/lock on M1; 1 = P1 10G/1G; 2 = P2 10G/1G; + 3 = P3 10G/1G; 8 = P0 1G clock/lock on M1. + - DATA4: FW Control SyncE Configuration — 0 = User control, 1 = FW control. + - DATA5[0]: M0 mux SYNCE_OEN. DATA5[1]: M1 mux SYNCE_OEN — 0 = Output enabled, + 1 = Output disable. DATA5[15:2]: Reserved. + +### §1.25.1.18 SET_SYNC_E_ENABLE (0x8013) + +- **Description:** Set SyncE enable setting. +- **Input Parameters:** + - DATA1: SyncE enable — 0 = disabled, 1 = enabled. + - DATA2: M0 mux select — 0 = P0 10G clock/lock on M0 (default); 1 = P1 10G/1G; 2 = P2 10G/1G; + 3 = P3 10G/1G; 8 = P0 1G on M0. + - DATA3: M1 mux select — 0 = P0 10G clock/lock on M1 (default); 1 = P1 10G/1G; 2 = P2 10G/1G; + 3 = P3 10G/1G; 8 = P0 1G on M1. + - DATA4: FW Control SyncE Configuration — 0 = User control (default), 1 = Firmware control. + - DATA5[0]: M0 mux SYNCE_OEN. DATA5[1]: M1 mux SYNCE_OEN — 0 = Output enabled, + 1 = Output disable. DATA5[15:2]: Reserved. +- **Return Results:** None. + +### §1.25.1.19 GET_XFI_TX_FILTERS (0x802B) + +- **Description:** Gets current XFI TX filter taps. +- **Input Parameters:** None. +- **Return Results:** + - DATA2: Bit[0:7] = Pre tap, Bit[8:15] = Main tap. + - DATA3: Bit[0:7] = Post1 tap, Bit[8:15] = Post2 tap. + - DATA4: Bit[8:15] = TX HPF. + - DATA5: Reserved. +- **NOTE:** The current link speed is the filter for that speed. If a link is down, the + filter tap is invalid. + +### §1.25.1.20 SET_XFI_TX_FILTERS (0x802C) + +- **Description:** Sets XFI TX filter taps. +- **Input Parameters:** + - DATA1: Bit[0:7] = Reserved; Bit[8:15] = Speed — 0 = Backward-compatible 10G, 1 = 100BT, + 2 = 1G, 3 = 10G, 4 = 2.5G, 5 = 5G. + - DATA2: Bit[0:7] = Pre tap, Bit[8:15] = Main tap. + - DATA3: Bit[0:7] = Post1 tap, Bit[8:15] = Post2 tap. + - DATA4: Bit[8:15] = TX HPF. + - DATA5: Reserved. +- **Return Results:** None. +- **NOTE:** Speed = 0 means 10G; this is for backward-compatibility. + +### §1.25.1.21 GET_XFI_POLARITY (0x802D) + +- **Description:** Gets XFI polarity. +- **Input Parameters:** None. +- **Return Results:** DATA2: TX polarity. DATA3: RX polarity. + +### §1.25.1.22 SET_XFI_POLARITY (0x802E) + +- **Description:** Sets XFI polarity. +- **Input Parameters:** DATA2: TX polarity. DATA3: RX polarity. +- **Return Results:** None. + +### §1.25.1.23 GET_CURRENT_VOLTAGE (0x802F) + +- **Description:** Gets current voltage. +- **Input Parameters:** None. +- **Return Results:** DATA1 = For 0.8V measurement. DATA2 = For 0.8V measurement. + DATA3 = For 1.88V measurement. DATA4 = Reserved. + +**Field note:** observed in tenths of mV — the 0.8 V rails and a 1.88 V rail. + +### §1.25.1.24 CMD_GET_SNR (0x8030) + +- **Description:** Gets SNR value. +- **Input Parameters:** DATA1: 0 = Do not display SNR in IEEE registers, 1 = Display SNR in + IEEE registers. +- **Return Results:** DATA2/10 = SNR for Channel A in dB; DATA3/10 = Channel B; + DATA4/10 = Channel C; DATA5/10 = Channel D. + +**Field note (hardware-verified):** on this ODM firmware, write **nothing** to DATA1 — +writing the display flag (either value) makes the firmware return zeros, and the IEEE +registers 1.133–1.140 never populate (they read a 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**, not IEEE SNR margin, so there is no documented +green/orange/red threshold — the 10GBASE-T operating point must be established empirically +(the graded-noise correlation run) rather than assumed. + +### §1.25.1.25 CMD_GET_CURRENT_TEMP (0x8031) + +- **Description:** Returns the internally derived temperature of the die. DATA1_REG returns + the temperature, when supported. +- **Input Parameters:** None. +- **Return Results:** DATA1_REG = Temperature value. + +**Field note:** observed ~68–70 °C on the bench. See also the firmware-reliability caveat — +temperature-like values can leak into other commands' DATA1. + +### §1.25.1.26 CMD_SET_UPPER_TEMP_WARNING_LEVEL (0x8032) + +- **Description:** Sets the upper-bound of the temperature warning to the value in DATA1_REG. +- **Input Parameters:** DATA1: Upper temperature limit in °C (2s compliment). DATA2: Upper + temperature limit margin in °C (positive number). DATA3: Enable upper temperature warning — + 0 = Disable, 1 = Enable. +- **Return Results:** None. + +### §1.25.1.27 CMD_GET_UPPER_TEMP_WARNING_LEVEL (0x8033) + +- **Description:** Gets the upper-bound of the temperature warning and saves the value to + DATA1_REG. +- **Input Parameters:** None. +- **Return Results:** DATA1: Upper temperature limit in °C (2s compliment). DATA2: Upper + temperature limit margin in °C (positive number). DATA3: Enable upper temperature warning — + 0 = Disable, 1 = Enable. + +### §1.25.1.28 CMD_SET_LOWER_TEMP_WARNING_LEVEL (0x8034) + +- **Description:** Sets the lower-bound of the temperature warning and saves the value to + DATA1_REG. +- **Input Parameters:** DATA1: Lower temperature limit in °C (2s compliment). DATA2: Lower + temperature limit margin in °C (positive number). DATA3: Enable upper temperature warning — + 0 = Disable, 1 = Enable. +- **Return Results:** None. + +### §1.25.1.29 CMD_GET_LOWER_TEMP_WARNING_LEVEL (0x8035) + +- **Description:** Gets the lower bound of the temperature warning to the value in DATA1_REG. +- **Input Parameters:** None. +- **Return Results:** DATA1: Lower temperature limit in °C (2s compliment). DATA2: Lower + temperature limit margin in °C (positive number). DATA3: Enable upper temperature warning — + 0 = Disable, 1 = Enable. + +### §1.25.1.30 GET_WAP_MODE_FRAME_TYPE (0x8023) + +- **Description:** — +- **Input Parameters:** None. +- **Return Results:** + - DATA1: 0 = Reserved; 1 = Priority protocol is IEEE 802.3bz. + - DATA2: Current link frame type — 0 = Reserved, 1 = IEEE 802.3bz, 2 = NBASE-T, 3 = Reserved. + - DATA3 to DATA5: Reserved. + +### §1.25.1.31 SET_WAP_MODE_FRAME_TYPE (0x8024) + +- **Description:** — +- **Input Parameters:** DATA1: Frame type priority — 0 = Reserved, 1 = IEEE 802.3bz. + DATA2 to DATA5: Reserved. +- **Return Results:** None. + +### §1.25.1.32 GET_XFI_2P5G_5G_MODE (0x8016) + +- **Description:** — +- **Input Parameters:** None. +- **Return Results:** + - DATA1: 0 = 10G Idle Stuffing mode for 2.5G; 1 = 2500BASE-X_5000BASE-X mode for 2.5G; + 2 = 2500BASE-R_5000BASE-R mode for 2.5G. + - DATA2: 0 = 10G Idle Stuffing mode for 5G; 1 = 2500BASE-X_5000BASE-X mode for 5G; + 2 = 2500BASE-R_5000BASE-R mode for 5G. + - DATA3 to DATA5: Not used. + +### §1.25.1.33 SET_XFI_2P5G_5G_MODE (0x8017) + +- **Description:** — +- **Input Parameters:** + - DATA1: 0 = 10G Idle Stuffing mode for 2.5G; 1 = 2500BASE-X_5000BASE-X mode for 2.5G; + 2 = 2500BASE-R_5000BASE-R mode for 2.5G. + - DATA2: 0 = 10G Idle Stuffing mode for 5G; 1 = 2500BASE-X_5000BASE-X mode for 5G; + 2 = 2500BASE-R_5000BASE-R mode for 5G. + - DATA3 to DATA5: Not used. +- **Return Results:** None. +- **NOTE:** KR mode is not supported when 2500X or 5000X mode is enabled. + +### §1.25.1.34 SET_EEE_STATISTICS (0x801A) + +- **Description:** Enable EEE statistics. +- **Input Parameters:** None. +- **Return Results:** None. +- **NOTE:** This command must be issued after the link is up. + +### §1.25.1.35 GET_EEE_STATISTICS (0x801B) + +- **Description:** — +- **Input Parameters:** Counter selection — 0 = Select event counters, 1 = Select time duration. +- **Return Results:** DATA2: TX (LOC) counters/time lower 16 bits. DATA3: TX (LOC) + counters/time upper 16 bits. DATA4: RX (REM) counters/time lower 16 bits. DATA5: RX (REM) + counters/time upper 16 bits. +- **NOTE:** PHY selects 10G or 1G based on current link speed. + +### §1.25.1.36 GET_JUMBO_PACKET (0x801D) + +- **Description:** Gets jumbo packet status setting (enable/disable). +- **Input Parameters:** None. +- **Return Results:** DATA1: Current jumbo packet enable status — 0 = disabled, 1 = enabled. + DATA2: Jumbo packet size option — 0 = 10K packet, 1 = 18k packet, 2 = 9k packet. + DATA3 to DATA5: Not used. + +### §1.25.1.37 SET_JUMBO_PACKET (0x801C) + +- **Description:** Sets jumbo packet status setting (enable/disable). +- **Input Parameters:** DATA1: Enable or disable jumbo packet — 0 = Disable, 1 = Enable. + DATA2: Jumbo packet size option — 0 = 10K packet, 1 = 18k packet, 2 = 9k packet. + DATA3 to DATA5: Not used. +- **Return Results:** None. + +### §1.25.1.38 GET_PAUSE_FRAME_MODE (0x801F) + +- **Description:** Gets the pause frame mode status (enable/disable). +- **Input Parameters:** None. +- **Return Results:** DATA1: Pause frame enable status — 0 = No pause frame, 1 = Pause frame + is enabled. DATA2 to 5: Reserved. +- **NOTE:** This is only valid for 2.5/5G Idle Stuffing mode in 10G XFI WAP mode. + +### §1.25.1.39 SET_PAUSE_FRAME_MODE (0x8020) + +- **Description:** Sets the pause frame mode status (enable/disable). +- **Input Parameters:** DATA1: Pause frame enable status — 0 = No pause frame, 1 = Pause frame + is enabled. +- **Return Results:** None. +- **NOTE:** This is only valid for 2.5/5G Idle Stuffing mode in 10G XFI WAP mode. + +### §1.25.1.40 GET_LED_TYPE (0x8021) + +- **Description:** Gets the LED control mode status (enable/disable). +- **Input Parameters:** None. +- **Return Results:** DATA1: Current LED type — 0 = Firmware control, 1 = User control. + DATA2 to DATA5: Reserved. + +### §1.25.1.41 SET_LED_TYPE (0x8022) + +- **Description:** Sets the LED control mode status (enable/disable). +- **Input Parameters:** DATA1: Current LED type — 0 = FW control, 1 = User control. + DATA2 to DATA5: Reserved. +- **Return Results:** None. + +### §1.25.1.42 GET_USXGMII (0x8027) + +- **Description:** Gets the USXGMII mode and AUTONEG function (enable/disable). +- **Input Parameters:** None. +- **Return Results:** + - DATA1: USXGMII enable status — 0 = disabled, 1 = enabled. + - DATA2: USXGMII autonegotiation enable status (only valid if USXGMII is enabled) — + 0 = disabled, 1 = enabled. + - DATA3: [0:2] = single_max_speed — 1 = 2.5G, 2 = 5G, 4 = 10G. + - DATA4: Reserved. + - DATA5: 1 = MAC/PHY frequency unlocked, 0 = MAC/PHY frequency is locked. + +### §1.25.1.43 SET_USXGMII (0x8026) + +- **Description:** Sets the USXGMII mode and AUTONEG function (enable/disable). +- **Input Parameters:** + - DATA1: USXGMII enable — 0 = Disable USXGMII, 1 = Enable USXGMII. + - DATA2: USXGMII autonegotiation enable status (only valid if USXGMII is enabled) — + 0 = Disable autonegotiation, 1 = Enable autonegotiation. + - DATA3: [0:2] = single_max_speed — 1 = 2.5G, 2 = 5G, 4 = 10G. + - DATA4: Reserved. + - DATA5: 1 = MAC/PHY frequency unlocked, 0 = MAC/PHY frequency is locked. +- **Return Results:** None. + +### §1.25.1.44 SET_WOL_ENABLE (0x805A) + +- **Description:** Enable/disable wake-on-LAN (WOL) mode. +- **Input Parameters:** DATA1: WOL mode enable — 0 = Disable WOL mode, 1 = Enable WOL mode. + DATA2 to DATA5: Reserved. +- **Return Results:** None. +- **NOTE:** This command takes effect immediately without need of link re-establishment. + After WOL mode is set, do a soft reset to the PHY prior to its normal operation. WOL mode is + only necessary for 2.5G speed and above. + +### §1.25.1.45 GET_WOL_ENABLE (0x805B) + +- **Description:** Get wake-on-LAN (WOL) mode settings. +- **Input Parameters:** None. +- **Return Results:** DATA1: WOL mode enable — 0 = Disable WOL mode, 1 = Enable WOL mode. + DATA2 to DATA5: Reserved. + +--- + +## §1.26 General-Purpose LED Programmability (excerpt start) + +The BCM84891L has five LED pins, LED1 through LED5, that can be functionally programmed. +Control register words select LED functions for each pin, located in register **LED Control +(DEVAD = 1, Address = 0xA83B)**. + +- LED sources are masked in the Control LEDx Mask register. An LED mask bit should be set to 1 + to allow the source to drive the LED pin. When multiple bits in the Control LEDx Mask + register are set, the LED sources are OR'd together. +- The LEDs are driven by **LED Control (DEVAD = 1, Address = 0xA83B)** and **LED Control + Source (DEVAD = 1, Address = 0xA83C)** when the mask associated with the LED is enabled. +- In 10G mode, each LED is controlled separately by individual bits of PHYC_CTL_LED_CTL. The + LEDx_OE_N enables the LEDx output. LEDx_CTL controls the mode: + - 00 = LED is off. + - 01 = LED blinks based on the selected source. The blink cycle is programmed by 10GBASE-T + Control LEDx bit [3:0]. + - 10 = LED is ON based on the selected source registers. + - 11 = reserved. +- Each of the five LEDs has a maskable source register bit (see Table 9 — not in this excerpt). +- Activity LED: unmask bit 1 (receiver activity) and/or bit 2 (transmitter activity) in the + associated Control LEDx Mask register. In **LED Control Source (DEVAD = 1, Address = 0xA83C)**, + bit 1 provides receiver activity status and bit 2 provides transmitter activity status. To + make the activity pulse visible, set the Stretch_En bit associated with the selected LED pin. + +*(The excerpt ends here; the LED source table and the remainder of §1.26–§1.28 are not +included — see the omitted-chapters list above.)* diff --git a/docs/modules/fs/bcm84891l-sfp-registers.md b/docs/modules/fs/bcm84891l-sfp-registers.md index 3d589dc..d1a30b5 100644 --- a/docs/modules/fs/bcm84891l-sfp-registers.md +++ b/docs/modules/fs/bcm84891l-sfp-registers.md @@ -1,79 +1,153 @@ # 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"). +Full visual transcription (tables intact) of a 4-page excerpt +`10GBase-T Coper SFP Registers Operation's Reference for BCM84891.pdf` (the pages are +numbered "Page N of 19", so this is a 4-page excerpt of a 19-page ODM document; PDF +metadata titles it "ABCU-5710RZ / ABCU-5700RZ"). Page banner: +"100/1000Base-T or 10/5/2.5GBase-T Copper SFP+ Transceiver; Cat 6a/7 up to 100 m at 10GBase; +Cat 5 or better up to 100 m at 100/1000Base; 0–70 °C or −40–85 °C." -## 1. Serial ID memory (A0h) +Cabletest field notes (shipped-unit deviations from the reference values, and findings) are +marked **Field note**. -Standard SFP MSA serial ID at I2C A0h. Notable factory values (the module is -honest about copper — cf. ../README.md): +## 1. Serial ID Memory Contents (I2C A0h) -| 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 | | +The 10GBase-T Copper SFP provides standard serial ID compliant with SFP MSA, accessed at +address A0h via the 2-wire serial CMOS EEPROM protocol. -## 2–3. SMI (I2C→MDIO) protocol for the PHY, with timing +### Base ID Fields -The PHY is a 2-wire device at 8-bit address **0xAC write / 0xAD read** -(`1010110x`). Clause-45 access frames: +| Addr | Size (B) | Field | Description / Contents | Hex | +|---|---|---|---|---| +| 0 | 1 | Identifier | Type of Serial transceiver (SFP) | 03 | +| 1 | 1 | Ext. Identifier | Extended identifier of type serial transceiver (MOD4) | 04 | +| 2 | 1 | Connector | Code of optical connector type (Copper) | 21 | +| 3–10 | 8 | Transceiver | 10G Base-XFI to Copper or SGMII to Copper | 02 00 00 00 00 08 00 00 | +| 11 | 1 | Encoding | 64B/66B (or 8B/10B) | 00 | +| 12 | 1 | BR, Nominal | Nominal baud rate, unit of 100 MBd (10.3125 GBd for 10GBase-T) | 67 | +| 13 | 1 | Rate Identifier | Type of rate select functionality (Unspecified) | 00 | +| 14 | 1 | Length (SMF9um)-km | Link length supported for single mode fiber, units of km | 00 | +| 15 | 1 | Length (SMF9um) | Link length supported for 9/125um fiber, units of 100m | 00 | +| 16 | 1 | Length (50um) | Link length supported for 50/125um OM2 fiber, units of 10m | 00 | +| 17 | 1 | Length (62.5um) | Link length supported for 62.5/125um OM1 fiber, units of 10m | 00 | +| 18 | 1 | Length (OM4 or copper cable) | Link length for 50um OM4 fiber, units of 10m. Alternatively copper or direct-attach cable, units of m. For copper links, specifies minimum link length (30m) supported while operating in compliance with applicable standards using copper cable. | 64 | +| 19 | 1 | Length (OM3) | Link length supported for 50um OM3 fiber, units of 10m | 00 | +| 20–35 | 16 | Vendor Name | SFP vendor name (ASCII) "OEM " | 4F 45 4D 20 20 20 20 20 20 20 20 20 20 20 20 20 | +| 36 | 1 | Transceiver | Code for electronic or optical compatibility | 00 | +| 37–39 | 3 | Vendor OUI | SFP vendor IEEE company ID; all zero = unspecified | 00 00 00 | +| 40–55 | 16 | Vendor PN | Part number (ASCII) "10GBase-T C100m" | 31 30 47 42 61 73 65 2D 54 20 42 21 30 30 6D 20 | +| 56–59 | 4 | Vendor rev | Revision (ASCII); all zero = unspecified (1.0 revision) | 31 2E 30 20 | +| 60–61 | 2 | Wavelength | Laser wavelength (Passive/Active Cable Spec Compliance). 00 for both bytes = wavelength/cable spec compliance unspecified. | 00 00 | +| 62 | 1 | Unallocated | | 00 | +| 63 | 1 | CC_BASE | Check code for Base ID Fields — LSB of checksum of addresses 0–62 | xx | -**Write (one I2C frame, 6 bytes):** -`S [0xAC] [000+DEVAD] [Reg_H] [Reg_L] [Data_H] [Data_L] P` +### Extended ID Fields -**Read (two I2C frames):** -`S [0xAC] [001+DEVAD] [Reg_H] [Reg_L] P` → **delay > 1 ms** → -`S [0xAD] [Data_H] [Data_L] P` +| Addr | Size (B) | Field | Description / Contents | Hex | +|---|---|---|---|---| +| 64–65 | 2 | Option | Which optional transceiver signals are implemented: TX_DISABLE and RX_LOS are implemented | 00 12 | +| 66 | 1 | BR, max | Upper bit-rate margin, units of %; 00 = not specified | 00 | +| 67 | 1 | BR, min | Lower bit-rate margin, units of %; 00 = not specified | 00 | +| 68–83 | 16 | Vendor SN | Serial number (ASCII) | xx… | +| 84–91 | 8 | Date code | Manufacturing date: Year (2B), Month (2B), Day (2B), vendor lot code, may be blank (2B) | xx… | +| 92 | 1 | Diagnostic Monitoring Type | Which type of diagnostic monitoring is implemented (if any) | 00 | +| 93 | 1 | Enhanced Options | Which optional enhanced features are implemented (if any) | 00 | +| 94 | 1 | SFF-8472 Compliance | Which SFF-8472 revision the transceiver complies with; 00 = digital diagnostics not included/undefined | 00 | +| 95 | 1 | CC_EX | Check code for Extended ID Fields (addresses 64–94) | xx | -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. +### Vendor Specific ID Fields -## 4. PHY MMD map +| Addr | Size (B) | Field | Description / Contents | Hex | +|---|---|---|---|---| +| 96–127 | 32 | Vendor specific | Vendor Specific EEPROM | all 00 | +| 128–255 | 128 | Reserved | Reserved for SFF-8079 | all 00 | -Clause-45 MMDs behind the bridge: +**Field note:** the shipped FS unit deviates from these reference values where it is *more* +honest about being copper — Connector reads 22 (RJ45) not 21; Vendor Name reads "FS"; +Vendor PN reads "SFP-10G-T-100"; Options read 00 1A. Critically, address 92 (Diagnostic +Monitoring Type) = 00 → **no A2h DOM is implemented** (the "optical DOM" some tools expect +is absent; only the PHY command handler exposes temperature/voltage/SNR). + +## 2. SMI (I2C→MDIO) Communication Protocol for the SFP's PHY + +The Copper SFP serial ID is at A0h. The physical IC (the PHY) is also accessible via 2-wire +bus at address **ACh** — the PHY address is `1010110x` where x is the R/W bit (0xAC write / +0xAD read). + +- **PHY register write — one I2C frame:** after START, send 0xAC (PHY address), then + `000+DevAD` (device address of PHY), then Reg_H and Reg_L (register address), then Data_H + and Data_L, before STOP. +- **PHY register read — two I2C frames:** first frame sends 0xAC and `001+DevAD` with Reg_H, + Reg_L before STOP. Second frame sends 0xAD after START, then reads Data_H, Data_L before + STOP. + +## 3. SMI Reading and Writing Time Sequence + +**SMI Write register** (6 I2C bytes): `S [0xAC] [000+DevAD] [Reg_H] [Reg_L] [Data_H] [Data_L] P` +- 1st byte: 0xAC (8 bits) +- 2nd byte: 0b000 + DEVAD (5 bits) +- 3–4 bytes: Register Address (16 bits) +- 5–6 bytes: Write Data (16 bits) + +**SMI Read register** (7 I2C bytes, two frames): +`S [0xAC] [001+DevAD] [Reg_H] [Reg_L] P` → **Delay > 1 mS** → `S [0xAD] [Data_H] [Data_L] P` +- 1st byte: 0xAC (8 bits) +- 2nd byte: 0b001 + DEVAD (5 bits) +- 3–4 bytes: Register Address (16 bits) +- **Delay > 1 mS (Important: for Host access Copper SFP PHY through I²C)** +- 5th byte: 0xAD (8 bits) +- 6–7 bytes: Read Data (16 bits) + +**Bit-level examples** (colored waveform: Start / Master / Slave-ACK / Stop): +- *Write 0x55AA to DEVAD 1 Register 0xA820.* +- *Read 0x8542 from DEVAD 1 Register 0x0003* — note the final read data byte is **NAK**'d by + the master before STOP, and the `Delay > 1 mS` sits between the address frame and the data + read. + +**Field note:** these diagrams are the authority for our `sff_i2c` framing — every written +byte is slave-ACKed, the final read byte is master-NAKed, and the >1 ms inter-frame delay is +mandatory (a single-byte read with no delay sees the bridge as inert/zero). Validated on +hardware; the compound `x` op holds the whole write→delay→read under one bus lock. + +## 4. PHY Device Register Map Summary (Clause-45 MMDs) | 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) | +| 1 | 10GBASE-T PMA/PMD (Clause 45 MMD) | +| 3 | 10GBASE-T PCS (Clause 45 MMD); XFI_M (XGMII) block is DEVAD 3\* | +| 7 | AN (Clause 45 MMD); SGMII (XGMII) and 10/100/1000BASE-T PCS/PMA/PMD at Clause-45 MMD 0xFFE0–0xFFFF | +| 30 | Top Level (User-Defined) (Clause 45 MMD) | -Side blocks: JTAG, SPI, BSC, PLL/clock, LED controller. +Side blocks (below the MMD bus): JTAG, SPI, BSC, PLL/Clock, LED Controller. -## 5. Reference access commands and 10G bring-up sequence +## 5. Accessing PHY Device Register Instructions -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`. +Two host command primitives implement PHY register read/write (command 1 = configuration, +command 2 = check XGPHY status): -Reference sequence "set PHY to work in 10GBE rate" (write in order): +- **Command 1 — `Write_XGPHY_Register p1 p2 p3 p4`:** p1 = 0xAC (8b); p2 = 0b000 + DEVAD (5b); + p3 = Register Address (16b, 2 bytes); p4 = Write Data (16b, 2 bytes). +- **Command 2 — `Read_XGPHY_Register p1 p2 p3 p4 p5 p6`:** p1 = 0xAC (8b); p2 = 0b001 + DEVAD + (5b); p3 = Register Address (16b); p4 = Delay > 1 mS (Important: for Host access Copper SFP + PHY through I2C); p5 = 0xAD (8b); p6 = Read Data (16b). -| Frame | Register = value | Meaning | +**Example — set PHY to work in 10GBE rate** (write these 8 frames one by one; the doc text +says "9 commands" but lists 8). The datasheet gives only the `Write_PHY_Register …` frames; +the `Register = value` column is a mechanical decode of the frame bytes, and the **Meaning +column is our annotation, not datasheet text**. + +| Frame | Register = value | Meaning (our annotation) | |---|---|---| -| 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 | +| `Write_PHY_Register AC 01 00 00 20 40` | 1.0x0000 = 0x2040 | PMA control: 10G speed select | +| `Write_PHY_Register AC 01 00 07 00 09` | 1.0x0007 = 0x0009 | PMA control 2: 10GBASE-T type | +| `Write_PHY_Register AC 07 00 10 10 01` | 7.0x0010 = 0x1001 | AN advertisement | +| `Write_PHY_Register AC 07 00 20 10 03` | 7.0x0020 = 0x1003 | 10GBASE-T AN control | +| `Write_PHY_Register AC 07 00 3C 00 08` | 7.0x003C = 0x0008 | EEE advertisement — advertises 10GBASE-T EEE | +| `Write_PHY_Register AC 07 00 40 00 00` | 7.0x0040 = 0x0000 | | +| `Write_PHY_Register AC 07 80 00 00 10` | 7.0x8000 = 0x0010 | vendor AN register | +| `Write_PHY_Register AC 07 00 00 B2 00` | 7.0x0000 = 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). +**Field note:** the EEE-advertisement line (7.0x003C = 0x0008) means the reference bring-up — +and possibly the module firmware's own defaults — leaves 10GBASE-T EEE negotiable. Verify and +force EEE/AutogrEEEn off for measurement runs (see the EEE-off recipe and probe results in +[README.md](README.md)).