Heap capability flags, heap info queries, and STL-compatible allocators. More...

Namespaces
namespace	idfxx

Classes
struct	idfxx::heap_info
	Heap region statistics. More...

struct	idfxx::caps_allocator< T, Caps, Alignment >
	STL-compatible allocator for capability-based memory regions. More...

struct	idfxx::heap_region
	Information about a heap region, passed to heap walk callbacks. More...

struct	idfxx::heap_block
	Information about a single heap block, passed to heap walk callbacks. More...

Typedefs
template<typename T >
using	idfxx::dram_allocator = caps_allocator< T, memory_caps::dram >
	STL-compatible allocator for internal DRAM.

template<typename T >
using	idfxx::spiram_allocator = caps_allocator< T, memory_caps::spiram >
	STL-compatible allocator for external PSRAM (SPI RAM).

template<typename T >
using	idfxx::dma_allocator = caps_allocator< T, memory_caps::dma >
	STL-compatible allocator for DMA-capable memory.

template<typename T , size_t Alignment>
using	idfxx::aligned_dram_allocator = caps_allocator< T, memory_caps::dram, Alignment >
	STL-compatible aligned allocator for internal DRAM.

template<typename T , size_t Alignment>
using	idfxx::aligned_spiram_allocator = caps_allocator< T, memory_caps::spiram, Alignment >
	STL-compatible aligned allocator for external PSRAM (SPI RAM).

template<typename T , size_t Alignment>
using	idfxx::aligned_dma_allocator = caps_allocator< T, memory_caps::dma, Alignment >
	STL-compatible aligned allocator for DMA-capable memory.

Enumerations
enum class	idfxx::memory_caps : uint32_t { idfxx::memory_caps::exec = MALLOC_CAP_EXEC , idfxx::memory_caps::access_32bit = MALLOC_CAP_32BIT , idfxx::memory_caps::access_8bit = MALLOC_CAP_8BIT , idfxx::memory_caps::dma = MALLOC_CAP_DMA , idfxx::memory_caps::spiram = MALLOC_CAP_SPIRAM , idfxx::memory_caps::internal = MALLOC_CAP_INTERNAL , idfxx::memory_caps::default_heap = MALLOC_CAP_DEFAULT , idfxx::memory_caps::iram = MALLOC_CAP_IRAM_8BIT , idfxx::memory_caps::retention = MALLOC_CAP_RETENTION , idfxx::memory_caps::rtc = MALLOC_CAP_RTCRAM , idfxx::memory_caps::dma_desc_ahb = MALLOC_CAP_DMA_DESC_AHB , idfxx::memory_caps::dma_desc_axi = MALLOC_CAP_DMA_DESC_AXI , idfxx::memory_caps::cache_aligned = MALLOC_CAP_CACHE_ALIGNED , idfxx::memory_caps::dram = internal \| access_8bit }
	Memory capability flags for heap allocations. More...

Functions
size_t	idfxx::heap_total_size (flags< memory_caps > caps) noexcept
	Returns the total size of heap regions matching the given capabilities.

size_t	idfxx::heap_free_size (flags< memory_caps > caps) noexcept
	Returns the current free size of heap regions matching the given capabilities.

size_t	idfxx::heap_largest_free_block (flags< memory_caps > caps) noexcept
	Returns the largest free block in heap regions matching the given capabilities.

size_t	idfxx::heap_minimum_free_size (flags< memory_caps > caps) noexcept
	Returns the minimum free size since boot for heap regions matching the given capabilities.

heap_info	idfxx::get_heap_info (flags< memory_caps > caps) noexcept
	Returns detailed heap statistics for regions matching the given capabilities.

void *	idfxx::heap_malloc (size_t size, flags< memory_caps > caps) noexcept
	Allocates memory from heap regions matching the given capabilities.

void *	idfxx::heap_calloc (size_t n, size_t size, flags< memory_caps > caps) noexcept
	Allocates zero-initialized memory from heap regions matching the given capabilities.

void *	idfxx::heap_realloc (void *ptr, size_t size, flags< memory_caps > caps) noexcept
	Reallocates memory from heap regions matching the given capabilities.

void	idfxx::heap_free (void *ptr) noexcept
	Frees memory previously allocated by heap allocation functions.

void *	idfxx::heap_aligned_alloc (size_t alignment, size_t size, flags< memory_caps > caps) noexcept
	Allocates aligned memory from heap regions matching the given capabilities.

void *	idfxx::heap_aligned_calloc (size_t alignment, size_t n, size_t size, flags< memory_caps > caps) noexcept
	Allocates aligned, zero-initialized memory from heap regions matching the given capabilities.

