L4Re Operating System Framework
Interface and Usage Documentation
Loading...
Searching...
No Matches
Region map interface

Region map C interface. More...

+ Collaboration diagram for Region map interface:

Enumerations

enum  l4re_rm_flags_values {
  L4RE_RM_F_R = L4RE_DS_F_R , L4RE_RM_F_W = L4RE_DS_F_W , L4RE_RM_F_X = L4RE_DS_F_X , L4RE_RM_F_RX = L4RE_DS_F_RX ,
  L4RE_RM_F_RW = L4RE_DS_F_RW , L4RE_RM_F_RWX = L4RE_DS_F_RWX , L4RE_RM_F_NO_ALIAS = 0x200 , L4RE_RM_F_PAGER = 0x400 ,
  L4RE_RM_F_RESERVED = 0x800 , L4RE_RM_CACHING_SHIFT = 4 , L4RE_RM_F_CACHING = L4RE_DS_F_CACHING_MASK , L4RE_RM_REGION_FLAGS = 0xffff ,
  L4RE_RM_F_CACHE_NORMAL = L4RE_DS_F_NORMAL , L4RE_RM_F_CACHE_BUFFERED = L4RE_DS_F_BUFFERABLE , L4RE_RM_F_CACHE_UNCACHED = L4RE_DS_F_UNCACHEABLE , L4RE_RM_F_SEARCH_ADDR = 0x020000 ,
  L4RE_RM_F_IN_AREA = 0x040000 , L4RE_RM_F_EAGER_MAP = 0x080000 , L4RE_RM_F_NO_EAGER_MAP = 0x100000 , L4RE_RM_F_ATTACH_FLAGS = 0x1f0000
}
 Flags for region operations. More...
 

Functions

int l4re_rm_reserve_area (l4_addr_t *start, unsigned long size, l4re_rm_flags_t flags, unsigned char align) L4_NOTHROW
 Reserve the given area in the region map.
 
int l4re_rm_free_area (l4_addr_t addr) L4_NOTHROW
 Free an area from the region map.
 
int l4re_rm_attach (void **start, unsigned long size, l4re_rm_flags_t flags, l4re_ds_t mem, l4re_rm_offset_t offs, unsigned char align) L4_NOTHROW
 Attach a data space to a region.
 
int l4re_rm_detach (void *addr) L4_NOTHROW
 Detach and unmap a region from the address space in the current task.
 
int l4re_rm_detach_ds (void *addr, l4re_ds_t *ds) L4_NOTHROW
 Detach and unmap a region and return affected dataspace in the current task.
 
int l4re_rm_detach_unmap (l4_addr_t addr, l4_cap_idx_t task) L4_NOTHROW
 Detach and unmap in specified task.
 
int l4re_rm_detach_ds_unmap (void *addr, l4re_ds_t *ds, l4_cap_idx_t task) L4_NOTHROW
 Detach and unmap in specified task.
 
int l4re_rm_find (l4_addr_t *addr, unsigned long *size, l4re_rm_offset_t *offset, l4re_rm_flags_t *flags, l4re_ds_t *m) L4_NOTHROW
 Find a region given an address and size.
 
void l4re_rm_show_lists (void) L4_NOTHROW
 Dump region map internal data structures.
 
int l4re_rm_reserve_area_srv (l4_cap_idx_t rm, l4_addr_t *start, unsigned long size, l4re_rm_flags_t flags, unsigned char align) L4_NOTHROW
 
int l4re_rm_free_area_srv (l4_cap_idx_t rm, l4_addr_t addr) L4_NOTHROW
 
int l4re_rm_attach_srv (l4_cap_idx_t rm, void **start, unsigned long size, l4re_rm_flags_t flags, l4re_ds_t mem, l4re_rm_offset_t offs, unsigned char align) L4_NOTHROW
 
int l4re_rm_detach_srv (l4_cap_idx_t rm, l4_addr_t addr, l4re_ds_t *ds, l4_cap_idx_t task) L4_NOTHROW
 
int l4re_rm_find_srv (l4_cap_idx_t rm, l4_addr_t *addr, unsigned long *size, l4re_rm_offset_t *offset, l4re_rm_flags_t *flags, l4re_ds_t *m) L4_NOTHROW
 
void l4re_rm_show_lists_srv (l4_cap_idx_t rm) L4_NOTHROW
 Dump region map internal data structures.
 

