diff mbox series

[net-next,v4,1/2] dt-bindings: net: ethernet-phy: Add timing-role role property for ethernet PHYs

Message ID 20241001073704.1389952-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: 9 this patch: 9
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: 9 this patch: 9
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 fail Errors and warnings before: 13 this patch: 12
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 27 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 Oct. 1, 2024, 7:37 a.m. UTC 
This patch introduces a new `timing-role` property in the device tree
bindings for configuring the master/slave role of PHYs. This is
essential for scenarios where hardware strap pins are unavailable or
incorrectly configured.

The `timing-role` property supports the following values:
- `force-master`: Forces the PHY to operate as a master (clock source).
- `force-slave`: Forces the PHY to operate as a slave (clock receiver).
- `prefer-master`: Prefers the PHY to be master but allows negotiation.
- `prefer-slave`: Prefers the PHY to be slave but allows negotiation.

The terms "master" and "slave" are retained in this context to align
with the IEEE 802.3 standards, where they are used to describe the roles
of PHY devices in managing clock signals for data transmission. In
particular, the terms are used in specifications for 1000Base-T and
MultiGBASE-T PHYs, among others. Although there is an effort to adopt
more inclusive terminology, replacing these terms could create
discrepancies between the Linux kernel and the established standards,
documentation, and existing hardware interfaces.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
Reviewed-by: Rob Herring (Arm) <robh@kernel.org>
---
changes v4:
- add "Reviewed-by: Rob Herring (Arm) <robh@kernel.org>"
changes v3:
- rename "master-slave" to "timing-role"
changes v2:
- use string property instead of multiple flags
---
 .../devicetree/bindings/net/ethernet-phy.yaml | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

Comments

Florian Fainelli Oct. 2, 2024, 4:29 a.m. UTC | #1 
On 10/1/2024 12:37 AM, Oleksij Rempel wrote:
> This patch introduces a new `timing-role` property in the device tree
> bindings for configuring the master/slave role of PHYs. This is
> essential for scenarios where hardware strap pins are unavailable or
> incorrectly configured.
> 
> The `timing-role` property supports the following values:
> - `force-master`: Forces the PHY to operate as a master (clock source).
> - `force-slave`: Forces the PHY to operate as a slave (clock receiver).
> - `prefer-master`: Prefers the PHY to be master but allows negotiation.
> - `prefer-slave`: Prefers the PHY to be slave but allows negotiation.
> 
> The terms "master" and "slave" are retained in this context to align
> with the IEEE 802.3 standards, where they are used to describe the roles
> of PHY devices in managing clock signals for data transmission. In
> particular, the terms are used in specifications for 1000Base-T and
> MultiGBASE-T PHYs, among others. Although there is an effort to adopt
> more inclusive terminology, replacing these terms could create
> discrepancies between the Linux kernel and the established standards,
> documentation, and existing hardware interfaces.
> 
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> Reviewed-by: Rob Herring (Arm) <robh@kernel.org>

