L4Re Operating System Framework – Interface and Usage Documentation
Loading...
Searching...
No Matches
Flex pages

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

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

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

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

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

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

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

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
addressFlex-page start address
sizeFlex-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.
rightsAccess rights, see L4_fpage_rights
Returns
Memory flex page

Definition at line 668 of file __l4_fpage.h.

References L4_FPAGE_MEMORY.

◆ 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
fpageFlex page
addrAddress
sizeSize of range in log2.
Return values
==0The range is not completely in the fpage.
!=0The 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
fFlex 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
orderOrder value to start with (e.g. for memory L4_LOG2_PAGESIZE would be used)
addrAddress to be covered by the flex page.
min_addrStart of region / minimal address (including).
max_addrEnd 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
fFlex 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
fFlex 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
fFlex 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
fFlex 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
srcFlex page
new_rightsNew 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
fFlex 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
fFlex 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
portI/O-flex-page port base
sizeI/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
fpFlex page.
Return values
!=0if flex page is writable.
==0if 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
objBase capability selector.
orderLog2 size (number of capabilities).
rightsAccess 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: