Memory Management Infrastructure API#

The Sound Open Firmware (SOF) memory architecture is organized into a multi-tier subsystem engineered for low-latency DSP audio pipelines, fine-grained power management, dynamic loadable module isolation, and flexible physical-to-virtual memory mapping.

Memory Architecture Organization#

SOF firmware executes across DSP architectures with heterogeneous memory pools and dedicated cache hierarchies:

+-------------------------------------------------------------------------+
|                     Audio Processing Modules (LLEXT)                    |
|           mod_balloc_align() / mod_alloc_ext() / mod_alloc()            |
+------------------------------------+------------------------------------+
                                     |
+------------------------------------v------------------------------------+
|               Context & Virtual Region Allocator (vregion)              |
|              struct mod_alloc_ctx { heap, vregion }                     |
|           [ Lifetime Partition ]  <--->  [ Interim Partition ]          |
+------------------------------------+------------------------------------+
                                     |
+------------------------------------v------------------------------------+
|                      Core RTOS Memory Allocators                        |
|           rmalloc_align() / rmalloc() / rzalloc() / rfree()             |
|                    rballoc_align() / rballoc()                          |
+-----------------+------------------+------------------+-----------------+
                  |                  |                  |
+-----------------v----+   +---------v----------+   +---v-----------------+
| System & Shared Heap |   | Virtual Heap (VMH) |   |  L3 IMR / DRAM Heap |
|  - sof_heap (SRAM)   |   |  - Dynamic TLB     |   |  - External DRAM    |
|  - shared_buffer_heap|   |  - vpage_alloc()   |   |  - Cached only      |
|  - Syscall k_heap    |   |  - Power-of-2 bins |   |  - l3_heap_save()   |
+----------------------+   +--------------------+   +---------------------+

Physical & Virtual Address Spaces#

High-Speed Internal SRAM (L2 SRAM): Low-latency on-chip memory where time-critical Low Latency (LL) task code, stack frames, ring buffers, and active processing states reside.
Cached vs. Uncached (Coherent) Memory Windows: On architectures like Xtensa and Intel cAVS/ACE, physical SRAM is mapped into both cached and uncached address aliases. The allocator dynamically selects the appropriate pointer representation based on SOF_MEM_FLAG_COHERENT:
- Cached addresses: Default for algorithm compute loops to maximize L1 cache throughput.
- Uncached (coherent) addresses: Required for DMA ring buffer descriptors, host mailboxes, and multi-core shared IPC control blocks.
External DRAM / Isolated Memory Region (L3 / IMR): High-capacity DRAM backing storage used on Intel ACE platforms (e.g. MTL, ARL, LNL, PTL) for storing large coefficient blobs, deep buffers, and inactive LLEXT modules. L3 allocations are strictly cached; requesting coherent L3 memory returns NULL. l3_heap_save() preserves L3 state and flushes cache lines across DSP power gating.
Shared User/Kernel Memory Heap: When CONFIG_SOF_USERSPACE_USE_SHARED_HEAP is active, a dedicated shared_buffer_heap is mapped across user space and supervisor domains for zero-copy buffer transfer between user modules and kernel drivers.

Subsystem Hierarchy & Allocators#

