1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 .. _phy_link_topology: 2 .. _phy_link_topology:
3 3
4 ================= 4 =================
5 PHY link topology 5 PHY link topology
6 ================= 6 =================
7 7
8 Overview 8 Overview
9 ======== 9 ========
10 10
11 The PHY link topology representation in the ne 11 The PHY link topology representation in the networking stack aims at representing
12 the hardware layout for any given Ethernet lin 12 the hardware layout for any given Ethernet link.
13 13
14 An Ethernet interface from userspace's point o 14 An Ethernet interface from userspace's point of view is nothing but a
15 :c:type:`struct net_device <net_device>`, whic 15 :c:type:`struct net_device <net_device>`, which exposes configuration options
16 through the legacy ioctls and the ethtool netl 16 through the legacy ioctls and the ethtool netlink commands. The base assumption
17 when designing these configuration APIs were t 17 when designing these configuration APIs were that the link looks something like ::
18 18
19 +-----------------------+ +---------- 19 +-----------------------+ +----------+ +--------------+
20 | Ethernet Controller / | | Ethernet 20 | Ethernet Controller / | | Ethernet | | Connector / |
21 | MAC | ------ | PHY 21 | MAC | ------ | PHY | ---- | Port | ---... to LP
22 +-----------------------+ +---------- 22 +-----------------------+ +----------+ +--------------+
23 struct net_device struct phy_d 23 struct net_device struct phy_device
24 24
25 Commands that needs to configure the PHY will 25 Commands that needs to configure the PHY will go through the net_device.phydev
26 field to reach the PHY and perform the relevan 26 field to reach the PHY and perform the relevant configuration.
27 27
28 This assumption falls apart in more complex to 28 This assumption falls apart in more complex topologies that can arise when,
29 for example, using SFP transceivers (although 29 for example, using SFP transceivers (although that's not the only specific case).
30 30
31 Here, we have 2 basic scenarios. Either the MA 31 Here, we have 2 basic scenarios. Either the MAC is able to output a serialized
32 interface, that can directly be fed to an SFP 32 interface, that can directly be fed to an SFP cage, such as SGMII, 1000BaseX,
33 10GBaseR, etc. 33 10GBaseR, etc.
34 34
35 The link topology then looks like this (when a 35 The link topology then looks like this (when an SFP module is inserted) ::
36 36
37 +-----+ SGMII +------------+ 37 +-----+ SGMII +------------+
38 | MAC | ------- | SFP Module | 38 | MAC | ------- | SFP Module |
39 +-----+ +------------+ 39 +-----+ +------------+
40 40
41 Knowing that some modules embed a PHY, the act 41 Knowing that some modules embed a PHY, the actual link is more like ::
42 42
43 +-----+ SGMII +--------------+ 43 +-----+ SGMII +--------------+
44 | MAC | -------- | PHY (on SFP) | 44 | MAC | -------- | PHY (on SFP) |
45 +-----+ +--------------+ 45 +-----+ +--------------+
46 46
47 In this case, the SFP PHY is handled by phylib 47 In this case, the SFP PHY is handled by phylib, and registered by phylink through
48 its SFP upstream ops. 48 its SFP upstream ops.
49 49
50 Now some Ethernet controllers aren't able to o 50 Now some Ethernet controllers aren't able to output a serialized interface, so
51 we can't directly connect them to an SFP cage. 51 we can't directly connect them to an SFP cage. However, some PHYs can be used
52 as media-converters, to translate the non-seri 52 as media-converters, to translate the non-serialized MAC MII interface to a
53 serialized MII interface fed to the SFP :: 53 serialized MII interface fed to the SFP ::
54 54
55 +-----+ RGMII +-----------------------+ S 55 +-----+ RGMII +-----------------------+ SGMII +--------------+
56 | MAC | ------- | PHY (media converter) | -- 56 | MAC | ------- | PHY (media converter) | ------- | PHY (on SFP) |
57 +-----+ +-----------------------+ 57 +-----+ +-----------------------+ +--------------+
58 58
59 This is where the model of having a single net 59 This is where the model of having a single net_device.phydev pointer shows its
60 limitations, as we now have 2 PHYs on the link 60 limitations, as we now have 2 PHYs on the link.
61 61
62 The phy_link topology framework aims at provid 62 The phy_link topology framework aims at providing a way to keep track of every
63 PHY on the link, for use by both kernel driver 63 PHY on the link, for use by both kernel drivers and subsystems, but also to
64 report the topology to userspace, allowing to 64 report the topology to userspace, allowing to target individual PHYs in configuration
65 commands. 65 commands.
66 66
67 API 67 API
68 === 68 ===
69 69
70 The :c:type:`struct phy_link_topology <phy_lin 70 The :c:type:`struct phy_link_topology <phy_link_topology>` is a per-netdevice
71 resource, that gets initialized at netdevice c 71 resource, that gets initialized at netdevice creation. Once it's initialized,
72 it is then possible to register PHYs to the to 72 it is then possible to register PHYs to the topology through :
73 73
74 :c:func:`phy_link_topo_add_phy` 74 :c:func:`phy_link_topo_add_phy`
75 75
76 Besides registering the PHY to the topology, t 76 Besides registering the PHY to the topology, this call will also assign a unique
77 index to the PHY, which can then be reported t 77 index to the PHY, which can then be reported to userspace to refer to this PHY
78 (akin to the ifindex). This index is a u32, ra 78 (akin to the ifindex). This index is a u32, ranging from 1 to U32_MAX. The value
79 0 is reserved to indicate the PHY doesn't belo 79 0 is reserved to indicate the PHY doesn't belong to any topology yet.
80 80
81 The PHY can then be removed from the topology 81 The PHY can then be removed from the topology through
82 82
83 :c:func:`phy_link_topo_del_phy` 83 :c:func:`phy_link_topo_del_phy`
84 84
85 These function are already hooked into the phy 85 These function are already hooked into the phylib subsystem, so all PHYs that
86 are linked to a net_device through :c:func:`ph 86 are linked to a net_device through :c:func:`phy_attach_direct` will automatically
87 join the netdev's topology. 87 join the netdev's topology.
88 88
89 PHYs that are on a SFP module will also be aut 89 PHYs that are on a SFP module will also be automatically registered IF the SFP
90 upstream is phylink (so, no media-converter). 90 upstream is phylink (so, no media-converter).
91 91
92 PHY drivers that can be used as SFP upstream n 92 PHY drivers that can be used as SFP upstream need to call :c:func:`phy_sfp_attach_phy`
93 and :c:func:`phy_sfp_detach_phy`, which can be 93 and :c:func:`phy_sfp_detach_phy`, which can be used as a
94 .attach_phy / .detach_phy implementation for t 94 .attach_phy / .detach_phy implementation for the
95 :c:type:`struct sfp_upstream_ops <sfp_upstream 95 :c:type:`struct sfp_upstream_ops <sfp_upstream_ops>`.
96 96
97 UAPI 97 UAPI
98 ==== 98 ====
99 99
100 There exist a set of netlink commands to query 100 There exist a set of netlink commands to query the link topology from userspace,
101 see ``Documentation/networking/ethtool-netlink 101 see ``Documentation/networking/ethtool-netlink.rst``.
102 102
103 The whole point of having a topology represent 103 The whole point of having a topology representation is to assign the phyindex
104 field in :c:type:`struct phy_device <phy_devic 104 field in :c:type:`struct phy_device <phy_device>`. This index is reported to
105 userspace using the ``ETHTOOL_MSG_PHY_GET`` et 105 userspace using the ``ETHTOOL_MSG_PHY_GET`` ethtnl command. Performing a DUMP operation
106 will result in all PHYs from all net_device be 106 will result in all PHYs from all net_device being listed. The DUMP command
107 accepts either a ``ETHTOOL_A_HEADER_DEV_INDEX` 107 accepts either a ``ETHTOOL_A_HEADER_DEV_INDEX`` or ``ETHTOOL_A_HEADER_DEV_NAME``
108 to be passed in the request to filter the DUMP 108 to be passed in the request to filter the DUMP to a single net_device.
109 109
110 The retrieved index can then be passed as a re 110 The retrieved index can then be passed as a request parameter using the
111 ``ETHTOOL_A_HEADER_PHY_INDEX`` field in the fo 111 ``ETHTOOL_A_HEADER_PHY_INDEX`` field in the following ethnl commands :
112 112
113 * ``ETHTOOL_MSG_STRSET_GET`` to get the stats 113 * ``ETHTOOL_MSG_STRSET_GET`` to get the stats string set from a given PHY
114 * ``ETHTOOL_MSG_CABLE_TEST_ACT`` and ``ETHTOOL 114 * ``ETHTOOL_MSG_CABLE_TEST_ACT`` and ``ETHTOOL_MSG_CABLE_TEST_ACT``, to perform
115 cable testing on a given PHY on the link (mo 115 cable testing on a given PHY on the link (most likely the outermost PHY)
116 * ``ETHTOOL_MSG_PSE_SET`` and ``ETHTOOL_MSG_PS 116 * ``ETHTOOL_MSG_PSE_SET`` and ``ETHTOOL_MSG_PSE_GET`` for PHY-controlled PoE and PSE settings
117 * ``ETHTOOL_MSG_PLCA_GET_CFG``, ``ETHTOOL_MSG_ 117 * ``ETHTOOL_MSG_PLCA_GET_CFG``, ``ETHTOOL_MSG_PLCA_SET_CFG`` and ``ETHTOOL_MSG_PLCA_GET_STATUS``
118 to set the PLCA (Physical Layer Collision Av 118 to set the PLCA (Physical Layer Collision Avoidance) parameters
119 119
120 Note that the PHY index can be passed to other 120 Note that the PHY index can be passed to other requests, which will silently
121 ignore it if present and irrelevant. 121 ignore it if present and irrelevant.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.