Detailed Description

Region map C interface.

Enumeration Type Documentation

◆ l4re_rm_flags_values

Flags for region operations.

Enumerator
L4RE_RM_F_R 

Region is read-only.

L4RE_RM_F_NO_ALIAS 

The region contains exclusive memory that is not mapped anywhere else.

L4RE_RM_F_PAGER 

Region has a pager.

L4RE_RM_F_RESERVED 

Region is reserved (blocked)

L4RE_RM_CACHING_SHIFT 

Start of region mapper cache bits.

L4RE_RM_F_CACHING 

Mask of all region manager cache bits.

L4RE_RM_REGION_FLAGS 

Mask of all region flags.

L4RE_RM_F_CACHE_NORMAL 

Cache bits for normal cacheable memory.

L4RE_RM_F_CACHE_BUFFERED 

Cache bits for buffered (write combining) memory.

L4RE_RM_F_CACHE_UNCACHED 

Cache bits for uncached memory.

L4RE_RM_F_SEARCH_ADDR 

Search for a suitable address range.

L4RE_RM_F_IN_AREA 

Search only in area, or map into area.

L4RE_RM_F_EAGER_MAP 

Eagerly map the attached data space in.

L4RE_RM_F_NO_EAGER_MAP 

Prevent eager mapping of the attached data space.

L4RE_RM_F_ATTACH_FLAGS 

Mask of all attach flags.

Definition at line 40 of file rm.h.

Function Documentation

◆ l4re_rm_attach()

int l4re_rm_attach ( void **  start,
unsigned long  size,
l4re_rm_flags_t  flags,
l4re_ds_t  mem,
l4re_rm_offset_t  offs,
unsigned char  align 
)
inline

Attach a data space to a region.

Parameters
[in,out]startVirtual start address where the region manager shall attach the data space. Will be rounded down to the nearest start of a page. If L4Re::Rm::F::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::F::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). Will be rounded up to the nearest multiple of the page size.
flagsThe flags control how and with which rights the dataspace is attached to the region. See L4Re::Rm::F::Attach_flags and L4Re::Rm::F::Region_flags. The caller must specify the desired rights of the attached region explicitly. The default set of rights is empty. If the F::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::F::Search_addr flag is used.
taskOptional destination task of mapping if F::Eager_map flag was passed. If invalid, the mapping is established in the current task. This parameter is only useful if the region manager is for a foreign task.
Return values
0Success
-L4_ENOENTNo area could be found (see L4Re::Rm::F::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).
See also
L4Re::Rm::attach

This function is using the L4::Env::env()->rm() service.

Examples
examples/libs/l4re/c/ma+rm.c.

Definition at line 287 of file rm.h.

References l4re_rm_attach_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_attach_srv()

int l4re_rm_attach_srv ( l4_cap_idx_t  rm,
void **  start,
unsigned long  size,
l4re_rm_flags_t  flags,
l4re_ds_t  mem,
l4re_rm_offset_t  offs,
unsigned char  align 
)
See also
L4Re::Rm::attach

Referenced by l4re_rm_attach().

+ Here is the caller graph for this function:

◆ l4re_rm_detach()

int l4re_rm_detach ( void *  addr)
inline

Detach and unmap a region from the address space in the current task.

Parameters
addrAddress of the region to detach.
Return values
L4Re::Rm::Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC errors

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

Also

See also
L4Re::Rm::detach

This function is using the L4::Env::env()->rm() service.

Definition at line 297 of file rm.h.

References L4_BASE_TASK_CAP, l4re_rm_detach_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_detach_ds()

int l4re_rm_detach_ds ( void *  addr,
l4re_ds_t ds 
)
inline

Detach and unmap a region and return affected dataspace in the current task.

Parameters
addrAddress of the region to detach.
[out]dsReturns dataspace that is affected.
Return values
L4Re::Rm::Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC errors

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

Also

See also
L4Re::Rm::detach

This function is using the L4::Env::env()->rm() service.

Examples
examples/libs/l4re/c/ma+rm.c.

Definition at line 310 of file rm.h.

References L4_BASE_TASK_CAP, l4re_rm_detach_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_detach_ds_unmap()

int l4re_rm_detach_ds_unmap ( void *  addr,
l4re_ds_t ds,
l4_cap_idx_t  task 
)
inline

Detach and unmap in specified task.

