[PATCH 10/10] docs: domain: document sysirq VIRQ mapping and routing rules

[Raymond Mao <raymondmaoca@gmail.com>]

From: Raymond Mao <raymond.mao@riscstar.com>

Document the DT binding semantics for opensbi,mpxy-sysirq nodes,
including how interrupts-extended entry order determines per-channel
VIRQ numbers and how opensbi,domain selects the destination OpenSBI
domain.
Add a rpmi_sysirq_intc example under /chosen/opensbi-domains.

Signed-off-by: Raymond Mao <raymond.mao@riscstar.com>
---
 docs/domain_support.md | 63 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/docs/domain_support.md b/docs/domain_support.md
index 93186c4a..8d474e50 100644
--- a/docs/domain_support.md
+++ b/docs/domain_support.md
@@ -198,6 +198,48 @@ The DT properties of a domain instance DT node are as follows:
 * **system-suspend-allowed** (Optional) - A boolean flag representing
   whether the domain instance is allowed to do system suspend.
 
+### Domain SysIRQ / VIRQ Routing Node
+
+The domain configuration DT node can also contain sysirq routing nodes for
+describing how a physical interrupt source should be mapped to a VIRQ and
+routed to a target domain. In local DTS overlays this node is often labeled
+`rpmi_sysirq_intc`, but OpenSBI matches it by compatible string rather than
+by node name or label.
+
+The DT properties of a domain sysirq routing DT node are as follows:
+
+* **compatible** (Mandatory) - The compatible string of the sysirq routing
+  node. This DT property should have value *"opensbi,mpxy-sysirq"*
+* **interrupt-controller** (Mandatory) - Marks the node as an interrupt
+  controller for child references.
+* **#interrupt-cells** (Mandatory) - Number of cells used by this interrupt
+  controller. Current examples use value **<1>**.
+* **interrupts-extended** (Mandatory) - The list of routed physical interrupt
+  sources. Each entry is `<&irqchip hwirq flags>`. OpenSBI interprets the
+  entry order as the VIRQ number within the selected MPXY channel, starting
+  from zero:
+  VIRQ 0 maps to entry 0, VIRQ 1 maps to entry 1, and so on.
+* **opensbi,mpxy-channel-id** (Mandatory) - The MPXY channel identifier used
+  as the VIRQ number space for this sysirq node.
+* **opensbi,domain** (Mandatory) - Phandle to the target domain instance DT
+  node. All physical interrupts listed in **interrupts-extended** are routed
+  to this domain after being mapped to VIRQs.
+
+The resulting VIRQ rule for a sysirq node is:
+
+* **mapping** - `(irqchip phandle, hwirq, entry index)` from
+  **interrupts-extended** becomes `(channel-id, virq)`
+* **routing** - `opensbi,domain` selects the destination OpenSBI domain for
+  all VIRQs created from that sysirq node
+
+In other words, a node labeled `rpmi_sysirq_intc` typically means:
+
+* the physical interrupt source is described by one **interrupts-extended**
+  entry
+* the VIRQ number is the position of that entry in the list
+* the VIRQ namespace is selected by **opensbi,mpxy-channel-id**
+* the destination domain is selected by **opensbi,domain**
+
 ### Assigning HART To Domain Instance
 
 By default, all HARTs are assigned to **the ROOT domain**. The OpenSBI
@@ -270,6 +312,27 @@ be done:
                 possible-harts = <&cpu1 &cpu2 &cpu3 &cpu4>;
                 regions = <&tmem 0x0>, <&tuart 0x0>, <&allmem 0x3f>;
             };
+
+            rpmi_sysirq_intc: interrupt-controller {
+                compatible = "opensbi,mpxy-sysirq";
+                interrupt-controller;
+                #interrupt-cells = <1>;
+
+                /*
+                 * VIRQ numbers are assigned from zero in
+                 * interrupts-extended order.
+                 */
+                interrupts-extended =
+                    <&aplic_m 10 4>, /* VIRQ 0 */
+                    <&aplic_m 20 4>, /* VIRQ 1 */
+                    <&aplic_m 21 4>; /* VIRQ 2 */
+
+                /* Select the VIRQ namespace / MPXY channel. */
+                opensbi,mpxy-channel-id = <4>;
+
+                /* Route all VIRQs from this node to udomain. */
+                opensbi,domain = <&udomain>;
+            };
         };
     };
 
-- 
2.25.1


-- 
opensbi mailing list
opensbi@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/opensbi