Loading...
Searching...
No Matches
Flexpages
Base API

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.
int | l4_is_fpage_valid (l4_fpage_t fp) L4_NOTHROW
| Test if the flexpage is valid.

## 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 314 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 703 of file __l4_fpage.h.

References L4_FPAGE_MEMORY, and L4_NOTHROW.

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

References L4_FPAGE_SPECIAL, L4_NOTHROW, 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 755 of file __l4_fpage.h.

References l4_fpage_memaddr(), l4_fpage_size(), and L4_NOTHROW.

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

References L4_FPAGE_SPECIAL, and L4_NOTHROW.

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

References L4_FPAGE_ADDR_SHIFT, and L4_NOTHROW.

## 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 763 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 665 of file __l4_fpage.h.

References L4_NOTHROW.

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

References L4_NOTHROW.

## 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 653 of file __l4_fpage.h.

References L4_FPAGE_ADDR_SHIFT, and L4_NOTHROW.

## 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 635 of file __l4_fpage.h.

References L4_FPAGE_RIGHTS_MASK, L4_FPAGE_RIGHTS_SHIFT, and L4_NOTHROW.

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

References L4_FPAGE_RIGHTS_MASK, L4_FPAGE_RIGHTS_SHIFT, L4_NOTHROW, 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 647 of file __l4_fpage.h.

References L4_FPAGE_SIZE_SHIFT, and L4_NOTHROW.

Referenced by l4_fpage_contains(), and l4_is_fpage_valid().

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

References L4_FPAGE_TYPE_SHIFT, and L4_NOTHROW.

Referenced by l4_is_fpage_valid().

Here is the caller graph for this function:

## 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 709 of file __l4_fpage.h.

References L4_FPAGE_ADDR_SHIFT, L4_FPAGE_IO, L4_FPAGE_RW, and L4_NOTHROW.

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

int l4_is_fpage_valid | ( | l4_fpage_t | fp | ) |

inline

Test if the flexpage is valid.

Parameters

  fp | Flexpage.

Return values

  !=0 | if flexpage is valid.
  ==0 | if flexpage is not valid.

Definition at line 788 of file __l4_fpage.h.

References l4_fpage_size(), L4_FPAGE_SPECIAL, l4_fpage_type(), and L4_NOTHROW.

Here is the call 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 736 of file __l4_fpage.h.

References l4_fpage_rights(), L4_FPAGE_W, and L4_NOTHROW.

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

References L4_CAP_SHIFT, L4_FPAGE_ADDR_SHIFT, L4_FPAGE_OBJ, and L4_NOTHROW.

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: