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
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
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);
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
212    using. This is particularly important for in-band negotiation
213    methods such as 1000base-X and SGMII.
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
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;
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
252     PCS whose operation is transparent, some other require dedicated PCS
254     provides a PCS abstraction through :c:type:`struct phylink_pcs <phylink_pcs>`.
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
260     If your controller doesn't have any internal PCS, you can go to step 11.
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
266     .. code-block:: c
268         struct phylink_pcs pcs;
271     configure your PCS. Create a :c:func:`pcs_get_state` function that reports
273     PCS according to phylink-provided parameters, and a :c:func:`pcs_validate`
275     your PCS:
277     .. code-block:: c
285     Arrange for PCS link state interrupts to be forwarded into
288     .. code-block:: c
290         phylink_pcs_change(pcs, link_is_up);
293     otherwise. If a PCS is unable to provide these interrupts, then
294     it should set ``pcs->pcs_poll = true;`` when creating the PCS.
296 11. If your controller relies on, or accepts the presence of an external PCS
300     .. code-block:: c
302         struct phylink_pcs *pcs;
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
310     .. code-block:: c
312         priv->pcs = lynx_pcs_create_mdiodev(bus, 0);
314     Some PCS can be recovered based on firmware information:
316     .. code-block:: c
318         priv->pcs = lynx_pcs_create_fwnode(of_fwnode_handle(node));
325     .. code-block:: c
333                 if ( /* 'interface' needs a PCS to function */ )
334                         return priv->pcs;
340     internal PCS.
342 13. Fill-in all the :c:type:`phy_interface_t <phy_interface_t>` (i.e. all MAC to
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
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);
382     .. code-block:: c
384 	phylink_mac_change(priv->phylink, link_is_up);