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:`mac_get_caps` method is optional, and if provided should
 204    return the phylink MAC capabilities that are supported for the passed
 205    ``interface`` mode. In general, there is no need to implement this method.
 206    Phylink will use these capabilities in combination with permissible
 207    capabilities for ``interface`` to determine the allowable ethtool link
 208    modes.
 209
 210    The :c:func:`mac_link_state` method is used to read the link state
 211    from the MAC, and report back the settings that the MAC is currently
 212    using. This is particularly important for in-band negotiation
 213    methods such as 1000base-X and SGMII.
 214
 215    The :c:func:`mac_link_up` method is used to inform the MAC that the
 216    link has come up. The call includes the negotiation mode and interface
 217    for reference only. The finalised link parameters are also supplied
 218    (speed, duplex and flow control/pause enablement settings) which
 219    should be used to configure the MAC when the MAC and PCS are not
 220    tightly integrated, or when the settings are not coming from in-band
 221    negotiation.
 222
 223    The :c:func:`mac_config` method is used to update the MAC with the
 224    requested state, and must avoid unnecessarily taking the link down
 225    when making changes to the MAC configuration.  This means the
 226    function should modify the state and only take the link down when
 227    absolutely necessary to change the MAC configuration.  An example
 228    of how to do this can be found in :c:func:`mvneta_mac_config` in
 229    ``drivers/net/ethernet/marvell/mvneta.c``.
 230
 231    For further information on these methods, please see the inline
 232    documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
 233
 234 9. Fill-in the :c:type:`struct phylink_config <phylink_config>` fields with
 235    a reference to the :c:type:`struct device <device>` associated to your
 236    :c:type:`struct net_device <net_device>`:
 237
 238    .. code-block:: c
 239
 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:: c
 246
 247         priv->phylink_config.mac_capabilities = MAC_SYM_PAUSE | MAC_10 | MAC_100 | MAC_1000FD;
 248
 249 10. Some Ethernet controllers work in pair with a PCS (Physical Coding Sublayer)
 250     block, that can handle among other things the encoding/decoding, link
 251     establishment detection and autonegotiation. While some MACs have internal
 252     PCS whose operation is transparent, some other require dedicated PCS
 253     configuration for the link to become functional. In that case, phylink
 254     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 if
 257     your controller can use an external PCS block that might be internally
 258     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, create
 263     one :c:type:`struct phylink_pcs <phylink_pcs>` instance per PCS block within
 264     your driver's private data structure:
 265
 266     .. code-block:: c
 267
 268         struct phylink_pcs pcs;
 269
 270     Populate the relevant :c:type:`struct phylink_pcs_ops <phylink_pcs_ops>` to
 271     configure your PCS. Create a :c:func:`pcs_get_state` function that reports
 272     the inband link state, a :c:func:`pcs_config` function to configure your
 273     PCS according to phylink-provided parameters, and a :c:func:`pcs_validate`
 274     function that report to phylink all accepted configuration parameters for
 275     your PCS:
 276
 277     .. code-block:: c
 278
 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 into
 286     phylink, via:
 287
 288     .. code-block:: c
 289
 290         phylink_pcs_change(pcs, link_is_up);
 291
 292     where ``link_is_up`` is true if the link is currently up or false
 293     otherwise. If a PCS is unable to provide these interrupts, then
 294     it should set ``pcs->pcs_poll = true;`` when creating the PCS.
 295
 296 11. If your controller relies on, or accepts the presence of an external PCS
 297     controlled through its own driver, add a pointer to a phylink_pcs instance
 298     in your driver private data structure:
 299
 300     .. code-block:: c
 301
 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 the
 306     corresponding :c:type:`struct mii_bus <mii_bus>` and the PCS's address on
 307     that bus. In this example, we assume the controller attaches to a Lynx PCS
 308     instance:
 309
 310     .. code-block:: c
 311
 312         priv->pcs = lynx_pcs_create_mdiodev(bus, 0);
 313
 314     Some PCS can be recovered based on firmware information:
 315
 316     .. code-block:: c
 317
 318         priv->pcs = lynx_pcs_create_fwnode(of_fwnode_handle(node));
 319
 320 12. Populate the :c:func:`mac_select_pcs` callback and add it to your
 321     :c:type:`struct phylink_mac_ops <phylink_mac_ops>` set of ops. This function
 322     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:: c
 326
 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 multiple
 340     internal PCS.
 341
 342 13. Fill-in all the :c:type:`phy_interface_t <phy_interface_t>` (i.e. all MAC to
 343     PHY link modes) that your MAC can output. The following example shows a
 344     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 associated
 346     with this MAC are capable of, and not just the interface you wish to use:
 347
 348     .. code-block:: c
 349
 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
 356 14. Remove calls to of_parse_phandle() for the PHY,
 357     of_phy_register_fixed_link() for fixed links etc. from the probe
 358     function, and replace with:
 359
 360     .. code-block:: c
 361
 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 as
 373     appropriate and the removal path too by calling:
 374
 375     .. code-block:: c
 376
 377         phylink_destroy(priv->phylink);
 378
 379 15. Arrange for MAC link state interrupts to be forwarded into
 380     phylink, via:
 381
 382     .. code-block:: c
 383
 384         phylink_mac_change(priv->phylink, link_is_up);
 385
 386     where ``link_is_up`` is true if the link is currently up or false
 387     otherwise.
 388
 389 16. 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` and
 396     :c:func:`mac_link_down` methods.
 397
 398 Network drivers should call phylink_stop() and phylink_start() via their
 399 suspend/resume paths, which ensures that the appropriate
 400 :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
 401 as necessary.
 402
 403 For information describing the SFP cage in DT, please see the binding
 404 documentation in the kernel source tree
 405 ``Documentation/devicetree/bindings/net/sff,sfp.yaml``.