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

Files
file	coherent.h
	Cache-coherent multi-core shared memory access abstractions.

file	fast-get.h
	Dynamic SRAM staging and cache mechanisms for cold DRAM-resident modules.

file	vregion.h
	Pre-allocated contiguous virtual memory region allocator (lifetime vs interim).

file	alloc.h
	Memory allocation API, zones, heaps, and alignment utilities.

file	memory.h
	Memory attributes, cold/hot execution paths, and platform memory inclusions.

file	mm_heap.h
	Legacy XTOS heap compatibility header.

file	regions_mm.h
	Virtual Memory Heap (VMH) and multi-block region allocator API.

file	vpage.h
	Virtual Page Allocator API for mapping contiguous memory pages.

Data Structures
struct	coherent
	Header embedded at start of multi-core shared memory objects for cache coherence. More...

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

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

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

Macros
#define	__coherent __aligned(PLATFORM_DCACHE_ALIGN)
	Cache line alignment specifier for coherent shared memory objects.

#define	ADDR_IS_INCOHERENT(_c)

#define	ADDR_IS_COHERENT(_c)

#define	CORE_CHECK_STRUCT_FIELD

#define	CORE_CHECK_STRUCT_INIT(_c, is_shared)

#define	CORE_CHECK_STRUCT(_c)

#define	CHECK_COHERENT_CORE(_c)

#define	CHECK_ISR() __ASSERT(!k_is_in_isr(), "Attempt to sleep in ISR!")

#define	CHECK_SLEEP(_c)

#define	CHECK_ATOMIC(_c)

#define	coherent_init(type, member)
	Allocate and initialize a coherent shared object with spinlock protection.

#define	coherent_shared(object, member)
	Mark an allocated coherent object as actively shared across multiple DSP cores.

#define	coherent_init_thread(type, member)
	Allocate and initialize a coherent shared object with mutex protection for thread context.

#define	coherent_shared_thread(object, member)
	Mark a thread-capable coherent object as shared across multiple DSP cores.

#define	coherent_free(object, member)
	Invalidate cache and free a coherent shared memory object.

#define	coherent_free_thread coherent_free
	Free a thread-capable coherent shared memory object.

#define	is_coherent_shared(object, member) ((object)->member.shared)
	Query whether a coherent object is configured for multi-core shared mode.

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

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

#define	dbg_path_hot_start_watching() do {} while (0)

#define	dbg_path_hot_stop_watching() do {} while (0)

#define	dbg_path_hot_confirm() do {} while (0)

#define	dbg_path_cold_enter() do {} while (0)

#define	assert_can_be_cold() do {} while (0)
	Assert that the current function is not executing from a latency-critical LL thread.

#define	VIRTUAL_REGION_SHARED_HEAP_ATTR 1U
	Region attribute for shared virtual memory heap.

#define	VIRTUAL_REGION_LLEXT_LIBRARIES_ATTR 2U
	Region attribute for loadable LLEXT libraries.

#define	VIRTUAL_REGION_VPAGES_ATTR 3U
	Region attribute for virtual page allocator.

#define	MAX_MEMORY_ALLOCATORS_COUNT 10
	Maximum amount of memory block allocators in one heap.

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

Enumerations
enum	vregion_mem_type { VREGION_MEM_TYPE_INTERIM , VREGION_MEM_TYPE_LIFETIME , VREGION_MEM_TYPE_INVALID }
	Memory allocation modes within a virtual memory region. More...

Functions
static struct coherent *	coherent_acquire (struct coherent *c, const size_t size)
	Acquire exclusive access to a cache-coherent shared object in atomic/spinlock context.

static void	coherent_release (struct coherent *c, const size_t size)
	Release exclusive access to a cache-coherent shared object in atomic/spinlock context.

static void *	__coherent_init (size_t offset, const size_t size)
	Internal helper to allocate and initialize a coherent shared object.

