I would like to add more properties similar to tx-p2p-microvolt, and I
don't think it makes sense to create one schema for each such property
(transmit-amplitude.yaml, lane-polarity.yaml, transmit-equalization.yaml
etc).

Instead, let's rename to phy-common-props.yaml, which makes it a more
adequate host schema for all the above properties.

Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
---
 .../{transmit-amplitude.yaml => phy-common-props.yaml}    | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
 rename Documentation/devicetree/bindings/phy/{transmit-amplitude.yaml => phy-common-props.yaml} (90%)

diff --git a/Documentation/devicetree/bindings/phy/transmit-amplitude.yaml b/Documentation/devicetree/bindings/phy/phy-common-props.yaml
similarity index 90%
rename from Documentation/devicetree/bindings/phy/transmit-amplitude.yaml
rename to Documentation/devicetree/bindings/phy/phy-common-props.yaml
index 617f3c0b3dfb..255205ac09cd 100644
--- a/Documentation/devicetree/bindings/phy/transmit-amplitude.yaml
+++ b/Documentation/devicetree/bindings/phy/phy-common-props.yaml
@@ -1,14 +1,14 @@
 # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
 %YAML 1.2
 ---
-$id: http://devicetree.org/schemas/phy/transmit-amplitude.yaml#
+$id: http://devicetree.org/schemas/phy/phy-common-props.yaml#
 $schema: http://devicetree.org/meta-schemas/core.yaml#
 
-title: Common PHY and network PCS transmit amplitude property
+title: Common PHY and network PCS properties
 
 description:
-  Binding describing the peak-to-peak transmit amplitude for common PHYs
-  and network PCSes.
+  Common PHY and network PCS properties, such as peak-to-peak transmit
+  amplitude.
 
 maintainers:
   - Marek Behún <kabel@kernel.org>
-- 
2.34.1

On Sat, Nov 22, 2025 at 09:33:33PM +0200, Vladimir Oltean wrote:
> I would like to add more properties similar to tx-p2p-microvolt, and I
> don't think it makes sense to create one schema for each such property
> (transmit-amplitude.yaml, lane-polarity.yaml, transmit-equalization.yaml
> etc).
> 
> Instead, let's rename to phy-common-props.yaml, which makes it a more
> adequate host schema for all the above properties.
> 
> Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
> ---
>  .../{transmit-amplitude.yaml => phy-common-props.yaml}    | 8 ++++----

So there is nothing currently referencing this file?

	Andrew

On Tue, Nov 25, 2025 at 10:19:11PM +0100, Andrew Lunn wrote:
> On Sat, Nov 22, 2025 at 09:33:33PM +0200, Vladimir Oltean wrote:
> > I would like to add more properties similar to tx-p2p-microvolt, and I
> > don't think it makes sense to create one schema for each such property
> > (transmit-amplitude.yaml, lane-polarity.yaml, transmit-equalization.yaml
> > etc).
> > 
> > Instead, let's rename to phy-common-props.yaml, which makes it a more
> > adequate host schema for all the above properties.
> > 
> > Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
> > ---
> >  .../{transmit-amplitude.yaml => phy-common-props.yaml}    | 8 ++++----
> 
> So there is nothing currently referencing this file?

Yeah, although as things currently stand, I'd say that is the lesser of
problems. The only user (mv88e6xxx) does something strange: it says it
wants to configure the TX amplitude of SerDes ports, but instead follows
the phy-handle and applies the amplitude specified in that node.

I tried to mentally follow how things would work in 2 cases:
1. PHY referenced by phy-handle is internal, then by definition it's not
   a SerDes port.
2. PHY referenced by phy-handle is external, then the mv88e6xxx driver
   looks at what is essentially a device tree description of the PHY's
   TX, and applies that as a mirror image to the local SerDes' TX.

I think the logic is used in mv88e6xxx through case #2, i.e. we
externalize the mv88e6xxx SerDes electrical properties to an unrelated
OF node, the connected Ethernet PHY.

I note that referencing an Ethernet PHY is done using "phy-handle", a
generic PHY using "phys", and that the two are not the same. A SerDes is
a generic PHY but not an Ethernet PHY.

I looked again through the most lengthy discussion on this patch:
https://lore.kernel.org/netdev/20211207190730.3076-2-holger.brunck@hitachienergy.com/
but did not see this aspect being pointed out.

