Re: [PATCH v2 2/6] dt-bindings: interrupt-controller: Convert mti,gic to DT schema

[Sergey Semin]

On Tue, Mar 31, 2020 at 03:02:48PM -0600, Rob Herring wrote:
> On Tue, Mar 24, 2020 at 08:43:21PM +0300, Sergey.Semin@xxxxxxxxxxxxxxxxxxxx wrote:
> > From: Serge Semin <Sergey.Semin@xxxxxxxxxxxxxxxxxxxx>
> > 
> > Modern device tree bindings are supposed to be created as YAML-files
> > in accordance with DT schema. This commit replaces MIPS GIC legacy bare
> > text binding with YAML file. As before the binding file states that the
> > corresponding dts node is supposed to be compatible with MIPS Global
> > Interrupt Controller indicated by the "mti,gic" compatible string and
> > to provide a mandatory interrupt-controller and '#interrupt-cells'
> > properties. There might be optional registers memory range,
> > "mti,reserved-cpu-vectors" and "mti,reserved-ipi-vectors" properties
> > specified.
> > 
> > MIPS GIC also includes a free-running global timer, per-CPU count/compare
> > timers, and a watchdog. Since currently the GIC Timer is only supported the
> > DT schema expects an IRQ and clock-phandler charged timer sub-node with
> > "mti,mips-gic-timer" compatible string.
> > 
> > Signed-off-by: Serge Semin <Sergey.Semin@xxxxxxxxxxxxxxxxxxxx>
> > Cc: Alexey Malahov <Alexey.Malahov@xxxxxxxxxxxxxxxxxxxx>
> > Cc: Thomas Bogendoerfer <tsbogend@xxxxxxxxxxxxxxxx>
> > Cc: Paul Burton <paulburton@xxxxxxxxxx>
> > Cc: Ralf Baechle <ralf@xxxxxxxxxxxxxx>
> > Cc: Alessandro Zummo <a.zummo@xxxxxxxxxxxx>
> > Cc: Alexandre Belloni <alexandre.belloni@xxxxxxxxxxx>
> > Cc: Daniel Lezcano <daniel.lezcano@xxxxxxxxxx>
> > Cc: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
> > Cc: Arnd Bergmann <arnd@xxxxxxxx>
> > Cc: Andy Shevchenko <andy.shevchenko@xxxxxxxxx>
> > Cc: Rob Herring <robh+dt@xxxxxxxxxx>
> > Cc: Mark Rutland <mark.rutland@xxxxxxx>
> > Cc: devicetree@xxxxxxxxxxxxxxx
> > Cc: linux-rtc@xxxxxxxxxxxxxxx
> > 
> > ---
> > 
> > I don't really know who is the corresponding driver maintainer, so I
> > added to the maintainers schema Paul since he used to be looking for the
> > MIPS arch and Thomas looking after it now. Any idea what email should be
> > specified there instead?
> > 
> > Similarly to the previous patch the "oneOf: - required: ..." pattern isn't
> > working here. Supposedly due to the script' dtschema/lib.py
> > interrupts/interrupts-extended fixup.
> > ---
> >  .../interrupt-controller/mips-gic.txt         |  67 --------
> >  .../interrupt-controller/mti,gic.yaml         | 152 ++++++++++++++++++
> >  2 files changed, 152 insertions(+), 67 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt
> >  create mode 100644 Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt
> > deleted file mode 100644
> > index 173595305e26..000000000000
> > --- a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt
> > +++ /dev/null
> > @@ -1,67 +0,0 @@
> > -MIPS Global Interrupt Controller (GIC)
> > -
> > -The MIPS GIC routes external interrupts to individual VPEs and IRQ pins.
> > -It also supports local (per-processor) interrupts and software-generated
> > -interrupts which can be used as IPIs.  The GIC also includes a free-running
> > -global timer, per-CPU count/compare timers, and a watchdog.
> > -
> > -Required properties:
> > -- compatible : Should be "mti,gic".
> > -- interrupt-controller : Identifies the node as an interrupt controller
> > -- #interrupt-cells : Specifies the number of cells needed to encode an
> > -  interrupt specifier.  Should be 3.
> > -  - The first cell is the type of interrupt, local or shared.
> > -    See <include/dt-bindings/interrupt-controller/mips-gic.h>.
> > -  - The second cell is the GIC interrupt number.
> > -  - The third cell encodes the interrupt flags.
> > -    See <include/dt-bindings/interrupt-controller/irq.h> for a list of valid
> > -    flags.
> > -
> > -Optional properties:
> > -- reg : Base address and length of the GIC registers.  If not present,
> > -  the base address reported by the hardware GCR_GIC_BASE will be used.
> > -- mti,reserved-cpu-vectors : Specifies the list of CPU interrupt vectors
> > -  to which the GIC may not route interrupts.  Valid values are 2 - 7.
> > -  This property is ignored if the CPU is started in EIC mode.
> > -- mti,reserved-ipi-vectors : Specifies the range of GIC interrupts that are
> > -  reserved for IPIs.
> > -  It accepts 2 values, the 1st is the starting interrupt and the 2nd is the size
> > -  of the reserved range.
> > -  If not specified, the driver will allocate the last 2 * number of VPEs in the
> > -  system.
> > -
> > -Required properties for timer sub-node:
> > -- compatible : Should be "mti,gic-timer".
> > -- interrupts : Interrupt for the GIC local timer.
> > -
> > -Optional properties for timer sub-node:
> > -- clocks : GIC timer operating clock.
> > -- clock-frequency : Clock frequency at which the GIC timers operate.
> > -
> > -Note that one of clocks or clock-frequency must be specified.
> > -
> > -Example:
> > -
> > -	gic: interrupt-controller@1bdc0000 {
> > -		compatible = "mti,gic";
> > -		reg = <0x1bdc0000 0x20000>;
> > -
> > -		interrupt-controller;
> > -		#interrupt-cells = <3>;
> > -
> > -		mti,reserved-cpu-vectors = <7>;
> > -		mti,reserved-ipi-vectors = <40 8>;
> > -
> > -		timer {
> > -			compatible = "mti,gic-timer";
> > -			interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>;
> > -			clock-frequency = <50000000>;
> > -		};
> > -	};
> > -
> > -	uart@18101400 {
> > -		...
> > -		interrupt-parent = <&gic>;
> > -		interrupts = <GIC_SHARED 24 IRQ_TYPE_LEVEL_HIGH>;
> > -		...
> > -	};
> > diff --git a/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml b/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml
> > new file mode 100644
> > index 000000000000..1e47c0cdc231
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/interrupt-controller/mti,gic.yaml
> > @@ -0,0 +1,152 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> 
> Do you have rights to add BSD?
> 

