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

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

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

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

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

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 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_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 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

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

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

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 380 of file task.h.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ l4_unmap_flags_t

Function Documentation

◆ l4_task_add_ku_mem()

◆ l4_task_cap_equal()

◆ l4_task_cap_has_child()

◆ l4_task_cap_valid()

◆ l4_task_delete_obj()

◆ l4_task_map()

◆ l4_task_release_cap()

◆ l4_task_unmap()

◆ l4_task_unmap_batch()