static void	__coherent_shared (struct coherent *c, const size_t size)
	Internal helper to mark an allocated coherent object as actively shared.

static 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.

static void	coherent_release_thread (struct coherent *c, const size_t size)
	Release exclusive access to a cache-coherent shared object in thread/mutex context.

static void *	__coherent_init_thread (size_t offset, const size_t size)
	Internal helper to allocate and initialize a thread-capable coherent shared object.

static void	__coherent_shared_thread (struct coherent *c, const size_t size)
	Internal helper to mark a thread-capable coherent object as actively shared.

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

static 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.

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.

void	vregion_set_interim (struct vregion *vr)
	Switch virtual region allocations to interim mode.

struct vregion *	vregion_get (struct vregion *vr)
	Increment virtual region's user count.

struct vregion *	vregion_put (struct vregion *vr)
	Decrement virtual region's user count or destroy it.

void *	vregion_alloc_align (struct vregion *vr, size_t size, size_t alignment)
	Allocate aligned memory from the specified virtual region.

void *	vregion_alloc_coherent_align (struct vregion *vr, size_t size, size_t alignment)
	Allocate aligned coherent (uncached) memory from the specified virtual region.

static void *	vregion_alloc (struct vregion *vr, size_t size)
	Allocate memory from the specified virtual region.

static void *	vregion_alloc_coherent (struct vregion *vr, size_t size)
	Allocate naturally aligned coherent (uncached) memory from the specified virtual region.

void	vregion_free (struct vregion vr, void ptr)
	Free memory allocated from the specified virtual region.

void	vregion_info (struct vregion *vr)
	Log virtual region memory usage.

void	vregion_mem_info (struct vregion vr, size_t size, uintptr_t *start)
	Retrieve virtual region memory base address and size.

bool	vregion_verify (struct vregion *vr)
	Validate that a virtual region handle is genuine and isolated from user space.

void *	rmalloc_align (uint32_t flags, size_t bytes, uint32_t alignment)
	Allocate memory block with explicit alignment and heap selection flags.

void *	rmalloc (uint32_t flags, size_t bytes)
	Allocate memory block with default natural alignment.

void *	rzalloc (uint32_t flags, size_t bytes)
	Allocate zero-initialized memory block with default natural alignment.

void *	rballoc_align (uint32_t flags, size_t bytes, uint32_t alignment)
	Allocate runtime stream buffer with explicit alignment.

static void *	rballoc (uint32_t flags, size_t bytes)
	Allocate runtime stream buffer aligned to platform data cache line size.

void	rfree (void *ptr)
	Free memory block allocated by SOF RTOS allocators.

void	l3_heap_save (void)
	Save and flush L3 heap state and metadata across DSP reset or power gating.

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.

void	sof_heap_free (struct k_heap heap, void addr)
	Free memory allocated via sof_heap_alloc().

struct k_heap *	sof_sys_heap_get (void)
	Get the system kernel heap descriptor.

struct k_heap *	sof_sys_user_heap_get (void)
	Get the heap object to use for audio application allocations.

static void	heap_trace_all (int force)
	Trace and log memory allocation statistics across all active heaps.

uintptr_t	get_shared_buffer_heap_start (void)
	Returns the start address of shared memory heap for buffers.

size_t	get_shared_buffer_heap_size (void)
	Returns the total size of shared memory heap for buffers.

static void *	sof_ctx_alloc (struct mod_alloc_ctx *ctx, uint32_t flags, size_t size, size_t alignment)
	Allocate memory from an allocation context.

static 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.

static void	sof_ctx_free (struct mod_alloc_ctx ctx, void ptr)
	Free memory allocated from an allocation context.

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.

void *	vmh_alloc (struct vmh_heap *heap, uint32_t alloc_size)
	Allocate a memory block from the virtual memory heap.

int	vmh_free_heap (struct vmh_heap *heap)
	Destroy a virtual memory heap and unmap all backing pages.

