# 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.)