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 ð { 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 ð { 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