Core Allocators (``rmalloc_align``, ``rmalloc``, ``rzalloc``, ``rfree``): General-purpose RTOS allocators evaluating flags (SOF_MEM_FLAG_*) to select between l3_heap, shared_buffer_heap, and sof_heap, with automatic VMH fallback on exhaustion.
Audio Streaming Buffer Allocator (``rballoc_align``, ``rballoc``): Specialized runtime buffer allocator for PCM streams. Unlike rmalloc_align(), rballoc_align() actively prioritizes the Virtual Memory Heap (VMH) when available to preserve scarce internal SRAM.
Context-Based Allocations (``struct mod_alloc_ctx``, ``sof_ctx_*``): Pairs a Zephyr k_heap with an optional vregion. Allocations are automatically directed to the vregion interim partition when present, and fall back to sof_heap_alloc().
Contiguous Virtual Regions (``vregion``): Manages a pre-allocated contiguous address range partitioned into Lifetime (non-freeable pipeline topology allocations) and Interim (dynamically freed runtime parameter buffers and control payloads) segments.
Virtual Page Allocator (``vpage``) & Multi-Bundle VMH: Provides dynamic TLB page-table mapping (vpage_alloc / vpage_free) and power-of-2 block bundle management (vmh_init_heap, vmh_alloc, vmh_free).
Cold DRAM Dynamic Staging (``fast_get`` / ``fast_put``): Enables code or read-only constants stored in cold DRAM to be temporarily staged into high-speed SRAM during processing execution, then released back.
Cold Path Annotations & Safety Invariants: Functions annotated with __cold and data with __cold_rodata may be placed in offload storage. The runtime invariant assert_can_be_cold() validates that non-latency-critical code is never invoked from a real-time Low Latency (LL) thread.

C API Reference#

group Memory Management Infrastructure

System heaps, Virtual Memory Heap (VMH), virtual regions, cold DRAM staging, and audio buffer allocators.

Note

Re-entrancy Contract: This API is NOT re-entrant. While runtime allocation and deallocation operations (vmh_alloc(), vmh_free()) synchronize internally via the heap mutex, heap lifecycle management operations (such as vmh_free_heap()) do not use mutual exclusion. It is assumed that only system management code performs heap lifecycle operations, and concurrent heap management with runtime allocations must be avoided.

Allocation flags

SOF_MEM_FLAG_DMA#

Allocate memory accessible by DMA controllers (e.g.

Host or DSP DMA).

SOF_MEM_FLAG_NO_COPY#

realloc() skips copying the original content.

Deprecated:: Legacy realloc optimization flag. rbrealloc() and rbrealloc_align() have been removed from the allocation API.

SOF_MEM_FLAG_COHERENT#

Allocate uncached / coherent memory address.

Directs the allocator to return an uncached pointer (e.g. bypassing cache alias or mapping uncached). Mandatory for DMA descriptors, mailboxes, and cross-core shared variables. Not supported for L3 memory.

SOF_MEM_FLAG_L3#

Allocate from L3 address space (IMR / external DRAM heap).

Allocates from the L3 heap (l3_heap). Only cached allocations are supported; requesting coherent L3 memory will fail and return NULL.

SOF_MEM_FLAG_LOW_POWER#

Allocate Low power memory address.

Deprecated:: Legacy flag from XTOS memory partitions; no-op in modern Zephyr heap manager.

SOF_MEM_FLAG_KERNEL#: Base allocation flag denoting memory allocated for kernel-space data structures.

SOF_MEM_FLAG_USER#: Base allocation flag denoting memory allocated for user-space threads and module execution.

SOF_MEM_FLAG_USER_SHARED_BUFFER#: Allocate from shared user memory heap (shared_buffer_heap) accessible across user/kernel domains.

SOF_MEM_FLAG_LARGE_BUFFER#: Route allocation to the Virtual Memory Heap (VMH / virtual_buffers_heap) for large stream buffers.

Defines

__coherent#: Cache line alignment specifier for coherent shared memory objects.

ADDR_IS_INCOHERENT(_c)#

ADDR_IS_COHERENT(_c)#

CORE_CHECK_STRUCT_FIELD#

CORE_CHECK_STRUCT_INIT(_c, is_shared)#

CORE_CHECK_STRUCT(_c)#

CHECK_COHERENT_CORE(_c)#

CHECK_ISR()#

CHECK_SLEEP(_c)#

CHECK_ATOMIC(_c)#

coherent_init(type, member)#

Allocate and initialize a coherent shared object with spinlock protection.

Wrapper around __coherent_init() computing the member offset and container type size.

Parameters:

type – [in] Type of the container structure.
member – [in] Member name of the embedded struct coherent.

