diff mbox series

[net-next,v2,1/2] dt-bindings: net: ethernet-phy: Add master-slave role property for SPE PHYs

Message ID 20240909124342.2838263-2-o.rempel@pengutronix.de (mailing list archive)
State Superseded
Delegated to: Netdev Maintainers
Headers show
Series net: phy: Support master-slave config via device tree | expand

Checks

Context Check Description
netdev/series_format success Posting correctly formatted
netdev/tree_selection success Clearly marked for net-next
netdev/ynl success Generated files up to date; no warnings/errors; no diff in generated;
netdev/fixes_present success Fixes tag not required for -next series
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 7 this patch: 7
netdev/build_tools success No tools touched, skip
netdev/cc_maintainers success CCed 12 of 12 maintainers
netdev/build_clang success Errors and warnings before: 7 this patch: 7
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/deprecated_api success None detected
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 7 this patch: 7
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 20 lines checked
netdev/build_clang_rust success No Rust files in patch. Skipping build
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0

Commit Message

Oleksij Rempel Sept. 9, 2024, 12:43 p.m. UTC
Introduce a new `master-slave` string property in the ethernet-phy
binding to specify the link role for Single Pair Ethernet
(1000/100/10Base-T1) PHYs. This property supports the values
`forced-master` and `forced-slave`, which allow the PHY to operate in a
predefined role, necessary when hardware strap pins are unavailable or
wrongly set.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
changes v2:
- use string property instead of multiple flags
---
 .../devicetree/bindings/net/ethernet-phy.yaml      | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

Comments

Florian Fainelli Sept. 9, 2024, 3:56 p.m. UTC | #1
On 9/9/24 05:43, Oleksij Rempel wrote:
> Introduce a new `master-slave` string property in the ethernet-phy
> binding to specify the link role for Single Pair Ethernet
> (1000/100/10Base-T1) PHYs. This property supports the values
> `forced-master` and `forced-slave`, which allow the PHY to operate in a
> predefined role, necessary when hardware strap pins are unavailable or
> wrongly set.
> 
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> ---
> changes v2:
> - use string property instead of multiple flags
> ---
>   .../devicetree/bindings/net/ethernet-phy.yaml      | 14 ++++++++++++++
>   1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> index d9b62741a2259..025e59f6be6f3 100644
> --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> @@ -158,6 +158,20 @@ properties:
>         Mark the corresponding energy efficient ethernet mode as
>         broken and request the ethernet to stop advertising it.
>   
> +  master-slave:
> +    $ref: /schemas/types.yaml#/definitions/string
> +    enum:
> +      - forced-master
> +      - forced-slave
> +    description: |
> +      Specifies the predefined link role for the PHY in Single Pair Ethernet
> +      (1000/100/10Base-T1).  This property is required for setups where the link
> +      role must be assigned by the device tree due to limitations in using
> +      hardware strap pins.

Nit: the way this is implemented right now, this is also applicable to 
1000BaseT which is fine, just needs to be called out explicitly IMHO.
Rob Herring Sept. 9, 2024, 4:20 p.m. UTC | #2
On Mon, Sep 09, 2024 at 02:43:40PM +0200, Oleksij Rempel wrote:
> Introduce a new `master-slave` string property in the ethernet-phy
> binding to specify the link role for Single Pair Ethernet
> (1000/100/10Base-T1) PHYs. This property supports the values
> `forced-master` and `forced-slave`, which allow the PHY to operate in a
> predefined role, necessary when hardware strap pins are unavailable or
> wrongly set.
> 
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> ---
> changes v2:
> - use string property instead of multiple flags
> ---
>  .../devicetree/bindings/net/ethernet-phy.yaml      | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> index d9b62741a2259..025e59f6be6f3 100644
> --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> @@ -158,6 +158,20 @@ properties:
>        Mark the corresponding energy efficient ethernet mode as
>        broken and request the ethernet to stop advertising it.
>  
> +  master-slave:

Outdated terminology and kind of vague what it is for...

The usual transformation to 'controller-device' would not make much
sense though. I think a better name would be "spe-link-role" or
"spe-link-mode".

