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