coherent_shared(object, member)#

Mark an allocated coherent object as actively shared across multiple DSP cores.

Wrapper around __coherent_shared() computing the member address and container size.

Parameters:

object – [inout] Pointer to the container structure.
member – [in] Member name of the embedded struct coherent.

coherent_init_thread(type, member)#

Allocate and initialize a coherent shared object with mutex protection for thread context.

Wrapper around __coherent_init_thread() computing the member offset and container type size.

Parameters:

type – [in] Type of the container structure.
member – [in] Member name of the embedded struct coherent.

coherent_shared_thread(object, member)#

Mark a thread-capable coherent object as shared across multiple DSP cores.

Wrapper around __coherent_shared_thread() computing the member address and container size.

Parameters:

object – [inout] Pointer to the container structure.
member – [in] Member name of the embedded struct coherent.

coherent_free(object, member)#

Invalidate cache and free a coherent shared memory object.

Flushes dirty cache lines back to physical memory and frees the memory block via rfree().

Parameters:

object – [inout] Pointer to the container structure.
member – [in] Member name of the embedded struct coherent.

coherent_free_thread#

Free a thread-capable coherent shared memory object.

Flushes dirty cache lines back to physical memory and frees the memory block via rfree().

Parameters:

object – [inout] Pointer to the container structure.
member – [in] Member name of the embedded struct coherent.

is_coherent_shared(object, member)#

Query whether a coherent object is configured for multi-core shared mode.

Parameters:

object – [in] Pointer to the container structure.
member – [in] Member name of the embedded struct coherent.

Returns:

Non-zero if shared mode is enabled, 0 otherwise.

__cold#

Attribute marking non-latency-critical code for placement in cold memory sections.

Cold code (e.g. initialization, IPC setup, or offload modules) may be placed in DRAM / L3 memory or powered-down banks to conserve high-speed internal SRAM.

__cold_rodata#: Attribute marking read-only constants for placement in cold memory sections.

dbg_path_hot_start_watching()#

dbg_path_hot_stop_watching()#

dbg_path_hot_confirm()#

dbg_path_cold_enter()#

assert_can_be_cold()#: Assert that the current function is not executing from a latency-critical LL thread.

VIRTUAL_REGION_SHARED_HEAP_ATTR#: Region attribute for shared virtual memory heap.

VIRTUAL_REGION_LLEXT_LIBRARIES_ATTR#: Region attribute for loadable LLEXT libraries.

VIRTUAL_REGION_VPAGES_ATTR#: Region attribute for virtual page allocator.

MAX_MEMORY_ALLOCATORS_COUNT#

Maximum amount of memory block allocators in one heap.

Since minimum realistic block is cache line size and block sizes must be powers of 2 (e.g. 64, 128, 256, 512, 1024, 2048, 4096, 8192).

DEFAULT_CONFIG_ALOCATORS_COUNT#: Default number of power-of-2 block allocators partitioned across a region.

Enums

enum vregion_mem_type#

Memory allocation modes within a virtual memory region.

Distinguishes lifetime allocations (bound to pipeline topology, cannot be freed until teardown) from interim allocations (dynamically created and released during runtime operations).

Values:

enumerator VREGION_MEM_TYPE_INTERIM#

Interim allocation that can be freed dynamically (e.g.

large config set/get, controls).

enumerator VREGION_MEM_TYPE_LIFETIME#

Lifetime allocation that persists until region destruction (e.g.

topology, module instances).

enumerator VREGION_MEM_TYPE_INVALID#: Invalid memory type indicating initialization error or exhaustion.

Functions

static inline struct coherent *coherent_acquire(struct coherent *c, const size_t size)#

Acquire exclusive access to a cache-coherent shared object in atomic/spinlock context.

For incoherent hardware platforms, validates uncache alias, acquires the spinlock, and invalidates the local data cache over the object range so local accesses observe fresh multi-core updates.

Parameters:

