dt-bindings: interrupt-controller: Convert Atmel AIC to json-schema

Convert the Atmel AIC binding document to DT schema format using
json-schema.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
---
Note: I get the following warnings on latest kernel but not in 6.7.
Should I be worried?

usage: yamllint [-h] [-] [-c CONFIG_FILE | -d CONFIG_DATA] [--list-files] [-f {parsable,standard,colored,github,auto}] [-s] [--no-warnings] [-v] [FILE_OR_DIR [FILE_OR_DIR ...]]
yamllint: error: one of the arguments FILE_OR_DIR - is required

 .../interrupt-controller/atmel,aic.txt        | 43 ---------
 .../interrupt-controller/atmel,aic.yaml       | 88 +++++++++++++++++++
 2 files changed, 88 insertions(+), 43 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt
 create mode 100644 Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml


base-commit: 047371968ffc470769f541d6933e262dc7085456

On Thu, 08 Feb 2024 14:50:15 +0530, Dharma Balasubiramani wrote:
> Convert the Atmel AIC binding document to DT schema format using
> json-schema.
> 
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> ---
> Note: I get the following warnings on latest kernel but not in 6.7.
> Should I be worried?
> 
> usage: yamllint [-h] [-] [-c CONFIG_FILE | -d CONFIG_DATA] [--list-files] [-f {parsable,standard,colored,github,auto}] [-s] [--no-warnings] [-v] [FILE_OR_DIR [FILE_OR_DIR ...]]
> yamllint: error: one of the arguments FILE_OR_DIR - is required
> 
>  .../interrupt-controller/atmel,aic.txt        | 43 ---------
>  .../interrupt-controller/atmel,aic.yaml       | 88 +++++++++++++++++++
>  2 files changed, 88 insertions(+), 43 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/interrupt-controller/atmel,aic.txt
>  create mode 100644 Documentation/devicetree/bindings/interrupt-controller/atmel,aic.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:
Documentation/devicetree/bindings/interrupt-controller/atmel,aic.example.dtb: /example-1/dma-controller@ffffec00: failed to match any schema with compatible: ['atmel,at91sam9g45-dma']

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20240208092015.263210-1-dharma.b@microchip.com

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.

Hey Dharma,

On Thu, Feb 08, 2024 at 03:51:31PM +0000, Rob Herring wrote:
> 
> On Thu, 08 Feb 2024 14:50:15 +0530, Dharma Balasubiramani wrote:
> > Convert the Atmel AIC binding document to DT schema format using
> > json-schema.
> > 
> > Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> > ---
> > Note: I get the following warnings on latest kernel but not in 6.7.
> > Should I be worried?
> > usage: yamllint [-h] [-] [-c CONFIG_FILE | -d CONFIG_DATA] [--list-files] [-f {parsable,standard,colored,github,auto}] [-s] [--no-warnings] [-v] [FILE_OR_DIR [FILE_OR_DIR ...]]
> > yamllint: error: one of the arguments FILE_OR_DIR - is required

Hard to say, how were you envoking the command? There were some issues
recently with dt_binding_check, but I thought those had been fixed.

> dtschema/dtc warnings/errors:
> Documentation/devicetree/bindings/interrupt-controller/atmel,aic.example.dtb: /example-1/dma-controller@ffffec00: failed to match any schema with compatible: ['atmel,at91sam9g45-dma']

But you didn't see this warning?
I think you can resolve it by just dropping the "user" example from the
binding entirely. I don't think it adds anything at all.

Cheers,
Conor.

Hey Dharma,

Overall this looks alright, but I have a few comments for you.

On Thu, Feb 08, 2024 at 02:50:15PM +0530, Dharma Balasubiramani wrote:

> diff --git a/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml
> new file mode 100644
> index 000000000000..396eac53da3a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml
> @@ -0,0 +1,88 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/interrupt-controller/atmel,aic.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Advanced Interrupt Controller (AIC)
> +
> +maintainers:
> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
> +  - Dharma balasubiramani <dharma.b@microchip.com>
> +
> +description: |

The chomping operator, |, is not needed here as you have no formatting
to preserve.

> +  The Advanced Interrupt Controller (AIC) is an 8-level priority, individually
> +  maskable, vectored interrupt controller providing handling of up to one
> +  hundred and twenty-eight interrupt sources.

> It is designed to substantially
> +  reduce the software and real-time overhead in handling internal and external
> +  interrupts.

This reeks of a marketing statement and should be removed IMO.

> +allOf:
> +  - $ref: /schemas/interrupt-controller.yaml#
> +
> +properties:
> +  compatible:
> +    enum:
> +      - atmel,at91rm9200-aic
> +      - atmel,sama5d2-aic
> +      - atmel,sama5d3-aic
> +      - atmel,sama5d4-aic
> +      - microchip,sam9x60-aic
> +
> +  interrupt-controller: true
> +
> +  "#interrupt-cells":
> +    const: 3
> +    description: |
> +      The 1st cell is the IRQ number (Peripheral IDentifier on datasheet).
> +      The 2nd cell specifies flags:
> +        bits[3:0] trigger type and level flags:
> +          1 = low-to-high edge triggered.
> +          2 = high-to-low edge triggered.
> +          4 = active high level-sensitive.
> +          8 = active low level-sensitive.
> +        Valid combinations: 1, 2, 3, 4, 8.

Shame that these are not aligned with the IRQ_TYPE defines :(

> +        Default for internal sources: 4 (active high).
> +      The 3rd cell specifies irq priority from 0 (lowest) to 7 (highest).
> +
> +  interrupts:

> +    description: Interrupt source of the parent interrupt controller.

Drop the description, it's obvious.

> +    maxItems: 1
> +
> +  reg:

A nit, but I would put reg after compatible.

> +    description: Specifies base physical address(s) and size of the AIC registers.

Same here.

> +    maxItems: 1
> +
> +  atmel,external-irqs:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    description: u32 array of external irqs.
> +
> +required:
> +  - compatible
> +  - interrupt-controller
> +  - "#interrupt-cells"
> +  - reg

A nit, but I would put reg after compatible

> +  - atmel,external-irqs
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    /* AIC */

Drop the comment, its obvious.

> +    aic: interrupt-controller@fffff000 {

The node name here is not used, drop it.

> +      compatible = "atmel,at91rm9200-aic";
> +      interrupt-controller;
> +      #interrupt-cells = <3>;
> +      reg = <0xfffff000 0x200>;
> +      atmel,external-irqs = <31>;
> +    };
> +

> +  - |
> +    /* An interrupt generating device that is wired to an AIC. */
> +    dma: dma-controller@ffffec00 {
> +      compatible = "atmel,at91sam9g45-dma";
> +      #dma-cells = <2>;
> +      reg = <0xffffec00 0x200>;
> +      interrupts = <21 4 5>;
> +    };

And delete this whole example :)

Cheers,
Conor.

Hi Conor,

On 09/02/24 12:19 am, Conor Dooley wrote:
> Hey Dharma,
> 
> On Thu, Feb 08, 2024 at 03:51:31PM +0000, Rob Herring wrote:
>> On Thu, 08 Feb 2024 14:50:15 +0530, Dharma Balasubiramani wrote:
>>> Convert the Atmel AIC binding document to DT schema format using
>>> json-schema.
>>>
>>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>>> ---
>>> Note: I get the following warnings on latest kernel but not in 6.7.
>>> Should I be worried?
>>> usage: yamllint [-h] [-] [-c CONFIG_FILE | -d CONFIG_DATA] [--list-files] [-f {parsable,standard,colored,github,auto}] [-s] [--no-warnings] [-v] [FILE_OR_DIR [FILE_OR_DIR ...]]
>>> yamllint: error: one of the arguments FILE_OR_DIR - is required
> Hard to say, how were you envoking the command? There were some issues
> recently with dt_binding_check, but I thought those had been fixed.

