Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Kernel Memory Management

Kernel Memory Management . More...

Topics

 Demand Paging
 
 

Functions

size_t k_mem_free_get (void)
 Return the amount of free memory available.
 
static void * k_mem_map (size_t size, uint32_t flags)
 Map anonymous memory into Zephyr's address space.
 
static void k_mem_unmap (void *addr, size_t size)
 Un-map mapped memory.
 
int k_mem_update_flags (void *addr, size_t size, uint32_t flags)
 Modify memory mapping attribute flags.
 
size_t k_mem_region_align (uintptr_t *aligned_addr, size_t *aligned_size, uintptr_t addr, size_t size, size_t align)
 Given an arbitrary region, provide a aligned region that covers it.
 

Caching mode definitions.

These are mutually exclusive.

#define K_MEM_CACHE_NONE   2
 No caching.
 
#define K_MEM_CACHE_WT   1
 Write-through caching.
 
#define K_MEM_CACHE_WB   0
 Full write-back caching.
 
#define K_MEM_CACHE_MASK   (BIT(3) - 1)
 Reserved bits for cache modes in k_map() flags argument.
 

Region permission attributes.

Default is read-only, no user, no exec

#define K_MEM_PERM_RW   BIT(3)
 Region will have read/write access (and not read-only)
 
#define K_MEM_PERM_EXEC   BIT(4)
 Region will be executable (normally forbidden)
 
#define K_MEM_PERM_USER   BIT(5)
 Region will be accessible to user mode (normally supervisor-only)
 

Region mapping behaviour attributes

#define K_MEM_DIRECT_MAP   BIT(6)
 Region will be mapped to 1:1 virtual and physical address.
 

k_mem_map() control flags

#define K_MEM_MAP_UNINIT   BIT(16)
 The mapped region is not guaranteed to be zeroed.
 
#define K_MEM_MAP_LOCK   BIT(17)
 Region will be pinned in memory and never paged.
 
#define K_MEM_MAP_UNPAGED   BIT(18)
 Region will be unpaged i.e.
 

Detailed Description

Kernel Memory Management .

Macro Definition Documentation

◆ K_MEM_CACHE_MASK

#define K_MEM_CACHE_MASK   (BIT(3) - 1)

#include <zephyr/kernel/mm.h>

Reserved bits for cache modes in k_map() flags argument.

◆ K_MEM_CACHE_NONE

#define K_MEM_CACHE_NONE   2

#include <zephyr/kernel/mm.h>

No caching.

Most drivers want this.

◆ K_MEM_CACHE_WB

#define K_MEM_CACHE_WB   0

#include <zephyr/kernel/mm.h>

Full write-back caching.

Any RAM mapped wants this.

◆ K_MEM_CACHE_WT

#define K_MEM_CACHE_WT   1

#include <zephyr/kernel/mm.h>

Write-through caching.

Used by certain drivers.

◆ K_MEM_DIRECT_MAP

#define K_MEM_DIRECT_MAP   BIT(6)

#include <zephyr/kernel/mm.h>

Region will be mapped to 1:1 virtual and physical address.

◆ K_MEM_MAP_LOCK

#define K_MEM_MAP_LOCK   BIT(17)

#include <zephyr/kernel/mm.h>

Region will be pinned in memory and never paged.

Such memory is guaranteed to never produce a page fault due to page-outs or copy-on-write once the mapping call has returned. Physical page frames will be pre-fetched as necessary and pinned.

◆ K_MEM_MAP_UNINIT

#define K_MEM_MAP_UNINIT   BIT(16)

#include <zephyr/kernel/mm.h>

The mapped region is not guaranteed to be zeroed.

This may improve performance. The associated page frames may contain indeterminate data, zeroes, or even sensitive information.

This may not be used with K_MEM_PERM_USER as there are no circumstances where this is safe.

◆ K_MEM_MAP_UNPAGED

#define K_MEM_MAP_UNPAGED   BIT(18)

#include <zephyr/kernel/mm.h>

Region will be unpaged i.e.

not mapped into memory

This is meant to be used by kernel code and not by application code.

Corresponding memory address range will be set so no actual memory will be allocated initially. Allocation will happen through demand paging when addresses in that range are accessed. This is incompatible with K_MEM_MAP_LOCK.

