Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml

   1 # SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
   2 # Copyright (C) 2020 SiFive, Inc.
   3 %YAML 1.2
   4 ---
   5 $id: http://devicetree.org/schemas/interrupt-controller/sifive,plic-1.0.0.yaml#
   6 $schema: http://devicetree.org/meta-schemas/core.yaml#
   7
   8 title: SiFive Platform-Level Interrupt Controller (PLIC)
   9
  10 description:
  11   SiFive SoCs and other RISC-V SoCs include an implementation of the
  12   Platform-Level Interrupt Controller (PLIC) high-level specification in
  13   the RISC-V Privileged Architecture specification. The PLIC connects all
  14   external interrupts in the system to all hart contexts in the system, via
  15   the external interrupt source in each hart.
  16
  17   A hart context is a privilege mode in a hardware execution thread. For example,
  18   in an 4 core system with 2-way SMT, you have 8 harts and probably at least two
  19   privilege modes per hart; machine mode and supervisor mode.
  20
  21   Each interrupt can be enabled on per-context basis. Any context can claim
  22   a pending enabled interrupt and then release it once it has been handled.
  23
  24   Each interrupt has a configurable priority. Higher priority interrupts are
  25   serviced first.  Each context can specify a priority threshold. Interrupts
  26   with priority below this threshold will not cause the PLIC to raise its
  27   interrupt line leading to the context.
  28
  29   The PLIC supports both edge-triggered and level-triggered interrupts. For
  30   edge-triggered interrupts, the RISC-V PLIC spec allows two responses to edges
  31   seen while an interrupt handler is active; the PLIC may either queue them or
  32   ignore them. In the first case, handlers are oblivious to the trigger type, so
  33   it is not included in the interrupt specifier. In the second case, software
  34   needs to know the trigger type, so it can reorder the interrupt flow to avoid
  35   missing interrupts. This special handling is needed by at least the Renesas
  36   RZ/Five SoC (AX45MP AndesCore with a NCEPLIC100) and the T-HEAD C900 PLIC.
  37
  38   While the RISC-V ISA doesn't specify a memory layout for the PLIC, the
  39   "sifive,plic-1.0.0" device is a concrete implementation of the PLIC that
  40   contains a specific memory layout, which is documented in chapter 8 of the
  41   SiFive U5 Coreplex Series Manual <https://static.dev.sifive.com/U54-MC-RVCoreIP.pdf>.
  42
  43   The thead,c900-plic is different from sifive,plic-1.0.0 in opensbi, the
  44   T-HEAD PLIC implementation requires setting a delegation bit to allow access
  45   from S-mode. So add thead,c900-plic to distinguish them.
  46
  47 maintainers:
  48   - Paul Walmsley  <paul.walmsley@sifive.com>
  49   - Palmer Dabbelt <palmer@dabbelt.com>
  50
  51 properties:
  52   compatible:
  53     oneOf:
  54       - items:
  55           - enum:
  56               - renesas,r9a07g043-plic
  57           - const: andestech,nceplic100
  58       - items:
  59           - enum:
  60               - canaan,k210-plic
  61               - sifive,fu540-c000-plic
  62               - spacemit,k1-plic
  63               - starfive,jh7100-plic
  64               - starfive,jh7110-plic
  65           - const: sifive,plic-1.0.0
  66       - items:
  67           - enum:
  68               - allwinner,sun20i-d1-plic
  69               - sophgo,cv1800b-plic
  70               - sophgo,cv1812h-plic
  71               - sophgo,sg2002-plic
  72               - sophgo,sg2042-plic
  73               - thead,th1520-plic
  74           - const: thead,c900-plic
  75       - items:
  76           - const: sifive,plic-1.0.0
  77           - const: riscv,plic0
  78         deprecated: true
  79         description: For the QEMU virt machine only
  80
  81   reg:
  82     maxItems: 1
  83
  84   '#address-cells':
  85     const: 0
  86
  87   '#interrupt-cells': true
  88
  89   interrupt-controller: true
  90
  91   interrupts-extended:
  92     minItems: 1
  93     maxItems: 15872
  94     description:
  95       Specifies which contexts are connected to the PLIC, with "-1" specifying
  96       that a context is not present. Each node pointed to should be a
  97       riscv,cpu-intc node, which has a riscv node as parent.
  98
  99   riscv,ndev:
 100     $ref: /schemas/types.yaml#/definitions/uint32
 101     description:
 102       Specifies how many external interrupts are supported by this controller.
 103
 104   clocks: true
 105
 106   power-domains: true
 107
 108   resets: true
 109
 110 required:
 111   - compatible
 112   - '#address-cells'
 113   - '#interrupt-cells'
 114   - interrupt-controller
 115   - reg
 116   - interrupts-extended
 117   - riscv,ndev
 118
 119 allOf:
 120   - if:
 121       properties:
 122         compatible:
 123           contains:
 124             enum:
 125               - andestech,nceplic100
 126               - thead,c900-plic
 127
 128     then:
 129       properties:
 130         '#interrupt-cells':
 131           const: 2
 132
 133     else:
 134       properties:
 135         '#interrupt-cells':
 136           const: 1
 137
 138   - if:
 139       properties:
 140         compatible:
 141           contains:
 142             const: renesas,r9a07g043-plic
 143
 144     then:
 145       properties:
 146         clocks:
 147           maxItems: 1
 148
 149         power-domains:
 150           maxItems: 1
 151
 152         resets:
 153           maxItems: 1
 154
 155       required:
 156         - clocks
 157         - power-domains
 158         - resets
 159
 160 additionalProperties: false
 161
 162 examples:
 163   - |
 164     plic: interrupt-controller@c000000 {
 165       #address-cells = <0>;
 166       #interrupt-cells = <1>;
 167       compatible = "sifive,fu540-c000-plic", "sifive,plic-1.0.0";
 168       interrupt-controller;
 169       interrupts-extended = <&cpu0_intc 11>,
 170                             <&cpu1_intc 11>, <&cpu1_intc 9>,
 171                             <&cpu2_intc 11>, <&cpu2_intc 9>,
 172                             <&cpu3_intc 11>, <&cpu3_intc 9>,
 173                             <&cpu4_intc 11>, <&cpu4_intc 9>;
 174       reg = <0xc000000 0x4000000>;
 175       riscv,ndev = <10>;
 176     };