L4Re - L4 Runtime Environment
L4Re::Rm Class Reference

Region map. More...

#include <l4/re/rm>

+ Inheritance diagram for L4Re::Rm:
+ Collaboration diagram for L4Re::Rm:

Public Types

enum  Detach_result { Detached_ds = 0, Kept_ds = 1, Split_ds = 2 , Detach_again = 4 }
 Result values for detach operation. More...
 
enum  Region_flags {
  Read_only = 0x01, Detach_free = 0x02, Pager = 0x04, Reserved = 0x08,
  Caching_shift = 8, Caching_ds_shift = Caching_shift - Dataspace::Map_caching_shift, Caching = Dataspace::Map_caching_mask << Caching_ds_shift, Cache_normal = Dataspace::Map_normal << Caching_ds_shift,
  Cache_buffered = Dataspace::Map_bufferable << Caching_ds_shift, Cache_uncached = Dataspace::Map_uncacheable << Caching_ds_shift, Region_flags = Caching | 0x0f
}
 Flags for regions. More...
 
enum  Attach_flags { Search_addr = 0x20, In_area = 0x40, Eager_map = 0x80, Attach_flags = 0xf0 }
 Flags for attach operation. More...
 
enum  Detach_flags { Detach_exact = 1, Detach_overlap = 2, Detach_keep = 4 }
 Flags for detach operation. More...
 

Public Member Functions

long reserve_area (l4_addr_t *start, unsigned long size, unsigned flags=0, unsigned char align=L4_PAGESHIFT) const throw ()
 Reserve the given area in the region map. More...
 
template<typename T >
long reserve_area (T **start, unsigned long size, unsigned flags=0, unsigned char align=L4_PAGESHIFT) const throw ()
 Reserve the given area in the region map. More...
 
long free_area (l4_addr_t addr)
 Free an area from the region map. More...
 
long attach (l4_addr_t *start, unsigned long size, unsigned long flags, L4::Ipc::Cap< Dataspace > mem, l4_addr_t offs=0, unsigned char align=L4_PAGESHIFT) const throw ()
 Attach a data space to a region. More...
 
template<typename T >
long attach (T **start, unsigned long size, unsigned long flags, L4::Ipc::Cap< Dataspace > mem, l4_addr_t offs=0, unsigned char align=L4_PAGESHIFT) const throw ()
 Attach a data space to a region. More...
 
int detach (l4_addr_t addr, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task=This_task) const throw ()
 Detach a region from the address space. More...
 
int detach (void *addr, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task=This_task) const throw ()
 Detach a region from the address space. More...
 
int detach (l4_addr_t start, unsigned long size, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task) const throw ()
 Detach all regions of the specified interval. More...
 
int find (l4_addr_t *addr, unsigned long *size, l4_addr_t *offset, unsigned *flags, L4::Cap< Dataspace > *m) throw ()
 Find a region given an address and size. More...
 
- Public Member Functions inherited from L4::Pager
l4_msgtag_t page_fault (l4_umword_t pfa, l4_umword_t pc, L4::Ipc::Opt< l4_mword_t &> result, L4::Ipc::Rcv_fpage rwin, L4::Ipc::Opt< L4::Ipc::Snd_fpage &> fp)
 Page-fault protocol message. More...
 
- Public Member Functions inherited from L4::Io_pager
l4_msgtag_t io_page_fault (l4_fpage_t io_pfa, l4_umword_t pc, L4::Ipc::Opt< l4_mword_t &> result, L4::Ipc::Rcv_fpage rwin, L4::Ipc::Opt< L4::Ipc::Snd_fpage &> fp)
 IO page fault protocol message. More...
 

Additional Inherited Members

- Protected Types inherited from L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >
typedef Rm Class
 The target interface type (inheriting from Kobject_t)
 
typedef Typeid::Iface< PROTO, Rm > __Iface
 The interface description for the derived class.
 
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename L4::Pager ::__Iface_list > __Iface_list
 The list of all RPC interfaces provided directly or through inheritance.
 
