xref: /linux/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml (revision ca220141fa8ebae09765a242076b2b77338106b0) 
1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/interrupt-controller/riscv,aplic.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: RISC-V Advanced Platform Level Interrupt Controller (APLIC)
8
9maintainers:
10  - Anup Patel <anup@brainfault.org>
11
12description:
13  The RISC-V advanced interrupt architecture (AIA) defines an advanced
14  platform level interrupt controller (APLIC) for handling wired interrupts
15  in a RISC-V platform. The RISC-V AIA specification can be found at
16  https://github.com/riscv/riscv-aia.
17
18  The RISC-V APLIC is implemented as hierarchical APLIC domains where all
19  interrupt sources connect to the root APLIC domain and a parent APLIC
20  domain can delegate interrupt sources to it's child APLIC domains. There
21  is one device tree node for each APLIC domain.
22
23allOf:
24  - $ref: /schemas/interrupt-controller.yaml#
25
26properties:
27  compatible:
28    items:
29      - enum:
30          - qemu,aplic
31          - spacemit,k3-aplic
32      - const: riscv,aplic
33
34  reg:
35    maxItems: 1
36
37  interrupt-controller: true
38
39  "#interrupt-cells":
40    const: 2
41
42  interrupts-extended:
43    minItems: 1
44    maxItems: 16384
45    description:
46      Given APLIC domain directly injects external interrupts to a set of
47      RISC-V HARTS (or CPUs). Each node pointed to should be a riscv,cpu-intc
48      node, which has a CPU node (i.e. RISC-V HART) as parent.
49
50  msi-parent:
51    description:
52      Given APLIC domain forwards wired interrupts as MSIs to a AIA incoming
53      message signaled interrupt controller (IMSIC). If both "msi-parent" and
54      "interrupts-extended" properties are present then it means the APLIC
55      domain supports both MSI mode and Direct mode in HW. In this case, the
56      APLIC driver has to choose between MSI mode or Direct mode.
57
58  riscv,num-sources:
59    $ref: /schemas/types.yaml#/definitions/uint32
60    minimum: 1
61    maximum: 1023
62    description:
63      Specifies the number of wired interrupt sources supported by this
64      APLIC domain.
65
66  riscv,children:
67    $ref: /schemas/types.yaml#/definitions/phandle-array
68    minItems: 1
69    maxItems: 1024
70    items:
71      maxItems: 1
72    description:
73      A list of child APLIC domains for the given APLIC domain. Each child
74      APLIC domain is assigned a child index in increasing order, with the
75      first child APLIC domain assigned child index 0. The APLIC domain child
76      index is used by firmware to delegate interrupts from the given APLIC
77      domain to a particular child APLIC domain.
78
79  riscv,delegation:
80    $ref: /schemas/types.yaml#/definitions/phandle-array
81    minItems: 1
82    maxItems: 1024
83    items:
84      items:
85        - description: child APLIC domain phandle
86        - description: first interrupt number of the parent APLIC domain (inclusive)
87        - description: last interrupt number of the parent APLIC domain (inclusive)
88    description:
89      A interrupt delegation list where each entry is a triple consisting
90      of child APLIC domain phandle, first interrupt number of the parent
91      APLIC domain, and last interrupt number of the parent APLIC domain.
92      Firmware must configure interrupt delegation registers based on
93      interrupt delegation list.
94
95  riscv,hart-indexes:
96    $ref: /schemas/types.yaml#/definitions/uint32-array
97    minItems: 1
98    maxItems: 16384
99    description:
100      A list of hart indexes that APLIC should use to address each hart
101      that is mentioned in the "interrupts-extended"
102
103dependencies:
104  riscv,delegation: [ "riscv,children" ]
105
106required:
107  - compatible
108  - reg
109  - interrupt-controller
110  - "#interrupt-cells"
111  - riscv,num-sources
112
113anyOf:
114  - required:
115      - interrupts-extended
116  - required:
117      - msi-parent
118
119unevaluatedProperties: false
120
121examples:
122  - |
123    // Example 1 (APLIC domains directly injecting interrupt to HARTs):
124
125    interrupt-controller@c000000 {
126      compatible = "qemu,aplic", "riscv,aplic";
127      interrupts-extended = <&cpu1_intc 11>,
128                            <&cpu2_intc 11>,
129                            <&cpu3_intc 11>,
130                            <&cpu4_intc 11>;
131      reg = <0xc000000 0x4080>;
132      interrupt-controller;
133      #interrupt-cells = <2>;
134      riscv,num-sources = <63>;
135      riscv,children = <&aplic1>, <&aplic2>;
136      riscv,delegation = <&aplic1 1 63>;
137    };
138
139    aplic1: interrupt-controller@d000000 {
140      compatible = "qemu,aplic", "riscv,aplic";
141      interrupts-extended = <&cpu1_intc 9>,
142                            <&cpu2_intc 9>;
143      reg = <0xd000000 0x4080>;
144      interrupt-controller;
145      #interrupt-cells = <2>;
146      riscv,num-sources = <63>;
147    };
148
149    aplic2: interrupt-controller@e000000 {
150      compatible = "qemu,aplic", "riscv,aplic";
151      interrupts-extended = <&cpu3_intc 9>,
152                            <&cpu4_intc 9>;
153      reg = <0xe000000 0x4080>;
154      interrupt-controller;
155      #interrupt-cells = <2>;
156      riscv,num-sources = <63>;
157    };
158
159  - |
160    // Example 2 (APLIC domains forwarding interrupts as MSIs):
161
162    interrupt-controller@c000000 {
163      compatible = "qemu,aplic", "riscv,aplic";
164      msi-parent = <&imsic_mlevel>;
165      reg = <0xc000000 0x4000>;
166      interrupt-controller;
167      #interrupt-cells = <2>;
168      riscv,num-sources = <63>;
169      riscv,children = <&aplic3>;
170      riscv,delegation = <&aplic3 1 63>;
171    };
172
173    aplic3: interrupt-controller@d000000 {
174      compatible = "qemu,aplic", "riscv,aplic";
175      msi-parent = <&imsic_slevel>;
176      reg = <0xd000000 0x4000>;
177      interrupt-controller;
178      #interrupt-cells = <2>;
179      riscv,num-sources = <63>;
180    };
181...
182