[RFC PATCH 0/2] Introduce INTC and VIRQ layer prototypes

[RFC PATCH 0/2] Introduce INTC and VIRQ layer prototypes

[Raymond Mao]

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

This RFC introduces INTC and VIRQ layers for APLIC wired interrupt
support in OpenSBI.

In the current OpenSBI implementation, APLIC support primarily focuses
on initialization and delegation, while external interrupt handling
for wired interrupts remains largely stubbed. As a result:
- There is no generic mechanism for OpenSBI drivers or platforms to
  register handlers for wired interrupt lines.
- Interrupt dispatch remains tightly coupled to specific irqchip
  implementations.

The goal is to introduce a small, extensible abstraction INTC
(Interrupt Controller) layer to hide the HW details and provide
abstract operations like interrupt provider registration,
claim/complete/mask/unmask operations with IRQ number mapping to avoid
exposure of hwirq.

VIRQ (Virtual IRQ) layer is on top of INTC, providing IRQ state
management via per-(domain,hart) IRQ pending queue, with courier
dispatching and interface to enqueue/pop/complete an IRQ.

Raymond Mao (2):
  lib: sbi: introduce INTC abstraction for wired interrupts
  lib: sbi: Add VIRQ layer

 sbi_intc.h | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 sbi_virq.h | 71 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 170 insertions(+)
 create mode 100644 sbi_intc.h
 create mode 100644 sbi_virq.h

-- 
2.25.1


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

[RFC PATCH 1/2] lib: sbi: introduce INTC abstraction for wired interrupts

[Raymond Mao]

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

Add a wired interrupt-controller (INTC) abstraction to OpenSBI.
This introduces a small provider interface based on
claim/complete/mask/unmak semantics, allowing to register a wired
interrupt controller as a provider.
Plus, add virtual IRQ number mapping to avoid exposure of hwirq.

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

diff --git a/sbi_intc.h b/sbi_intc.h
new file mode 100644
index 00000000..f51974c9
--- /dev/null
+++ b/sbi_intc.h
@@ -0,0 +1,99 @@
+/*
+ * SPDX-License-Identifier: BSD-2-Clause
+ *
+ * Copyright (c) 2026 RISCstar Solutions Corporation.
+ *
+ * Author: Raymond Mao <raymond.mao@riscstar.com>
+ */
+
+#ifndef __SBI_INTC_H__
+#define __SBI_INTC_H__
+
+#include <sbi/sbi_types.h>
+
+/* Handler for a specified IRQ number */
+typedef int (*sbi_intc_irq_handler_t)(u32 irq, void *priv);
+
+/*
+ * Provider capabilities, at the moment it contains the maximum valid source ID
+ * but extensible in the future
+ */
+struct sbi_intc_provider_caps {
+	/*
+	 * Maximum supported wired source ID for this provider.
+	 *
+	 * For APLIC this corresponds to the highest valid source ID (1..N).
+	 * The INTC core treats this as an abstract provider source ID space.
+	 */
+	u32 max_src;
+};
+
+/* Provider operations */
+struct sbi_intc_provider_ops {
+	/*
+	 * Query provider capabilities.
+	 *
+	 * This avoids exposing provider-specific limits (such as APLIC
+	 * num_source) through the registration API.
+	 */
+	int (*get_caps)(void *ctx, struct sbi_intc_provider_caps *caps);
+
+	/*
+	 * Claim a pending wired interrupt on current hart.
+	 * Returns:
+	 *   SBI_OK      : *hwirq is valid
+	 *   SBI_ENOENT  : no pending wired interrupt
+	 *   <0          : error
+	 */
+	int (*claim)(void *ctx, u32 *irq);
+
+	/*
+	 * Complete/acknowledge a previously claimed wired interrupt
+	 * (if required by HW).
+	 * Some HW may not require an explicit completion.
+	 */
+	void (*complete)(void *ctx, u32 irq);
+
+	/*
+	 * mask/unmask a wired interrupt line.
+	 *
+	 * These are required for reliable couriering of level-triggered device
+	 * interrupts to S-mode: mask in M-mode before enqueueing, and unmask
+	 * after S-mode has cleared the device interrupt source.
+	 */
+	void (*mask)(void *ctx, u32 irq);
+	void (*unmask)(void *ctx, u32 irq);
+};
+
+/* Register the active wired interrupt provider, e.g. APLIC, via ops and ctx */
+int sbi_intc_register_provider(const struct sbi_intc_provider_ops *ops,
+			       void *ctx);
+
+/*
+ * Optional: map a IRQ number (irq) to a hardware wired IRQ (hwirq).
+ *
+ * If no explicit mapping exists, 'irq==hwirq' is assumed.
+ *
+ * This allows upper layers (e.g. VIRQ courier/emulation) to use stable irq
+ * identifiers without exposing the wired controller's hwirq numbering.
+ */
+int sbi_intc_map_irq(u32 irq, u32 hwirq);
+int sbi_intc_unmap_irq(u32 irq);
+u32 sbi_intc_irq_to_hwirq(u32 irq);
+u32 sbi_intc_hwirq_to_irq(u32 hwirq);
+
+/* Set/clear handler for a specified IRQ number */
+int sbi_intc_set_handler(u32 irq, sbi_intc_irq_handler_t handler, void *priv);
+int sbi_intc_clear_handler(u32 irq);
+
+/*
+ * Platform independent mask/unmak wrappers on top of platform registered
+ * mask/unmask ops functions.
+ */
+void sbi_intc_mask_irq(u32 irq);
+void sbi_intc_unmask_irq(u32 irq);
+
+/* External interrupt handler (for irqchip device hook 'irqchip.irq_handle') */
+int sbi_intc_handle_external_irq(void);
+
+#endif
-- 
2.25.1


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

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