- Protected Types inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT >
typedef Pager Class
 The target interface type (inheriting from Kobject_t)
 
typedef Typeid::Iface< PROTO, Pager__Iface
 The interface description for the derived class.
 
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Io_pager ::__Iface_list > __Iface_list
 The list of all RPC interfaces provided directly or through inheritance.
 
- Protected Member Functions inherited from L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >
L4::Cap< Classc () const
 Get the capability to ourselves.
 
- Protected Member Functions inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT >
L4::Cap< Classc () const
 Get the capability to ourselves.
 
- Static Protected Member Functions inherited from L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >
static void __check_protocols__ ()
 Helper to check for protocol conflicts.
 
- Static Protected Member Functions inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT >
static void __check_protocols__ ()
 Helper to check for protocol conflicts.
 

Detailed Description

Region map.

Definition at line 69 of file rm.

Member Enumeration Documentation

◆ Attach_flags

Flags for attach operation.

Enumerator
Search_addr 

Search for a suitable address range.

In_area 

Search only in area, or map into area.

Eager_map 

Eagerly map the attached data space in.

Attach_flags 

Mask of all attach flags.

Definition at line 111 of file rm.

◆ Detach_flags

Flags for detach operation.

Enumerator
Detach_exact 

Do an unmap of the exact region given.

Detach_overlap 

Do an unmap of all overlapping regions.

Detach_keep 

Do not free the detached data space, ignore the Detach_free.

Definition at line 121 of file rm.

◆ Detach_result

Result values for detach operation.

Enumerator
Detached_ds 

Detached data sapce.

Kept_ds 

Kept data space.

Split_ds 

Splitted data space, and done.

Detach_again 

Detached data space, more to do.

Definition at line 75 of file rm.

◆ Region_flags

Flags for regions.

Enumerator
Read_only 

Region is read-only.

Detach_free 

Free the portion of the data space after detach.

Pager 

Region has a pager.

Reserved 

Region is reserved (blocked)

Caching_shift 

Start of Rm cache bits.

Caching_ds_shift 

Shift value for Dataspace to Rm cache bits.

Caching 

Mask of all Rm cache bits.

Cache_normal 

Cache bits for normal cacheable memory.

Cache_buffered 

Cache bits for buffered (write combining) memory.

Cache_uncached 

Cache bits for uncached memory.

Region_flags 

Mask of all region flags.

Definition at line 86 of file rm.

Member Function Documentation

◆ attach() [1/2]

long L4Re::Rm::attach ( l4_addr_t start,
unsigned long  size,
unsigned long  flags,
L4::Ipc::Cap< Dataspace mem,
l4_addr_t  offs = 0,
unsigned char  align = L4_PAGESHIFT 
) const
throw (
)

Attach a data space to a region.

Parameters
[in,out]startVirtual start address where the region manager shall attach the data space. If L4Re::Rm::Search_addr is given this value is used as the start address to search for a free virtual memory region and the resulting address is returned here. If L4Re::Rm::In_area is given the value is used as a selector for the area (see L4Re::Rm::reserve_area) to attach the data space to.
sizeSize of the data space to attach (in bytes)
flagsFlags, see L4Re::Rm::Attach_flags and L4Re::Rm::Region_flags. If the Eager_map flag is set this function may also return L4Re::Dataspace::map error codes if the mapping fails.
memData space
offsOffset into the data space to use
alignAlignment of the virtual region, log2-size, default: a page (L4_PAGESHIFT). This is only meaningful if the L4Re::Rm::Search_addr flag is used.
Return values
0Success
-L4_ENOENTNo area could be found (see L4Re::Rm::In_area)
-L4_EPERMOperation not allowed.
-L4_EINVAL
-L4_EADDRNOTAVAILThe given address is not available.
<0IPC errors

Makes the whole or parts of a data space visible in the virtual memory of the corresponding task. The corresponding region in the virtual address space is backed with the contents of the dataspace.