c – [inout] Pointer to uncached coherent object header.
size – [in] Size of the coherent object including header in bytes.

Returns:

Pointer to the cached memory view of the coherent object.

static inline void coherent_release(struct coherent *c, const size_t size)#

Release exclusive access to a cache-coherent shared object in atomic/spinlock context.

Writes back dirty cache lines across the object range to physical memory, invalidates local cache lines, and releases the multi-core spinlock.

Parameters:

c – [inout] Pointer to cached memory view of the coherent object.
size – [in] Size of the coherent object including header in bytes.

static inline void *__coherent_init(size_t offset, const size_t size)#

Internal helper to allocate and initialize a coherent shared object.

Allocates cache-aligned uncached memory with SOF_MEM_FLAG_COHERENT and initializes the coherent spinlock, tracking list, and owner core ID.

Parameters:

offset – [in] Byte offset of the struct coherent member within the allocated object.
size – [in] Total size in bytes of the container object.

Returns:

Pointer to the newly allocated coherent object, or NULL on failure.

static inline void __coherent_shared(struct coherent *c, const size_t size)#

Internal helper to mark an allocated coherent object as actively shared.

Transitions the coherent object state to shared mode under spinlock protection and invalidates local cache.

Parameters:

c – [inout] Pointer to uncached coherent object header.
size – [in] Total size in bytes of the coherent object.

static inline struct coherent *coherent_acquire_thread(struct coherent *c, const size_t size)#

Acquire exclusive access to a cache-coherent shared object in thread/mutex context.

Locks the embedded mutex (blocking if necessary) and invalidates the local data cache region so thread-level accesses observe updates from other cores.

Parameters:

c – [inout] Pointer to uncached coherent object header.
size – [in] Size of the coherent object including header in bytes.

Returns:

Pointer to the cached memory view of the coherent object.

static inline void coherent_release_thread(struct coherent *c, const size_t size)#

Release exclusive access to a cache-coherent shared object in thread/mutex context.

Writes back dirty cache lines to physical memory, invalidates local cache, and unlocks the embedded mutex.

Parameters:

c – [inout] Pointer to cached memory view of the coherent object.
size – [in] Size of the coherent object including header in bytes.

static inline void *__coherent_init_thread(size_t offset, const size_t size)#

Internal helper to allocate and initialize a thread-capable coherent shared object.

Allocates cache-aligned uncached memory with SOF_MEM_FLAG_COHERENT and initializes the embedded mutex and list header with sleeping allowed.

Parameters:

offset – [in] Byte offset of the struct coherent member within the allocated object.
size – [in] Total size in bytes of the container object.

Returns:

Pointer to the newly allocated coherent object, or NULL on failure.

static inline void __coherent_shared_thread(struct coherent *c, const size_t size)#

Internal helper to mark a thread-capable coherent object as actively shared.

Transitions the coherent object state to shared mode under mutex protection and invalidates local cache.

Parameters:

c – [inout] Pointer to uncached coherent object header.
size – [in] Total size in bytes of the coherent object.

static inline const void *fast_get(struct mod_alloc_ctx *alloc, const void *const dram_ptr, size_t size)#

static inline void fast_put(struct mod_alloc_ctx *alloc, struct k_mem_domain *mdom, const void *sram_ptr)#

struct vregion *vregion_create(size_t memsize)#

Create a new virtual region instance.

Create a new virtual region instance with specified memory size. Allocations start in LIFETIME mode.

Parameters:

memsize – [in] Total size of the virtual region memory in bytes.

Returns:

Pointer to the new virtual region instance, or NULL on failure.

struct vregion *vregion_create_map(uintptr_t *vreg_start, size_t *vreg_size)#

Create and map a new virtual region instance accessible by user-space domains.

Allocates contiguous virtual memory and configures memory protection domain permissions.

Parameters:

vreg_start – [out] Output pointer receiving the virtual start address of the region.
vreg_size – [inout] Input pointer specifying the requested size in bytes (must be non-zero); updated on return with the actual mapped size in bytes.

Returns:

Pointer to the allocated virtual region instance, or NULL on failure.

void vregion_set_interim(struct vregion *vr)#

Switch virtual region allocations to interim mode.

After this call, all allocations from this vregion will use the interim heap. The interim heap is created lazily from remaining lifetime space. Multiple calls are allowed but log a warning.

Parameters:

vr – [in] Pointer to the virtual region instance.

struct vregion *vregion_get(struct vregion *vr)#

Increment virtual region’s user count.

The creator of the virtual region is its first user, for any additional users increment the region’s use-count.

Parameters:

vr – [in] Pointer to the virtual region instance to release.

Returns:

struct vregion* Pointer to the virtual region instance.

struct vregion *vregion_put(struct vregion *vr)#

Decrement virtual region’s user count or destroy it.

Decrement virtual region’s user count, when it reaches 0 free all associated resources.

Parameters:

vr – [in] Pointer to the virtual region instance to release.

Returns:

struct vregion* Pointer to the virtual region instance or NULL if it has been destroyed.

void *vregion_alloc_align(struct vregion *vr, size_t size, size_t alignment)#

Allocate aligned memory from the specified virtual region.

Allocate aligned memory from the specified virtual region using the current allocation mode (lifetime or interim).

Parameters:

vr – [in] Pointer to the virtual region instance.
size – [in] Size of memory to allocate in bytes.
alignment – [in] Alignment of memory to allocate in bytes.

Returns:

void* Pointer to the allocated memory, or NULL on failure.

void *vregion_alloc_coherent_align(struct vregion *vr, size_t size, size_t alignment)#

Allocate aligned coherent (uncached) memory from the specified virtual region.

Parameters:

vr – [inout] Pointer to the virtual region instance.
size – [in] Size of memory to allocate in bytes.
alignment – [in] Alignment of memory to allocate in bytes.

Returns:

Pointer to the allocated coherent memory, or NULL on failure.

static inline void *vregion_alloc(struct vregion *vr, size_t size)#

Allocate memory from the specified virtual region.

Parameters:

vr – [inout] Pointer to the virtual region instance.
size – [in] Size of memory to allocate in bytes.

Returns:

Pointer to the allocated memory, or NULL on failure.

static inline void *vregion_alloc_coherent(struct vregion *vr, size_t size)#

Allocate naturally aligned coherent (uncached) memory from the specified virtual region.

Parameters:

vr – [inout] Pointer to the virtual region instance.
size – [in] Size of memory to allocate in bytes.

Returns:

Pointer to the allocated coherent memory, or NULL on failure.

void vregion_free(struct vregion *vr, void *ptr)#

Free memory allocated from the specified virtual region.

Free memory previously allocated from the specified virtual region.

Parameters:

vr – [inout] Pointer to the virtual region instance.
ptr – [inout] Pointer to the memory to free.

void vregion_info(struct vregion *vr)#

Log virtual region memory usage.

Parameters:

vr – [in] Pointer to the virtual region instance.

void vregion_mem_info(struct vregion *vr, size_t *size, uintptr_t *start)#

Retrieve virtual region memory base address and size.

Parameters:

vr – [in] Pointer to the virtual region instance.
size – [out] Output pointer receiving total region size in bytes.
start – [out] Output pointer receiving starting virtual address.

bool vregion_verify(struct vregion *vr)#

Validate that a virtual region handle is genuine and isolated from user space.

Parameters:

vr – [in] Pointer to virtual region instance to verify.

Returns:

True if handle is valid and secure, false otherwise.

void *rmalloc_align(uint32_t flags, size_t bytes, uint32_t alignment)#

Allocate memory block with explicit alignment and heap selection flags.

Core RTOS memory allocator. Evaluates flags to select the appropriate heap:

SOF_MEM_FLAG_L3: Allocates from the L3 IMR / external DRAM heap (cached only).
SOF_MEM_FLAG_USER_SHARED_BUFFER: Allocates from shared_buffer_heap.
Default: Allocates from system heap (sof_heap).

