Re: [PATCH v4 net-next 8/9] dt-bindings: net: add generic ethernet-switch-port binding

[Vladimir Oltean]

On Fri, Dec 02, 2022 at 12:45:58PM -0800, Colin Foster wrote:
> The dsa-port.yaml binding had several references that can be common to all
> ethernet ports, not just dsa-specific ones. Break out the generic bindings
> to ethernet-switch-port.yaml they can be used by non-dsa drivers.
> 
> Signed-off-by: Colin Foster <colin.foster@xxxxxxxxxxxxxxxx>
> Suggested-by: Vladimir Oltean <olteanv@xxxxxxxxx>
> Reviewed-by: Florian Fainelli <f.fainelli@xxxxxxxxx>
> ---
> 
> v3 -> v4
>   * Add Florian Reviewed tag
> 
> v2 -> v3
>   * Change dsa-port title from "DSA Switch port Device Tree Bindings"
>     to "Generic DSA Switch port"
>   * Add reference to ethernet-switch-port.yaml# in dsa-port.yaml
>   * Change title of ethernet-switch-port.yaml from "Ethernet Switch
>     port Device Tree Bindings" to "Generic Ethernet Switch port"
>   * Remove most properties from ethernet-switch-port.yaml. They're
>     all in ethernet-controller, and are all allowed.
>   * ethernet-switch.yaml now only references ethernet-switch-port.yaml#
>     under the port node.
> 
> v1 -> v2
>   * Remove accidental addition of
>     "$ref: /schemas/net/ethernet-switch-port.yaml" which should be kept
>     out of dsa-port so that it doesn't get referenced multiple times
>     through both ethernet-switch and dsa-port.
> 
> ---
>  .../devicetree/bindings/net/dsa/dsa-port.yaml | 24 ++----------------
>  .../bindings/net/ethernet-switch-port.yaml    | 25 +++++++++++++++++++
>  .../bindings/net/ethernet-switch.yaml         |  6 +----
>  MAINTAINERS                                   |  1 +
>  4 files changed, 29 insertions(+), 27 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/net/ethernet-switch-port.yaml
> 
> diff --git a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml
> index 9abb8eba5fad..5b457f41273a 100644
> --- a/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml
> +++ b/Documentation/devicetree/bindings/net/dsa/dsa-port.yaml
> @@ -4,7 +4,7 @@
>  $id: http://devicetree.org/schemas/net/dsa/dsa-port.yaml#
>  $schema: http://devicetree.org/meta-schemas/core.yaml#
>  
> -title: Ethernet Switch port Device Tree Bindings
> +title: Generic DSA Switch port

What are the capitalization rules in titles? Looks odd that "port" is
lowercase but "switch" isn't.

>  
>  maintainers:
>    - Andrew Lunn <andrew@xxxxxxx>
> @@ -14,8 +14,7 @@ maintainers:
>  description:
>    Ethernet switch port Description
>  
> -allOf:
> -  - $ref: /schemas/net/ethernet-controller.yaml#
> +$ref: /schemas/net/ethernet-switch-port.yaml#
>  
>  properties:
>    reg:
> @@ -58,25 +57,6 @@ properties:
>        - rtl8_4t
>        - seville
>  
> -  phy-handle: true
> -
> -  phy-mode: true
> -
> -  fixed-link: true
> -
> -  mac-address: true
> -
> -  sfp: true
> -
> -  managed: true
> -
> -  rx-internal-delay-ps: true
> -
> -  tx-internal-delay-ps: true
> -
> -required:
> -  - reg
> -
>  # CPU and DSA ports must have phylink-compatible link descriptions
>  if:
>    oneOf:
> diff --git a/Documentation/devicetree/bindings/net/ethernet-switch-port.yaml b/Documentation/devicetree/bindings/net/ethernet-switch-port.yaml
> new file mode 100644
> index 000000000000..3d7da6916fb8
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/ethernet-switch-port.yaml
> @@ -0,0 +1,25 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/ethernet-switch-port.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Generic Ethernet Switch port
> +
> +maintainers:
> +  - Andrew Lunn <andrew@xxxxxxx>
> +  - Florian Fainelli <f.fainelli@xxxxxxxxx>
> +  - Vivien Didelot <vivien.didelot@xxxxxxxxx>
> +
> +description:
> +  Ethernet switch port Description

Sounds a bit too "lorem ipsum dolor sit amet". You can say that a port
is a component of a switch which manages one MAC, and can pass Ethernet
frames.

> +
> +$ref: ethernet-controller.yaml#
> +
> +properties:
> +  reg:
> +    description: Port number
> +
> +additionalProperties: true
> +
> +...
> diff --git a/Documentation/devicetree/bindings/net/ethernet-switch.yaml b/Documentation/devicetree/bindings/net/ethernet-switch.yaml
> index afeb9ffd84c8..1e8b7649a9b2 100644
> --- a/Documentation/devicetree/bindings/net/ethernet-switch.yaml
> +++ b/Documentation/devicetree/bindings/net/ethernet-switch.yaml
> @@ -40,10 +40,6 @@ patternProperties:
>          type: object
>          description: Ethernet switch ports
>  
> -        $ref: ethernet-controller.yaml#
> -
> -        additionalProperties: true
> -
>  oneOf:
>    - required:
>        - ports
> @@ -60,7 +56,7 @@ $defs:
>      patternProperties:
>        "^(ethernet-)?port@[0-9]+$":
>          description: Ethernet switch ports
> -        $ref: ethernet-controller.yaml#
> +        $ref: ethernet-switch-port.yaml#
>          unevaluatedProperties: false
>  
>  ...
> diff --git a/MAINTAINERS b/MAINTAINERS
> index d574cae901b3..fe5f52c9864a 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14337,6 +14337,7 @@ M:	Florian Fainelli <f.fainelli@xxxxxxxxx>
>  M:	Vladimir Oltean <olteanv@xxxxxxxxx>
>  S:	Maintained
>  F:	Documentation/devicetree/bindings/net/dsa/
> +F:	Documentation/devicetree/bindings/net/ethernet-switch-port.yaml
>  F:	Documentation/devicetree/bindings/net/ethernet-switch.yaml
>  F:	drivers/net/dsa/
>  F:	include/linux/dsa/
> -- 
> 2.25.1
>