[PATCH] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[PATCH] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[Buday Csaba]

Change PHY ID description in ethernet-phy.yaml to clarify that a
PHY ID is required (may -> must) when the PHY requires special
initialization sequence.

Link: https://lore.kernel.org/netdev/20251026212026.GA2959311-robh@kernel.org/
Link: https://lore.kernel.org/netdev/aQIZvDt5gooZSTcp@debianbuilder/

Signed-off-by: Buday Csaba <buday.csaba@prolan.hu>
---
 Documentation/devicetree/bindings/net/ethernet-phy.yaml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
index 2ec2d9fda..6f5599902 100644
--- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
+++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
@@ -35,9 +35,10 @@ properties:
         description: PHYs that implement IEEE802.3 clause 45
       - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
         description:
-          If the PHY reports an incorrect ID (or none at all) then the
-          compatible list may contain an entry with the correct PHY ID
-          in the above form.
+          If the PHY reports an incorrect ID (or none at all), or the PHY
+          requires a specific initialization sequence (like a particular
+          order of clocks, resets, power supplies), then the compatible list
+          must contain an entry with the correct PHY ID in the above form.
           The first group of digits is the 16 bit Phy Identifier 1
           register, this is the chip vendor OUI bits 3:18. The
           second group of digits is the Phy Identifier 2 register,
-- 
2.39.5

Re: [PATCH] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[Andrew Lunn]

On Fri, Oct 31, 2025 at 09:15:06AM +0100, Buday Csaba wrote:
> Change PHY ID description in ethernet-phy.yaml to clarify that a
> PHY ID is required (may -> must) when the PHY requires special
> initialization sequence.
> 
> Link: https://lore.kernel.org/netdev/20251026212026.GA2959311-robh@kernel.org/
> Link: https://lore.kernel.org/netdev/aQIZvDt5gooZSTcp@debianbuilder/
> 
> Signed-off-by: Buday Csaba <buday.csaba@prolan.hu>
> ---
>  Documentation/devicetree/bindings/net/ethernet-phy.yaml | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> index 2ec2d9fda..6f5599902 100644
> --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> @@ -35,9 +35,10 @@ properties:
>          description: PHYs that implement IEEE802.3 clause 45
>        - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
>          description:
> -          If the PHY reports an incorrect ID (or none at all) then the
> -          compatible list may contain an entry with the correct PHY ID
> -          in the above form.
> +          If the PHY reports an incorrect ID (or none at all), or the PHY
> +          requires a specific initialization sequence (like a particular
> +          order of clocks, resets, power supplies), then the compatible list
> +          must contain an entry with the correct PHY ID in the above form.

That is good start, but how about:

          PHYs contain identification registers. These will be read to
          identify the PHY. If the PHY reports an incorrect ID, or the
          PHY requires a specific initialization sequence (like a
          particular order of clocks, resets, power supplies), in
          order to be able to read the ID registers, then the
          compatible list must contain an entry with the correct PHY
          ID in the above form.

The first two sentences make it clear we ideally use the ID registers.
Then we say what happens if cannot work.

The "(or none at all)" is exactly the case you are trying to clarify,
it does not respond due to missing reset, clocks etc. We don't need to
say it twice, so i removed it.

    Andrew

Re: [PATCH] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 2593 bytes --]

On Fri, Oct 31, 2025 at 02:01:26PM +0100, Andrew Lunn wrote:
> On Fri, Oct 31, 2025 at 09:15:06AM +0100, Buday Csaba wrote:
> > Change PHY ID description in ethernet-phy.yaml to clarify that a
> > PHY ID is required (may -> must) when the PHY requires special
> > initialization sequence.
> > 
> > Link: https://lore.kernel.org/netdev/20251026212026.GA2959311-robh@kernel.org/
> > Link: https://lore.kernel.org/netdev/aQIZvDt5gooZSTcp@debianbuilder/
> > 
> > Signed-off-by: Buday Csaba <buday.csaba@prolan.hu>
> > ---
> >  Documentation/devicetree/bindings/net/ethernet-phy.yaml | 7 ++++---
> >  1 file changed, 4 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > index 2ec2d9fda..6f5599902 100644
> > --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > @@ -35,9 +35,10 @@ properties:
> >          description: PHYs that implement IEEE802.3 clause 45
> >        - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
> >          description:
> > -          If the PHY reports an incorrect ID (or none at all) then the
> > -          compatible list may contain an entry with the correct PHY ID
> > -          in the above form.
> > +          If the PHY reports an incorrect ID (or none at all), or the PHY
> > +          requires a specific initialization sequence (like a particular
> > +          order of clocks, resets, power supplies), then the compatible list
> > +          must contain an entry with the correct PHY ID in the above form.
> 
> That is good start, but how about:
> 
>           PHYs contain identification registers. These will be read to
>           identify the PHY. If the PHY reports an incorrect ID, or the
>           PHY requires a specific initialization sequence (like a
>           particular order of clocks, resets, power supplies), in
>           order to be able to read the ID registers, then the
>           compatible list must contain an entry with the correct PHY
>           ID in the above form.
> 
> The first two sentences make it clear we ideally use the ID registers.
> Then we say what happens if cannot work.
> 
> The "(or none at all)" is exactly the case you are trying to clarify,
> it does not respond due to missing reset, clocks etc. We don't need to
> say it twice, so i removed it.

I like this wording,
Acked-by: Conor Dooley <conor.dooley@microchip.com>
pw-bot: changes-requested

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[PATCH v2 1/1] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[Buday Csaba]

Change PHY ID description in ethernet-phy.yaml to clarify that a
PHY ID is required (may -> must) when the PHY requires special
initialization sequence.

Link: https://lore.kernel.org/netdev/20251026212026.GA2959311-robh@kernel.org/
Link: https://lore.kernel.org/netdev/aQIZvDt5gooZSTcp@debianbuilder/

Signed-off-by: Buday Csaba <buday.csaba@prolan.hu>
---
V1 -> V2: Changed wording on maintainer request.
---
 .../devicetree/bindings/net/ethernet-phy.yaml          | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
index 2ec2d9fda..bb4c49fc5 100644
--- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
+++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
@@ -35,9 +35,13 @@ properties:
         description: PHYs that implement IEEE802.3 clause 45
       - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
         description:
-          If the PHY reports an incorrect ID (or none at all) then the
-          compatible list may contain an entry with the correct PHY ID
-          in the above form.
+          PHYs contain identification registers. These will be read to
+          identify the PHY. If the PHY reports an incorrect ID, or the
+          PHY requires a specific initialization sequence (like a
+          particular order of clocks, resets, power supplies), in
+          order to be able to read the ID registers, then the
+          compatible list must contain an entry with the correct PHY
+          ID in the above form.
           The first group of digits is the 16 bit Phy Identifier 1
           register, this is the chip vendor OUI bits 3:18. The
           second group of digits is the Phy Identifier 2 register,

base-commit: 0d0eb186421d0886ac466008235f6d9eedaf918e
-- 
2.39.5

Re: [PATCH v2 1/1] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[Andrew Lunn]

On Mon, Nov 03, 2025 at 09:13:42AM +0100, Buday Csaba wrote:
> Change PHY ID description in ethernet-phy.yaml to clarify that a
> PHY ID is required (may -> must) when the PHY requires special
> initialization sequence.
> 
> Link: https://lore.kernel.org/netdev/20251026212026.GA2959311-robh@kernel.org/
> Link: https://lore.kernel.org/netdev/aQIZvDt5gooZSTcp@debianbuilder/
> 
> Signed-off-by: Buday Csaba <buday.csaba@prolan.hu>

Please always start a new thread for each version of a patch. The CI
probably just sees this as a comment made to the previous version, and
so has probably not tested it.

Given that you have only changed some DT binding text, it is however
likely safe.

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

Re: [PATCH v2 1/1] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[Florian Fainelli]

On 11/3/25 00:13, Buday Csaba wrote:
> Change PHY ID description in ethernet-phy.yaml to clarify that a
> PHY ID is required (may -> must) when the PHY requires special
> initialization sequence.
> 
> Link: https://lore.kernel.org/netdev/20251026212026.GA2959311-robh@kernel.org/
> Link: https://lore.kernel.org/netdev/aQIZvDt5gooZSTcp@debianbuilder/
> 
> Signed-off-by: Buday Csaba <buday.csaba@prolan.hu>

Reviewed-by: Florian Fainelli <florian.fainelli@broadcom.com>
-- 
Florian

Re: [PATCH v2 1/1] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID

[patchwork-bot+netdevbpf]

Hello:

This patch was applied to netdev/net-next.git (main)
by Jakub Kicinski <kuba@kernel.org>:

On Mon, 3 Nov 2025 09:13:42 +0100 you wrote:
> Change PHY ID description in ethernet-phy.yaml to clarify that a
> PHY ID is required (may -> must) when the PHY requires special
> initialization sequence.
> 
> Link: https://lore.kernel.org/netdev/20251026212026.GA2959311-robh@kernel.org/
> Link: https://lore.kernel.org/netdev/aQIZvDt5gooZSTcp@debianbuilder/
> 
> [...]

Here is the summary with links:
  - [v2,1/1] dt-bindings: net: ethernet-phy: clarify when compatible must specify PHY ID
    https://git.kernel.org/netdev/net-next/c/e0c78fcad2bb

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html