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
11 directly connected to a MAC without needing to re-initialise the
12 adapter on hot-plug events.
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
77 two parts dealing with link-down and link-up. This can be done as
78 a separate preparation commit.
79
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.
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;
105 struct phylink_config phylink_config;
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
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::
158
159 phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface);
160
161 and associated code with a call to::
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
166 the phy_attach_direct() inside this function call if a PHY is specified
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:`mac_get_caps` method is optional, and if provided should
204 return the phylink MAC capabilities that are supported for the passed
205 ``interface`` mode. In general, there is no need to implement this method.
206 Phylink will use these capabilities in combination with permissible
207 capabilities for ``interface`` to determine the allowable ethtool link
208 modes.
209
210 The :c:func:`mac_link_state` method is used to read the link state
211 from the MAC, and report back the settings that the MAC is currently
212 using. This is particularly important for in-band negotiation
213 methods such as 1000base-X and SGMII.
214
215 The :c:func:`mac_link_up` method is used to inform the MAC that the
216 link has come up. The call includes the negotiation mode and interface
217 for reference only. The finalised link parameters are also supplied
218 (speed, duplex and flow control/pause enablement settings) which
219 should be used to configure the MAC when the MAC and PCS are not
220 tightly integrated, or when the settings are not coming from in-band
221 negotiation.
222
223 The :c:func:`mac_config` method is used to update the MAC with the
224 requested state, and must avoid unnecessarily taking the link down
225 when making changes to the MAC configuration. This means the
226 function should modify the state and only take the link down when
227 absolutely necessary to change the MAC configuration. An example
228 of how to do this can be found in :c:func:`mvneta_mac_config` in
229 ``drivers/net/ethernet/marvell/mvneta.c``.
230
231 For further information on these methods, please see the inline
232 documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
233
234 9. Fill-in the :c:type:`struct phylink_config <phylink_config>` fields with
235 a reference to the :c:type:`struct device <device>` associated to your
236 :c:type:`struct net_device <net_device>`:
237
238 .. code-block:: c
239
240 priv->phylink_config.dev = &dev.dev;
241 priv->phylink_config.type = PHYLINK_NETDEV;
242
243 Fill-in the various speeds, pause and duplex modes your MAC can handle:
244
245 .. code-block:: c
246
247 priv->phylink_config.mac_capabilities = MAC_SYM_PAUSE | MAC_10 | MAC_100 | MAC_1000FD;
248
249 10. Some Ethernet controllers work in pair with a PCS (Physical Coding Sublayer)
250 block, that can handle among other things the encoding/decoding, link
251 establishment detection and autonegotiation. While some MACs have internal
252 PCS whose operation is transparent, some other require dedicated PCS
253 configuration for the link to become functional. In that case, phylink
254 provides a PCS abstraction through :c:type:`struct phylink_pcs <phylink_pcs>`.
255
256 Identify if your driver has one or more internal PCS blocks, and/or if
257 your controller can use an external PCS block that might be internally
258 connected to your controller.
259
260 If your controller doesn't have any internal PCS, you can go to step 11.
261
262 If your Ethernet controller contains one or several PCS blocks, create
263 one :c:type:`struct phylink_pcs <phylink_pcs>` instance per PCS block within
264 your driver's private data structure:
265
266 .. code-block:: c
267
268 struct phylink_pcs pcs;
269
270 Populate the relevant :c:type:`struct phylink_pcs_ops <phylink_pcs_ops>` to
271 configure your PCS. Create a :c:func:`pcs_get_state` function that reports
272 the inband link state, a :c:func:`pcs_config` function to configure your
273 PCS according to phylink-provided parameters, and a :c:func:`pcs_validate`
274 function that report to phylink all accepted configuration parameters for
275 your PCS:
276
277 .. code-block:: c
278
279 struct phylink_pcs_ops foo_pcs_ops = {
280 .pcs_validate = foo_pcs_validate,
281 .pcs_get_state = foo_pcs_get_state,
282 .pcs_config = foo_pcs_config,
283 };
284
285 Arrange for PCS link state interrupts to be forwarded into
286 phylink, via:
287
288 .. code-block:: c
289
290 phylink_pcs_change(pcs, link_is_up);
291
292 where ``link_is_up`` is true if the link is currently up or false
293 otherwise. If a PCS is unable to provide these interrupts, then
294 it should set ``pcs->pcs_poll = true;`` when creating the PCS.
295
296 11. If your controller relies on, or accepts the presence of an external PCS
297 controlled through its own driver, add a pointer to a phylink_pcs instance
298 in your driver private data structure:
299
300 .. code-block:: c
301
302 struct phylink_pcs *pcs;
303
304 The way of getting an instance of the actual PCS depends on the platform,
305 some PCS sit on an MDIO bus and are grabbed by passing a pointer to the
306 corresponding :c:type:`struct mii_bus <mii_bus>` and the PCS's address on
307 that bus. In this example, we assume the controller attaches to a Lynx PCS
308 instance:
309
310 .. code-block:: c
311
312 priv->pcs = lynx_pcs_create_mdiodev(bus, 0);
313
314 Some PCS can be recovered based on firmware information:
315
316 .. code-block:: c
317
318 priv->pcs = lynx_pcs_create_fwnode(of_fwnode_handle(node));
319
320 12. Populate the :c:func:`mac_select_pcs` callback and add it to your
321 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` set of ops. This function
322 must return a pointer to the relevant :c:type:`struct phylink_pcs <phylink_pcs>`
323 that will be used for the requested link configuration:
324
325 .. code-block:: c
326
327 static struct phylink_pcs *foo_select_pcs(struct phylink_config *config,
328 phy_interface_t interface)
329 {
330 struct foo_priv *priv = container_of(config, struct foo_priv,
331 phylink_config);
332
333 if ( /* 'interface' needs a PCS to function */ )
334 return priv->pcs;
335
336 return NULL;
337 }
338
339 See :c:func:`mvpp2_select_pcs` for an example of a driver that has multiple
340 internal PCS.
341
342 13. Fill-in all the :c:type:`phy_interface_t <phy_interface_t>` (i.e. all MAC to
343 PHY link modes) that your MAC can output. The following example shows a
344 configuration for a MAC that can handle all RGMII modes, SGMII and 1000BaseX.
345 You must adjust these according to what your MAC and all PCS associated
346 with this MAC are capable of, and not just the interface you wish to use:
347
348 .. code-block:: c
349
350 phy_interface_set_rgmii(priv->phylink_config.supported_interfaces);
351 __set_bit(PHY_INTERFACE_MODE_SGMII,
352 priv->phylink_config.supported_interfaces);
353 __set_bit(PHY_INTERFACE_MODE_1000BASEX,
354 priv->phylink_config.supported_interfaces);
355
356 14. Remove calls to of_parse_phandle() for the PHY,
357 of_phy_register_fixed_link() for fixed links etc. from the probe
358 function, and replace with:
359
360 .. code-block:: c
361
362 struct phylink *phylink;
363
364 phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
365 if (IS_ERR(phylink)) {
366 err = PTR_ERR(phylink);
367 fail probe;
368 }
369
370 priv->phylink = phylink;
371
372 and arrange to destroy the phylink in the probe failure path as
373 appropriate and the removal path too by calling:
374
375 .. code-block:: c
376
377 phylink_destroy(priv->phylink);
378
379 15. Arrange for MAC link state interrupts to be forwarded into
380 phylink, via:
381
382 .. code-block:: c
383
384 phylink_mac_change(priv->phylink, link_is_up);
385
386 where ``link_is_up`` is true if the link is currently up or false
387 otherwise.
388
389 16. Verify that the driver does not call::
390
391 netif_carrier_on()
392 netif_carrier_off()
393
394 as these will interfere with phylink's tracking of the link state,
395 and cause phylink to omit calls via the :c:func:`mac_link_up` and
396 :c:func:`mac_link_down` methods.
397
398 Network drivers should call phylink_stop() and phylink_start() via their
399 suspend/resume paths, which ensures that the appropriate
400 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
401 as necessary.
402
403 For information describing the SFP cage in DT, please see the binding
404 documentation in the kernel source tree
405 ``Documentation/devicetree/bindings/net/sff,sfp.yaml``.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.