Orange Pi5 kernel

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