285 lines
9.3 KiB
ReStructuredText
285 lines
9.3 KiB
ReStructuredText
.. 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 phy_attach_direct() 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``
|