Documentation/networking/phy-link-topology.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/phy-link-topology.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/phy-link-topology.rst
Extension
.rst
Size
5314 bytes
Lines
122
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0
.. _phy_link_topology:

=================
PHY link topology
=================

Overview
========

The PHY link topology representation in the networking stack aims at representing
the hardware layout for any given Ethernet link.

An Ethernet interface from userspace's point of view is nothing but a
:c:type:`struct net_device <net_device>`, which exposes configuration options
through the legacy ioctls and the ethtool netlink commands. The base assumption
when designing these configuration APIs were that the link looks something like ::

  +-----------------------+        +----------+      +--------------+
  | Ethernet Controller / |        | Ethernet |      | Connector /  |
  |       MAC             | ------ |   PHY    | ---- |    Port      | ---... to LP
  +-----------------------+        +----------+      +--------------+
  struct net_device               struct phy_device

Commands that needs to configure the PHY will go through the net_device.phydev
field to reach the PHY and perform the relevant configuration.

This assumption falls apart in more complex topologies that can arise when,
for example, using SFP transceivers (although that's not the only specific case).

Here, we have 2 basic scenarios. Either the MAC is able to output a serialized
interface, that can directly be fed to an SFP cage, such as SGMII, 1000BaseX,
10GBaseR, etc.

The link topology then looks like this (when an SFP module is inserted) ::

  +-----+  SGMII  +------------+
  | MAC | ------- | SFP Module |
  +-----+         +------------+

Knowing that some modules embed a PHY, the actual link is more like ::

  +-----+  SGMII   +--------------+
  | MAC | -------- | PHY (on SFP) |
  +-----+          +--------------+

In this case, the SFP PHY is handled by phylib, and registered by phylink through
its SFP upstream ops.

Now some Ethernet controllers aren't able to output a serialized interface, so
we can't directly connect them to an SFP cage. However, some PHYs can be used
as media-converters, to translate the non-serialized MAC MII interface to a
serialized MII interface fed to the SFP ::

  +-----+  RGMII  +-----------------------+  SGMII  +--------------+
  | MAC | ------- | PHY (media converter) | ------- | PHY (on SFP) |
  +-----+         +-----------------------+         +--------------+

This is where the model of having a single net_device.phydev pointer shows its
limitations, as we now have 2 PHYs on the link.

The phy_link topology framework aims at providing a way to keep track of every
PHY on the link, for use by both kernel drivers and subsystems, but also to
report the topology to userspace, allowing to target individual PHYs in configuration
commands.

API
===

The :c:type:`struct phy_link_topology <phy_link_topology>` is a per-netdevice

Annotation

Implementation Notes