Documentation/networking/sfp-phylink.rst

1 .. SPDX-License-Identifier: GPL-2.0
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.
14 phylink supports conventional phylib-based setups, fixed link setups
23 1. PHY mode
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
30 2. Fixed mode
32    Fixed mode is the same as PHY mode as far as the MAC driver is
35 3. In-band mode
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
43 .. code-block:: none
47     phy-mode = "sgmii";
50 does not use in-band SGMII signalling.  The PHY is expected to follow
55 .. code-block:: none
58     managed = "in-band-status";
60     phy-mode = "sgmii";
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
66 :c:func:`mac_link_down` functions must not force the MAC side link
77    two parts dealing with link-down and link-up. This can be done as
82    link-up part now includes configuring the MAC for the link settings.
113    .. flat-table::
114     :header-rows: 1
116     :stub-columns: 0
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)
139    .. code-block:: c
146 		return phylink_ethtool_ksettings_set(priv->phylink, cmd);
154 		return phylink_ethtool_ksettings_get(priv->phylink, cmd);
163 	err = phylink_of_phy_connect(priv->phylink, node, flags);
176    This function is replaced by a different form of MAC updates
186    Finally, note that the MAC driver has no direct access to the PHY
197    It is important that if in-band negotiation is used,
199    in-band negotiation from completing, since these functions are called
200    when the in-band link state changes - otherwise the link will never
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.
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.
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
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
223    The :c:func:`mac_config` method is used to update the MAC with the
225    when making changes to the MAC configuration.  This means the
227    absolutely necessary to change the MAC configuration.  An example
234 9. Fill-in the :c:type:`struct phylink_config <phylink_config>` fields with
238    .. code-block:: c
240 	priv->phylink_config.dev = &dev.dev;
241 	priv->phylink_config.type = PHYLINK_NETDEV;
243    Fill-in the various speeds, pause and duplex modes your MAC can handle:
245    .. code-block:: c
247         priv->phylink_config.mac_capabilities = MAC_SYM_PAUSE | MAC_10 | MAC_100 | MAC_1000FD;
266     .. code-block:: c
273     PCS according to phylink-provided parameters, and a :c:func:`pcs_validate`
277     .. code-block:: c
288     .. code-block:: c
294     it should set ``pcs->pcs_poll = true;`` when creating the PCS.
300     .. code-block:: c
310     .. code-block:: c
312         priv->pcs = lynx_pcs_create_mdiodev(bus, 0);
316     .. code-block:: c
318         priv->pcs = lynx_pcs_create_fwnode(of_fwnode_handle(node));
325     .. code-block:: c
334                         return priv->pcs;
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:
348     .. code-block:: c
350        phy_interface_set_rgmii(priv->phylink_config.supported_interfaces);
352                   priv->phylink_config.supported_interfaces);
354                   priv->phylink_config.supported_interfaces);
360     .. code-block:: c
364 	phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
370 	priv->phylink = phylink;
375     .. code-block:: c
377 	phylink_destroy(priv->phylink);
379 15. Arrange for MAC link state interrupts to be forwarded into
382     .. code-block:: c
384 	phylink_mac_change(priv->phylink, link_is_up);