Flex-page related API. More...

Collaboration diagram for Flex pages:

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

struct	l4_snd_fpage_t
	Send-flex-page types. 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 flex-page 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 }
	Cap-flex-page rights. More...

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

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

enum	L4_obj_fpage_ctl { L4_FPAGE_C_REF_CNT = 0x00 , L4_FPAGE_C_NO_REF_CNT = 0x10 , L4_FPAGE_C_OBJ_RIGHT1 = 0x20 , L4_FPAGE_C_OBJ_RIGHT2 = 0x40 , L4_FPAGE_C_OBJ_RIGHT3 = 0x80 , L4_FPAGE_C_OBJ_RIGHTS = 0xe0 , L4_FPAGE_C_IPCGATE_SVR = L4_FPAGE_C_OBJ_RIGHT1 }
	Flex-page map control for capabilities (snd_base) More...

enum	l4_fpage_cacheability_opt_t { L4_FPAGE_CACHE_OPT = 0x1 , L4_FPAGE_CACHEABLE = 0x3 , L4_FPAGE_BUFFERABLE = 0x5 , L4_FPAGE_UNCACHEABLE = 0x1 }
	Flex-page cacheability option. More...

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

Functions
l4_fpage_t	l4_fpage (l4_addr_t address, unsigned int size, unsigned char rights) L4_NOTHROW
	Create a memory flex page.

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

l4_fpage_t	l4_fpage_invalid (void) L4_NOTHROW
	Get an invalid flex page.

l4_fpage_t	l4_iofpage (unsigned long port, unsigned int size) L4_NOTHROW
	Create an IO-port flex page.

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

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

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

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

unsigned	l4_fpage_size (l4_fpage_t f) L4_NOTHROW
	Return size from a flex page.

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

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

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

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

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

int	l4_fpage_contains (l4_fpage_t fpage, l4_addr_t addr, unsigned size) 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 flex page size of a region.

Detailed Description

Flex-page related API.

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

A flex page 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 flex page also carries type and access right information for the described region. The type information selects the address space in which the flex page 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 flex page.

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 flex page. It can be also used as size for a special flex page to define a flex page which completely covers all spaces.

Definition at line 93 of file __l4_fpage.h.

◆ anonymous enum

anonymous enum

Special constants for IO flex pages.

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 flex page.

L4_IOPORT_MAX

Maximum I/O port address plus 1.

Definition at line 304 of file __l4_fpage.h.

◆ L4_cap_fpage_rights

enum L4_cap_fpage_rights

Cap-flex-page rights.

Capabilities are modified or transfered with map and unmap operations. For that capabilities are wrapped into flex-page objects. The flex-page 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: 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 flex-pages. 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 flex-pages. 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 flex-page 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 flex-page, the source and destination task capabilities have the 'S' right.
L4_CAP_FPAGE_R	Read right for capability flex-pages. This is always required, otherwise no capability is mapped.
L4_CAP_FPAGE_RO	Read right for capability flex-pages. This is always required, otherwise no capability is mapped.
L4_CAP_FPAGE_D	Delete right for capability flex-pages. 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 flex-pages. 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 flex-pages. 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 flex-pages. 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 flex-pages. 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 flex-pages. 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 flex-pages. See also L4_CAP_FPAGE_R, L4_CAP_FPAGE_S, and L4_CAP_FPAGE_D

Definition at line 151 of file __l4_fpage.h.

◆ l4_fpage_cacheability_opt_t

enum l4_fpage_cacheability_opt_t

Flex-page cacheability option.

Enumerator
L4_FPAGE_CACHE_OPT	Enable the cacheability option in a send flex page.
L4_FPAGE_CACHEABLE	Cacheability option to enable caches for the mapping.
L4_FPAGE_BUFFERABLE	Cacheability option to enable buffered writes for the mapping.
L4_FPAGE_UNCACHEABLE	Cacheability option to disable caching for the mapping.

Definition at line 285 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 57 of file __l4_fpage.h.

◆ L4_fpage_control

enum L4_fpage_control

Flex-page 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 244 of file __l4_fpage.h.

◆ L4_fpage_rights

enum L4_fpage_rights

Memory and IO port flex-page 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.

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

Definition at line 124 of file __l4_fpage.h.

◆ L4_fpage_type

enum L4_fpage_type

Flex-page type.

Enumerator
L4_FPAGE_SPECIAL	Special flex page, either invalid or all spaces.
L4_FPAGE_MEMORY	Memory flex page.
L4_FPAGE_IO	IO-port flex page.
L4_FPAGE_OBJ	Object flex page (capabilities).