> Yeah, although as things currently stand, I'd say that is the lesser of
> problems. The only user (mv88e6xxx) does something strange: it says it
> wants to configure the TX amplitude of SerDes ports, but instead follows
> the phy-handle and applies the amplitude specified in that node.
> 
> I tried to mentally follow how things would work in 2 cases:
> 1. PHY referenced by phy-handle is internal, then by definition it's not
>    a SerDes port.
> 2. PHY referenced by phy-handle is external, then the mv88e6xxx driver
>    looks at what is essentially a device tree description of the PHY's
>    TX, and applies that as a mirror image to the local SerDes' TX.
> 
> I think the logic is used in mv88e6xxx through case #2, i.e. we
> externalize the mv88e6xxx SerDes electrical properties to an unrelated
> OF node, the connected Ethernet PHY.

My understanding of the code is the same, #2. Although i would
probably not say it is an unrelated node. I expect the PHY is on the
other end of the SERDES link which is having the TX amplitudes
set. This clearly will not work if there is an SFP cage on the other
end, but it does for an SGMII PHY.

I guess this code is from before the time Russell converted the
mv88e6xxx SERDES code into PCS drivers. The register being set is
within the PCS register set.  The mv88e6xxx also does not make use of
generic phys to represent the SERDES part of the PCS. So there is no
phys phandle to follow since there is no phy.

	Andrew

+Maxime, Holger
thread at https://lore.kernel.org/netdev/20251122193341.332324-2-vladimir.oltean@nxp.com/

On Tue, Nov 25, 2025 at 11:33:09PM +0100, Andrew Lunn wrote:
> > Yeah, although as things currently stand, I'd say that is the lesser of
> > problems. The only user (mv88e6xxx) does something strange: it says it
> > wants to configure the TX amplitude of SerDes ports, but instead follows
> > the phy-handle and applies the amplitude specified in that node.
> > 
> > I tried to mentally follow how things would work in 2 cases:
> > 1. PHY referenced by phy-handle is internal, then by definition it's not
> >    a SerDes port.
> > 2. PHY referenced by phy-handle is external, then the mv88e6xxx driver
> >    looks at what is essentially a device tree description of the PHY's
> >    TX, and applies that as a mirror image to the local SerDes' TX.
> > 
> > I think the logic is used in mv88e6xxx through case #2, i.e. we
> > externalize the mv88e6xxx SerDes electrical properties to an unrelated
> > OF node, the connected Ethernet PHY.
> 
> My understanding of the code is the same, #2. Although i would
> probably not say it is an unrelated node. I expect the PHY is on the
> other end of the SERDES link which is having the TX amplitudes
> set. This clearly will not work if there is an SFP cage on the other
> end, but it does for an SGMII PHY.

It is unrelated in the sense that the SGMII PHY is a different kernel
object, and the mv88e6xxx is polluting its OF node with properties which
it then interprets as its own, when the PHY driver may have wanted to
configure its SGMII TX amplitude too, via those same generic properties.

> I guess this code is from before the time Russell converted the
> mv88e6xxx SERDES code into PCS drivers. The register being set is
> within the PCS register set.  The mv88e6xxx also does not make use of
> generic phys to represent the SERDES part of the PCS. So there is no
> phys phandle to follow since there is no phy.

In my view, the phy-common-props.yaml are supposed to be applicable to either:
(1) a network PHY with SerDes host-side connection (I suppose the media
    side electrical properties would be covered by Maxime's phy_port
    work - Maxime, please confirm).
(2) a phylink_pcs with SerDes registers within the same register set
(3) a generic PHY

My patch 8/9 (net: phy: air_en8811h: deprecate "airoha,pnswap-rx" and
"airoha,pnswap-tx") is an example of case (1) for polarities. Also, for
example, at least Aquantia Gen3 PHYs (AQR111, AQR112) have a (not very
well documented) "SerDes Lane 0 Amplitude" field in the PHY XS Receive
(XAUI TX) Reserved Vendor Provisioning 4 register (address 4.E413).

My patch 7/9 (net: pcs: xpcs: allow lane polarity inversion) is an
example of case (2).

I haven't submitted an example of case (3) yet, but the Lynx PCS and
Lynx SerDes would fall into that category. The PCS would be free of
describing electrical properties, and those would go to the generic PHY
(SerDes).

All I'm trying to say is that we're missing an OF node to describe
mv88e6xxx PCS electrical properties, because otherwise, it collides with
case (1). My note regarding "phys" was just a guess that the "phy-handle"
may have been mistaken for the port's SerDes PHY. Although there is a
chance Holger knew what he was doing. In any case, I think we need to
sort this one way or another, leaving the phy-handle logic a discouraged
fallback path.

