C IRQ interface, see L4::Irq for the C++ interface. More...

Collaboration diagram for IRQs:

Enumerations
enum	L4_irq_mode { L4_IRQ_F_NONE = 0 , L4_IRQ_F_SET_MODE = 0x1 , L4_IRQ_F_LEVEL = 0x2 , L4_IRQ_F_EDGE = 0x0 , L4_IRQ_F_POS = 0x0 , L4_IRQ_F_NEG = 0x4 , L4_IRQ_F_BOTH = 0x8 , L4_IRQ_F_LEVEL_HIGH = L4_IRQ_F_SET_MODE \| L4_IRQ_F_LEVEL \| L4_IRQ_F_POS , L4_IRQ_F_LEVEL_LOW = L4_IRQ_F_SET_MODE \| L4_IRQ_F_LEVEL \| L4_IRQ_F_NEG , L4_IRQ_F_POS_EDGE = L4_IRQ_F_SET_MODE \| L4_IRQ_F_EDGE \| L4_IRQ_F_POS , L4_IRQ_F_NEG_EDGE = L4_IRQ_F_SET_MODE \| L4_IRQ_F_EDGE \| L4_IRQ_F_NEG , L4_IRQ_F_BOTH_EDGE = L4_IRQ_F_SET_MODE \| L4_IRQ_F_EDGE \| L4_IRQ_F_BOTH , L4_IRQ_F_MASK = 0xf , L4_IRQ_F_SET_WAKEUP = 0x10 , L4_IRQ_F_CLEAR_WAKEUP = 0x20 }
	Interrupt attributes. More...

Functions
l4_msgtag_t	l4_irq_detach (l4_cap_idx_t irq) L4_NOTHROW
	Detach from an interrupt source.

