C++ L4 kernel thread interface, see Thread for the C interface. More...

#include <thread>

Inheritance diagram for L4::Thread:

Collaboration diagram for L4::Thread:

Data Structures
class	Attr
	Thread attributes used for control(). More...

class	Modify_senders
	Class wrapping a list of rules which modify the sender label of IPC messages inbound to this thread. More...

Public Member Functions
l4_msgtag_t	ex_regs (l4_addr_t ip, l4_addr_t sp, l4_umword_t flags, l4_utcb_t *utcb=l4_utcb()) noexcept
	Exchange basic thread registers.

l4_msgtag_t	ex_regs (l4_addr_t ip, l4_addr_t sp, l4_umword_t flags, l4_utcb_t utcb=l4_utcb()) noexcept
	Exchange basic thread registers and return previous values.

l4_msgtag_t	control (Attr const &attr) noexcept
	Commit the given thread-attributes object.

l4_msgtag_t	switch_to (l4_utcb_t *utcb=l4_utcb()) noexcept
	Switch execution to this thread.

l4_msgtag_t	stats_time (l4_kernel_clock_t us, l4_utcb_t utcb=l4_utcb()) noexcept
	Get consumed time of thread in us.

l4_msgtag_t	vcpu_resume_start (l4_utcb_t *utcb=l4_utcb()) noexcept
	Resume from vCPU asynchronous IPC handler, start.

l4_msgtag_t	vcpu_resume_commit (l4_msgtag_t tag, l4_utcb_t *utcb=l4_utcb()) noexcept
	Resume from vCPU asynchronous IPC handler, commit.

l4_msgtag_t	vcpu_control (l4_addr_t vcpu_state, l4_utcb_t *utcb=l4_utcb()) noexcept
	Enable the vCPU feature for the thread.

l4_msgtag_t	vcpu_control_ext (l4_addr_t ext_vcpu_state, l4_utcb_t *utcb=l4_utcb()) noexcept
	Enable the extended vCPU feature for the thread.

l4_msgtag_t	register_del_irq (Cap< Irq > irq, l4_utcb_t *u=l4_utcb()) noexcept
	Register an IRQ that will trigger upon deletion events.

l4_msgtag_t	modify_senders (Modify_senders const &todo) noexcept
	Apply sender modification rules.

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_t< Thread, Kobject, L4_PROTO_THREAD, Type_info::Demand_t< 1 > >
typedef Thread	Class
	The target interface type (inheriting from Kobject_t)

typedef Typeid::Iface< PROTO, Thread >	__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_t< Thread, Kobject, L4_PROTO_THREAD, 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_t< Thread, Kobject, L4_PROTO_THREAD, Type_info::Demand_t< 1 > >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Detailed Description

C++ L4 kernel thread interface, see Thread for the C interface.

The Thread class defines 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 the L4::Factory API (L4::Factory::create()).

Amongst other things an L4::Thread encapsulates:

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

Thread objects provide an API for

Thread configuration and manipulation
Thread switching.

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

thread
Common thread related definitions.

For the C interface see the Thread API. For more elaborated documentation on the vCPU feature see vCPU API.

Definition at line 59 of file thread.

Member Function Documentation

◆ control()

l4_msgtag_t L4::Thread::control ( Attr const & attr )

inlinenoexcept

Commit the given thread-attributes object.

Parameters

attr	the attribute object to commit to the thread.

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

Return values

L4_EOK	Operation successful.
-L4_EPERM	No L4_CAP_FPAGE_S right on the capability used to invoke this operation or the task capability set in Attr::bind().
-L4_EINVAL	Malformed thread-attributes.

Definition at line 249 of file thread.

References L4::Kobject::cap().

Here is the call graph for this function:

◆ ex_regs() [1/2]