Definition at line 233 of file __l4_fpage.h.

◆ L4_obj_fpage_ctl

enum L4_obj_fpage_ctl

Flex-page map control for capabilities (snd_base)

These rights need to be added to the snd_base when mapping and control internal behavior. The exact meaning depends on the type of capability (currently used only with IPC gates).

Enumerator
L4_FPAGE_C_REF_CNT	Mapping is reference-counted (default).
L4_FPAGE_C_NO_REF_CNT	Don't increase the reference counter.
L4_FPAGE_C_OBJ_RIGHT1	Object-type specific right.
L4_FPAGE_C_OBJ_RIGHT2	Object-type specific right.
L4_FPAGE_C_OBJ_RIGHT3	Object-type specific right.
L4_FPAGE_C_OBJ_RIGHTS	All Object-type specific right bits.
L4_FPAGE_C_IPCGATE_SVR	The receiver may invoke IPC-gate-specific functions on the capability, e.g. bind a thread to the gate and modify the label. Needed if the receiver implements the server side of an IPC gate.

Definition at line 263 of file __l4_fpage.h.

Function Documentation

◆ l4_fpage()

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

inline

Create a memory flex page.

Parameters

address	Flex-page start address
size	Flex-page size (log2), L4_WHOLE_ADDRESS_SPACE to specify the whole address space (with `address` 0). The minimum log2 size of a memory flex page 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 flex page

Definition at line 668 of file __l4_fpage.h.

References L4_FPAGE_MEMORY.

Referenced by L4Re::Util::Dataspace_svr::map().

Here is the caller graph for this function:

◆ l4_fpage_all()

l4_fpage_t l4_fpage_all ( void )

inline

Get a flex page, describing all address spaces at once.

Returns: Special all-spaces flex page.

Note: This flex page 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 flex page as send item.

Definition at line 688 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	size
	)

inline

Test whether a given range is completely within an fpage.

Parameters

fpage	Flex page
addr	Address
size	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 720 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 flex page.

Returns: Special invalid flex page.

Definition at line 694 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 flex page.

Parameters

f Flex page

Returns: IO port number from the given IO flex page.

Precondition: f must be an IO flex page (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 624 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 flex page 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 flex page.
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 flex-page can be determined with l4_trunc_size(addr, returnvalue)

Definition at line 728 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 flex page.

Parameters

f Flex page

Returns: Page address from the given memory flex page.

Precondition: f must be a memory flex page (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 630 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 flex page.

Parameters

f Flex page

Returns: Capability index from the given object flex page.

Precondition: f must be an object flex page (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 636 of file __l4_fpage.h.

◆ l4_fpage_page()

unsigned long l4_fpage_page ( l4_fpage_t f )

inline

Return the page part from a flex page.

Parameters

f Flex page

Returns: Page part of the given flex page.

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

Definition at line 618 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 flex page.

Parameters

f Flex page

Returns: Size part of the given flex page.

Definition at line 600 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 flex page.

Parameters

src	Flex page
new_rights	New rights

Returns: Modified flex page with new rights.

Definition at line 659 of file __l4_fpage.h.

References L4_FPAGE_RIGHTS_MASK, L4_FPAGE_RIGHTS_SHIFT, and l4_fpage_t::raw.

◆ l4_fpage_size()

unsigned l4_fpage_size ( l4_fpage_t f )

inline

Return size from a flex page.

Parameters

f Flex page

Returns: Size part of the given flex page.

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

Definition at line 612 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 flex page.

Parameters

f Flex page

Returns: Type part of the given flex page.

Definition at line 606 of file __l4_fpage.h.

References L4_FPAGE_TYPE_SHIFT.

◆ l4_iofpage()

l4_fpage_t l4_iofpage	(	unsigned long	port,
		unsigned int	size
	)

inline

Create an IO-port flex page.

Parameters

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

Returns: I/O flex page

Definition at line 674 of file __l4_fpage.h.

References L4_FPAGE_ADDR_SHIFT, L4_FPAGE_IO, and L4_FPAGE_RW.

Referenced by 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 flex page is writable.

Parameters

fp	Flex page.

Return values

!=0	if flex page is writable.
==0	if flex pags is not writable.

Definition at line 701 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 flex page.

Parameters

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

Returns: Flex page 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 680 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(), and l4_irq_mux_chain_u().

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_cacheability_opt_t

◆ L4_fpage_consts

◆ L4_fpage_control

◆ L4_fpage_rights

◆ L4_fpage_type

◆ L4_obj_fpage_ctl

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