When this flag is specified, the phys argument to arch_mem_map() is interpreted as a backing store location value not a physical address. This is very similar to arch_mem_page_out() in that regard. Two special location values are defined: ARCH_UNPAGED_ANON_ZERO and ARCH_UNPAGED_ANON_UNINIT. Those are to be used with anonymous memory mappings for zeroed and uninitialized pages respectively.

◆ K_MEM_PERM_EXEC

#define K_MEM_PERM_EXEC   BIT(4)

#include <zephyr/kernel/mm.h>

Region will be executable (normally forbidden)

◆ K_MEM_PERM_RW

#define K_MEM_PERM_RW   BIT(3)

#include <zephyr/kernel/mm.h>

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

◆ K_MEM_PERM_USER

#define K_MEM_PERM_USER   BIT(5)

#include <zephyr/kernel/mm.h>

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

Function Documentation

◆ k_mem_free_get()

size_t k_mem_free_get ( void )

#include <zephyr/kernel/mm.h>

Return the amount of free memory available.

The returned value will reflect how many free RAM page frames are available. If demand paging is enabled, it may still be possible to allocate more.

The information reported by this function may go stale immediately if concurrent memory mappings or page-ins take place.

Returns
Free physical RAM, in bytes

◆ k_mem_map()

static void * k_mem_map ( size_t size,
uint32_t flags )
inlinestatic

#include <zephyr/kernel/mm.h>

Map anonymous memory into Zephyr's address space.

This function effectively increases the data space available to Zephyr. The kernel will choose a base virtual address and return it to the caller. The memory will have access permissions for all contexts set per the provided flags argument.

If user thread access control needs to be managed in any way, do not enable K_MEM_PERM_USER flags here; instead manage the region's permissions with memory domain APIs after the mapping has been established. Setting K_MEM_PERM_USER here will allow all user threads to access this memory which is usually undesirable.

Unless K_MEM_MAP_UNINIT is used, the returned memory will be zeroed.

The mapped region is not guaranteed to be physically contiguous in memory. Physically contiguous buffers should be allocated statically and pinned at build time.

Pages mapped in this way have write-back cache settings.

The returned virtual memory pointer will be page-aligned. The size parameter, and any base address for re-mapping purposes must be page- aligned.

Note that the allocation includes two guard pages immediately before and after the requested region. The total size of the allocation will be the requested size plus the size of these two guard pages.

Many K_MEM_MAP_* flags have been implemented to alter the behavior of this function, with details in the documentation for these flags.

Parameters
sizeSize of the memory mapping. This must be page-aligned.
flagsK_MEM_PERM_*, K_MEM_MAP_* control flags.
Returns
The mapped memory location, or NULL if insufficient virtual address space, insufficient physical memory to establish the mapping, or insufficient memory for paging structures.

◆ k_mem_region_align()

size_t k_mem_region_align ( uintptr_t * aligned_addr,
size_t * aligned_size,
uintptr_t addr,
size_t size,
size_t align )

#include <zephyr/kernel/mm.h>

Given an arbitrary region, provide a aligned region that covers it.

The returned region will have both its base address and size aligned to the provided alignment value.

Parameters
[out]aligned_addrAligned address
[out]aligned_sizeAligned region size
[in]addrRegion base address
[in]sizeRegion size
[in]alignWhat to align the address and size to
Return values
offsetbetween aligned_addr and addr

◆ k_mem_unmap()

static void k_mem_unmap ( void * addr,
size_t size )
inlinestatic

#include <zephyr/kernel/mm.h>

Un-map mapped memory.

This removes a memory mapping for the provided page-aligned region. Associated page frames will be free and the kernel may re-use the associated virtual address region. Any paged out data pages may be discarded.

Calling this function on a region which was not mapped to begin with is undefined behavior.

Parameters
addrPage-aligned memory region base virtual address
sizePage-aligned memory region size

◆ k_mem_update_flags()

int k_mem_update_flags ( void * addr,
size_t size,
uint32_t flags )

#include <zephyr/kernel/mm.h>

Modify memory mapping attribute flags.

This updates caching, access and control flags for the provided page-aligned memory region.

Calling this function on a region which was not mapped to begin with is undefined behavior. However system memory implicitly mapped at boot time is supported.

Parameters
addrPage-aligned memory region base virtual address
sizePage-aligned memory region size
flagsK_MEM_PERM_*, K_MEM_MAP_* control flags.
Returns
0 for success, negative error code otherwise.