[RFC PATCH 2/2] lib: sbi: Add VIRQ layer

[Raymond Mao]

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

Add virtual wired IRQ support on top of INTC with:
- per-(domain,hart) pending IRQ queue
- IRQ state management with courier handler and enqueue/pop/complete
  interface.

Signed-off-by: Raymond Mao <raymond.mao at riscstar.com>
---
 sbi_virq.h | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 sbi_virq.h

diff --git a/sbi_virq.h b/sbi_virq.h
new file mode 100644
index 00000000..7a3d3def
--- /dev/null
+++ b/sbi_virq.h
@@ -0,0 +1,71 @@
+/*
+ * SPDX-License-Identifier: BSD-2-Clause
+ *
+ * Copyright (c) 2026 RISCstar Solutions Corporation.
+ *
+ * Author: Raymond Mao <raymond.mao at riscstar.com>
+ */
+
+#ifndef __SBI_VIRQ_H__
+#define __SBI_VIRQ_H__
+
+#include <sbi/sbi_domain.h>
+#include <sbi/sbi_types.h>
+
+/*
+ * Keep the queue small for bring-up. If it overflows, we drop and warn.
+ */
+#define SBI_VIRQ_QSIZE  32
+
+/* per-(domain,hart) IRQ state */
+struct sbi_domain_virq_state {
+	spinlock_t lock;
+	u32 head;
+	u32 tail;
+	/* pending IRQ queue */
+	u32 q[SBI_VIRQ_QSIZE];
+};
+
+/* Per-domain VIRQ context */
+struct sbi_domain_virq_priv {
+	/* harts number of the domain */
+	u32 nharts;
+	/* IRQ states of all harts of the domain */
+	struct sbi_domain_virq_state st[];
+};
+
+/* Enqueue an interrupt (as seen by the generic INTC layer) for a domain. */
+int sbi_virq_enqueue(struct sbi_domain *dom, u32 irq);
+
+/*
+ * Complete a previously couriered irq for the current domain.
+ *
+ * This will unmask the interrupt line at the active INTC provider, allowing
+ * further interrupts once S-mode has cleared the device interrupt source.
+ */
+void sbi_virq_complete_thishart(u32 irq);
+
+/* Pop next pending irq for current domain on this hart. Returns 0 if none. */
+u32 sbi_virq_pop_thishart(void);
+
+/*
+ * Courier handler for wired INTC dispatch.
+ *
+ * Intended usage:
+ *   sbi_intc_set_handler(irq, sbi_virq_courier_handler, dom);
+ *
+ * It will enqueue (irq) for the provided domain and inject SSE on the
+ * current hart to notify S-mode.
+ */
+int sbi_virq_courier_handler(u32 irq, void *priv);
+
+/*
+ * Bind helper function: bind a given irq and register the courier handler
+ * for a domain.
+ */
+int sbi_virq_bind_irq_to_domain(u32 irq, struct sbi_domain *dom);
+
+/* Initialize per-domain virq state (alloc + lock init). */
+int sbi_virq_domain_init(struct sbi_domain *dom);
+
+#endif
-- 
2.25.1