Documentation/devicetree/bindings/interrupt-controller/arm,gic-v5.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/interrupt-controller/arm,gic-v5.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: ARM Generic Interrupt Controller, version 5

maintainers:
  - Lorenzo Pieralisi <lpieralisi@kernel.org>
  - Marc Zyngier <maz@kernel.org>

description: |
  The GICv5 architecture defines the guidelines to implement GICv5
  compliant interrupt controllers for AArch64 systems.

  The GICv5 specification can be found at
  https://developer.arm.com/documentation/aes0070

  The GICv5 architecture is composed of multiple components:
    - one or more IRS (Interrupt Routing Service)
    - zero or more ITS (Interrupt Translation Service)

  The architecture defines:
    - PE-Private Peripheral Interrupts (PPI)
    - Shared Peripheral Interrupts (SPI)
    - Logical Peripheral Interrupts (LPI)

allOf:
  - $ref: /schemas/interrupt-controller.yaml#

properties:
  compatible:
    const: arm,gic-v5

  "#address-cells":
    enum: [ 1, 2 ]

  "#size-cells":
    enum: [ 1, 2 ]

  ranges: true

  "#interrupt-cells":
    description: |
      The 1st cell corresponds to the INTID.Type field in the INTID; 1 for PPI,
      3 for SPI. LPI interrupts must not be described in the bindings since
      they are allocated dynamically by the software component managing them.

      The 2nd cell contains the interrupt INTID.ID field.

      The 3rd cell is the flags, encoded as follows:
      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

    const: 3

  interrupt-controller: true

  interrupts:
    description:
      The VGIC maintenance interrupt.
    maxItems: 1

required:
  - compatible
  - "#address-cells"
  - "#size-cells"
  - ranges
  - "#interrupt-cells"
  - interrupt-controller

patternProperties:
  "^irs@[0-9a-f]+$":
    type: object
    description:
      GICv5 has one or more Interrupt Routing Services (IRS) that are
      responsible for handling IRQ state and routing.

    additionalProperties: false

    properties:
      compatible:
        const: arm,gic-v5-irs

      reg:
        minItems: 1
        items:
          - description: IRS config frames
          - description: IRS setlpi frames

      reg-names:
        description:
          Describe config and setlpi frames that are present.
          "ns-" stands for non-secure, "s-" for secure, "realm-" for realm
          and "el3-" for EL3.
        minItems: 1
        maxItems: 8
        items:
          enum: [ ns-config, s-config, realm-config, el3-config, ns-setlpi,
                  s-setlpi, realm-setlpi, el3-setlpi ]

      "#address-cells":
        enum: [ 1, 2 ]

      "#size-cells":
        enum: [ 1, 2 ]

      ranges: true

      dma-noncoherent:
        description:
          Present if the GIC IRS permits programming shareability and
          cacheability attributes but is connected to a non-coherent
          downstream interconnect.

      cpus:
        description:
          CPUs managed by the IRS.

      arm,iaffids:
        $ref: /schemas/types.yaml#/definitions/uint16-array
        description:
          Interrupt AFFinity ID (IAFFID) associated with the CPU whose
          CPU node phandle is at the same index in the cpus array.

    patternProperties:
      "^its@[0-9a-f]+$":
        type: object
        description:
          GICv5 has zero or more Interrupt Translation Services (ITS) that are
          used to route Message Signalled Interrupts (MSI) to the CPUs. Each
          ITS is connected to an IRS.
        additionalProperties: false

        properties:
          compatible:
            const: arm,gic-v5-its

          reg:
            items:
              - description: ITS config frames

          reg-names:
            description:
              Describe config frames that are present.
              "ns-" stands for non-secure, "s-" for secure, "realm-" for realm
              and "el3-" for EL3.
            minItems: 1
            maxItems: 4
            items:
              enum: [ ns-config, s-config, realm-config, el3-config ]

          "#address-cells":
            enum: [ 1, 2 ]

          "#size-cells":
            enum: [ 1, 2 ]

          ranges: true

          dma-noncoherent:
            description:
              Present if the GIC ITS permits programming shareability and
              cacheability attributes but is connected to a non-coherent
              downstream interconnect.

        patternProperties:
          "^msi-controller@[0-9a-f]+$":
            type: object
            description:
              GICv5 ITS has one or more translate register frames.
            additionalProperties: false

            properties:
              reg:
                items:
                  - description: ITS translate frames

              reg-names:
                description:
                  Describe translate frames that are present.
                  "ns-" stands for non-secure, "s-" for secure, "realm-" for realm
                  and "el3-" for EL3.
                minItems: 1
                maxItems: 4
                items:
                  enum: [ ns-translate, s-translate, realm-translate, el3-translate ]

              "#msi-cells":
                description:
                  The single msi-cell is the DeviceID of the device which will
                  generate the MSI.
                const: 1

              msi-controller: true

            required:
              - reg
              - reg-names
              - "#msi-cells"
              - msi-controller

        required:
          - compatible
          - reg
          - reg-names

    required:
      - compatible
      - reg
      - reg-names
      - cpus
      - arm,iaffids

additionalProperties: false

examples:
  - |
    interrupt-controller {
      compatible = "arm,gic-v5";

      #interrupt-cells = <3>;
      interrupt-controller;

      #address-cells = <1>;
      #size-cells = <1>;
      ranges;

      interrupts = <1 25 4>;

      irs@2f1a0000 {
        compatible = "arm,gic-v5-irs";
        reg = <0x2f1a0000 0x10000>;  // IRS_CONFIG_FRAME
        reg-names = "ns-config";

        #address-cells = <1>;
        #size-cells = <1>;
        ranges;

        cpus = <&cpu0>, <&cpu1>, <&cpu2>, <&cpu3>, <&cpu4>, <&cpu5>, <&cpu6>, <&cpu7>;
        arm,iaffids = /bits/ 16 <0 1 2 3 4 5 6 7>;

        its@2f120000 {
          compatible = "arm,gic-v5-its";
          reg = <0x2f120000 0x10000>;   // ITS_CONFIG_FRAME
          reg-names = "ns-config";

          #address-cells = <1>;
          #size-cells = <1>;
          ranges;

          msi-controller@2f130000 {
            reg = <0x2f130000 0x10000>;   // ITS_TRANSLATE_FRAME
            reg-names = "ns-translate";

            #msi-cells = <1>;
            msi-controller;
          };
        };
      };
    };
...