xref: /linux/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml (revision 6315d93541f8a5f77c5ef5c4f25233e66d189603) 
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      - const: riscv,aplic
32
33  reg:
34    maxItems: 1
35
36  interrupt-controller: true
37
38  "#interrupt-cells":
39    const: 2
40
41  interrupts-extended:
42    minItems: 1
43    maxItems: 16384
44    description:
45      Given APLIC domain directly injects external interrupts to a set of
46      RISC-V HARTS (or CPUs). Each node pointed to should be a riscv,cpu-intc
47      node, which has a CPU node (i.e. RISC-V HART) as parent.
48
49  msi-parent:
50    description:
51      Given APLIC domain forwards wired interrupts as MSIs to a AIA incoming
52      message signaled interrupt controller (IMSIC). If both "msi-parent" and
53      "interrupts-extended" properties are present then it means the APLIC
54      domain supports both MSI mode and Direct mode in HW. In this case, the
55      APLIC driver has to choose between MSI mode or Direct mode.
56
57  riscv,num-sources:
58    $ref: /schemas/types.yaml#/definitions/uint32
59    minimum: 1
60    maximum: 1023
61    description:
62      Specifies the number of wired interrupt sources supported by this
63      APLIC domain.
64
65  riscv,children:
66    $ref: /schemas/types.yaml#/definitions/phandle-array
67    minItems: 1
68    maxItems: 1024
69    items:
70      maxItems: 1
71    description:
72      A list of child APLIC domains for the given APLIC domain. Each child
73      APLIC domain is assigned a child index in increasing order, with the
74      first child APLIC domain assigned child index 0. The APLIC domain child
75      index is used by firmware to delegate interrupts from the given APLIC
76      domain to a particular child APLIC domain.
77
78  riscv,delegation:
79    $ref: /schemas/types.yaml#/definitions/phandle-array
80    minItems: 1
81    maxItems: 1024
82    items:
83      items:
84        - description: child APLIC domain phandle
85        - description: first interrupt number of the parent APLIC domain (inclusive)
86        - description: last interrupt number of the parent APLIC domain (inclusive)
87    description:
88      A interrupt delegation list where each entry is a triple consisting
89      of child APLIC domain phandle, first interrupt number of the parent
90      APLIC domain, and last interrupt number of the parent APLIC domain.
91      Firmware must configure interrupt delegation registers based on
92      interrupt delegation list.
93
94  riscv,hart-indexes:
95    $ref: /schemas/types.yaml#/definitions/uint32-array
96    minItems: 1
97    maxItems: 16384
98    description:
99      A list of hart indexes that APLIC should use to address each hart
100      that is mentioned in the "interrupts-extended"
101
102dependencies:
103  riscv,delegation: [ "riscv,children" ]
104
105required:
106  - compatible
107  - reg
108  - interrupt-controller
109  - "#interrupt-cells"
110  - riscv,num-sources
111
112anyOf:
113  - required:
114      - interrupts-extended
115  - required:
116      - msi-parent
117
118unevaluatedProperties: false
119
120examples:
121  - |
122    // Example 1 (APLIC domains directly injecting interrupt to HARTs):
123
124    interrupt-controller@c000000 {
125      compatible = "qemu,aplic", "riscv,aplic";
126      interrupts-extended = <&cpu1_intc 11>,
127                            <&cpu2_intc 11>,
128                            <&cpu3_intc 11>,
129                            <&cpu4_intc 11>;
130      reg = <0xc000000 0x4080>;
131      interrupt-controller;
132      #interrupt-cells = <2>;
133      riscv,num-sources = <63>;
134      riscv,children = <&aplic1>, <&aplic2>;
135      riscv,delegation = <&aplic1 1 63>;
136    };
137
138    aplic1: interrupt-controller@d000000 {
139      compatible = "qemu,aplic", "riscv,aplic";
140      interrupts-extended = <&cpu1_intc 9>,
141                            <&cpu2_intc 9>;
142      reg = <0xd000000 0x4080>;
143      interrupt-controller;
144      #interrupt-cells = <2>;
145      riscv,num-sources = <63>;
146    };
147
148    aplic2: interrupt-controller@e000000 {
149      compatible = "qemu,aplic", "riscv,aplic";
150      interrupts-extended = <&cpu3_intc 9>,
151                            <&cpu4_intc 9>;
152      reg = <0xe000000 0x4080>;
153      interrupt-controller;
154      #interrupt-cells = <2>;
155      riscv,num-sources = <63>;
156    };
157
158  - |
159    // Example 2 (APLIC domains forwarding interrupts as MSIs):
160
161    interrupt-controller@c000000 {
162      compatible = "qemu,aplic", "riscv,aplic";
163      msi-parent = <&imsic_mlevel>;
164      reg = <0xc000000 0x4000>;
165      interrupt-controller;
166      #interrupt-cells = <2>;
167      riscv,num-sources = <63>;
168      riscv,children = <&aplic3>;
169      riscv,delegation = <&aplic3 1 63>;
170    };
171
172    aplic3: interrupt-controller@d000000 {
173      compatible = "qemu,aplic", "riscv,aplic";
174      msi-parent = <&imsic_slevel>;
175      reg = <0xd000000 0x4000>;
176      interrupt-controller;
177      #interrupt-cells = <2>;
178      riscv,num-sources = <63>;
179    };
180...
181