Documentation/devicetree/bindings/interrupt-controller/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
   7 title: RISC-V Incoming MSI Controller (IMSIC)
   8
   9 maintainers:
  10   - Anup Patel <anup@brainfault.org>
  11
  12 description: |
  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
  42 allOf:
  43   - $ref: /schemas/interrupt-controller.yaml#
  44   - $ref: /schemas/interrupt-controller/msi-controller.yaml#
  45
  46 properties:
  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
 124 required:
 125   - compatible
 126   - reg
 127   - interrupt-controller
 128   - msi-controller
 129   - "#msi-cells"
 130   - interrupts-extended
 131   - riscv,num-ids
 132
 133 unevaluatedProperties: false
 134
 135 examples:
 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 ...