> +    $ref: /schemas/types.yaml#/definitions/string
> +    enum:
> +      - forced-master
> +      - forced-slave
> +    description: |
> +      Specifies the predefined link role for the PHY in Single Pair Ethernet
> +      (1000/100/10Base-T1).  This property is required for setups where the link
> +      role must be assigned by the device tree due to limitations in using
> +      hardware strap pins.
> +
> +      - 'forced-master': The PHY is forced to operate as a master.
> +      - 'forced-slave': The PHY is forced to operate as a slave.
> +
>    pses:
>      $ref: /schemas/types.yaml#/definitions/phandle-array
>      maxItems: 1
> -- 
> 2.39.2
>
Andrew Lunn Sept. 9, 2024, 5 p.m. UTC | #3
On Mon, Sep 09, 2024 at 11:20:09AM -0500, Rob Herring wrote:
> On Mon, Sep 09, 2024 at 02:43:40PM +0200, Oleksij Rempel wrote:
> > Introduce a new `master-slave` string property in the ethernet-phy
> > binding to specify the link role for Single Pair Ethernet
> > (1000/100/10Base-T1) PHYs. This property supports the values
> > `forced-master` and `forced-slave`, which allow the PHY to operate in a
> > predefined role, necessary when hardware strap pins are unavailable or
> > wrongly set.
> > 
> > Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> > ---
> > changes v2:
> > - use string property instead of multiple flags
> > ---
> >  .../devicetree/bindings/net/ethernet-phy.yaml      | 14 ++++++++++++++
> >  1 file changed, 14 insertions(+)
> > 
> > diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > index d9b62741a2259..025e59f6be6f3 100644
> > --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > @@ -158,6 +158,20 @@ properties:
> >        Mark the corresponding energy efficient ethernet mode as
> >        broken and request the ethernet to stop advertising it.
> >  
> > +  master-slave:
> 
> Outdated terminology and kind of vague what it is for...
> 
> The usual transformation to 'controller-device' would not make much
> sense though. I think a better name would be "spe-link-role" or
> "spe-link-mode".

This applies to more than Single Pair Ethernet. This property could
also be used for 2 and 4 pair cables. So spe-link-mode would be wrong.

Also:

https://grouper.ieee.org/groups/802/3/dc/comments/P8023_D2p0_comments_final_by_cls.pdf