[Raymond Mao]

From: Raymond Mao <raymond.mao@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@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@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


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

Re: [RFC PATCH 1/2] lib: sbi: introduce INTC abstraction for wired interrupts

[Anup Patel]

On Tue, Jan 27, 2026 at 8:54 PM Raymond Mao <raymondmaoca@gmail.com> wrote:
>
> From: Raymond Mao <raymond.mao@riscstar.com>
>
> Add a wired interrupt-controller (INTC) abstraction to OpenSBI.
> This introduces a small provider interface based on
> claim/complete/mask/unmak semantics, allowing to register a wired
> interrupt controller as a provider.
> Plus, add virtual IRQ number mapping to avoid exposure of hwirq.
>
> Signed-off-by: Raymond Mao <raymond.mao@riscstar.com>
> ---
>  sbi_intc.h | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 99 insertions(+)
>  create mode 100644 sbi_intc.h
>
> diff --git a/sbi_intc.h b/sbi_intc.h
> new file mode 100644
> index 00000000..f51974c9
> --- /dev/null
> +++ b/sbi_intc.h
> @@ -0,0 +1,99 @@
> +/*
> + * SPDX-License-Identifier: BSD-2-Clause
> + *
> + * Copyright (c) 2026 RISCstar Solutions Corporation.
> + *
> + * Author: Raymond Mao <raymond.mao@riscstar.com>
> + */
> +
> +#ifndef __SBI_INTC_H__
> +#define __SBI_INTC_H__
> +
> +#include <sbi/sbi_types.h>
> +
> +/* Handler for a specified IRQ number */
> +typedef int (*sbi_intc_irq_handler_t)(u32 irq, void *priv);
> +
> +/*
> + * Provider capabilities, at the moment it contains the maximum valid source ID
> + * but extensible in the future
> + */
> +struct sbi_intc_provider_caps {
> +       /*
> +        * Maximum supported wired source ID for this provider.
> +        *
> +        * For APLIC this corresponds to the highest valid source ID (1..N).
> +        * The INTC core treats this as an abstract provider source ID space.
> +        */
> +       u32 max_src;
> +};
> +
> +/* Provider operations */
> +struct sbi_intc_provider_ops {
> +       /*
> +        * Query provider capabilities.
> +        *
> +        * This avoids exposing provider-specific limits (such as APLIC
> +        * num_source) through the registration API.
> +        */
> +       int (*get_caps)(void *ctx, struct sbi_intc_provider_caps *caps);

This callback is not needed instead you driver can pass max_src
as parameter to sbi_intc_register_provider()

> +
> +       /*
> +        * Claim a pending wired interrupt on current hart.
> +        * Returns:
> +        *   SBI_OK      : *hwirq is valid
> +        *   SBI_ENOENT  : no pending wired interrupt
> +        *   <0          : error
> +        */
> +       int (*claim)(void *ctx, u32 *irq);
> +
> +       /*
> +        * Complete/acknowledge a previously claimed wired interrupt
> +        * (if required by HW).
> +        * Some HW may not require an explicit completion.
> +        */
> +       void (*complete)(void *ctx, u32 irq);

All provider callbacks should take hwirq as a parameter.

> +
> +       /*
> +        * mask/unmask a wired interrupt line.
> +        *
> +        * These are required for reliable couriering of level-triggered device
> +        * interrupts to S-mode: mask in M-mode before enqueueing, and unmask
> +        * after S-mode has cleared the device interrupt source.
> +        */
> +       void (*mask)(void *ctx, u32 irq);
> +       void (*unmask)(void *ctx, u32 irq);

Same as above.

> +};
> +
> +/* Register the active wired interrupt provider, e.g. APLIC, via ops and ctx */
> +int sbi_intc_register_provider(const struct sbi_intc_provider_ops *ops,
> +                              void *ctx);
> +
> +/*
> + * Optional: map a IRQ number (irq) to a hardware wired IRQ (hwirq).
> + *
> + * If no explicit mapping exists, 'irq==hwirq' is assumed.
> + *
> + * This allows upper layers (e.g. VIRQ courier/emulation) to use stable irq
> + * identifiers without exposing the wired controller's hwirq numbering.
> + */
> +int sbi_intc_map_irq(u32 irq, u32 hwirq);
> +int sbi_intc_unmap_irq(u32 irq);

