Flexpage-related API. More...

Collaboration diagram for Flexpages:

Data Structures
union	l4_fpage_t
	L4 flexpage type. More...

Enumerations
enum	L4_fpage_consts { L4_FPAGE_RIGHTS_SHIFT = 0 , L4_FPAGE_TYPE_SHIFT = 4 , L4_FPAGE_SIZE_SHIFT = 6 , L4_FPAGE_ADDR_SHIFT = 12 , L4_FPAGE_RIGHTS_BITS = 4 , L4_FPAGE_TYPE_BITS = 2 , L4_FPAGE_SIZE_BITS = 6 , L4_FPAGE_ADDR_BITS = L4_MWORD_BITS - L4_FPAGE_ADDR_SHIFT , L4_FPAGE_RIGHTS_MASK , L4_FPAGE_TYPE_MASK , L4_FPAGE_SIZE_MASK , L4_FPAGE_ADDR_MASK = ~0UL << L4_FPAGE_ADDR_SHIFT , L4_FPAGE_RIGHTS_ALL = L4_FPAGE_RIGHTS_MASK }
	L4 flexpage structure. More...

enum	{ L4_WHOLE_ADDRESS_SPACE = 63 }
	Constants for flexpages. More...

enum	L4_fpage_rights { L4_FPAGE_X = 1 , L4_FPAGE_W = 2 , L4_FPAGE_RO = 4 , L4_FPAGE_RW = L4_FPAGE_RO \| L4_FPAGE_W , L4_FPAGE_RX = L4_FPAGE_RO \| L4_FPAGE_X , L4_FPAGE_RWX = L4_FPAGE_RW \| L4_FPAGE_X }
	Memory and IO port flexpage rights. More...

enum	L4_cap_fpage_rights { L4_CAP_FPAGE_W = 0x1 , L4_CAP_FPAGE_S = 0x2 , L4_CAP_FPAGE_R = 0x4 , L4_CAP_FPAGE_RO = 0x4 , L4_CAP_FPAGE_D = 0x8 , L4_CAP_FPAGE_RW = L4_CAP_FPAGE_R \| L4_CAP_FPAGE_W , L4_CAP_FPAGE_RS = L4_CAP_FPAGE_R \| L4_CAP_FPAGE_S , L4_CAP_FPAGE_RWS = L4_CAP_FPAGE_RW \| L4_CAP_FPAGE_S , L4_CAP_FPAGE_RWSD = L4_CAP_FPAGE_RWS \| L4_CAP_FPAGE_D , L4_CAP_FPAGE_RWD = L4_CAP_FPAGE_RW \| L4_CAP_FPAGE_D , L4_CAP_FPAGE_RSD = L4_CAP_FPAGE_RS \| L4_CAP_FPAGE_D }
	Object flexpage rights. More...

enum	L4_fpage_type { L4_FPAGE_SPECIAL = 0 , L4_FPAGE_MEMORY = 1 , L4_FPAGE_IO = 2 , L4_FPAGE_OBJ = 3 }
	Flexpage type. More...

enum	L4_fpage_control { L4_FPAGE_CONTROL_OFFSET_SHIFT = 12 , L4_FPAGE_CONTROL_MASK = ~0UL << L4_FPAGE_CONTROL_OFFSET_SHIFT }
	Flexpage map control flags. More...

enum	{ L4_WHOLE_IOADDRESS_SPACE = 16 , L4_IOPORT_MAX = (1L << L4_WHOLE_IOADDRESS_SPACE) }
	Special constants for IO flexpages. More...

Functions
l4_fpage_t	l4_fpage (l4_addr_t address, unsigned int order, unsigned char rights) L4_NOTHROW
	Create a memory flexpage.

l4_fpage_t	l4_fpage_all (void) L4_NOTHROW
	Get a flexpage, describing all address spaces at once.

l4_fpage_t	l4_fpage_invalid (void) L4_NOTHROW
	Get an invalid flexpage.

l4_fpage_t	l4_iofpage (unsigned long port, unsigned int order) L4_NOTHROW
	Create an IO-port flexpage.

l4_fpage_t	l4_obj_fpage (l4_cap_idx_t obj, unsigned int order, unsigned char rights) L4_NOTHROW
	Create a kernel-object flexpage.

int	l4_is_fpage_writable (l4_fpage_t fp) L4_NOTHROW
	Test if the flexpage is writable.

unsigned	l4_fpage_rights (l4_fpage_t f) L4_NOTHROW
	Return rights from a flexpage.

unsigned	l4_fpage_type (l4_fpage_t f) L4_NOTHROW
	Return type from a flexpage.

