123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284 |
- .. SPDX-License-Identifier: GPL-2.0
- =======
- phylink
- =======
- Overview
- ========
- phylink is a mechanism to support hot-pluggable networking modules
- directly connected to a MAC without needing to re-initialise the
- adapter on hot-plug events.
- phylink supports conventional phylib-based setups, fixed link setups
- and SFP (Small Formfactor Pluggable) modules at present.
- Modes of operation
- ==================
- phylink has several modes of operation, which depend on the firmware
- settings.
- 1. PHY mode
- In PHY mode, we use phylib to read the current link settings from
- the PHY, and pass them to the MAC driver. We expect the MAC driver
- to configure exactly the modes that are specified without any
- negotiation being enabled on the link.
- 2. Fixed mode
- Fixed mode is the same as PHY mode as far as the MAC driver is
- concerned.
- 3. In-band mode
- In-band mode is used with 802.3z, SGMII and similar interface modes,
- and we are expecting to use and honor the in-band negotiation or
- control word sent across the serdes channel.
- By example, what this means is that:
- .. code-block:: none
- ð {
- phy = <&phy>;
- phy-mode = "sgmii";
- };
- does not use in-band SGMII signalling. The PHY is expected to follow
- exactly the settings given to it in its :c:func:`mac_config` function.
- The link should be forced up or down appropriately in the
- :c:func:`mac_link_up` and :c:func:`mac_link_down` functions.
- .. code-block:: none
- ð {
- managed = "in-band-status";
- phy = <&phy>;
- phy-mode = "sgmii";
- };
- uses in-band mode, where results from the PHY's negotiation are passed
- to the MAC through the SGMII control word, and the MAC is expected to
- acknowledge the control word. The :c:func:`mac_link_up` and
- :c:func:`mac_link_down` functions must not force the MAC side link
- up and down.
- Rough guide to converting a network driver to sfp/phylink
- =========================================================
- This guide briefly describes how to convert a network driver from
- phylib to the sfp/phylink support. Please send patches to improve
- this documentation.
- 1. Optionally split the network driver's phylib update function into
- two parts dealing with link-down and link-up. This can be done as
- a separate preparation commit.
- An older example of this preparation can be found in git commit
- fc548b991fb0, although this was splitting into three parts; the
- link-up part now includes configuring the MAC for the link settings.
- Please see :c:func:`mac_link_up` for more information on this.
- 2. Replace::
- select FIXED_PHY
- select PHYLIB
- with::
- select PHYLINK
- in the driver's Kconfig stanza.
- 3. Add::
- #include <linux/phylink.h>
- to the driver's list of header files.
- 4. Add::
- struct phylink *phylink;
- struct phylink_config phylink_config;
- to the driver's private data structure. We shall refer to the
- driver's private data pointer as ``priv`` below, and the driver's
- private data structure as ``struct foo_priv``.
- 5. Replace the following functions:
- .. flat-table::
- :header-rows: 1
- :widths: 1 1
- :stub-columns: 0
- * - Original function
- - Replacement function
- * - phy_start(phydev)
- - phylink_start(priv->phylink)
- * - phy_stop(phydev)
- - phylink_stop(priv->phylink)
- * - phy_mii_ioctl(phydev, ifr, cmd)
- - phylink_mii_ioctl(priv->phylink, ifr, cmd)
- * - phy_ethtool_get_wol(phydev, wol)
- - phylink_ethtool_get_wol(priv->phylink, wol)
- * - phy_ethtool_set_wol(phydev, wol)
- - phylink_ethtool_set_wol(priv->phylink, wol)
- * - phy_disconnect(phydev)
- - phylink_disconnect_phy(priv->phylink)
- Please note that some of these functions must be called under the
- rtnl lock, and will warn if not. This will normally be the case,
- except if these are called from the driver suspend/resume paths.
- 6. Add/replace ksettings get/set methods with:
- .. code-block:: c
- static int foo_ethtool_set_link_ksettings(struct net_device *dev,
- const struct ethtool_link_ksettings *cmd)
- {
- struct foo_priv *priv = netdev_priv(dev);
-
- return phylink_ethtool_ksettings_set(priv->phylink, cmd);
- }
- static int foo_ethtool_get_link_ksettings(struct net_device *dev,
- struct ethtool_link_ksettings *cmd)
- {
- struct foo_priv *priv = netdev_priv(dev);
-
- return phylink_ethtool_ksettings_get(priv->phylink, cmd);
- }
- 7. Replace the call to::
- phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface);
- and associated code with a call to::
- err = phylink_of_phy_connect(priv->phylink, node, flags);
- For the most part, ``flags`` can be zero; these flags are passed to
- the of_phy_attach() inside this function call if a PHY is specified
- in the DT node ``node``.
- ``node`` should be the DT node which contains the network phy property,
- fixed link properties, and will also contain the sfp property.
- The setup of fixed links should also be removed; these are handled
- internally by phylink.
- of_phy_connect() was also passed a function pointer for link updates.
- This function is replaced by a different form of MAC updates
- described below in (8).
- Manipulation of the PHY's supported/advertised happens within phylink
- based on the validate callback, see below in (8).
- Note that the driver no longer needs to store the ``phy_interface``,
- and also note that ``phy_interface`` becomes a dynamic property,
- just like the speed, duplex etc. settings.
- Finally, note that the MAC driver has no direct access to the PHY
- anymore; that is because in the phylink model, the PHY can be
- dynamic.
- 8. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to
- the driver, which is a table of function pointers, and implement
- these functions. The old link update function for
- :c:func:`of_phy_connect` becomes three methods: :c:func:`mac_link_up`,
- :c:func:`mac_link_down`, and :c:func:`mac_config`. If step 1 was
- performed, then the functionality will have been split there.
- It is important that if in-band negotiation is used,
- :c:func:`mac_link_up` and :c:func:`mac_link_down` do not prevent the
- in-band negotiation from completing, since these functions are called
- when the in-band link state changes - otherwise the link will never
- come up.
- The :c:func:`validate` method should mask the supplied supported mask,
- and ``state->advertising`` with the supported ethtool link modes.
- These are the new ethtool link modes, so bitmask operations must be
- used. For an example, see drivers/net/ethernet/marvell/mvneta.c.
- The :c:func:`mac_link_state` method is used to read the link state
- from the MAC, and report back the settings that the MAC is currently
- using. This is particularly important for in-band negotiation
- methods such as 1000base-X and SGMII.
- The :c:func:`mac_link_up` method is used to inform the MAC that the
- link has come up. The call includes the negotiation mode and interface
- for reference only. The finalised link parameters are also supplied
- (speed, duplex and flow control/pause enablement settings) which
- should be used to configure the MAC when the MAC and PCS are not
- tightly integrated, or when the settings are not coming from in-band
- negotiation.
- The :c:func:`mac_config` method is used to update the MAC with the
- requested state, and must avoid unnecessarily taking the link down
- when making changes to the MAC configuration. This means the
- function should modify the state and only take the link down when
- absolutely necessary to change the MAC configuration. An example
- of how to do this can be found in :c:func:`mvneta_mac_config` in
- drivers/net/ethernet/marvell/mvneta.c.
- For further information on these methods, please see the inline
- documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`.
- 9. Remove calls to of_parse_phandle() for the PHY,
- of_phy_register_fixed_link() for fixed links etc. from the probe
- function, and replace with:
- .. code-block:: c
- struct phylink *phylink;
- priv->phylink_config.dev = &dev.dev;
- priv->phylink_config.type = PHYLINK_NETDEV;
- phylink = phylink_create(&priv->phylink_config, node, phy_mode, &phylink_ops);
- if (IS_ERR(phylink)) {
- err = PTR_ERR(phylink);
- fail probe;
- }
- priv->phylink = phylink;
- and arrange to destroy the phylink in the probe failure path as
- appropriate and the removal path too by calling:
- .. code-block:: c
- phylink_destroy(priv->phylink);
- 10. Arrange for MAC link state interrupts to be forwarded into
- phylink, via:
- .. code-block:: c
- phylink_mac_change(priv->phylink, link_is_up);
- where ``link_is_up`` is true if the link is currently up or false
- otherwise. If a MAC is unable to provide these interrupts, then
- it should set ``priv->phylink_config.pcs_poll = true;`` in step 9.
- 11. Verify that the driver does not call::
- netif_carrier_on()
- netif_carrier_off()
- as these will interfere with phylink's tracking of the link state,
- and cause phylink to omit calls via the :c:func:`mac_link_up` and
- :c:func:`mac_link_down` methods.
- Network drivers should call phylink_stop() and phylink_start() via their
- suspend/resume paths, which ensures that the appropriate
- :c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called
- as necessary.
- For information describing the SFP cage in DT, please see the binding
- documentation in the kernel source tree
- ``Documentation/devicetree/bindings/net/sff,sfp.txt``
|