diff mbox series

[v3] dt-bindings: renesas: Document preferred compatible naming

Message ID 20240213192340.2786430-1-niklas.soderlund+renesas@ragnatech.se (mailing list archive)
State Superseded
Delegated to: Geert Uytterhoeven
Headers show
Series [v3] dt-bindings: renesas: Document preferred compatible naming | expand

Commit Message

Niklas Söderlund Feb. 13, 2024, 7:23 p.m. UTC 
Compatibles can come in two formats. Either "vendor,ip-soc" or
"vendor,soc-ip". Add a DT schema file documenting Renesas preferred
policy and enforcing it for all new compatibles, except few existing
patterns.

Suggested-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Signed-off-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
---
* Changes since v2
- Improve the select so it matches on any compatible containing a
  component specific Renesas value.
- Make the regexps more compact.
- Define MaxItems to allow the increased selection to work.
- Add rmobile and shmobile prefixes.
- I did not take Rob's ack from v2 as the schema changed a lot after
  Geerts review.

* Changes since v1
- Split the "SoC agnostic compatibles" section into two to make it's
  intent clearer.
- Improved the documentation for each group of compatibles.
- Reduced the number of regexp to create a larger target area. As
  suggested by Krzysztof the goal is not to validate each SoC name but
  check for the correct order of SoC-IP.

* Changes since RFC
- Moved to Documentation/devicetree/bindings/soc/renesas.
- Changed the pattern in the initial select to match on .*-.*.
- Added a lot of missing compatible values.
---
 .../bindings/soc/renesas/renesas-soc.yaml     | 72 +++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml

Comments

Rob Herring Feb. 13, 2024, 8:21 p.m. UTC | #1 
On Tue, 13 Feb 2024 20:23:40 +0100, Niklas Söderlund wrote:
> Compatibles can come in two formats. Either "vendor,ip-soc" or
> "vendor,soc-ip". Add a DT schema file documenting Renesas preferred
> policy and enforcing it for all new compatibles, except few existing
> patterns.
> 
> Suggested-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> Signed-off-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
> ---
> * Changes since v2
> - Improve the select so it matches on any compatible containing a
>   component specific Renesas value.
> - Make the regexps more compact.
> - Define MaxItems to allow the increased selection to work.
> - Add rmobile and shmobile prefixes.
> - I did not take Rob's ack from v2 as the schema changed a lot after
>   Geerts review.
> 
> * Changes since v1
> - Split the "SoC agnostic compatibles" section into two to make it's
>   intent clearer.
> - Improved the documentation for each group of compatibles.
> - Reduced the number of regexp to create a larger target area. As
>   suggested by Krzysztof the goal is not to validate each SoC name but
>   check for the correct order of SoC-IP.
> 
> * Changes since RFC
> - Moved to Documentation/devicetree/bindings/soc/renesas.
> - Changed the pattern in the initial select to match on .*-.*.
> - Added a lot of missing compatible values.
> ---
>  .../bindings/soc/renesas/renesas-soc.yaml     | 72 +++++++++++++++++++
>  1 file changed, 72 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml: properties:compatible:items: {'anyOf': [{'pattern': '^renesas,(emev2|r(7s|8a|9a)[a-z0-9]+|rcar|rmobile|rz[a-z0-9]*|sh(7[a-z0-9]+)?|mobile)-[a-z0-9-]+$'}, {'pattern': '^renesas,(condor|falcon|gr-peach|salvator|sk-rz|smar(c(2)?)?|spider|white-hawk)(.*)?$'}, {'pattern': '^renesas,(can|cpg|dmac|du|(g)?ether(avb)?|gpio|hscif|(r)?i[i2]c|imr|intc|ipmmu|irqc|jpu|mmcif|msiof|mtu2|pci(e)?|pfc|pwm|[rq]spi|rcar_sound|sata|scif[ab]*|sdhi|thermal|tmu|tpu|usb(2|hs)?|vin|xhci)-[a-z0-9-]+$'}, {'pattern': '^renesas,(d|s)?bsc(3)?-(r8a73a4|r8a7740|sh73a0)$'}, {'pattern': '^renesas,em-(gio|sti|uart)$'}, {'pattern': '^renesas,fsi2-(r8a7740|sh73a0)$'}, {'pattern': '^renesas,hspi-r8a777[89]$'}, {'pattern': '^renesas,sysc-(r8a73a4|r8a7740|rmobile|sh73a0)$'}, {'enum': ['renesas,imr-lx4', 'renesas,mtu2-r7s72100']}, {'enum': ['renesas,smp-sram']}, {'pattern': '^(?!renesas,.+-.+).+$'}]} is not of type 'array'
	from schema $id: http://devicetree.org/meta-schemas/string-array.yaml#

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20240213192340.2786430-1-niklas.soderlund+renesas@ragnatech.se

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.
Rob Herring Feb. 13, 2024, 10:37 p.m. UTC | #2 
On Tue, Feb 13, 2024 at 08:23:40PM +0100, Niklas Söderlund wrote:
> Compatibles can come in two formats. Either "vendor,ip-soc" or
> "vendor,soc-ip". Add a DT schema file documenting Renesas preferred
> policy and enforcing it for all new compatibles, except few existing
> patterns.
> 
> Suggested-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> Signed-off-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
> ---
> * Changes since v2
> - Improve the select so it matches on any compatible containing a
>   component specific Renesas value.
> - Make the regexps more compact.
> - Define MaxItems to allow the increased selection to work.
> - Add rmobile and shmobile prefixes.
> - I did not take Rob's ack from v2 as the schema changed a lot after
>   Geerts review.
> 
> * Changes since v1
> - Split the "SoC agnostic compatibles" section into two to make it's
>   intent clearer.
> - Improved the documentation for each group of compatibles.
> - Reduced the number of regexp to create a larger target area. As
>   suggested by Krzysztof the goal is not to validate each SoC name but
>   check for the correct order of SoC-IP.
> 
> * Changes since RFC
> - Moved to Documentation/devicetree/bindings/soc/renesas.
> - Changed the pattern in the initial select to match on .*-.*.
> - Added a lot of missing compatible values.
> ---
>  .../bindings/soc/renesas/renesas-soc.yaml     | 72 +++++++++++++++++++
>  1 file changed, 72 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
> new file mode 100644
> index 000000000000..57c11022d793
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
> @@ -0,0 +1,72 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/soc/renesas/renesas-soc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Renesas SoC compatibles naming convention
> +
> +maintainers:
> +  - Geert Uytterhoeven <geert+renesas@glider.be>
> +  - Niklas Söderlund <niklas.soderlund@ragnatech.se>
> +
> +description: |
> +  Guidelines for new compatibles for SoC blocks/components.
> +  When adding new compatibles in new bindings, use the format::
> +    renesas,SoC-IP
> +
> +  For example::
> +   renesas,r8a77965-csi2
> +
> +  When adding new compatibles to existing bindings, use the format in the
> +  existing binding, even if it contradicts the above.
> +
> +select:
> +  properties:
> +    compatible:
> +      contains:
> +        pattern: "^renesas,.+-.+$"
> +  required:
> +    - compatible
> +
> +properties:
> +  compatible:
> +    maxItems: 4

'minItems: 1' should fix the error reported.


> +    items:
> +      anyOf:
> +        # Preferred naming style for compatibles of SoC components
> +        - pattern: "^renesas,(emev2|r(7s|8a|9a)[a-z0-9]+|rcar|rmobile|rz[a-z0-9]*|sh(7[a-z0-9]+)?|mobile)-[a-z0-9-]+$"
> +        - pattern: "^renesas,(condor|falcon|gr-peach|salvator|sk-rz|smar(c(2)?)?|spider|white-hawk)(.*)?$"
> +
> +        # Legacy compatibles
> +        #
> +        # New compatibles are not allowed.
> +        - pattern: "^renesas,(can|cpg|dmac|du|(g)?ether(avb)?|gpio|hscif|(r)?i[i2]c|imr|intc|ipmmu|irqc|jpu|mmcif|msiof|mtu2|pci(e)?|pfc|pwm|[rq]spi|rcar_sound|sata|scif[ab]*|sdhi|thermal|tmu|tpu|usb(2|hs)?|vin|xhci)-[a-z0-9-]+$"
> +        - pattern: "^renesas,(d|s)?bsc(3)?-(r8a73a4|r8a7740|sh73a0)$"
> +        - pattern: "^renesas,em-(gio|sti|uart)$"
> +        - pattern: "^renesas,fsi2-(r8a7740|sh73a0)$"
> +        - pattern: "^renesas,hspi-r8a777[89]$"
> +        - pattern: "^renesas,sysc-(r8a73a4|r8a7740|rmobile|sh73a0)$"
> +        - enum:
> +            - renesas,imr-lx4
> +            - renesas,mtu2-r7s72100
> +
> +        # None SoC component compatibles
> +        #
> +        # Compatibles with the Renesas vendor prefix that do not relate to any SoC
> +        # component are OK. New compatibles are allowed.
> +        - enum:
> +            - renesas,smp-sram
> +
> +        # Do not fail compatibles not matching the select pattern
> +        #
> +        # Some SoC components in addition to a Renesas compatible list
> +        # compatibles not related to Renesas. The select pattern for this
> +        # schema hits all compatibles that have at lest one Renesas compatible
> +        # and try to validate all values in that compatible array, allow all
> +        # that don't match the schema select pattern. For example,
> +        #
> +        #   compatible = "renesas,r9a07g044-mali", "arm,mali-bifrost";
> +        - pattern: "^(?!renesas,.+-.+).+$"
> +
> +additionalProperties: true
> -- 
> 2.43.0
>
Niklas Söderlund Feb. 13, 2024, 10:42 p.m. UTC | #3 
Hi Rob,

On 2024-02-13 16:37:38 -0600, Rob Herring wrote:
> On Tue, Feb 13, 2024 at 08:23:40PM +0100, Niklas Söderlund wrote:
> > Compatibles can come in two formats. Either "vendor,ip-soc" or
> > "vendor,soc-ip". Add a DT schema file documenting Renesas preferred
> > policy and enforcing it for all new compatibles, except few existing
> > patterns.
> > 
> > Suggested-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> > Signed-off-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
> > ---
> > * Changes since v2
> > - Improve the select so it matches on any compatible containing a
> >   component specific Renesas value.
> > - Make the regexps more compact.
> > - Define MaxItems to allow the increased selection to work.
> > - Add rmobile and shmobile prefixes.
> > - I did not take Rob's ack from v2 as the schema changed a lot after
> >   Geerts review.
> > 
> > * Changes since v1
> > - Split the "SoC agnostic compatibles" section into two to make it's
> >   intent clearer.
> > - Improved the documentation for each group of compatibles.
> > - Reduced the number of regexp to create a larger target area. As
> >   suggested by Krzysztof the goal is not to validate each SoC name but
> >   check for the correct order of SoC-IP.
> > 
> > * Changes since RFC
> > - Moved to Documentation/devicetree/bindings/soc/renesas.
> > - Changed the pattern in the initial select to match on .*-.*.
> > - Added a lot of missing compatible values.
> > ---
> >  .../bindings/soc/renesas/renesas-soc.yaml     | 72 +++++++++++++++++++
> >  1 file changed, 72 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
> > new file mode 100644
> > index 000000000000..57c11022d793
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
> > @@ -0,0 +1,72 @@
> > +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/soc/renesas/renesas-soc.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Renesas SoC compatibles naming convention
> > +
> > +maintainers:
> > +  - Geert Uytterhoeven <geert+renesas@glider.be>
> > +  - Niklas Söderlund <niklas.soderlund@ragnatech.se>
> > +
> > +description: |
> > +  Guidelines for new compatibles for SoC blocks/components.
> > +  When adding new compatibles in new bindings, use the format::
> > +    renesas,SoC-IP
> > +
> > +  For example::
> > +   renesas,r8a77965-csi2
> > +
> > +  When adding new compatibles to existing bindings, use the format in the
> > +  existing binding, even if it contradicts the above.
> > +
> > +select:
> > +  properties:
> > +    compatible:
> > +      contains:
> > +        pattern: "^renesas,.+-.+$"
> > +  required:
> > +    - compatible
> > +
> > +properties:
> > +  compatible:
> > +    maxItems: 4
> 
> 'minItems: 1' should fix the error reported.

Thanks, was just about to send a v4 to fix this mistake.

> 
> 
> > +    items:
> > +      anyOf:
> > +        # Preferred naming style for compatibles of SoC components
> > +        - pattern: "^renesas,(emev2|r(7s|8a|9a)[a-z0-9]+|rcar|rmobile|rz[a-z0-9]*|sh(7[a-z0-9]+)?|mobile)-[a-z0-9-]+$"
> > +        - pattern: "^renesas,(condor|falcon|gr-peach|salvator|sk-rz|smar(c(2)?)?|spider|white-hawk)(.*)?$"
> > +
> > +        # Legacy compatibles
> > +        #
> > +        # New compatibles are not allowed.
> > +        - pattern: "^renesas,(can|cpg|dmac|du|(g)?ether(avb)?|gpio|hscif|(r)?i[i2]c|imr|intc|ipmmu|irqc|jpu|mmcif|msiof|mtu2|pci(e)?|pfc|pwm|[rq]spi|rcar_sound|sata|scif[ab]*|sdhi|thermal|tmu|tpu|usb(2|hs)?|vin|xhci)-[a-z0-9-]+$"
> > +        - pattern: "^renesas,(d|s)?bsc(3)?-(r8a73a4|r8a7740|sh73a0)$"
> > +        - pattern: "^renesas,em-(gio|sti|uart)$"
> > +        - pattern: "^renesas,fsi2-(r8a7740|sh73a0)$"
> > +        - pattern: "^renesas,hspi-r8a777[89]$"
> > +        - pattern: "^renesas,sysc-(r8a73a4|r8a7740|rmobile|sh73a0)$"
> > +        - enum:
> > +            - renesas,imr-lx4
> > +            - renesas,mtu2-r7s72100
> > +
> > +        # None SoC component compatibles
> > +        #
> > +        # Compatibles with the Renesas vendor prefix that do not relate to any SoC
> > +        # component are OK. New compatibles are allowed.
> > +        - enum:
> > +            - renesas,smp-sram
> > +
> > +        # Do not fail compatibles not matching the select pattern
> > +        #
> > +        # Some SoC components in addition to a Renesas compatible list
> > +        # compatibles not related to Renesas. The select pattern for this
> > +        # schema hits all compatibles that have at lest one Renesas compatible
> > +        # and try to validate all values in that compatible array, allow all
> > +        # that don't match the schema select pattern. For example,
> > +        #
> > +        #   compatible = "renesas,r9a07g044-mali", "arm,mali-bifrost";
> > +        - pattern: "^(?!renesas,.+-.+).+$"
> > +
> > +additionalProperties: true
> > -- 
> > 2.43.0
> >
Geert Uytterhoeven Feb. 16, 2024, 2:51 p.m. UTC | #4 
Hi Niklas,

On Tue, Feb 13, 2024 at 8:23 PM Niklas Söderlund
<niklas.soderlund+renesas@ragnatech.se> wrote:
> Compatibles can come in two formats. Either "vendor,ip-soc" or
> "vendor,soc-ip". Add a DT schema file documenting Renesas preferred
> policy and enforcing it for all new compatibles, except few existing
> patterns.
>
> Suggested-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> Signed-off-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
> ---
> * Changes since v2
> - Improve the select so it matches on any compatible containing a
>   component specific Renesas value.
> - Make the regexps more compact.
> - Define MaxItems to allow the increased selection to work.
> - Add rmobile and shmobile prefixes.
> - I did not take Rob's ack from v2 as the schema changed a lot after
>   Geerts review.