My manager said we can submitted the DT schema bindings under both GPL and
BSD licenses. Though I don't know what license was of the legacy binding file.

BTW Rob, you ask about the license very often whether I set pure GPL-2.0
or dual-license header. Just wondering is it some kind of protocol to make
sure a submitter has got proper rights to submit the binding?

> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/interrupt-controller/mti,gic.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: MIPS Global Interrupt Controller
> > +
> > +maintainers:
> > +  - Paul Burton <paulburton@xxxxxxxxxx>
> > +  - Thomas Bogendoerfer <tsbogend@xxxxxxxxxxxxxxxx>
> > +
> > +description: |
> > +  The MIPS GIC routes external interrupts to individual VPEs and IRQ pins.
> > +  It also supports local (per-processor) interrupts and software-generated
> > +  interrupts which can be used as IPIs. The GIC also includes a free-running
> > +  global timer, per-CPU count/compare timers, and a watchdog.
> > +
> > +allOf:
> > +  - $ref: /schemas/interrupt-controller.yaml#
> 
> Drop this.
> 

Ok.

> > +
> > +properties:
> > +  compatible:
> > +    const: mti,gic
> > +
> > +  "#interrupt-cells":
> > +    const: 3
> > +    description: |
> > +      The 1st cell is the type of interrupt: local or shared defined in the
> > +      file 'dt-bindings/interrupt-controller/mips-gic.h'. The 2nd cell is the
> > +      GIC interrupt number. The 3d cell encodes the interrupt flags setting up
> > +      the IRQ trigger modes, which are defined in the file
> > +      'dt-bindings/interrupt-controller/irq.h'.
> > +
> > +  reg:
> > +    description: |
> > +      Base address and length of the GIC registers space. If not present,
> > +      the base address reported by the hardware GCR_GIC_BASE will be used.
> > +    maxItems: 1
> > +
> > +  interrupt-controller: true
> > +
> > +  mti,reserved-cpu-vectors:
> > +    description: |
> > +      Specifies the list of CPU interrupt vectors to which the GIC may not
> > +      route interrupts. This property is ignored if the CPU is started in EIC
> > +      mode.
> > +    allOf:
> > +      - $ref: /schemas/types.yaml#definitions/uint32-array
> > +      - minItems: 1
> > +        maxItems: 6
> > +        uniqueItems: true
> > +        items:
> > +          minimum: 2
> > +          maximum: 7
> > +
> > +  mti,reserved-ipi-vectors:
> > +    description: |
> > +      Specifies the range of GIC interrupts that are reserved for IPIs.
> > +      It accepts two values: the 1st is the starting interrupt and the 2nd is
> > +      the size of the reserved range. If not specified, the driver will
> > +      allocate the last (2 * number of VPEs in the system).
> > +    allOf:
> > +      - $ref: /schemas/types.yaml#definitions/uint32-array
> > +      - items:
> > +          - minimum: 0
> > +            maximum: 254
> > +          - minimum: 2
> > +            maximum: 254
> > +
> > +patternProperties:
> > +  "^timer(@[0-9a-f]+)?$":
> 
> If you have an unit-address, then there should be a 'reg' property.
> 
> Seems like this can be just 'timer'?
> 

