C Thread object interface, see L4::Thread for the C++ interface. More...

Collaboration diagram for Thread:

Modules
	Thread control
	API for Thread Control method.

	vCPU API
	vCPU API.

Enumerations
enum	L4_thread_control_flags { L4_THREAD_CONTROL_SET_PAGER = 0x0010000 , L4_THREAD_CONTROL_BIND_TASK = 0x0200000 , L4_THREAD_CONTROL_ALIEN = 0x0400000 , L4_THREAD_CONTROL_UX_NATIVE = 0x0800000 , L4_THREAD_CONTROL_SET_EXC_HANDLER = 0x1000000 }
	Flags for the thread control operation. More...

enum	L4_thread_control_mr_indices { L4_THREAD_CONTROL_MR_IDX_FLAGS = 0 , L4_THREAD_CONTROL_MR_IDX_PAGER = 1 , L4_THREAD_CONTROL_MR_IDX_EXC_HANDLER = 2 , L4_THREAD_CONTROL_MR_IDX_FLAG_VALS = 4 , L4_THREAD_CONTROL_MR_IDX_BIND_UTCB = 5 , L4_THREAD_CONTROL_MR_IDX_BIND_TASK = 6 }
	Indices for the values in the message register for thread control. More...

enum	L4_thread_ex_regs_flags { L4_THREAD_EX_REGS_CANCEL = 0x10000UL , L4_THREAD_EX_REGS_TRIGGER_EXCEPTION = 0x20000UL , L4_THREAD_EX_REGS_ARCH_MASK = 0xff000000UL }
	Flags for the thread ex-regs operation. More...

enum	L4_thread_ex_regs_flags_arm { L4_THREAD_EX_REGS_ARM_SET_EL_MASK = 0x3 << 24 , L4_THREAD_EX_REGS_ARM_SET_EL_KEEP = 0x0 << 24 , L4_THREAD_EX_REGS_ARM_SET_EL_EL0 = 0x1 << 24 , L4_THREAD_EX_REGS_ARM_SET_EL_EL1 = 0x2 << 24 }
	Arm specific L4::Thread::ex_regs() flags. More...

Functions
l4_msgtag_t	l4_thread_ex_regs (l4_cap_idx_t thread, l4_addr_t ip, l4_addr_t sp, l4_umword_t flags) L4_NOTHROW
	Exchange basic thread registers.

l4_msgtag_t	l4_thread_ex_regs_u (l4_cap_idx_t thread, l4_addr_t ip, l4_addr_t sp, l4_umword_t flags, l4_utcb_t *utcb) L4_NOTHROW
	Exchange basic thread registers.

l4_msgtag_t	l4_thread_ex_regs_ret (l4_cap_idx_t thread, l4_addr_t ip, l4_addr_t sp, l4_umword_t *flags) L4_NOTHROW
	Exchange basic thread registers and return previous values.

l4_msgtag_t	l4_thread_ex_regs_ret_u (l4_cap_idx_t thread, l4_addr_t ip, l4_addr_t sp, l4_umword_t flags, l4_utcb_t utcb) L4_NOTHROW
	Exchange basic thread registers and return previous values.

l4_msgtag_t	l4_thread_yield (void) L4_NOTHROW
	Yield current time slice.

l4_msgtag_t	l4_thread_switch (l4_cap_idx_t to_thread) L4_NOTHROW
	Switch to another thread (and donate the remaining time slice).

l4_msgtag_t	l4_thread_stats_time (l4_cap_idx_t thread, l4_kernel_clock_t *us) L4_NOTHROW
	Get consumed time of thread in µs.

l4_msgtag_t	l4_thread_vcpu_resume_start (void) L4_NOTHROW
	vCPU return from event handler.

l4_msgtag_t	l4_thread_vcpu_resume_commit (l4_cap_idx_t thread, l4_msgtag_t tag) L4_NOTHROW
	Commit vCPU resume.

