C interface for capabilities. More...

Collaboration diagram for Capabilities:

Macros
#define	L4_CAP_SHIFT
	Capability index shift; see l4_cap_idx_t.
#define	L4_CAP_SIZE
	Deprecated.
#define	L4_CAP_OFFSET
	Offset of two consecutive capability indices.
#define	L4_CAP_MASK
	Mask to get only the relevant bits of an l4_cap_idx_t.
#define	L4_INVALID_CAP
	Invalid capability selector; see l4_cap_idx_t.
#define	L4_INVALID_CAP_BIT
	Bit indicating if a capability selector is invalid.

Typedefs
typedef unsigned long	l4_cap_idx_t
	Capability selector type.

Enumerations
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 invalid (i.e., L4_INVALID_CAP_BIT is set).
unsigned	l4_is_valid_cap (l4_cap_idx_t c) L4_NOTHROW
	Test if a capability selector is valid (i.e., L4_INVALID_CAP_BIT is not set).
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.

Macro Definition Documentation

◆ L4_CAP_SIZE

#define L4_CAP_SIZE

Deprecated.

Deprecated: Superseded by L4_CAP_OFFSET.

Definition at line 149 of file consts.h.

◆ L4_INVALID_CAP_BIT

#define L4_INVALID_CAP_BIT

Bit indicating if a capability selector is invalid.

If the bit is set, the capability selector is considered invalid.

Definition at line 173 of file consts.h.

Referenced by L4::Cap_base::invalid_cap_error(), L4::Cap_base::is_valid(), L4::Ipc::Cap< A >::is_valid(), l4_is_invalid_cap(), and l4_is_valid_cap().

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, a (shifted) reply capability index or the invalid capability selector L4_INVALID_CAP.

An alternative, synonymous term for capability index is capability slot.

When an interface expects an argument of type l4_cap_idx_t and the documentation does not state any specifics, it is assumed that the argument is an object capability index, i.e., idx << L4_CAP_SHIFT for arbitrary idx. The behavior for other values is then undefined.

Some interfaces allow use of L4_INVALID_CAP for indicating the absence of a capability index.

When invoking IPC (see Object Invocation), all types of capability selectors are relevant. The particular type is determined by the IPC operation.

When the operation is a reply (with or without a receive phase) or an open wait without a send, then the selector refers to a reply capability.
Otherwise, the selector refers to an object capability.

When not L4_INVALID_CAP, the selector contains a capability index for the respective space (reply capability space or object capability space) of the current task. When the selector is L4_INVALID_CAP, the meaning depends on the type of capability:

When the operation needs a reply capability, the implicit reply capability of the invoking thread is used.
When the operation needs an object capability, an implicit object capability for the current thread with full permissions is used.

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 374 of file types.h.

Enumeration Type Documentation

◆ l4_default_caps_t

enum l4_default_caps_t

Default capabilities setup for the initial tasks.

These capability indices 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 index for the current task.
L4_BASE_FACTORY_CAP	Capability index for the factory.
L4_BASE_THREAD_CAP	Capability index for the first thread.
L4_BASE_PAGER_CAP	Capability index 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 index for the log object. Present if the corresponding feature is turned on in the microkernel configuration.
L4_BASE_ICU_CAP	Capability index for the base icu object.
L4_BASE_SCHEDULER_CAP	Capability index for the scheduler cap.
L4_BASE_IOMMU_CAP	Capability index for the IO-MMU cap. Present if the microkernel detected an IO-MMU.
L4_BASE_DEBUGGER_CAP	Capability index for the debugger cap. Present if the corresponding feature is turned on in the microkernel configuration.
L4_BASE_ARM_SMCCC_CAP	Capability index 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 341 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 436 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 invalid (i.e., L4_INVALID_CAP_BIT is set).

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 428 of file types.h.

References L4_INVALID_CAP_BIT, and L4_NOTHROW.

◆ l4_is_valid_cap()

unsigned l4_is_valid_cap ( l4_cap_idx_t c )

inline

Test if a capability selector is valid (i.e., L4_INVALID_CAP_BIT is not set).

Parameters

c	Capability selector

Return values

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

Definition at line 432 of file types.h.

References L4_INVALID_CAP_BIT, and 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:

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ L4_CAP_SIZE

◆ L4_INVALID_CAP_BIT

Typedef Documentation

◆ l4_cap_idx_t

Enumeration Type Documentation

◆ l4_default_caps_t

Function Documentation

◆ l4_capability_equal()

◆ l4_is_invalid_cap()

◆ l4_is_valid_cap()