Virtual Memory Management
[L4 Region Mapper Library API Reference]


Defines
#define	L4RM_REGION_FREE 1
	Free region.
#define	L4RM_REGION_RESERVED 2
	Reserved region.
#define	L4RM_REGION_DATASPACE 3
	Region with dataspace attached to it.
#define	L4RM_REGION_PAGER 4
	Region with external pager.
#define	L4RM_REGION_EXCEPTION 5
	Region in which pagefaults are forwared as exceptions.
#define	L4RM_REGION_BLOCKED 6
	Blocked (unavailable) region.
#define	L4RM_REGION_UNKNOWN 7
	Unknown region type.
#define	L4RM_DEFAULT_REGION_AREA 0
	Default region area id.
#define	L4RM_REPLY_EMPTY 0
	Reply with empty message.
#define	L4RM_REPLY_EXCEPTION 1
	Forward exception to source thread.
#define	L4RM_REPLY_NO_REPLY 2
	Send no reply.
#define	L4RM_REPLY_SUCCESS 3
	Successfully handled request.
Typedefs
typedef L4_CV int(*	l4rm_pf_callback_fn_t )(l4_addr_t addr, l4_addr_t eip, l4_threadid_t src)
	Pagefault callback function prototype.
typedef L4_CV int(*	l4rm_unknown_fault_callback_fn_t )(l4_msgtag_t tag, l4_utcb_t *utcb, l4_threadid_t src)
	Callback function type for unknown faults.
Functions
L4_CV L4_INLINE int	l4rm_area_setup (l4_size_t size, l4_uint32_t area, int type, l4_uint32_t flags, l4_threadid_t pager, l4_addr_t *addr)
	Setup VM area.
L4_CV L4_INLINE int	l4rm_area_setup_region (l4_addr_t addr, l4_size_t size, l4_uint32_t area, int type, l4_uint32_t flags, l4_threadid_t pager)
	Setup VM area.
L4_CV int	l4rm_area_clear_region (l4_addr_t addr)
	Clear VM area.
L4_CV L4_INLINE int	l4rm_area_reserve (l4_size_t size, l4_uint32_t flags, l4_addr_t addr, l4_uint32_t area)
	Reserve area.
L4_CV L4_INLINE int	l4rm_area_reserve_region (l4_addr_t addr, l4_size_t size, l4_uint32_t flags, l4_uint32_t *area)
	Reserve specified area.
L4_CV int	l4rm_area_release (l4_uint32_t area)
	Release area.
L4_CV int	l4rm_area_release_addr (const void *ptr)
	Release area at given address.
L4_CV int	l4rm_set_userptr (const void addr, void ptr)
	Store a user-defined pointer for region.
L4_CV void *	l4rm_get_userptr (const void *addr)
	Read user-defined pointer for region.
L4_CV int	l4rm_lookup (const void addr, l4_addr_t map_addr, l4_size_t map_size, l4dm_dataspace_t ds, l4_offs_t offset, l4_threadid_t pager)
	Lookup address.
L4_CV int	l4rm_lookup_region (const void addr, l4_addr_t map_addr, l4_size_t map_size, l4dm_dataspace_t ds, l4_offs_t offset, l4_threadid_t pager)
	Lookup address, return size and type of region.
L4_CV void	l4rm_set_unkown_pagefault_callback (l4rm_pf_callback_fn_t callback)
	Set callback function for unkown pagefaults.
L4_CV void	l4rm_set_unkown_fault_callback (l4rm_unknown_fault_callback_fn_t callback)
	Set callback function for unkown faults.
L4_CV void	l4rm_enable_pagefault_exceptions (void)
	Enable exception forward for unkown pagefaults.
L4_CV void	l4rm_disable_pagefault_exceptions (void)
	Disable exception forward for unkown pagefaults.

Typedef Documentation

typedef L4_CV int(* l4rm_pf_callback_fn_t)(l4_addr_t addr, l4_addr_t eip, l4_threadid_t src)

Pagefault callback function prototype.

Parameters:

	addr	Pagefault address
	eip	Pagefault instruction pointer
	src	Pagefault source thread

Returns:

The callback function must return what type of reply the region mapper should send back to the source thread:

L4RM_REPLY_EMPTY Send an empty reply message, this should be used if the callback function could resolve the pagefault
L4RM_REPLY_EXCEPTION Forward a pagefault exception to the source thread, the thread should have registered an appropriate exception handler
L4RM_REPLY_NO_REPLY Send no reply, this blocks the source thread

typedef L4_CV int(* l4rm_unknown_fault_callback_fn_t)(l4_msgtag_t tag, l4_utcb_t *utcb, l4_threadid_t src)

Callback function type for unknown faults.

Parameters:

	tag	IPC msgtag
	utcb	UTCB pointer of the fault receiver
	src	Fault source thread

Returns:

The callback function must return what type of reply the region mapper should send back to the source thread:

L4RM_REPLY_EMPTY Send an empty reply message, this should be used if the callback function could resolve the pagefault
L4RM_REPLY_EXCEPTION Forward a pagefault exception to the source thread, the thread should have registered an appropriate exception handler
L4RM_REPLY_NO_REPLY Send no reply, this blocks the source thread

Function Documentation

L4_CV L4_INLINE int l4rm_area_setup	(	l4_size_t	size,
		l4_uint32_t	area,
		int	type,
		l4_uint32_t	flags,
		l4_threadid_t	pager,
		l4_addr_t *	addr
	)

Setup VM area.

Parameters:

	size	Region size
	area	Area id, set to L4RM_DEFAULT_REGION_AREA to use default area (i.e. an area not reserved)
	type	Region type: L4RM_REGION_PAGER region with external pager, pager must contain the id of the external pager L4RM_REGION_EXCEPTION region with exception forward L4RM_REGION_BLOCKED blocked (unavailable) region
	flags	Flags: L4RM_LOG2_ALIGNED reserve a 2^(log2(size) + 1) aligned region L4RM_SUPERPAGE_ALIGNED reserve a superpage aligned region L4RM_LOG2_ALLOC reserve the whole 2^(log2(size) + 1) sized region
	pager	External pager (if type is L4RM_REGION_PAGER), if set to L4_INVALID_ID, the pager of the region mapper thread is used

Return values:

addr

Region start address

Returns:

0 on success (setup region), error code otherwise:

-L4_ENOMAP no region found
-L4_ENOMEM out of memory allocation region descriptor
-L4_EINVAL invalid area / type
-L4_EIPC error calling region mapper

L4_CV L4_INLINE int l4rm_area_setup_region	(	l4_addr_t	addr,
		l4_size_t	size,
		l4_uint32_t	area,
		int	type,
		l4_uint32_t	flags,
		l4_threadid_t	pager
	)

Setup VM area.

Parameters:

	addr	Region start address
	size	Region size
	area	Area id, set to L4RM_DEFAULT_REGION_AREA to use default area (i.e. an area not reserved)
	type	Region type: L4RM_REGION_PAGER region with external pager, pager must contain the id of the external pager L4RM_REGION_EXCEPTION region with exception forward L4RM_REGION_BLOCKED blocked (unavailable) region
	flags	Flags: L4RM_LOG2_ALIGNED reserve a 2^(log2(size) + 1) aligned region L4RM_SUPERPAGE_ALIGNED reserve a superpage aligned region L4RM_LOG2_ALLOC reserve the whole 2^(log2(size) + 1) sized region
	pager	External pager (if type is L4RM_REGION_PAGER), if set to L4_INVALID_ID, the pager of the region mapper thread is used

Returns:

0 on success (setup region), error code otherwise:

-L4_ENOMEM out of memory allocation region descriptor
-L4_EUSED address region already used
-L4_EINVAL invalid area / type
-L4_EIPC error calling region mapper

L4_CV int l4rm_area_clear_region ( l4_addr_t addr )

Clear VM area.

Parameters:

addr

Address of VM area

Returns:

0 on success, error code otherwise

-L4_ENOTFOUND no region found at address addr
-L4_EINVAL invalid region type
-L4_EIPC IPC error calling region mapper thread

Clear region which was set up with l4rm_area_setup_region().

L4_CV L4_INLINE int l4rm_area_reserve	(	l4_size_t	size,
		l4_uint32_t	flags,
		l4_addr_t *	addr,
		l4_uint32_t *	area
	)

Reserve area.

Parameters:

	size	Area size
	flags	Flags: L4RM_LOG2_ALIGNED find a $2^{(log_2(size) + 1)}$ aligned region L4RM_SUPERPAGE_ALIGNED find a superpage aligned region L4RM_LOG2_ALLOC allocate the whole $2^{(log_2(size) + 1)}$ sized region

Return values:

	addr	Start address
	area	Area id

Returns:

0 on success (reserved area at addr), error code otherwise:

-L4_ENOTFOUND no free area of size size found
-L4_ENOMEM out of memory allocating descriptors
-L4_EIPC error calling region mapper

Reserve area of size size. The reserved area will not be used in l4rm_attach or l4rm_attach_to_region, dataspace can only be attached to this area calling l4rm_area_attach or l4rm_area_attach_to region with the appropriate area id.

L4_CV L4_INLINE int l4rm_area_reserve_region	(	l4_addr_t	addr,
		l4_size_t	size,
		l4_uint32_t	flags,
		l4_uint32_t *	area
	)

Reserve specified area.

Parameters:

	addr	Address
	size	Area Size
	flags	Flags:

Return values:

area

Area id

Returns:

0 on success (reserved area at addr), error code otherwise:

-L4_EUSED specified are aalready used
-L4_ENOMEM out of memory allocating descriptors
-L4_EIPC error calling region mapper

Reserve area at addr.

L4_CV int l4rm_area_release ( l4_uint32_t area )

Release area.

Parameters:

area

Area id

Returns:

0 on success (area released), error code otherwise:

-L4_EIPC error calling region mapper.

Release area.

L4_CV int l4rm_area_release_addr ( const void * ptr )

Release area at given address.

Parameters:

ptr

VM address

Returns:

0 on success (area released), error code otherwise:

-L4_EINVAL invalid address, address belongs not to a reserved area

L4_CV int l4rm_set_userptr	(	const void *	addr,
		void *	ptr
	)

Store a user-defined pointer for region.

Parameters:

	addr	addr inside region
	ptr	user pointer

Returns:

0 on success, error code otherwise:

-L4_EINVAL invalid address, address belongs to no used region

L4_CV void* l4rm_get_userptr ( const void * addr )

Read user-defined pointer for region.

Parameters:

addr

addr inside region

Returns:: stored user pointer or 0 if none

L4_CV int l4rm_lookup	(	const void *	addr,
		l4_addr_t *	map_addr,
		l4_size_t *	map_size,
		l4dm_dataspace_t *	ds,
		l4_offs_t *	offset,
		l4_threadid_t *	pager
	)

Lookup address.

Parameters:

addr

Address

Return values:

	map_addr	Map area start address
	map_size	Map area size
	ds	Dataspace
	offset	Offset of ptr in dataspace
	pager	External pager

Returns:

Region type on success (> 0):

L4RM_REGION_DATASPACE region with attached dataspace, ds and offset contain the dataspace id and the map offset in the dataspace
L4RM_REGION_PAGER region with external pager, pager contains the id of the external pager
L4RM_REGION_EXCEPTION region with exception forward
L4RM_REGION_BLOCKED blocked (unavailable) region
L4RM_REGION_UNKNOWN unknown region Error codes (< 0):
-L4_ENOTFOUND dataspace not found for address

Return the region type of the region at address addr. l4rm_lookup() only returns successfully if the region at addr is really used (i.e. a dataspace was attached with l4rm_attach* or the region was set up with l4rm_area_setup*). If the region is not used (either really not used or only reserved using l4rm_reserve*), l4rm_lookup() returns -L4_ENOTFOUND. To get also a result for free / reserved regions, use l4rm_lookup_region() instead of l4rm_lookup().

Note that l4rm_lookup_region() is slower than l4rm_lookup(), you should prefer l4rm_lookup() as long as you do not need to distinguish between free and reserved regions.

L4_CV int l4rm_lookup_region	(	const void *	addr,
		l4_addr_t *	map_addr,
		l4_size_t *	map_size,
		l4dm_dataspace_t *	ds,
		l4_offs_t *	offset,
		l4_threadid_t *	pager
	)

Lookup address, return size and type of region.

Parameters:

addr

Address

Return values:

	map_addr	Start address of region
	map_size	Size of whole region, beginning at map_addr
	ds	Dataspace
	offset	Offset of ptr in dataspace
	pager	External pager

Returns:

Region type on success (> 0):

L4RM_REGION_FREE free region
L4RM_REGION_RESERVED reserved region
L4RM_REGION_DATASPACE region with attached dataspace
L4RM_REGION_PAGER region with external pager
L4RM_REGION_EXCEPTION region with exception forward
L4RM_REGION_BLOCKED blocked (unavailable) region
L4RM_REGION_UNKNOWN unknown region Error codes (< 0):
-L4_ENOTFOUND no region found at given address

See l4rm_lookup() for comments.

L4_CV void l4rm_set_unkown_pagefault_callback ( l4rm_pf_callback_fn_t callback )

Set callback function for unkown pagefaults.

Parameters:

callback

Callback function, set to NULL to remove callback

L4_CV void l4rm_set_unkown_fault_callback ( l4rm_unknown_fault_callback_fn_t callback )

Set callback function for unkown faults.

Parameters:

callback

Callback function, set to NULL to remove callback

Virtual Memory Management [L4 Region Mapper Library API Reference]

Defines

Typedefs

Functions

Typedef Documentation

Function Documentation

Virtual Memory Management
[L4 Region Mapper Library API Reference]