Loading...
Searching...
No Matches
Capabilities
Base API

C interface for capabilities. More...

Collaboration diagram for Capabilities:

## Typedefs

typedef unsigned long | l4_cap_idx_t
| Capability selector type.

## Enumerations

enum | l4_cap_consts_t { L4_CAP_SHIFT , L4_CAP_SIZE = 1UL << L4_CAP_SHIFT , L4_CAP_OFFSET , L4_CAP_MASK , L4_INVALID_CAP , L4_INVALID_CAP_BIT = 1UL << (L4_CAP_SHIFT - 1) }
| Constants related to capability selectors. More...
enum | l4_default_caps_t { L4_BASE_TASK_CAP , L4_BASE_FACTORY_CAP , L4_BASE_THREAD_CAP , L4_BASE_PAGER_CAP , L4_BASE_LOG_CAP , L4_BASE_ICU_CAP , L4_BASE_SCHEDULER_CAP , L4_BASE_IOMMU_CAP , L4_BASE_DEBUGGER_CAP , L4_BASE_ARM_SMCCC_CAP , L4_BASE_CAPS_LAST_P1 , L4_BASE_CAPS_LAST = L4_BASE_CAPS_LAST_P1 - 1 }
| Default capabilities setup for the initial tasks. More...

## Functions

unsigned | l4_is_invalid_cap (l4_cap_idx_t c) L4_NOTHROW
| Test if a capability selector is the invalid capability.
unsigned | l4_is_valid_cap (l4_cap_idx_t c) L4_NOTHROW
| Test if a capability selector is a valid selector.
unsigned | l4_capability_equal (l4_cap_idx_t c1, l4_cap_idx_t c2) L4_NOTHROW
| Test if the capability indices of two capability selectors are equal.

## Detailed Description

C interface for capabilities.

Add

    #include <l4/sys/types.h>
    #include <l4/sys/consts.h>

to your code to use the functions and definitions explained here.

## Typedef Documentation

## l4_cap_idx_t

typedef unsigned long l4_cap_idx_t

Capability selector type.

A capability selector is either a (shifted) capability index or the invalid capability selector L4_INVALID_CAP.

Usage of the invalid capability selector is defined only for invoking IPC (see Object Invocation): When IPC is invoked on L4_INVALID_CAP, then it is resolved to a capability for the current thread with full permissions.

Otherwise, the API assumes that each argument of type l4_cap_idx_t is a capability index, i.e., idx << L4_CAP_SHIFT for arbitrary idx. The behavior for other arguments is then undefined.

Examples
  examples/libs/shmc/prodcons.c, examples/sys/aliens/main.c, examples/sys/isr/main.c, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 336 of file types.h.

## Enumeration Type Documentation

## l4_cap_consts_t

enum l4_cap_consts_t

Constants related to capability selectors.

Enumerator
L4_CAP_SHIFT | Capability index shift.

L4_CAP_SIZE

Deprecated
  Superseded by L4_CAP_OFFSET.

L4_CAP_OFFSET | Offset of two consecutive capability selectors.
L4_CAP_MASK | Mask to get only the relevant bits of an l4_cap_idx_t.
L4_INVALID_CAP | Invalid capability selector.

Definition at line 139 of file consts.h.

## l4_default_caps_t

enum l4_default_caps_t

Default capabilities setup for the initial tasks.

These capability selectors are setup per default by the micro kernel for the two initial tasks, the Root-Pager (Sigma0) and the Root-Task (Moe).

Attention
  These constants do not have any particular meaning for applications started by Moe, see Initial Environment for this kind of information.

See also
  Initial Environment for information useful for normal user applications.

Enumerator
L4_BASE_TASK_CAP | Capability selector for the current task.
L4_BASE_FACTORY_CAP | Capability selector for the factory.
L4_BASE_THREAD_CAP | Capability selector for the first thread.
L4_BASE_PAGER_CAP | Capability selector for the pager gate. For Sigma0, the pager is not present since it never raises page faults. For Moe, the pager is set to Sigma0.
L4_BASE_LOG_CAP | Capability selector for the log object. Present if the corresponding feature is turned on in the microkernel configuration.
L4_BASE_ICU_CAP | Capability selector for the base icu object.
L4_BASE_SCHEDULER_CAP | Capability selector for the scheduler cap.
L4_BASE_IOMMU_CAP | Capability selector for the IO-MMU cap. Present if the microkernel detected an IO-MMU.
L4_BASE_DEBUGGER_CAP | Capability selector for the debugger cap. Present if the corresponding feature is turned on in the microkernel configuration.
L4_BASE_ARM_SMCCC_CAP | Capability selector for the ARM SMCCC cap. Present if the microkernel detected an ARM SMC capable trusted execution environment.
L4_BASE_CAPS_LAST | Last capability index used for base capabilities.

Definition at line 324 of file consts.h.

## Function Documentation

## l4_capability_equal()

unsigned l4_capability_equal | ( | l4_cap_idx_t | c1,
|  | l4_cap_idx_t | c2 )

inline

Test if the capability indices of two capability selectors are equal.

Parameters

  c1 | Capability selector.
  c2 | Capability selector.

Return values

  0 | The index parts of the capability selectors differ.
  1 | The index parts of the capability selectors are equal.

Precondition
  Both capability selectors must be valid (cf. l4_is_valid_cap()) otherwise the return value is undefined.

Definition at line 397 of file types.h.

References L4_CAP_SHIFT, and L4_NOTHROW.

## l4_is_invalid_cap()

unsigned l4_is_invalid_cap | ( | l4_cap_idx_t | c | ) |

inline

Test if a capability selector is the invalid capability.

Parameters

  c | Capability selector

Return values

  0 | The capability selector is not the invalid capability.
  >0 | The capability selector is the invalid capability.

Examples
  examples/libs/l4re/c/ma+rm.c, examples/sys/aliens/main.c, examples/sys/isr/main.c, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 389 of file types.h.

References L4_NOTHROW.

## l4_is_valid_cap()

unsigned l4_is_valid_cap | ( | l4_cap_idx_t | c | ) |

inline

Test if a capability selector is a valid selector.

Parameters

  c | Capability selector

Return values

  0 | The capability selector is not valid.
  >0 | The capability selector is valid.

Definition at line 393 of file types.h.

References L4_NOTHROW.

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

Here is the caller graph for this function: