Commit 62518b5b authored by Maxime Chevallier's avatar Maxime Chevallier Committed by Jakub Kicinski
Browse files

Documentation: networking: Document the phy_port infrastructure 



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

Reviewed-by: default avatarChristophe Leroy <christophe.leroy@csgroup.eu>
Reviewed-by: default avatarAndrew Lunn <andrew@lunn.ch>
Tested-by: default avatarChristophe Leroy <christophe.leroy@csgroup.eu>
Signed-off-by: default avatarMaxime Chevallier <maxime.chevallier@bootlin.com>
Link: https://patch.msgid.link/20260108080041.553250-15-maxime.chevallier@bootlin.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent bad869b5

Documentation/networking/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -96,6 +96,7 @@ Contents: 
   packet_mmap

   phonet

   phy-link-topology

   phy-port

   pktgen

   plip

   ppp_generic

Documentation/networking/phy-port.rst

0 → 100644
+111 −0
Original line number Diff line number Diff line 
.. 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 pairs 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 little 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.

MAINTAINERS

+2 −0
Original line number Diff line number Diff line
@@ -9399,6 +9399,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
@@ -18221,6 +18222,7 @@ F: net/ethtool/phy.c 
NETWORKING [ETHTOOL PHY PORT]

M:	Maxime Chevallier <maxime.chevallier@bootlin.com>

F:	Documentation/devicetree/bindings/net/ethernet-connector.yaml

F:	Documentation/networking/phy-port.rst

F:	drivers/net/phy/phy_port.c

F:	include/linux/phy_port.h

K:	struct\s+phy_port|phy_port_