l4_msgtag_t	l4_thread_vcpu_control (l4_cap_idx_t thread, l4_addr_t vcpu_state) L4_NOTHROW
	Enable the vCPU feature for the thread.

l4_msgtag_t	l4_thread_vcpu_control_u (l4_cap_idx_t thread, l4_addr_t vcpu_state, l4_utcb_t *utcb) L4_NOTHROW
	Enable the vCPU feature for the thread.

l4_msgtag_t	l4_thread_vcpu_control_ext (l4_cap_idx_t thread, l4_addr_t ext_vcpu_state) L4_NOTHROW
	Enable the extended vCPU feature for the thread.

l4_msgtag_t	l4_thread_vcpu_control_ext_u (l4_cap_idx_t thread, l4_addr_t ext_vcpu_state, l4_utcb_t *utcb) L4_NOTHROW
	Enable the extended vCPU feature for the thread.

l4_msgtag_t	l4_thread_register_del_irq (l4_cap_idx_t thread, l4_cap_idx_t irq) L4_NOTHROW
	Register an IRQ that will trigger upon deletion events.

l4_msgtag_t	l4_thread_modify_sender_start (void) L4_NOTHROW
	Start a thread sender modification sequence.

int	l4_thread_modify_sender_add (l4_umword_t match_mask, l4_umword_t match, l4_umword_t del_bits, l4_umword_t add_bits, l4_msgtag_t *tag) L4_NOTHROW
	Add a modification pattern to a sender modification sequence.

l4_msgtag_t	l4_thread_modify_sender_commit (l4_cap_idx_t thread, l4_msgtag_t tag) L4_NOTHROW
	Apply (commit) a sender modification sequence.

l4_msgtag_t	l4_thread_arm_set_tpidruro (l4_cap_idx_t thread, l4_addr_t tpidruro) L4_NOTHROW
	Set the TPIDRURO thread specific register.

Detailed Description

C Thread object interface, see L4::Thread for the C++ interface.

An L4 thread is a thread of execution in the L4 context. Usually user-level and kernel threads are mapped 1:1 to each other. Thread kernel objects are created using a factory, see Factory (l4_factory_create_thread()).

Amongst other things an L4 thread encapsulates:

CPU state
- General-purpose registers
- Program counter
- Stack pointer
FPU state
Scheduling parameters, see the Scheduler API
Execution state
- Blocked, Runnable, Running

Thread objects provide an API for

Thread configuration and manipulation
Thread switching.

The thread control functions are used to control various aspects of a thread. See l4_thread_control_start() for more information.

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

For the C++ interface refer to L4::Thread.

Enumeration Type Documentation

◆ L4_thread_control_flags

enum L4_thread_control_flags

Flags for the thread control operation.

Enumerator
L4_THREAD_CONTROL_SET_PAGER	The pager will be given.
L4_THREAD_CONTROL_BIND_TASK	The task to bind the thread to will be given.
L4_THREAD_CONTROL_ALIEN	Alien state of the thread is set.
L4_THREAD_CONTROL_UX_NATIVE	Fiasco-UX only: pass-through of host system calls is set.
L4_THREAD_CONTROL_SET_EXC_HANDLER	The exception handler of the thread will be given.

Definition at line 721 of file thread.h.

◆ L4_thread_control_mr_indices

enum L4_thread_control_mr_indices

Indices for the values in the message register for thread control.

Enumerator
L4_THREAD_CONTROL_MR_IDX_FLAGS	See also L4_thread_control_flags.
L4_THREAD_CONTROL_MR_IDX_PAGER	Index for pager cap.
L4_THREAD_CONTROL_MR_IDX_EXC_HANDLER	Index for exception handler.
L4_THREAD_CONTROL_MR_IDX_FLAG_VALS	Index for feature values.
L4_THREAD_CONTROL_MR_IDX_BIND_UTCB	Index for UTCB address for bind.
L4_THREAD_CONTROL_MR_IDX_BIND_TASK	Index for task flex-page for bind.

