Memory Management Driver APIs

Memory Management Driver APIs. More...

Data Structures
struct	sys_mm_drv_region
	Represents an available memory region. More...

Memory Mapping and Unmapping
On mapping and unmapping of memory.
int	sys_mm_drv_map_page (void *virt, uintptr_t phys, uint32_t flags)
	Map one physical page into the virtual address space.
int	sys_mm_drv_map_region (void *virt, uintptr_t phys, size_t size, uint32_t flags)
	Map a region of physical memory into the virtual address space.
int	sys_mm_drv_map_array (void *virt, uintptr_t *phys, size_t cnt, uint32_t flags)
	Map an array of physical memory into the virtual address space.
int	sys_mm_drv_unmap_page (void *virt)
	Remove mapping for one page of the provided virtual address.
int	sys_mm_drv_unmap_region (void *virt, size_t size)
	Remove mappings for a provided virtual address range.
int	sys_mm_drv_remap_region (void *virt_old, size_t size, void *virt_new)
	Remap virtual pages into new address.

Memory Moving
On moving already mapped memory.
int	sys_mm_drv_move_region (void *virt_old, size_t size, void *virt_new, uintptr_t phys_new)
	Physically move memory, with copy.
int	sys_mm_drv_move_array (void *virt_old, size_t size, void *virt_new, uintptr_t *phys_new, size_t phys_cnt)
	Physically move memory, with copy.

Memory Mapping Attributes
On manipulating attributes of already mapped memory.
int	sys_mm_drv_update_page_flags (void *virt, uint32_t flags)
	Update memory page flags.
int	sys_mm_drv_update_region_flags (void *virt, size_t size, uint32_t flags)
	Update memory region flags.

Memory Mappings Query
On querying information on memory mappings.
int	sys_mm_drv_page_phys_get (void *virt, uintptr_t *phys)
	Get the mapped physical memory address from virtual address.
const struct sys_mm_drv_region *	sys_mm_drv_query_memory_regions (void)
	Query available memory regions.
void	sys_mm_drv_query_memory_regions_free (const struct sys_mm_drv_region *regions)
	Free the memory array returned by sys_mm_drv_query_memory_regions.
#define	SYS_MM_DRV_MEMORY_REGION_FOREACH(regions, iter)    for (iter = regions; iter->size; iter++)
	Iterates over an array of regions returned by sys_mm_drv_query_memory_regions.

Caching mode definitions.
These are mutually exclusive.
#define	SYS_MM_MEM_CACHE_NONE   2
	No caching.
#define	SYS_MM_MEM_CACHE_WT   1
	Write-through caching.
#define	SYS_MM_MEM_CACHE_WB   0
	Full write-back caching.
#define	SYS_MM_MEM_CACHE_MASK   (BIT(3) - 1)
	Reserved bits for cache modes.

Region permission attributes.
Default should be read-only, no user, no exec.
#define	SYS_MM_MEM_PERM_RW   BIT(3)
	Region will have read/write access (and not read-only)
#define	SYS_MM_MEM_PERM_EXEC   BIT(4)
	Region will be executable (normally forbidden)
#define	SYS_MM_MEM_PERM_USER   BIT(5)
	Region will be accessible to user mode (normally supervisor-only)

Detailed Description

Memory Management Driver APIs.

This contains APIs for a system-wide memory management driver. Only one instance is permitted on the system.

Macro Definition Documentation

SYS_MM_DRV_MEMORY_REGION_FOREACH

#define SYS_MM_DRV_MEMORY_REGION_FOREACH	(		regions,
			iter
	)		for (iter = regions; iter->size; iter++)

#include <include/zephyr/drivers/mm/system_mm.h>

Iterates over an array of regions returned by sys_mm_drv_query_memory_regions.

Note that a sentinel item marking the end of the array is expected for this macro to work.

SYS_MM_MEM_CACHE_MASK

#define SYS_MM_MEM_CACHE_MASK   (BIT(3) - 1)

#include <include/zephyr/drivers/mm/system_mm.h>

Reserved bits for cache modes.

SYS_MM_MEM_CACHE_NONE

#define SYS_MM_MEM_CACHE_NONE   2

#include <include/zephyr/drivers/mm/system_mm.h>

No caching.

SYS_MM_MEM_CACHE_WB

#define SYS_MM_MEM_CACHE_WB   0

#include <include/zephyr/drivers/mm/system_mm.h>

Full write-back caching.

SYS_MM_MEM_CACHE_WT

#define SYS_MM_MEM_CACHE_WT   1

#include <include/zephyr/drivers/mm/system_mm.h>

Write-through caching.

SYS_MM_MEM_PERM_EXEC

#define SYS_MM_MEM_PERM_EXEC   BIT(4)

#include <include/zephyr/drivers/mm/system_mm.h>

Region will be executable (normally forbidden)

SYS_MM_MEM_PERM_RW

#define SYS_MM_MEM_PERM_RW   BIT(3)

#include <include/zephyr/drivers/mm/system_mm.h>