int	vmh_free (struct vmh_heap heap, void ptr)
	Free a memory block previously allocated from a virtual memory heap.

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.

static 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.

void *	vpage_alloc (unsigned int pages)
	Allocate contiguous virtual pages.

void	vpage_free (void *ptr)
	Free virtual pages.

Allocation flags
#define	SOF_MEM_FLAG_DMA BIT(2)
	Allocate memory accessible by DMA controllers (e.g.

#define	SOF_MEM_FLAG_NO_COPY BIT(3)
	realloc() skips copying the original content.

#define	SOF_MEM_FLAG_COHERENT BIT(4)
	Allocate uncached / coherent memory address.

#define	SOF_MEM_FLAG_L3 BIT(5)
	Allocate from L3 address space (IMR / external DRAM heap).

#define	SOF_MEM_FLAG_LOW_POWER BIT(6)
	Allocate Low power memory address.

#define	SOF_MEM_FLAG_KERNEL BIT(7)
	Base allocation flag denoting memory allocated for kernel-space data structures.

#define	SOF_MEM_FLAG_USER BIT(8)
	Base allocation flag denoting memory allocated for user-space threads and module execution.

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

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

Detailed Description

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.

Macro Definition Documentation

◆ __coherent

#define __coherent __aligned(PLATFORM_DCACHE_ALIGN)

Cache line alignment specifier for coherent shared memory objects.

◆ __cold

#define __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

#define __cold_rodata

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

◆ ADDR_IS_COHERENT

#define ADDR_IS_COHERENT ( _c )

◆ ADDR_IS_INCOHERENT

#define ADDR_IS_INCOHERENT ( _c )

◆ assert_can_be_cold

#define assert_can_be_cold ( ) do {} while (0)

Assert that the current function is not executing from a latency-critical LL thread.

◆ CHECK_ATOMIC

#define CHECK_ATOMIC ( _c )

Value:

__ASSERT(!(_c)->sleep_allowed, \

"This context has been initialized for sleeping!")

◆ CHECK_COHERENT_CORE

#define CHECK_COHERENT_CORE ( _c )

◆ CHECK_ISR

#define CHECK_ISR ( ) __ASSERT(!k_is_in_isr(), "Attempt to sleep in ISR!")

◆ CHECK_SLEEP

#define CHECK_SLEEP ( _c )

Value:

__ASSERT((_c)->sleep_allowed, \

"This context hasn't been initialized for sleeping!")

◆ coherent_free

#define coherent_free	(	object,
		member
	)

Value:

    do {                                    \
        /* assert if someone passes a cache address in here. */     \
        ADDR_IS_COHERENT(object);                   \
        /* wtb and inv local data to coherent object */         \
        dcache_writeback_invalidate_region(uncache_to_cache(object),    \
                           sizeof(*object));        \
        rfree(object);                          \
    } while (0)

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

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

◆ coherent_free_thread

#define coherent_free_thread coherent_free

Free a thread-capable coherent shared memory object.

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

Parameters

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

◆ coherent_init

#define coherent_init	(	type,
		member
	)

Value:

__coherent_init(offsetof(type, member), \

sizeof(type))

__coherent_init

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

Internal helper to allocate and initialize a coherent shared object.

Definition coherent.h:224

type

uint32_t type

Message type, symmetric to the incoming request.

Definition header.h:8

Allocate and initialize a coherent shared object with spinlock protection.

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

Parameters

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

◆ coherent_init_thread

#define coherent_init_thread	(	type,
		member
	)

Value:

__coherent_init_thread(offsetof(type, member), \

sizeof(type))

__coherent_init_thread

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

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

Definition coherent.h:371

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

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

◆ coherent_shared

#define coherent_shared	(	object,
		member
	)

Value:

__coherent_shared(&(object)->member, \

sizeof(*object))

__coherent_shared

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

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

Definition coherent.h:272

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

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

Parameters

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

