Memory Management Driver APIs

Memory Management Driver APIs. More...

Macros
#define	SYS_MM_MEM_CACHE_NONE   2
#define	SYS_MM_MEM_CACHE_WT   1
#define	SYS_MM_MEM_CACHE_WB   0
#define	SYS_MM_MEM_CACHE_MASK   (BIT(3) - 1)
#define	SYS_MM_MEM_PERM_RW   BIT(3)
#define	SYS_MM_MEM_PERM_EXEC   BIT(4)
#define	SYS_MM_MEM_PERM_USER   BIT(5)

Functions
int	sys_mm_drv_map_page (void *virt, uintptr_t phys, uint32_t flags)
	Map one physical page into the virtual address space. More...
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. More...
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. More...
int	sys_mm_drv_unmap_page (void *virt)
	Remove mapping for one page of the provided virtual address. More...
int	sys_mm_drv_unmap_region (void *virt, size_t size)
	Remove mappings for a provided virtual address range. More...
int	sys_mm_drv_page_phys_get (void *virt, uintptr_t *phys)
	Get the mapped physical memory address from virtual address. More...
int	sys_mm_drv_remap_region (void *virt_old, size_t size, void *virt_new)
	Remap virtual pages into new address. More...
int	sys_mm_drv_move_region (void *virt_old, size_t size, void *virt_new, uintptr_t phys_new)
	Physically move memory, with copy. More...
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. More...

Detailed Description

Memory Management Driver APIs.

Macro Definition Documentation

SYS_MM_MEM_CACHE_MASK

#define SYS_MM_MEM_CACHE_MASK   (BIT(3) - 1)

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

Reserved bits for cache modes

SYS_MM_MEM_CACHE_NONE

#define SYS_MM_MEM_CACHE_NONE   2

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

No caching

SYS_MM_MEM_CACHE_WB

#define SYS_MM_MEM_CACHE_WB   0

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

Full write-back caching

SYS_MM_MEM_CACHE_WT

#define SYS_MM_MEM_CACHE_WT   1

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

Write-through caching

SYS_MM_MEM_PERM_EXEC

#define SYS_MM_MEM_PERM_EXEC   BIT(4)

#include <include/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/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/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/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/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/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/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 simplier 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/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 simplier 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/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_remap_region()

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

#include <include/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 simplier 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/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 entrie 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/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 addresses have already been mapped