Parameters
addrAddress of the region to detach.
[out]dsReturns dataspace that is affected.
taskTask to unmap pages from, specify L4_INVALID_CAP to not unmap
Returns
0 on success, <0 on error

Also

See also
L4Re::Rm::detach

This function is using the L4::Env::env()->rm() service.

Definition at line 317 of file rm.h.

References l4re_rm_detach_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_detach_srv()

int l4re_rm_detach_srv ( l4_cap_idx_t  rm,
l4_addr_t  addr,
l4re_ds_t ds,
l4_cap_idx_t  task 
)
See also
L4Re::Rm::detach

Referenced by l4re_rm_detach(), l4re_rm_detach_ds(), l4re_rm_detach_ds_unmap(), and l4re_rm_detach_unmap().

+ Here is the caller graph for this function:

◆ l4re_rm_detach_unmap()

int l4re_rm_detach_unmap ( l4_addr_t  addr,
l4_cap_idx_t  task 
)
inline

Detach and unmap in specified task.

Parameters
addrAddress of the region to detach.
taskTask to unmap pages from, specify L4_INVALID_CAP to not unmap
Returns
0 on success, <0 on error

Also

See also
L4Re::Rm::detach

This function is using the L4::Env::env()->rm() service.

Definition at line 304 of file rm.h.

References l4re_rm_detach_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_find()

int l4re_rm_find ( l4_addr_t addr,
unsigned long *  size,
l4re_rm_offset_t *  offset,
l4re_rm_flags_t *  flags,
l4re_ds_t m 
)
inline

Find a region given an address and size.

Parameters
[in,out]addrAddress to look for. Returns the start address of the found region.
[in,out]sizeSize of the area to look for (in bytes). Returns the size of the found region (in bytes).
[out]offsetOffset at the beginning of the region within the associated dataspace.
[out]flagsRegion flags, see F::Region_flags (and F::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 F::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.
See also
L4Re::Rm::find

Definition at line 324 of file rm.h.

References l4re_rm_find_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_find_srv()

int l4re_rm_find_srv ( l4_cap_idx_t  rm,
l4_addr_t addr,
unsigned long *  size,
l4re_rm_offset_t *  offset,
l4re_rm_flags_t *  flags,
l4re_ds_t m 
)
See also
L4Re::Rm::find

Referenced by l4re_rm_find().

+ Here is the caller graph for this function:

◆ l4re_rm_free_area()

int l4re_rm_free_area ( l4_addr_t  addr)
inline

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.
L4Re::Rm::free_area

This function is using the L4::Env::env()->rm() service.

Definition at line 281 of file rm.h.

References l4re_rm_free_area_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_free_area_srv()

int l4re_rm_free_area_srv ( l4_cap_idx_t  rm,
l4_addr_t  addr 
)
See also
L4Re::Rm::free_area

Referenced by l4re_rm_free_area().

+ Here is the caller graph for this function:

◆ l4re_rm_reserve_area()

int l4re_rm_reserve_area ( l4_addr_t start,
unsigned long  size,
l4re_rm_flags_t  flags,
unsigned char  align 
)
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::F::Region_flags and L4Re::Rm::F::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 managed by the region map. There are two kinds of areas available:

  • Reserved areas (flags = L4Re::Rm::F::Reserved), where no data spaces can be attached
  • Special purpose areas (flags = 0), where data spaces can be attached to the area via the L4Re::Rm::F::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 = L4Re::Rm::F::Search_addr), the space between start and the end of the virtual address space is searched.
See also
L4Re::Rm::reserve_area

This function is using the L4::Env::env()->rm() service.

Definition at line 273 of file rm.h.

References l4re_rm_reserve_area_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function:

◆ l4re_rm_reserve_area_srv()

int l4re_rm_reserve_area_srv ( l4_cap_idx_t  rm,
l4_addr_t start,
unsigned long  size,
l4re_rm_flags_t  flags,
unsigned char  align 
)
See also
L4Re::Rm::reserve_area

Referenced by l4re_rm_reserve_area().

+ Here is the caller graph for this function:

◆ l4re_rm_show_lists()

void l4re_rm_show_lists ( void  )
inline

Dump region map internal data structures.

This function is using the L4::Env::env()->rm() service.

Definition at line 332 of file rm.h.

References l4re_rm_show_lists_srv(), and l4re_env_t::rm.

+ Here is the call graph for this function: