Device Tree Link Mode Configuration for Microchip Switch SoCs

For these the phy-mode is the PCS the switch MAC itself runs.

The -KX and -KR suffixes only describe the medium (AC-coupled backplane); they do not appear in mainline Linux phy-mode strings.

A BASE-T link uses an external Cu PHY; the wire-side PCS lives inside that PHY. The DT phy-mode therefore describes the MAC-to-PHY SerDes interface, not the wire-side PCS. The Microchip driver supports the following MAC-side interfaces toward a BASE-T PHY:

At the time of writing, Microchip does not offer multigig (2.5G, 5G, or 10G) copper PHYs in-house, so boards that need the lower four rows above pair a Microchip switch with a third-party PHY. The corresponding MAC-side modes are supported by the driver and usable with any PHY that speaks the right host interface.

The PHY runs Clause 28 autonegotiation (or its multigig extensions) toward the cable partner and reports the resolved state in-band to the MAC. The DT side uses phy-handle = <&phyX> to reach the PHY on MDIO and, for SGMII / QSGMII / 10G-QXGMII, managed = "in-band-status" so the MAC tracks the PHY’s in-band status updates. See Example A for SGMII, Example E for QSGMII, and Example F for 10G-QXGMII.

Two IEEE 802.3 clauses often come up in this area but describe MDIO bus transactions, not link operation, and therefore do not drive the DT link-mode choice:

These clauses describe how the kernel talks to the PHY on the MDIO bus, not how the MAC-PHY link comes up. phylib selects the right clause from the PHY’s compatible string, so the DT rarely has to say anything about it. When the MDIO controller defaults to Clause 22 and the PHY needs Clause 45, a use-mdio-c45 property on the MDIO bus node switches the default.

The DT expresses the backplane-vs-optical distinction, the fixed-vs-autoneg distinction, and the PHY-vs-SerDes distinction through a small set of link-management properties. The next subsection lists them.

On Sparx5 and LAN969x each MAC port binds to a specific SerDes lane via the phys property, pointing at the serdes phandle with a lane index:

The lane index has hard capability limits (next section). The Microchip SerDes driver rejects a lane bind if the requested phy-mode exceeds the lane’s maximum rate.

The SerDes driver declares three lane classes at lines 24-25 of sparx5_serdes.c, with maximum rates and supported modes as shown below.

LAN969x provides only 10G-class SerDes lanes; it has no 25G lanes. Each lane supports the same mode set as a Sparx5 10G lane, with a maximum of 10 Gbit/s per lane.

LAN966x has no KR-class rates. The driver accepts the following phy-mode strings (see lines 917-931 of lan966x_main.c): MII, RMII, GMII, SGMII, QSGMII, QUSGMII, 1000BASE-X, and 2500BASE-X. For this page that puts LAN966x out of scope for KR work, but in scope for 1000BASE-X/KX links and MAC-to-MAC 2.5G-X links.

LAN9645x is a DSA switch that attaches to a host MAC, typically the LAN966x SoC. Its DT structure differs from the other SoCs in several ways, which the LAN9645x section below documents. The driver reports the following per-port phylink capabilities in lan9645x_phylink.c:

The MACs support 10, 100, 1000FD, and 2500FD rates. LAN9645x has no 5G, 10G, or 25G MACs, and therefore no KR support.

These are the nodes the examples reference via phandle. They are already present in the SoC .dtsi (e.g. sparx5.dtsi) and shown here so the example snippets are unambiguous.

Examples below use the &switch / &mdio3 overlay style.

This is an example of a single-port 1 Gbit/s Cu PHY setup (VSC8221). The PHY runs Clause 28 autonegotiation toward the cable partner over MDIO, and the MAC runs SGMII toward the PHY. The PHY reports the resolved link state in-band to the MAC, so the DT does not need managed = "in-band-status": the phy-handle is sufficient.

Source: the snippet below is the minimal form of the example used on Microchip reference boards with a VSC8221-class PHY.

The switch MAC drives the SerDes in 1000BASE-X mode and attaches to an SFP cage. The switch PCS performs Clause 37 autonegotiation against the SFP module’s own PCS at link bring-up. phylink reacts to SFP insert and remove events on the cage.

The SFP cage node describes the board-level wiring (I2C bus for the EEPROM, GPIOs for los / mod-def0 / tx-disable / tx-fault).

Source: sparx5_pcb134_board.dtsi.

A 10G SFP cage uses the same structure with phy-mode = "10gbase-r" and a 10G-capable SerDes lane; PCB134 does this for its four 10G SFP+ ports.

This example describes a SerDes link with no autonegotiation, no SFP cage, and no external PHY. The board designer fixes both ends to the same rate. Typical use cases are a backplane trace, an on-board MAC-to-MAC connection, and an SFP+ DAC cable (the SerDes driver treats a DAC cable as the same link type as an optical BASE-R or a backplane -KR).

The template is the same at every rate; only speed, phy-mode, microchip,bandwidth, and the SerDes lane index change.

Rate-specific substitutions (Sparx5 lane ranges from the SerDes capability table above; LAN969x has only 10G lanes):

All these modes require full-duplex. The SerDes driver rejects a lane assignment when the lane’s maximum rate falls below the requested rate; see sparx5_serdes_validate() in sparx5_serdes.c.

With no autonegotiation the pause configuration defaults to off or follows an out-of-band agreement. Add pause; inside fixed-link when both ends have agreed on flow control.

This example uses the same physical setup as example C at 1 Gbit/s, with PCS autonegotiation enabled at both ends. The switch PCS exchanges speed, duplex, and pause with the link partner via the Clause 37 base page. Among the direct-SerDes rates that the Microchip SerDes driver supports, 1000BASE-X is the only one with standard PCS autonegotiation; 2500BASE-X has no aneg by spec, and the BASE-R rates would need Clause 73 backplane autoneg (see Known Limitations).

This example carries four independent 1 Gbit/s ports over a single SerDes lane to a Microchip quad Cu PHY (VSC8574). Each port declares its own phy-handle that targets a distinct PHY address on the shared MDIO bus. All four ports share the same SerDes lane through an identical phys value, because QSGMII multiplexes four sub-ports onto one 10G SerDes lane. The SerDes driver configures the lane once; the four MAC blocks on the switch side then de-multiplex the sub-channels.

Source: sparx5_pcb135_board.dtsi.

The four switch ports that form a QSGMII group are not arbitrary. Consult the chip’s port-map table for the valid port-to-SerDes-lane groupings on the target SoC.

This example carries four independent 2.5 Gbit/s ports over a single 10G SerDes lane to an external quad multigig Cu PHY. Like QSGMII, all four ports share the same phys value; unlike QSGMII, the MAC-side PCS is USXGMII-based and carries full in-band rate and status signalling per sub-port, so each port can independently run at 10 Mbit/s, 100 Mbit/s, 1 Gbit/s, or 2.5 Gbit/s. The port requires managed = "in-band-status" so that the MAC tracks the PHY’s per-sub-port rate and link state.

The Microchip driver supports this mode on Sparx5 and LAN969x. At the time of writing Microchip does not produce a quad multigig Cu PHY, so boards using this example pair the switch with a third-party PHY that exposes a 10G-QXGMII host interface.

The switch-side port numbers that form a valid 10G-QXGMII quartet are chip-specific. Consult the SoC datasheet for the valid port-to-SerDes-lane groupings.

Two further notes apply to this example:

The LAN9645x block lives under an MFD parent on the LAN966x SoC. The examples below reference these nodes. Layout follows lan966x-pcb8385-lan9645x-evb.dts.

Each of ports 0-3 pairs with a dedicated on-chip Cu PHY. The MAC-side interface runs GMII, and the Cu PHY handles Clause 28 autonegotiation toward the cable partner.

Source: lan966x-pcb8385-lan9645x-evb.dts.

Ports 5 and 6 are the SerDes ports. A port running at up to 1 Gbit/s attaches to an SFP cage and uses SGMII in-band autonegotiation between the switch PCS and the SFP module.

Source: lan966x-pcb8385-lan9645x-evb.dts.

A 2.5G SFP uses phy-mode = "2500base-x" and drops managed = "in-band-status", because the 2500BASE-X PCS has no standard in-band autonegotiation.

Port 5 or port 6 drives a peer MAC directly, without autonegotiation and without an SFP cage. This example is the LAN9645x equivalent of Example C at 1 Gbit/s.

To reach 2.5 Gbit/s over the same SerDes port, replace 1000base-x with 2500base-x and speed = <1000> with speed = <2500>.

Port 7 (and, when a second uplink is in use, port 8) connects the LAN9645x DSA switch to the host MAC on the LAN966x SoC. The link is a fixed internal connection with clocking agreed at board design time, so the DT describes it as a fixed-link. The ethernet property marks this port as the DSA CPU port and points at the LAN966x MAC port shown in the prerequisite nodes above.

Source: lan966x-pcb8385-lan9645x-evb.dts.

The phy-mode string selects which side inserts the 2 ns RGMII clock delay: rgmii-id puts the delay on both sides, rgmii-rxid and rgmii-txid put it on one side, and plain rgmii relies on external delay. The MAC-side delay logic lives in lan9645x_phylink.c.

When port 4 or port 8 runs in its RGMII variant, it attaches to an external RGMII Cu PHY on the corresponding chip RGMII interface. The board DTSI enables the PHY node that the prerequisite section declared as disabled, and disables the other member of the shadow pair so only one variant is active.

Source: lan966x-pcb8385-lan9645x-evb.dts.

From lines 978-989 of sparx5_switch.c:

Anything else returns PHY_INTERFACE_MODE_NA and the port will not come up in U-Boot.

Consequence: customers needing a backplane or MAC-to-MAC 1G-X / 10G-R link that must be active during U-Boot (for example, netboot) cannot achieve this with the current U-Boot driver. Options:

Same as the example already used in mscc,sparx5_pcb134.dtsi:

The Microchip SerDes driver (sparx5_serdes.c) does not implement 802.3ap / Clause 73 backplane autonegotiation or Clause 72 adaptive equalisation (commonly called "KR link training"). These are OPTIONAL parts of the KR and KX family: the driver brings the link up with static SerDes equalisation presets, the same way the driver already handles DAC (10GBASE-CR) and optical 10GBASE-R links.

For the common cases (short on-board traces, midplane links of moderate length, and DAC cables) the static presets are sufficient, and this is not a functional gap. The board designer statically configures both ends to the same rate at design time.

Clause 73 and Clause 72 only matter when:

Such cases require a different solution: a shorter trace, a retimer, or a rate fallback to 5GBASE-R or 2500BASE-X.

The driver does not expose BASE-R FEC (Clause 74) or RS-FEC (Clause 91, 25G) via DT. The driver picks a default FEC mode per rate. A link partner that requires a specific FEC behaviour currently requires driver changes.

As described above, the U-Boot MSCC eswitch driver today supports only SGMII, QSGMII, and RGMII. U-Boot cannot bring up a KX, KR, BASE-X, or BASE-R link without additional driver work.