Architecture-specific memory-mapping APIs

Macros
#define	ARCH_DATA_PAGE_ACCESSED   ((uintptr_t)BIT(5))
	Bit indicating the data page was accessed since the value was last cleared.
#define	ARCH_DATA_PAGE_DIRTY   ((uintptr_t)BIT(6))
	Bit indicating the data page, if evicted, will need to be paged out.
#define	ARCH_DATA_PAGE_LOADED   ((uintptr_t)BIT(0))
	Bit indicating that the data page is loaded into a physical page frame.
#define	ARCH_DATA_PAGE_NOT_MAPPED   ((uintptr_t)BIT(7))
	If ARCH_DATA_PAGE_LOADED is un-set, this will indicate that the page is not mapped at all.

Enumerations
enum	arch_page_location { ARCH_PAGE_LOCATION_PAGED_OUT , ARCH_PAGE_LOCATION_PAGED_IN , ARCH_PAGE_LOCATION_BAD }
	Status of a particular page location. More...

Functions
void	arch_mem_map (void *virt, uintptr_t phys, size_t size, uint32_t flags)
	Map physical memory into the virtual address space.
void	arch_mem_unmap (void *addr, size_t size)
	Remove mappings for a provided virtual address range.
int	arch_page_phys_get (void *virt, uintptr_t *phys)
	Get the mapped physical memory address from virtual address.
void	arch_reserved_pages_update (void)
	Update page frame database with reserved pages.
void	arch_mem_page_out (void *addr, uintptr_t location)
	Update all page tables for a paged-out data page.
void	arch_mem_page_in (void *addr, uintptr_t phys)
	Update all page tables for a paged-in data page.
void	arch_mem_scratch (uintptr_t phys)
	Update current page tables for a temporary mapping.
enum arch_page_location	arch_page_location_get (void *addr, uintptr_t *location)
	Fetch location information about a page at a particular address.
uintptr_t	arch_page_info_get (void *addr, uintptr_t *location, bool clear_accessed)
	Retrieve page characteristics from the page table(s)

Detailed Description

Macro Definition Documentation

ARCH_DATA_PAGE_ACCESSED

#define ARCH_DATA_PAGE_ACCESSED   ((uintptr_t)BIT(5))

#include <zephyr/arch/x86/mmustructs.h>

Bit indicating the data page was accessed since the value was last cleared.

Used by marking eviction algorithms. Safe to set this if uncertain.

This bit is undefined if ARCH_DATA_PAGE_LOADED is not set.

ARCH_DATA_PAGE_DIRTY

#define ARCH_DATA_PAGE_DIRTY   ((uintptr_t)BIT(6))

#include <zephyr/arch/x86/mmustructs.h>

Bit indicating the data page, if evicted, will need to be paged out.

Set if the data page was modified since it was last paged out, or if it has never been paged out before. Safe to set this if uncertain.

This bit is undefined if ARCH_DATA_PAGE_LOADED is not set.

ARCH_DATA_PAGE_LOADED

#define ARCH_DATA_PAGE_LOADED   ((uintptr_t)BIT(0))

#include <zephyr/arch/x86/mmustructs.h>

Bit indicating that the data page is loaded into a physical page frame.

If un-set, the data page is paged out or not mapped.

ARCH_DATA_PAGE_NOT_MAPPED

#define ARCH_DATA_PAGE_NOT_MAPPED   ((uintptr_t)BIT(7))

#include <zephyr/arch/x86/mmustructs.h>

If ARCH_DATA_PAGE_LOADED is un-set, this will indicate that the page is not mapped at all.

This bit is undefined if ARCH_DATA_PAGE_LOADED is set.

Enumeration Type Documentation

arch_page_location

enum arch_page_location

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Status of a particular page location.

Enumerator
ARCH_PAGE_LOCATION_PAGED_OUT	The page has been evicted to the backing store.
ARCH_PAGE_LOCATION_PAGED_IN	The page is resident in memory.
ARCH_PAGE_LOCATION_BAD	The page is not mapped.

Function Documentation

arch_mem_map()

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

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Map physical memory into the virtual address space.

This is a low-level interface to mapping pages into the address space. Behavior when providing unaligned addresses/sizes is undefined, these are assumed to be aligned to CONFIG_MMU_PAGE_SIZE.

The core kernel handles all management of the virtual address space; by the time we invoke this function, we know exactly where this mapping will be established. If the page tables already had mappings installed for the virtual memory region, these will be overwritten.

If the target architecture supports multiple page sizes, currently only the smallest page size will be used.

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, and indeed all usage will originate from kernel/mm.c which handles virtual memory management.

Architectures are expected to pre-allocate page tables for the entire address space, as defined by CONFIG_KERNEL_VM_BASE and CONFIG_KERNEL_VM_SIZE. This operation should never require any kind of allocation for paging structures.

Validation of arguments should be done via assertions.

This API is part of infrastructure still under development and may change.

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 K_MAP_* macros

arch_mem_page_in()

void arch_mem_page_in	(	void *	addr,
		uintptr_t	phys
	)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Update all page tables for a paged-in data page.

This function:

• Maps the specified virtual data page address to the provided physical page frame address, such that future memory accesses will function as expected. Access and caching attributes are undisturbed.
• Clears any accounting for "accessed" and "dirty" states.

If multiple page tables are in use, this must update all page tables. This function is called with interrupts locked.

Calling this function on data pages which are already paged in is undefined behavior.

This API is part of infrastructure still under development and may change.

arch_mem_page_out()

void arch_mem_page_out	(	void *	addr,
		uintptr_t	location
	)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Update all page tables for a paged-out data page.

This function:

