xref: /linux/Documentation/networking/phy-port.rst (revision 2d7eaeb05ae265bd64270376e6a2c0d80244771f) 
1.. SPDX-License-Identifier: GPL-2.0
2.. _phy_port:
3
4=================
5Ethernet ports
6=================
7
8This document is a basic description of the phy_port infrastructure,
9introduced to represent physical interfaces of Ethernet devices.
10
11Without phy_port, we already have quite a lot of information about what the
12media-facing interface of a NIC can do and looks like, through the
13:c:type:`struct ethtool_link_ksettings <ethtool_link_ksettings>` attributes,
14which includes :
15
16 - What the NIC can do through the :c:member:`supported` field
17 - What the Link Partner advertises through :c:member:`lp_advertising`
18 - Which features we're advertising through :c:member:`advertising`
19
20We also have info about the number of pairs and the PORT type. These settings
21are built by aggregating together information reported by various devices that
22are sitting on the link :
23
24  - The NIC itself, through the :c:member:`get_link_ksettings` callback
25  - Precise information from the MAC and PCS by using phylink in the MAC driver
26  - Information reported by the PHY device
27  - Information reported by an SFP module (which can itself include a PHY)
28
29This model however starts showing its limitations when we consider devices that
30have more than one media interface. In such a case, only information about the
31actively used interface is reported, and it's not possible to know what the
32other interfaces can do. In fact, we have very little information about whether
33or not there are any other media interfaces.
34
35The goal of the phy_port representation is to provide a way of representing a
36physical interface of a NIC, regardless of what is driving the port (NIC through
37a firmware, SFP module, Ethernet PHY).
38
39Multi-port interfaces examples
40==============================
41
42Several cases of multi-interface NICs have been observed so far :
43
44Internal MII Mux::
45
46  +------------------+
47  | SoC              |
48  |          +-----+ |           +-----+
49  | +-----+  |     |-------------| PHY |
50  | | MAC |--| Mux | |   +-----+ +-----+
51  | +-----+  |     |-----| SFP |
52  |          +-----+ |   +-----+
53  +------------------+
54
55Internal Mux with internal PHY::
56
57  +------------------------+
58  | SoC                    |
59  |          +-----+ +-----+
60  | +-----+  |     |-| PHY |
61  | | MAC |--| Mux | +-----+   +-----+
62  | +-----+  |     |-----------| SFP |
63  |          +-----+       |   +-----+
64  +------------------------+
65
66External Mux::
67
68  +---------+
69  | SoC     |  +-----+  +-----+
70  |         |  |     |--| PHY |
71  | +-----+ |  |     |  +-----+
72  | | MAC |----| Mux |  +-----+
73  | +-----+ |  |     |--| PHY |
74  |         |  +-----+  +-----+
75  |         |     |
76  |    GPIO-------+
77  +---------+
78
79Double-port PHY::
80
81  +---------+
82  | SoC     | +-----+
83  |         | |     |--- RJ45
84  | +-----+ | |     |
85  | | MAC |---| PHY |   +-----+
86  | +-----+ | |     |---| SFP |
87  +---------+ +-----+   +-----+
88
89phy_port aims at providing a path to support all the above topologies, by
90representing the media interfaces in a way that's agnostic to what's driving
91the interface. the struct phy_port object has its own set of callback ops, and
92will eventually be able to report its own ksettings::
93
94             _____      +------+
95            (     )-----| Port |
96 +-----+   (       )    +------+
97 | MAC |--(   ???   )
98 +-----+   (       )    +------+
99            (_____)-----| Port |
100                        +------+
101
102SFP ports
103=========
104
105SFP interfaces involve 2 distinct components, each represented by
106a :c:type:`struct phy_port <phy_port>` instance :
107
108 - The SFP cage itself is a :c:type:`struct phy_port <phy_port>`. It's special
109   in that it's not an MDI interface, but rather a hot-pluggable MII.
110   The :c:type:`struct phy_port <phy_port>` associated to it lists the different
111   MII interfaces we can use on the cage.
112
113 - The SFP module, when inserted, will also be associated to a
114   :c:type:`struct phy_port <phy_port>`, that represents the various linkmodes
115   that it gives access to. The module's :c:type:`struct phy_port <phy_port>`
116   doesn't supersede the cage's port, it references it through
117   the :c:type:`struct phy_port <phy_port>` :c:member:`upstream_port` field.
118
119Next steps
120==========
121
122As of writing this documentation, the port's presence and information can only
123be queried, and it's not possible to change any of the port's settings or select
124which one should be used.
125
126Another parallel task is the introduction of a MII muxing framework to allow the
127control of non-PHY driven multi-port setups.
128