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
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
46     phy = <&phy>;
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";
59     phy = <&phy>;
60     phy-mode = "sgmii";
63 uses in-band mode, where results from the PHY's negotiation are passed
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);
166    the phy_attach_direct() inside this function call if a PHY is specified
169    ``node`` should be the DT node which contains the network phy property,
179    Manipulation of the PHY's supported/advertised happens within phylink
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
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.
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;
251     establishment detection and autonegotiation. While some MACs have internal
256     Identify if your driver has one or more internal PCS blocks, and/or if
260     If your controller doesn't have any internal PCS, you can go to step 11.
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;
340     internal 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
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);
356 14. Remove calls to of_parse_phandle() for the PHY,
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);