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