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    three parts dealing with link-down, link-up and reconfiguring the
  78    MAC settings. This can be done as a separate preparation commit.
  79
  80    An example of this preparation can be found in git commit fc548b991fb0.
  81
  82 2. Replace::
  83
  84         select FIXED_PHY
  85         select PHYLIB
  86
  87    with::
  88
  89         select PHYLINK
  90
  91    in the driver's Kconfig stanza.
  92
  93 3. Add::
  94
  95         #include <linux/phylink.h>
  96
  97    to the driver's list of header files.
  98
  99 4. Add::
 100
 101         struct phylink *phylink;
 102         struct phylink_config phylink_config;
 103
 104    to the driver's private data structure.  We shall refer to the
 105    driver's private data pointer as ``priv`` below, and the driver's
 106    private data structure as ``struct foo_priv``.
 107
 108 5. Replace the following functions:
 109
 110    .. flat-table::
 111     :header-rows: 1
 112     :widths: 1 1
 113     :stub-columns: 0
 114
 115     * - Original function
 116       - Replacement function
 117     * - phy_start(phydev)
 118       - phylink_start(priv->phylink)
 119     * - phy_stop(phydev)
 120       - phylink_stop(priv->phylink)
 121     * - phy_mii_ioctl(phydev, ifr, cmd)
 122       - phylink_mii_ioctl(priv->phylink, ifr, cmd)
 123     * - phy_ethtool_get_wol(phydev, wol)
 124       - phylink_ethtool_get_wol(priv->phylink, wol)
 125     * - phy_ethtool_set_wol(phydev, wol)
 126       - phylink_ethtool_set_wol(priv->phylink, wol)
 127     * - phy_disconnect(phydev)
 128       - phylink_disconnect_phy(priv->phylink)
 129
 130    Please note that some of these functions must be called under the
 131    rtnl lock, and will warn if not. This will normally be the case,
 132    except if these are called from the driver suspend/resume paths.
 133
 134 6. Add/replace ksettings get/set methods with:
 135
 136    .. code-block:: c
 137
 138     static int foo_ethtool_set_link_ksettings(struct net_device *dev,
 139                                              const struct ethtool_link_ksettings *cmd)
 140     {
 141         struct foo_priv *priv = netdev_priv(dev);
 142
 143         return phylink_ethtool_ksettings_set(priv->phylink, cmd);
 144     }
 145
 146     static int foo_ethtool_get_link_ksettings(struct net_device *dev,
 147                                              struct ethtool_link_ksettings *cmd)
 148     {
 149         struct foo_priv *priv = netdev_priv(dev);
 150
 151         return phylink_ethtool_ksettings_get(priv->phylink, cmd);
 152     }
 153
 154 7. Replace the call to:
 155
 156         phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface);
 157
 158    and associated code with a call to:
 159
 160         err = phylink_of_phy_connect(priv->phylink, node, flags);
 161
 162    For the most part, ``flags`` can be zero; these flags are passed to
 163    the of_phy_attach() inside this function call if a PHY is specified
 164    in the DT node ``node``.
 165
 166    ``node`` should be the DT node which contains the network phy property,
 167    fixed link properties, and will also contain the sfp property.
 168
 169    The setup of fixed links should also be removed; these are handled
 170    internally by phylink.
 171
 172    of_phy_connect() was also passed a function pointer for link updates.
 173    This function is replaced by a different form of MAC updates
 174    described below in (8).
 175
 176    Manipulation of the PHY's supported/advertised happens within phylink
 177    based on the validate callback, see below in (8).
 178
 179    Note that the driver no longer needs to store the ``phy_interface``,
 180    and also note that ``phy_interface`` becomes a dynamic property,
 181    just like the speed, duplex etc. settings.
 182
 183    Finally, note that the MAC driver has no direct access to the PHY
 184    anymore; that is because in the phylink model, the PHY can be
 185    dynamic.
 186
 187 8. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to
 188    the driver, which is a table of function pointers, and implement
 189    these functions. The old link update function for
 190    :c:func:`of_phy_connect` becomes three methods: :c:func:`mac_link_up`,
 191    :c:func:`mac_link_down`, and :c:func:`mac_config`. If step 1 was
 192    performed, then the functionality will have been split there.
 193
 194    It is important that if in-band negotiation is used,
 195    :c:func:`mac_link_up` and :c:func:`mac_link_down` do not prevent the
 196    in-band negotiation from completing, since these functions are called
 197    when the in-band link state changes - otherwise the link will never
 198    come up.
 199
 200    The :c:func:`validate` method should mask the supplied supported mask,
 201    and ``state->advertising`` with the supported ethtool link modes.
 202    These are the new ethtool link modes, so bitmask operations must be
 203    used. For an example, see drivers/net/ethernet/marvell/mvneta.c.
 204
 205    The :c:func:`mac_link_state` method is used to read the link state
 206    from the MAC, and report back the settings that the MAC is currently
 207    using. This is particularly important for in-band negotiation
 208    methods such as 1000base-X and SGMII.
 209
 210    The :c:func:`mac_config` method is used to update the MAC with the
 211    requested state, and must avoid unnecessarily taking the link down
 212    when making changes to the MAC configuration.  This means the
 213    function should modify the state and only take the link down when
 214    absolutely necessary to change the MAC configuration.  An example
 215    of how to do this can be found in :c:func:`mvneta_mac_config` in
 216    drivers/net/ethernet/marvell/mvneta.c.
 217
 218    For further information on these methods, please see the inline
 219    documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
 220
 221 9. Remove calls to of_parse_phandle() for the PHY,
 222    of_phy_register_fixed_link() for fixed links etc. from the probe
 223    function, and replace with:
 224
 225    .. code-block:: c
 226
 227         struct phylink *phylink;
 228         priv->phylink_config.dev = &dev.dev;
 229         priv->phylink_config.type = PHYLINK_NETDEV;
 230
 231         phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
 232         if (IS_ERR(phylink)) {
 233                 err = PTR_ERR(phylink);
 234                 fail probe;
 235         }
 236
 237         priv->phylink = phylink;
 238
 239    and arrange to destroy the phylink in the probe failure path as
 240    appropriate and the removal path too by calling:
 241
 242    .. code-block:: c
 243
 244         phylink_destroy(priv->phylink);
 245
 246 10. Arrange for MAC link state interrupts to be forwarded into
 247     phylink, via:
 248
 249     .. code-block:: c
 250
 251         phylink_mac_change(priv->phylink, link_is_up);
 252
 253     where ``link_is_up`` is true if the link is currently up or false
 254     otherwise. If a MAC is unable to provide these interrupts, then
 255     it should set ``priv->phylink_config.pcs_poll = true;`` in step 9.
 256
 257 11. Verify that the driver does not call::
 258
 259         netif_carrier_on()
 260         netif_carrier_off()
 261
 262    as these will interfere with phylink's tracking of the link state,
 263    and cause phylink to omit calls via the :c:func:`mac_link_up` and
 264    :c:func:`mac_link_down` methods.
 265
 266 Network drivers should call phylink_stop() and phylink_start() via their
 267 suspend/resume paths, which ensures that the appropriate
 268 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
 269 as necessary.
 270
 271 For information describing the SFP cage in DT, please see the binding
 272 documentation in the kernel source tree
 273 ``Documentation/devicetree/bindings/net/sff,sfp.txt``