l4_msgtag_t L4::Thread::ex_regs	(	l4_addr_t *	ip,
		l4_addr_t *	sp,
		l4_umword_t *	flags,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Exchange basic thread registers and return previous values.

Parameters

[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 123 of file thread.

References L4::Kobject::cap(), and l4_thread_ex_regs_ret_u().

Here is the call graph for this function:

◆ ex_regs() [2/2]

l4_msgtag_t L4::Thread::ex_regs	(	l4_addr_t	ip,
		l4_addr_t	sp,
		l4_umword_t	flags,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Exchange basic thread registers.

Parameters

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 90 of file thread.

References L4::Kobject::cap(), and l4_thread_ex_regs_u().

Here is the call graph for this function:

◆ modify_senders()

l4_msgtag_t L4::Thread::modify_senders ( Modify_senders const & todo )

inlinenoexcept

Apply sender modification rules.

Parameters

todo	Prepared sender modification rules.

Returns: System call return tag.

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.

See Modify_senders for a detailed description when applying sender modification rules is required.

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

See also: l4_thread_modify_sender_commit()

Definition at line 501 of file thread.

References L4::Kobject::cap(), l4_ipc_call(), L4_IPC_NEVER, l4_msgtag(), and L4_PROTO_THREAD.

Here is the call graph for this function:

◆ register_del_irq()

l4_msgtag_t L4::Thread::register_del_irq	(	Cap< Irq >	irq,
		l4_utcb_t *	u = `l4_utcb()`
	)

inlinenoexcept

Register an IRQ that will trigger upon deletion events.

Parameters

irq	Capability selector for the IRQ object to be triggered.
u	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns: System call return tag containing the return code.

Return values

-L4_BUSY	A deletion IRQ is already bound to this thread.
-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.

See also: l4_thread_register_del_irq

Definition at line 414 of file thread.

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

Here is the call graph for this function:

◆ stats_time()

l4_msgtag_t L4::Thread::stats_time	(	l4_kernel_clock_t *	us,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Get consumed time of thread in us.

Parameters

[out]	us	Consumed time in µs.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns: Syscall return tag.

Definition at line 270 of file thread.

References L4::Kobject::cap().

Here is the call graph for this function:

◆ switch_to()

l4_msgtag_t L4::Thread::switch_to ( l4_utcb_t * utcb = l4_utcb() )

inlinenoexcept

Switch execution to this thread.

Parameters

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

Note: The current time slice is inherited to this thread.

Definition at line 259 of file thread.

References L4::Kobject::cap().

Here is the call graph for this function:

◆ vcpu_control()

l4_msgtag_t L4::Thread::vcpu_control	(	l4_addr_t	vcpu_state,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Enable the vCPU feature for the thread.

Parameters

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 354 of file thread.

References L4::Kobject::cap(), and l4_thread_vcpu_control_u().

Here is the call graph for this function:

◆ vcpu_control_ext()

l4_msgtag_t L4::Thread::vcpu_control_ext	(	l4_addr_t	ext_vcpu_state,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Enable the extended vCPU feature for the thread.

Parameters

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 387 of file thread.

References L4::Kobject::cap(), and l4_thread_vcpu_control_ext_u().

Here is the call graph for this function:

◆ vcpu_resume_commit()

l4_msgtag_t L4::Thread::vcpu_resume_commit	(	l4_msgtag_t	tag,
		l4_utcb_t *	utcb = `l4_utcb()`
	)

inlinenoexcept

Resume from vCPU asynchronous IPC handler, commit.

Parameters

tag	Tag to use, returned by l4_thread_vcpu_resume_start().
utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

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.

The asynchronous IPC handling is described at vCPU API.

See also: l4_thread_vcpu_resume_commit

Definition at line 330 of file thread.

References L4::Kobject::cap().

Here is the call graph for this function:

◆ vcpu_resume_start()

l4_msgtag_t L4::Thread::vcpu_resume_start ( l4_utcb_t * utcb = l4_utcb() )

inlinenoexcept

Resume from vCPU asynchronous IPC handler, start.

Parameters

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

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().

The asynchronous IPC handling is described at vCPU API.

See also: l4_thread_vcpu_resume_start

Definition at line 289 of file thread.

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

l4/sys/thread

Data Structures

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ control()

◆ ex_regs() [1/2]

◆ ex_regs() [2/2]

◆ modify_senders()

◆ register_del_irq()

◆ stats_time()

◆ switch_to()

◆ vcpu_control()

◆ vcpu_control_ext()

◆ vcpu_resume_commit()

◆ vcpu_resume_start()