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

enum 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]	start	Virtual 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.
	size	Size of the data space to attach (in bytes). Will be rounded up to the nearest multiple of the page size.
	flags	The 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.
	mem	Data space.
	offs	Offset into the data space to use.
	align	Alignment 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.
	task	Optional 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

0	Success
-L4_ENOENT	No area could be found (see L4Re::Rm::F::In_area)
-L4_EPERM	Operation not allowed.
-L4_EINVAL
-L4_EADDRNOTAVAIL	The given address is not available.
<0	IPC 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

addr	Address of the region to detach.

Return values

L4Re::Rm::Detach_result	On success.
-L4_ENOENT	No region found.
<0	IPC 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

	addr	Address of the region to detach.
[out]	ds	Returns dataspace that is affected.

Return values

L4Re::Rm::Detach_result	On success.
-L4_ENOENT	No region found.
<0	IPC 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

	addr	Address of the region to detach.
[out]	ds	Returns dataspace that is affected.
	task	Task 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

addr	Address of the region to detach.
task	Task 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]	addr	Address to look for. Returns the start address of the found region.
[in,out]	size	Size of the area to look for (in bytes). Returns the size of the found region (in bytes).
[out]	offset	Offset at the beginning of the region within the associated dataspace.
[out]	flags	Region flags, see F::Region_flags (and F::In_area).
[out]	m	Associated dataspace or paging service.

Return values

0	Success
-L4_EPERM	Operation not allowed.
-L4_ENOENT	No region found.
<0	IPC 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

addr	An address within the area to free.

Return values

0	Success
-L4_ENOENT	No area found.
<0	IPC 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]	start	The virtual start address of the area to reserve. Returns the start address of the area.
	size	The size of the area to reserve (in bytes).
	flags	Flags for the reserved area (see L4Re::Rm::F::Region_flags and L4Re::Rm::F::Attach_flags).
	align	Alignment of area if searched as bits (log2 value).

Return values

0	Success
-L4_EADDRNOTAVAIL	The given area cannot be reserved.
<0	IPC 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:

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ l4re_rm_flags_values

Function Documentation

◆ l4re_rm_attach()

◆ l4re_rm_attach_srv()

◆ l4re_rm_detach()

◆ l4re_rm_detach_ds()

◆ l4re_rm_detach_ds_unmap()

◆ l4re_rm_detach_srv()

◆ l4re_rm_detach_unmap()

◆ l4re_rm_find()

◆ l4re_rm_find_srv()

◆ l4re_rm_free_area()

◆ l4re_rm_free_area_srv()

◆ l4re_rm_reserve_area()

◆ l4re_rm_reserve_area_srv()

◆ l4re_rm_show_lists()