template<typename T , typename U , flags< memory_caps > Caps, size_t Alignment>
constexpr bool	idfxx::operator== (const caps_allocator< T, Caps, Alignment > &, const caps_allocator< U, Caps, Alignment > &) noexcept
	Equality comparison for caps_allocator.

template<typename F >
void	idfxx::heap_walk (flags< memory_caps > caps, F &&walker)
	Walk all heap blocks in regions matching the given capabilities.

template<typename F >
void	idfxx::heap_walk_all (F &&walker)
	Walk all heap blocks across all heaps.

bool	idfxx::heap_check_integrity (flags< memory_caps > caps, bool print_errors=false) noexcept
	Check integrity of all heaps with the given capabilities.

bool	idfxx::heap_check_integrity_all (bool print_errors=false) noexcept
	Check integrity of all heaps.

void	idfxx::heap_dump (flags< memory_caps > caps) noexcept
	Dump the structure of all heaps with matching capabilities.

void	idfxx::heap_dump_all () noexcept
	Dump the structure of all heaps.

Variables
template<>
constexpr bool	idfxx::enable_flags_operators< memory_caps > = true

Detailed Description

Heap capability flags, heap info queries, and STL-compatible allocators.

Provides composable memory capability flags via memory_caps, heap query functions, heap walking and integrity checking, and allocators (including aligned variants) for internal DRAM, external PSRAM, and DMA-capable memory that can be used with standard containers.

Typedef Documentation

◆ aligned_dma_allocator

template<typename T , size_t Alignment>

using idfxx::aligned_dma_allocator = typedef caps_allocator<T, memory_caps::dma, Alignment>

STL-compatible aligned allocator for DMA-capable memory.

Allocates DMA-capable memory with a guaranteed byte alignment.

Template Parameters

T	The type of object to allocate.
Alignment	Alignment in bytes (must be a power of two).

Definition at line 406 of file memory.hpp.

◆ aligned_dram_allocator

template<typename T , size_t Alignment>

using idfxx::aligned_dram_allocator = typedef caps_allocator<T, memory_caps::dram, Alignment>

STL-compatible aligned allocator for internal DRAM.

Allocates from internal DRAM with a guaranteed byte alignment.

Template Parameters

T	The type of object to allocate.
Alignment	Alignment in bytes (must be a power of two).

Definition at line 380 of file memory.hpp.

◆ aligned_spiram_allocator

template<typename T , size_t Alignment>

using idfxx::aligned_spiram_allocator = typedef caps_allocator<T, memory_caps::spiram, Alignment>

STL-compatible aligned allocator for external PSRAM (SPI RAM).

Allocates from external PSRAM with a guaranteed byte alignment.

Template Parameters

T	The type of object to allocate.
Alignment	Alignment in bytes (must be a power of two).

Note: Requires a device with external PSRAM and CONFIG_SPIRAM enabled.

Definition at line 394 of file memory.hpp.

◆ dma_allocator

template<typename T >

using idfxx::dma_allocator = typedef caps_allocator<T, memory_caps::dma>

STL-compatible allocator for DMA-capable memory.

Uses the ESP-IDF heap_caps API to allocate memory that is suitable for DMA transfers. Can be used with standard containers to create buffers for SPI, I2S, LCD, and other DMA-capable peripherals.

Template Parameters

T	The type of object to allocate.

Definition at line 368 of file memory.hpp.

◆ dram_allocator

template<typename T >

using idfxx::dram_allocator = typedef caps_allocator<T, memory_caps::dram>

STL-compatible allocator for internal DRAM.

Uses the ESP-IDF heap_caps API to allocate memory from internal DRAM with 8-bit access capability. Can be used with standard containers to ensure allocations come from internal memory rather than external PSRAM.

Template Parameters

T	The type of object to allocate.

Definition at line 339 of file memory.hpp.

◆ spiram_allocator

template<typename T >

using idfxx::spiram_allocator = typedef caps_allocator<T, memory_caps::spiram>

STL-compatible allocator for external PSRAM (SPI RAM).

Uses the ESP-IDF heap_caps API to allocate memory from external PSRAM. Can be used with standard containers to place large data structures in PSRAM, freeing internal DRAM for performance-critical or DMA-capable allocations.

Template Parameters

T	The type of object to allocate.

Note: Requires a device with external PSRAM and CONFIG_SPIRAM enabled.

Definition at line 355 of file memory.hpp.

Enumeration Type Documentation

◆ memory_caps

enum class idfxx::memory_caps : uint32_t

strong

Memory capability flags for heap allocations.