Region will have read/write access (and not read-only)

SYS_MM_MEM_PERM_USER

#define SYS_MM_MEM_PERM_USER   BIT(5)

#include <include/zephyr/drivers/mm/system_mm.h>

Region will be accessible to user mode (normally supervisor-only)

Function Documentation

sys_mm_drv_map_array()

int sys_mm_drv_map_array	(	void *	virt,
		uintptr_t *	phys,
		size_t	cnt,
		uint32_t	flags
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Map an array of physical memory into the virtual address space.

This maps an array of physical pages into a continuous virtual address space. Behavior when providing unaligned addresses is undefined, these are assumed to be page aligned.

The physical memory pages are never accessed by this operation.

This API must be safe to call in ISRs or exception handlers. Calls to this API are assumed to be serialized.

Parameters

virt	Page-aligned destination virtual address to map
phys	Array of pge-aligned source physical address to map
cnt	Number of elements in the physical page array
flags	Caching, access and control flags, see SYS_MM_MEM_* macros

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if any virtual addresses have already been mapped

sys_mm_drv_map_page()

int sys_mm_drv_map_page	(	void *	virt,
		uintptr_t	phys,
		uint32_t	flags
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Map one physical page into the virtual address space.

This maps one physical page into the virtual address space. Behavior when providing unaligned address is undefined, this is assumed to be page aligned.

The memory range itself is never accessed by this operation.

This API must be safe to call in ISRs or exception handlers. Calls to this API are assumed to be serialized.

Parameters

virt	Page-aligned destination virtual address to map
phys	Page-aligned source physical address to map
flags	Caching, access and control flags, see SYS_MM_MEM_* macros

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if virtual address has already been mapped

sys_mm_drv_map_region()

int sys_mm_drv_map_region	(	void *	virt,
		uintptr_t	phys,
		size_t	size,
		uint32_t	flags
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Map a region of physical memory into the virtual address space.

This maps a region of physical memory into the virtual address space. Behavior when providing unaligned addresses/sizes is undefined, these are assumed to be page aligned.

The memory range itself is never accessed by this operation.

This API must be safe to call in ISRs or exception handlers. Calls to this API are assumed to be serialized.

Parameters

virt	Page-aligned destination virtual address to map
phys	Page-aligned source physical address to map
size	Page-aligned size of the mapped memory region in bytes
flags	Caching, access and control flags, see SYS_MM_MEM_* macros

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if any virtual addresses have already been mapped

sys_mm_drv_move_array()

int sys_mm_drv_move_array	(	void *	virt_old,
		size_t	size,
		void *	virt_new,
		uintptr_t *	phys_new,
		size_t	phys_cnt
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Physically move memory, with copy.

This maps a region of physical memory into the new virtual address space (virt_new), and copy region of size size from the old virtual address space (virt_old). The new virtual memory region is mapped from an array of physical pages.

Behavior when providing unaligned addresses/sizes is undefined, these are assumed to be page aligned.

Note that the virtual memory at both the old and new addresses must be unmapped in the memory domains of any runnable Zephyr thread as this does not deal with memory domains.

Note that overlapping of old and new virtual memory regions is usually not supported for simpler implementation. Refer to the actual driver to make sure if overlapping is allowed.

Parameters

virt_old	Page-aligned base virtual address of existing memory
size	Page-aligned size of the mapped memory region in bytes
virt_new	Page-aligned base virtual address to which to map new physical pages
phys_new	Array of page-aligned physical address to contain the moved memory
phys_cnt	Number of elements in the physical page array

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if old virtual addresses are not all mapped or new virtual addresses are not all unmapped

sys_mm_drv_move_region()

int sys_mm_drv_move_region	(	void *	virt_old,
		size_t	size,
		void *	virt_new,
		uintptr_t	phys_new
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Physically move memory, with copy.

This maps a region of physical memory into the new virtual address space (virt_new), and copy region of size size from the old virtual address space (virt_old). The new virtual memory region is mapped from physical memory starting at phys_new of size size.

Behavior when providing unaligned addresses/sizes is undefined, these are assumed to be page aligned.

Note that the virtual memory at both the old and new addresses must be unmapped in the memory domains of any runnable Zephyr thread as this does not deal with memory domains.

Note that overlapping of old and new virtual memory regions is usually not supported for simpler implementation. Refer to the actual driver to make sure if overlapping is allowed.

Parameters

virt_old	Page-aligned base virtual address of existing memory
size	Page-aligned size of the mapped memory region in bytes
virt_new	Page-aligned base virtual address to which to map new physical pages
phys_new	Page-aligned base physical address to contain the moved memory

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if old virtual addresses are not all mapped or new virtual addresses are not all unmapped

sys_mm_drv_page_phys_get()

int sys_mm_drv_page_phys_get	(	void *	virt,
		uintptr_t *	phys
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Get the mapped physical memory address from virtual address.

The function queries the translation tables to find the physical memory address of a mapped virtual address.

Behavior when providing unaligned address is undefined, this is assumed to be page aligned.

Parameters

	virt	Page-aligned virtual address
[out]	phys	Mapped physical address (can be NULL if only checking if virtual address is mapped)

Return values

0	if mapping is found and valid
-EINVAL	if invalid arguments are provided
-EFAULT	if virtual address is not mapped

sys_mm_drv_query_memory_regions()

const struct sys_mm_drv_region * sys_mm_drv_query_memory_regions

(

void

)

#include <include/zephyr/drivers/mm/system_mm.h>

Query available memory regions.

Returns an array of available memory regions. One can iterate over the array using SYS_MM_DRV_MEMORY_REGION_FOREACH. Note that the last item of the array is a sentinel marking the end, and it's identified by it's size attribute, which is zero.

Return values

regions

A possibly empty array - i.e. containing only the sentinel marking at the end - of memory regions.

sys_mm_drv_query_memory_regions_free()

void sys_mm_drv_query_memory_regions_free

(

const struct sys_mm_drv_region *

regions

)

#include <include/zephyr/drivers/mm/system_mm.h>

Free the memory array returned by sys_mm_drv_query_memory_regions.

The driver may have dynamically allocated the memory for the array of regions returned by sys_mm_drv_query_memory_regions. This method provides it the opportunity to free any related resources.

Parameters

regions

Array of regions previously returned by sys_mm_drv_query_memory_regions

sys_mm_drv_remap_region()

int sys_mm_drv_remap_region	(	void *	virt_old,
		size_t	size,
		void *	virt_new
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Remap virtual pages into new address.

This remaps a virtual memory region starting at virt_old of size size into a new virtual memory region starting at virt_new. In other words, physical memory at virt_old is remapped to appear at virt_new. Both addresses must be page aligned and valid.

Note that the virtual memory at both the old and new addresses must be unmapped in the memory domains of any runnable Zephyr thread as this does not deal with memory domains.

Note that overlapping of old and new virtual memory regions is usually not supported for simpler implementation. Refer to the actual driver to make sure if overlapping is allowed.

Parameters

virt_old	Page-aligned base virtual address of existing memory
size	Page-aligned size of the mapped memory region in bytes
virt_new	Page-aligned base virtual address to which to remap the memory

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if old virtual addresses are not all mapped or new virtual addresses are not all unmapped

sys_mm_drv_unmap_page()

int sys_mm_drv_unmap_page

(

void *

virt

)

#include <include/zephyr/drivers/mm/system_mm.h>

Remove mapping for one page of the provided virtual address.

This unmaps one page from the virtual address space.

When this completes, the relevant translation table entries will be updated as if no mapping was ever made for that memory page. No previous context needs to be preserved. This function must update mapping in all active translation tables.

Behavior when providing unaligned address is undefined, this is assumed to be page aligned.

Implementations must invalidate translation caching as necessary.

Parameters

virt	Page-aligned virtual address to un-map

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if virtual address is not mapped

sys_mm_drv_unmap_region()

int sys_mm_drv_unmap_region	(	void *	virt,
		size_t	size
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Remove mappings for a provided virtual address range.

This unmaps pages in the provided virtual address range.

When this completes, the relevant translation table entries will be updated as if no mapping was ever made for that memory range. No previous context needs to be preserved. This function must update mappings in all active translation tables.

Behavior when providing unaligned address is undefined, this is assumed to be page aligned.

Implementations must invalidate translation caching as necessary.

Parameters

virt	Page-aligned base virtual address to un-map
size	Page-aligned region size

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if virtual address is not mapped

sys_mm_drv_update_page_flags()

int sys_mm_drv_update_page_flags	(	void *	virt,
		uint32_t	flags
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Update memory page flags.

This changes the attributes of physical memory page which is already mapped to a virtual address. This is useful when use case of specific memory region changes. E.g. when the library/module code is copied to the memory then it needs to be read-write and after it has already been copied and library/module code is ready to be executed then attributes need to be changed to read-only/executable. Calling this API must not cause losing memory contents.

Parameters

virt	Page-aligned virtual address to be updated
flags	Caching, access and control flags, see SYS_MM_MEM_* macros

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if virtual addresses is not mapped

sys_mm_drv_update_region_flags()

int sys_mm_drv_update_region_flags	(	void *	virt,
		size_t	size,
		uint32_t	flags
	)

#include <include/zephyr/drivers/mm/system_mm.h>

Update memory region flags.

This changes the attributes of physical memory which is already mapped to a virtual address. This is useful when use case of specific memory region changes. E.g. when the library/module code is copied to the memory then it needs to be read-write and after it has already been copied and library/module code is ready to be executed then attributes need to be changed to read-only/executable. Calling this API must not cause losing memory contents.

Parameters

virt	Page-aligned virtual address to be updated
size	Page-aligned size of the mapped memory region in bytes
flags	Caching, access and control flags, see SYS_MM_MEM_* macros

Return values

0	if successful
-EINVAL	if invalid arguments are provided
-EFAULT	if virtual addresses is not mapped