Note
When searching for a free place in the virtual address space, the space between start and the end of the virtual address space is searched.
There is no region object created, instead the region is defined by a virtual address within this range (see L4Re::Rm::find).

Definition at line 43 of file rm_impl.h.

References L4::Ipc::Cap< T >::cap(), detach(), L4::Cap_base::is_valid(), L4_FP_ALL_SPACES, l4_fpage(), L4_FPAGE_RWX, L4_INVALID_CAP, L4_LOG2_PAGESIZE, l4_round_page(), L4_UNLIKELY, L4Re::Dataspace::map_region(), L4Re::Dataspace::Map_ro, L4Re::Dataspace::Map_rw, and L4::Task::unmap().

+ Here is the call graph for this function:

◆ attach() [2/2]

template<typename T >
long L4Re::Rm::attach ( T **  start,
unsigned long  size,
unsigned long  flags,
L4::Ipc::Cap< Dataspace mem,
l4_addr_t  offs = 0,
unsigned char  align = L4_PAGESHIFT 
) const
throw (
)
inline

Attach a data space to a region.

Parameters
[in,out]startVirtual start address where the region manager shall attach the data space. If L4Re::Rm::Search_addr is given this value is used as the start address to search for a free virtual memory region and the resulting address is returned here. If L4Re::Rm::In_area is given the value is used as a selector for the area (see L4Re::Rm::reserve_area) to attach the data space to.
sizeSize of the data space to attach (in bytes)
flagsFlags, see L4Re::Rm::Attach_flags and L4Re::Rm::Region_flags. If the Eager_map flag is set this function may also return L4Re::Dataspace::map error codes if the mapping fails.
memData space
offsOffset into the data space to use
alignAlignment of the virtual region, log2-size, default: a page (L4_PAGESHIFT). This is only meaningful if the L4Re::Rm::Search_addr flag is used.
Return values
0Success
-L4_ENOENTNo area could be found (see L4Re::Rm::In_area)
-L4_EPERMOperation not allowed.
-L4_EINVAL
-L4_EADDRNOTAVAILThe given address is not available.
<0IPC errors

Makes the whole or parts of a data space visible in the virtual memory of the corresponding task. The corresponding region in the virtual address space is backed with the contents of the dataspace.

Note
When searching for a free place in the virtual address space, the space between start and the end of the virtual address space is searched.
There is no region object created, instead the region is defined by a virtual address within this range (see L4Re::Rm::find).

Definition at line 345 of file rm.

◆ detach() [1/3]

int L4Re::Rm::detach ( l4_addr_t  addr,
L4::Cap< Dataspace > *  mem,
L4::Cap< L4::Task > const &  task = This_task 
) const
throw (
)
inline

Detach a region from the address space.

Parameters
addrVirtual address of region, any address within the region is valid.
[out]memDataspace that is affected. Give 0 if not interested.
taskThis argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task.
Return values
Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC errors

Frees a region in the virtual address space given by addr (address type). The corresponding part of the address space is now available again.

Definition at line 589 of file rm.

Referenced by attach().

+ Here is the caller graph for this function:

◆ detach() [2/3]

int L4Re::Rm::detach ( void *  addr,
L4::Cap< Dataspace > *  mem,
L4::Cap< L4::Task > const &  task = This_task 
) const
throw (
)
inline

Detach a region from the address space.

Parameters
addrVirtual address of region, any address within the region is valid.
[out]memDataspace that is affected. Give 0 if not interested.
taskThis argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task.
Return values
Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC errors

Frees a region in the virtual address space given by addr (address type). The corresponding part of the address space is now available again.

Definition at line 594 of file rm.

◆ detach() [3/3]

int L4Re::Rm::detach ( l4_addr_t  start,
unsigned long  size,
L4::Cap< Dataspace > *  mem,
L4::Cap< L4::Task > const &  task 
) const
throw (
)
inline

Detach all regions of the specified interval.