I use this command to validate

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- dt_binding_check 
DT_SCHEMA_FILES=Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml

and also dtbs_check.

version = yamllint 1.32.0
> 
>> dtschema/dtc warnings/errors:
>> Documentation/devicetree/bindings/interrupt-controller/atmel,aic.example.dtb: /example-1/dma-controller@ffffec00: failed to match any schema with compatible: ['atmel,at91sam9g45-dma']
> But you didn't see this warning?

No I didn't see this warning when applied on tag:6.7. Don't know why.

> I think you can resolve it by just dropping the "user" example from the
> binding entirely. I don't think it adds anything at all.

I intentionally checked the generated example dts file and found that 
both the examples look correct.

     example-0 {
         #address-cells = <1>;
         #size-cells = <1>;

         /* AIC */
         aic: interrupt-controller@fffff000 {
           compatible = "atmel,at91rm9200-aic";
           interrupt-controller;
           #interrupt-cells = <3>;
           reg = <0xfffff000 0x200>;
           atmel,external-irqs = <31>;
         };

     };

     example-1 {
         #address-cells = <1>;
         #size-cells = <1>;

         interrupt-parent = <&fake_intc1>;
         fake_intc1: fake-interrupt-controller {
             interrupt-controller;
             #interrupt-cells = < 3 >;
         };

         /* An interrupt generating device that is wired to an AIC. */
         dma: dma-controller@ffffec00 {
           compatible = "atmel,at91sam9g45-dma";
           #dma-cells = <2>;
           reg = <0xffffec00 0x200>;
           interrupts = <21 4 5>;
         };

     };

> 
> Cheers,
> Conor.

Please correct me if I'm doing something wrong here.

On Fri, Feb 09, 2024 at 06:31:15AM +0000, Dharma.B@microchip.com wrote:
> Hi Conor,
> 
> On 09/02/24 12:19 am, Conor Dooley wrote:
> > Hey Dharma,
> > 
> > On Thu, Feb 08, 2024 at 03:51:31PM +0000, Rob Herring wrote:
> >> On Thu, 08 Feb 2024 14:50:15 +0530, Dharma Balasubiramani wrote:
> >>> Convert the Atmel AIC binding document to DT schema format using
> >>> json-schema.
> >>>
> >>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
> >>> ---
> >>> Note: I get the following warnings on latest kernel but not in 6.7.
> >>> Should I be worried?
> >>> usage: yamllint [-h] [-] [-c CONFIG_FILE | -d CONFIG_DATA] [--list-files] [-f {parsable,standard,colored,github,auto}] [-s] [--no-warnings] [-v] [FILE_OR_DIR [FILE_OR_DIR ...]]
> >>> yamllint: error: one of the arguments FILE_OR_DIR - is required
> > Hard to say, how were you envoking the command? There were some issues
> > recently with dt_binding_check, but I thought those had been fixed.
> 
> I use this command to validate
> 
> make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- dt_binding_check 
> DT_SCHEMA_FILES=Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml

Humm, not sure. Will have to investigate.


> and also dtbs_check.
> 
> version = yamllint 1.32.0
> > 
> >> dtschema/dtc warnings/errors:
> >> Documentation/devicetree/bindings/interrupt-controller/atmel,aic.example.dtb: /example-1/dma-controller@ffffec00: failed to match any schema with compatible: ['atmel,at91sam9g45-dma']
> > But you didn't see this warning?
> 
> No I didn't see this warning when applied on tag:6.7. Don't know why.

That's because it just got enabled by default.

> 
> > I think you can resolve it by just dropping the "user" example from the
> > binding entirely. I don't think it adds anything at all.
> 
> I intentionally checked the generated example dts file and found that 
> both the examples look correct.

