122 lines · plain
1.. SPDX-License-Identifier: GPL-2.02.. _phy_link_topology:3 4=================5PHY link topology6=================7 8Overview9========10 11The PHY link topology representation in the networking stack aims at representing12the hardware layout for any given Ethernet link.13 14An Ethernet interface from userspace's point of view is nothing but a15:c:type:`struct net_device <net_device>`, which exposes configuration options16through the legacy ioctls and the ethtool netlink commands. The base assumption17when designing these configuration APIs were that the link looks something like ::18 19 +-----------------------+ +----------+ +--------------+20 | Ethernet Controller / | | Ethernet | | Connector / |21 | MAC | ------ | PHY | ---- | Port | ---... to LP22 +-----------------------+ +----------+ +--------------+23 struct net_device struct phy_device24 25Commands that needs to configure the PHY will go through the net_device.phydev26field to reach the PHY and perform the relevant configuration.27 28This assumption falls apart in more complex topologies that can arise when,29for example, using SFP transceivers (although that's not the only specific case).30 31Here, we have 2 basic scenarios. Either the MAC is able to output a serialized32interface, that can directly be fed to an SFP cage, such as SGMII, 1000BaseX,3310GBaseR, etc.34 35The link topology then looks like this (when an SFP module is inserted) ::36 37 +-----+ SGMII +------------+38 | MAC | ------- | SFP Module |39 +-----+ +------------+40 41Knowing that some modules embed a PHY, the actual link is more like ::42 43 +-----+ SGMII +--------------+44 | MAC | -------- | PHY (on SFP) |45 +-----+ +--------------+46 47In this case, the SFP PHY is handled by phylib, and registered by phylink through48its SFP upstream ops.49 50Now some Ethernet controllers aren't able to output a serialized interface, so51we can't directly connect them to an SFP cage. However, some PHYs can be used52as media-converters, to translate the non-serialized MAC MII interface to a53serialized MII interface fed to the SFP ::54 55 +-----+ RGMII +-----------------------+ SGMII +--------------+56 | MAC | ------- | PHY (media converter) | ------- | PHY (on SFP) |57 +-----+ +-----------------------+ +--------------+58 59This is where the model of having a single net_device.phydev pointer shows its60limitations, as we now have 2 PHYs on the link.61 62The phy_link topology framework aims at providing a way to keep track of every63PHY on the link, for use by both kernel drivers and subsystems, but also to64report the topology to userspace, allowing to target individual PHYs in configuration65commands.66 67API68===69 70The :c:type:`struct phy_link_topology <phy_link_topology>` is a per-netdevice71resource, that gets initialized at netdevice creation. Once it's initialized,72it is then possible to register PHYs to the topology through :73 74:c:func:`phy_link_topo_add_phy`75 76Besides registering the PHY to the topology, this call will also assign a unique77index to the PHY, which can then be reported to userspace to refer to this PHY78(akin to the ifindex). This index is a u32, ranging from 1 to U32_MAX. The value790 is reserved to indicate the PHY doesn't belong to any topology yet.80 81The PHY can then be removed from the topology through82 83:c:func:`phy_link_topo_del_phy`84 85These function are already hooked into the phylib subsystem, so all PHYs that86are linked to a net_device through :c:func:`phy_attach_direct` will automatically87join the netdev's topology.88 89PHYs that are on a SFP module will also be automatically registered IF the SFP90upstream is phylink (so, no media-converter).91 92PHY drivers that can be used as SFP upstream need to call :c:func:`phy_sfp_attach_phy`93and :c:func:`phy_sfp_detach_phy`, which can be used as a94.attach_phy / .detach_phy implementation for the95:c:type:`struct sfp_upstream_ops <sfp_upstream_ops>`.96 97UAPI98====99 100There exist a set of netlink commands to query the link topology from userspace,101see ``Documentation/networking/ethtool-netlink.rst``.102 103The whole point of having a topology representation is to assign the phyindex104field in :c:type:`struct phy_device <phy_device>`. This index is reported to105userspace using the ``ETHTOOL_MSG_PHY_GET`` ethtnl command. Performing a DUMP operation106will result in all PHYs from all net_device being listed. The DUMP command107accepts either a ``ETHTOOL_A_HEADER_DEV_INDEX`` or ``ETHTOOL_A_HEADER_DEV_NAME``108to be passed in the request to filter the DUMP to a single net_device.109 110The retrieved index can then be passed as a request parameter using the111``ETHTOOL_A_HEADER_PHY_INDEX`` field in the following ethnl commands :112 113* ``ETHTOOL_MSG_STRSET_GET`` to get the stats string set from a given PHY114* ``ETHTOOL_MSG_CABLE_TEST_ACT`` and ``ETHTOOL_MSG_CABLE_TEST_ACT``, to perform115 cable testing on a given PHY on the link (most likely the outermost PHY)116* ``ETHTOOL_MSG_PSE_SET`` and ``ETHTOOL_MSG_PSE_GET`` for PHY-controlled PoE and PSE settings117* ``ETHTOOL_MSG_PLCA_GET_CFG``, ``ETHTOOL_MSG_PLCA_SET_CFG`` and ``ETHTOOL_MSG_PLCA_GET_STATUS``118 to set the PLCA (Physical Layer Collision Avoidance) parameters119 120Note that the PHY index can be passed to other requests, which will silently121ignore it if present and irrelevant.122