Region map. More...

#include <l4/re/rm>

Inheritance diagram for L4Re::Rm:

Collaboration diagram for L4Re::Rm:

Data Structures
struct	F
	Rm flags definitions. More...

struct	Range
	A range of virtual addresses. More...

class	Unique_region
	Unique region. More...

Public Types
enum	Detach_result { Detached_ds = 0 , Kept_ds = 1 , Split_ds = 2 , Detach_result_mask = 3 , Detach_again = 4 }
	Result values for detach operation. More...

enum	Region_flag_shifts { Caching_shift = Dataspace::F::Caching_shift }
	Region flag shifts. More...

enum	Detach_flags { Detach_exact = 1 , Detach_overlap = 2 , Detach_keep = 4 }
	Flags for detach operation. More...

using	Region = Range
	A region is a range of virtual addresses which is backed by a dataspace.

using	Area = Range
	An area is a range of virtual addresses which is reserved, see L4Re::Rm::reserve_area().

Public Member Functions
long	reserve_area (l4_addr_t *start, unsigned long size, Flags flags=Flags(0), unsigned char align=L4_PAGESHIFT) const noexcept
	Reserve the given area in the region map.

template<typename T >
long	reserve_area (T **start, unsigned long size, Flags flags=Flags(0), unsigned char align=L4_PAGESHIFT) const noexcept
	Reserve the given area in the region map.

long	free_area (l4_addr_t addr)
	Free an area from the region map.

long	attach (l4_addr_t *start, unsigned long size, Flags flags, L4::Ipc::Cap< Dataspace > mem, Offset offs=0, unsigned char align=L4_PAGESHIFT, L4::Cap< L4::Task > const task=L4::Cap< L4::Task >::Invalid) const noexcept
	Attach a data space to a region.

template<typename T >
long	attach (T **start, unsigned long size, Flags flags, L4::Ipc::Cap< Dataspace > mem, Offset offs=0, unsigned char align=L4_PAGESHIFT, L4::Cap< L4::Task > const task=L4::Cap< L4::Task >::Invalid) const noexcept
	Attach a data space to a region.

int	detach (l4_addr_t addr, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task=This_task) const noexcept
	Detach and unmap a region from the address space.

int	detach (void addr, L4::Cap< Dataspace > mem, L4::Cap< L4::Task > const &task=This_task) const noexcept
	Detach and unmap a region from the address space.

int	detach (l4_addr_t start, unsigned long size, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task) const noexcept
	Detach and unmap all parts of the regions within the specified interval.

long	find (l4_addr_t addr, unsigned long size, Offset offset, L4Re::Rm::Flags flags, L4::Cap< Dataspace > *m) noexcept
	Find a region given an address and size.

long	get_regions (l4_addr_t start, L4::Ipc::Ret_array< Range > regions)
	Return the list of regions whose starting addresses are higher or equal to `start` in the address space managed by this region map.

long	get_areas (l4_addr_t start, L4::Ipc::Ret_array< Range > areas)
	Return the list of areas whose starting addresses are higher or equal to `start` in the address space managed by this region map.

Public Member Functions inherited from L4::Pager
l4_msgtag_t	page_fault (l4_umword_t pfa, l4_umword_t pc, L4::Ipc::Rcv_fpage rwin, L4::Ipc::Opt< L4::Ipc::Snd_fpage & > fp)
	Page-fault protocol message.

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::Rcv_fpage rwin, L4::Ipc::Opt< L4::Ipc::Snd_fpage & > fp)
	IO page fault protocol message.

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 Base::__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 Base::__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< Class >	c () const noexcept
	Get the capability to ourselves.

Protected Member Functions inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT >
L4::Cap< Class >	c () const noexcept
	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__ () noexcept
	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__ () noexcept
	Helper to check for protocol conflicts.

Detailed Description

Region map.

See also: Region map API .

Definition at line 92 of file rm.

Member Typedef Documentation

◆ Area

using L4Re::Rm::Area = Range

An area is a range of virtual addresses which is reserved, see L4Re::Rm::reserve_area().

See also: Region map API

Definition at line 701 of file rm.

◆ Region

using L4Re::Rm::Region = Range

A region is a range of virtual addresses which is backed by a dataspace.

See also: Region map API

Definition at line 693 of file rm.

Member Enumeration Documentation

◆ Detach_flags

enum L4Re::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 F::Detach_free.

Definition at line 229 of file rm.

◆ Detach_result

enum L4Re::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 100 of file rm.

◆ Region_flag_shifts

enum L4Re::Rm::Region_flag_shifts

