L4Re - L4 Runtime Environment

C interface of the Task kernel object. More...

+ Collaboration diagram for Task:

Enumerations

enum  l4_unmap_flags_t { L4_FP_ALL_SPACES, L4_FP_DELETE_OBJ, L4_FP_OTHER_SPACES }
 Flags for the unmap operation. More...
 

Functions

l4_msgtag_t l4_task_map (l4_cap_idx_t dst_task, l4_cap_idx_t src_task, l4_fpage_t snd_fpage, l4_addr_t snd_base) L4_NOTHROW
 Map resources available in the source task to a destination task. More...
 
l4_msgtag_t l4_task_unmap (l4_cap_idx_t task, l4_fpage_t fpage, l4_umword_t map_mask) L4_NOTHROW
 Revoke rights from the task. More...
 
l4_msgtag_t l4_task_unmap_batch (l4_cap_idx_t task, l4_fpage_t const *fpages, unsigned num_fpages, unsigned long map_mask) L4_NOTHROW
 Revoke rights from a task. More...
 
l4_msgtag_t l4_task_delete_obj (l4_cap_idx_t task, l4_cap_idx_t obj) L4_NOTHROW
 Release capability and delete object. More...
 
l4_msgtag_t l4_task_release_cap (l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
 Release capability. More...
 
l4_msgtag_t l4_task_cap_valid (l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
 Check whether a capability is present (refers to an object). More...
 
l4_msgtag_t l4_task_cap_has_child (l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
 Test whether a capability has child mappings (in another task). More...
 
l4_msgtag_t l4_task_cap_equal (l4_cap_idx_t task, l4_cap_idx_t cap_a, l4_cap_idx_t cap_b) L4_NOTHROW
 Test whether two capabilities point to the same object with the same rights. More...
 
l4_msgtag_t l4_task_add_ku_mem (l4_cap_idx_t task, l4_fpage_t ku_mem) L4_NOTHROW
 Add kernel-user memory. More...
 

Detailed Description

C interface of the Task kernel object.

A task represents a combination of the address spaces provided by the L4Re micro kernel. A task consists of at least a memory address space and an object address space. On IA32 there is also an IO-port address space.

Task objects are created using the Factory interface.

Include File
#include <l4/sys/task.h>

Enumeration Type Documentation

◆ l4_unmap_flags_t

Flags for the unmap operation.

See also
L4::Task::unmap() and l4_task_unmap()
Enumerator
L4_FP_ALL_SPACES 

Flag to tell the unmap operation to unmap all child mappings including the mapping in the invoked task.

See also
L4::Task::unmap() l4_task_unmap()
L4_FP_DELETE_OBJ 

Flag that indicates that the unmap operation on a capability shall try to delete the corresponding objects immediately.

See also
L4::Task::unmap() l4_task_unmap()
L4_FP_OTHER_SPACES 

Counterpart to L4_FP_ALL_SPACES, unmap only child mappings.

See also
L4::Task::unmap() l4_task_unmap()

Definition at line 157 of file consts.h.

Function Documentation

◆ l4_task_add_ku_mem()

l4_msgtag_t l4_task_add_ku_mem ( l4_cap_idx_t  task,
l4_fpage_t  ku_mem 
)
inline

Add kernel-user memory.

Parameters
taskCapability selector of the task to add the memory to
ku_memFlexpage describing the virtual area the memory goes to.
Returns
Syscall return tag

Definition at line 436 of file task.h.

◆ l4_task_cap_equal()

l4_msgtag_t l4_task_cap_equal ( l4_cap_idx_t  task,
l4_cap_idx_t  cap_a,
l4_cap_idx_t  cap_b 
)
inline

Test whether two capabilities point to the same object with the same rights.

Parameters
taskCapability selector of the destination task to do the lookup in
cap_aCapability selector to compare
cap_bCapability selector to compare
Returns
label contains 1 if equal, 0 if not equal

Definition at line 429 of file task.h.

◆ l4_task_cap_has_child()

l4_msgtag_t l4_task_cap_has_child ( l4_cap_idx_t  task,
l4_cap_idx_t  cap 
)
inline

Test whether a capability has child mappings (in another task).

Parameters
taskCapability selector of the destination task to do the lookup in
capCapability selector to look up in the destination task
Returns
label contains 1 if it has at least one child, 0 if not or invalid
Deprecated:
Do not use. Undetermined future, might be removed.

Definition at line 423 of file task.h.

◆ l4_task_cap_valid()

l4_msgtag_t l4_task_cap_valid ( l4_cap_idx_t  task,
l4_cap_idx_t  cap 
)
inline

Check whether a capability is present (refers to an object).

Parameters
taskTask to check the capability in.
capCapability to check for presence..
Return values
tag.label()> 0 Capability is present (refers to an object).
tag.label()== 0 No capability present (void object).

A capability is considered present when it refers to an existing kernel object.

Definition at line 417 of file task.h.

◆ l4_task_delete_obj()

l4_msgtag_t l4_task_delete_obj ( l4_cap_idx_t  task,
l4_cap_idx_t  obj 
)
inline

Release capability and delete object.

Parameters
taskCapability selector of destination task
objCapability selector of object to delete
Returns
Syscall return tag

The object will be deleted if the obj has sufficient rights. No error will be reported if the rights are insufficient, however, the capability is removed in all cases.

This operation calls l4_task_unmap() with L4_FP_DELETE_OBJ.

Definition at line 396 of file task.h.

◆ l4_task_map()

l4_msgtag_t l4_task_map ( l4_cap_idx_t  dst_task,
l4_cap_idx_t  src_task,
l4_fpage_t  snd_fpage,
l4_addr_t  snd_base 
)
inline

Map resources available in the source task to a destination task.

Parameters
dst_taskCapability selector of destination task
src_taskCapability selector of source task
snd_fpageSend flexpage that describes an area in the address space or object space of the source task.
snd_baseSend base that describes an offset in the receive window of the destination task.
Returns
Syscall return tag

This method allows for asynchronous rights delegation from one task to another. It can be used to share memory as well as to delegate access to objects.

Definition at line 366 of file task.h.

Referenced by L4::Cap_base::copy(), and L4::Cap_base::move().

+ Here is the caller graph for this function:

◆ l4_task_release_cap()

l4_msgtag_t l4_task_release_cap ( l4_cap_idx_t  task,
l4_cap_idx_t  cap 
)
inline

Release capability.

Parameters
taskCapability selector of destination task
capCapability selector to release
Returns
Syscall return tag

This operation unmaps the capability from the specified task.

Definition at line 411 of file task.h.

◆ l4_task_unmap()

l4_msgtag_t l4_task_unmap ( l4_cap_idx_t  task,
l4_fpage_t  fpage,
l4_umword_t  map_mask 
)
inline

Revoke rights from the task.

Parameters
taskCapability selector of destination task
fpageFlexpage that describes an area in the address space or object space of the destination task
map_maskUnmap mask, see l4_unmap_flags_t
Returns
Syscall return tag

This method allows to revoke rights from the destination task and from all the tasks that got the rights delegated from that task (i.e., this operation does a recursive rights revocation).

Note
Calling this function on the object space can cause a root capability of an object to be destructed, which destroys the object itself.

Definition at line 373 of file task.h.

◆ l4_task_unmap_batch()

l4_msgtag_t l4_task_unmap_batch ( l4_cap_idx_t  task,
l4_fpage_t const *  fpages,
unsigned  num_fpages,
unsigned long  map_mask 
)
inline

Revoke rights from a task.

Parameters
taskCapability selector of destination task
fpagesAn array of flexpages that describes an area in the address space or object space of the destination task each
num_fpagesThe size of the fpages array in elements (number of fpages sent).
map_maskUnmap mask, see l4_unmap_flags_t
Returns
Syscall return tag

This method allows to revoke rights from the destination task and from all the tasks that got the rights delegated from that task (i.e., this operation does a recursive rights revocation).

Precondition
The caller needs to take care that num_fpages is not bigger than L4_UTCB_GENERIC_DATA_SIZE - 2.
Note
Calling this function on the object space can cause a root capability of an object to be destructed, which destroys the object itself.

Definition at line 380 of file task.h.