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
11directly connected to a MAC without needing to re-initialise the
12adapter on hot-plug events.
13
14phylink supports conventional phylib-based setups, fixed link setups
15and SFP (Small Formfactor Pluggable) modules at present.
16
17Modes of operation
18==================
19
20phylink has several modes of operation, which depend on the firmware
21settings.
22
231. 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
302. Fixed mode
31
32   Fixed mode is the same as PHY mode as far as the MAC driver is
33   concerned.
34
353. 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
41By example, what this means is that:
42
43.. code-block:: none
44
45  &eth {
46    phy = <&phy>;
47    phy-mode = "sgmii";
48  };
49
50does not use in-band SGMII signalling.  The PHY is expected to follow
51exactly the settings given to it in its :c:func:`mac_config` function.
52The 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  &eth {
58    managed = "in-band-status";
59    phy = <&phy>;
60    phy-mode = "sgmii";
61  };
62
63uses in-band mode, where results from the PHY's negotiation are passed
64to the MAC through the SGMII control word, and the MAC is expected to
65acknowledge the control word.  The :c:func:`mac_link_up` and
66:c:func:`mac_link_down` functions must not force the MAC side link
67up and down.
68
69Rough guide to converting a network driver to sfp/phylink
70=========================================================
71
72This guide briefly describes how to convert a network driver from
73phylib to the sfp/phylink support.  Please send patches to improve
74this documentation.
75
761. 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
852. 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
963. Add::
97
98	#include <linux/phylink.h>
99
100   to the driver's list of header files.
101
1024. 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
1115. 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
1376. 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
1577. 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
1908. 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
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
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
2329. 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;
239	priv->phylink_config.dev = &dev.dev;
240	priv->phylink_config.type = PHYLINK_NETDEV;
241
242	phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
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
25710. 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
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.
267
26811. 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
277Network drivers should call phylink_stop() and phylink_start() via their
278suspend/resume paths, which ensures that the appropriate
279:c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
280as necessary.
281
282For information describing the SFP cage in DT, please see the binding
283documentation in the kernel source tree
284``Documentation/devicetree/bindings/net/sff,sfp.txt``
285