]>
Commit | Line | Data |
---|---|---|
0a6c33e8 RK |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ======= | |
4 | phylink | |
5 | ======= | |
6 | ||
7 | Overview | |
8 | ======== | |
9 | ||
10 | phylink is a mechanism to support hot-pluggable networking modules | |
67e80b99 RK |
11 | directly connected to a MAC without needing to re-initialise the |
12 | adapter on hot-plug events. | |
0a6c33e8 RK |
13 | |
14 | phylink supports conventional phylib-based setups, fixed link setups | |
15 | and SFP (Small Formfactor Pluggable) modules at present. | |
16 | ||
17 | Modes of operation | |
18 | ================== | |
19 | ||
20 | phylink has several modes of operation, which depend on the firmware | |
21 | settings. | |
22 | ||
23 | 1. PHY mode | |
24 | ||
25 | In PHY mode, we use phylib to read the current link settings from | |
26 | the PHY, and pass them to the MAC driver. We expect the MAC driver | |
27 | to configure exactly the modes that are specified without any | |
28 | negotiation being enabled on the link. | |
29 | ||
30 | 2. Fixed mode | |
31 | ||
32 | Fixed mode is the same as PHY mode as far as the MAC driver is | |
33 | concerned. | |
34 | ||
35 | 3. In-band mode | |
36 | ||
37 | In-band mode is used with 802.3z, SGMII and similar interface modes, | |
38 | and we are expecting to use and honor the in-band negotiation or | |
39 | control word sent across the serdes channel. | |
40 | ||
41 | By example, what this means is that: | |
42 | ||
43 | .. code-block:: none | |
44 | ||
45 | ð { | |
46 | phy = <&phy>; | |
47 | phy-mode = "sgmii"; | |
48 | }; | |
49 | ||
50 | does not use in-band SGMII signalling. The PHY is expected to follow | |
51 | exactly the settings given to it in its :c:func:`mac_config` function. | |
52 | The link should be forced up or down appropriately in the | |
53 | :c:func:`mac_link_up` and :c:func:`mac_link_down` functions. | |
54 | ||
55 | .. code-block:: none | |
56 | ||
57 | ð { | |
58 | managed = "in-band-status"; | |
59 | phy = <&phy>; | |
60 | phy-mode = "sgmii"; | |
61 | }; | |
62 | ||
63 | uses in-band mode, where results from the PHY's negotiation are passed | |
64 | to the MAC through the SGMII control word, and the MAC is expected to | |
65 | acknowledge the control word. The :c:func:`mac_link_up` and | |
66 | :c:func:`mac_link_down` functions must not force the MAC side link | |
67 | up and down. | |
68 | ||
69 | Rough guide to converting a network driver to sfp/phylink | |
70 | ========================================================= | |
71 | ||
72 | This guide briefly describes how to convert a network driver from | |
73 | phylib to the sfp/phylink support. Please send patches to improve | |
74 | this documentation. | |
75 | ||
76 | 1. Optionally split the network driver's phylib update function into | |
91a208f2 RK |
77 | two parts dealing with link-down and link-up. This can be done as |
78 | a separate preparation commit. | |
0a6c33e8 | 79 | |
91a208f2 RK |
80 | An older example of this preparation can be found in git commit |
81 | fc548b991fb0, although this was splitting into three parts; the | |
82 | link-up part now includes configuring the MAC for the link settings. | |
83 | Please see :c:func:`mac_link_up` for more information on this. | |
0a6c33e8 RK |
84 | |
85 | 2. Replace:: | |
86 | ||
87 | select FIXED_PHY | |
88 | select PHYLIB | |
89 | ||
90 | with:: | |
91 | ||
92 | select PHYLINK | |
93 | ||
94 | in the driver's Kconfig stanza. | |
95 | ||
96 | 3. Add:: | |
97 | ||
98 | #include <linux/phylink.h> | |
99 | ||
100 | to the driver's list of header files. | |
101 | ||
102 | 4. Add:: | |
103 | ||
104 | struct phylink *phylink; | |
44cc27e4 | 105 | struct phylink_config phylink_config; |
0a6c33e8 RK |
106 | |
107 | to the driver's private data structure. We shall refer to the | |
108 | driver's private data pointer as ``priv`` below, and the driver's | |
109 | private data structure as ``struct foo_priv``. | |
110 | ||
111 | 5. Replace the following functions: | |
112 | ||
113 | .. flat-table:: | |
114 | :header-rows: 1 | |
115 | :widths: 1 1 | |
116 | :stub-columns: 0 | |
117 | ||
118 | * - Original function | |
119 | - Replacement function | |
120 | * - phy_start(phydev) | |
121 | - phylink_start(priv->phylink) | |
122 | * - phy_stop(phydev) | |
123 | - phylink_stop(priv->phylink) | |
124 | * - phy_mii_ioctl(phydev, ifr, cmd) | |
125 | - phylink_mii_ioctl(priv->phylink, ifr, cmd) | |
126 | * - phy_ethtool_get_wol(phydev, wol) | |
127 | - phylink_ethtool_get_wol(priv->phylink, wol) | |
128 | * - phy_ethtool_set_wol(phydev, wol) | |
129 | - phylink_ethtool_set_wol(priv->phylink, wol) | |
130 | * - phy_disconnect(phydev) | |
131 | - phylink_disconnect_phy(priv->phylink) | |
132 | ||
133 | Please note that some of these functions must be called under the | |
134 | rtnl lock, and will warn if not. This will normally be the case, | |
135 | except if these are called from the driver suspend/resume paths. | |
136 | ||
137 | 6. Add/replace ksettings get/set methods with: | |
138 | ||
139 | .. code-block:: c | |
140 | ||
c04d102b RK |
141 | static int foo_ethtool_set_link_ksettings(struct net_device *dev, |
142 | const struct ethtool_link_ksettings *cmd) | |
143 | { | |
144 | struct foo_priv *priv = netdev_priv(dev); | |
145 | ||
146 | return phylink_ethtool_ksettings_set(priv->phylink, cmd); | |
147 | } | |
148 | ||
149 | static int foo_ethtool_get_link_ksettings(struct net_device *dev, | |
150 | struct ethtool_link_ksettings *cmd) | |
151 | { | |
152 | struct foo_priv *priv = netdev_priv(dev); | |
153 | ||
154 | return phylink_ethtool_ksettings_get(priv->phylink, cmd); | |
155 | } | |
156 | ||
157 | 7. Replace the call to:: | |
0a6c33e8 RK |
158 | |
159 | phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface); | |
160 | ||
c04d102b | 161 | and associated code with a call to:: |
0a6c33e8 RK |
162 | |
163 | err = phylink_of_phy_connect(priv->phylink, node, flags); | |
164 | ||
165 | For the most part, ``flags`` can be zero; these flags are passed to | |
96313e1d | 166 | the phy_attach_direct() inside this function call if a PHY is specified |
0a6c33e8 RK |
167 | in the DT node ``node``. |
168 | ||
169 | ``node`` should be the DT node which contains the network phy property, | |
170 | fixed link properties, and will also contain the sfp property. | |
171 | ||
172 | The setup of fixed links should also be removed; these are handled | |
173 | internally by phylink. | |
174 | ||
175 | of_phy_connect() was also passed a function pointer for link updates. | |
176 | This function is replaced by a different form of MAC updates | |
177 | described below in (8). | |
178 | ||
179 | Manipulation of the PHY's supported/advertised happens within phylink | |
180 | based on the validate callback, see below in (8). | |
181 | ||
182 | Note that the driver no longer needs to store the ``phy_interface``, | |
183 | and also note that ``phy_interface`` becomes a dynamic property, | |
184 | just like the speed, duplex etc. settings. | |
185 | ||
186 | Finally, note that the MAC driver has no direct access to the PHY | |
187 | anymore; that is because in the phylink model, the PHY can be | |
188 | dynamic. | |
189 | ||
190 | 8. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to | |
191 | the driver, which is a table of function pointers, and implement | |
192 | these functions. The old link update function for | |
193 | :c:func:`of_phy_connect` becomes three methods: :c:func:`mac_link_up`, | |
194 | :c:func:`mac_link_down`, and :c:func:`mac_config`. If step 1 was | |
195 | performed, then the functionality will have been split there. | |
196 | ||
197 | It is important that if in-band negotiation is used, | |
198 | :c:func:`mac_link_up` and :c:func:`mac_link_down` do not prevent the | |
199 | in-band negotiation from completing, since these functions are called | |
200 | when the in-band link state changes - otherwise the link will never | |
201 | come up. | |
202 | ||
203 | The :c:func:`validate` method should mask the supplied supported mask, | |
204 | and ``state->advertising`` with the supported ethtool link modes. | |
205 | These are the new ethtool link modes, so bitmask operations must be | |
206 | used. For an example, see drivers/net/ethernet/marvell/mvneta.c. | |
207 | ||
208 | The :c:func:`mac_link_state` method is used to read the link state | |
209 | from the MAC, and report back the settings that the MAC is currently | |
210 | using. This is particularly important for in-band negotiation | |
211 | methods such as 1000base-X and SGMII. | |
212 | ||
91a208f2 RK |
213 | The :c:func:`mac_link_up` method is used to inform the MAC that the |
214 | link has come up. The call includes the negotiation mode and interface | |
215 | for reference only. The finalised link parameters are also supplied | |
216 | (speed, duplex and flow control/pause enablement settings) which | |
217 | should be used to configure the MAC when the MAC and PCS are not | |
218 | tightly integrated, or when the settings are not coming from in-band | |
219 | negotiation. | |
220 | ||
0a6c33e8 RK |
221 | The :c:func:`mac_config` method is used to update the MAC with the |
222 | requested state, and must avoid unnecessarily taking the link down | |
223 | when making changes to the MAC configuration. This means the | |
224 | function should modify the state and only take the link down when | |
225 | absolutely necessary to change the MAC configuration. An example | |
226 | of how to do this can be found in :c:func:`mvneta_mac_config` in | |
227 | drivers/net/ethernet/marvell/mvneta.c. | |
228 | ||
229 | For further information on these methods, please see the inline | |
230 | documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`. | |
231 | ||
232 | 9. Remove calls to of_parse_phandle() for the PHY, | |
233 | of_phy_register_fixed_link() for fixed links etc. from the probe | |
234 | function, and replace with: | |
235 | ||
236 | .. code-block:: c | |
237 | ||
238 | struct phylink *phylink; | |
44cc27e4 IC |
239 | priv->phylink_config.dev = &dev.dev; |
240 | priv->phylink_config.type = PHYLINK_NETDEV; | |
0a6c33e8 | 241 | |
44cc27e4 | 242 | phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops); |
0a6c33e8 RK |
243 | if (IS_ERR(phylink)) { |
244 | err = PTR_ERR(phylink); | |
245 | fail probe; | |
246 | } | |
247 | ||
248 | priv->phylink = phylink; | |
249 | ||
250 | and arrange to destroy the phylink in the probe failure path as | |
251 | appropriate and the removal path too by calling: | |
252 | ||
253 | .. code-block:: c | |
254 | ||
255 | phylink_destroy(priv->phylink); | |
256 | ||
257 | 10. Arrange for MAC link state interrupts to be forwarded into | |
258 | phylink, via: | |
259 | ||
260 | .. code-block:: c | |
261 | ||
262 | phylink_mac_change(priv->phylink, link_is_up); | |
263 | ||
264 | where ``link_is_up`` is true if the link is currently up or false | |
1511ed0a VO |
265 | otherwise. If a MAC is unable to provide these interrupts, then |
266 | it should set ``priv->phylink_config.pcs_poll = true;`` in step 9. | |
0a6c33e8 RK |
267 | |
268 | 11. Verify that the driver does not call:: | |
269 | ||
270 | netif_carrier_on() | |
271 | netif_carrier_off() | |
272 | ||
273 | as these will interfere with phylink's tracking of the link state, | |
274 | and cause phylink to omit calls via the :c:func:`mac_link_up` and | |
275 | :c:func:`mac_link_down` methods. | |
276 | ||
277 | Network drivers should call phylink_stop() and phylink_start() via their | |
278 | suspend/resume paths, which ensures that the appropriate | |
279 | :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called | |
280 | as necessary. | |
281 | ||
282 | For information describing the SFP cage in DT, please see the binding | |
283 | documentation in the kernel source tree | |
284 | ``Documentation/devicetree/bindings/net/sff,sfp.txt`` |