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.

void	l4_thread_control_pager (l4_cap_idx_t pager) L4_NOTHROW
	Set the pager.

void	l4_thread_control_exc_handler (l4_cap_idx_t exc_handler) L4_NOTHROW
	Set the exception handler.

void	l4_thread_control_bind (l4_utcb_t *thread_utcb, l4_cap_idx_t task) L4_NOTHROW
	Bind the thread to a task.

void	l4_thread_control_alien (int on) L4_NOTHROW
	Enable alien mode.

void	l4_thread_control_ux_host_syscall (int on) L4_NOTHROW
	Enable pass through of native host (Linux) system calls.

l4_msgtag_t	l4_thread_control_commit (l4_cap_idx_t thread) L4_NOTHROW
	Commit the thread control parameters.

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_thread_control_start();
l4_thread_control_pager(pager_cap);
l4_thread_control_bind (thread_utcb, task);
l4_thread_control_commit(thread_cap);

Function Documentation

◆ l4_thread_control_alien()

void l4_thread_control_alien ( int on )

inline

Enable alien mode.

Parameters

on	Boolean value defining the state of the feature.

For a thread in alien mode the kernel produces just an exception IPC for each IPC and exception caused by the alien thread instead of handling these events regularly. (Page faults of alien threads and interrupts occuring while the alien thread is running are always handled regularly.) While the alien thread is blocking, the execption handler can inspect and modify the state of the alien thread and potentially also the systemcall arguments. If the exception handler replies with L4_PROTO_ALLOW_SYSCALL as message tag, the kernel handles the next IPC or exception of the alien thread in a regular way. If the exception handler leaves certain thread state unchanged (in particular the instruction pointer), this will be the IPC or exception that caused the call of the exception handler. For a regularly processed IPC or exception of the alien thread the kernel also performs an exception IPC on kernel exit.

This feature can be used to attach a debugger to a thread and trace all object invocations and their results. It could also be used to handle other systems that use the same syscall instruction as L4Re.

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

Definition at line 946 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ 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_utcb	The thread’s UTCB address within the task it shall be bound to. The address must be aligned (architecture dependent; at least word aligned) and it must point to at least L4_UTCB_OFFSET bytes of kernel-user memory.
task	The task the thread shall be bound to.

Precondition: The thread must not be bound to a task yet.

A thread may execute code in the context of a task if and only if the thread is bound to the task. To actually start execution, l4_thread_ex_regs() needs to be used. Execution in the context of the task means that the code has access to all the task’s resources (and only those). The executed code itself must be one of those resources. A thread can be bound at most once to a task.

Note: The UTCBs of different threads in the same task should not overlap in order 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 940 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_control_commit()

l4_msgtag_t l4_thread_control_commit ( l4_cap_idx_t thread )

inline

Commit the thread control parameters.

Parameters

thread Capability selector of target thread to commit to.

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 `thread` or the task capability set in l4_thread_control_bind().
-L4_EINVAL	Malformed thread control parameters.

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

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_control_exc_handler()

void l4_thread_control_exc_handler ( l4_cap_idx_t exc_handler )

inline

Set the exception handler.

Parameters

exc_handler Capability 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 933 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ l4_thread_control_pager()

void l4_thread_control_pager ( l4_cap_idx_t pager )

inline

Set the pager.

Parameters

pager Capability 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 927 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

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

l4_thread_control_pager()
l4_thread_control_exc_handler()
l4_thread_control_bind()
l4_thread_control_alien()
l4_thread_control_ux_host_syscall() (Fiasco-UX only)

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 (see l4_utcb()), 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 921 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

◆ 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

on	Boolean 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 952 of file thread.h.

References l4_utcb().

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ l4_thread_control_alien()

◆ l4_thread_control_bind()

◆ l4_thread_control_commit()

◆ l4_thread_control_exc_handler()

◆ l4_thread_control_pager()

◆ l4_thread_control_start()

◆ l4_thread_control_ux_host_syscall()