L4Re - L4 Runtime Environment
Thread control

API for Thread Control method. More...

+ Collaboration diagram for Thread control:

Functions

void l4_thread_control_start (void) L4_NOTHROW
 Start a thread control API sequence. More...
 
void l4_thread_control_pager (l4_cap_idx_t pager) L4_NOTHROW
 Set the pager. More...
 
void l4_thread_control_exc_handler (l4_cap_idx_t exc_handler) L4_NOTHROW
 Set the exception handler. More...
 
void l4_thread_control_bind (l4_utcb_t *thread_utcb, l4_cap_idx_t task) L4_NOTHROW
 Bind the thread to a task. More...
 
void l4_thread_control_alien (int on) L4_NOTHROW
 Enable alien mode. More...
 
void l4_thread_control_ux_host_syscall (int on) L4_NOTHROW
 Enable pass through of native host (Linux) system calls. More...
 
l4_msgtag_t l4_thread_control_commit (l4_cap_idx_t thread) L4_NOTHROW
 Commit the thread control parameters. More...
 

Detailed Description

API for Thread Control method.

The thread control API provides access to almost any parameter of a thread object. The API is based on a single invocation of the thread object. However, because of the huge amount of parameters, the API provides a set of functions to set specific parameters of a thread and a commit function to commit the thread control call (see l4_thread_control_commit()).

A thread control operation must always start with l4_thread_control_start() and be committed with l4_thread_control_commit(). All other thread control parameter setter functions must be called between these two functions.

An example for a sequence of thread control API calls can be found below.

l4_utcb_t *u = l4_utcb();
l4_thread_control_start(u);
l4_thread_control_pager(u, pager_cap);
l4_thread_control_bind (u, thread_utcb, task);
l4_thread_control_commit(u, thread_cap);

Function Documentation

◆ l4_thread_control_alien()

void l4_thread_control_alien ( int  on)
inline

Enable alien mode.

Parameters
onBoolean value defining the state of the feature.

Alien mode means the thread is not allowed to invoke L4 kernel objects directly and it is also not allowed to allocate FPU state. All those operations result in an exception IPC that gets sent through the pager capability. The responsible pager can then selectively allow an object invocation or allocate FPU state for the thread.

This feature can be used to attach a debugger to a thread and trace all object invocations.

Examples:
examples/sys/aliens/main.c, and examples/sys/singlestep/main.c.

Definition at line 868 of file thread.h.

◆ l4_thread_control_bind()

void l4_thread_control_bind ( l4_utcb_t thread_utcb,
l4_cap_idx_t  task 
)
inline

Bind the thread to a task.

Parameters
thread_utcbThe address of the UTCB in the target task.
taskThe target task of the thread.

Binding a thread to a task has the effect that the thread afterwards executes code within that task and has access to the resources visible within that task.

Note
There should not be more than one thread use a UTCB to prevent data corruption.
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 862 of file thread.h.

◆ l4_thread_control_commit()

l4_msgtag_t l4_thread_control_commit ( l4_cap_idx_t  thread)
inline

Commit the thread control parameters.

Parameters
threadCapability selector of target thread to commit to.
Returns
system call return tag
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 880 of file thread.h.

◆ l4_thread_control_exc_handler()

void l4_thread_control_exc_handler ( l4_cap_idx_t  exc_handler)
inline

Set the exception handler.

Parameters
exc_handlerCapability selector invoked to send an exception IPC.
Note
The exception-handler capability selector is interpreted in the task the thread is bound to (executes in).
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 855 of file thread.h.

◆ l4_thread_control_pager()

void l4_thread_control_pager ( l4_cap_idx_t  pager)
inline

Set the pager.

Parameters
pagerCapability selector invoked to send a page-fault IPC.
Note
The pager capability selector is interpreted in the task the thread is bound to (executes in).
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 849 of file thread.h.

◆ l4_thread_control_start()

void l4_thread_control_start ( void  )
inline

Start a thread control API sequence.

This function starts a sequence of thread control API functions. After this functions any of following functions may be called in any order.

To commit the changes to the thread l4_thread_control_commit() must be called in the end.

Note
The thread control API calls store the parameters for the thread in the UTCB of the caller, this means between l4_thread_control_start() and l4_thread_control_commit() no functions that modify the UTCB contents must be called.
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 843 of file thread.h.

◆ l4_thread_control_ux_host_syscall()

void l4_thread_control_ux_host_syscall ( int  on)
inline

Enable pass through of native host (Linux) system calls.

Parameters
onBoolean value defining the state of the feature.
Precondition
Running on Fiasco-UX

This enables the thread to do host system calls. This feature is only available in Fiasco-UX and ignored in other environments.

Definition at line 874 of file thread.h.