1 .. SPDX-License-Identifier: GPL-2.0
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.
14 phylink supports conventional phylib-based setups, fixed link setups
15 and SFP (Small Formfactor Pluggable) modules at present.
20 phylink has several modes of operation, which depend on the firmware
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.
32 Fixed mode is the same as PHY mode as far as the MAC driver is
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.
41 By example, what this means is that:
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.
58 managed = "in-band-status";
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
69 Rough guide to converting a network driver to sfp/phylink
70 =========================================================
72 This guide briefly describes how to convert a network driver from
73 phylib to the sfp/phylink support. Please send patches to improve
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.
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.
94 in the driver's Kconfig stanza.
98 #include <linux/phylink.h>
100 to the driver's list of header files.
104 struct phylink *phylink;
105 struct phylink_config phylink_config;
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``.
111 5. Replace the following functions:
118 * - Original function
119 - Replacement function
120 * - phy_start(phydev)
121 - phylink_start(priv->phylink)
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)
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.
137 6. Add/replace ksettings get/set methods with:
141 static int foo_ethtool_set_link_ksettings(struct net_device *dev,
142 const struct ethtool_link_ksettings *cmd)
144 struct foo_priv *priv = netdev_priv(dev);
146 return phylink_ethtool_ksettings_set(priv->phylink, cmd);
149 static int foo_ethtool_get_link_ksettings(struct net_device *dev,
150 struct ethtool_link_ksettings *cmd)
152 struct foo_priv *priv = netdev_priv(dev);
154 return phylink_ethtool_ksettings_get(priv->phylink, cmd);
157 7. Replace the call to::
159 phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface);
161 and associated code with a call to::
163 err = phylink_of_phy_connect(priv->phylink, node, flags);
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``.
169 ``node`` should be the DT node which contains the network phy property,
170 fixed link properties, and will also contain the sfp property.
172 The setup of fixed links should also be removed; these are handled
173 internally by phylink.
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).
179 Manipulation of the PHY's supported/advertised happens within phylink
180 based on the validate callback, see below in (8).
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.
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
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.
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
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
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.
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
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``.
231 For further information on these methods, please see the inline
232 documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
234 9. Remove calls to of_parse_phandle() for the PHY,
235 of_phy_register_fixed_link() for fixed links etc. from the probe
236 function, and replace with:
240 struct phylink *phylink;
241 priv->phylink_config.dev = &dev.dev;
242 priv->phylink_config.type = PHYLINK_NETDEV;
244 phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
245 if (IS_ERR(phylink)) {
246 err = PTR_ERR(phylink);
250 priv->phylink = phylink;
252 and arrange to destroy the phylink in the probe failure path as
253 appropriate and the removal path too by calling:
257 phylink_destroy(priv->phylink);
259 10. Arrange for MAC link state interrupts to be forwarded into
264 phylink_mac_change(priv->phylink, link_is_up);
266 where ``link_is_up`` is true if the link is currently up or false
267 otherwise. If a MAC is unable to provide these interrupts, then
268 it should set ``priv->phylink_config.pcs_poll = true;`` in step 9.
270 11. Verify that the driver does not call::
275 as these will interfere with phylink's tracking of the link state,
276 and cause phylink to omit calls via the :c:func:`mac_link_up` and
277 :c:func:`mac_link_down` methods.
279 Network drivers should call phylink_stop() and phylink_start() via their
280 suspend/resume paths, which ensures that the appropriate
281 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
284 For information describing the SFP cage in DT, please see the binding
285 documentation in the kernel source tree
286 ``Documentation/devicetree/bindings/net/sff,sfp.yaml``.