unsigned	l4_fpage_size (l4_fpage_t f) L4_NOTHROW
	Return size (log2) from a flexpage.

unsigned long	l4_fpage_page (l4_fpage_t f) L4_NOTHROW
	Return the page part from a flexpage.

l4_addr_t	l4_fpage_memaddr (l4_fpage_t f) L4_NOTHROW
	Return the memory address from the memory flexpage.

l4_cap_idx_t	l4_fpage_obj (l4_fpage_t f) L4_NOTHROW
	Return the capability index from the object flexpage.

unsigned long	l4_fpage_ioport (l4_fpage_t f) L4_NOTHROW
	Return the IO port number from the IO flexpage.

l4_fpage_t	l4_fpage_set_rights (l4_fpage_t src, unsigned char new_rights) L4_NOTHROW
	Set new right in a flexpage.

int	l4_fpage_contains (l4_fpage_t fpage, l4_addr_t addr, unsigned order) L4_NOTHROW
	Test whether a given range is completely within an fpage.

unsigned char	l4_fpage_max_order (unsigned char order, l4_addr_t addr, l4_addr_t min_addr, l4_addr_t max_addr, l4_addr_t hotspot=0)
	Determine maximum flexpage size of a region.

Detailed Description

Flexpage-related API.

A flexpage is a page with a variable size, that can describe memory, IO-Ports (IA32 only), and sets of kernel objects.

A flexpage describes an always size aligned region of an address space. The size is given in a log2 scale. This means the size in elements (bytes for memory, ports for IO-Ports, and capabilities for kernel objects) is always a power of two.

A flexpage also carries type and access right information for the described region. The type information selects the address space in which the flexpage is valid. Access rights have a meaning depending on the specific address space (type).

There exists a special type for defining receive windows or for the l4_task_unmap() method, that can be used to describe all address spaces (all types) with a single flexpage.

Include File: #include <l4/sys/types.h>

types.h
Common L4 ABI Data Types.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Constants for flexpages.

Enumerator

L4_WHOLE_ADDRESS_SPACE

Whole address space size.

This value does not only specify the log2 size of the biggest possible memory flexpage. It can be also used as size for a special flexpage to define a flexpage which completely covers all spaces.

Definition at line 84 of file __l4_fpage.h.

◆ anonymous enum

anonymous enum

Special constants for IO flexpages.

Enumerator

L4_WHOLE_IOADDRESS_SPACE

Whole I/O address space size.

In contrast to L4_WHOLE_ADDRESS_SPACE, this value forms the log2 size of the biggest possible I/O flexpage.

L4_IOPORT_MAX

Maximum I/O port address plus 1.

Definition at line 307 of file __l4_fpage.h.

◆ L4_cap_fpage_rights

enum L4_cap_fpage_rights

Object flexpage rights.

Capabilities are modified or transferred with map and unmap operations. For that, capabilities are wrapped into flexpage objects. The flexpage carries a set of rights the sender wants to hand over to the receiver along with the capability.

For the user only the 'S' and the 'W' right are visible. Other rights such as the 'D' right are internal to the corresponding kernel object and cannot be evaluated by the receiver.

Note that additional object attributes and permissions can be specified in a send item, see L4_obj_fpage_ctl.

Note: A thread can also map a capability from its task's capability table with a reduced set of rights into another slot of its own capability table.