Definition at line 744 of file thread.h.

◆ L4_thread_ex_regs_flags

enum L4_thread_ex_regs_flags

Flags for the thread ex-regs operation.

Enumerator
L4_THREAD_EX_REGS_CANCEL	Cancel ongoing IPC in the thread.
L4_THREAD_EX_REGS_TRIGGER_EXCEPTION	Trigger artificial exception in thread.
L4_THREAD_EX_REGS_ARCH_MASK	Arch specific flags.

Definition at line 759 of file thread.h.

◆ L4_thread_ex_regs_flags_arm

enum L4_thread_ex_regs_flags_arm

Arm specific L4::Thread::ex_regs() flags.

Only one option must be used in calls to L4::Thread::ex_regs(). Using more than one option results in undefined behaviour.

Enumerator
L4_THREAD_EX_REGS_ARM_SET_EL_MASK	Exception level set mask.
L4_THREAD_EX_REGS_ARM_SET_EL_KEEP	Keep current exception level of thread (default).
L4_THREAD_EX_REGS_ARM_SET_EL_EL0	Set exception level of thread to EL0 (usr mode).
L4_THREAD_EX_REGS_ARM_SET_EL_EL1	Set exception level of thread to EL1 (sys mode).

Definition at line 53 of file thread.h.

Function Documentation

◆ l4_thread_arm_set_tpidruro()

l4_msgtag_t l4_thread_arm_set_tpidruro	(	l4_cap_idx_t	thread,
		l4_addr_t	tpidruro
	)

inline

Set the TPIDRURO thread specific register.

Parameters

thread	Thread to manipulate
tpidruro	The value to be set

Returns: System call return tag

Definition at line 79 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_ex_regs()

l4_msgtag_t l4_thread_ex_regs	(	l4_cap_idx_t	thread,
		l4_addr_t	ip,
		l4_addr_t	sp,
		l4_umword_t	flags
	)

inline

Exchange basic thread registers.

Parameters

thread	Capability selector of the thread to manipulate.
ip	New instruction pointer, use ~0UL to leave the instruction pointer unchanged.
sp	New stack pointer, use ~0UL to leave the stack pointer unchanged.
flags	Ex-regs flags, see L4_thread_ex_regs_flags.

Returns: System call return tag

This method allows to manipulate and start a thread. The basic functionality is to set the instruction pointer and the stack pointer of a thread. Additionally, this method allows also to cancel ongoing IPC operations and to force the thread to raise an artificial exception (see flags). If the thread is in an IPC operation or if L4_THREAD_EX_REGS_TRIGGER_EXCEPTION forces an IPC then changes in IP and SP take effect directly after returning from this IPC.

The thread is started using l4_scheduler_run_thread(). However, if at the time l4_scheduler_run_thread() is called, the instruction pointer of the thread is invalid, a later call to l4_thread_ex_regs() with a valid instruction pointer might start the thread.

Examples: examples/sys/aliens/main.c, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 912 of file thread.h.

References l4_thread_ex_regs_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_thread_ex_regs_ret()

l4_msgtag_t l4_thread_ex_regs_ret	(	l4_cap_idx_t	thread,
		l4_addr_t *	ip,
		l4_addr_t *	sp,
		l4_umword_t *	flags
	)

inline

Exchange basic thread registers and return previous values.

Parameters

	thread	Capability selector of the thread to manipulate.
[in,out]	ip	New instruction pointer, use ~0UL to leave the instruction pointer unchanged, return previous instruction pointer.
[in,out]	sp	New stack pointer, use ~0UL to leave the stack pointer unchanged, returns previous stack pointer.
[in,out]	flags	Ex-regs flags, see L4_thread_ex_regs_flags, return previous CPU flags of the thread.

Returns: System call return tag

This method allows to manipulate and start a thread. The basic functionality is to set the instruction pointer and the stack pointer of a thread. Additionally, this method allows also to cancel ongoing IPC operations and to force the thread to raise an artificial exception (see flags). If the thread is in an IPC operation or if L4_THREAD_EX_REGS_TRIGGER_EXCEPTION forces an IPC then changes in IP and SP take effect directly after returning from this IPC.