If SOF_MEM_FLAG_COHERENT is specified, returns an uncached (coherent) pointer. Otherwise, returns a cached pointer. When CONFIG_VIRTUAL_HEAP is enabled and system heap allocation fails, transparently attempts fallback allocation from the Virtual Memory Heap (VMH).

Parameters:

flags – [in] Memory allocation flags, see SOF_MEM_FLAG_…
bytes – [in] Size in bytes to allocate.
alignment – [in] Required alignment in bytes (0 for default/natural alignment).

Returns:

Pointer to the allocated memory block, or NULL on allocation failure.

void *rmalloc(uint32_t flags, size_t bytes)#

Allocate memory block with default natural alignment.

Convenience wrapper calling rmalloc_align() with alignment set to 0.

Parameters:

flags – [in] Memory allocation flags, see SOF_MEM_FLAG_…
bytes – [in] Size in bytes to allocate.

Returns:

Pointer to the allocated memory block, or NULL on allocation failure.

void *rzalloc(uint32_t flags, size_t bytes)#

Allocate zero-initialized memory block with default natural alignment.

Allocates memory via rmalloc() and, if successful, zeroes the entire block with memset() before returning.

Parameters:

flags – [in] Memory allocation flags, see SOF_MEM_FLAG_…
bytes – [in] Size in bytes to allocate.

Returns:

Pointer to zero-initialized memory block, or NULL on allocation failure.

void *rballoc_align(uint32_t flags, size_t bytes, uint32_t alignment)#

Allocate runtime stream buffer with explicit alignment.

Runtime buffer allocator designed for audio stream buffers. Unlike rmalloc_align(), rballoc_align() actively prioritizes the Virtual Memory Heap (VMH / virtual_buffers_heap) when CONFIG_VIRTUAL_HEAP is enabled to preserve internal SRAM. Supports SOF_MEM_FLAG_L3 and SOF_MEM_FLAG_USER_SHARED_BUFFER. Respects SOF_MEM_FLAG_COHERENT for system and shared heaps, but note that the L3 heap path returns cached memory directly and does not support coherent uncached views.

Parameters:

flags – [in] Memory allocation flags, see SOF_MEM_FLAG_…
bytes – [in] Size in bytes to allocate.
alignment – [in] Required alignment in bytes.

Returns:

Pointer to allocated buffer, or NULL on allocation failure.

static inline void *rballoc(uint32_t flags, size_t bytes)#

Allocate runtime stream buffer aligned to platform data cache line size.

Helper calling rballoc_align() with alignment set to PLATFORM_DCACHE_ALIGN.

Parameters:

flags – [in] Memory allocation flags, see SOF_MEM_FLAG_…
bytes – [in] Size in bytes to allocate.

Returns:

Pointer to allocated buffer aligned to cache line, or NULL on failure.

void rfree(void *ptr)#

Free memory block allocated by SOF RTOS allocators.

Unified memory deallocator. Automatically determines the origin heap (L3 heap, Virtual Memory Heap, shared buffer heap, or system heap) using address boundary checks and returns memory to the respective pool. Passing a NULL pointer is safely treated as a no-op.

Parameters:

ptr – [inout] Pointer to the memory block to free (can be NULL).

void l3_heap_save(void)#

Save and flush L3 heap state and metadata across DSP reset or power gating.

Flushes dirty cache lines for the L3 heap region and copies metadata into preserved storage to ensure data persistence across low-power reset cycles.

void *sof_heap_alloc(struct k_heap *heap, uint32_t flags, size_t bytes, size_t alignment)#

Allocate memory from a specified Zephyr heap or default system heap.

Parameters:

heap – [inout] Target Zephyr k_heap (or NULL to let implementation choose).
flags – [in] Memory allocation flags (SOF_MEM_FLAG_…).
bytes – [in] Size in bytes to allocate.
alignment – [in] Required memory alignment in bytes.

Returns:

Pointer to allocated buffer, or NULL on allocation failure.

void sof_heap_free(struct k_heap *heap, void *addr)#

Free memory allocated via sof_heap_alloc().

Parameters:

heap – [inout] Target Zephyr k_heap.
addr – [inout] Address of allocated buffer to free.

struct k_heap *sof_sys_heap_get(void)#

Get the system kernel heap descriptor.

Returns:: Pointer to the global system k_heap structure (sof_heap), or NULL in unit test mode.

struct k_heap *sof_sys_user_heap_get(void)#

Get the heap object to use for audio application allocations.

Returns zephyr_ll_user_heap() when CONFIG_SOF_USERSPACE_LL is enabled, or NULL to allow sof_heap_alloc() to pick the default heap.

Note

Audio processing modules should use mod_alloc() instead.

Returns:: Pointer to application k_heap, or NULL for default heap selection.

static inline void heap_trace_all(int force)#

Trace and log memory allocation statistics across all active heaps.

Deprecated:: No-op stub. Heap diagnostics are tracked via Zephyr runtime statistics (CONFIG_SYS_HEAP_RUNTIME_STATS), IPC4 telemetry, and VMH diagnostics (vmh_log_stats()).

Parameters:

force – [in] Force dumping heap trace even if logging threshold is not met.

uintptr_t get_shared_buffer_heap_start(void)#

Returns the start address of shared memory heap for buffers.

Returns:: Pointer address to shared memory heap start.

size_t get_shared_buffer_heap_size(void)#

Returns the total size of shared memory heap for buffers.

Returns:: Total size of shared memory heap in bytes.

static inline void *sof_ctx_alloc(struct mod_alloc_ctx *ctx, uint32_t flags, size_t size, size_t alignment)#

Allocate memory from an allocation context.

When the context has an associated vregion, allocates from the vregion interim partition using vregion_alloc_coherent_align() (if SOF_MEM_FLAG_COHERENT is set) or vregion_alloc_align(). When no vregion is attached, falls back to sof_heap_alloc().

Parameters:

ctx – [inout] Allocation context (heap + optional vregion).
flags – [in] Allocation flags (SOF_MEM_FLAG_*).
size – [in] Size in bytes to allocate.
alignment – [in] Required alignment in bytes.

Returns:

Pointer to allocated memory, or NULL on failure.

static inline void *sof_ctx_zalloc(struct mod_alloc_ctx *ctx, uint32_t flags, size_t size, size_t alignment)#

Allocate zero-initialized memory from an allocation context.

Allocates memory via sof_ctx_alloc() and clears it with memset() if successful.

Parameters:

ctx – [inout] Allocation context.
flags – [in] Allocation flags (SOF_MEM_FLAG_*).
size – [in] Size in bytes to allocate.
alignment – [in] Required alignment in bytes.

Returns:

Pointer to zero-initialized allocated memory, or NULL on failure.

static inline void sof_ctx_free(struct mod_alloc_ctx *ctx, void *ptr)#

Free memory allocated from an allocation context.

If the context contains a vregion, frees via vregion_free(); otherwise delegates to sof_heap_free(). Passing a NULL pointer is safely treated as a no-op.

Parameters:

ctx – [inout] Allocation context.
ptr – [inout] Pointer to memory to free (can be NULL).

bool ll_sch_is_current(void)#

struct vmh_heap *vmh_init_heap(const struct vmh_heap_config *cfg, bool allocating_continuously)#

Initialize a virtual memory heap with the given bundle configuration.

Parameters:

cfg – [in] Pointer to heap bundle configuration.
allocating_continuously – [in] If true, allows allocations to span a contiguous run of VMH block slots within a bundle; does not guarantee contiguous physical backing pages.

Returns:

Pointer to initialized vmh_heap, or NULL on failure.

void *vmh_alloc(struct vmh_heap *heap, uint32_t alloc_size)#