Region flag shifts.

Enumerator
Caching_shift	Start of Rm cache bits.

Definition at line 112 of file rm.

Member Function Documentation

◆ attach() [1/2]

long L4Re::Rm::attach	(	l4_addr_t *	start,
		unsigned long	size,
		Rm::Flags	flags,
		L4::Ipc::Cap< Dataspace >	mem,
		Rm::Offset	offs = `0`,
		unsigned char	align = `L4_PAGESHIFT`,
		L4::Cap< L4::Task > const	task = `L4::Cap<L4::Task>::Invalid`
	)		const

noexcept

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

Definition at line 44 of file rm_impl.h.

◆ attach() [2/2]

template<typename T >

long L4Re::Rm::attach	(	T **	start,
		unsigned long	size,
		Flags	flags,
		L4::Ipc::Cap< Dataspace >	mem,
		Offset	offs = `0`,
		unsigned char	align = `L4_PAGESHIFT`,
		L4::Cap< L4::Task > const	task = `L4::Cap<L4::Task>::Invalid`
	)		const

inlinenoexcept

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

Definition at line 411 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

inlinenoexcept

Detach and unmap a region from the address space.

Parameters

	addr	Virtual address of region, any address within the region is valid.
[out]	mem	Dataspace that is affected. Give 0 if not interested.
	task	This 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

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 (address type). The corresponding part of the address space is now available again.

Definition at line 746 of file rm.

◆ detach() [2/3]

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

inlinenoexcept

Detach and unmap all parts of the regions within the specified interval.

Parameters

	start	Start of area to detach, must be within region.
	size	Size of of area to detach (in bytes).
[out]	mem	Dataspace that is affected. Give 0 if not interested.
	task	This 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

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

◆ detach() [3/3]

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

inlinenoexcept

Detach and unmap a region from the address space.

Parameters

	addr	Virtual address of region, any address within the region is valid.
[out]	mem	Dataspace that is affected. Give 0 if not interested.
	task	This 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

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 (address type). The corresponding part of the address space is now available again.

Definition at line 751 of file rm.

◆ find()

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

inlinenoexcept

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.

Definition at line 668 of file rm.

◆ free_area()

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

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.

◆ get_areas()

long L4Re::Rm::get_areas	(	l4_addr_t	start,
		L4::Ipc::Ret_array< Range >	areas
	)

Return the list of areas whose starting addresses are higher or equal to start in the address space managed by this region map.

Parameters

	start	Virtual address from where to start searching.
[out]	areas	List of areas found in this region map.

Return values

>=0	Number of returned areas in the `areas` array.
<0	IPC errors

Note: The returned list of areas might not be complete and the caller shall use the function repeatedly with a start address one larger than the end address of the last area from the previous call.

◆ get_regions()

long L4Re::Rm::get_regions	(	l4_addr_t	start,
		L4::Ipc::Ret_array< Range >	regions
	)

Return the list of regions whose starting addresses are higher or equal to start in the address space managed by this region map.

Parameters

	start	Virtual address from where to start searching.
[out]	regions	List of regions found in this region map.

Return values

>=0	Number of returned regions in the `regions` array.
<0	IPC errors

Note: The returned list of regions might not be complete and the caller shall use the function repeatedly with a start address one larger that the end address of the last region from the previous call.

◆ reserve_area() [1/2]

long L4Re::Rm::reserve_area	(	l4_addr_t *	start,
		unsigned long	size,
		Flags	flags = `Flags(0)`,
		unsigned char	align = `L4_PAGESHIFT`
	)		const

inlinenoexcept

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.

Definition at line 288 of file rm.

◆ reserve_area() [2/2]

template<typename T >

long L4Re::Rm::reserve_area	(	T **	start,
		unsigned long	size,
		Flags	flags = `Flags(0)`,
		unsigned char	align = `L4_PAGESHIFT`
	)		const

inlinenoexcept

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 F::Region_flags and 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

For more information, please refer to the analogous function

See also: L4Re::Rm::reserve_area.

Definition at line 314 of file rm.

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

l4/re/rm
l4/re/impl/rm_impl.h

Data Structures

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Area

◆ Region

Member Enumeration Documentation

◆ Detach_flags

◆ Detach_result

◆ Region_flag_shifts

Member Function Documentation

◆ attach() [1/2]

◆ attach() [2/2]

◆ detach() [1/3]

◆ detach() [2/3]

◆ detach() [3/3]

◆ find()

◆ free_area()

◆ get_areas()

◆ get_regions()

◆ reserve_area() [1/2]

◆ reserve_area() [2/2]