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     $ref: /schemas/types.yaml#/definitions/uint64
  95     multipleOf: 0x10000
  96     exclusiveMinimum: 0
  97
  98   "#redistributor-regions":
  99     description:
 100       The number of independent contiguous regions occupied by the
 101       redistributors. Required if more than one such region is present.
 102     $ref: /schemas/types.yaml#/definitions/uint32
 103     maximum: 4096
 104
 105   msi-controller:
 106     description:
 107       Only present if the Message Based Interrupt functionnality is
 108       being exposed by the HW, and the mbi-ranges property present.
 109
 110   mbi-ranges:
 111     description:
 112       A list of pairs <intid span>, where "intid" is the first SPI of a range
 113       that can be used an MBI, and "span" the size of that range. Multiple
 114       ranges can be provided.
 115     $ref: /schemas/types.yaml#/definitions/uint32-matrix
 116     items:
 117       minItems: 2
 118       maxItems: 2
 119
 120   mbi-alias:
 121     description:
 122       Address property. Base address of an alias of the GICD region containing
 123       only the {SET,CLR}SPI registers to be used if isolation is required,
 124       and if supported by the HW.
 125     $ref: /schemas/types.yaml#/definitions/uint32-array
 126     items:
 127       minItems: 1
 128       maxItems: 2
 129
 130   ppi-partitions:
 131     type: object
 132     description:
 133       PPI affinity can be expressed as a single "ppi-partitions" node,
 134       containing a set of sub-nodes.
 135     patternProperties:
 136       "^interrupt-partition-[0-9]+$":
 137         type: object
 138         properties:
 139           affinity:
 140             $ref: /schemas/types.yaml#/definitions/phandle-array
 141             description:
 142               Should be a list of phandles to CPU nodes (as described in
 143               Documentation/devicetree/bindings/arm/cpus.yaml).
 144
 145         required:
 146           - affinity
 147
 148   clocks:
 149     maxItems: 1
 150
 151   clock-names:
 152     items:
 153       - const: aclk
 154
 155   power-domains:
 156     maxItems: 1
 157
 158   resets:
 159     maxItems: 1
 160
 161 dependencies:
 162   mbi-ranges: [ msi-controller ]
 163   msi-controller: [ mbi-ranges ]
 164
 165 required:
 166   - compatible
 167   - interrupts
 168   - reg
 169
 170 patternProperties:
 171   "^gic-its@": false
 172   "^interrupt-controller@[0-9a-f]+$": false
 173   # msi-controller is preferred, but allow other names
 174   "^(msi-controller|gic-its|interrupt-controller)@[0-9a-f]+$":
 175     type: object
 176     description:
 177       GICv3 has one or more Interrupt Translation Services (ITS) that are
 178       used to route Message Signalled Interrupts (MSI) to the CPUs.
 179     properties:
 180       compatible:
 181         const: arm,gic-v3-its
 182
 183       msi-controller: true
 184
 185       "#msi-cells":
 186         description:
 187           The single msi-cell is the DeviceID of the device which will generate
 188           the MSI.
 189         const: 1
 190
 191       reg:
 192         description:
 193           Specifies the base physical address and size of the ITS registers.
 194         maxItems: 1
 195
 196       socionext,synquacer-pre-its:
 197         description:
 198           (u32, u32) tuple describing the untranslated
 199           address and size of the pre-ITS window.
 200         $ref: /schemas/types.yaml#/definitions/uint32-array
 201         items:
 202           minItems: 2
 203           maxItems: 2
 204
 205     required:
 206       - compatible
 207       - msi-controller
 208       - "#msi-cells"
 209       - reg
 210
 211     additionalProperties: false
 212
 213 additionalProperties: false
 214
 215 examples:
 216   - |
 217     gic: interrupt-controller@2cf00000 {
 218       compatible = "arm,gic-v3";
 219       #interrupt-cells = <3>;
 220       #address-cells = <1>;
 221       #size-cells = <1>;
 222       ranges;
 223       interrupt-controller;
 224       reg = <0x2f000000 0x10000>,  // GICD
 225             <0x2f100000 0x200000>,  // GICR
 226             <0x2c000000 0x2000>,  // GICC
 227             <0x2c010000 0x2000>,  // GICH
 228             <0x2c020000 0x2000>;  // GICV
 229       interrupts = <1 9 4>;
 230
 231       msi-controller;
 232       mbi-ranges = <256 128>;
 233
 234       msi-controller@2c200000 {
 235         compatible = "arm,gic-v3-its";
 236         msi-controller;
 237         #msi-cells = <1>;
 238         reg = <0x2c200000 0x20000>;
 239       };
 240     };
 241
 242     interrupt-controller@2c010000 {
 243       compatible = "arm,gic-v3";
 244       #interrupt-cells = <4>;
 245       #address-cells = <1>;
 246       #size-cells = <1>;
 247       ranges;
 248       interrupt-controller;
 249       redistributor-stride = <0x0 0x40000>;  // 256kB stride
 250       #redistributor-regions = <2>;
 251       reg = <0x2c010000 0x10000>,  // GICD
 252             <0x2d000000 0x800000>,  // GICR 1: CPUs 0-31
 253             <0x2e000000 0x800000>,  // GICR 2: CPUs 32-63
 254             <0x2c040000 0x2000>,  // GICC
 255             <0x2c060000 0x2000>,  // GICH
 256             <0x2c080000 0x2000>;  // GICV
 257       interrupts = <1 9 4>;
 258
 259       msi-controller@2c200000 {
 260         compatible = "arm,gic-v3-its";
 261         msi-controller;
 262         #msi-cells = <1>;
 263         reg = <0x2c200000 0x20000>;
 264       };
 265
 266       msi-controller@2c400000 {
 267         compatible = "arm,gic-v3-its";
 268         msi-controller;
 269         #msi-cells = <1>;
 270         reg = <0x2c400000 0x20000>;
 271       };
 272
 273       ppi-partitions {
 274         part0: interrupt-partition-0 {
 275           affinity = <&cpu0 &cpu2>;
 276         };
 277
 278         part1: interrupt-partition-1 {
 279           affinity = <&cpu1 &cpu3>;
 280         };
 281       };
 282     };
 283
 284
 285     device@0 {
 286       reg = <0 4>;
 287       interrupts = <1 1 4 &part0>;
 288     };
 289
 290 ...