Loading...
Searching...
No Matches
Task
Base API » Kernel Objects

C interface of the Task kernel object, see L4::Task for the C++ interface. 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_vgicc_map (l4_cap_idx_t task, l4_fpage_t vgicc_fpage) L4_NOTHROW
| Map the GIC virtual CPU interface page to the task in case Fiasco detected a GIC version 2.
l4_msgtag_t | l4_task_map (l4_cap_idx_t dst_task, l4_cap_idx_t src_task, l4_fpage_t snd_fpage, l4_umword_t snd_base) L4_NOTHROW
| Map resources available in the source task to a destination task.
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.
l4_msgtag_t | l4_task_unmap_batch (l4_cap_idx_t task, l4_fpage_t const *fpages, unsigned num_fpages, l4_umword_t map_mask) L4_NOTHROW
| Revoke rights from a task.
l4_msgtag_t | l4_task_delete_obj (l4_cap_idx_t task, l4_cap_idx_t obj) L4_NOTHROW
| Release capability and delete object.
l4_msgtag_t | l4_task_release_cap (l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
| Release object capability.
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).
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 permissions (only considering selected permissions).
l4_msgtag_t | l4_task_add_ku_mem (l4_cap_idx_t task, l4_fpage_t *ku_mem) L4_NOTHROW
| Add kernel-user memory.

## Detailed Description

C interface of the Task kernel object, see L4::Task for the C++ interface.

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 revoke permissions from all child mappings including the mapping in the invoked task.

Note
  Object capabilities are not hierarchical – they have no children. The result of the map operation on an object capability is a copy of that capability in the object space of the destination task. An unmap operation on object capabilities is a no-op if this flag is not specified.

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

L4_FP_DELETE_OBJ

Flag that indicates that an unmap operation on object capabilities shall try to delete the corresponding objects immediately.

This flag implies the L4_FP_ALL_SPACES flag. The concept of deletion is only applicable to kernel objects. Therefore, for memory and I/O port capabilities, this flag has the same effect as L4_FP_ALL_SPACES alone.

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

Note
  Specifying L4_FP_DELETE_OBJ ^ L4_FP_ALL_SPACES is treated as L4_FP_OTHER_SPACES.

L4_FP_OTHER_SPACES

Counterpart to L4_FP_ALL_SPACES; revoke permissions from child mappings only.

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

Definition at line 169 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.
  [in,out] | ku_mem | Flexpage describing the virtual area the memory goes to. On systems without MMU, the flexpage is adjusted to reflect the acually allocated physical address.

Returns
  Syscall return tag

Kernel-user memory (ku_mem) is memory that is shared between the kernel and user-space. It is needed for the UTCB area of threads (see l4_thread_control_bind()) and for (extended) vCPU state. Note that existing kernel-user memory cannot be unmapped or mapped somewhere else.

Note
  The amount of kernel-user memory that can be allocated at once is limited by the used kernel implementation. The minimum allocatable amount is one page (L4_PAGESIZE). A portable implementation should not depend on allocations greater than 16KiB to succeed.
  This function is only guaranteed to work on L4::Task objects. It might or might not work on L4::Vm objects or on L4Re::Dma_space objects but there is no practical use for adding kernel-user memory to L4::Vm objects or to L4Re::Dma_space objects.

Definition at line 497 of file task.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## 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 permissions (only considering selected permissions).

Parameters

  task | Capability selector for the destination task to do the lookup in.
  cap_a | Capability selector for the first capability to compare.
  cap_b | Capability selector for the second capability to compare.

Return values

  l4_msgtag_t::label() = 1 | The compared capabilities point to the same object with same considered permission.
  l4_msgtag_t::label() = 0 | The compared capabilities do not point to the same object or differ in the considered permission.

- For L4::Ipc_gate objects, only the permissions L4_CAP_FPAGE_W, L4_CAP_FPAGE_S, and L4_FPAGE_C_OBJ_RIGHT1 are considered for the comparison. Differences in other permissions are ignored.
- For other objects, only the permissions L4_CAP_FPAGE_W and L4_CAP_FPAGE_S are considered for the comparison. Differences in other permissions are ignored.

Note that having the L4_CAP_FPAGE_R permission is implicit in possessing the capability.

Definition at line 490 of file task.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

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

  l4_msgtag_t::label() > 0 | Capability is present (refers to an object).
  l4_msgtag_t::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 484 of file task.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## 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 index of the object to delete.

Returns
  Syscall return tag

If obj has the delete permission, initiates the deletion of the object. This implies that all capabilities for that object are gone afterwards. However, kernel-internally, objects are not destroyed until all other kernel objects holding a reference to it drop the reference. Hence, quota used by that object might not be freed immediately.

If obj does not have the delete permission, no error will be reported and only the capability obj is removed. (Note that, depending on the object’s reference counter, this might still imply initiation of deletion.)

This operation is equivalent to l4_task_unmap() with L4_FP_DELETE_OBJ flag.

Definition at line 463 of file task.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## 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_umword_t | snd_base )

inline

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

Parameters

  dst_task | Capability selector of the destination task.
  src_task | Capability selector of the 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. The lower bits contain additional map control flags (see l4_fpage_cacheability_opt_t for memory mappings, L4_obj_fpage_ctl for object mappings, and L4_MAP_ITEM_GRANT; also see l4_map_control() and l4_map_obj_control()).

Returns
  Syscall return tag. The function l4_error() shall be used to test if the map operation was successful.

Return values

  L4_EOK | Operation successful (but see notes below).
  -L4_EPERM | Insufficient permissions; see precondition.
  -L4_EINVAL | Invalid source task capability.
  -L4_IPC_SEMAPFAILED | The map operation failed due to limited quota.

Precondition
  The capability dst_task must have the permission L4_CAP_FPAGE_W.

This method allows for asynchronous transfer of capabilities, memory mappings, and IO-port mappings (on IA32) from one task to another. The receive window is the whole address space of dst_task. By specifying proper rights in snd_fpage and snd_base, it is possible to remove rights during transfer.

Note
  If the send flexpage is of type L4_FPAGE_OBJ, the L4_CAP_FPAGE_S right is removed from the transferred capability unless both the source and destination task capabilities possess the L4_CAP_FPAGE_S right themselves.
  Even with l4_error() returning L4_EOK there might be cases where not all pages of the send flexpage were mapped respectively granted to the destination task, for instance, if the corresponding mapping in the destination task does already exist.

For more information on spaces and mappings, see Spaces and Mappings. The flexpage API is described in more detail at Flexpages.

Note
  For peculiarities when using grant, see L4_MAP_ITEM_GRANT.

Definition at line 433 of file task.h.

References L4_NOTHROW, and l4_utcb().

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

Here is the call graph for this function:
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 object capability.

Parameters

  task | Capability selector of destination task
  cap | Capability selector of object to release

Returns
  Syscall return tag

This operation unmaps the capability from the specified task. This operation is equivalent to unmapping a single object capability by specifying all object rights as unmap mask.

Note
  If the reference counter of the kernel object referenced by cap goes down to zero, deletion of the object is initiated. Objects are not destroyed until all other kernel objects holding a reference to it drop the reference.

Definition at line 478 of file task.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## 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 one capability space of the destination task and the rights to revoke.
  map_mask | Unmap mask, see l4_unmap_flags_t

Returns
  Syscall return tag

This method allows to revoke rights from the destination task. The rights to revoke are specified in the flexpage, see l4_fpage_rights(). For a flexpage describing IO ports or memory, it also revokes rights from all the tasks that got the rights delegated from the destination task (i.e., this operation does a recursive rights revocation). The capability is unmapped if certain rights are specified, see below for details. It is guaranteed that the rights revocation is completed before this function returns.

Note that this function cannot be used to revoke the reference counting permission (see L4_FPAGE_C_REF_CNT) or the IPC-gate server permission (see L4_FPAGE_C_IPCGATE_SVR) from object capabilities.

It depends on the platform and the object type which rights need to be specified in the rights field of fpage to unmap a capability:

- An object capability is unmapped if and only if the L4_CAP_FPAGE_R right bit is set.
- An IO port is unmapped if and only if any right bit is set.
- Memory is unmapped if and only if the L4_FPAGE_RO right bit is set.

Note
  Depending on the page-table features supported by the hardware, revocation of certain rights from a memory capability can be a no-op (i.e., the rights are not revoked). Further, revocation of certain rights may grant other rights which were not present before. For instance, on an architecture without support for NX, revoking X does nothing. For another example, revoking only X from an execute-only page grants read permission (because the mapping remains present in the page table).
  If the reference counter of a kernel object referenced in fpage goes down to zero (as a result of deleting capabilities), the deletion of the object is initiated. Objects are not destroyed until all other kernel objects holding a reference to it drop the reference.

Examples
  examples/sys/utcb-ipc/main.c.

Definition at line 440 of file task.h.

References L4_NOTHROW, and l4_utcb().

Referenced by L4Re::Util::Cap_alloc_base::free(), L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::free(), and L4Re::Util::Counting_cap_alloc< COUNTERTYPE, Dbg >::release().

Here is the call graph for this function:
Here is the caller graph for this function:

## l4_task_unmap_batch()

l4_msgtag_t l4_task_unmap_batch | ( | l4_cap_idx_t | task,
|  | l4_fpage_t const * | fpages,
|  | unsigned | num_fpages,
|  | l4_umword_t | map_mask )

inline

Revoke rights from a task.

Parameters

  task | Capability selector of destination task
  fpages | An array of flexpages. Each item describes an area in one capability space of the destination task.
  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

Revoke rights specified in an array of flexpages, see l4_task_unmap for details.

Precondition
  The caller needs to take care that num_fpages is not bigger than L4_UTCB_GENERIC_DATA_SIZE - 2.

Definition at line 447 of file task.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_task_vgicc_map()

l4_msgtag_t l4_task_vgicc_map | ( | l4_cap_idx_t | task,
|  | l4_fpage_t | vgicc_fpage )

inline

Map the GIC virtual CPU interface page to the task in case Fiasco detected a GIC version 2.

Parameters

  task | Capability selector of destination task
  vgicc_fpage | Flexpage that describes an area in the address space of the destination task to map the vGICC page to

Returns
  Syscall return tag

Definition at line 46 of file __task-arm.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function: