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

   1 # SPDX-License-Identifier: GPL-2.0
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/interrupt-controller/arm,gic-v3.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: ARM Generic Interrupt Controller, version 3
   8
   9 maintainers:
  10   - Marc Zyngier <marc.zyngier@arm.com>
  11
  12 description: |
  13   AArch64 SMP cores are often associated with a GICv3, providing Private
  14   Peripheral Interrupts (PPI), Shared Peripheral Interrupts (SPI),
  15   Software Generated Interrupts (SGI), and Locality-specific Peripheral
  16   Interrupts (LPI).
  17
  18 allOf:
  19   - $ref: /schemas/interrupt-controller.yaml#
  20
  21 properties:
  22   compatible:
  23     oneOf:
  24       - items:
  25           - enum:
  26               - qcom,msm8996-gic-v3
  27           - const: arm,gic-v3
  28       - const: arm,gic-v3
  29
  30   interrupt-controller: true
  31
  32   "#address-cells":
  33     enum: [ 0, 1, 2 ]
  34   "#size-cells":
  35     enum: [ 1, 2 ]
  36
  37   ranges: true
  38
  39   "#interrupt-cells":
  40     description: |
  41       Specifies the number of cells needed to encode an interrupt source.
  42       Must be a single cell with a value of at least 3.
  43       If the system requires describing PPI affinity, then the value must
  44       be at least 4.
  45
  46       The 1st cell is the interrupt type; 0 for SPI interrupts, 1 for PPI
  47       interrupts, 2 for interrupts in the Extended SPI range, 3 for the
  48       Extended PPI range. Other values are reserved for future use.
  49
  50       The 2nd cell contains the interrupt number for the interrupt type.
  51       SPI interrupts are in the range [0-987]. PPI interrupts are in the
  52       range [0-15]. Extented SPI interrupts are in the range [0-1023].
  53       Extended PPI interrupts are in the range [0-127].
  54
  55       The 3rd cell is the flags, encoded as follows:
  56       bits[3:0] trigger type and level flags.
  57         1 = edge triggered
  58         4 = level triggered
  59
  60       The 4th cell is a phandle to a node describing a set of CPUs this
  61       interrupt is affine to. The interrupt must be a PPI, and the node
  62       pointed must be a subnode of the "ppi-partitions" subnode. For
  63       interrupt types other than PPI or PPIs that are not partitionned,
  64       this cell must be zero. See the "ppi-partitions" node description
  65       below.
  66
  67       Cells 5 and beyond are reserved for future use and must have a value
  68       of 0 if present.
  69     enum: [ 3, 4 ]
  70
  71   reg:
  72     description: |
  73       Specifies base physical address(s) and size of the GIC
  74       registers, in the following order:
  75       - GIC Distributor interface (GICD)
  76       - GIC Redistributors (GICR), one range per redistributor region
  77       - GIC CPU interface (GICC)
  78       - GIC Hypervisor interface (GICH)
  79       - GIC Virtual CPU interface (GICV)
  80
  81       GICC, GICH and GICV are optional.
  82     minItems: 2
  83     maxItems: 4096   # Should be enough?
  84
  85   interrupts:
  86     description:
  87       Interrupt source of the VGIC maintenance interrupt.
  88     maxItems: 1
  89
  90   redistributor-stride:
  91     description:
  92       If using padding pages, specifies the stride of consecutive
  93       redistributors. Must be a multiple of 64kB.
  94     allOf:
  95       - $ref: /schemas/types.yaml#/definitions/uint64
  96       - multipleOf: 0x10000
  97         exclusiveMinimum: 0
  98
  99   "#redistributor-regions":
 100     description:
 101       The number of independent contiguous regions occupied by the
 102       redistributors. Required if more than one such region is present.
 103     allOf:
 104       - $ref: /schemas/types.yaml#/definitions/uint32
 105       - maximum: 4096   # Should be enough?
 106
 107   msi-controller:
 108     description:
 109       Only present if the Message Based Interrupt functionnality is
 110       being exposed by the HW, and the mbi-ranges property present.
 111
 112   mbi-ranges:
 113     description:
 114       A list of pairs <intid span>, where "intid" is the first SPI of a range
 115       that can be used an MBI, and "span" the size of that range. Multiple
 116       ranges can be provided.
 117     allOf:
 118       - $ref: /schemas/types.yaml#/definitions/uint32-matrix
 119       - items:
 120           minItems: 2
 121           maxItems: 2
 122
 123   mbi-alias:
 124     description:
 125       Address property. Base address of an alias of the GICD region containing
 126       only the {SET,CLR}SPI registers to be used if isolation is required,
 127       and if supported by the HW.
 128     allOf:
 129       - $ref: /schemas/types.yaml#/definitions/uint32-array
 130       - items:
 131           minItems: 1
 132           maxItems: 2
 133
 134   ppi-partitions:
 135     type: object
 136     description:
 137       PPI affinity can be expressed as a single "ppi-partitions" node,
 138       containing a set of sub-nodes.
 139     patternProperties:
 140       "^interrupt-partition-[0-9]+$":
 141         properties:
 142           affinity:
 143             $ref: /schemas/types.yaml#/definitions/phandle-array
 144             description:
 145               Should be a list of phandles to CPU nodes (as described in
 146               Documentation/devicetree/bindings/arm/cpus.yaml).
 147
 148         required:
 149           - affinity
 150
 151 dependencies:
 152   mbi-ranges: [ msi-controller ]
 153   msi-controller: [ mbi-ranges ]
 154
 155 required:
 156   - compatible
 157   - interrupts
 158   - reg
 159
 160 patternProperties:
 161   "^gic-its@": false
 162   "^interrupt-controller@[0-9a-f]+$": false
 163   # msi-controller is preferred, but allow other names
 164   "^(msi-controller|gic-its|interrupt-controller)@[0-9a-f]+$":
 165     type: object
 166     description:
 167       GICv3 has one or more Interrupt Translation Services (ITS) that are
 168       used to route Message Signalled Interrupts (MSI) to the CPUs.
 169     properties:
 170       compatible:
 171         const: arm,gic-v3-its
 172
 173       msi-controller: true
 174
 175       "#msi-cells":
 176         description:
 177           The single msi-cell is the DeviceID of the device which will generate
 178           the MSI.
 179         const: 1
 180
 181       reg:
 182         description:
 183           Specifies the base physical address and size of the ITS registers.
 184         maxItems: 1
 185
 186       socionext,synquacer-pre-its:
 187         description:
 188           (u32, u32) tuple describing the untranslated
 189           address and size of the pre-ITS window.
 190         allOf:
 191           - $ref: /schemas/types.yaml#/definitions/uint32-array
 192           - items:
 193               minItems: 2
 194               maxItems: 2
 195
 196     required:
 197       - compatible
 198       - msi-controller
 199       - "#msi-cells"
 200       - reg
 201
 202     additionalProperties: false
 203
 204 additionalProperties: false
 205
 206 examples:
 207   - |
 208     gic: interrupt-controller@2cf00000 {
 209       compatible = "arm,gic-v3";
 210       #interrupt-cells = <3>;
 211       #address-cells = <1>;
 212       #size-cells = <1>;
 213       ranges;
 214       interrupt-controller;
 215       reg = <0x2f000000 0x10000>,  // GICD
 216             <0x2f100000 0x200000>,  // GICR
 217             <0x2c000000 0x2000>,  // GICC
 218             <0x2c010000 0x2000>,  // GICH
 219             <0x2c020000 0x2000>;  // GICV
 220       interrupts = <1 9 4>;
 221
 222       msi-controller;
 223       mbi-ranges = <256 128>;
 224
 225       msi-controller@2c200000 {
 226         compatible = "arm,gic-v3-its";
 227         msi-controller;
 228         #msi-cells = <1>;
 229         reg = <0x2c200000 0x20000>;
 230       };
 231     };
 232
 233     interrupt-controller@2c010000 {
 234       compatible = "arm,gic-v3";
 235       #interrupt-cells = <4>;
 236       #address-cells = <1>;
 237       #size-cells = <1>;
 238       ranges;
 239       interrupt-controller;
 240       redistributor-stride = <0x0 0x40000>;  // 256kB stride
 241       #redistributor-regions = <2>;
 242       reg = <0x2c010000 0x10000>,  // GICD
 243             <0x2d000000 0x800000>,  // GICR 1: CPUs 0-31
 244             <0x2e000000 0x800000>,  // GICR 2: CPUs 32-63
 245             <0x2c040000 0x2000>,  // GICC
 246             <0x2c060000 0x2000>,  // GICH
 247             <0x2c080000 0x2000>;  // GICV
 248       interrupts = <1 9 4>;
 249
 250       msi-controller@2c200000 {
 251         compatible = "arm,gic-v3-its";
 252         msi-controller;
 253         #msi-cells = <1>;
 254         reg = <0x2c200000 0x20000>;
 255       };
 256
 257       msi-controller@2c400000 {
 258         compatible = "arm,gic-v3-its";
 259         msi-controller;
 260         #msi-cells = <1>;
 261         reg = <0x2c400000 0x20000>;
 262       };
 263
 264       ppi-partitions {
 265         part0: interrupt-partition-0 {
 266           affinity = <&cpu0 &cpu2>;
 267         };
 268
 269         part1: interrupt-partition-1 {
 270           affinity = <&cpu1 &cpu3>;
 271         };
 272       };
 273     };
 274
 275
 276     device@0 {
 277       reg = <0 4>;
 278       interrupts = <1 1 4 &part0>;
 279     };
 280
 281 ...