Composable flags that describe properties of memory regions. Use the bitwise operators provided by idfxx::flags<memory_caps> to combine multiple capabilities.

Used by components such as Task Component (for stack allocation) and Queue Component (for queue storage) to control memory placement, and by the heap query functions to filter heap statistics.

Note: spiram requires a device with external PSRAM and CONFIG_SPIRAM enabled.

Enumerator
exec	Executable memory.
access_32bit	32-bit aligned access
access_8bit	8/16/32-bit access
dma	DMA-capable memory.
spiram	External PSRAM.
internal	Internal memory.
default_heap	Default heap (same as malloc)
iram	IRAM with unaligned access.
retention	Retention DMA accessible.
rtc	RTC fast memory.
dma_desc_ahb	AHB DMA descriptor capable.
dma_desc_axi	AXI DMA descriptor capable.
cache_aligned	Cache-line aligned.
dram	Internal DRAM (8-bit accessible)

Definition at line 48 of file memory.hpp.

Function Documentation

◆ get_heap_info()

heap_info idfxx::get_heap_info ( flags< memory_caps > caps )

inlinenoexcept

Returns detailed heap statistics for regions matching the given capabilities.

Parameters

caps	Capability flags to filter heap regions.

Returns: A heap_info struct containing aggregated statistics.

Definition at line 140 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_aligned_alloc()

void * idfxx::heap_aligned_alloc	(	size_t	alignment,
		size_t	size,
		flags< memory_caps >	caps
	)

inlinenoexcept

Allocates aligned memory from heap regions matching the given capabilities.

Parameters

alignment	Alignment in bytes (must be a power of two).
size	Number of bytes to allocate.
caps	Capability flags to select heap regions.

Returns: Pointer to the aligned memory, or nullptr on failure.

Definition at line 218 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_aligned_calloc()

void * idfxx::heap_aligned_calloc	(	size_t	alignment,
		size_t	n,
		size_t	size,
		flags< memory_caps >	caps
	)

inlinenoexcept

Allocates aligned, zero-initialized memory from heap regions matching the given capabilities.

Parameters

alignment	Alignment in bytes (must be a power of two).
n	Number of elements to allocate.
size	Size of each element in bytes.
caps	Capability flags to select heap regions.

Returns: Pointer to the aligned, zero-initialized memory, or nullptr on failure.

Definition at line 233 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_calloc()

void * idfxx::heap_calloc	(	size_t	n,
		size_t	size,
		flags< memory_caps >	caps
	)

inlinenoexcept

Allocates zero-initialized memory from heap regions matching the given capabilities.

Parameters

n	Number of elements to allocate.
size	Size of each element in bytes.
caps	Capability flags to select heap regions.

Returns: Pointer to the zero-initialized memory, or nullptr on failure.

Definition at line 177 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_check_integrity()

bool idfxx::heap_check_integrity	(	flags< memory_caps >	caps,
		bool	print_errors = `false`
	)

inlinenoexcept

Check integrity of all heaps with the given capabilities.

Parameters

caps	Capability flags to filter heap regions.
print_errors	Print specific errors if heap corruption is found.

Returns: True if all matching heaps are valid, false if at least one is corrupt.

Definition at line 483 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_check_integrity_all()

bool idfxx::heap_check_integrity_all ( bool print_errors = false )

inlinenoexcept

Check integrity of all heaps.

Parameters

print_errors Print specific errors if heap corruption is found.

Returns: True if all heaps are valid, false if at least one is corrupt.

Definition at line 494 of file memory.hpp.

◆ heap_dump()

void idfxx::heap_dump ( flags< memory_caps > caps )

inlinenoexcept

Dump the structure of all heaps with matching capabilities.

Prints detailed information about every block in matching heaps to the serial console.

Parameters

caps	Capability flags to filter heap regions.

Definition at line 508 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_dump_all()

void idfxx::heap_dump_all ( )

inlinenoexcept

Dump the structure of all heaps.

Prints detailed information about every block in all heaps to the serial console.

Definition at line 518 of file memory.hpp.

◆ heap_free()

void idfxx::heap_free ( void * ptr )

inlinenoexcept

Frees memory previously allocated by heap allocation functions.

Accepts nullptr safely. Works for both regular and aligned allocations.

Parameters

ptr	Pointer to the memory to free, or `nullptr`.

Definition at line 205 of file memory.hpp.

◆ heap_free_size()

size_t idfxx::heap_free_size ( flags< memory_caps > caps )

inlinenoexcept

Returns the current free size of heap regions matching the given capabilities.

Parameters

caps	Capability flags to filter heap regions.

Returns: Current free bytes across all matching heap regions.

Definition at line 104 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_largest_free_block()

size_t idfxx::heap_largest_free_block ( flags< memory_caps > caps )

inlinenoexcept

Returns the largest free block in heap regions matching the given capabilities.

Parameters

caps	Capability flags to filter heap regions.

Returns: Size in bytes of the largest contiguous free block.

Definition at line 115 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_malloc()

void * idfxx::heap_malloc	(	size_t	size,
		flags< memory_caps >	caps
	)

inlinenoexcept

Allocates memory from heap regions matching the given capabilities.

Parameters

size	Number of bytes to allocate.
caps	Capability flags to select heap regions.

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

Definition at line 164 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_minimum_free_size()

size_t idfxx::heap_minimum_free_size ( flags< memory_caps > caps )

inlinenoexcept

Returns the minimum free size since boot for heap regions matching the given capabilities.

This is the high-water mark of heap usage — the lowest amount of free memory recorded since the system booted.

Parameters

caps	Capability flags to filter heap regions.

Returns: Minimum free bytes since boot across all matching heap regions.

Definition at line 129 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_realloc()

void * idfxx::heap_realloc	(	void *	ptr,
		size_t	size,
		flags< memory_caps >	caps
	)

inlinenoexcept

Reallocates memory from heap regions matching the given capabilities.

If ptr is nullptr, behaves like heap_malloc(). The returned pointer may differ from ptr.

Parameters

ptr	Pointer to previously allocated memory, or `nullptr`.
size	New size in bytes.
caps	Capability flags to select heap regions.

Returns: Pointer to the reallocated memory, or nullptr on failure.

Definition at line 193 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_total_size()

size_t idfxx::heap_total_size ( flags< memory_caps > caps )

inlinenoexcept

Returns the total size of heap regions matching the given capabilities.

Parameters

caps	Capability flags to filter heap regions.

Returns: Total size in bytes of all matching heap regions.

Definition at line 93 of file memory.hpp.

References idfxx::to_underlying().

◆ heap_walk()

template<typename F >

void idfxx::heap_walk	(	flags< memory_caps >	caps,
		F &&	walker
	)

Walk all heap blocks in regions matching the given capabilities.

Iterates over every block in heaps that match caps, invoking walker for each block. The walker receives a heap_region describing the containing region and a heap_block describing the individual block.

Template Parameters

F	Callable with signature `bool(heap_region, heap_block)`.

Parameters

caps	Capability flags to filter heap regions.
walker	Callable invoked for each block. Return true to continue, false to stop.

Definition at line 442 of file memory.hpp.

References idfxx::heap_block::ptr, and idfxx::to_underlying().

◆ heap_walk_all()

template<typename F >

void idfxx::heap_walk_all ( F && walker )

Walk all heap blocks across all heaps.

Iterates over every block in all registered heaps, invoking walker for each block.

Template Parameters

F	Callable with signature `bool(heap_region, heap_block)`.

Parameters

walker Callable invoked for each block. Return true to continue, false to stop.

Definition at line 463 of file memory.hpp.

References idfxx::heap_block::ptr.

◆ operator==()

template<typename T , typename U , flags< memory_caps > Caps, size_t Alignment>

constexpr bool idfxx::operator==	(	const caps_allocator< T, Caps, Alignment > &	,
		const caps_allocator< U, Caps, Alignment > &
	)

constexprnoexcept

Equality comparison for caps_allocator.

All caps_allocator instances with the same capability flags and alignment are considered equal.

Returns: Always returns true.

Definition at line 324 of file memory.hpp.

Variable Documentation

◆ enable_flags_operators< memory_caps >

template<>

constexpr bool idfxx::enable_flags_operators< memory_caps > = true

inlineconstexpr

Definition at line 67 of file memory.hpp.

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ aligned_dma_allocator

◆ aligned_dram_allocator

◆ aligned_spiram_allocator

◆ dma_allocator

◆ dram_allocator

◆ spiram_allocator

Enumeration Type Documentation

◆ memory_caps

Function Documentation

◆ get_heap_info()

◆ heap_aligned_alloc()

◆ heap_aligned_calloc()

◆ heap_calloc()

◆ heap_check_integrity()

◆ heap_check_integrity_all()

◆ heap_dump()

◆ heap_dump_all()

◆ heap_free()

◆ heap_free_size()

◆ heap_largest_free_block()

◆ heap_malloc()

◆ heap_minimum_free_size()

◆ heap_realloc()

◆ heap_total_size()

◆ heap_walk()

◆ heap_walk_all()

◆ operator==()

Variable Documentation

◆ enable_flags_operators< memory_caps >