Thanks, works better now: "make dtbs_check" flags the addition of
my bogus test properties to DTS.
It doesn't flag my bogus test properties in actual DT bindings, but I guess
that is expected behavior.

Reviewed-by: Geert Uytterhoeven <geert+renesas@glider.be>
i.e. will queue in renesas-devel for v6.9.

Gr{oetje,eeting}s,

                        Geert
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
new file mode 100644
index 000000000000..57c11022d793
--- /dev/null
+++ b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml
@@ -0,0 +1,72 @@ 
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/soc/renesas/renesas-soc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas SoC compatibles naming convention
+
+maintainers:
+  - Geert Uytterhoeven <geert+renesas@glider.be>
+  - Niklas Söderlund <niklas.soderlund@ragnatech.se>
+
+description: |
+  Guidelines for new compatibles for SoC blocks/components.
+  When adding new compatibles in new bindings, use the format::
+    renesas,SoC-IP
+
+  For example::
+   renesas,r8a77965-csi2
+
+  When adding new compatibles to existing bindings, use the format in the
+  existing binding, even if it contradicts the above.
+
+select:
+  properties:
+    compatible:
+      contains:
+        pattern: "^renesas,.+-.+$"
+  required:
+    - compatible
+
+properties:
+  compatible:
+    maxItems: 4
+    items:
+      anyOf:
+        # Preferred naming style for compatibles of SoC components
+        - pattern: "^renesas,(emev2|r(7s|8a|9a)[a-z0-9]+|rcar|rmobile|rz[a-z0-9]*|sh(7[a-z0-9]+)?|mobile)-[a-z0-9-]+$"
+        - pattern: "^renesas,(condor|falcon|gr-peach|salvator|sk-rz|smar(c(2)?)?|spider|white-hawk)(.*)?$"
+
+        # Legacy compatibles
+        #
+        # New compatibles are not allowed.
+        - pattern: "^renesas,(can|cpg|dmac|du|(g)?ether(avb)?|gpio|hscif|(r)?i[i2]c|imr|intc|ipmmu|irqc|jpu|mmcif|msiof|mtu2|pci(e)?|pfc|pwm|[rq]spi|rcar_sound|sata|scif[ab]*|sdhi|thermal|tmu|tpu|usb(2|hs)?|vin|xhci)-[a-z0-9-]+$"
+        - pattern: "^renesas,(d|s)?bsc(3)?-(r8a73a4|r8a7740|sh73a0)$"
+        - pattern: "^renesas,em-(gio|sti|uart)$"
+        - pattern: "^renesas,fsi2-(r8a7740|sh73a0)$"
+        - pattern: "^renesas,hspi-r8a777[89]$"
+        - pattern: "^renesas,sysc-(r8a73a4|r8a7740|rmobile|sh73a0)$"
+        - enum:
+            - renesas,imr-lx4
+            - renesas,mtu2-r7s72100
+
+        # None SoC component compatibles
+        #
+        # Compatibles with the Renesas vendor prefix that do not relate to any SoC
+        # component are OK. New compatibles are allowed.
+        - enum:
+            - renesas,smp-sram
+
+        # Do not fail compatibles not matching the select pattern
+        #
+        # Some SoC components in addition to a Renesas compatible list
+        # compatibles not related to Renesas. The select pattern for this
+        # schema hits all compatibles that have at lest one Renesas compatible
+        # and try to validate all values in that compatible array, allow all
+        # that don't match the schema select pattern. For example,
+        #
+        #   compatible = "renesas,r9a07g044-mali", "arm,mali-bifrost";
+        - pattern: "^(?!renesas,.+-.+).+$"
+
+additionalProperties: true