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