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   three parts dealing with link-down, link-up and reconfiguring the
78   MAC settings. This can be done as a separate preparation commit.
79
80   An example of this preparation can be found in git commit fc548b991fb0.
81
822. Replace::
83
84	select FIXED_PHY
85	select PHYLIB
86
87   with::
88
89	select PHYLINK
90
91   in the driver's Kconfig stanza.
92
933. Add::
94
95	#include <linux/phylink.h>
96
97   to the driver's list of header files.
98
994. Add::
100
101	struct phylink *phylink;
102	struct phylink_config phylink_config;
103
104   to the driver's private data structure.  We shall refer to the
105   driver's private data pointer as ``priv`` below, and the driver's
106   private data structure as ``struct foo_priv``.
107
1085. Replace the following functions:
109
110   .. flat-table::
111    :header-rows: 1
112    :widths: 1 1
113    :stub-columns: 0
114
115    * - Original function
116      - Replacement function
117    * - phy_start(phydev)
118      - phylink_start(priv->phylink)
119    * - phy_stop(phydev)
120      - phylink_stop(priv->phylink)
121    * - phy_mii_ioctl(phydev, ifr, cmd)
122      - phylink_mii_ioctl(priv->phylink, ifr, cmd)
123    * - phy_ethtool_get_wol(phydev, wol)
124      - phylink_ethtool_get_wol(priv->phylink, wol)
125    * - phy_ethtool_set_wol(phydev, wol)
126      - phylink_ethtool_set_wol(priv->phylink, wol)
127    * - phy_disconnect(phydev)
128      - phylink_disconnect_phy(priv->phylink)
129
130   Please note that some of these functions must be called under the
131   rtnl lock, and will warn if not. This will normally be the case,
132   except if these are called from the driver suspend/resume paths.
133
1346. Add/replace ksettings get/set methods with:
135
136   .. code-block:: c
137
138    static int foo_ethtool_set_link_ksettings(struct net_device *dev,
139					     const struct ethtool_link_ksettings *cmd)
140    {
141	struct foo_priv *priv = netdev_priv(dev);
142
143	return phylink_ethtool_ksettings_set(priv->phylink, cmd);
144    }
145
146    static int foo_ethtool_get_link_ksettings(struct net_device *dev,
147					     struct ethtool_link_ksettings *cmd)
148    {
149	struct foo_priv *priv = netdev_priv(dev);
150
151	return phylink_ethtool_ksettings_get(priv->phylink, cmd);
152    }
153
1547. Replace the call to:
155
156	phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface);
157
158   and associated code with a call to:
159
160	err = phylink_of_phy_connect(priv->phylink, node, flags);
161
162   For the most part, ``flags`` can be zero; these flags are passed to
163   the of_phy_attach() inside this function call if a PHY is specified
164   in the DT node ``node``.
165
166   ``node`` should be the DT node which contains the network phy property,
167   fixed link properties, and will also contain the sfp property.
168
169   The setup of fixed links should also be removed; these are handled
170   internally by phylink.
171
172   of_phy_connect() was also passed a function pointer for link updates.
173   This function is replaced by a different form of MAC updates
174   described below in (8).
175
176   Manipulation of the PHY's supported/advertised happens within phylink
177   based on the validate callback, see below in (8).
178
179   Note that the driver no longer needs to store the ``phy_interface``,
180   and also note that ``phy_interface`` becomes a dynamic property,
181   just like the speed, duplex etc. settings.
182
183   Finally, note that the MAC driver has no direct access to the PHY
184   anymore; that is because in the phylink model, the PHY can be
185   dynamic.
186
1878. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to
188   the driver, which is a table of function pointers, and implement
189   these functions. The old link update function for
190   :c:func:`of_phy_connect` becomes three methods: :c:func:`mac_link_up`,
191   :c:func:`mac_link_down`, and :c:func:`mac_config`. If step 1 was
192   performed, then the functionality will have been split there.
193
194   It is important that if in-band negotiation is used,
195   :c:func:`mac_link_up` and :c:func:`mac_link_down` do not prevent the
196   in-band negotiation from completing, since these functions are called
197   when the in-band link state changes - otherwise the link will never
198   come up.
199
200   The :c:func:`validate` method should mask the supplied supported mask,
201   and ``state->advertising`` with the supported ethtool link modes.
202   These are the new ethtool link modes, so bitmask operations must be
203   used. For an example, see drivers/net/ethernet/marvell/mvneta.c.
204
205   The :c:func:`mac_link_state` method is used to read the link state
206   from the MAC, and report back the settings that the MAC is currently
207   using. This is particularly important for in-band negotiation
208   methods such as 1000base-X and SGMII.
209
210   The :c:func:`mac_config` method is used to update the MAC with the
211   requested state, and must avoid unnecessarily taking the link down
212   when making changes to the MAC configuration.  This means the
213   function should modify the state and only take the link down when
214   absolutely necessary to change the MAC configuration.  An example
215   of how to do this can be found in :c:func:`mvneta_mac_config` in
216   drivers/net/ethernet/marvell/mvneta.c.
217
218   For further information on these methods, please see the inline
219   documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
220
2219. Remove calls to of_parse_phandle() for the PHY,
222   of_phy_register_fixed_link() for fixed links etc. from the probe
223   function, and replace with:
224
225   .. code-block:: c
226
227	struct phylink *phylink;
228	priv->phylink_config.dev = &dev.dev;
229	priv->phylink_config.type = PHYLINK_NETDEV;
230
231	phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
232	if (IS_ERR(phylink)) {
233		err = PTR_ERR(phylink);
234		fail probe;
235	}
236
237	priv->phylink = phylink;
238
239   and arrange to destroy the phylink in the probe failure path as
240   appropriate and the removal path too by calling:
241
242   .. code-block:: c
243
244	phylink_destroy(priv->phylink);
245
24610. Arrange for MAC link state interrupts to be forwarded into
247    phylink, via:
248
249    .. code-block:: c
250
251	phylink_mac_change(priv->phylink, link_is_up);
252
253    where ``link_is_up`` is true if the link is currently up or false
254    otherwise. If a MAC is unable to provide these interrupts, then
255    it should set ``priv->phylink_config.pcs_poll = true;`` in step 9.
256
25711. Verify that the driver does not call::
258
259	netif_carrier_on()
260	netif_carrier_off()
261
262   as these will interfere with phylink's tracking of the link state,
263   and cause phylink to omit calls via the :c:func:`mac_link_up` and
264   :c:func:`mac_link_down` methods.
265
266Network drivers should call phylink_stop() and phylink_start() via their
267suspend/resume paths, which ensures that the appropriate
268:c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
269as necessary.
270
271For information describing the SFP cage in DT, please see the binding
272documentation in the kernel source tree
273``Documentation/devicetree/bindings/net/sff,sfp.txt``
274