Enumerator
L4_CAP_FPAGE_W	Interface specific 'W' right for capability flexpages. The semantics of the 'W' right is defined by the protocol. For example in case of a dataspace cap, the 'W' right is needed to get a writable dataspace.
L4_CAP_FPAGE_S	Interface specific 'S' right for capability flexpages. The semantics of the 'S' right is defined by the interface. When transferring object capabilities via IPC, the kernel masks this right with the 'S' right of the capability used to address the IPC partner. Thus, the 'S' right of sent capabilities is only transferred if both the flexpage and the IPC gate or thread capability specifying the IPC partner have the 'S' right. For L4::Task::map(), the 'S' right is only transferred if the flexpage, the source and destination task capabilities have the 'S' right.
L4_CAP_FPAGE_R	Read right for capability flexpages. This is always required, otherwise no capability is mapped.
L4_CAP_FPAGE_RO	Read right for capability flexpages. This is always required, otherwise no capability is mapped.
L4_CAP_FPAGE_D	Delete right for capability flexpages. This allows the receiver to delete the corresponding kernel object using unmap() regardless of other tasks still holding a capability to the kernel object. Such capabilities are set to an empty capability if the object is deleted.
L4_CAP_FPAGE_RW	Read and interface specific 'W' right for capability flexpages. The semantics of the 'W' right is defined by the interface. See also L4_CAP_FPAGE_W
L4_CAP_FPAGE_RS	Read and interface specific 'S' right for capability flexpages. The semantics of the 'S' right is defined by the interface. See also L4_CAP_FPAGE_S
L4_CAP_FPAGE_RWS	Read, interface specific 'W', and 'S' rights for capability flexpages. The semantics of the 'W' and 'S' right are defined by the interface. See also L4_CAP_FPAGE_R, L4_CAP_FPAGE_W, and L4_CAP_FPAGE_S
L4_CAP_FPAGE_RWSD	Full rights for capability flexpages. See also L4_CAP_FPAGE_R, L4_CAP_FPAGE_W, L4_CAP_FPAGE_S, and L4_CAP_FPAGE_D
L4_CAP_FPAGE_RWD	Read, write, and delete right for capability flexpages. See also L4_CAP_FPAGE_R, L4_CAP_FPAGE_W, and L4_CAP_FPAGE_D
L4_CAP_FPAGE_RSD	Read, 'S', and delete right for capability flexpages. See also L4_CAP_FPAGE_R, L4_CAP_FPAGE_S, and L4_CAP_FPAGE_D

Definition at line 148 of file __l4_fpage.h.

◆ L4_fpage_consts

enum L4_fpage_consts

L4 flexpage structure.

Enumerator
L4_FPAGE_RIGHTS_SHIFT	Access permissions shift.
L4_FPAGE_TYPE_SHIFT	Flexpage type shift (memory, IO port, obj...)
L4_FPAGE_SIZE_SHIFT	Flexpage size shift (log2-based)
L4_FPAGE_ADDR_SHIFT	Page address shift.
L4_FPAGE_RIGHTS_BITS	Access permissions size.
L4_FPAGE_TYPE_BITS	Flexpage type size (memory, IO port, obj...)
L4_FPAGE_SIZE_BITS	Flexpage size size (log2-based)
L4_FPAGE_ADDR_BITS	Page address size.
L4_FPAGE_RIGHTS_MASK	Mask to get the flexpage rights.
L4_FPAGE_RIGHTS_ALL	Specify as flexpage rights during grant.

Definition at line 48 of file __l4_fpage.h.

◆ L4_fpage_control

enum L4_fpage_control

Flexpage map control flags.

Enumerator
L4_FPAGE_CONTROL_OFFSET_SHIFT	Number of bits an index must be shifted or an address must be aligned to in the control word.
L4_FPAGE_CONTROL_MASK	Mask for truncating the lower bits of the send base or the index of the control word.

Definition at line 243 of file __l4_fpage.h.

◆ L4_fpage_rights

enum L4_fpage_rights

Memory and IO port flexpage rights.

For IO flexpages, bit 1 and bit 2 are a combined read/write right. In a map operation, the receiver receives the IO port capability when the sender possesses it and at least one of these bits is present. For an unmap operation, the absence of one of those bits is sufficient to unmap the IO port capability.

Note that more memory attributes can be specified in a send item, see l4_fpage_cacheability_opt_t.

Enumerator
L4_FPAGE_X	Executable flexpage.
L4_FPAGE_W	Writable flexpage.
L4_FPAGE_RO	Read-only flexpage
L4_FPAGE_RW	Read-write flexpage.
L4_FPAGE_RX	Read-execute flexpage.
L4_FPAGE_RWX	Read-write-execute flexpage.

Definition at line 118 of file __l4_fpage.h.

◆ L4_fpage_type

enum L4_fpage_type

Flexpage type.

Enumerator
L4_FPAGE_SPECIAL	Special flexpage, either l4_fpage_invalid() or l4_fpage_all(); only supported by selected interfaces.
L4_FPAGE_MEMORY	Flexpage for memory spaces.
L4_FPAGE_IO	Flexpage for I/O port spaces.
L4_FPAGE_OBJ	Flexpage for object spaces.

Definition at line 230 of file __l4_fpage.h.

Function Documentation

◆ l4_fpage()

l4_fpage_t l4_fpage	(	l4_addr_t	address,
		unsigned int	order,
		unsigned char	rights
	)

inline

Create a memory flexpage.

Parameters

address	Flexpage start address
order	Flexpage size (log2), L4_WHOLE_ADDRESS_SPACE to specify the whole address space (with `address` 0). The minimum log2 size of a memory flexpage is defined by L4_LOG2_PAGESIZE according to the size of the smallest virtual page supported by the MMU.
rights	Access rights, see L4_fpage_rights

