Overview¶

The PHY link topology representation in the networking stack aims at representingthe hardware layout for any given Ethernet link.

An Ethernet interface from userspace’s point of view is nothing but astructnet_device, which exposes configuration optionsthrough the legacy ioctls and the ethtool netlink commands. The base assumptionwhen designing these configuration APIs were that the link looks something like

+-----------------------+        +----------+      +--------------+| Ethernet Controller / |        | Ethernet |      | Connector /  ||       MAC             | ------ |   PHY    | ---- |    Port      | ---... to LP+-----------------------+        +----------+      +--------------+struct net_device               struct phy_device

Commands that needs to configure the PHY will go through the net_device.phydevfield to reach the PHY and perform the relevant configuration.

This assumption falls apart in more complex topologies that can arise when,for example, using SFP transceivers (although that’s not the only specific case).

Here, we have 2 basic scenarios. Either the MAC is able to output a serializedinterface, that can directly be fed to an SFP cage, such as SGMII, 1000BaseX,10GBaseR, etc.

The link topology then looks like this (when an SFP module is inserted)

+-----+  SGMII  +------------+| MAC | ------- | SFP Module |+-----+         +------------+

Knowing that some modules embed a PHY, the actual link is more like

+-----+  SGMII   +--------------+| MAC | -------- | PHY (on SFP) |+-----+          +--------------+

In this case, the SFP PHY is handled by phylib, and registered by phylink throughits SFP upstream ops.

Now some Ethernet controllers aren’t able to output a serialized interface, sowe can’t directly connect them to an SFP cage. However, some PHYs can be usedas media-converters, to translate the non-serialized MAC MII interface to aserialized MII interface fed to the SFP

+-----+  RGMII  +-----------------------+  SGMII  +--------------+| MAC | ------- | PHY (media converter) | ------- | PHY (on SFP) |+-----+         +-----------------------+         +--------------+

This is where the model of having a single net_device.phydev pointer shows itslimitations, as we now have 2 PHYs on the link.

The phy_link topology framework aims at providing a way to keep track of everyPHY on the link, for use by both kernel drivers and subsystems, but also toreport the topology to userspace, allowing to target individual PHYs in configurationcommands.

API¶

Thestructphy_link_topology is a per-netdeviceresource, that gets initialized at netdevice creation. Once it’s initialized,it is then possible to register PHYs to the topology through :

phy_link_topo_add_phy()

Besides registering the PHY to the topology, this call will also assign a uniqueindex to the PHY, which can then be reported to userspace to refer to this PHY(akin to the ifindex). This index is a u32, ranging from 1 to U32_MAX. The value0 is reserved to indicate the PHY doesn’t belong to any topology yet.

The PHY can then be removed from the topology through

phy_link_topo_del_phy()

These function are already hooked into the phylib subsystem, so all PHYs thatare linked to a net_device throughphy_attach_direct() will automaticallyjoin the netdev’s topology.

PHYs that are on a SFP module will also be automatically registered IF the SFPupstream is phylink (so, no media-converter).

PHY drivers that can be used as SFP upstream need to callphy_sfp_attach_phy()andphy_sfp_detach_phy(), which can be used as a.attach_phy / .detach_phy implementation for thestructsfp_upstream_ops.

UAPI¶

There exist a set of netlink commands to query the link topology from userspace,seeDocumentation/networking/ethtool-netlink.rst.

The whole point of having a topology representation is to assign the phyindexfield instructphy_device. This index is reported touserspace using theETHTOOL_MSG_PHY_GET ethtnl command. Performing a DUMP operationwill result in all PHYs from all net_device being listed. The DUMP commandaccepts either aETHTOOL_A_HEADER_DEV_INDEX orETHTOOL_A_HEADER_DEV_NAMEto be passed in the request to filter the DUMP to a single net_device.

The retrieved index can then be passed as a request parameter using theETHTOOL_A_HEADER_PHY_INDEX field in the following ethnl commands :

• ETHTOOL_MSG_STRSET_GET to get the stats string set from a given PHY

• ETHTOOL_MSG_CABLE_TEST_ACT andETHTOOL_MSG_CABLE_TEST_ACT, to performcable testing on a given PHY on the link (most likely the outermost PHY)

• ETHTOOL_MSG_PSE_SET andETHTOOL_MSG_PSE_GET for PHY-controlled PoE and PSE settings

• ETHTOOL_MSG_PLCA_GET_CFG,ETHTOOL_MSG_PLCA_SET_CFG andETHTOOL_MSG_PLCA_GET_STATUSto set the PLCA (Physical Layer Collision Avoidance) parameters

Note that the PHY index can be passed to other requests, which will silentlyignore it if present and irrelevant.