Parameters
startStart of area to detach, must be within region.
sizeSize of of area to detach (in bytes).
[out]memDataspace that is affected. Give 0 if not interested.
taskThis argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task.
Return values
Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC errors

Frees all regions within the interval given by start and size. If a region overlaps the start or the end of the interval this region is only detached partly. If the interval is within one region the original region is split up into two separate regions.

Definition at line 599 of file rm.

◆ find()

int L4Re::Rm::find ( l4_addr_t addr,
unsigned long *  size,
l4_addr_t offset,
unsigned *  flags,
L4::Cap< Dataspace > *  m 
)
throw (
)
inline

Find a region given an address and size.

Parameters
addrAddress to look for
sizeSize of the area to look for (in bytes).
[out]addrStart address of the found region.
[out]sizeSize of the found region (in bytes).
[out]offsetOffset at the beginning of the region within the associated dataspace.
[out]flagsRegion flags, see Region_flags (and In_area).
[out]mAssociated dataspace or paging service.
Return values
0Success
-L4_EPERMOperation not allowed.
-L4_ENOENTNo region found.
<0IPC errors

This function returns the properties of the region that contains the area described by the addr and size parameter. If no such region is found but a reserved area, the area is returned and In_area is set in `flags`. Note, in the case of an area the `offset` and `m` return values are invalid.

                size-out
              /           \
             /             \
         addr-out           \
            ^________________\
------------|----------------|------------------
|           | Region         |       Dataspace |
|           |_______|___|____|                 |
------------|-------|---|-----------------------
 \         /        |\ /
  \       /         | |> size-in
  offset-out        |
                    |> addr-in
Note
The value of the size input parameter should be 1 to assure that a region can be determined unambiguously.

Definition at line 553 of file rm.

◆ free_area()

long L4Re::Rm::free_area ( l4_addr_t  addr)

Free an area from the region map.

Parameters
addrAn address within the area to free.
Return values
0Success
-L4_ENOENTNo area found.
<0IPC errors
Note
The data spaces that are attached to that area are not detached by this operation.
See also
reserve_area() for more information about areas.

◆ reserve_area() [1/2]

long L4Re::Rm::reserve_area ( l4_addr_t start,
unsigned long  size,
unsigned  flags = 0,
unsigned char  align = L4_PAGESHIFT 
) const
throw (
)
inline

Reserve the given area in the region map.

Parameters
[in,out]startThe virtual start address of the area to reserve. Returns the start address of the area.
sizeThe size of the area to reserve (in bytes).
flagsFlags for the reserved area (see L4Re::Rm::Region_flags and L4Re::Rm::Attach_flags).
alignAlignment of area if searched as bits (log2 value).
Return values
0Success
-L4_EADDRNOTAVAILThe given area cannot be reserved.
<0IPC errors

This function reserves an area within the virtual address space implemented by the region map. There are two kinds of areas available:

  • Reserved areas (flags = Reserved), where no data spaces can be attached
  • Special purpose areas (flags = 0), where data spaces can be attached to the area via the In_area flag and a start address within the area itself.
Note
When searching for a free place in the virtual address space (with flags = Search_addr), the space between start and the end of the virtual address space is searched.

Definition at line 239 of file rm.

◆ reserve_area() [2/2]

template<typename T >
long L4Re::Rm::reserve_area ( T **  start,
unsigned long  size,
unsigned  flags = 0,
unsigned char  align = L4_PAGESHIFT 
) const
throw (
)
inline

Reserve the given area in the region map.

Parameters
[in,out]startThe virtual start address of the area to reserve. Returns the start address of the area.
sizeThe size of the area to reserve (in bytes).
flagsFlags for the reserved area (see Region_flags and Attach_flags).
alignAlignment of area if searched as bits (log2 value).
Return values
0Success
-L4_EADDRNOTAVAILThe given area cannot be reserved.
<0IPC errors

For more information, please refer to the analogous function

See also
L4Re::Rm::reserve_area.

Definition at line 265 of file rm.


The documentation for this class was generated from the following files: