C++ Irq interface, see IRQs for the C interface. More...

#include <irq>

Inheritance diagram for L4::Irq:

Collaboration diagram for L4::Irq:

Public Member Functions
l4_msgtag_t	bind_vcpu (L4::Cap< Thread > const &thread, l4_umword_t cfg, l4_utcb_t *utcb=l4_utcb()) noexcept
	Bind a thread to this Irq for vCPU interrupt forwarding.

l4_msgtag_t	detach (l4_utcb_t *utcb=l4_utcb()) noexcept
	Detach from this interrupt.

l4_msgtag_t	receive (l4_timeout_t timeout=L4_IPC_NEVER, l4_utcb_t *utcb=l4_utcb()) noexcept
	Unmask and wait for this IRQ.

l4_msgtag_t	wait (l4_umword_t label, l4_timeout_t timeout=L4_IPC_NEVER, l4_utcb_t utcb=l4_utcb()) noexcept
	Unmask IRQ and (open) wait for any message.

l4_msgtag_t	unmask (l4_utcb_t *utcb=l4_utcb()) noexcept
	Unmask this IRQ.

Public Member Functions inherited from L4::Triggerable
l4_msgtag_t	trigger (l4_utcb_t *utcb=l4_utcb()) noexcept
	Trigger the object.

Public Member Functions inherited from L4::Irq_eoi
l4_msgtag_t	unmask (unsigned irqnum, l4_umword_t label=0, l4_timeout_t to=L4_IPC_NEVER, l4_utcb_t utcb=l4_utcb()) noexcept
	Unmask the given interrupt line.

Public Member Functions inherited from L4::Rcv_endpoint
l4_msgtag_t	bind_thread (Ipc::Cap< Thread > t, l4_umword_t label)
	Bind a thread to an IPC receive endpoint.

Public Member Functions inherited from L4::Kobject
l4_msgtag_t	dec_refcnt (l4_mword_t diff, l4_utcb_t *utcb=l4_utcb())
	Decrement the in kernel reference counter for the object.

Additional Inherited Members
Protected Types inherited from L4::Kobject_2t< Irq, Triggerable, Rcv_endpoint, L4_PROTO_IRQ_SENDER >
typedef Irq	Class
	The target interface type (inheriting from Kobject_t)

typedef Typeid::Iface< PROTO, Irq >	__Iface
	The interface description for the derived class.

typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, Typeid::Merge_list< typename Base1::__Iface_list, typename Base2::__Iface_list > >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.

Protected Types inherited from L4::Kobject_t< Triggerable, Irq_eoi, L4_PROTO_IRQ >
typedef Triggerable	Class
	The target interface type (inheriting from Kobject_t)

typedef Typeid::Iface< PROTO, Triggerable >	__Iface
	The interface description for the derived class.

typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.

Protected Types inherited from L4::Kobject_t< Rcv_endpoint, Kobject, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
typedef Rcv_endpoint	Class
	The target interface type (inheriting from Kobject_t)

typedef Typeid::Iface< PROTO, Rcv_endpoint >	__Iface
	The interface description for the derived class.

typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.

Protected Member Functions inherited from L4::Kobject_2t< Irq, Triggerable, Rcv_endpoint, L4_PROTO_IRQ_SENDER >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.

Protected Member Functions inherited from L4::Kobject_t< Triggerable, Irq_eoi, L4_PROTO_IRQ >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.

Protected Member Functions inherited from L4::Kobject_t< Rcv_endpoint, Kobject, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.

Protected Member Functions inherited from L4::Kobject
l4_cap_idx_t	cap () const noexcept
	Return capability selector.

Static Protected Member Functions inherited from L4::Kobject_2t< Irq, Triggerable, Rcv_endpoint, L4_PROTO_IRQ_SENDER >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Static Protected Member Functions inherited from L4::Kobject_t< Triggerable, Irq_eoi, L4_PROTO_IRQ >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Static Protected Member Functions inherited from L4::Kobject_t< Rcv_endpoint, Kobject, L4_PROTO_KOBJECT, Type_info::Demand_t< 1 > >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Detailed Description

C++ Irq interface, see IRQs for the C interface.

Note: "IRQ" is short for "interrupt request". This is often used interchangeably for "interrupt"

The Irq class provides access to abstract interrupts provided by the microkernel. Interrupts may be

