[PATCH v2 11/12] docs: domain: document sysirq VIRQ mapping and routing rules

[Raymond Mao]

From: Raymond Mao <raymond.mao at 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 SYSIRQ node example under /chosen/opensbi-domains.

Describe DT-driven courier registration and delivery to the owning
domain's boot hart. Summarize interrupt notification, claiming,
completion and deferred return domain switches.

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

diff --git a/docs/domain_support.md b/docs/domain_support.md
index 51737218..a2d40024 100644
--- a/docs/domain_support.md
+++ b/docs/domain_support.md
@@ -325,3 +325,58 @@ be done:
         ...
     };
 ```
+
+### SYSIRQ Node
+
+The SYSIRQ node describes physical interrupts delivered to a domain through
+an RPMI SYSTEM_IRQ channel over SBI MPXY. It should be placed under the
+domain configuration node.
+
+The DT properties of a SYSIRQ node are as follows:
+
+* **compatible** (Mandatory) - The compatible string of the SYSIRQ node.
+  This DT property should have value *"opensbi,mpxy-sysirq"*.
+* **interrupt-controller** (Optional) - Marks the node as a virtual interrupt
+  controller when it is referenced by other DT nodes.
+* **#interrupt-cells** (Optional) - Must be <1> when the node is used as an
+  interrupt controller. The interrupt specifier is the VIRQ number.
+* **interrupts-extended** (Mandatory) - The physical interrupt sources,
+  specified as <&irqchip hwirq flags> entries.
+* **opensbi,mpxy-channel-id** (Mandatory) - The unique SBI MPXY channel ID.
+  Each channel has its own VIRQ namespace.
+* **opensbi,domain** (Mandatory) - The phandle of the destination domain
+  instance node.
+
+Each interrupts-extended entry maps a physical interrupt to a VIRQ number
+starting from zero, in entry order. All entries in the node belong to the
+specified domain. Physical sources are identified by the interrupt controller
+and HWIRQ number; the same HWIRQ number on different controllers denotes
+different sources. Each physical source can belong to only one channel.
+The physical specifier must contain one HWIRQ cell and one flags cell.
+Physical delivery targets the domain's finalized boot HART. The current
+registration path supports wired M-mode interrupt controllers with masking
+and affinity operations. The interrupt controller must be configured to
+deliver these sources to M-mode rather than delegate them to S-mode.
+
+OpenSBI establishes the channel mappings and routing rules, then selects
+domain boot HARTs before enabling physical delivery. It notifies the
+destination domain through SEIP and switches to that domain if required.
+The payload claims pending interrupts through SYSIRQ_CLAIM and handles the
+device sources before completing them through the next CLAIM or the optional
+Yield ECALL. Return to a previously interrupted domain is permitted only
+after pending and claimed interrupts are drained. This completion and
+return-switch convention is specific to OpenSBI's domain courier.
+
+For example, the following node maps physical interrupt 10 to VIRQ 0 in
+channel 4 and delivers it to the boot HART of tdomain:
+
+```dts
+sysirq {
+    compatible = "opensbi,mpxy-sysirq";
+    interrupt-controller;
+    #interrupt-cells = <1>;
+    opensbi,mpxy-channel-id = <4>;
+    opensbi,domain = <&tdomain>;
+    interrupts-extended = <&aplic_m 10 4>;
+};
+```
-- 
2.25.1