The thread is started using l4_scheduler_run_thread(). However, if at the time l4_scheduler_run_thread() is called, the instruction pointer of the thread is invalid, a later call to l4_thread_ex_regs() with a valid instruction pointer might start the thread.

Returned values are valid only if function returns successfully.

Definition at line 919 of file thread.h.

References l4_thread_ex_regs_ret_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_thread_ex_regs_ret_u()

l4_msgtag_t l4_thread_ex_regs_ret_u	(	l4_cap_idx_t	thread,
		l4_addr_t *	ip,
		l4_addr_t *	sp,
		l4_umword_t *	flags,
		l4_utcb_t *	utcb
	)

inline

Exchange basic thread registers and return previous values.

Parameters

	thread	Capability selector of the thread to manipulate.
[in,out]	ip	New instruction pointer, use ~0UL to leave the instruction pointer unchanged, return previous instruction pointer.
[in,out]	sp	New stack pointer, use ~0UL to leave the stack pointer unchanged, returns previous stack pointer.
[in,out]	flags	Ex-regs flags, see L4_thread_ex_regs_flags, return previous CPU flags of the thread.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns: System call return tag. [out] parameters are only valid if the function returns successfully. Use l4_error() to check.

This method allows to manipulate and start a thread. The basic functionality is to set the instruction pointer and the stack pointer of a thread. Additionally, this method allows also to cancel ongoing IPC operations and to force the thread to raise an artificial exception (see flags). If the thread is in an IPC operation or if L4_THREAD_EX_REGS_TRIGGER_EXCEPTION forces an IPC then changes in IP and SP take effect directly after returning from this IPC.

The thread is started using L4::Scheduler::run_thread(). However, if at the time L4::Scheduler::run_thread() is called, the instruction pointer of the thread is invalid, a later call to ex_regs() with a valid instruction pointer might start the thread.

Definition at line 785 of file thread.h.

References l4_thread_ex_regs_u(), and l4_msg_regs_t::mr.

Referenced by L4::Thread::ex_regs(), and l4_thread_ex_regs_ret().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_thread_ex_regs_u()

l4_msgtag_t l4_thread_ex_regs_u	(	l4_cap_idx_t	thread,
		l4_addr_t	ip,
		l4_addr_t	sp,
		l4_umword_t	flags,
		l4_utcb_t *	utcb
	)

inline

Exchange basic thread registers.

Parameters

thread	Capability selector of the thread to manipulate.
ip	New instruction pointer, use ~0UL to leave the instruction pointer unchanged.
sp	New stack pointer, use ~0UL to leave the stack pointer unchanged.
flags	Ex-regs flags, see L4_thread_ex_regs_flags.
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns: System call return tag.

This method allows to manipulate and start a thread. The basic functionality is to set the instruction pointer and the stack pointer of a thread. Additionally, this method allows also to cancel ongoing IPC operations and to force the thread to raise an artificial exception (see flags). If the thread is in an IPC operation or if L4_THREAD_EX_REGS_TRIGGER_EXCEPTION forces an IPC then changes in IP and SP take effect directly after returning from this IPC.

The thread is started using L4::Scheduler::run_thread(). However, if at the time L4::Scheduler::run_thread() is called, the instruction pointer of the thread is invalid, a later call to ex_regs() with a valid instruction pointer might start the thread.

Definition at line 774 of file thread.h.

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

Referenced by L4::Thread::ex_regs(), l4_thread_ex_regs(), and l4_thread_ex_regs_ret_u().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_thread_modify_sender_add()

int l4_thread_modify_sender_add	(	l4_umword_t	match_mask,
		l4_umword_t	match,
		l4_umword_t	del_bits,
		l4_umword_t	add_bits,
		l4_msgtag_t *	tag
	)

inline

