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
7title: ARM Generic Interrupt Controller, version 3
8
9maintainers:
10  - Marc Zyngier <maz@kernel.org>
11
12description: |
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
18allOf:
19  - $ref: /schemas/interrupt-controller.yaml#
20
21properties:
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 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  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
181dependencies:
182  mbi-ranges: [ msi-controller ]
183  msi-controller: [ mbi-ranges ]
184
185required:
186  - compatible
187  - reg
188
189patternProperties:
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
238additionalProperties: false
239
240examples:
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...
317