That being said, I'm not exactly an expert in determining _how_ we could
best retrofit SerDes/PCS OF nodes on top of the mv88e6xxx bindings.
It depends on how many SerDes ports there are in these switches
architecturally, and what is their register access method, so it would
need to be handled on a case-by-case basis rather than one-size-fits-all.
PCS node in port node could be a starting point, I guess, but I don't
know if it would work.

For SJA1105 and the XPCS, I thought the best course of action would be
to create a "regs" container node in the switch, under which we'd have
"ethernet-pcs" children, but that seems to be problematic in its own
ways, due to how MFD is seemingly abused to make that work:
https://lore.kernel.org/netdev/20251118190530.580267-15-vladimir.oltean@nxp.com/

Hi,

On 26/11/2025 08:26, Vladimir Oltean wrote:
> +Maxime, Holger
> thread at https://lore.kernel.org/netdev/20251122193341.332324-2-vladimir.oltean@nxp.com/
> 
> On Tue, Nov 25, 2025 at 11:33:09PM +0100, Andrew Lunn wrote:
>>> Yeah, although as things currently stand, I'd say that is the lesser of
>>> problems. The only user (mv88e6xxx) does something strange: it says it
>>> wants to configure the TX amplitude of SerDes ports, but instead follows
>>> the phy-handle and applies the amplitude specified in that node.
>>>
>>> I tried to mentally follow how things would work in 2 cases:
>>> 1. PHY referenced by phy-handle is internal, then by definition it's not
>>>    a SerDes port.
>>> 2. PHY referenced by phy-handle is external, then the mv88e6xxx driver
>>>    looks at what is essentially a device tree description of the PHY's
>>>    TX, and applies that as a mirror image to the local SerDes' TX.
>>>
>>> I think the logic is used in mv88e6xxx through case #2, i.e. we
>>> externalize the mv88e6xxx SerDes electrical properties to an unrelated
>>> OF node, the connected Ethernet PHY.
>>
>> My understanding of the code is the same, #2. Although i would
>> probably not say it is an unrelated node. I expect the PHY is on the
>> other end of the SERDES link which is having the TX amplitudes
>> set. This clearly will not work if there is an SFP cage on the other
>> end, but it does for an SGMII PHY.
> 
> It is unrelated in the sense that the SGMII PHY is a different kernel
> object, and the mv88e6xxx is polluting its OF node with properties which
> it then interprets as its own, when the PHY driver may have wanted to
> configure its SGMII TX amplitude too, via those same generic properties.
> 
>> I guess this code is from before the time Russell converted the
>> mv88e6xxx SERDES code into PCS drivers. The register being set is
>> within the PCS register set.  The mv88e6xxx also does not make use of
>> generic phys to represent the SERDES part of the PCS. So there is no
>> phys phandle to follow since there is no phy.
> 
> In my view, the phy-common-props.yaml are supposed to be applicable to either:
> (1) a network PHY with SerDes host-side connection (I suppose the media
>     side electrical properties would be covered by Maxime's phy_port
>     work - Maxime, please confirm).

True, but we could definitely conceive applying phy-common-props.yaml on
the media-side as well :) I don't have a use-case for it right now
though, and we don't yet have detailed descriptions of the electrical
properties.

Maxime

> All I'm trying to say is that we're missing an OF node to describe
> mv88e6xxx PCS electrical properties, because otherwise, it collides with
> case (1). My note regarding "phys" was just a guess that the "phy-handle"
> may have been mistaken for the port's SerDes PHY. Although there is a
> chance Holger knew what he was doing. In any case, I think we need to
> sort this one way or another, leaving the phy-handle logic a discouraged
> fallback path.
> 
> That being said, I'm not exactly an expert in determining _how_ we could
> best retrofit SerDes/PCS OF nodes on top of the mv88e6xxx bindings.
> It depends on how many SerDes ports there are in these switches
> architecturally, and what is their register access method, so it would
> need to be handled on a case-by-case basis rather than one-size-fits-all.
> PCS node in port node could be a starting point, I guess, but I don't
> know if it would work.

I would more likely have a PCS container node and then list each PCS
within it, using reg as the MDIO bus address. The 6352 has one PCS,
but depending on configuration port 5 or port 6 can make use of it. (I
might have the numbers wrong, but the principle is correct). Some of
the other switches have more PCSs but with a fixed mapping to
ports. And the 6390X has 2x 10G PCS. But you can take this 10G PCS and
split it into 2x 5G. And you can take those 5G PCS and split it into
two to give a PCS which can do 1/2.5G.

Given this flexibility, putting the PCS in the port would probably be
a bad idea.

	Andrew