The virq courier/emulation will be an independent module
so drop these functions.

Also, the driver should have no control on how irq is mapped
to hwirq. The INTC framework will internally manage irq to
hwirq mapping for a particular provider.

> +u32 sbi_intc_irq_to_hwirq(u32 irq);
> +u32 sbi_intc_hwirq_to_irq(u32 hwirq);
> +
> +/* Set/clear handler for a specified IRQ number */
> +int sbi_intc_set_handler(u32 irq, sbi_intc_irq_handler_t handler, void *priv);
> +int sbi_intc_clear_handler(u32 irq);
> +
> +/*
> + * Platform independent mask/unmak wrappers on top of platform registered
> + * mask/unmask ops functions.
> + */
> +void sbi_intc_mask_irq(u32 irq);
> +void sbi_intc_unmask_irq(u32 irq);
> +
> +/* External interrupt handler (for irqchip device hook 'irqchip.irq_handle') */
> +int sbi_intc_handle_external_irq(void);
> +
> +#endif

Also, introducing a new set of sbi_intc.c and sbi_intc.h is
not going to fly.

We had already created sbi_irqchip.c and sbi_irqchip.h to
manage external interrupts so the goal should be to enhance
these frameworks.

Regards,
Anup

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

Re: [RFC PATCH 1/2] lib: sbi: introduce INTC abstraction for wired interrupts

[Raymond Mao]

Hi Anup,