hardware interrupts provided by the platform interrupt controller,
virtual device interrupts provided by the microkernel's virtual devices (virtual serial or trace buffer) or
virtual interrupts that can be triggered by user programs (IRQs) via the inherited method L4::Triggerable::trigger().

For hardware and virtual device interrupts the Irq object must be bound to an interrupt source, see L4::Icu. To receive interrupts, the Irq object must be bound to a thread, see L4::Rcv_endpoint.

Irq objects can be created using a factory, see the L4::Factory API (L4::Factory::create()).

Include File: #include <l4/sys/irq>

irq
C++ Irq interface.

For the C interface refer to the IRQs API for an overview.

Examples: examples/libs/l4re/c++/shared_ds/ds_clnt.cc.

Definition at line 120 of file irq.

Member Function Documentation

◆ bind_vcpu()

l4_msgtag_t L4::Irq::bind_vcpu	(	L4::Cap< Thread > const &	thread,
		l4_umword_t	cfg,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Bind a thread to this Irq for vCPU interrupt forwarding.

If the interrupt is triggered, the kernel will directly inject the interrupt into the guest. This requires that the thread is currently in extended vCPU user mode. Otherwise the interrupt will stay pending and gets injected on the next vCPU user mode transition. Optionally a doorbell Irq can be registered on the thread (see Thread::register_doorbell_irq()) that is triggered in this case.

If a guest has acknowledged the interrupt but has not yet issued an EOI (i.e. the interrupt is in "active" state), it is not possible to bind the Irq to a new thread object. Either wait for the guest to issue the EOI or detach() from the current thread. In this case the interrupt will stay active in the guest and it is the responsibility of the VMM to handle the eventual EOI of the guest.

Parameters

thread	Thread object that shall be bound to this Irq.
cfg	Architecture specific interrupt configuration.
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns: Syscall return tag

Return values

-L4_EPERM	No L4_CAP_FPAGE_S rights on the capability used to invoke this operation.
-L4_EBUSY	Cannot bind to new thread because interrupt is active on previous thread and guest has to issue end-of-interrupt first.
-L4_ENOSYS	The kernel does not support direct interrupt forwarding.

Definition at line 156 of file irq.

References L4::Cap_base::cap(), and l4_irq_bind_vcpu_u().

Here is the call graph for this function:

◆ detach()

l4_msgtag_t L4::Irq::detach ( l4_utcb_t * utcb = l4_utcb() )

inlinenoexcept

Detach from this interrupt.

Parameters

utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns: Syscall return tag

Return values

0	Successfully detached, there was no interrupt pending.
1	Successfully detached, there was an interrupt pending.
2	Successfully detached, an active vIRQ was abandoned.
-L4_EPERM	No L4_CAP_FPAGE_S rights on the capability used to invoke this operation.

Definition at line 173 of file irq.

References l4_irq_detach_u().

Here is the call graph for this function:

◆ receive()

l4_msgtag_t L4::Irq::receive	(	l4_timeout_t	timeout = `L4_IPC_NEVER`,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Unmask and wait for this IRQ.

Parameters

timeout	Timeout.
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns: Syscall return tag

Note: If this is the function normally used for your IRQs consider using L4::Semaphore instead of L4::Irq.

Definition at line 188 of file irq.

References l4_irq_receive_u().

Here is the call graph for this function:

◆ unmask()

l4_msgtag_t L4::Irq::unmask ( l4_utcb_t * utcb = l4_utcb() )

inlinenoexcept

Unmask this IRQ.

Parameters

utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns: Syscall return tag for a send-only operation, this means there is no return value except L4_MSGTAG_ERROR indicating success or failure of the send operation. Use l4_ipc_error() to check for errors and do not use l4_error().

Irq::wait() and Irq::receive() operations already include an unmask(), do not use an extra unmask() in these cases.

Definition at line 218 of file irq.

References L4_IPC_NEVER, and unmask().

Referenced by unmask(), and wait().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wait()

l4_msgtag_t L4::Irq::wait	(	l4_umword_t *	label,
		l4_timeout_t	timeout = `L4_IPC_NEVER`,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Unmask IRQ and (open) wait for any message.

Parameters

label	The protected label shall be received here.
timeout	Timeout.
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. See l4_utcb.

Returns: Syscall return tag

Definition at line 201 of file irq.

References unmask().

Here is the call graph for this function:

The documentation for this class was generated from the following file:

l4/sys/irq

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ bind_vcpu()

◆ detach()

◆ receive()

◆ unmask()

◆ wait()