L4Re - L4 Runtime Environment

Thread object. 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 }
 Flags for the thread ex-regs operation. 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. More...
 
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. More...
 
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. More...
 
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. More...
 
l4_msgtag_t l4_thread_yield (void) L4_NOTHROW
 Yield current time slice. More...
 
l4_msgtag_t l4_thread_switch (l4_cap_idx_t to_thread) L4_NOTHROW
 Switch to another thread (and donate the remaining time slice). More...
 
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. More...
 
l4_msgtag_t l4_thread_vcpu_resume_start (void) L4_NOTHROW
 vCPU return from event handler. More...
 
l4_msgtag_t l4_thread_vcpu_resume_commit (l4_cap_idx_t thread, l4_msgtag_t tag) L4_NOTHROW
 Commit vCPU resume. More...
 
l4_msgtag_t l4_thread_vcpu_control (l4_cap_idx_t thread, l4_addr_t vcpu_state) L4_NOTHROW
 Enable or disable the vCPU feature for the thread. More...
 
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 or disable the vCPU feature for the thread. More...
 
l4_msgtag_t l4_thread_vcpu_control_ext (l4_cap_idx_t thread, l4_addr_t ext_vcpu_state) L4_NOTHROW
 Enable or disable the extended vCPU feature for the thread. More...
 
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 or disable the extended vCPU feature for the thread. More...
 
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. More...
 
l4_msgtag_t l4_thread_modify_sender_start (void) L4_NOTHROW
 Start a thread sender modifiction sequence. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

Thread object.

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:

Thread objects provide an API for

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

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

◆ 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 663 of file thread.h.

◆ 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.

Definition at line 678 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
threadThread to manipulate
tpidruroThe value to be set
Returns
System call return tag

Definition at line 59 of file thread.h.

◆ 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
threadCapability selector of the thread to manipulate.
ipNew instruction pointer, use ~0UL to leave the instruction pointer unchanged.
spNew stack pointer, use ~0UL to leave the stack pointer unchanged.
flagsEx-regs flags, see L4_thread_ex_regs_flags.
Returns
System call return tag

This method allows to manipulate 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).

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 829 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
threadCapability selector of the thread to manipulate.
[in,out]ipNew instruction pointer, use ~0UL to leave the instruction pointer unchanged, return previous instruction pointer.
[in,out]spNew stack pointer, use ~0UL to leave the stack pointer unchanged, returns previous stack pointer.
[in,out]flagsEx-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).

Returned values are valid only if function returns successfully.

Definition at line 836 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
threadCapability selector of the thread to manipulate.
[in,out]ipNew instruction pointer, use ~0UL to leave the instruction pointer unchanged, return previous instruction pointer.
[in,out]spNew stack pointer, use ~0UL to leave the stack pointer unchanged, returns previous stack pointer.
[in,out]flagsEx-regs flags, see L4_thread_ex_regs_flags, return previous CPU flags of the thread.
utcbUTCB to use for this operation.
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).

Definition at line 702 of file thread.h.

Referenced by l4_thread_ex_regs_ret().

+ 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
threadCapability selector of the thread to manipulate.
ipNew instruction pointer, use ~0UL to leave the instruction pointer unchanged.
spNew stack pointer, use ~0UL to leave the stack pointer unchanged.
flagsEx-regs flags, see L4_thread_ex_regs_flags.
utcbUTCB to use for this operation.
Returns
System call return tag

This method allows to manipulate 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).

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

Referenced by l4_thread_ex_regs().

+ 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
tagTag received from l4_thread_modify_sender_start() or previous l4_thread_modify_sender_add() calls from the same sequence.
match_maskBitmask of bits to match the label.
matchBitmask that must be equal to the label after applying match_mask.
del_bitsBits to be deleted from the label.
add_bitsBits to be added to the label.
Returns
0 on sucess, <0 on error

In pseudo code: if ((sender_label & match_mask) == match) { label = (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 1009 of file thread.h.

◆ 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.

See also
l4_thread_modify_sender_start
l4_thread_modify_sender_add

Definition at line 1020 of file thread.h.

◆ l4_thread_modify_sender_start()

l4_msgtag_t l4_thread_modify_sender_start ( void  )
inline

Start a thread sender modifiction 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().

See also
l4_thread_modify_sender_add
l4_thread_modify_sender_commit

Definition at line 1003 of file thread.h.

◆ 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
threadThread to register IRQ for.
irqCapability selector for the IRQ object to be triggered.
Returns
System call return tag containing the return code.

An example of a deletion event is the removal of an IPC gate that is bound to this thread.

Definition at line 930 of file thread.h.

◆ 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
threadThread to get the consumed time from.
[out]usConsumed time in µs.
Returns
system call return tag

Definition at line 898 of file thread.h.

◆ 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_threadThe thread to switch to.
Returns
system call return tag

Definition at line 889 of file thread.h.

◆ l4_thread_vcpu_control()

l4_msgtag_t l4_thread_vcpu_control ( l4_cap_idx_t  thread,
l4_addr_t  vcpu_state 
)
inline

Enable or disable the vCPU feature for the thread.

Parameters
threadCapability selector of the thread for which the vCPU feature shall be enabled or disabled.
vcpu_stateThe 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 if vcpu_state is set to a valid kernel-user-memory address, or disables the vCPU feature if vcpu_state is 0. (Disable: optional, currently unsupported.)

Definition at line 947 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 or disable the extended vCPU feature for the thread.

Parameters
threadCapability selector of the thread for which the extended vCPU feature shall be enabled or disabled.
ext_vcpu_stateThe 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
Systemcall result message 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 if ext_vcpu_state is set to a valid kernel-user-memory address, or disables the vCPU feature if ext_vcpu_state is 0.

Note
The extended vCPU mode includes the normal vCPU mode.

Definition at line 962 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 or disable the extended vCPU feature for the thread.

Parameters
threadCapability selector of the thread for which the extended vCPU feature shall be enabled or disabled.
ext_vcpu_stateThe 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()).
utcbUTCB to use for this operation.
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 if ext_vcpu_state is set to a valid kernel-user-memory address, or disables the vCPU feature if ext_vcpu_state is 0.

Note
The extended vCPU mode includes the normal vCPU mode.

Definition at line 952 of file thread.h.

Referenced by l4_thread_vcpu_control_ext().

+ 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 or disable the vCPU feature for the thread.

Parameters
threadCapability selector of the thread for which the vCPU feature shall be enabled or disabled.
vcpu_stateThe 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()).
utcbUTCB to use for this operation.
Returns
Syscall return tag.

This function enables the vCPU feature of this thread if vcpu_state is set to a valid kernel-user-memory address, or disables the vCPU feature if vcpu_state is 0. (Disable: optional, currently unsupported.)

Definition at line 937 of file thread.h.

Referenced by l4_thread_vcpu_control().

+ 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
threadThread to be resumed, the invalid cap can be used for the current thread.
tagTag to use, returned by l4_thread_vcpu_resume_start()
Returns
System call result message tag. In extended vCPU mode and when the virtual interrupts are cleared, the return code 1 flags an incoming IPC message, whereas 0 indicates a VM exit. An error is returned upon:
  • Insufficient rights on the given task capability (-L4_EPERM).
  • Given task capability is invalid (-L4_ENOENT).
  • A supplied mapping failed.

To resume into another address space the capability to the target task must be set in the vCPU-state, with all lower bits in the task capability cleared (see L4_CAP_MASK). The kernel adds the L4_SYSF_SEND flag to this field to indicate that the capability has been referenced in the kernel. Consecutive resumes will not reference the task capability again until all bits are cleared again. To release a task use the different task capability or use an invalid capability with the L4_SYSF_REPLY flag set.

See also
l4_vcpu_state_t

Definition at line 910 of file thread.h.

◆ 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 904 of file thread.h.

◆ l4_thread_yield()

l4_msgtag_t l4_thread_yield ( void  )
inline

Yield current time slice.

Returns
system call return tag

Definition at line 778 of file thread.h.

References L4_INVALID_CAP, and l4_ipc_receive().

+ Here is the call graph for this function: