[PATCH v1 1/3] dt-bindings: interrupt-controller: Require trigger type for T-HEAD PLIC

[Samuel Holland]

The RISC-V PLIC specification unfortunately allows PLIC implementations
to ignore edges seen while an edge-triggered interrupt is being handled:

  Depending on the design of the device and the interrupt handler,
  in between sending an interrupt request and receiving notice of its
  handler’s completion, the gateway might either ignore additional
  matching edges or increment a counter of pending interrupts.

For PLICs with that misfeature, software needs to know the trigger type
of each interrupt. This allows it to work around the issue by completing
edge-triggered interrupts before handling them. Such a workaround is
required to avoid missing any edges.

The T-HEAD C9xx PLIC is an example of a PLIC with this behavior.

Signed-off-by: Samuel Holland <samuel at sholland.org>
---

 .../sifive,plic-1.0.0.yaml                    | 31 ++++++++++++++++---
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml
index 27092c6a86c4..3c589cbca851 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml
@@ -26,9 +26,13 @@ description:
   with priority below this threshold will not cause the PLIC to raise its
   interrupt line leading to the context.
 
-  While the PLIC supports both edge-triggered and level-triggered interrupts,
-  interrupt handlers are oblivious to this distinction and therefore it is not
-  specified in the PLIC device-tree binding.
+  The PLIC supports both edge-triggered and level-triggered interrupts. For
+  edge-triggered interrupts, the RISC-V PLIC spec allows two responses to edges
+  seen while an interrupt handler is active; the PLIC may either queue them or
+  ignore them. In the first case, handlers are oblivious to the trigger type, so
+  it is not included in the interrupt specifier. In the second case, software
+  needs to know the trigger type, so it can reorder the interrupt flow to avoid
+  missing interrupts.
 
   While the RISC-V ISA doesn't specify a memory layout for the PLIC, the
   "sifive,plic-1.0.0" device is a concrete implementation of the PLIC that
@@ -65,7 +69,8 @@ properties:
     const: 0
 
   '#interrupt-cells':
-    const: 1
+    minimum: 1
+    maximum: 2
 
   interrupt-controller: true
 
@@ -91,6 +96,24 @@ required:
   - interrupts-extended
   - riscv,ndev
 
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - thead,c900-plic
+
+    then:
+      properties:
+        '#interrupt-cells':
+          const: 2
+
+    else:
+      properties:
+        '#interrupt-cells':
+          const: 1
+
 additionalProperties: false
 
 examples:
-- 
2.35.1