l4_msgtag_t	l4_irq_detach_u (l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
	Detach from this interrupt.

l4_msgtag_t	l4_irq_bind_vcpu (l4_cap_idx_t irq, l4_cap_idx_t thread, l4_umword_t cfg) L4_NOTHROW
	Bind a thread to this Irq for vCPU interrupt forwarding.

l4_msgtag_t	l4_irq_bind_vcpu_u (l4_cap_idx_t irq, l4_cap_idx_t thread, l4_umword_t cfg, l4_utcb_t *utcb) L4_NOTHROW
	Bind a thread to this Irq for vCPU interrupt forwarding.

l4_msgtag_t	l4_irq_trigger (l4_cap_idx_t irq) L4_NOTHROW
	Trigger an IRQ.

l4_msgtag_t	l4_irq_trigger_u (l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
	Trigger the object.

l4_msgtag_t	l4_irq_receive (l4_cap_idx_t irq, l4_timeout_t to) L4_NOTHROW
	Unmask and wait for specified IRQ.

l4_msgtag_t	l4_irq_receive_u (l4_cap_idx_t irq, l4_timeout_t timeout, l4_utcb_t *utcb) L4_NOTHROW
	Unmask and wait for this IRQ.

l4_msgtag_t	l4_irq_wait (l4_cap_idx_t irq, l4_umword_t *label, l4_timeout_t to) L4_NOTHROW
	Unmask IRQ and wait for any message.

l4_msgtag_t	l4_irq_wait_u (l4_cap_idx_t irq, l4_umword_t label, l4_timeout_t timeout, l4_utcb_t utcb) L4_NOTHROW
	Unmask IRQ and (open) wait for any message.

l4_msgtag_t	l4_irq_unmask (l4_cap_idx_t irq) L4_NOTHROW
	Unmask IRQ.

l4_msgtag_t	l4_irq_unmask_u (l4_cap_idx_t irq, l4_utcb_t *utcb) L4_NOTHROW
	Unmask this IRQ.

Detailed Description

C IRQ interface, see L4::Irq for the C++ interface.

The IRQ interface 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 l4_irq_trigger().

For hardware and virtual device interrupts the Irq object must be bound to an interrupt source, see Interrupt controller. To receive interrupts, the Irq object must be bound to a thread, see l4_rcv_ep_bind_thread().

IRQ objects can be created using a factory, see the Factory API (use l4_factory_create_irq()).

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

irq.h
C Irq interface.

For the C++ interface refer to the L4::Irq API for an overview.

Enumeration Type Documentation

◆ L4_irq_mode

enum L4_irq_mode

Interrupt attributes.

Enumerator
L4_IRQ_F_NONE	Flow types. None
L4_IRQ_F_SET_MODE	Valid flag, if not set, the set_mode operation does nothing.
L4_IRQ_F_LEVEL	Level triggered.
L4_IRQ_F_EDGE	Edge triggered.
L4_IRQ_F_POS	Positive trigger.
L4_IRQ_F_NEG	Negative trigger.
L4_IRQ_F_BOTH	Both edges trigger.
L4_IRQ_F_LEVEL_HIGH	Level high trigger.
L4_IRQ_F_LEVEL_LOW	Level low trigger.
L4_IRQ_F_POS_EDGE	Positive edge trigger.
L4_IRQ_F_NEG_EDGE	Negative edge trigger.
L4_IRQ_F_BOTH_EDGE	Both edges trigger.
L4_IRQ_F_MASK	Mask.
L4_IRQ_F_SET_WAKEUP	Wakeup source? Use irq as wakeup source
L4_IRQ_F_CLEAR_WAKEUP	Do not use irq as wakeup source.

Definition at line 69 of file icu.h.

Function Documentation

◆ l4_irq_bind_vcpu()

l4_msgtag_t l4_irq_bind_vcpu	(	l4_cap_idx_t	irq,
		l4_cap_idx_t	thread,
		l4_umword_t	cfg
	)

inline

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

irq	The IRQ object that shall be bound.
thread	Thread object this Irq shall be bound to.
cfg	Architecture specific interrupt configuration.

Returns: Syscall return tag

Return values

-L4_EPERM	Insufficient permissions; see precondition.
-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.

Precondition: The capabilities irq and thread both must have the permission L4_CAP_FPAGE_S.

Definition at line 299 of file irq.h.

References l4_irq_bind_vcpu_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_irq_bind_vcpu_u()

l4_msgtag_t l4_irq_bind_vcpu_u	(	l4_cap_idx_t	irq,
		l4_cap_idx_t	thread,
		l4_umword_t	cfg,
		l4_utcb_t *	utcb
	)

inline

Bind a thread to this Irq for vCPU interrupt forwarding.

Parameters

irq	The IRQ object that shall be bound.

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 this Irq shall be bound to.
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	Insufficient permissions; see precondition.
-L4_EBUSY	Cannot bind to the 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.

Precondition: The invoked Irq capability and the capability thread both must have the permission L4_CAP_FPAGE_S.

Definition at line 249 of file irq.h.

References L4_CAP_FPAGE_RWS, l4_ipc_call(), L4_IPC_NEVER, l4_map_obj_control(), l4_msgtag(), l4_obj_fpage(), L4_PROTO_IRQ_SENDER, l4_msg_regs_t::mr, and l4_fpage_t::raw.

Referenced by L4::Irq::bind_vcpu(), and l4_irq_bind_vcpu().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_irq_detach()

l4_msgtag_t l4_irq_detach ( l4_cap_idx_t irq )

inline

Detach from an interrupt source.

Parameters

irq	The IRQ object that shall be detached.

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	Insufficient permissions; see precondition.

Precondition: The capability irq must have the permission L4_CAP_FPAGE_S.

Examples: examples/sys/isr/main.c.

Definition at line 293 of file irq.h.

References l4_irq_detach_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_irq_detach_u()

l4_msgtag_t l4_irq_detach_u	(	l4_cap_idx_t	irq,
		l4_utcb_t *	utcb
	)

inline

Detach from this interrupt.

Parameters

irq	The IRQ object that shall be detached.
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	Insufficient permissions; see precondition.

Precondition: The invoked Irq capability must have the permission L4_CAP_FPAGE_S.

Definition at line 241 of file irq.h.

References l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), L4_PROTO_IRQ_SENDER, and l4_msg_regs_t::mr.

Referenced by L4::Irq::detach(), and l4_irq_detach().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_irq_receive()

l4_msgtag_t l4_irq_receive	(	l4_cap_idx_t	irq,
		l4_timeout_t	to
	)

inline

Unmask and wait for specified IRQ.

Parameters

irq	The IRQ object that shall be unmasked.
to	Timeout.

Returns: Syscall return tag

Definition at line 312 of file irq.h.

References l4_irq_receive_u(), and l4_utcb().

Referenced by L4Re::Util::Event_buffer_consumer_t< PAYLOAD >::process().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_irq_receive_u()

l4_msgtag_t l4_irq_receive_u	(	l4_cap_idx_t	irq,
		l4_timeout_t	timeout,
		l4_utcb_t *	utcb
	)

inline

Unmask and wait for this IRQ.

Parameters

irq	The IRQ object that shall be unmasked.
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 269 of file irq.h.

References l4_ipc_call(), l4_msgtag(), L4_PROTO_IRQ, and l4_msg_regs_t::mr.

Referenced by l4_irq_receive(), and L4::Irq::receive().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_irq_trigger()

l4_msgtag_t l4_irq_trigger ( l4_cap_idx_t irq )

inline

Trigger an IRQ.

Parameters

irq	The IRQ object that shall be triggered.

Returns: Syscall return tag.

Note that this function is a send only operation, i.e. there is no return value except for a failed send operation. Especially l4_error() will return an error value from the message tag which still contains the IRQ protocol used for the send operation.

Use l4_ipc_error() to check for (send) errors.

Definition at line 306 of file irq.h.

References l4_irq_trigger_u(), and l4_utcb().

Referenced by l4_semaphore_up().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_irq_trigger_u()

l4_msgtag_t l4_irq_trigger_u	(	l4_cap_idx_t	irq,
		l4_utcb_t *	utcb
	)

inline

Trigger the object.

Parameters

irq	The IRQ object that shall be triggered.
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().

Definition at line 262 of file irq.h.

References L4_IPC_BOTH_TIMEOUT_0, l4_ipc_send(), l4_msgtag(), and L4_PROTO_IRQ.

Referenced by l4_irq_trigger(), and L4::Triggerable::trigger().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_irq_unmask()

l4_msgtag_t l4_irq_unmask ( l4_cap_idx_t irq )

inline

Unmask IRQ.

Parameters

irq	The IRQ object that shall be unmasked.

Returns: Syscall return tag

Note: l4_irq_wait() and l4_irq_receive() are doing the unmask themselves.

Definition at line 325 of file irq.h.

References l4_irq_unmask_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_irq_unmask_u()

l4_msgtag_t l4_irq_unmask_u	(	l4_cap_idx_t	irq,
		l4_utcb_t *	utcb
	)

inline

Unmask this IRQ.

Parameters

irq	The IRQ object that shall be unmasked.
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 285 of file irq.h.

References L4_IPC_NEVER, l4_ipc_send(), l4_msgtag(), L4_PROTO_IRQ, and l4_msg_regs_t::mr.

Referenced by l4_irq_unmask().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_irq_wait()

l4_msgtag_t l4_irq_wait	(	l4_cap_idx_t	irq,
		l4_umword_t *	label,
		l4_timeout_t	to
	)

inline

Unmask IRQ and wait for any message.

Parameters

irq	The IRQ object that shall be unmasked.
label	Receive label.
to	Timeout.

Returns: Syscall return tag

Examples: examples/sys/isr/main.c.

Definition at line 318 of file irq.h.

References l4_irq_wait_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_irq_wait_u()

l4_msgtag_t l4_irq_wait_u	(	l4_cap_idx_t	irq,
		l4_umword_t *	label,
		l4_timeout_t	timeout,
		l4_utcb_t *	utcb
	)

inline

Unmask IRQ and (open) wait for any message.

Parameters

irq	The IRQ object that shall be unmasked.
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 276 of file irq.h.

References l4_ipc_send_and_wait(), l4_msgtag(), L4_PROTO_IRQ, and l4_msg_regs_t::mr.

Referenced by l4_irq_wait().

Here is the call graph for this function:

Here is the caller graph for this function:

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ L4_irq_mode

Function Documentation

◆ l4_irq_bind_vcpu()

◆ l4_irq_bind_vcpu_u()

◆ l4_irq_detach()

◆ l4_irq_detach_u()

◆ l4_irq_receive()

◆ l4_irq_receive_u()

◆ l4_irq_trigger()

◆ l4_irq_trigger_u()

◆ l4_irq_unmask()

◆ l4_irq_unmask_u()

◆ l4_irq_wait()

◆ l4_irq_wait_u()