On Fri, Jan 30, 2026 at 2:48 AM Anup Patel <anup@brainfault.org> wrote:
>
> On Tue, Jan 27, 2026 at 8:54 PM Raymond Mao <raymondmaoca@gmail.com> wrote:
> >
> > From: Raymond Mao <raymond.mao@riscstar.com>
> >
> > Add a wired interrupt-controller (INTC) abstraction to OpenSBI.
> > This introduces a small provider interface based on
> > claim/complete/mask/unmak semantics, allowing to register a wired
> > interrupt controller as a provider.
> > Plus, add virtual IRQ number mapping to avoid exposure of hwirq.
> >
> > Signed-off-by: Raymond Mao <raymond.mao@riscstar.com>
> > ---
> >  sbi_intc.h | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 99 insertions(+)
> >  create mode 100644 sbi_intc.h
> >
> > diff --git a/sbi_intc.h b/sbi_intc.h
> > new file mode 100644
> > index 00000000..f51974c9
> > --- /dev/null
> > +++ b/sbi_intc.h
> > @@ -0,0 +1,99 @@
> > +/*
> > + * SPDX-License-Identifier: BSD-2-Clause
> > + *
> > + * Copyright (c) 2026 RISCstar Solutions Corporation.
> > + *
> > + * Author: Raymond Mao <raymond.mao@riscstar.com>
> > + */
> > +
> > +#ifndef __SBI_INTC_H__
> > +#define __SBI_INTC_H__
> > +
> > +#include <sbi/sbi_types.h>
> > +
> > +/* Handler for a specified IRQ number */
> > +typedef int (*sbi_intc_irq_handler_t)(u32 irq, void *priv);
> > +
> > +/*
> > + * Provider capabilities, at the moment it contains the maximum valid source ID
> > + * but extensible in the future
> > + */
> > +struct sbi_intc_provider_caps {
> > +       /*
> > +        * Maximum supported wired source ID for this provider.
> > +        *
> > +        * For APLIC this corresponds to the highest valid source ID (1..N).
> > +        * The INTC core treats this as an abstract provider source ID space.
> > +        */
> > +       u32 max_src;
> > +};
> > +
> > +/* Provider operations */
> > +struct sbi_intc_provider_ops {
> > +       /*
> > +        * Query provider capabilities.
> > +        *
> > +        * This avoids exposing provider-specific limits (such as APLIC
> > +        * num_source) through the registration API.
> > +        */
> > +       int (*get_caps)(void *ctx, struct sbi_intc_provider_caps *caps);
>
> This callback is not needed instead you driver can pass max_src
> as parameter to sbi_intc_register_provider()
>

I think it will be more extensible for the future to have get_caps,
though currently it holds only the max source.

> > +
> > +       /*
> > +        * Claim a pending wired interrupt on current hart.
> > +        * Returns:
> > +        *   SBI_OK      : *hwirq is valid
> > +        *   SBI_ENOENT  : no pending wired interrupt
> > +        *   <0          : error
> > +        */
> > +       int (*claim)(void *ctx, u32 *irq);
> > +
> > +       /*
> > +        * Complete/acknowledge a previously claimed wired interrupt
> > +        * (if required by HW).
> > +        * Some HW may not require an explicit completion.
> > +        */
> > +       void (*complete)(void *ctx, u32 irq);
>
> All provider callbacks should take hwirq as a parameter.

According to our last sync-up, you would like a virtual IRQ number
mapping, so do you prefer moving the hwirq mapping from INTC to VIRQ?

>
> > +
> > +       /*
> > +        * mask/unmask a wired interrupt line.
> > +        *
> > +        * These are required for reliable couriering of level-triggered device
> > +        * interrupts to S-mode: mask in M-mode before enqueueing, and unmask
> > +        * after S-mode has cleared the device interrupt source.
> > +        */
> > +       void (*mask)(void *ctx, u32 irq);
> > +       void (*unmask)(void *ctx, u32 irq);
>
> Same as above.
>
> > +};
> > +
> > +/* Register the active wired interrupt provider, e.g. APLIC, via ops and ctx */
> > +int sbi_intc_register_provider(const struct sbi_intc_provider_ops *ops,
> > +                              void *ctx);
> > +
> > +/*
> > + * Optional: map a IRQ number (irq) to a hardware wired IRQ (hwirq).
> > + *
> > + * If no explicit mapping exists, 'irq==hwirq' is assumed.
> > + *
> > + * This allows upper layers (e.g. VIRQ courier/emulation) to use stable irq
> > + * identifiers without exposing the wired controller's hwirq numbering.
> > + */
> > +int sbi_intc_map_irq(u32 irq, u32 hwirq);
> > +int sbi_intc_unmap_irq(u32 irq);
>
> The virq courier/emulation will be an independent module
> so drop these functions.
>
> Also, the driver should have no control on how irq is mapped
> to hwirq. The INTC framework will internally manage irq to
> hwirq mapping for a particular provider.
>
> > +u32 sbi_intc_irq_to_hwirq(u32 irq);
> > +u32 sbi_intc_hwirq_to_irq(u32 hwirq);
> > +
> > +/* Set/clear handler for a specified IRQ number */
> > +int sbi_intc_set_handler(u32 irq, sbi_intc_irq_handler_t handler, void *priv);
> > +int sbi_intc_clear_handler(u32 irq);
> > +
> > +/*
> > + * Platform independent mask/unmak wrappers on top of platform registered
> > + * mask/unmask ops functions.
> > + */
> > +void sbi_intc_mask_irq(u32 irq);
> > +void sbi_intc_unmask_irq(u32 irq);
> > +
> > +/* External interrupt handler (for irqchip device hook 'irqchip.irq_handle') */
> > +int sbi_intc_handle_external_irq(void);
> > +
> > +#endif
>
> Also, introducing a new set of sbi_intc.c and sbi_intc.h is
> not going to fly.
>
> We had already created sbi_irqchip.c and sbi_irqchip.h to
> manage external interrupts so the goal should be to enhance
> these frameworks.
>

All right, I can move the implementation from INTC to sbi_irqchip.

Regards,
Raymond

> Regards,
> Anup

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