[net-next,v6,14/14] Documentation: networking: Document the phy_port infrastructure

This documentation aims at describing the main goal of the phy_port
infrastructure.

Signed-off-by: Maxime Chevallier <maxime.chevallier@bootlin.com>
---
 Documentation/networking/index.rst    |   1 +
 Documentation/networking/phy-port.rst | 111 ++++++++++++++++++++++++++
 MAINTAINERS                           |   1 +
 3 files changed, 113 insertions(+)
 create mode 100644 Documentation/networking/phy-port.rst

Hi Maxime,

On Wednesday, 7 May 2025 15:53:30 CEST Maxime Chevallier wrote:
> This documentation aims at describing the main goal of the phy_port
> infrastructure.
> 
> Signed-off-by: Maxime Chevallier <maxime.chevallier@bootlin.com>
> ---
>  Documentation/networking/index.rst    |   1 +
>  Documentation/networking/phy-port.rst | 111 ++++++++++++++++++++++++++
>  MAINTAINERS                           |   1 +
>  3 files changed, 113 insertions(+)
>  create mode 100644 Documentation/networking/phy-port.rst
> 
> diff --git a/Documentation/networking/index.rst
> b/Documentation/networking/index.rst index ac90b82f3ce9..f60acc06e3f7
> 100644
> --- a/Documentation/networking/index.rst
> +++ b/Documentation/networking/index.rst
> @@ -96,6 +96,7 @@ Contents:
>     packet_mmap
>     phonet
>     phy-link-topology
> +   phy-port
>     pktgen
>     plip
>     ppp_generic
> diff --git a/Documentation/networking/phy-port.rst
> b/Documentation/networking/phy-port.rst new file mode 100644
> index 000000000000..6d9d46ebe438
> --- /dev/null
> +++ b/Documentation/networking/phy-port.rst
> @@ -0,0 +1,111 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. _phy_port:
> +
> +=================
> +Ethernet ports
> +=================
> +
> +This document is a basic description of the phy_port infrastructure,
> +introduced to represent physical interfaces of Ethernet devices.
> +
> +Without phy_port, we already have quite a lot of information about what the
> +media-facing interface of a NIC can do and looks like, through the

I'd replace "and looks like" by "and what it looks like".

> +:c:type:`struct ethtool_link_ksettings <ethtool_link_ksettings>`
> attributes, +which includes :
> +
> + - What the NIC can do through the :c:member:`supported` field
> + - What the Link Partner advertises through :c:member:`lp_advertising`
> + - Which features we're advertising through :c:member:`advertising`
> +
> +We also have info about the number of lanes and the PORT type. These
> settings +are built by aggregating together information reported by various
> devices that +are sitting on the link :
> +
> +  - The NIC itself, through the :c:member:`get_link_ksettings` callback
> +  - Precise information from the MAC and PCS by using phylink in the MAC
> driver +  - Information reported by the PHY device
> +  - Information reported by an SFP module (which can itself include a PHY)
> +
> +This model however starts showing its limitations when we consider devices
> that +have more than one media interface. In such a case, only information
> about the +actively used interface is reported, and it's not possible to
> know what the +other interfaces can do. In fact, we have very few
> information about whether or +not there are any other media interfaces.

maybe "hints" instead of "information"?

> +
> +The goal of the phy_port representation is to provide a way of representing
> a +physical interface of a NIC, regardless of what is driving the port (NIC
> through +a firmware, SFP module, Ethernet PHY).
> +
> +Multi-port interfaces examples
> +==============================
> +
> +Several cases of multi-interface NICs have been observed so far :
> +
> +Internal MII Mux::
> +
> +  +------------------+
> +  | SoC              |
> +  |          +-----+ |           +-----+
> +  | +-----+  |     |-------------| PHY |
> +  | | MAC |--| Mux | |   +-----+ +-----+
> +  | +-----+  |     |-----| SFP |
> +  |          +-----+ |   +-----+
> +  +------------------+
> +
> +Internal Mux with internal PHY::
> +
> +  +------------------------+
> +  | SoC                    |
> +  |          +-----+ +-----+
> +  | +-----+  |     |-| PHY |
> +  | | MAC |--| Mux | +-----+   +-----+
> +  | +-----+  |     |-----------| SFP |
> +  |          +-----+       |   +-----+
> +  +------------------------+
> +
> +External Mux::
> +
> +  +---------+
> +  | SoC     |  +-----+  +-----+
> +  |         |  |     |--| PHY |
> +  | +-----+ |  |     |  +-----+
> +  | | MAC |----| Mux |  +-----+
> +  | +-----+ |  |     |--| PHY |
> +  |         |  +-----+  +-----+
> +  |         |     |
> +  |    GPIO-------+
> +  +---------+
> +
> +Double-port PHY::
> +
> +  +---------+
> +  | SoC     | +-----+
> +  |         | |     |--- RJ45
> +  | +-----+ | |     |
> +  | | MAC |---| PHY |   +-----+
> +  | +-----+ | |     |---| SFP |
> +  +---------+ +-----+   +-----+
> +
> +phy_port aims at providing a path to support all the above topologies, by
> +representing the media interfaces in a way that's agnostic to what's
> driving +the interface. the struct phy_port object has its own set of

s/the/The

> callback ops, and +will eventually be able to report its own ksettings::
> +
> +             _____      +------+
> +            (     )-----| Port |
> + +-----+   (       )    +------+
> + | MAC |--(   ???   )
> + +-----+   (       )    +------+
> +            (_____)-----| Port |
> +                        +------+
> +
> +Next steps
> +==========
> +
> +As of writing this documentation, only ports controlled by PHY devices are
> +supported. The next steps will be to add the Netlink API to expose these
> +to userspace and add support for raw ports (controlled by some firmware,
> and directly +managed by the NIC driver).
> +
> +Another parallel task is the introduction of a MII muxing framework to

I'd suggest "related" instead of "parallel".

> allow the +control of non-PHY driver multi-port setups.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index b155eec69552..211a6ba50166 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8781,6 +8781,7 @@
> F:	Documentation/devicetree/bindings/net/ethernet-connector.yaml
> F:	Documentation/devicetree/bindings/net/ethernet-phy.yaml
>  F:	Documentation/devicetree/bindings/net/mdio*
>  F:	Documentation/devicetree/bindings/net/qca,ar803x.yaml
> +F:	Documentation/networking/phy-port.rst
>  F:	Documentation/networking/phy.rst
>  F:	drivers/net/mdio/
>  F:	drivers/net/mdio/acpi_mdio.c

Thanks!