l4_task_new -- create or delete a task

1 Synopsis

#include <l4/sys/syscalls.h>

static inline l4_taskid_t
l4_task_new(l4_taskid_t dest , l4_umword_t mcp_or_new_chief , l4_umword_t esp , l4_umword_t eip , l4_threadid_t pager );

2 Description

The l4_task_new() system call deletes and/or creates a task. Deletion of a task means that the address space of the task and all threads of the task disappear. The cpu time of all deleted threads is added to the cputime of the deleting thread. If the deleted task was chief of a clan, all tasks of the clan are deleted as well.

Tasks may be created as active or inactive. For an active task, a new address space is created together with 128 threads. Lthread 0 is started, the other ones wait for a "real" creation using l4_thread_ex_regs(). An inactive task is empty. It occupies no resources, has no address space and no threads. Communication with inactive tasks is not possible.

A newly created task gets the creator as its chief, i.e. it is created inside the creator's clan. Symmetrically, a task can only be deleted either directly by its chief or indirectly by a higher-level chief.

3 Arguments

Task id of an existing task whose chief is the current task. If this is not fulfilled, the system call has no effect. Simultaneously, a new task with the same task number is created. It may be active or inactive.
Depending on the state of the task (active or inactive), two variants are possible here:

Maximum controlled priority defines the highest priority which can be ruled by the new task acting as a scheduler. The new task's effective mcp is the minimum of the creator's mcp and the specified mcp. Use this parameter if the newly generated task is an active task.
Specifies the chief of the new inactive task. This mechanism permits to transfer inactive tasks to other tasks. Transferring an inactive task to the specified chief means to transfer the related right to create a task. Use this parameter if the newly generated task is an inactive task.
Initial stack pointer for lthread 0 if the new task is created as an active one. Ignore otherwise.
Initial instruction pointer for lthread 0 if the new task is created as an active one. Ignored otherwise.
If L4_NIL_ID is used, the new task is created as inactive. Lthread 0 is not created. Otherwise the new task is created as active and the specified pager is associated to Lthread 0.

4 Return Values If task creation succeeded its id is delivered

back. If the new task is active, the new task id will have a new version number so that it differs from all task ids used earlier. Chief and task number are the same as in dest task. If the new task is created inactive, the chief is taken from the chief parameter; the task number remains unchanged. The version is undefined so that the new task id might be identical with a formerly (but not currently and not in future) valid task id. This is safe since communication with inactive tasks is impossible.

If task creation failed L4_NIL_ID is returned.

5 See Also

l4_thread_ex_regs , l4_myself , l4_nchief , l4_thread_switch , l4_thread_schedule , l4_task_new