◆ coherent_shared_thread

#define coherent_shared_thread	(	object,
		member
	)

Value:

__coherent_shared_thread(&(object)->member, \

sizeof(*object))

__coherent_shared_thread

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

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

Definition coherent.h:415

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

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

◆ CORE_CHECK_STRUCT

#define CORE_CHECK_STRUCT ( _c )

◆ CORE_CHECK_STRUCT_FIELD

#define CORE_CHECK_STRUCT_FIELD

◆ CORE_CHECK_STRUCT_INIT

#define CORE_CHECK_STRUCT_INIT	(	_c,
		is_shared
	)

◆ dbg_path_cold_enter

#define dbg_path_cold_enter ( ) do {} while (0)

◆ dbg_path_hot_confirm

#define dbg_path_hot_confirm ( ) do {} while (0)

◆ dbg_path_hot_start_watching

#define dbg_path_hot_start_watching ( ) do {} while (0)

◆ dbg_path_hot_stop_watching

#define dbg_path_hot_stop_watching ( ) do {} while (0)

◆ DEFAULT_CONFIG_ALOCATORS_COUNT

#define DEFAULT_CONFIG_ALOCATORS_COUNT 5

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

◆ is_coherent_shared

#define is_coherent_shared	(	object,
		member
	)	((object)->member.shared)

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

Parameters

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

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

◆ MAX_MEMORY_ALLOCATORS_COUNT

#define MAX_MEMORY_ALLOCATORS_COUNT 10

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).

◆ SOF_MEM_FLAG_COHERENT

#define SOF_MEM_FLAG_COHERENT BIT(4)

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_DMA

#define SOF_MEM_FLAG_DMA BIT(2)

Allocate memory accessible by DMA controllers (e.g.

Host or DSP DMA).

◆ SOF_MEM_FLAG_KERNEL

#define SOF_MEM_FLAG_KERNEL BIT(7)

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

◆ SOF_MEM_FLAG_L3

#define SOF_MEM_FLAG_L3 BIT(5)

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_LARGE_BUFFER

#define SOF_MEM_FLAG_LARGE_BUFFER BIT(10)

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

◆ SOF_MEM_FLAG_LOW_POWER

#define SOF_MEM_FLAG_LOW_POWER BIT(6)

Allocate Low power memory address.

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

◆ SOF_MEM_FLAG_NO_COPY

#define SOF_MEM_FLAG_NO_COPY BIT(3)

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_USER

#define SOF_MEM_FLAG_USER BIT(8)

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

◆ SOF_MEM_FLAG_USER_SHARED_BUFFER

#define SOF_MEM_FLAG_USER_SHARED_BUFFER BIT(9)

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

◆ VIRTUAL_REGION_LLEXT_LIBRARIES_ATTR

#define VIRTUAL_REGION_LLEXT_LIBRARIES_ATTR 2U

Region attribute for loadable LLEXT libraries.

◆ VIRTUAL_REGION_SHARED_HEAP_ATTR

#define VIRTUAL_REGION_SHARED_HEAP_ATTR 1U

Region attribute for shared virtual memory heap.

◆ VIRTUAL_REGION_VPAGES_ATTR

#define VIRTUAL_REGION_VPAGES_ATTR 3U

Region attribute for virtual page allocator.

Enumeration Type Documentation

◆ vregion_mem_type

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).

Enumerator

VREGION_MEM_TYPE_INTERIM

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

large config set/get, controls).

VREGION_MEM_TYPE_LIFETIME

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

topology, module instances).

VREGION_MEM_TYPE_INVALID

Invalid memory type indicating initialization error or exhaustion.

Function Documentation

◆ __coherent_init()

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

inlinestatic

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

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

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

◆ __coherent_init_thread()

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

inlinestatic

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

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

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

◆ __coherent_shared()

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

inlinestatic

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

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

◆ __coherent_shared_thread()

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

inlinestatic

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

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

