The ability to describe the physical ports of Ethernet devices is useful
to describe multi-port devices, as well as to remove any ambiguity with
regard to the nature of the port.
Moreover, describing ports allows for a better description of features
that are tied to connectors, such as PoE through the PSE-PD devices.
Introduce a binding to allow describing the ports, for now with 2
attributes :
- The number of lanes, which is a quite generic property that allows
differentating between multiple similar technologies such as BaseT1
and "regular" BaseT (which usually means BaseT4).
- The media that can be used on that port, such as BaseT for Twisted
Copper, BaseC for coax copper, BaseS/L for Fiber, BaseK for backplane
ethernet, etc. This allows defining the nature of the port, and
therefore avoids the need for vendor-specific properties such as
"micrel,fiber-mode" or "ti,fiber-mode".
The port description lives in its own file, as it is intended in the
future to allow describing the ports for phy-less devices.
Reviewed-by: Rob Herring (Arm) <robh@kernel.org>
Reviewed-by: Kory Maincent <kory.maincent@bootlin.com>
Reviewed-by: Christophe Leroy <christophe.leroy@csgroup.eu>
Tested-by: Oleksij Rempel <o.rempel@pengutronix.de>
Tested-by: Florian Fainelli <florian.fainelli@broadcom.com>
Tested-by: Christophe Leroy <christophe.leroy@csgroup.eu>
Signed-off-by: Maxime Chevallier <maxime.chevallier@bootlin.com>
---
.../bindings/net/ethernet-connector.yaml | 45 +++++++++++++++++++
.../devicetree/bindings/net/ethernet-phy.yaml | 18 ++++++++
MAINTAINERS | 1 +
3 files changed, 64 insertions(+)
create mode 100644 Documentation/devicetree/bindings/net/ethernet-connector.yaml
diff --git a/Documentation/devicetree/bindings/net/ethernet-connector.yaml b/Documentation/devicetree/bindings/net/ethernet-connector.yaml
new file mode 100644
index 000000000000..32ae9f45b0e4
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/ethernet-connector.yaml
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/ethernet-connector.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic Ethernet Connector
+
+maintainers:
+ - Maxime Chevallier <maxime.chevallier@bootlin.com>
+
+description:
+ An Ethernet Connector represents the output of a network component such as
+ a PHY, an Ethernet controller with no PHY, or an SFP module.
+
+properties:
+
+ lanes:
+ description:
+ Defines the number of lanes on the port, that is the number of physical
+ channels used to convey the data with the link partner.
+ $ref: /schemas/types.yaml#/definitions/uint32
+
+ media:
+ description:
+ The mediums, as defined in 802.3, that can be used on the port.
+ enum:
+ - BaseT
+ - BaseK
+ - BaseS
+ - BaseC
+ - BaseL
+ - BaseD
+ - BaseE
+ - BaseF
+ - BaseV
+ - BaseMLD
+
+required:
+ - lanes
+ - media
+
+additionalProperties: true
+
+...
diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
index 2ec2d9fda7e3..5ba04170a503 100644
--- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
+++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
@@ -277,6 +277,17 @@ properties:
additionalProperties: false
+ mdi:
+ type: object
+
+ patternProperties:
+ '^connector-[a-f0-9]+$':
+ $ref: /schemas/net/ethernet-connector.yaml#
+
+ unevaluatedProperties: false
+
+ additionalProperties: false
+
required:
- reg
@@ -313,5 +324,12 @@ examples:
default-state = "keep";
};
};
+ /* Fast Ethernet port, with only 2 pairs wired */
+ mdi {
+ connector-0 {
+ lanes = <2>;
+ media = "BaseT";
+ };
+ };
};
};
diff --git a/MAINTAINERS b/MAINTAINERS
index 3a27901781c2..2f8a5ae66314 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9268,6 +9268,7 @@ R: Russell King <linux@armlinux.org.uk>
L: netdev@vger.kernel.org
S: Maintained
F: Documentation/ABI/testing/sysfs-class-net-phydev
+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
--
2.49.0Hi,
> @@ -313,5 +324,12 @@ examples:
> default-state = "keep";
> };
> };
> + /* Fast Ethernet port, with only 2 pairs wired */
> + mdi {
> + connector-0 {
> + lanes = <2>;
> + media = "BaseT";
> + };
> + };
> };
> };
As Andrew suggest clearly differentiating "lanes" and "pairs", do we
want this difference to also affect the binding ?
I still think "lanes" makes some level of sense here, but at least
the doc will need updating.
Andrew what do you think ?
Maxime
On Thu, Oct 30, 2025 at 01:13:14PM +0100, Maxime Chevallier wrote:
> Hi,
>
> > @@ -313,5 +324,12 @@ examples:
> > default-state = "keep";
> > };
> > };
> > + /* Fast Ethernet port, with only 2 pairs wired */
> > + mdi {
> > + connector-0 {
> > + lanes = <2>;
> > + media = "BaseT";
> > + };
> > + };
> > };
> > };
>
> As Andrew suggest clearly differentiating "lanes" and "pairs", do we
> want this difference to also affect the binding ?
>
> I still think "lanes" makes some level of sense here, but at least
> the doc will need updating.
How do you define MDI?
For copper, one possibility is an RJ-45 plug/socket, and you have
twisted pairs, 2 or 4 of them.
Some people are old enough to remember 10Base2, using a coaxial cable
and BNC connectors. Would you consider that a pair? A lane?
How about an SFF, a soldered down module. Its MDI interface is likely
to be 2 fibre strands. But consider so called bidi modules, which use
one fibre, and two different wavelengths of light.
Or an SFP, where you have no idea what the MDI is until you plug it in
and read the EEPROM.
Do we need to be able to describe all the different MDI? Do we maybe
need to look at the media property to decide it is an RJ-45 connector
so there should be a pairs property? Or the media is -KS, so there
should be a lanes property for the number of PCS lanes on the PCB?
This needs further discussion, what are you actually trying to
represent here?
Andrew
Hi Andrew, thanks for the reply !
On 30/10/2025 14:23, Andrew Lunn wrote:
> On Thu, Oct 30, 2025 at 01:13:14PM +0100, Maxime Chevallier wrote:
>> Hi,
>>
>>> @@ -313,5 +324,12 @@ examples:
>>> default-state = "keep";
>>> };
>>> };
>>> + /* Fast Ethernet port, with only 2 pairs wired */
>>> + mdi {
>>> + connector-0 {
>>> + lanes = <2>;
>>> + media = "BaseT";
>>> + };
>>> + };
>>> };
>>> };
>>
>> As Andrew suggest clearly differentiating "lanes" and "pairs", do we
>> want this difference to also affect the binding ?
>>
>> I still think "lanes" makes some level of sense here, but at least
>> the doc will need updating.
>
> How do you define MDI?
>
> For copper, one possibility is an RJ-45 plug/socket, and you have
> twisted pairs, 2 or 4 of them.
>
> Some people are old enough to remember 10Base2, using a coaxial cable
> and BNC connectors. Would you consider that a pair? A lane?
>
> How about an SFF, a soldered down module. Its MDI interface is likely
> to be 2 fibre strands. But consider so called bidi modules, which use
> one fibre, and two different wavelengths of light.
>
> Or an SFP, where you have no idea what the MDI is until you plug it in
> and read the EEPROM.
>
> Do we need to be able to describe all the different MDI? Do we maybe
> need to look at the media property to decide it is an RJ-45 connector
> so there should be a pairs property? Or the media is -KS, so there
> should be a lanes property for the number of PCS lanes on the PCB?
>
> This needs further discussion, what are you actually trying to
> represent here?
What I'd like to represent here is at least BaseT connectors, or simple
Fiber connectors without SFF/SFP (we already have an sff/sfp description
in DT, and we can know what they do by reading the eeprom).
Let's consider these examples, which are representative of what I
want to represent and why.
As a remainder, the end-goal is to be able to list to userspace the
front-facing ports that are beind a netdev, so that we can in the end
support MII-side muxing.
We have several examples of that already upstream :
- Turris omnia, where we have a mux in the SoC to output the SGMII/1000BaseX
either on a PHY or an SFP port. This is not covered by this series.
- The MCBin Doubleshot. Here we have the Marvell 88x3310 PHY connected to the MAC,
and to both an SFP and a RJ45.
However, what we have in DT is :
&cp0_xmdio {
status = "okay";
phy0: ethernet-phy@0 {
compatible = "ethernet-phy-ieee802.3-c45";
reg = <0>;
sfp = <&sfp_eth0>;
};
[...]
};
The question is, with the information we have in DT and from what the PHY
can autodiscover, how do we know if we have this :
MAC --- PHY ---- SFP
or this :
MAC ---PHY ----SFP
\-----RJ45
I don't think we can, we are missing a description of the MDI-side of the PHY.
Of course I don't want to start representing the MDI for every PHY out
there, most common case we have one MDI, that supports whatever the PHY
reports from .get_features(), with the possibility of reading some straps to
adjust.
When we start representing the MDI, we can take that opportunity to solve other
problems :
- The proliferation of vendor properties like "ti,fiber-mode" or "micrel,fiber-mode"
- The use of "max-speed = <100>;" because the PHY is only connected to the RJ45 with
2 pairs
So that being said, an option could be to only focus on pairs, only for medium = BaseT,
and ditch the "lanes" terminology, at least when it comes to the DT bindings.
Does that sound good ?
Maxime
> So that being said, an option could be to only focus on pairs, only > for medium = BaseT, and ditch the "lanes" terminology, at least when > it comes to the DT bindings. > > Does that sound good ? That sounds reasonable. In the binding, maybe try to express that we might in the future extend it. You can do that with conditionals. medium is required. If medium = BaseT then pairs is required. That leaves it open, e.g. in the future we could add medium = BaseKS, and require that has lanes. Andrew
On 30/10/2025 16:01, Andrew Lunn wrote: >> So that being said, an option could be to only focus on pairs, only >> for medium = BaseT, and ditch the "lanes" terminology, at least when >> it comes to the DT bindings. >> >> Does that sound good ? > > That sounds reasonable. > > In the binding, maybe try to express that we might in the future > extend it. You can do that with conditionals. medium is required. If > medium = BaseT then pairs is required. That leaves it open, e.g. in > the future we could add medium = BaseKS, and require that has lanes. Thanks Andrew :) I'll update that then ! Maxime
© 2016 - 2025 Red Hat, Inc.