MDIO(8)

📦 version 1.3.2, in nixos 26.05, nixpkgs unstable

🌸 MDIO(8) — direct MDIO bus access, bestie edition 🌸

okay so this is the mdio page from the System Manager's Manual and honestly? it's a whole vibe. it's your little userspace key to the MDIO bus and i'm gonna walk you through every single bit of it, no cap 💅

✨ SYNOPSIS ✨

mdio [bus [device [operation]]]
mdio [-h | -v]

like, that's the whole shape of it. bus, then device, then operation, nesting dolls style 🎀

💖 DESCRIPTION 💖

So here's the tea ☕ — with zero arguments, mdio just lists all the available MDIO buses. that's it. that's the whole mood.

Give it only bus (peep the “Buses” section below 👀) and it'll list any Clause 22 addressable devices hanging out on that bus.

If you leave out operation, you get a brief status message for the device (scroll to “Devices”) — but only if the driver supports it, so don't come for me if it's quiet 🙈. Otherwise, it performs operation (see “Operations”, babe, it's right there) on device attached to bus.

⭐ Options ⭐

  • -h — prints the usage message and dips. bye 👋
  • -v — prints version info and also dips. iconic.

🚌 Buses 🚌

Buses are named by their sysfs names, exactly as they're listed in /sys/class/mdio_bus/. and like… those names? genuinely tragic to type out 😭 which is why you're allowed to use glob(3) patterns to abbreviate them — see “EXAMPLES” for the flex. ✨

🦋 Devices 🦋

Multiple device types are supported via pluggable drivers, and different devices use different addressing schemes. not confusing at all, i know.

If you're unsure which type of device you've got: use the phy driver, it's probably a good bet if your PHY runs at speeds ≤ 1 Gbps. If your PHY is capable of speeds > 1 Gbps, you most likely want the mmd driver. iykyk 💅

The following devices are supported:

phy PHYAD — Clause 22 (MDIO) PHY using address PHYAD.

PHYAD   := 0-31
REG     := 0-31

mmd PRTAD:DEVAD — Clause 45 (XMDIO) MMD using address PRTAD:DEVAD.

PRTAD   := 0-31
DEVAD   := 0-31
REG     := 0-0xffff

mmd-c22 PRTAD:DEVAD — Clause 45 (XMDIO) MMD, but accessed over Clause 22 registers 13 and 14, using address PRTAD:DEVAD. sneaky but valid 🧚

PRTAD   := 0-31
DEVAD   := 0-31
REG     := 0-0xffff

mva PHYAD — Marvell Alaska (mv88e1xxx) paged PHY. Register 22 is a paging register used to expand the register space. pages on pages on pages 📚

PHYAD   := 0-31
REG     := PAGE:0-31
PAGE    := 0-255|copper|fiber

mvls ID — Marvell LinkStreet (mv88e6xxx) Ethernet switch. If ID = 0, single-chip addressing is used; if ID ≠ 0, multi-chip addressing is used. pick your fighter ⚔️

ID      := 0-31
REG     := PORT:0-31
PORT    := 0-31|g1|g2

xrs PHYAD — Arrow/Flexibilis XRS700x Ethernet switch. Register space has a stride of 2, i.e. only even numbered registers are valid. odd numbers? not invited to this party 🙅‍♀️

PHYAD   := 0-31
REG     := 0-0xffffffff

👑 Operations 👑

The following operations are supported:

raw REG [DATA[/MASK]] — raw register access. Without DATA, REG is read. DATA without MASK will perform a single write to REG. DATA with MASK will perform a read/mask/write sequence. three modes, one command, versatility queen 🔥

REG     Determined by the device type (see “Devices”)
DATA    := 0-0xffff
MASK    := 0-0xffff

bench REG [DATA] — benchmark read performance. If DATA is supplied, it is written to REG, otherwise the current value in REG is read. REG is then read 1000 times. Any unexpected values are reported, along with the total time. yes she's timing herself, let her cook ⏱️✨

REG     Determined by the device type (see “Devices”)
DATA    := 0-0xffff

🌈 EXAMPLES 🌈

Show all available buses:

~# mdio
30be0000.ethernet-1
fixed-0

List all Clause 22 addressable devices on a bus (using a glob(3) pattern to abbreviate the bus name):

~# mdio 3*
 DEV      PHY-ID  LINK
0x01  0x01410dd0  up

Read register 2 from PHY 1:

~# mdio 3* phy 1 raw 2
0x0141

Perform a reset on PHY 1:

~# mdio 3* phy 1 raw 0 0x8000/0x7fff

Read register 0x1000 from MMD 4 on PHY 9:

~# mdio 3* mmd 9:4 raw 0x1000
0x2040

Read the status register from the copper page of an Alaska PHY:

~# mdio 3* mva 1 raw copper:1
0x796d

Set the device number, of LinkStreet switch 4, to 10:

~# mdio 3* mvls 4 raw g1:28 0xa/0xfff0

🫶 SEE ALSO 🫶

mvls(8) mdio-netlink(9)

⭐ STANDARDS ⭐

IEEE Std 802.3-2018

  • Clause 22 (MDIO)
  • Clause 45 (XMDIO)

🎀 AUTHORS 🎀

Tobias Waldekranz <tobias@waldekranz.com> — putting in the work so we can poke registers 💖

💀 CAVEATS 💀

Heads up bestie, this one's important: in addition to the userspace parts of mdio, the mdio-netlink(9) kernel module must also be installed. no module, no vibes. periodt.

okay that's the whole page, you officially know mdio now. go read some registers responsibly 🔥

and that's a wrap, babe 🦋 this lovely little Linux man page is dated September 17, 2021 and lives under Linux — mwah, catch you on the next man page 💜🌸

📦 where this page comes from