Documentation/networking/sfp-phylink.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======
   4 phylink
   5 =======
   6
   7 Overview
   8 ========
   9
  10 phylink is a mechanism to support hot-pluggable networking modules
  11 without needing to re-initialise the adapter on hot-plug events.
  12
  13 phylink supports conventional phylib-based setups, fixed link setups
  14 and SFP (Small Formfactor Pluggable) modules at present.
  15
  16 Modes of operation
  17 ==================
  18
  19 phylink has several modes of operation, which depend on the firmware
  20 settings.
  21
  22 1. PHY mode
  23
  24    In PHY mode, we use phylib to read the current link settings from
  25    the PHY, and pass them to the MAC driver.  We expect the MAC driver
  26    to configure exactly the modes that are specified without any
  27    negotiation being enabled on the link.
  28
  29 2. Fixed mode
  30
  31    Fixed mode is the same as PHY mode as far as the MAC driver is
  32    concerned.
  33
  34 3. In-band mode
  35
  36    In-band mode is used with 802.3z, SGMII and similar interface modes,
  37    and we are expecting to use and honor the in-band negotiation or
  38    control word sent across the serdes channel.
  39
  40 By example, what this means is that:
  41
  42 .. code-block:: none
  43
  44   &eth {
  45     phy = <&phy>;
  46     phy-mode = "sgmii";
  47   };
  48
  49 does not use in-band SGMII signalling.  The PHY is expected to follow
  50 exactly the settings given to it in its :c:func:`mac_config` function.
  51 The link should be forced up or down appropriately in the
  52 :c:func:`mac_link_up` and :c:func:`mac_link_down` functions.
  53
  54 .. code-block:: none
  55
  56   &eth {
  57     managed = "in-band-status";
  58     phy = <&phy>;
  59     phy-mode = "sgmii";
  60   };
  61
  62 uses in-band mode, where results from the PHY's negotiation are passed
  63 to the MAC through the SGMII control word, and the MAC is expected to
  64 acknowledge the control word.  The :c:func:`mac_link_up` and
  65 :c:func:`mac_link_down` functions must not force the MAC side link
  66 up and down.
  67
  68 Rough guide to converting a network driver to sfp/phylink
  69 =========================================================
  70
  71 This guide briefly describes how to convert a network driver from
  72 phylib to the sfp/phylink support.  Please send patches to improve
  73 this documentation.
  74
  75 1. Optionally split the network driver's phylib update function into
  76    three parts dealing with link-down, link-up and reconfiguring the
  77    MAC settings. This can be done as a separate preparation commit.
  78
  79    An example of this preparation can be found in git commit fc548b991fb0.
  80
  81 2. Replace::
  82
  83         select FIXED_PHY
  84         select PHYLIB
  85
  86    with::
  87
  88         select PHYLINK
  89
  90    in the driver's Kconfig stanza.
  91
  92 3. Add::
  93
  94         #include <linux/phylink.h>
  95
  96    to the driver's list of header files.
  97
  98 4. Add::
  99
 100         struct phylink *phylink;
 101         struct phylink_config phylink_config;
 102
 103    to the driver's private data structure.  We shall refer to the
 104    driver's private data pointer as ``priv`` below, and the driver's
 105    private data structure as ``struct foo_priv``.
 106
 107 5. Replace the following functions:
 108
 109    .. flat-table::
 110     :header-rows: 1
 111     :widths: 1 1
 112     :stub-columns: 0
 113
 114     * - Original function
 115       - Replacement function
 116     * - phy_start(phydev)
 117       - phylink_start(priv->phylink)
 118     * - phy_stop(phydev)
 119       - phylink_stop(priv->phylink)
 120     * - phy_mii_ioctl(phydev, ifr, cmd)
 121       - phylink_mii_ioctl(priv->phylink, ifr, cmd)
 122     * - phy_ethtool_get_wol(phydev, wol)
 123       - phylink_ethtool_get_wol(priv->phylink, wol)
 124     * - phy_ethtool_set_wol(phydev, wol)
 125       - phylink_ethtool_set_wol(priv->phylink, wol)
 126     * - phy_disconnect(phydev)
 127       - phylink_disconnect_phy(priv->phylink)
 128
 129    Please note that some of these functions must be called under the
 130    rtnl lock, and will warn if not. This will normally be the case,
 131    except if these are called from the driver suspend/resume paths.
 132
 133 6. Add/replace ksettings get/set methods with:
 134
 135    .. code-block:: c
 136
 137     static int foo_ethtool_set_link_ksettings(struct net_device *dev,
 138                                              const struct ethtool_link_ksettings *cmd)
 139     {
 140         struct foo_priv *priv = netdev_priv(dev);
 141
 142         return phylink_ethtool_ksettings_set(priv->phylink, cmd);
 143     }
 144
 145     static int foo_ethtool_get_link_ksettings(struct net_device *dev,
 146                                              struct ethtool_link_ksettings *cmd)
 147     {
 148         struct foo_priv *priv = netdev_priv(dev);
 149
 150         return phylink_ethtool_ksettings_get(priv->phylink, cmd);
 151     }
 152
 153 7. Replace the call to:
 154
 155         phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface);
 156
 157    and associated code with a call to:
 158
 159         err = phylink_of_phy_connect(priv->phylink, node, flags);
 160
 161    For the most part, ``flags`` can be zero; these flags are passed to
 162    the of_phy_attach() inside this function call if a PHY is specified
 163    in the DT node ``node``.
 164
 165    ``node`` should be the DT node which contains the network phy property,
 166    fixed link properties, and will also contain the sfp property.
 167
 168    The setup of fixed links should also be removed; these are handled
 169    internally by phylink.
 170
 171    of_phy_connect() was also passed a function pointer for link updates.
 172    This function is replaced by a different form of MAC updates
 173    described below in (8).
 174
 175    Manipulation of the PHY's supported/advertised happens within phylink
 176    based on the validate callback, see below in (8).
 177
 178    Note that the driver no longer needs to store the ``phy_interface``,
 179    and also note that ``phy_interface`` becomes a dynamic property,
 180    just like the speed, duplex etc. settings.
 181
 182    Finally, note that the MAC driver has no direct access to the PHY
 183    anymore; that is because in the phylink model, the PHY can be
 184    dynamic.
 185
 186 8. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to
 187    the driver, which is a table of function pointers, and implement
 188    these functions. The old link update function for
 189    :c:func:`of_phy_connect` becomes three methods: :c:func:`mac_link_up`,
 190    :c:func:`mac_link_down`, and :c:func:`mac_config`. If step 1 was
 191    performed, then the functionality will have been split there.
 192
 193    It is important that if in-band negotiation is used,
 194    :c:func:`mac_link_up` and :c:func:`mac_link_down` do not prevent the
 195    in-band negotiation from completing, since these functions are called
 196    when the in-band link state changes - otherwise the link will never
 197    come up.
 198
 199    The :c:func:`validate` method should mask the supplied supported mask,
 200    and ``state->advertising`` with the supported ethtool link modes.
 201    These are the new ethtool link modes, so bitmask operations must be
 202    used. For an example, see drivers/net/ethernet/marvell/mvneta.c.
 203
 204    The :c:func:`mac_link_state` method is used to read the link state
 205    from the MAC, and report back the settings that the MAC is currently
 206    using. This is particularly important for in-band negotiation
 207    methods such as 1000base-X and SGMII.
 208
 209    The :c:func:`mac_config` method is used to update the MAC with the
 210    requested state, and must avoid unnecessarily taking the link down
 211    when making changes to the MAC configuration.  This means the
 212    function should modify the state and only take the link down when
 213    absolutely necessary to change the MAC configuration.  An example
 214    of how to do this can be found in :c:func:`mvneta_mac_config` in
 215    drivers/net/ethernet/marvell/mvneta.c.
 216
 217    For further information on these methods, please see the inline
 218    documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
 219
 220 9. Remove calls to of_parse_phandle() for the PHY,
 221    of_phy_register_fixed_link() for fixed links etc. from the probe
 222    function, and replace with:
 223
 224    .. code-block:: c
 225
 226         struct phylink *phylink;
 227         priv->phylink_config.dev = &dev.dev;
 228         priv->phylink_config.type = PHYLINK_NETDEV;
 229
 230         phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
 231         if (IS_ERR(phylink)) {
 232                 err = PTR_ERR(phylink);
 233                 fail probe;
 234         }
 235
 236         priv->phylink = phylink;
 237
 238    and arrange to destroy the phylink in the probe failure path as
 239    appropriate and the removal path too by calling:
 240
 241    .. code-block:: c
 242
 243         phylink_destroy(priv->phylink);
 244
 245 10. Arrange for MAC link state interrupts to be forwarded into
 246     phylink, via:
 247
 248     .. code-block:: c
 249
 250         phylink_mac_change(priv->phylink, link_is_up);
 251
 252     where ``link_is_up`` is true if the link is currently up or false
 253     otherwise.
 254
 255 11. Verify that the driver does not call::
 256
 257         netif_carrier_on()
 258         netif_carrier_off()
 259
 260    as these will interfere with phylink's tracking of the link state,
 261    and cause phylink to omit calls via the :c:func:`mac_link_up` and
 262    :c:func:`mac_link_down` methods.
 263
 264 Network drivers should call phylink_stop() and phylink_start() via their
 265 suspend/resume paths, which ensures that the appropriate
 266 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
 267 as necessary.
 268
 269 For information describing the SFP cage in DT, please see the binding
 270 documentation in the kernel source tree
 271 ``Documentation/devicetree/bindings/net/sff,sfp.txt``