Reviewed-by: Florian Fainelli <florian.fainelli@broadcom.com>
Divya Koppera Oct. 3, 2024, 10:49 a.m. UTC | #2 
> -----Original Message-----
> From: Oleksij Rempel <o.rempel@pengutronix.de>
> Sent: Tuesday, October 1, 2024 1:07 PM
> To: Andrew Lunn <andrew@lunn.ch>; Heiner Kallweit
> <hkallweit1@gmail.com>; David S. Miller <davem@davemloft.net>; Eric
> Dumazet <edumazet@google.com>; Jakub Kicinski <kuba@kernel.org>; Paolo
> Abeni <pabeni@redhat.com>; Rob Herring <robh@kernel.org>; Krzysztof
> Kozlowski <krzk+dt@kernel.org>; Conor Dooley <conor+dt@kernel.org>;
> Florian Fainelli <f.fainelli@gmail.com>
> Cc: Oleksij Rempel <o.rempel@pengutronix.de>; kernel@pengutronix.de;
> linux-kernel@vger.kernel.org; netdev@vger.kernel.org; Russell King
> <linux@armlinux.org.uk>; devicetree@vger.kernel.org
> Subject: [PATCH net-next v4 1/2] dt-bindings: net: ethernet-phy: Add timing-
> role role property for ethernet PHYs
> 
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the
> content is safe
> 
> This patch introduces a new `timing-role` property in the device tree bindings
> for configuring the master/slave role of PHYs. This is essential for scenarios
> where hardware strap pins are unavailable or incorrectly configured.
> 
> The `timing-role` property supports the following values:
> - `force-master`: Forces the PHY to operate as a master (clock source).
> - `force-slave`: Forces the PHY to operate as a slave (clock receiver).
> - `prefer-master`: Prefers the PHY to be master but allows negotiation.
> - `prefer-slave`: Prefers the PHY to be slave but allows negotiation.
> 
> The terms "master" and "slave" are retained in this context to align with the
> IEEE 802.3 standards, where they are used to describe the roles of PHY
> devices in managing clock signals for data transmission. In particular, the
> terms are used in specifications for 1000Base-T and MultiGBASE-T PHYs,
> among others. Although there is an effort to adopt more inclusive
> terminology, replacing these terms could create discrepancies between the
> Linux kernel and the established standards, documentation, and existing
> hardware interfaces.
> 
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> Reviewed-by: Rob Herring (Arm) <robh@kernel.org>
> ---
> changes v4:
> - add "Reviewed-by: Rob Herring (Arm) <robh@kernel.org>"
> changes v3:
> - rename "master-slave" to "timing-role"
> changes v2:
> - use string property instead of multiple flags
> ---
>  .../devicetree/bindings/net/ethernet-phy.yaml | 21 +++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> index d9b62741a2259..da9eaa811d70f 100644
> --- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> @@ -158,6 +158,27 @@ properties:
>        Mark the corresponding energy efficient ethernet mode as
>        broken and request the ethernet to stop advertising it.
> 
> +  timing-role:
> +    $ref: /schemas/types.yaml#/definitions/string
> +    enum:
> +      - force-master
> +      - force-slave
> +      - prefer-master
> +      - prefer-slave
> +    description: |
> +      Specifies the timing role of the PHY in the network link. This property is
> +      required for setups where the role must be explicitly assigned via the
> +      device tree due to limitations in hardware strapping or incorrect strap
> +      configurations.
> +      It is applicable to Single Pair Ethernet (1000/100/10Base-T1) and other
> +      PHY types, including 1000Base-T, where it controls whether the PHY
> should
> +      be a master (clock source) or a slave (clock receiver).
> +
> +      - 'force-master': The PHY is forced to operate as a master.
> +      - 'force-slave': The PHY is forced to operate as a slave.
> +      - 'prefer-master': Prefer the PHY to be master but allow negotiation.
> +      - 'prefer-slave': Prefer the PHY to be slave but allow negotiation.
> +

I would suggest to use "preferred" instead of "prefer" to be in sync with existing phy library macros.

>    pses:
>      $ref: /schemas/types.yaml#/definitions/phandle-array
>      maxItems: 1
> --
> 2.39.5
> 

Reviewed-by: Divya Koppera <divya.koppera@microchip.com>
Andrew Lunn Oct. 3, 2024, 12:08 p.m. UTC | #3 
> > +      - 'force-master': The PHY is forced to operate as a master.
> > +      - 'force-slave': The PHY is forced to operate as a slave.
> > +      - 'prefer-master': Prefer the PHY to be master but allow negotiation.
> > +      - 'prefer-slave': Prefer the PHY to be slave but allow negotiation.
> > +
> 
> I would suggest to use "preferred" instead of "prefer" to be in sync with existing phy library macros.

How does 802.3 name it?

	Andrew
Oleksij Rempel Oct. 3, 2024, 1:08 p.m. UTC | #4 
On Thu, Oct 03, 2024 at 02:08:00PM +0200, Andrew Lunn wrote:
> > > +      - 'force-master': The PHY is forced to operate as a master.
> > > +      - 'force-slave': The PHY is forced to operate as a slave.
> > > +      - 'prefer-master': Prefer the PHY to be master but allow negotiation.
> > > +      - 'prefer-slave': Prefer the PHY to be slave but allow negotiation.
> > > +
> > 
> > I would suggest to use "preferred" instead of "prefer" to be in sync with existing phy library macros.
> 
> How does 802.3 name it?

