1 .. SPDX-License-Identifier: GPL-2.0
2 .. _phy_link_topology:
3
4 =================
5 PHY link topology
6 =================
7
8 Overview
9 ========
10
11 The PHY link topology representation in the ne
12 the hardware layout for any given Ethernet lin
13
14 An Ethernet interface from userspace's point o
15 :c:type:`struct net_device <net_device>`, whic
16 through the legacy ioctls and the ethtool netl
17 when designing these configuration APIs were t
18
19 +-----------------------+ +----------
20 | Ethernet Controller / | | Ethernet
21 | MAC | ------ | PHY
22 +-----------------------+ +----------
23 struct net_device struct phy_d
24
25 Commands that needs to configure the PHY will
26 field to reach the PHY and perform the relevan
27
28 This assumption falls apart in more complex to
29 for example, using SFP transceivers (although
30
31 Here, we have 2 basic scenarios. Either the MA
32 interface, that can directly be fed to an SFP
33 10GBaseR, etc.
34
35 The link topology then looks like this (when a
36
37 +-----+ SGMII +------------+
38 | MAC | ------- | SFP Module |
39 +-----+ +------------+
40
41 Knowing that some modules embed a PHY, the act
42
43 +-----+ SGMII +--------------+
44 | MAC | -------- | PHY (on SFP) |
45 +-----+ +--------------+
46
47 In this case, the SFP PHY is handled by phylib
48 its SFP upstream ops.
49
50 Now some Ethernet controllers aren't able to o
51 we can't directly connect them to an SFP cage.
52 as media-converters, to translate the non-seri
53 serialized MII interface fed to the SFP ::
54
55 +-----+ RGMII +-----------------------+ S
56 | MAC | ------- | PHY (media converter) | --
57 +-----+ +-----------------------+
58
59 This is where the model of having a single net
60 limitations, as we now have 2 PHYs on the link
61
62 The phy_link topology framework aims at provid
63 PHY on the link, for use by both kernel driver
64 report the topology to userspace, allowing to
65 commands.
66
67 API
68 ===
69
70 The :c:type:`struct phy_link_topology <phy_lin
71 resource, that gets initialized at netdevice c
72 it is then possible to register PHYs to the to
73
74 :c:func:`phy_link_topo_add_phy`
75
76 Besides registering the PHY to the topology, t
77 index to the PHY, which can then be reported t
78 (akin to the ifindex). This index is a u32, ra
79 0 is reserved to indicate the PHY doesn't belo
80
81 The PHY can then be removed from the topology
82
83 :c:func:`phy_link_topo_del_phy`
84
85 These function are already hooked into the phy
86 are linked to a net_device through :c:func:`ph
87 join the netdev's topology.
88
89 PHYs that are on a SFP module will also be aut
90 upstream is phylink (so, no media-converter).
91
92 PHY drivers that can be used as SFP upstream n
93 and :c:func:`phy_sfp_detach_phy`, which can be
94 .attach_phy / .detach_phy implementation for t
95 :c:type:`struct sfp_upstream_ops <sfp_upstream
96
97 UAPI
98 ====
99
100 There exist a set of netlink commands to query
101 see ``Documentation/networking/ethtool-netlink
102
103 The whole point of having a topology represent
104 field in :c:type:`struct phy_device <phy_devic
105 userspace using the ``ETHTOOL_MSG_PHY_GET`` et
106 will result in all PHYs from all net_device be
107 accepts either a ``ETHTOOL_A_HEADER_DEV_INDEX`
108 to be passed in the request to filter the DUMP
109
110 The retrieved index can then be passed as a re
111 ``ETHTOOL_A_HEADER_PHY_INDEX`` field in the fo
112
113 * ``ETHTOOL_MSG_STRSET_GET`` to get the stats
114 * ``ETHTOOL_MSG_CABLE_TEST_ACT`` and ``ETHTOOL
115 cable testing on a given PHY on the link (mo
116 * ``ETHTOOL_MSG_PSE_SET`` and ``ETHTOOL_MSG_PS
117 * ``ETHTOOL_MSG_PLCA_GET_CFG``, ``ETHTOOL_MSG_
118 to set the PLCA (Physical Layer Collision Av
119
120 Note that the PHY index can be passed to other
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.