◆ coherent_acquire()

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

inlinestatic

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

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

Returns: Pointer to the cached memory view of the coherent object.

◆ coherent_acquire_thread()

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

inlinestatic

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

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

Returns: Pointer to the cached memory view of the coherent object.

◆ coherent_release()

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

inlinestatic

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

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

◆ coherent_release_thread()

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

inlinestatic

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

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

◆ fast_get()

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

inlinestatic

◆ fast_put()

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

inlinestatic

◆ get_shared_buffer_heap_size()

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.

◆ get_shared_buffer_heap_start()

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.

◆ heap_trace_all()

static void heap_trace_all ( int force )

inlinestatic

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

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

◆ l3_heap_save()

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.

◆ ll_sch_is_current()

bool ll_sch_is_current ( void )

◆ rballoc()

static void * rballoc	(	uint32_t	flags,
		size_t	bytes
	)

inlinestatic

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

Helper calling rballoc_align() with alignment set to PLATFORM_DCACHE_ALIGN.

Parameters

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

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

◆ rballoc_align()

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

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

Returns: Pointer to allocated buffer, or NULL on allocation failure.

◆ rfree()

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

[in,out] ptr Pointer to the memory block to free (can be NULL).

◆ rmalloc()

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

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

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

◆ rmalloc_align()

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

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

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

◆ rzalloc()

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

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

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

◆ sof_ctx_alloc()

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

inlinestatic

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

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

Returns: Pointer to allocated memory, or NULL on failure.

◆ sof_ctx_free()

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

inlinestatic

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

[in,out]	ctx	Allocation context.
[in,out]	ptr	Pointer to memory to free (can be NULL).

◆ sof_ctx_zalloc()

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

inlinestatic

Allocate zero-initialized memory from an allocation context.

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

Parameters

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

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

◆ sof_heap_alloc()

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

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

Returns: Pointer to allocated buffer, or NULL on allocation failure.

◆ sof_heap_free()

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

Free memory allocated via sof_heap_alloc().

Parameters

[in,out]	heap	Target Zephyr k_heap.
[in,out]	addr	Address of allocated buffer to free.

◆ sof_sys_heap_get()

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.

◆ sof_sys_user_heap_get()

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.

◆ vmh_alloc()

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

Allocate a memory block from the virtual memory heap.

Parameters

[in,out]	heap	Pointer to target vmh_heap instance.
[in]	alloc_size	Allocation size in bytes.

Returns: Pointer to allocated buffer, or NULL on failure.

◆ vmh_free()

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

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

Parameters

[in,out]	heap	Pointer to vmh_heap instance.
[in,out]	ptr	Pointer to memory block to free.

Returns: 0 on success, negative error code on failure.

◆ vmh_free_heap()

int vmh_free_heap ( struct vmh_heap * heap )

Destroy a virtual memory heap and unmap all backing pages.

Parameters

[in,out] heap Pointer to vmh_heap instance to destroy.

Returns: 0 on success, negative error code on failure.

◆ vmh_get_default_heap_config()

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

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

◆ vmh_init_heap()

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

[in]	cfg	Pointer to heap bundle configuration.
[in]	allocating_continuously	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.

◆ vmh_is_ptr_in_memory_range()

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

inlinestatic

Checks if ptr is in range of given memory range.

Parameters

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

Return values

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

◆ vpage_alloc()

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

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

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

◆ vpage_free()

void vpage_free ( void * ptr )

Free virtual pages.

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

Parameters

[in,out] ptr Pointer to the virtual memory pages to free.

◆ vregion_alloc()

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

inlinestatic

Allocate memory from the specified virtual region.

Parameters

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

Returns: Pointer to the allocated memory, or NULL on failure.

◆ vregion_alloc_align()

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

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

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

◆ vregion_alloc_coherent()

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

inlinestatic

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

Parameters

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

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

◆ vregion_alloc_coherent_align()

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

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

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

◆ vregion_create()

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

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

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

◆ vregion_create_map()

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

[out]	vreg_start	Output pointer receiving the virtual start address of the region.
[in,out]	vreg_size	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.

◆ vregion_free()

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

[in,out]	vr	Pointer to the virtual region instance.
[in,out]	ptr	Pointer to the memory to free.

◆ vregion_get()

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

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

Returns: struct vregion* Pointer to the virtual region instance.

◆ vregion_info()

void vregion_info ( struct vregion * vr )

Log virtual region memory usage.

Parameters

[in] vr Pointer to the virtual region instance.

◆ vregion_mem_info()

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

Retrieve virtual region memory base address and size.

Parameters

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

◆ vregion_put()

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

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

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

◆ vregion_set_interim()

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

[in] vr Pointer to the virtual region instance.

◆ vregion_verify()

bool vregion_verify ( struct vregion * vr )

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

Parameters

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

Returns: True if handle is valid and secure, false otherwise.

Files

Data Structures

Macros

Enumerations

Functions

Allocation flags

Detailed Description

Macro Definition Documentation

◆ __coherent

◆ __cold

◆ __cold_rodata

◆ ADDR_IS_COHERENT

◆ ADDR_IS_INCOHERENT

◆ assert_can_be_cold

◆ CHECK_ATOMIC

◆ CHECK_COHERENT_CORE

◆ CHECK_ISR

◆ CHECK_SLEEP

◆ coherent_free

◆ coherent_free_thread

◆ coherent_init

◆ coherent_init_thread

◆ coherent_shared

◆ coherent_shared_thread

◆ CORE_CHECK_STRUCT

◆ CORE_CHECK_STRUCT_FIELD

◆ CORE_CHECK_STRUCT_INIT

◆ dbg_path_cold_enter

◆ dbg_path_hot_confirm

◆ dbg_path_hot_start_watching

◆ dbg_path_hot_stop_watching

◆ DEFAULT_CONFIG_ALOCATORS_COUNT

◆ is_coherent_shared

◆ MAX_MEMORY_ALLOCATORS_COUNT

◆ SOF_MEM_FLAG_COHERENT

◆ SOF_MEM_FLAG_DMA

◆ SOF_MEM_FLAG_KERNEL

◆ SOF_MEM_FLAG_L3

◆ SOF_MEM_FLAG_LARGE_BUFFER

◆ SOF_MEM_FLAG_LOW_POWER

◆ SOF_MEM_FLAG_NO_COPY

◆ SOF_MEM_FLAG_USER

◆ SOF_MEM_FLAG_USER_SHARED_BUFFER

◆ VIRTUAL_REGION_LLEXT_LIBRARIES_ATTR

◆ VIRTUAL_REGION_SHARED_HEAP_ATTR

◆ VIRTUAL_REGION_VPAGES_ATTR

Enumeration Type Documentation

◆ vregion_mem_type

Function Documentation

◆ __coherent_init()

◆ __coherent_init_thread()

◆ __coherent_shared()

◆ __coherent_shared_thread()

◆ coherent_acquire()

◆ coherent_acquire_thread()

◆ coherent_release()

◆ coherent_release_thread()

◆ fast_get()

◆ fast_put()

◆ get_shared_buffer_heap_size()

◆ get_shared_buffer_heap_start()

◆ heap_trace_all()

◆ l3_heap_save()

◆ ll_sch_is_current()

◆ rballoc()

◆ rballoc_align()

◆ rfree()

◆ rmalloc()

◆ rmalloc_align()

◆ rzalloc()

◆ sof_ctx_alloc()

◆ sof_ctx_free()

◆ sof_ctx_zalloc()

◆ sof_heap_alloc()

◆ sof_heap_free()

◆ sof_sys_heap_get()

◆ sof_sys_user_heap_get()

◆ vmh_alloc()

◆ vmh_free()

◆ vmh_free_heap()