1 files changed, 58 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/sim/devices/irq.py b/debug/risc-v-gsp-rm-vm/sim/devices/irq.py
new file mode 100644
index 0000000..7ce63fb
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/sim/devices/irq.py
@@ -0,0 +1,58 @@
+"""IRQ routing seam.
+
+Evidence kind: **hardware register/field header + observed access pattern.**
+
+The GSP boot handshake sets the falcon ``IRQSSET`` HALT bit (bit 4) after
+writing MAILBOX0/DEBUGINFO, and the boot code reads ``FALCON_IRQSTAT``; the
+libos kernel owns the RISC-V-local ``RISCV_IRQMSET``/``IRQMCLR``/``IRQMASK``
+group.  This module aggregates those two sources behind one object so a
+future core-interrupt model can consume a single ``pending()`` surface.
+
+It does **not** deliver interrupts to the machine's hart: mstatus/mie/mip/
+mtvec trap entry is not modelled (documented unknown).  It only makes the
+routing state explicit and serialisable.
+"""
+from __future__ import annotations
+
+# Falcon IRQSSET/IRQSCLR bit positions used by the boot handshake (header
+# field list; only the ones with proven firmware use are named).
+FALCON_IRQ_GPTMR = 1 << 0
+FALCON_IRQ_WDTMR = 1 << 1
+FALCON_IRQ_MTHD = 1 << 2
+FALCON_IRQ_CTXSW = 1 << 3
+FALCON_IRQ_HALT = 1 << 4
+FALCON_IRQ_EXTERR = 1 << 5
+FALCON_IRQ_SWGEN0 = 1 << 6
+FALCON_IRQ_SWGEN1 = 1 << 7
+FALCON_IRQ_DMA = 1 << 16
+FALCON_IRQ_SHA = 1 << 17
+
+
+class IrqRouter:
+    """Aggregate falcon + RISC-V-local interrupt state."""
+
+    name = "irq"
+
+    def __init__(self, *, falcon=None, priscv=None):
+        self.falcon = falcon
+        self.priscv = priscv
+
+    def falcon_status(self) -> int:
+        return self.falcon.irq_status if self.falcon is not None else 0
+
+    def riscv_mask(self) -> int:
+        return self.priscv.irq_mask if self.priscv is not None else 0
+
+    def pending(self) -> dict:
+        """Raw pending state; delivery is deliberately not modelled."""
+        return {
+            "falcon_irq_status": self.falcon_status(),
+            "falcon_halt": bool(self.falcon_status() & FALCON_IRQ_HALT),
+            "riscv_irq_mask": self.riscv_mask(),
+        }
+
+    def state(self) -> dict:
+        return self.pending()
+
+    def reset(self) -> None:
+        pass