Overview¶

phylink is a mechanism to support hot-pluggable networking modulesdirectly connected to a MAC without needing to re-initialise theadapter on hot-plug events.

phylink supports conventional phylib-based setups, fixed link setupsand SFP (Small Formfactor Pluggable) modules at present.

Modes of operation¶

phylink has several modes of operation, which depend on the firmwaresettings.

1. PHY mode

   In PHY mode, we use phylib to read the current link settings fromthe PHY, and pass them to the MAC driver. We expect the MAC driverto configure exactly the modes that are specified without anynegotiation being enabled on the link.

2. Fixed mode

   Fixed mode is the same as PHY mode as far as the MAC driver isconcerned.

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 orcontrol word sent across the serdes channel.

By example, what this means is that:

&eth {  phy = <&phy>;  phy-mode = "sgmii";};

does not use in-band SGMII signalling. The PHY is expected to followexactly the settings given to it in itsmac_config() function.The link should be forced up or down appropriately in themac_link_up() andmac_link_down() functions.

&eth {  managed = "in-band-status";  phy = <&phy>;  phy-mode = "sgmii";};

uses in-band mode, where results from the PHY’s negotiation are passedto the MAC through the SGMII control word, and the MAC is expected toacknowledge the control word. Themac_link_up() andmac_link_down() functions must not force the MAC side linkup and down.

Rough guide to converting a network driver to sfp/phylink¶

This guide briefly describes how to convert a network driver fromphylib to the sfp/phylink support. Please send patches to improvethis documentation.

1. Optionally split the network driver’s phylib update function intotwo parts dealing with link-down and link-up. This can be done asa separate preparation commit.

   An older example of this preparation can be found in git commitfc548b991fb0, although this was splitting into three parts; thelink-up part now includes configuring the MAC for the link settings.Please seemac_link_up() for more information on this.

2. Replace:

   select FIXED_PHYselect 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 thedriver’s private data pointer aspriv below, and the driver’sprivate data structure asstructfoo_priv.

5. Replace the following functions:

   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 thertnl 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:

   staticintfoo_ethtool_set_link_ksettings(structnet_device*dev,conststructethtool_link_ksettings*cmd){structfoo_priv*priv=netdev_priv(dev);returnphylink_ethtool_ksettings_set(priv->phylink,cmd);}staticintfoo_ethtool_get_link_ksettings(structnet_device*dev,structethtool_link_ksettings*cmd){structfoo_priv*priv=netdev_priv(dev);returnphylink_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 tothe of_phy_attach() inside this function call if a PHY is specifiedin the DT nodenode.

   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 handledinternally by phylink.

   of_phy_connect() was also passed a function pointer for link updates.This function is replaced by a different form of MAC updatesdescribed below in (8).

   Manipulation of the PHY’s supported/advertised happens within phylinkbased on the validate callback, see below in (8).

   Note that the driver no longer needs to store thephy_interface,and also note thatphy_interface becomes a dynamic property,just like the speed, duplex etc. settings.

   Finally, note that the MAC driver has no direct access to the PHYanymore; that is because in the phylink model, the PHY can bedynamic.

8. Add astructphylink_mac_ops instance tothe driver, which is a table of function pointers, and implementthese functions. The old link update function forof_phy_connect() becomes three methods:mac_link_up(),mac_link_down(), andmac_config(). If step 1 wasperformed, then the functionality will have been split there.

   It is important that if in-band negotiation is used,mac_link_up() andmac_link_down() do not prevent thein-band negotiation from completing, since these functions are calledwhen the in-band link state changes - otherwise the link will nevercome up.

   Thevalidate() method should mask the supplied supported mask,andstate->advertising with the supported ethtool link modes.These are the new ethtool link modes, so bitmask operations must beused. For an example, see drivers/net/ethernet/marvell/mvneta.c.

   Themac_link_state() method is used to read the link statefrom the MAC, and report back the settings that the MAC is currentlyusing. This is particularly important for in-band negotiationmethods such as 1000base-X and SGMII.

   Themac_link_up() method is used to inform the MAC that thelink has come up. The call includes the negotiation mode and interfacefor reference only. The finalised link parameters are also supplied(speed, duplex and flow control/pause enablement settings) whichshould be used to configure the MAC when the MAC and PCS are nottightly integrated, or when the settings are not coming from in-bandnegotiation.

   Themac_config() method is used to update the MAC with therequested state, and must avoid unnecessarily taking the link downwhen making changes to the MAC configuration. This means thefunction should modify the state and only take the link down whenabsolutely necessary to change the MAC configuration. An exampleof how to do this can be found inmvneta_mac_config() indrivers/net/ethernet/marvell/mvneta.c.

   For further information on these methods, please see the inlinedocumentation instructphylink_mac_ops.

9. Remove calls to of_parse_phandle() for the PHY,of_phy_register_fixed_link() for fixed links etc. from the probefunction, and replace with:

   structphylink*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);failprobe;}priv->phylink=phylink;

   and arrange to destroy the phylink in the probe failure path asappropriate and the removal path too by calling:

   phylink_destroy(priv->phylink);

10. Arrange for MAC link state interrupts to be forwarded intophylink, via:

    phylink_mac_change(priv->phylink,link_is_up);

    wherelink_is_up is true if the link is currently up or falseotherwise. If a MAC is unable to provide these interrupts, thenit should setpriv->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 themac_link_up() andmac_link_down() methods.

Network drivers should callphylink_stop() andphylink_start() via theirsuspend/resume paths, which ensures that the appropriatestructphylink_mac_ops methods are calledas necessary.

For information describing the SFP cage in DT, please see the bindingdocumentation in the kernel source treeDocumentation/devicetree/bindings/net/sff,sfp.txt