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-pluggabl
11 directly connected to a MAC without needing to
12 adapter on hot-plug events.
13
14 phylink supports conventional phylib-based set
15 and SFP (Small Formfactor Pluggable) modules a
16
17 Modes of operation
18 ==================
19
20 phylink has several modes of operation, which
21 settings.
22
23 1. PHY mode
24
25 In PHY mode, we use phylib to read the curr
26 the PHY, and pass them to the MAC driver.
27 to configure exactly the modes that are spe
28 negotiation being enabled on the link.
29
30 2. Fixed mode
31
32 Fixed mode is the same as PHY mode as far a
33 concerned.
34
35 3. In-band mode
36
37 In-band mode is used with 802.3z, SGMII and
38 and we are expecting to use and honor the i
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 PH
51 exactly the settings given to it in its :c:fun
52 The link should be forced up or down appropria
53 :c:func:`mac_link_up` and :c:func:`mac_link_do
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'
64 to the MAC through the SGMII control word, and
65 acknowledge the control word. The :c:func:`ma
66 :c:func:`mac_link_down` functions must not for
67 up and down.
68
69 Rough guide to converting a network driver to
70 ==============================================
71
72 This guide briefly describes how to convert a
73 phylib to the sfp/phylink support. Please sen
74 this documentation.
75
76 1. Optionally split the network driver's phyli
77 two parts dealing with link-down and link-u
78 a separate preparation commit.
79
80 An older example of this preparation can be
81 fc548b991fb0, although this was splitting i
82 link-up part now includes configuring the M
83 Please see :c:func:`mac_link_up` for more i
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
108 driver's private data pointer as ``priv`` b
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,
126 * - phy_ethtool_get_wol(phydev, wol)
127 - phylink_ethtool_get_wol(priv->phylink,
128 * - phy_ethtool_set_wol(phydev, wol)
129 - phylink_ethtool_set_wol(priv->phylink,
130 * - phy_disconnect(phydev)
131 - phylink_disconnect_phy(priv->phylink)
132
133 Please note that some of these functions mu
134 rtnl lock, and will warn if not. This will
135 except if these are called from the driver
136
137 6. Add/replace ksettings get/set methods with:
138
139 .. code-block:: c
140
141 static int foo_ethtool_set_link_ksetti
142
143 {
144 struct foo_priv *priv = netdev
145
146 return phylink_ethtool_ksettin
147 }
148
149 static int foo_ethtool_get_link_ksetti
150
151 {
152 struct foo_priv *priv = netdev
153
154 return phylink_ethtool_ksettin
155 }
156
157 7. Replace the call to::
158
159 phy_dev = of_phy_connect(dev, node, li
160
161 and associated code with a call to::
162
163 err = phylink_of_phy_connect(priv->phy
164
165 For the most part, ``flags`` can be zero; t
166 the phy_attach_direct() inside this functio
167 in the DT node ``node``.
168
169 ``node`` should be the DT node which contai
170 fixed link properties, and will also contai
171
172 The setup of fixed links should also be rem
173 internally by phylink.
174
175 of_phy_connect() was also passed a function
176 This function is replaced by a different fo
177 described below in (8).
178
179 Manipulation of the PHY's supported/adverti
180 based on the validate callback, see below i
181
182 Note that the driver no longer needs to sto
183 and also note that ``phy_interface`` become
184 just like the speed, duplex etc. settings.
185
186 Finally, note that the MAC driver has no di
187 anymore; that is because in the phylink mod
188 dynamic.
189
190 8. Add a :c:type:`struct phylink_mac_ops <phyl
191 the driver, which is a table of function po
192 these functions. The old link update functi
193 :c:func:`of_phy_connect` becomes three meth
194 :c:func:`mac_link_down`, and :c:func:`mac_c
195 performed, then the functionality will have
196
197 It is important that if in-band negotiation
198 :c:func:`mac_link_up` and :c:func:`mac_link
199 in-band negotiation from completing, since
200 when the in-band link state changes - other
201 come up.
202
203 The :c:func:`mac_get_caps` method is option
204 return the phylink MAC capabilities that ar
205 ``interface`` mode. In general, there is no
206 Phylink will use these capabilities in comb
207 capabilities for ``interface`` to determine
208 modes.
209
210 The :c:func:`mac_link_state` method is used
211 from the MAC, and report back the settings
212 using. This is particularly important for i
213 methods such as 1000base-X and SGMII.
214
215 The :c:func:`mac_link_up` method is used to
216 link has come up. The call includes the neg
217 for reference only. The finalised link para
218 (speed, duplex and flow control/pause enabl
219 should be used to configure the MAC when th
220 tightly integrated, or when the settings ar
221 negotiation.
222
223 The :c:func:`mac_config` method is used to
224 requested state, and must avoid unnecessari
225 when making changes to the MAC configuratio
226 function should modify the state and only t
227 absolutely necessary to change the MAC conf
228 of how to do this can be found in :c:func:`
229 ``drivers/net/ethernet/marvell/mvneta.c``.
230
231 For further information on these methods, p
232 documentation in :c:type:`struct phylink_ma
233
234 9. Fill-in the :c:type:`struct phylink_config
235 a reference to the :c:type:`struct device <
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_NE
242
243 Fill-in the various speeds, pause and duple
244
245 .. code-block:: c
246
247 priv->phylink_config.mac_capabilities
248
249 10. Some Ethernet controllers work in pair wit
250 block, that can handle among other things
251 establishment detection and autonegotiatio
252 PCS whose operation is transparent, some o
253 configuration for the link to become funct
254 provides a PCS abstraction through :c:type
255
256 Identify if your driver has one or more in
257 your controller can use an external PCS bl
258 connected to your controller.
259
260 If your controller doesn't have any intern
261
262 If your Ethernet controller contains one o
263 one :c:type:`struct phylink_pcs <phylink_p
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 phyl
271 configure your PCS. Create a :c:func:`pcs_
272 the inband link state, a :c:func:`pcs_conf
273 PCS according to phylink-provided paramete
274 function that report to phylink all accept
275 your PCS:
276
277 .. code-block:: c
278
279 struct phylink_pcs_ops foo_pcs_ops = {
280 .pcs_validate = foo_pcs_valida
281 .pcs_get_state = foo_pcs_get_s
282 .pcs_config = foo_pcs_config,
283 };
284
285 Arrange for PCS link state interrupts to b
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 i
293 otherwise. If a PCS is unable to provide t
294 it should set ``pcs->pcs_poll = true;`` wh
295
296 11. If your controller relies on, or accepts t
297 controlled through its own driver, add a p
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 actu
305 some PCS sit on an MDIO bus and are grabbe
306 corresponding :c:type:`struct mii_bus <mii
307 that bus. In this example, we assume the c
308 instance:
309
310 .. code-block:: c
311
312 priv->pcs = lynx_pcs_create_mdiodev(bu
313
314 Some PCS can be recovered based on firmwar
315
316 .. code-block:: c
317
318 priv->pcs = lynx_pcs_create_fwnode(of_
319
320 12. Populate the :c:func:`mac_select_pcs` call
321 :c:type:`struct phylink_mac_ops <phylink_m
322 must return a pointer to the relevant :c:t
323 that will be used for the requested link c
324
325 .. code-block:: c
326
327 static struct phylink_pcs *foo_select_
328
329 {
330 struct foo_priv *priv = contai
331
332
333 if ( /* 'interface' needs a PC
334 return priv->pcs;
335
336 return NULL;
337 }
338
339 See :c:func:`mvpp2_select_pcs` for an exam
340 internal PCS.
341
342 13. Fill-in all the :c:type:`phy_interface_t <
343 PHY link modes) that your MAC can output.
344 configuration for a MAC that can handle al
345 You must adjust these according to what yo
346 with this MAC are capable of, and not just
347
348 .. code-block:: c
349
350 phy_interface_set_rgmii(priv->phylink_c
351 __set_bit(PHY_INTERFACE_MODE_SGMII,
352 priv->phylink_config.support
353 __set_bit(PHY_INTERFACE_MODE_1000BASEX
354 priv->phylink_config.support
355
356 14. Remove calls to of_parse_phandle() for the
357 of_phy_register_fixed_link() for fixed lin
358 function, and replace with:
359
360 .. code-block:: c
361
362 struct phylink *phylink;
363
364 phylink = phylink_create(&priv->phylin
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
373 appropriate and the removal path too by ca
374
375 .. code-block:: c
376
377 phylink_destroy(priv->phylink);
378
379 15. Arrange for MAC link state interrupts to b
380 phylink, via:
381
382 .. code-block:: c
383
384 phylink_mac_change(priv->phylink, link
385
386 where ``link_is_up`` is true if the link i
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 tra
395 and cause phylink to omit calls via the :c
396 :c:func:`mac_link_down` methods.
397
398 Network drivers should call phylink_stop() and
399 suspend/resume paths, which ensures that the a
400 :c:type:`struct phylink_mac_ops <phylink_mac_o
401 as necessary.
402
403 For information describing the SFP cage in DT,
404 documentation in the kernel source tree
405 ``Documentation/devicetree/bindings/net/sff,sf
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.