riscv,imsics.yaml

  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 = <0x24000000 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...