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
+: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.
+
+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 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 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
-- 
2.49.0

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!

-- 
Romain Gantois, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com