Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/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/sdk-nrf/sdk-nrf/ncs/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
virtPage-aligned Destination virtual address to map
physPage-aligned Source physical address to map
sizePage-aligned size of the mapped memory region in bytes
flagsCaching, 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/sdk-nrf/sdk-nrf/ncs/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/sdk-nrf/sdk-nrf/ncs/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/sdk-nrf/sdk-nrf/ncs/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/sdk-nrf/sdk-nrf/ncs/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
addrPage-aligned base virtual address to un-map
sizePage-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/sdk-nrf/sdk-nrf/ncs/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
addrVirtual address to look up in page tables
[out]locationIf 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_accessedWhether to clear ARCH_DATA_PAGE_ACCESSED state
Return values
Valuewith 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/sdk-nrf/sdk-nrf/ncs/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
addrVirtual data page address that took the page fault
[out]locationIn 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_OUTThe page was evicted to the backing store.
ARCH_PAGE_FAULT_PAGED_INThe data page is resident in memory.
ARCH_PAGE_FAULT_BADThe 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/sdk-nrf/sdk-nrf/ncs/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
virtPage-aligned virtual address
[out]physMapped physical address (can be NULL if only checking if virtual address is mapped)
Return values
0if mapping is found and valid
-EFAULTif virtual address is not mapped

◆ arch_reserved_pages_update()

void arch_reserved_pages_update ( void  )

#include </home/runner/work/sdk-nrf/sdk-nrf/ncs/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.