Returns: Memory flexpage

Definition at line 684 of file __l4_fpage.h.

References L4_FPAGE_MEMORY.

Referenced by L4Re::Util::Dataspace_svr::map(), L4::Ipc::Rcv_fpage::mem(), and L4::Ipc::Snd_fpage::mem().

Here is the caller graph for this function:

◆ l4_fpage_all()

l4_fpage_t l4_fpage_all ( void )

inline

Get a flexpage, describing all address spaces at once.

Returns: Special all-spaces flexpage.

Note: This flexpage can be used to define a receive window where the sender can send objects of any type, or for an unmap item completely covering all spaces of the target task. It does not make sense to use this flexpage as send item.

Definition at line 704 of file __l4_fpage.h.

References L4_FPAGE_SPECIAL, and L4_WHOLE_ADDRESS_SPACE.

◆ l4_fpage_contains()

int l4_fpage_contains	(	l4_fpage_t	fpage,
		l4_addr_t	addr,
		unsigned	order
	)

inline

Test whether a given range is completely within an fpage.

Parameters

fpage	Flexpage
addr	Address
order	Size of range in log2.

Return values

==0	The range is not completely in the fpage.
!=0	The range is within the fpage.

Definition at line 736 of file __l4_fpage.h.

References l4_fpage_memaddr(), and l4_fpage_size().

Here is the call graph for this function:

◆ l4_fpage_invalid()

l4_fpage_t l4_fpage_invalid ( void )

inline

Get an invalid flexpage.

Returns: Special invalid flexpage.

Definition at line 710 of file __l4_fpage.h.

References L4_FPAGE_SPECIAL.

◆ l4_fpage_ioport()

unsigned long l4_fpage_ioport ( l4_fpage_t f )

inline

Return the IO port number from the IO flexpage.

Parameters

f Flexpage

Returns: IO port number from the given IO flexpage.

Precondition: f must be an IO flexpage (l4_fpage_type(f) == L4_FPAGE_IO) and

The function does not enforce size alignment of the read memory address. The caller must ensure the input fpage is correct.

Definition at line 640 of file __l4_fpage.h.

References L4_FPAGE_ADDR_SHIFT.

◆ l4_fpage_max_order()

unsigned char l4_fpage_max_order	(	unsigned char	order,
		l4_addr_t	addr,
		l4_addr_t	min_addr,
		l4_addr_t	max_addr,
		l4_addr_t	hotspot = `0`
	)

inline

Determine maximum flexpage size of a region.

Parameters

order	Order value to start with (e.g. for memory L4_LOG2_PAGESIZE would be used)
addr	Address to be covered by the flexpage.
min_addr	Start of region / minimal address (including).
max_addr	End of region / maximal address (excluding).
hotspot	(Optional) hot spot.

Returns: Maximum order (log2-size) possible.

Note: The start address of the flexpage can be determined with l4_trunc_size(addr, returnvalue)

Definition at line 744 of file __l4_fpage.h.

References l4_trunc_size().

Here is the call graph for this function:

◆ l4_fpage_memaddr()

l4_addr_t l4_fpage_memaddr ( l4_fpage_t f )

inline

Return the memory address from the memory flexpage.

Parameters

f Flexpage

Returns: Page address from the given memory flexpage.

Precondition: f must be a memory flexpage (l4_fpage_type(f) == L4_FPAGE_MEMORY).

The function does not enforce size alignment of the read memory address. The caller must ensure the input fpage is correct.

Definition at line 646 of file __l4_fpage.h.

Referenced by l4_fpage_contains().

Here is the caller graph for this function:

◆ l4_fpage_obj()

l4_cap_idx_t l4_fpage_obj ( l4_fpage_t f )

inline

Return the capability index from the object flexpage.

Parameters

f Flexpage

Returns: Capability index from the given object flexpage.

Precondition: f must be an object flexpage (l4_fpage_type(f) == L4_FPAGE_OBJ)

The function does not enforce size alignment of the read memory address. The caller must ensure the input fpage is correct.

Definition at line 652 of file __l4_fpage.h.

◆ l4_fpage_page()

unsigned long l4_fpage_page ( l4_fpage_t f )

inline

Return the page part from a flexpage.

Parameters

f Flexpage

Returns: Page part of the given flexpage.

Note: The meaning of the page part depends on the flexpage type.

Definition at line 634 of file __l4_fpage.h.

References L4_FPAGE_ADDR_SHIFT.

◆ l4_fpage_rights()

unsigned l4_fpage_rights ( l4_fpage_t f )

inline

