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