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

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>
---
Hello,

I have mixed up the order of soc and ip a few times. The last time I did 
Krzysztof suggested a schema could help catch this, and this is my  
attempt to create one.

One thing to note is that the select clause matches on all renesas 
related bindings, including ones that are SoC agnostic and a few that 
are Renesas IP that are not related to a SoC e.g. a Renesas regulator.

For this reason these two classes of compatibles have been added to this 
schema. An alternative solution would be to change the select clause to 
"^renesas,.+-.+$" and drop these two classes from the schema.

I have tested this schema with all DTBs built for ARM using the in tree 
shmobile_defconfig and ARM64 using the renesas_defconfig found in 
Geert's renesas-drivers tree [1].

1.  https://git.kernel.org/pub/scm/linux/kernel/git/geert/renesas-drivers.git

---
 .../devicetree/bindings/arm/renesas-soc.yaml  | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/renesas-soc.yaml

Hi Geert,

Thanks for your feedback.

On 2023-11-24 09:02:28 +0100, Geert Uytterhoeven wrote:
> Hi Niklas,
> 
> On Thu, Nov 23, 2023 at 8:07 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>
> 
> Thanks for your patch!
> 
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/arm/renesas-soc.yaml
> 
> s/arm/soc/

I opted to put this in soc/renesas/renesas-soc.yaml.

> 
> > @@ -0,0 +1,85 @@
> > +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/arm/renesas-soc.yaml#
> 
> s/arm/soc/
> 
> > +$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>
> 
> +renesas?

Nope, I don't record the +renesas part in files. I fear the day Gmail
drops support for the feature or I need to switch mail provider.

> 
> > +
> > +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:
> > +      pattern: "^renesas,.*$"
> > +  required:
> > +    - compatible
> > +
> > +properties:
> > +  compatible:
> > +    oneOf:
> > +      # Preferred naming style for compatibles of SoC components:
> > +      - pattern: "^renesas,emev2-[a-z0-9-]+$"
> > +      - pattern: "^renesas,r7s[0-9]+-[a-z0-9-]+$"
> > +      - pattern: "^renesas,r8a[a-z0-9]+-[a-z0-9-]+$"
> > +      - pattern: "^renesas,r9a[0-9]+g[0-9]+-[a-z0-9-]+$"
> 
> Missing renesas,rcar-* families.
> 
> > +      - pattern: "^renesas,rzn1-[a-z0-9-]+$"
> 
> Missing renesas,rzg2l-* (there may be more).

There where a few more, added.

> 
> > +      - pattern: "^renesas,rzv2m-[a-z0-9-]+$"
> > +      - pattern: "^renesas,sh73a0-[a-z0-9-]+$"
> 
> We'll get more sh7* soon ;-)

I adapted the regexp to prepare for this.


> 
> > +
> > +      # SoC agnostic compatibles - new compatibles are OK:
> > +      - enum:
> > +          - renesas,bsid
> > +          - renesas,fcpf
> > +          - renesas,fcpv
> > +          - renesas,fdp1
> > +          - renesas,prr
> > +          - renesas,smp-sram
> 
> Missing renesas,tmu (there may be more).

As discussed offline I will change the pattern in the initial select to 
only match on .*-.* so most of these will be gone.

> 
> > +          - renesas,vsp1
> > +          - renesas,vsp2
> > +
> > +      # Legacy namings - variations of existing patterns/compatibles are OK,
> > +      # but do not add completely new entries to these:
> > +      - pattern: "^renesas,du-[a-z0-9]+$"
> > +      - pattern: "^renesas,ether-[a-z0-9]+$"
> > +      - pattern: "^renesas,gether-[a-z0-9]+$"
> > +      - pattern: "^renesas,ipmmu-[a-z0-9]+$"
> > +      - pattern: "^renesas,pfc-[a-z0-9]+$"
> > +      - pattern: "^renesas,sata-[a-z0-9]+$"
> > +      - pattern: "^renesas,scif-[a-z0-9]+$"
> > +      - pattern: "^renesas,sdhi-[a-z0-9]+$"
> > +      - pattern: "^renesas,thermal-[a-z0-9]+$"
> > +      - pattern: "^renesas,usb2-phy-[a-z0-9]+$"
> > +      - pattern: "^renesas,vin-[a-z0-9]+$"
> 
> This list also looks incomplete, e.g. hscif and scif[ab] are missing.
> I guess you created it based on the error output of "make dtbs_check",
> which ignores all nodes that are disabled?  Although that can't explain
> everything, as some boards use scifa for the console...

Not sure how my tests missed so much. For next version I have extracted 
all compatible variables and created a test dts file with every 
available value. There where quiet a lot missing in this RFC.

> 
> Gr{oetje,eeting}s,
> 
>                         Geert
> 
> -- 
> Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
> 
> In personal conversations with technical people, I call myself a hacker. But
> when I'm talking to journalists I just say "programmer" or something like that.
>                                 -- Linus Torvalds