Message-ID: <f5b16bd6-01b6-45c0-9668-41ccf90445a3@infradead.org>
Date: Tue, 10 Jun 2025 17:24:08 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Sean Anderson <sean.anderson@...ux.dev>, netdev@...r.kernel.org,
 Andrew Lunn <andrew+netdev@...n.ch>, "David S . Miller"
 <davem@...emloft.net>, Eric Dumazet <edumazet@...gle.com>,
 Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
 Russell King <linux@...linux.org.uk>
Cc: Vineeth Karumanchi <vineeth.karumanchi@....com>,
 Heiner Kallweit <hkallweit1@...il.com>, linux-kernel@...r.kernel.org,
 Kory Maincent <kory.maincent@...tlin.com>,
 Daniel Golle <daniel@...rotopia.org>, Simon Horman <horms@...nel.org>,
 Christian Marangi <ansuelsmth@...il.com>, Lei Wei <quic_leiwei@...cinc.com>,
 Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Subject: Re: [net-next PATCH v6 03/10] net: pcs: Add subsystem

Hi,


> diff --git a/Documentation/networking/pcs.rst b/Documentation/networking/pcs.rst
> new file mode 100644
> index 000000000000..4b41ba884160
> --- /dev/null
> +++ b/Documentation/networking/pcs.rst
> @@ -0,0 +1,102 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============
> +PCS Subsystem
> +=============
> +
> +The PCS (Physical Coding Sublayer) subsystem handles the registration and lookup
> +of PCS devices. These devices contain the upper sublayers of the Ethernet
> +physical layer, generally handling framing, scrambling, and encoding tasks. PCS
> +devices may also include PMA (Physical Medium Attachment) components. PCS
> +devices transfer data between the Link-layer MAC device, and the rest of the
> +physical layer, typically via a serdes. The output of the serdes may be
> +connected more-or-less directly to the medium when using fiber-optic or
> +backplane connections (1000BASE-SX, 1000BASE-KX, etc). It may also communicate
> +with a separate PHY (such as over SGMII) which handles the connection to the
> +medium (such as 1000BASE-T).
> +
> +Looking up PCS Devices
> +----------------------
> +
> +There are generally two ways to look up a PCS device. If the PCS device is
> +internal to a larger device (such as a MAC or switch), and it does not share an
> +implementation with an existing PCS, then it does not need to be registered with
> +the PCS subsystem. Instead, you can populate a :c:type:`phylink_pcs`
> +in your probe function. Otherwise, you must look up the PCS.
> +
> +If your device has a :c:type:`fwnode_handle`, you can add a PCS using the
> +``pcs-handle`` property::
> +
> +    ethernet-controller {
> +        // ...
> +        pcs-handle = <&pcs>;
> +        pcs-handle-names = "internal";
> +    };
> +
> +Then, during your probe function, you can get the PCS using :c:func:`pcs_get`::

It's preferable to use                               PCS using pcs_get()::
instead of the :c:func: notation to make the .rst file more human-readable.
They produce the same generated output.

> +
> +    mac->pcs = pcs_get(dev, "internal");
> +    if (IS_ERR(mac->pcs)) {
> +        err = PTR_ERR(mac->pcs);
> +        return dev_err_probe(dev, "Could not get PCS\n");
> +    }
> +
> +If your device doesn't have a :c:type:`fwnode_handle`, you can get the PCS
> +based on the providing device using :c:func:`pcs_get_by_dev`. Typically, you

ditto.

> +will create the device and bind your PCS driver to it before calling this
> +function. This allows reuse of an existing PCS driver.
> +
> +Once you are done using the PCS, you must call :c:func:`pcs_put`.

ditto.

> +
> +Using PCS Devices
> +-----------------
> +
> +To select the PCS from a MAC driver, implement the ``mac_select_pcs`` callback
> +of :c:type:`phylink_mac_ops`. In this example, the PCS is selected for SGMII
> +and 1000BASE-X, and deselected for other interfaces::
> +
> +    static struct phylink_pcs *mac_select_pcs(struct phylink_config *config,
> +                                              phy_interface_t iface)
> +    {
> +        struct mac *mac = config_to_mac(config);
> +
> +        switch (iface) {
> +        case PHY_INTERFACE_MODE_SGMII:
> +        case PHY_INTERFACE_MODE_1000BASEX:
> +            return mac->pcs;
> +        default:
> +            return NULL;
> +        }
> +    }
> +
> +To do the same from a DSA driver, implement the ``phylink_mac_select_pcs``
> +callback of :c:type:`dsa_switch_ops`.
> +
> +Writing PCS Drivers
> +-------------------
> +
> +To write a PCS driver, first implement :c:type:`phylink_pcs_ops`. Then,
> +register your PCS in your probe function using :c:func:`pcs_register`. If you

ditto

> +need to provide multiple PCSs for the same device, then you can pass specific
> +firmware nodes using :c:macro:`pcs_register_full`.
> +
> +You must call :c:func:`pcs_unregister` from your remove function. You can avoid

ditto.

> +this step by registering with :c:func:`devm_pcs_unregister`.
> +
> +API Reference
> +-------------
> +
> +.. kernel-doc:: include/linux/phylink.h
> +   :identifiers: phylink_pcs phylink_pcs_ops pcs_validate pcs_inband_caps
> +      pcs_enable pcs_disable pcs_pre_config pcs_post_config pcs_get_state
> +      pcs_config pcs_an_restart pcs_link_up pcs_disable_eee pcs_enable_eee
> +      pcs_pre_init
> +
> +.. kernel-doc:: include/linux/pcs.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/net/pcs/core.c
> +   :export:
> +
> +.. kernel-doc:: drivers/net/pcs/core.c
> +   :internal:

Thanks.

-- 
~Randy

Powered by blists - more mailing lists