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