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 <marc.zyngier@arm.com>
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. 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
149dependencies:
150  mbi-ranges: [ msi-controller ]
151  msi-controller: [ mbi-ranges ]
152
153required:
154  - compatible
155  - interrupts
156  - reg
157
158patternProperties:
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
202additionalProperties: false
203
204examples:
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...
280