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,imsics.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: RISC-V Incoming MSI Controller (IMSIC)
8
9maintainers:
10  - Anup Patel <anup@brainfault.org>
11
12description: |
13  The RISC-V advanced interrupt architecture (AIA) defines a per-CPU incoming
14  MSI controller (IMSIC) for handling MSIs in a RISC-V platform. The RISC-V
15  AIA specification can be found at https://github.com/riscv/riscv-aia.
16
17  The IMSIC is a per-CPU (or per-HART) device with separate interrupt file
18  for each privilege level (machine or supervisor). The configuration of
19  a IMSIC interrupt file is done using AIA CSRs and it also has a 4KB MMIO
20  space to receive MSIs from devices. Each IMSIC interrupt file supports a
21  fixed number of interrupt identities (to distinguish MSIs from devices)
22  which is same for given privilege level across CPUs (or HARTs).
23
24  The device tree of a RISC-V platform will have one IMSIC device tree node
25  for each privilege level (machine or supervisor) which collectively describe
26  IMSIC interrupt files at that privilege level across CPUs (or HARTs).
27
28  The arrangement of IMSIC interrupt files in MMIO space of a RISC-V platform
29  follows a particular scheme defined by the RISC-V AIA specification. A IMSIC
30  group is a set of IMSIC interrupt files co-located in MMIO space and we can
31  have multiple IMSIC groups (i.e. clusters, sockets, chiplets, etc) in a
32  RISC-V platform. The MSI target address of a IMSIC interrupt file at given
33  privilege level (machine or supervisor) encodes group index, HART index,
34  and guest index (shown below).
35
36  XLEN-1            > (HART Index MSB)                  12    0
37  |                  |                                  |     |
38  -------------------------------------------------------------
39  |xxxxxx|Group Index|xxxxxxxxxxx|HART Index|Guest Index|  0  |
40  -------------------------------------------------------------
41
42allOf:
43  - $ref: /schemas/interrupt-controller.yaml#
44  - $ref: /schemas/interrupt-controller/msi-controller.yaml#
45
46properties:
47  compatible:
48    items:
49      - enum:
50          - qemu,imsics
51      - const: riscv,imsics
52
53  reg:
54    minItems: 1
55    maxItems: 16384
56    description:
57      Base address of each IMSIC group.
58
59  interrupt-controller: true
60
61  "#interrupt-cells":
62    const: 0
63
64  msi-controller: true
65
66  "#msi-cells":
67    const: 0
68
69  interrupts-extended:
70    minItems: 1
71    maxItems: 16384
72    description:
73      This property represents the set of CPUs (or HARTs) for which given
74      device tree node describes the IMSIC interrupt files. Each node pointed
75      to should be a riscv,cpu-intc node, which has a CPU node (i.e. RISC-V
76      HART) as parent.
77
78  riscv,num-ids:
79    $ref: /schemas/types.yaml#/definitions/uint32
80    minimum: 63
81    maximum: 2047
82    description:
83      Number of interrupt identities supported by IMSIC interrupt file.
84
85  riscv,num-guest-ids:
86    $ref: /schemas/types.yaml#/definitions/uint32
87    minimum: 63
88    maximum: 2047
89    description:
90      Number of interrupt identities are supported by IMSIC guest interrupt
91      file. When not specified it is assumed to be same as specified by the
92      riscv,num-ids property.
93
94  riscv,guest-index-bits:
95    minimum: 0
96    maximum: 7
97    default: 0
98    description:
99      Number of guest index bits in the MSI target address.
100
101  riscv,hart-index-bits:
102    minimum: 0
103    maximum: 15
104    description:
105      Number of HART index bits in the MSI target address. When not
106      specified it is calculated based on the interrupts-extended property.
107
108  riscv,group-index-bits:
109    minimum: 0
110    maximum: 7
111    default: 0
112    description:
113      Number of group index bits in the MSI target address.
114
115  riscv,group-index-shift:
116    $ref: /schemas/types.yaml#/definitions/uint32
117    minimum: 0
118    maximum: 55
119    default: 24
120    description:
121      The least significant bit position of the group index bits in the
122      MSI target address.
123
124required:
125  - compatible
126  - reg
127  - interrupt-controller
128  - msi-controller
129  - "#msi-cells"
130  - interrupts-extended
131  - riscv,num-ids
132
133unevaluatedProperties: false
134
135examples:
136  - |
137    // Example 1 (Machine-level IMSIC files with just one group):
138
139    interrupt-controller@24000000 {
140      compatible = "qemu,imsics", "riscv,imsics";
141      interrupts-extended = <&cpu1_intc 11>,
142                            <&cpu2_intc 11>,
143                            <&cpu3_intc 11>,
144                            <&cpu4_intc 11>;
145      reg = <0x28000000 0x4000>;
146      interrupt-controller;
147      #interrupt-cells = <0>;
148      msi-controller;
149      #msi-cells = <0>;
150      riscv,num-ids = <127>;
151    };
152
153  - |
154    // Example 2 (Supervisor-level IMSIC files with two groups):
155
156    interrupt-controller@28000000 {
157      compatible = "qemu,imsics", "riscv,imsics";
158      interrupts-extended = <&cpu1_intc 9>,
159                            <&cpu2_intc 9>,
160                            <&cpu3_intc 9>,
161                            <&cpu4_intc 9>;
162      reg = <0x28000000 0x2000>, /* Group0 IMSICs */
163            <0x29000000 0x2000>; /* Group1 IMSICs */
164      interrupt-controller;
165      #interrupt-cells = <0>;
166      msi-controller;
167      #msi-cells = <0>;
168      riscv,num-ids = <127>;
169      riscv,group-index-bits = <1>;
170      riscv,group-index-shift = <24>;
171    };
172...
173