802.3 use "Multiport device" for "preferred master" and "single-port device"
for "preferred slave". We decided to use other wording back in the past
to avoid confusing and align it with forced master/slave configurations.
Andrew Lunn Oct. 3, 2024, 5:05 p.m. UTC | #5 
On Thu, Oct 03, 2024 at 03:08:09PM +0200, Oleksij Rempel wrote:
> On Thu, Oct 03, 2024 at 02:08:00PM +0200, Andrew Lunn wrote:
> > > > +      - 'force-master': The PHY is forced to operate as a master.
> > > > +      - 'force-slave': The PHY is forced to operate as a slave.
> > > > +      - 'prefer-master': Prefer the PHY to be master but allow negotiation.
> > > > +      - 'prefer-slave': Prefer the PHY to be slave but allow negotiation.
> > > > +
> > > 
> > > I would suggest to use "preferred" instead of "prefer" to be in sync with existing phy library macros.
> > 
> > How does 802.3 name it?
> 
> 802.3 use "Multiport device" for "preferred master" and "single-port device"
> for "preferred slave". We decided to use other wording back in the past
> to avoid confusing and align it with forced master/slave configurations. 

ethtool is preferred, so it would be more consistent with preferred

[Shrug]

	Andrew
Jakub Kicinski Oct. 4, 2024, 4:51 p.m. UTC | #6 
On Thu, 3 Oct 2024 19:05:58 +0200 Andrew Lunn wrote:
> > 802.3 use "Multiport device" for "preferred master" and "single-port device"
> > for "preferred slave". We decided to use other wording back in the past
> > to avoid confusing and align it with forced master/slave configurations.   
> 
> ethtool is preferred, so it would be more consistent with preferred
> 
> [Shrug]

IIUC we have two weak preferences for "preferred"?
LMK if I misunderstood.
Oleksij Rempel Oct. 7, 2024, 5:15 a.m. UTC | #7 
On Fri, Oct 04, 2024 at 09:51:54AM -0700, Jakub Kicinski wrote:
> On Thu, 3 Oct 2024 19:05:58 +0200 Andrew Lunn wrote:
> > > 802.3 use "Multiport device" for "preferred master" and "single-port device"
> > > for "preferred slave". We decided to use other wording back in the past
> > > to avoid confusing and align it with forced master/slave configurations.   
> > 
> > ethtool is preferred, so it would be more consistent with preferred
> > 
> > [Shrug]
> 
> IIUC we have two weak preferences for "preferred"?
> LMK if I misunderstood.

Ahm... yes :)
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
index d9b62741a2259..da9eaa811d70f 100644
--- a/Documentation/devicetree/bindings/net/ethernet-phy.yaml
+++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
@@ -158,6 +158,27 @@  properties:
       Mark the corresponding energy efficient ethernet mode as
       broken and request the ethernet to stop advertising it.
 
+  timing-role:
+    $ref: /schemas/types.yaml#/definitions/string
+    enum:
+      - force-master
+      - force-slave
+      - prefer-master
+      - prefer-slave
+    description: |
+      Specifies the timing role of the PHY in the network link. This property is
+      required for setups where the role must be explicitly assigned via the
+      device tree due to limitations in hardware strapping or incorrect strap
+      configurations.
+      It is applicable to Single Pair Ethernet (1000/100/10Base-T1) and other
+      PHY types, including 1000Base-T, where it controls whether the PHY should
+      be a master (clock source) or a slave (clock receiver).
+
+      - 'force-master': The PHY is forced to operate as a master.
+      - 'force-slave': The PHY is forced to operate as a slave.
+      - 'prefer-master': Prefer the PHY to be master but allow negotiation.
+      - 'prefer-slave': Prefer the PHY to be slave but allow negotiation.
+
   pses:
     $ref: /schemas/types.yaml#/definitions/phandle-array
     maxItems: 1