• Sets the data page virtual address to trigger a fault if accessed that can be distinguished from access violations or un-mapped pages.
• Saves the provided location value so that it can retrieved for that data page in the page fault handler.
• The location value semantics are undefined here but the value will be always be page-aligned. It could be 0.

If multiple page tables are in use, this must update all page tables. This function is called with interrupts locked.

Calling this function on data pages which are already paged out is undefined behavior.

This API is part of infrastructure still under development and may change.

arch_mem_scratch()

void arch_mem_scratch

(

uintptr_t

phys

)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Update current page tables for a temporary mapping.

Map a physical page frame address to a special virtual address Z_SCRATCH_PAGE, with read/write access to supervisor mode, such that when this function returns, the calling context can read/write the page frame's contents from the Z_SCRATCH_PAGE address.

This mapping only needs to be done on the current set of page tables, as it is only used for a short period of time exclusively by the caller. This function is called with interrupts locked.

This API is part of infrastructure still under development and may change.

arch_mem_unmap()

void arch_mem_unmap	(	void *	addr,
		size_t	size
	)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Remove mappings for a provided virtual address range.

This is a low-level interface for un-mapping pages from the address space. When this completes, the relevant page 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 page tables.

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

Behavior when providing an address range that is not already mapped is undefined.

This function should never require memory allocations for paging structures, and it is not necessary to free any paging structures. Empty page tables due to all contained entries being un-mapped may remain in place.

Implementations must invalidate TLBs as necessary.

This API is part of infrastructure still under development and may change.

Parameters

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

arch_page_info_get()

uintptr_t arch_page_info_get	(	void *	addr,
		uintptr_t *	location,
		bool	clear_accessed
	)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Retrieve page characteristics from the page table(s)

The architecture is responsible for maintaining "accessed" and "dirty" states of data pages to support marking eviction algorithms. This can either be directly supported by hardware or emulated by modifying protection policy to generate faults on reads or writes. In all cases the architecture must maintain this information in some way.

For the provided virtual address, report the logical OR of the accessed and dirty states for the relevant entries in all active page tables in the system if the page is mapped and not paged out.

If clear_accessed is true, the ARCH_DATA_PAGE_ACCESSED flag will be reset. This function will report its prior state. If multiple page tables are in use, this function clears accessed state in all of them.

This function is called with interrupts locked, so that the reported information can't become stale while decisions are being made based on it.

The return value may have other bits set which the caller must ignore.

Clearing accessed state for data pages that are not ARCH_DATA_PAGE_LOADED is undefined behavior.

ARCH_DATA_PAGE_DIRTY and ARCH_DATA_PAGE_ACCESSED bits in the return value are only significant if ARCH_DATA_PAGE_LOADED is set, otherwise ignore them.

ARCH_DATA_PAGE_NOT_MAPPED bit in the return value is only significant if ARCH_DATA_PAGE_LOADED is un-set, otherwise ignore it.

Unless otherwise specified, virtual data pages have the same mappings across all page tables. Calling this function on data pages that are exceptions to this rule (such as the scratch page) is undefined behavior.

This API is part of infrastructure still under development and may change.

Parameters

	addr	Virtual address to look up in page tables
[out]	location	If non-NULL, updated with either physical page frame address or backing store location depending on ARCH_DATA_PAGE_LOADED state. This is not touched if ARCH_DATA_PAGE_NOT_MAPPED.
	clear_accessed	Whether to clear ARCH_DATA_PAGE_ACCESSED state

Return values

Value

with ARCH_DATA_PAGE_* bits set reflecting the data page configuration

arch_page_location_get()

enum arch_page_location arch_page_location_get	(	void *	addr,
		uintptr_t *	location
	)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Fetch location information about a page at a particular address.

The function only needs to query the current set of page tables as the information it reports must be common to all of them if multiple page tables are in use. If multiple page tables are active it is unnecessary to iterate over all of them. This may allow certain types of optimizations (such as reverse page table mapping on x86).

This function is called with interrupts locked, so that the reported information can't become stale while decisions are being made based on it.

Unless otherwise specified, virtual data pages have the same mappings across all page tables. Calling this function on data pages that are exceptions to this rule (such as the scratch page) is undefined behavior. Just check the currently installed page tables and return the information in that.

Parameters

	addr	Virtual data page address that took the page fault
[out]	location	In the case of ARCH_PAGE_FAULT_PAGED_OUT, the backing store location value used to retrieve the data page. In the case of ARCH_PAGE_FAULT_PAGED_IN, the physical address the page is mapped to.

Return values

ARCH_PAGE_FAULT_PAGED_OUT	The page was evicted to the backing store.
ARCH_PAGE_FAULT_PAGED_IN	The data page is resident in memory.
ARCH_PAGE_FAULT_BAD	The page is un-mapped or otherwise has had invalid access

arch_page_phys_get()

int arch_page_phys_get	(	void *	virt,
		uintptr_t *	phys
	)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Get the mapped physical memory address from virtual address.

The function only needs to query the current set of page tables as the information it reports must be common to all of them if multiple page tables are in use. If multiple page tables are active it is unnecessary to iterate over all of them.

Unless otherwise specified, virtual pages have the same mappings across all page tables. Calling this function on data pages that are exceptions to this rule (such as the scratch page) is undefined behavior. Just check the currently installed page tables and return the information in that.

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
-EFAULT	if virtual address is not mapped

arch_reserved_pages_update()

void arch_reserved_pages_update

(

void

)

#include </home/runner/_work/zephyr/zephyr/kernel/include/kernel_arch_interface.h>

Update page frame database with reserved pages.

Some page frames within system RAM may not be available for use. A good example of this is reserved regions in the first megabyte on PC-like systems.

Implementations of this function should mark all relevant entries in z_page_frames with K_PAGE_FRAME_RESERVED. This function is called at early system initialization with mm_lock held.