Maybe so, but how do we know with no schema? Your choices are drop from 
the example or add a schema for the DMA controller.

Rob

Hi Rob,

On 09/02/24 2:40 pm, Rob Herring wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> On Fri, Feb 09, 2024 at 06:31:15AM +0000, Dharma.B@microchip.com wrote:
>> Hi Conor,
>>
>> On 09/02/24 12:19 am, Conor Dooley wrote:
>>> Hey Dharma,
>>>
>>> On Thu, Feb 08, 2024 at 03:51:31PM +0000, Rob Herring wrote:
>>>> On Thu, 08 Feb 2024 14:50:15 +0530, Dharma Balasubiramani wrote:
>>>>> Convert the Atmel AIC binding document to DT schema format using
>>>>> json-schema.
>>>>>
>>>>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>>>>> ---
>>>>> Note: I get the following warnings on latest kernel but not in 6.7.
>>>>> Should I be worried?
>>>>> usage: yamllint [-h] [-] [-c CONFIG_FILE | -d CONFIG_DATA] [--list-files] [-f {parsable,standard,colored,github,auto}] [-s] [--no-warnings] [-v] [FILE_OR_DIR [FILE_OR_DIR ...]]
>>>>> yamllint: error: one of the arguments FILE_OR_DIR - is required
>>> Hard to say, how were you envoking the command? There were some issues
>>> recently with dt_binding_check, but I thought those had been fixed.
>>
>> I use this command to validate
>>
>> make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- dt_binding_check
>> DT_SCHEMA_FILES=Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml
> 
> Humm, not sure. Will have to investigate.
> 
> 
>> and also dtbs_check.
>>
>> version = yamllint 1.32.0
>>>
>>>> dtschema/dtc warnings/errors:
>>>> Documentation/devicetree/bindings/interrupt-controller/atmel,aic.example.dtb: /example-1/dma-controller@ffffec00: failed to match any schema with compatible: ['atmel,at91sam9g45-dma']
>>> But you didn't see this warning?
>>
>> No I didn't see this warning when applied on tag:6.7. Don't know why.
> 
> That's because it just got enabled by default.
> 
>>
>>> I think you can resolve it by just dropping the "user" example from the
>>> binding entirely. I don't think it adds anything at all.
>>
>> I intentionally checked the generated example dts file and found that
>> both the examples look correct.
> 
> Maybe so, but how do we know with no schema? Your choices are drop from
> the example or add a schema for the DMA controller.

Currently, my colleague is actively working on adding the schema for 
DMA, anyway I will drop the dma example in the interrupt controller for now.

Thanks.
> 
> Rob

