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

Vladimir Oltean
2022-12-06T15:51:34Z

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@in-advantage.com>
> Suggested-by: Vladimir Oltean <olteanv@gmail.com>
> Reviewed-by: Florian Fainelli <f.fainelli@gmail.com>
> ---
>
> 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@lunn.ch>
> @@ -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@lunn.ch>
> + - Florian Fainelli <f.fainelli@gmail.com>
> + - Vivien Didelot <vivien.didelot@gmail.com>
> +
> +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@gmail.com>
> M: Vladimir Oltean <olteanv@gmail.com>
> 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
>