xref: /linux/Documentation/devicetree/bindings/interrupt-controller/riscv,imsics.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,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          - spacemit,k3-imsics
52      - const: riscv,imsics
53
54  reg:
55    minItems: 1
56    maxItems: 16384
57    description:
58      Base address of each IMSIC group.
59
60  interrupt-controller: true
61
62  "#interrupt-cells":
63    const: 0
64
65  msi-controller: true
66
67  "#msi-cells":
68    const: 0
69
70  interrupts-extended:
71    minItems: 1
72    maxItems: 16384
73    description:
74      This property represents the set of CPUs (or HARTs) for which given
75      device tree node describes the IMSIC interrupt files. Each node pointed
76      to should be a riscv,cpu-intc node, which has a CPU node (i.e. RISC-V
77      HART) as parent.
78
79  riscv,num-ids:
80    $ref: /schemas/types.yaml#/definitions/uint32
81    minimum: 63
82    maximum: 2047
83    description:
84      Number of interrupt identities supported by IMSIC interrupt file.
85
86  riscv,num-guest-ids:
87    $ref: /schemas/types.yaml#/definitions/uint32
88    minimum: 63
89    maximum: 2047
90    description:
91      Number of interrupt identities are supported by IMSIC guest interrupt
92      file. When not specified it is assumed to be same as specified by the
93      riscv,num-ids property.
94
95  riscv,guest-index-bits:
96    minimum: 0
97    maximum: 7
98    default: 0
99    description:
100      Number of guest index bits in the MSI target address.
101
102  riscv,hart-index-bits:
103    minimum: 0
104    maximum: 15
105    description:
106      Number of HART index bits in the MSI target address. When not
107      specified it is calculated based on the interrupts-extended property.
108
109  riscv,group-index-bits:
110    minimum: 0
111    maximum: 7
112    default: 0
113    description:
114      Number of group index bits in the MSI target address.
115
116  riscv,group-index-shift:
117    $ref: /schemas/types.yaml#/definitions/uint32
118    minimum: 0
119    maximum: 55
120    default: 24
121    description:
122      The least significant bit position of the group index bits in the
123      MSI target address.
124
125required:
126  - compatible
127  - reg
128  - interrupt-controller
129  - msi-controller
130  - "#msi-cells"
131  - interrupts-extended
132  - riscv,num-ids
133
134unevaluatedProperties: false
135
136examples:
137  - |
138    // Example 1 (Machine-level IMSIC files with just one group):
139
140    interrupt-controller@24000000 {
141      compatible = "qemu,imsics", "riscv,imsics";
142      interrupts-extended = <&cpu1_intc 11>,
143                            <&cpu2_intc 11>,
144                            <&cpu3_intc 11>,
145                            <&cpu4_intc 11>;
146      reg = <0x24000000 0x4000>;
147      interrupt-controller;
148      #interrupt-cells = <0>;
149      msi-controller;
150      #msi-cells = <0>;
151      riscv,num-ids = <127>;
152    };
153
154  - |
155    // Example 2 (Supervisor-level IMSIC files with two groups):
156
157    interrupt-controller@28000000 {
158      compatible = "qemu,imsics", "riscv,imsics";
159      interrupts-extended = <&cpu1_intc 9>,
160                            <&cpu2_intc 9>,
161                            <&cpu3_intc 9>,
162                            <&cpu4_intc 9>;
163      reg = <0x28000000 0x2000>, /* Group0 IMSICs */
164            <0x29000000 0x2000>; /* Group1 IMSICs */
165      interrupt-controller;
166      #interrupt-cells = <0>;
167      msi-controller;
168      #msi-cells = <0>;
169      riscv,num-ids = <127>;
170      riscv,group-index-bits = <1>;
171      riscv,group-index-shift = <24>;
172    };
173...
174