L4Re - L4 Runtime Environment
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 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
}
 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
 Flex-page type.
 
enum  L4_fpage_control
 Flex-page map control flags.
 
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. More...
 
l4_fpage_t l4_fpage_all (void) L4_NOTHROW
 Get a flex page, describing all address spaces at once. More...
 
l4_fpage_t l4_fpage_invalid (void) L4_NOTHROW
 Get an invalid flex page. More...
 
l4_fpage_t l4_iofpage (unsigned long port, unsigned int size) L4_NOTHROW
 Create an IO-port flex page. More...
 
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. More...
 
int l4_is_fpage_writable (l4_fpage_t fp) L4_NOTHROW
 Test if the flex page is writable. More...
 
unsigned l4_fpage_rights (l4_fpage_t f) L4_NOTHROW
 Return rights from a flex page. More...
 
unsigned l4_fpage_type (l4_fpage_t f) L4_NOTHROW
 Return type from a flex page. More...
 
unsigned l4_fpage_size (l4_fpage_t f) L4_NOTHROW
 Return size from a flex page. More...
 
unsigned long l4_fpage_page (l4_fpage_t f) L4_NOTHROW
 Return the page part from a flex page. More...
 
l4_addr_t l4_fpage_memaddr (l4_fpage_t f) L4_NOTHROW
 Return the memory address from the memory flex page. More...
 
l4_cap_idx_t l4_fpage_obj (l4_fpage_t f) L4_NOTHROW
 Return the capability index from the object flex page. More...
 
unsigned long l4_fpage_ioport (l4_fpage_t f) L4_NOTHROW
 Return the IO port number from the IO flex page. More...
 
l4_fpage_t l4_fpage_set_rights (l4_fpage_t src, unsigned char new_rights) L4_NOTHROW
 Set new right in a flex page. More...
 
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. More...
 
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. More...
 

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.

Definition at line 89 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.

L4_IOPORT_MAX 

Maximum I/O port address.

Definition at line 281 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. The kernel masks this right with the 'S' right of the IPC gate over which the capability is mapped. That means that the receiver capability will only have the 'S' right set if both the flex-page and the IPC gate have the 'S' bit set.

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 134 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 262 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.

Definition at line 55 of file __l4_fpage.h.

◆ L4_fpage_rights

Flex-page rights.

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 107 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 240 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)
rightsAccess rights, see L4_fpage_rights
Returns
Memory flex page

Definition at line 633 of file __l4_fpage.h.

Referenced by L4Re::Rm::attach().

+ 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.

Definition at line 653 of file __l4_fpage.h.

References 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 685 of file __l4_fpage.h.

References l4_fpage_memaddr().

+ 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 659 of file __l4_fpage.h.

◆ 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 589 of file __l4_fpage.h.

◆ 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 693 of file __l4_fpage.h.

References l4_trunc_size().

Referenced by L4Re::Dataspace::map(), and L4Re::Dataspace::map_region().

+ Here is the call graph for this function:
+ Here is the caller 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 595 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 601 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 583 of file __l4_fpage.h.

◆ 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 565 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 624 of file __l4_fpage.h.

References 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 577 of file __l4_fpage.h.

◆ 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 571 of file __l4_fpage.h.

◆ 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 639 of file __l4_fpage.h.

References L4_FPAGE_ADDR_SHIFT.

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 666 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.

Definition at line 645 of file __l4_fpage.h.

Referenced by L4::Cap_base::fpage().

+ Here is the caller graph for this function: