Task

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

enum 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

task	Capability selector of the task to add the memory to
ku_mem	Flexpage describing the virtual area the memory goes to.

Returns

Syscall return tag

Definition at line 439 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

task	Capability selector of the destination task to do the lookup in
cap_a	Capability selector to compare
cap_b	Capability selector to compare

Returns

label contains 1 if equal, 0 if not equal

Definition at line 432 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

task	Capability selector of the destination task to do the lookup in
cap	Capability 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 426 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

task	Task to check the capability in.
cap	Valid capability 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.

Precondition

cap must be a valid capability index (i.e. not L4_INVALID_CAP or the like).

Definition at line 420 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

task	Capability selector of destination task
obj	Capability 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 399 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_task	Capability selector of destination task
src_task	Capability selector of source task
snd_fpage	Send flexpage that describes an area in the address space or object space of the source task.
snd_base	Send 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 369 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

task	Capability selector of destination task
cap	Capability selector to release

Returns

Syscall return tag

This operation unmaps the capability from the specified task.

Definition at line 414 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

task	Capability selector of destination task
fpage	Flexpage that describes an area in the address space or object space of the destination task
map_mask	Unmap 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 376 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

task	Capability selector of destination task
fpages	An array of flexpages that describes an area in the address space or object space of the destination task each
num_fpages	The size of the fpages array in elements (number of fpages sent).
map_mask	Unmap 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 383 of file task.h.