406 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=======4phylink5=======6 7Overview8========9 10phylink is a mechanism to support hot-pluggable networking modules11directly connected to a MAC without needing to re-initialise the12adapter on hot-plug events.13 14phylink supports conventional phylib-based setups, fixed link setups15and SFP (Small Formfactor Pluggable) modules at present.16 17Modes of operation18==================19 20phylink has several modes of operation, which depend on the firmware21settings.22 231. PHY mode24 25 In PHY mode, we use phylib to read the current link settings from26 the PHY, and pass them to the MAC driver. We expect the MAC driver27 to configure exactly the modes that are specified without any28 negotiation being enabled on the link.29 302. Fixed mode31 32 Fixed mode is the same as PHY mode as far as the MAC driver is33 concerned.34 353. In-band mode36 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 or39 control word sent across the serdes channel.40 41By example, what this means is that:42 43.. code-block:: none44 45 ð {46 phy = <&phy>;47 phy-mode = "sgmii";48 };49 50does not use in-band SGMII signalling. The PHY is expected to follow51exactly the settings given to it in its :c:func:`mac_config` function.52The link should be forced up or down appropriately in the53:c:func:`mac_link_up` and :c:func:`mac_link_down` functions.54 55.. code-block:: none56 57 ð {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 passed64to the MAC through the SGMII control word, and the MAC is expected to65acknowledge the control word. The :c:func:`mac_link_up` and66:c:func:`mac_link_down` functions must not force the MAC side link67up and down.68 69Rough guide to converting a network driver to sfp/phylink70=========================================================71 72This guide briefly describes how to convert a network driver from73phylib to the sfp/phylink support. Please send patches to improve74this documentation.75 761. Optionally split the network driver's phylib update function into77 two parts dealing with link-down and link-up. This can be done as78 a separate preparation commit.79 80 An older example of this preparation can be found in git commit81 fc548b991fb0, although this was splitting into three parts; the82 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_PHY88 select PHYLIB89 90 with::91 92 select PHYLINK93 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 the108 driver's private data pointer as ``priv`` below, and the driver's109 private data structure as ``struct foo_priv``.110 1115. Replace the following functions:112 113 .. flat-table::114 :header-rows: 1115 :widths: 1 1116 :stub-columns: 0117 118 * - Original function119 - Replacement function120 * - 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 the134 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:: c140 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 to166 the phy_attach_direct() inside this function call if a PHY is specified167 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 handled173 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 updates177 described below in (8).178 179 Manipulation of the PHY's supported/advertised happens within phylink180 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 PHY187 anymore; that is because in the phylink model, the PHY can be188 dynamic.189 1908. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to191 the driver, which is a table of function pointers, and implement192 these functions. The old link update function for193 :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 was195 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 the199 in-band negotiation from completing, since these functions are called200 when the in-band link state changes - otherwise the link will never201 come up.202 203 The :c:func:`mac_get_caps` method is optional, and if provided should204 return the phylink MAC capabilities that are supported for the passed205 ``interface`` mode. In general, there is no need to implement this method.206 Phylink will use these capabilities in combination with permissible207 capabilities for ``interface`` to determine the allowable ethtool link208 modes.209 210 The :c:func:`mac_link_state` method is used to read the link state211 from the MAC, and report back the settings that the MAC is currently212 using. This is particularly important for in-band negotiation213 methods such as 1000base-X and SGMII.214 215 The :c:func:`mac_link_up` method is used to inform the MAC that the216 link has come up. The call includes the negotiation mode and interface217 for reference only. The finalised link parameters are also supplied218 (speed, duplex and flow control/pause enablement settings) which219 should be used to configure the MAC when the MAC and PCS are not220 tightly integrated, or when the settings are not coming from in-band221 negotiation.222 223 The :c:func:`mac_config` method is used to update the MAC with the224 requested state, and must avoid unnecessarily taking the link down225 when making changes to the MAC configuration. This means the226 function should modify the state and only take the link down when227 absolutely necessary to change the MAC configuration. An example228 of how to do this can be found in :c:func:`mvneta_mac_config` in229 ``drivers/net/ethernet/marvell/mvneta.c``.230 231 For further information on these methods, please see the inline232 documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.233 2349. Fill-in the :c:type:`struct phylink_config <phylink_config>` fields with235 a reference to the :c:type:`struct device <device>` associated to your236 :c:type:`struct net_device <net_device>`:237 238 .. code-block:: c239 240 priv->phylink_config.dev = &dev.dev;241 priv->phylink_config.type = PHYLINK_NETDEV;242 243 Fill-in the various speeds, pause and duplex modes your MAC can handle:244 245 .. code-block:: c246 247 priv->phylink_config.mac_capabilities = MAC_SYM_PAUSE | MAC_10 | MAC_100 | MAC_1000FD;248 24910. Some Ethernet controllers work in pair with a PCS (Physical Coding Sublayer)250 block, that can handle among other things the encoding/decoding, link251 establishment detection and autonegotiation. While some MACs have internal252 PCS whose operation is transparent, some other require dedicated PCS253 configuration for the link to become functional. In that case, phylink254 provides a PCS abstraction through :c:type:`struct phylink_pcs <phylink_pcs>`.255 256 Identify if your driver has one or more internal PCS blocks, and/or if257 your controller can use an external PCS block that might be internally258 connected to your controller.259 260 If your controller doesn't have any internal PCS, you can go to step 11.261 262 If your Ethernet controller contains one or several PCS blocks, create263 one :c:type:`struct phylink_pcs <phylink_pcs>` instance per PCS block within264 your driver's private data structure:265 266 .. code-block:: c267 268 struct phylink_pcs pcs;269 270 Populate the relevant :c:type:`struct phylink_pcs_ops <phylink_pcs_ops>` to271 configure your PCS. Create a :c:func:`pcs_get_state` function that reports272 the inband link state, a :c:func:`pcs_config` function to configure your273 PCS according to phylink-provided parameters, and a :c:func:`pcs_validate`274 function that report to phylink all accepted configuration parameters for275 your PCS:276 277 .. code-block:: c278 279 struct phylink_pcs_ops foo_pcs_ops = {280 .pcs_validate = foo_pcs_validate,281 .pcs_get_state = foo_pcs_get_state,282 .pcs_config = foo_pcs_config,283 };284 285 Arrange for PCS link state interrupts to be forwarded into286 phylink, via:287 288 .. code-block:: c289 290 phylink_pcs_change(pcs, link_is_up);291 292 where ``link_is_up`` is true if the link is currently up or false293 otherwise. If a PCS is unable to provide these interrupts, then294 it should set ``pcs->pcs_poll = true;`` when creating the PCS.295 29611. If your controller relies on, or accepts the presence of an external PCS297 controlled through its own driver, add a pointer to a phylink_pcs instance298 in your driver private data structure:299 300 .. code-block:: c301 302 struct phylink_pcs *pcs;303 304 The way of getting an instance of the actual PCS depends on the platform,305 some PCS sit on an MDIO bus and are grabbed by passing a pointer to the306 corresponding :c:type:`struct mii_bus <mii_bus>` and the PCS's address on307 that bus. In this example, we assume the controller attaches to a Lynx PCS308 instance:309 310 .. code-block:: c311 312 priv->pcs = lynx_pcs_create_mdiodev(bus, 0);313 314 Some PCS can be recovered based on firmware information:315 316 .. code-block:: c317 318 priv->pcs = lynx_pcs_create_fwnode(of_fwnode_handle(node));319 32012. Populate the :c:func:`mac_select_pcs` callback and add it to your321 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` set of ops. This function322 must return a pointer to the relevant :c:type:`struct phylink_pcs <phylink_pcs>`323 that will be used for the requested link configuration:324 325 .. code-block:: c326 327 static struct phylink_pcs *foo_select_pcs(struct phylink_config *config,328 phy_interface_t interface)329 {330 struct foo_priv *priv = container_of(config, struct foo_priv,331 phylink_config);332 333 if ( /* 'interface' needs a PCS to function */ )334 return priv->pcs;335 336 return NULL;337 }338 339 See :c:func:`mvpp2_select_pcs` for an example of a driver that has multiple340 internal PCS.341 34213. Fill-in all the :c:type:`phy_interface_t <phy_interface_t>` (i.e. all MAC to343 PHY link modes) that your MAC can output. The following example shows a344 configuration for a MAC that can handle all RGMII modes, SGMII and 1000BaseX.345 You must adjust these according to what your MAC and all PCS associated346 with this MAC are capable of, and not just the interface you wish to use:347 348 .. code-block:: c349 350 phy_interface_set_rgmii(priv->phylink_config.supported_interfaces);351 __set_bit(PHY_INTERFACE_MODE_SGMII,352 priv->phylink_config.supported_interfaces);353 __set_bit(PHY_INTERFACE_MODE_1000BASEX,354 priv->phylink_config.supported_interfaces);355 35614. Remove calls to of_parse_phandle() for the PHY,357 of_phy_register_fixed_link() for fixed links etc. from the probe358 function, and replace with:359 360 .. code-block:: c361 362 struct phylink *phylink;363 364 phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);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 probe failure path as373 appropriate and the removal path too by calling:374 375 .. code-block:: c376 377 phylink_destroy(priv->phylink);378 37915. Arrange for MAC link state interrupts to be forwarded into380 phylink, via:381 382 .. code-block:: c383 384 phylink_mac_change(priv->phylink, link_is_up);385 386 where ``link_is_up`` is true if the link is currently up or false387 otherwise.388 38916. 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 tracking of the link state,395 and cause phylink to omit calls via the :c:func:`mac_link_up` and396 :c:func:`mac_link_down` methods.397 398Network drivers should call phylink_stop() and phylink_start() via their399suspend/resume paths, which ensures that the appropriate400:c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called401as necessary.402 403For information describing the SFP cage in DT, please see the binding404documentation in the kernel source tree405``Documentation/devicetree/bindings/net/sff,sfp.yaml``.406