Allocate a memory block from the virtual memory heap.

Parameters:

heap – [inout] Pointer to target vmh_heap instance.
alloc_size – [in] Allocation size in bytes.

Returns:

Pointer to allocated buffer, or NULL on failure.

int vmh_free_heap(struct vmh_heap *heap)#

Destroy a virtual memory heap and unmap all backing pages.

Parameters:

heap – [inout] Pointer to vmh_heap instance to destroy.

Returns:

0 on success, negative error code on failure.

int vmh_free(struct vmh_heap *heap, void *ptr)#

Free a memory block previously allocated from a virtual memory heap.

Parameters:

heap – [inout] Pointer to vmh_heap instance.
ptr – [inout] Pointer to memory block to free.

Returns:

0 on success, negative error code on failure.

void vmh_get_default_heap_config(const struct sys_mm_drv_region *region, struct vmh_heap_config *cfg)#

Generate a default heap partition configuration for a memory driver region.

Parameters:

region – [in] Driver region describing base and size.
cfg – [out] Destination configuration structure to populate.

static inline bool vmh_is_ptr_in_memory_range(uintptr_t ptr, uintptr_t range_start, size_t range_size)#

Checks if ptr is in range of given memory range.

Parameters:

ptr – [in] Checked pointer address.
range_start – [in] Start of checked memory range.
range_size – [in] Size of checked memory range in bytes.

Return values:

false – if no overlap detected.
true – if any overlap detected.

void *vpage_alloc(unsigned int pages)#

Allocate contiguous virtual pages.

Allocates a specified number of contiguous virtual memory pages by mapping physical backing pages into the DSP page table.

Parameters:

pages – [in] Number of pages (typically 4KB per page) to allocate.

Returns:

Pointer to the allocated virtual memory region, or NULL on failure.

void vpage_free(void *ptr)#

Free virtual pages.

Frees previously allocated virtual memory pages and unmaps them from the page table.

Parameters:

ptr – [inout] Pointer to the virtual memory pages to free.

struct coherent#

#include <src/include/sof/coherent.h>

Header embedded at start of multi-core shared memory objects for cache coherence.

Ensures cache line alignment and synchronizes cached/uncached state transitions across DSP cores. Must only be manipulated via coherent_* APIs.

Public Members

struct k_spinlock lock#: Spinlock synchronizing multi-core access.

k_spinlock_key_t key#: Spinlock key storing interrupt flags.

struct k_mutex mutex#: Mutex synchronizing thread-level access when sleeping is allowed.

union coherent

uint8_t sleep_allowed#: Non-zero if context allows sleeping/blocking mutex operations.

uint8_t shared#: Non-zero if object is shared across non-coherent cores.

uint16_t core#: Owner core ID when object is not shared.

struct list_item list#: Node for coherent tracking list iteration.

struct mod_alloc_ctx#

#include <zephyr/include/rtos/alloc.h>

Module and pipeline allocation context aggregating a Zephyr heap and optional virtual region.

Public Members

struct k_heap *heap#: Underlying Zephyr heap descriptor.

struct vregion *vreg#: Optional virtual region for interim/lifetime partitioning.

struct vmh_block_bundle_descriptor#

#include <zephyr/include/sof/lib/regions_mm.h>

Descriptor for a power-of-2 block size bundle in a virtual memory heap.

Public Members

size_t block_size#: Size of memory block in bytes.

size_t number_of_blocks#: Number of memory blocks in this bundle.

struct vmh_heap_config#

#include <zephyr/include/sof/lib/regions_mm.h>

This is a struct that aggregates vmh_block_bundle_descriptor to create one cfg that can be passed to heap initiation.

Provided config size must be physical page aligned so it will not overlap in physical space with other heaps during mapping. So every block has to have its overall size aligned to CONFIG_MM_DRV_PAGE_SIZE

Public Members

struct vmh_block_bundle_descriptor block_bundles_table[MAX_MEMORY_ALLOCATORS_COUNT]#