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 directly connected to a MAC without needing to re-initialise the
  12 adapter on hot-plug events.
  13
  14 phylink supports conventional phylib-based setups, fixed link setups
  15 and SFP (Small Formfactor Pluggable) modules at present.
  16
  17 Modes of operation
  18 ==================
  19
  20 phylink has several modes of operation, which depend on the firmware
  21 settings.
  22
  23 1. 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
  30 2. Fixed mode
  31
  32    Fixed mode is the same as PHY mode as far as the MAC driver is
  33    concerned.
  34
  35 3. 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
  41 By example, what this means is that:
  42
  43 .. code-block:: none
  44
  45   &eth {
  46     phy = <&phy>;
  47     phy-mode = "sgmii";
  48   };
  49
  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.
  54
  55 .. code-block:: none
  56
  57   &eth {
  58     managed = "in-band-status";
  59     phy = <&phy>;
  60     phy-mode = "sgmii";
  61   };
  62
  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
  67 up and down.
  68
  69 Rough guide to converting a network driver to sfp/phylink
  70 =========================================================
  71
  72 This guide briefly describes how to convert a network driver from
  73 phylib to the sfp/phylink support.  Please send patches to improve
  74 this documentation.
  75
  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.
  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
  85 2. 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
  96 3. Add::
  97
  98         #include <linux/phylink.h>
  99
 100    to the driver's list of header files.
 101
 102 4. 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
 111 5. 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
 137 6. 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
 157 7. 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
 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.
 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
 232 9. 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
 257 10. 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
 268 11. 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
 277 Network drivers should call phylink_stop() and phylink_start() via their
 278 suspend/resume paths, which ensures that the appropriate
 279 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
 280 as necessary.
 281
 282 For information describing the SFP cage in DT, please see the binding
 283 documentation in the kernel source tree
 284 ``Documentation/devicetree/bindings/net/sff,sfp.yaml``.