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