Ok. reg property isn't supported by the timer sub-node. So I'll make it to
be just "timer" node with no unit-address number.

-Sergey

> > +    type: object
> > +    description: |
> > +      MIPS GIC includes a free-running global timer, per-CPU count/compare
> > +      timers, and a watchdog. Currently only the GIC Timer is supported.
> > +    properties:
> > +      compatible:
> > +        const: mti,gic-timer
> > +
> > +      interrupts:
> > +        description: |
> > +          Interrupt for the GIC local timer, so normally it's suppose to be of
> > +          <GIC_LOCAL X IRQ_TYPE_NONE> format.
> > +        maxItems: 1
> > +
> > +      clocks:
> > +        maxItems: 1
> > +
> > +      clock-frequency: true
> > +
> > +    required:
> > +      - compatible
> > +      - interrupts
> > +
> > +    oneOf:
> > +      - required:
> > +          - clocks
> > +      - required:
> > +          - clock-frequency
> > +
> > +    additionalProperties: false
> > +
> > +unevaluatedProperties: false
> > +
> > +required:
> > +  - compatible
> > +  - "#interrupt-cells"
> > +  - interrupt-controller
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/mips-gic.h>
> > +    #include <dt-bindings/interrupt-controller/irq.h>
> > +
> > +    interrupt-controller@1bdc0000 {
> > +      compatible = "mti,gic";
> > +      reg = <0x1bdc0000 0x20000>;
> > +      interrupt-controller;
> > +      #interrupt-cells = <3>;
> > +      mti,reserved-cpu-vectors = <7>;
> > +      mti,reserved-ipi-vectors = <40 8>;
> > +
> > +      timer {
> > +        compatible = "mti,gic-timer";
> > +        interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>;
> > +        clock-frequency = <50000000>;
> > +      };
> > +    };
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/mips-gic.h>
> > +    #include <dt-bindings/interrupt-controller/irq.h>
> > +
> > +    interrupt-controller@1bdc0000 {
> > +      compatible = "mti,gic";
> > +      reg = <0x1bdc0000 0x20000>;
> > +      interrupt-controller;
> > +      #interrupt-cells = <3>;
> > +
> > +      timer {
> > +        compatible = "mti,gic-timer";
> > +        interrupts = <GIC_LOCAL 1 IRQ_TYPE_NONE>;
> > +        clocks = <&cpu_pll>;
> > +      };
> > +    };
> > +  - |
> > +    interrupt-controller {
> > +      compatible = "mti,gic";
> > +      interrupt-controller;
> > +      #interrupt-cells = <3>;
> > +    };
> > +...
> > -- 
> > 2.25.1
> >