Add a modification pattern to a sender modification sequence.

Parameters

tag	Tag received from l4_thread_modify_sender_start() or previous l4_thread_modify_sender_add() calls from the same sequence.
match_mask	Bitmask of bits to match the label.
match	Bitmask that must be equal to the label after applying match_mask.
del_bits	Bits to be deleted from the label.
add_bits	Bits to be added to the label.

Returns: 0 on sucess, <0 on error

In pseudo code: if ((sender_label & match_mask) == match) { sender_label = (sender_label & ~del_bits) | add_bits; }

Only the first match is applied.

See also: l4_thread_modify_sender_start; l4_thread_modify_sender_commit

Definition at line 1092 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_modify_sender_commit()

l4_msgtag_t l4_thread_modify_sender_commit	(	l4_cap_idx_t	thread,
		l4_msgtag_t	tag
	)

inline

Apply (commit) a sender modification sequence.

The modification rules are applied to all IPCs to the thread (whether directly or by IPC gate) that are already in flight, that is that the sender is already blocking on.

Note: Modifying the senders of a thread running on a different CPU core is not supported.

See also: l4_thread_modify_sender_start; l4_thread_modify_sender_add

Definition at line 1103 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_modify_sender_start()

l4_msgtag_t l4_thread_modify_sender_start ( void )

inline

Start a thread sender modification sequence.

Add modification rules with l4_thread_modify_sender_add() and commit with l4_thread_modify_sender_commit(). Do not touch the UTCB between l4_thread_modify_sender_start() and l4_thread_modify_sender_commit().

This mechanism shall be used to change the source object labels of every pending IPC of an IPC gate or an IRQ if the labels in such pending IPC become invalid for the receiving thread, potentially because:

a thread was unbound from an IPC gate / IRQ, or
an IPC gate /IRQ was removed, or
the label of an IPC gate /IRQ bound to a thread was changed.

It is not required to perform the modify_sender mechanism after an IPC gate or an IRQ was bound to a thread for the first time.

See also: l4_thread_modify_sender_add; l4_thread_modify_sender_commit

Definition at line 1086 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_register_del_irq()

l4_msgtag_t l4_thread_register_del_irq	(	l4_cap_idx_t	thread,
		l4_cap_idx_t	irq
	)

inline

Register an IRQ that will trigger upon deletion events.

Parameters

thread	Thread to register IRQ for.
irq	Capability selector for the IRQ object to be triggered.

Returns: System call return tag containing the return code.

Return values

-L4_EPERM L4_CAP_FPAGE_W missing on irq

In case the irq is already bound to an interrupt source, it is unbound first. When irq is deleted, it will be deregistered first. A registered deletion Irq can only be deregistered by deleting the Irq or the thread.

List of deletion events:

deletion of one or several IPC gates bound to this thread.

When the deletion event is delivered, there is no indication about which IPC gate was deleted.

Definition at line 1013 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_stats_time()

l4_msgtag_t l4_thread_stats_time	(	l4_cap_idx_t	thread,
		l4_kernel_clock_t *	us
	)

inline

Get consumed time of thread in µs.

Parameters

	thread	Thread to get the consumed time from.
[out]	us	Consumed time in µs.

Returns: system call return tag

Definition at line 981 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_switch()

l4_msgtag_t l4_thread_switch ( l4_cap_idx_t to_thread )

inline

Switch to another thread (and donate the remaining time slice).

Parameters

to_thread The thread to switch to.

Returns: system call return tag

Definition at line 972 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_vcpu_control()

l4_msgtag_t l4_thread_vcpu_control	(	l4_cap_idx_t	thread,
		l4_addr_t	vcpu_state
	)

inline

Enable the vCPU feature for the thread.

Parameters

thread	Capability selector of the thread for which the vCPU feature shall be enabled.
vcpu_state	The virtual address where the kernel shall store the vCPU state in case of vCPU exits. The address must be a valid kernel-user-memory address (see l4_task_add_ku_mem()).

Returns: Syscall return tag.

This function enables the vCPU feature of the thread.

The kernel-user memory area starting at vcpu_state must be at least 128-byte aligned and must cover the size of l4_vcpu_state_t.

Note: Disabling of the vCPU feature is optional and currently not supported.

Definition at line 1030 of file thread.h.

References l4_thread_vcpu_control_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_thread_vcpu_control_ext()

l4_msgtag_t l4_thread_vcpu_control_ext	(	l4_cap_idx_t	thread,
		l4_addr_t	ext_vcpu_state
	)

inline

Enable the extended vCPU feature for the thread.

Parameters

thread	Capability selector of the thread for which the extended vCPU feature shall be enabled.
ext_vcpu_state	The virtual address where the kernel shall store the vCPU state in case of vCPU exits. The address must be a valid kernel-user-memory address (see l4_task_add_ku_mem()).

Returns: Syscall return tag.

The extended vCPU feature allows the use of hardware-virtualization features such as Intel's VT or AMD's SVM.

This function enables the extended vCPU feature of the thread. Enabling the extended vCPU feature also enables the vCPU feature.

The kernel-user memory area starting at ext_vcpu_state must be at least 4 KiB aligned and must cover a size of L4_PAGESIZE. It includes the data of l4_vcpu_state_t at offset 0, the extended vCPU state at offset L4_VCPU_OFFSET_EXT_STATE, and, on some platforms, the extended vCPU information at offset L4_VCPU_OFFSET_EXT_INFOS.

Note: Enabling the extended vCPU feature for a thread running on a different CPU core is currently not supported.; Disabling of the extended vCPU feature is currently not supported.; Upgrading from non-extended vCPU feature to extended vCPU feature is currently not supported.

Definition at line 1045 of file thread.h.

References l4_thread_vcpu_control_ext_u(), and l4_utcb().

Here is the call graph for this function:

◆ l4_thread_vcpu_control_ext_u()

l4_msgtag_t l4_thread_vcpu_control_ext_u	(	l4_cap_idx_t	thread,
		l4_addr_t	ext_vcpu_state,
		l4_utcb_t *	utcb
	)

inline

Enable the extended vCPU feature for the thread.

Parameters

thread	Capability selector of the thread for which the extended vCPU feature shall be enabled.
ext_vcpu_state	The virtual address where the kernel shall store the vCPU state in case of vCPU exits. The address must be a valid kernel-user-memory address (see L4::Task::add_ku_mem()).
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns: Syscall return tag.

The extended vCPU feature allows the use of hardware-virtualization features such as Intel's VT or AMD's SVM.

This function enables the extended vCPU feature of this thread. Enabling the extended vCPU feature also enables the vCPU feature.

The kernel-user memory area starting at ext_vcpu_state must be at least 4 KiB aligned and must cover a size of L4_PAGESIZE. It includes the data of l4_vcpu_state_t at offset 0, the extended vCPU state at offset L4_VCPU_OFFSET_EXT_STATE, and, on some platforms, the extended vCPU information at offset L4_VCPU_OFFSET_EXT_INFOS.

Note: Enabling the extended vCPU feature for a thread running on a different CPU core is currently not supported.; Disabling of the extended vCPU feature is currently not supported.; Upgrading from non-extended vCPU feature to extended vCPU feature is currently not supported.

Definition at line 1035 of file thread.h.

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

Referenced by l4_thread_vcpu_control_ext(), and L4::Thread::vcpu_control_ext().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_thread_vcpu_control_u()

l4_msgtag_t l4_thread_vcpu_control_u	(	l4_cap_idx_t	thread,
		l4_addr_t	vcpu_state,
		l4_utcb_t *	utcb
	)

inline

Enable the vCPU feature for the thread.

Parameters

thread	Capability selector of the thread for which the vCPU feature shall be enabled.
vcpu_state	A virtual address pointing to a l4_vcpu_state_t. It must be a valid kernel-user-memory address (see L4::Task::add_ku_mem()).
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns: Syscall return tag.

This function enables the vCPU feature of this thread

The kernel-user memory starting at vcpu_state must be at least 128-byte aligned and must cover the size of l4_vcpu_state_t.

The asynchronous IPC handling is described at vCPU API.

Note: Disabling of the vCPU feature is optional and currently not supported.

Definition at line 1020 of file thread.h.

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

Referenced by l4_thread_vcpu_control(), and L4::Thread::vcpu_control().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ l4_thread_vcpu_resume_commit()

l4_msgtag_t l4_thread_vcpu_resume_commit	(	l4_cap_idx_t	thread,
		l4_msgtag_t	tag
	)

inline

Commit vCPU resume.

Parameters

thread	Thread to be resumed, the invalid cap can be used for the current thread.
tag	Tag to use, returned by l4_thread_vcpu_resume_start()

Returns: Syscall return tag containing one of the following return codes.

Return values

0	Indicates a VM exit, provided that `thread` is in extended vCPU mode with virtual interrupts cleared.
1	Indicates an incoming IPC message, provided that the `thread` is in extended vCPU mode with virtual interrupts cleared.
-L4_EPERM	The user task capability set in the vCPU state is missing the L4_CAP_FPAGE_S right.
-L4_ENOENT	The user task capability set in the vCPU state is invalid.
-L4_EINVAL	`thread` is not the current running thread, or does not have the vCPU feature enabled.
<0	A supplied mapping failed.

All flex pages in the UTCB (added with l4_sndfpage_add() after l4_thread_vcpu_resume_start()) are unconditionally mapped into the user task configured in the vCPU state.

To resume into another address space, the capability to the target Task (or L4::Vm) must be set in l4_vcpu_state_t::user_task together with L4_VCPU_F_USER_MODE. The capability selector must have all lower bits clear (see L4_CAP_MASK). The kernel adds the L4_SYSF_SEND flag there to indicate that the capability has been referenced in the kernel. Consecutive resumes will not reference the task capability again until all lower bits are cleared again. To release a task use a different task capability or use an invalid capability with the L4_SYSF_REPLY flag set.

See also: l4_vcpu_state_t

Definition at line 993 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_vcpu_resume_start()

l4_msgtag_t l4_thread_vcpu_resume_start ( void )

inline

vCPU return from event handler.

Returns: Message tag to be used for l4_sndfpage_add() and l4_thread_vcpu_resume_commit()

The vCPU resume functionality is split in multiple functions to allow the specification of additional send-flex-pages using l4_sndfpage_add().

Definition at line 987 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_yield()

l4_msgtag_t l4_thread_yield ( void )

inline

Yield current time slice.

Returns: system call return tag

Definition at line 861 of file thread.h.

References L4_INVALID_CAP, L4_IPC_BOTH_TIMEOUT_0, l4_ipc_receive(), and l4_msgtag().

Here is the call graph for this function:

Modules

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ L4_thread_control_flags

◆ L4_thread_control_mr_indices

◆ L4_thread_ex_regs_flags

◆ L4_thread_ex_regs_flags_arm

Function Documentation

◆ l4_thread_arm_set_tpidruro()

◆ l4_thread_ex_regs()

◆ l4_thread_ex_regs_ret()

◆ l4_thread_ex_regs_ret_u()

◆ l4_thread_ex_regs_u()

◆ l4_thread_modify_sender_add()

◆ l4_thread_modify_sender_commit()

◆ l4_thread_modify_sender_start()

◆ l4_thread_register_del_irq()

◆ l4_thread_stats_time()

◆ l4_thread_switch()

◆ l4_thread_vcpu_control()

◆ l4_thread_vcpu_control_ext()

◆ l4_thread_vcpu_control_ext_u()

◆ l4_thread_vcpu_control_u()

◆ l4_thread_vcpu_resume_commit()

◆ l4_thread_vcpu_resume_start()

◆ l4_thread_yield()