Return rights from a flexpage.

Parameters

f Flexpage

Returns: Size part of the given flexpage.

Definition at line 616 of file __l4_fpage.h.

References L4_FPAGE_RIGHTS_MASK, and L4_FPAGE_RIGHTS_SHIFT.

Referenced by l4_is_fpage_writable().

Here is the caller graph for this function:

◆ l4_fpage_set_rights()

l4_fpage_t l4_fpage_set_rights	(	l4_fpage_t	src,
		unsigned char	new_rights
	)

inline

Set new right in a flexpage.

Parameters

src	Flexpage
new_rights	New rights

Returns: Modified flexpage with new rights.

Definition at line 675 of file __l4_fpage.h.

References L4_FPAGE_RIGHTS_MASK, L4_FPAGE_RIGHTS_SHIFT, and l4_fpage_t::raw.

Referenced by L4::Ipc::Snd_fpage::io().

Here is the caller graph for this function:

◆ l4_fpage_size()

unsigned l4_fpage_size ( l4_fpage_t f )

inline

Return size (log2) from a flexpage.

Parameters

f Flexpage

Returns: Size part of the given flexpage.

See also: l4_fpage_memaddr(), l4_fpage_obj(), l4_fpage_ioport()

Definition at line 628 of file __l4_fpage.h.

References L4_FPAGE_SIZE_SHIFT.

Referenced by l4_fpage_contains().

Here is the caller graph for this function:

◆ l4_fpage_type()

unsigned l4_fpage_type ( l4_fpage_t f )

inline

Return type from a flexpage.

Parameters

f Flexpage

Returns: Type part of the given flexpage.

Definition at line 622 of file __l4_fpage.h.

References L4_FPAGE_TYPE_SHIFT.

◆ l4_iofpage()

l4_fpage_t l4_iofpage	(	unsigned long	port,
		unsigned int	order
	)

inline

Create an IO-port flexpage.

Parameters

port	I/O-flexpage port base
order	I/O-flexpage size (log2), L4_WHOLE_IOADDRESS_SPACE to specify the whole I/O address space (with `port` 0)

Returns: I/O flexpage

Definition at line 690 of file __l4_fpage.h.

References L4_FPAGE_ADDR_SHIFT, L4_FPAGE_IO, and L4_FPAGE_RW.

Referenced by L4::Ipc::Rcv_fpage::io(), L4::Ipc::Snd_fpage::io(), and l4util_ioport_map().

Here is the caller graph for this function:

◆ l4_is_fpage_writable()

int l4_is_fpage_writable ( l4_fpage_t fp )

inline

Test if the flexpage is writable.

Parameters

fp Flexpage.

Return values

!=0	if flexpage is writable.
==0	if flexpage is not writable.

Definition at line 717 of file __l4_fpage.h.

References l4_fpage_rights(), and L4_FPAGE_W.

Here is the call graph for this function:

◆ l4_obj_fpage()

l4_fpage_t l4_obj_fpage	(	l4_cap_idx_t	obj,
		unsigned int	order,
		unsigned char	rights
	)

inline

Create a kernel-object flexpage.

Parameters

obj	Base capability selector.
order	Log2 size (number of capabilities).
rights	Access rights, see L4_cap_fpage_rights

Returns: Flexpage for a set of kernel objects.

Note: L4_CAP_FPAGE_R is always required, otherwise no capability is mapped.

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

Definition at line 696 of file __l4_fpage.h.

References L4_CAP_SHIFT, L4_FPAGE_ADDR_SHIFT, and L4_FPAGE_OBJ.

Referenced by L4::Cap_base::fpage(), l4_icu_bind_u(), l4_icu_unbind_u(), l4_irq_bind_vcpu_u(), L4::Ipc::Rcv_fpage::obj(), and L4::Ipc::Snd_fpage::obj().

Here is the caller graph for this function:

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ L4_cap_fpage_rights

◆ L4_fpage_consts

◆ L4_fpage_control

◆ L4_fpage_rights

◆ L4_fpage_type

Function Documentation

◆ l4_fpage()

◆ l4_fpage_all()

◆ l4_fpage_contains()

◆ l4_fpage_invalid()

◆ l4_fpage_ioport()

◆ l4_fpage_max_order()

◆ l4_fpage_memaddr()

◆ l4_fpage_obj()

◆ l4_fpage_page()

◆ l4_fpage_rights()

◆ l4_fpage_set_rights()

◆ l4_fpage_size()

◆ l4_fpage_type()

◆ l4_iofpage()

◆ l4_is_fpage_writable()

◆ l4_obj_fpage()