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         type: object
 142         properties:
 143           affinity:
 144             $ref: /schemas/types.yaml#/definitions/phandle-array
 145             description:
 146               Should be a list of phandles to CPU nodes (as described in
 147               Documentation/devicetree/bindings/arm/cpus.yaml).
 148
 149         required:
 150           - affinity
 151
 152 dependencies:
 153   mbi-ranges: [ msi-controller ]
 154   msi-controller: [ mbi-ranges ]
 155
 156 required:
 157   - compatible
 158   - interrupts
 159   - reg
 160
 161 patternProperties:
 162   "^gic-its@": false
 163   "^interrupt-controller@[0-9a-f]+$": false
 164   # msi-controller is preferred, but allow other names
 165   "^(msi-controller|gic-its|interrupt-controller)@[0-9a-f]+$":
 166     type: object
 167     description:
 168       GICv3 has one or more Interrupt Translation Services (ITS) that are
 169       used to route Message Signalled Interrupts (MSI) to the CPUs.
 170     properties:
 171       compatible:
 172         const: arm,gic-v3-its
 173
 174       msi-controller: true
 175
 176       "#msi-cells":
 177         description:
 178           The single msi-cell is the DeviceID of the device which will generate
 179           the MSI.
 180         const: 1
 181
 182       reg:
 183         description:
 184           Specifies the base physical address and size of the ITS registers.
 185         maxItems: 1
 186
 187       socionext,synquacer-pre-its:
 188         description:
 189           (u32, u32) tuple describing the untranslated
 190           address and size of the pre-ITS window.
 191         allOf:
 192           - $ref: /schemas/types.yaml#/definitions/uint32-array
 193           - items:
 194               minItems: 2
 195               maxItems: 2
 196
 197     required:
 198       - compatible
 199       - msi-controller
 200       - "#msi-cells"
 201       - reg
 202
 203     additionalProperties: false
 204
 205 additionalProperties: false
 206
 207 examples:
 208   - |
 209     gic: interrupt-controller@2cf00000 {
 210       compatible = "arm,gic-v3";
 211       #interrupt-cells = <3>;
 212       #address-cells = <1>;
 213       #size-cells = <1>;
 214       ranges;
 215       interrupt-controller;
 216       reg = <0x2f000000 0x10000>,  // GICD
 217             <0x2f100000 0x200000>,  // GICR
 218             <0x2c000000 0x2000>,  // GICC
 219             <0x2c010000 0x2000>,  // GICH
 220             <0x2c020000 0x2000>;  // GICV
 221       interrupts = <1 9 4>;
 222
 223       msi-controller;
 224       mbi-ranges = <256 128>;
 225
 226       msi-controller@2c200000 {
 227         compatible = "arm,gic-v3-its";
 228         msi-controller;
 229         #msi-cells = <1>;
 230         reg = <0x2c200000 0x20000>;
 231       };
 232     };
 233
 234     interrupt-controller@2c010000 {
 235       compatible = "arm,gic-v3";
 236       #interrupt-cells = <4>;
 237       #address-cells = <1>;
 238       #size-cells = <1>;
 239       ranges;
 240       interrupt-controller;
 241       redistributor-stride = <0x0 0x40000>;  // 256kB stride
 242       #redistributor-regions = <2>;
 243       reg = <0x2c010000 0x10000>,  // GICD
 244             <0x2d000000 0x800000>,  // GICR 1: CPUs 0-31
 245             <0x2e000000 0x800000>,  // GICR 2: CPUs 32-63
 246             <0x2c040000 0x2000>,  // GICC
 247             <0x2c060000 0x2000>,  // GICH
 248             <0x2c080000 0x2000>;  // GICV
 249       interrupts = <1 9 4>;
 250
 251       msi-controller@2c200000 {
 252         compatible = "arm,gic-v3-its";
 253         msi-controller;
 254         #msi-cells = <1>;
 255         reg = <0x2c200000 0x20000>;
 256       };
 257
 258       msi-controller@2c400000 {
 259         compatible = "arm,gic-v3-its";
 260         msi-controller;
 261         #msi-cells = <1>;
 262         reg = <0x2c400000 0x20000>;
 263       };
 264
 265       ppi-partitions {
 266         part0: interrupt-partition-0 {
 267           affinity = <&cpu0 &cpu2>;
 268         };
 269
 270         part1: interrupt-partition-1 {
 271           affinity = <&cpu1 &cpu3>;
 272         };
 273       };
 274     };
 275
 276
 277     device@0 {
 278       reg = <0 4>;
 279       interrupts = <1 1 4 &part0>;
 280     };
 281
 282 ...