This documentation aims at describing the main goal of the phy_port
infrastructure.
Signed-off-by: Maxime Chevallier <maxime.chevallier@xxxxxxxxxxx>
---
V4: new patch
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 058193ed2eeb..7358794258cc 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 4eca34ee6941..ecbf70939927 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8604,6 +8604,7 @@ F: Documentation/ABI/testing/sysfs-class-net-phydev
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.48.1