On 3 December 2020, the IEEE SA Standard Board passed the following resolution. (See
<https://standards.ieee.org/about/sasb/resolutions.html>.)

  "IEEE standards (including recommended practices and guides) shall
  be written in such a way as to unambiguously communicate the
  technical necessities, preferences, and options of the standard to
  best enable market adoption, conformity assessment,
  interoperability, and other technical aspirations of the developing
  standards committee. IEEE standards should be written in such a way
  as to avoid non-inclusive and insensitive terminology (see IEEE
  Policy 9.27) and other deprecated terminology (see clause 10 of the
  IEEE SA Style Manual) except when required by safety, legal,
  regulatory, and other similar considerations.  Terms such as
  master/slave, blacklist, and whitelist should be avoided."

  In IEEE Std 802.3, 1000BASE-T, 10BASE-T1L, 100BASE-T1, 1000BASE-T1,
  and MultiGBASE-T PHYs use the terms "master" and "slave" to indicate
  whether the clock is derived from an external source or from the
  received signal. In these cases, the terms appear in the text,
  figures, state names, variable names, register/bit names, etc. A
  direct substitution of terms will create disconnects between the
  standard and the documentation for devices in the field (e.g., the
  register interface) and also risks the introduction of technical
  errors. Note that "master" and "slave" are also occasionally used to
  describe the relationship between an ONT and an ONU for EPON and
  between a CNT and a CNU for EPoC.

  The approach that other IEEE standards are taking to address this
  issue have been considered. For example, IEEE P1588g proposes to
  define "optional alternative suitable and inclusive terminology" but
  not replace the original terms. (See
  <https://development.standards.ieee.org/myproject-web/public/view.html#pardetail/8858>.)
  It is understood that an annex to the IEEE 1588 standard has been
  proposed that defines the inclusive terminology. It is also
  understood that the inclusive terminology has been chosen to be
  "leader" and "follower".

  The IEEE P802.1ASdr project proposes to align to the IEEE P1588g
  inclusive terminology.  (See
  <https://development.standards.ieee.org/myprojectweb/public/view.html#pardetail/9009>.)
  Based on this, it seems reasonable to include an annex that defines
  optional alternative inclusive terminology and, for consistency, to
  use the terms "leader" and "follower" as the inclusive terminology

The 2022 revision of 802.3 still has master/slave when describing the
registers, but it does have Annex K as described above saying "leader"
and "follower" are optional substitutions.

The Linux code has not changed, and the uAPI has not changed. It seems
like the best compromise would be to allow both 'force-master' and
'force-leader', as well as 'force-slave' and 'force-follower', and a
reference to 802.3 Annex K.

As to you comment about it being unclear what it means i would suggest
a reference to 802.3 section 1.4.389:

  1.4.389 master Physical Layer device (PHY): Within IEEE 802.3, in a
  100BASE-T2, 1000BASE-T, 10BASE-T1L, 100BASE-T1, 1000BASE-T1, or any
  MultiGBASE-T link containing a pair of PHYs, the PHY that uses an
  external clock for generating its clock signals to determine the
  timing of transmitter and receiver operations. It also uses the
  master transmit scrambler generator polynomial for side-stream
  scrambling. Master and slave PHY status is determined during the
  Auto-Negotiation process that takes place prior to establishing the
  transmission link, or in the case of a PHY where Auto-Negotiation is
  optional and not used, master and slave PHY status

	Andrew
Rob Herring Sept. 10, 2024, 4:54 p.m. UTC | #4
On Mon, Sep 9, 2024 at 12:00 PM Andrew Lunn <andrew@lunn.ch> wrote:
>
> On Mon, Sep 09, 2024 at 11:20:09AM -0500, Rob Herring wrote:
> > On Mon, Sep 09, 2024 at 02:43:40PM +0200, Oleksij Rempel wrote:
> > > Introduce a new `master-slave` string property in the ethernet-phy
> > > binding to specify the link role for Single Pair Ethernet
> > > (1000/100/10Base-T1) PHYs. This property supports the values
> > > `forced-master` and `forced-slave`, which allow the PHY to operate in a
> > > predefined role, necessary when hardware strap pins are unavailable or
> > > wrongly set.
> > >
> > > Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> > > ---
> > > changes v2:
> > > - use string property instead of multiple flags
> > > ---
> > >  .../devicetree/bindings/net/ethernet-phy.yaml      | 14 ++++++++++++++
> > >  1 file changed, 14 insertions(+)
> > >
> > > diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > > index d9b62741a2259..025e59f6be6f3 100644
> > > --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > > +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> > > @@ -158,6 +158,20 @@ properties:
> > >        Mark the corresponding energy efficient ethernet mode as
> > >        broken and request the ethernet to stop advertising it.
> > >
> > > +  master-slave:
> >
> > Outdated terminology and kind of vague what it is for...
> >
> > The usual transformation to 'controller-device' would not make much
> > sense though. I think a better name would be "spe-link-role" or
> > "spe-link-mode".
>
> This applies to more than Single Pair Ethernet. This property could
> also be used for 2 and 4 pair cables. So spe-link-mode would be wrong.

I kind of figured that... Propose something that's not just
duplicating possible values.

>
> Also:
>
> https://grouper.ieee.org/groups/802/3/dc/comments/P8023_D2p0_comments_final_by_cls.pdf
>
> On 3 December 2020, the IEEE SA Standard Board passed the following resolution. (See
> <https://standards.ieee.org/about/sasb/resolutions.html>.)
>
>   "IEEE standards (including recommended practices and guides) shall
>   be written in such a way as to unambiguously communicate the
>   technical necessities, preferences, and options of the standard to
>   best enable market adoption, conformity assessment,
>   interoperability, and other technical aspirations of the developing
>   standards committee. IEEE standards should be written in such a way
>   as to avoid non-inclusive and insensitive terminology (see IEEE
>   Policy 9.27) and other deprecated terminology (see clause 10 of the
>   IEEE SA Style Manual) except when required by safety, legal,
>   regulatory, and other similar considerations.  Terms such as
>   master/slave, blacklist, and whitelist should be avoided."
>
>   In IEEE Std 802.3, 1000BASE-T, 10BASE-T1L, 100BASE-T1, 1000BASE-T1,
>   and MultiGBASE-T PHYs use the terms "master" and "slave" to indicate
>   whether the clock is derived from an external source or from the
>   received signal. In these cases, the terms appear in the text,
>   figures, state names, variable names, register/bit names, etc. A
>   direct substitution of terms will create disconnects between the
>   standard and the documentation for devices in the field (e.g., the
>   register interface) and also risks the introduction of technical
>   errors. Note that "master" and "slave" are also occasionally used to
>   describe the relationship between an ONT and an ONU for EPON and
>   between a CNT and a CNU for EPoC.
>
>   The approach that other IEEE standards are taking to address this
>   issue have been considered. For example, IEEE P1588g proposes to
>   define "optional alternative suitable and inclusive terminology" but
>   not replace the original terms. (See
>   <https://development.standards.ieee.org/myproject-web/public/view.html#pardetail/8858>.)
>   It is understood that an annex to the IEEE 1588 standard has been
>   proposed that defines the inclusive terminology. It is also
>   understood that the inclusive terminology has been chosen to be
>   "leader" and "follower".
>
>   The IEEE P802.1ASdr project proposes to align to the IEEE P1588g
>   inclusive terminology.  (See
>   <https://development.standards.ieee.org/myprojectweb/public/view.html#pardetail/9009>.)
>   Based on this, it seems reasonable to include an annex that defines
>   optional alternative inclusive terminology and, for consistency, to
>   use the terms "leader" and "follower" as the inclusive terminology
>
> The 2022 revision of 802.3 still has master/slave when describing the
> registers, but it does have Annex K as described above saying "leader"
> and "follower" are optional substitutions.
>
> The Linux code has not changed, and the uAPI has not changed. It seems
> like the best compromise would be to allow both 'force-master' and
> 'force-leader', as well as 'force-slave' and 'force-follower', and a
> reference to 802.3 Annex K.

It seems silly to maintain both forever. I'd rather have one or the
other than both.

> As to you comment about it being unclear what it means i would suggest
> a reference to 802.3 section 1.4.389:
>
>   1.4.389 master Physical Layer device (PHY): Within IEEE 802.3, in a
>   100BASE-T2, 1000BASE-T, 10BASE-T1L, 100BASE-T1, 1000BASE-T1, or any
>   MultiGBASE-T link containing a pair of PHYs, the PHY that uses an
>   external clock for generating its clock signals to determine the
>   timing of transmitter and receiver operations. It also uses the
>   master transmit scrambler generator polynomial for side-stream
>   scrambling. Master and slave PHY status is determined during the
>   Auto-Negotiation process that takes place prior to establishing the
>   transmission link, or in the case of a PHY where Auto-Negotiation is
>   optional and not used, master and slave PHY status

phy-status? Shrug.

Another thought. Is it possible that h/w strapping disables auto-neg,
but you actually want to override that and force auto-neg?

Rob
Oleksij Rempel Sept. 11, 2024, 7 a.m. UTC | #5
On Tue, Sep 10, 2024 at 11:54:04AM -0500, Rob Herring wrote:
> On Mon, Sep 9, 2024 at 12:00 PM Andrew Lunn <andrew@lunn.ch> wrote:
....
> > The 2022 revision of 802.3 still has master/slave when describing the
> > registers, but it does have Annex K as described above saying "leader"
> > and "follower" are optional substitutions.
> >
> > The Linux code has not changed, and the uAPI has not changed. It seems
> > like the best compromise would be to allow both 'force-master' and
> > 'force-leader', as well as 'force-slave' and 'force-follower', and a
> > reference to 802.3 Annex K.
> 
> It seems silly to maintain both forever. I'd rather have one or the
> other than both.

I'll accept what ever will be decided. Even if we will decide to use
words 'leader' and 'follower' for the properties, we still need to
document that they correspond to 'master' and 'slave' in the IEEE
specification and in the kernel UAPI.

I can imagine a mdi-link-clock-role = 'leader' or 'follower'

> > As to you comment about it being unclear what it means i would suggest
> > a reference to 802.3 section 1.4.389:
> >
> >   1.4.389 master Physical Layer device (PHY): Within IEEE 802.3, in a
> >   100BASE-T2, 1000BASE-T, 10BASE-T1L, 100BASE-T1, 1000BASE-T1, or any
> >   MultiGBASE-T link containing a pair of PHYs, the PHY that uses an
> >   external clock for generating its clock signals to determine the
> >   timing of transmitter and receiver operations. It also uses the
> >   master transmit scrambler generator polynomial for side-stream
> >   scrambling. Master and slave PHY status is determined during the
> >   Auto-Negotiation process that takes place prior to establishing the
> >   transmission link, or in the case of a PHY where Auto-Negotiation is
> >   optional and not used, master and slave PHY status
> 
> phy-status? Shrug.

In my understanding, the 'status' is result not actual configuration
request.

> Another thought. Is it possible that h/w strapping disables auto-neg,
> but you actually want to override that and force auto-neg?

Yes. If I would need it, I would recommend to have a different override
property, something like: autoneg-default = 'on' or 'off'

Regards,
Oleksij
Andrew Lunn Sept. 11, 2024, 12:05 p.m. UTC | #6
> It seems silly to maintain both forever. I'd rather have one or the
> other than both.

It currently seems like 802.3 is going to keep with master/slave in
the body of the text. And they don't even have to deal with breaking
backwards compatibility. So i suggest we keep with master/slave, but
comment that an annex of the standard proposes alternative names of
leader/follower. But don't actually accept them.

> 
> > As to you comment about it being unclear what it means i would suggest
> > a reference to 802.3 section 1.4.389:
> >
> >   1.4.389 master Physical Layer device (PHY): Within IEEE 802.3, in a
> >   100BASE-T2, 1000BASE-T, 10BASE-T1L, 100BASE-T1, 1000BASE-T1, or any
> >   MultiGBASE-T link containing a pair of PHYs, the PHY that uses an
> >   external clock for generating its clock signals to determine the
> >   timing of transmitter and receiver operations. It also uses the
> >   master transmit scrambler generator polynomial for side-stream
> >   scrambling. Master and slave PHY status is determined during the
> >   Auto-Negotiation process that takes place prior to establishing the
> >   transmission link, or in the case of a PHY where Auto-Negotiation is
> >   optional and not used, master and slave PHY status
> 
> phy-status? Shrug.

phy-status is too generic. Maybe 'timing-role' ?

> 
> Another thought. Is it possible that h/w strapping disables auto-neg,
> but you actually want to override that and force auto-neg?

Autoneg can be used for a bunch of parameters. In automotive
situations, it is generally disabled and those parameters are
forced. In more tradition settings those parameters are
negotiated. However, even with autoneg enabled, you can force each
individual parameter, rather than negotiate it.

So we would need a DT parameter about autoneg in general. And then a
DT parameter about 'timing-role', where force-master/force-slave means
don't negotiate, and prefer-master/prefer-slave means do negotiate
with the given preference.

	Andrew
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
index d9b62741a2259..025e59f6be6f3 100644
--- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
+++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
@@ -158,6 +158,20 @@  properties:
       Mark the corresponding energy efficient ethernet mode as
       broken and request the ethernet to stop advertising it.
 
+  master-slave:
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - forced-master
+      - forced-slave
+    description: |
+      Specifies the predefined link role for the PHY in Single Pair Ethernet
+      (1000/100/10Base-T1).  This property is required for setups where the link
+      role must be assigned by the device tree due to limitations in using
+      hardware strap pins.
+
+      - 'forced-master': The PHY is forced to operate as a master.
+      - 'forced-slave': The PHY is forced to operate as a slave.
+
   pses:
     $ref: /schemas/types.yaml#/definitions/phandle-array
     maxItems: 1