On Thu, Feb 08, 2024 at 11:10:32PM +0000, Conor Dooley wrote:
> On Thu, Feb 08, 2024 at 02:50:15PM +0530, Dharma Balasubiramani wrote:
> > +  "#interrupt-cells":
> > +    const: 3
> > +    description: |
> > +      The 1st cell is the IRQ number (Peripheral IDentifier on datasheet).
> > +      The 2nd cell specifies flags:
> > +        bits[3:0] trigger type and level flags:
> > +          1 = low-to-high edge triggered.
> > +          2 = high-to-low edge triggered.
> > +          4 = active high level-sensitive.
> > +          8 = active low level-sensitive.
> > +        Valid combinations: 1, 2, 3, 4, 8.
> 
> Shame that these are not aligned with the IRQ_TYPE defines :(

Dharma pointed out to me that these are the same and I just looked at
the wrong header file.

Hi Conor,

On 09/02/24 4:40 am, Conor Dooley wrote:
> Hey Dharma,
> 
> Overall this looks alright, but I have a few comments for you.
> 
> On Thu, Feb 08, 2024 at 02:50:15PM +0530, Dharma Balasubiramani wrote:
> 
>> diff --git a/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml
>> new file mode 100644
>> index 000000000000..396eac53da3a
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/interrupt-controller/atmel,aic.yaml
>> @@ -0,0 +1,88 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id:http://devicetree.org/schemas/interrupt-controller/atmel,aic.yaml#
>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Advanced Interrupt Controller (AIC)
>> +
>> +maintainers:
>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
>> +  - Dharma balasubiramani<dharma.b@microchip.com>
>> +
>> +description: |
> The chomping operator, |, is not needed here as you have no formatting
> to preserve.

I missed it again, I will fix it.
> 
>> +  The Advanced Interrupt Controller (AIC) is an 8-level priority, individually
>> +  maskable, vectored interrupt controller providing handling of up to one
>> +  hundred and twenty-eight interrupt sources.
>> It is designed to substantially
>> +  reduce the software and real-time overhead in handling internal and external
>> +  interrupts.
> This reeks of a marketing statement and should be removed IMO.

Noted. I will remove it.
> 
>> +allOf:
>> +  - $ref: /schemas/interrupt-controller.yaml#
>> +
>> +properties:
>> +  compatible:
>> +    enum:
>> +      - atmel,at91rm9200-aic
>> +      - atmel,sama5d2-aic
>> +      - atmel,sama5d3-aic
>> +      - atmel,sama5d4-aic
>> +      - microchip,sam9x60-aic
>> +
>> +  interrupt-controller: true
>> +
>> +  "#interrupt-cells":
>> +    const: 3
>> +    description: |
>> +      The 1st cell is the IRQ number (Peripheral IDentifier on datasheet).
>> +      The 2nd cell specifies flags:
>> +        bits[3:0] trigger type and level flags:
>> +          1 = low-to-high edge triggered.
>> +          2 = high-to-low edge triggered.
>> +          4 = active high level-sensitive.
>> +          8 = active low level-sensitive.
>> +        Valid combinations: 1, 2, 3, 4, 8.
> Shame that these are not aligned with the IRQ_TYPE defines 🙁
> 
>> +        Default for internal sources: 4 (active high).
>> +      The 3rd cell specifies irq priority from 0 (lowest) to 7 (highest).
>> +
>> +  interrupts:
>> +    description: Interrupt source of the parent interrupt controller.
> Drop the description, it's obvious.

Sure.
> 
>> +    maxItems: 1
>> +
>> +  reg:
> A nit, but I would put reg after compatible.

Sure.
> 
>> +    description: Specifies base physical address(s) and size of the AIC registers.
> Same here.

Sure, I will drop the description.
> 
>> +    maxItems: 1
>> +
>> +  atmel,external-irqs:
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    description: u32 array of external irqs.
>> +
>> +required:
>> +  - compatible
>> +  - interrupt-controller
>> +  - "#interrupt-cells"
>> +  - reg
> A nit, but I would put reg after compatible

Sure.
> 
>> +  - atmel,external-irqs
>> +
>> +unevaluatedProperties: false
>> +
>> +examples:
>> +  - |
>> +    /* AIC */
> Drop the comment, its obvious.

Sure, I will drop it
> 
>> +    aic: interrupt-controller@fffff000 {
> The node name here is not used, drop it.

Sure, I will drop the aic and use just interrupt-controller@fffff000.
> 
>> +      compatible = "atmel,at91rm9200-aic";
>> +      interrupt-controller;
>> +      #interrupt-cells = <3>;
>> +      reg = <0xfffff000 0x200>;
>> +      atmel,external-irqs = <31>;
>> +    };
>> +
>> +  - |
>> +    /* An interrupt generating device that is wired to an AIC. */
>> +    dma: dma-controller@ffffec00 {
>> +      compatible = "atmel,at91sam9g45-dma";
>> +      #dma-cells = <2>;
>> +      reg = <0xffffec00 0x200>;
>> +      interrupts = <21 4 5>;
>> +    };
> And delete this whole example 🙂

Sure, I will delete this example.
> 
> Cheers,
> Conor.
>