Memory capability flags, heap queries, allocation, walking, integrity checking, and STL-compatible allocators. More...

Namespaces
namespace	idfxx

namespace	idfxx::memory

Classes
struct	idfxx::memory::info
	Heap region statistics. More...

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

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

struct	idfxx::caps_allocator< T, Caps, Alignment >
	STL-compatible allocator for capability-based memory regions. 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::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::memory::total_size (flags< caps > c) noexcept
	Returns the total size of heap regions matching the given capabilities.

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

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

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

info	idfxx::memory::get_info (flags< caps > c) noexcept
	Returns detailed heap statistics for regions matching the given capabilities.

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

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

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

bool	idfxx::memory::check_integrity (bool print_errors=false) noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	idfxx::memory::dump (flags< caps > c) noexcept
	Dump the structure of heaps with matching capabilities, or all heaps.

void	idfxx::memory::dump () noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

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

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

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

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

void *	idfxx::aligned_calloc (size_t alignment, size_t n, size_t size, flags< memory::caps > c) 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.

Variables
size_t	idfxx::memory::info::total_free_bytes
	Total free bytes across matching regions.

size_t	idfxx::memory::info::total_allocated_bytes
	Total allocated bytes across matching regions.

size_t	idfxx::memory::info::largest_free_block
	Size of the largest contiguous free block.

size_t	idfxx::memory::info::minimum_free_bytes
	Minimum free bytes since boot (high-water mark).

size_t	idfxx::memory::info::allocated_blocks
	Number of allocated blocks.

size_t	idfxx::memory::info::free_blocks
	Number of free blocks.

size_t	idfxx::memory::info::total_blocks
	Total number of blocks (allocated + free).

intptr_t	idfxx::memory::region::start
	Start address of the heap region.

intptr_t	idfxx::memory::region::end
	End address of the heap region.

void *	idfxx::memory::block::ptr
	Pointer to the block data.

size_t	idfxx::memory::block::size
	Size of the block in bytes.

bool	idfxx::memory::block::used
	True if allocated, false if free.

Detailed Description

Memory capability flags, heap queries, allocation, walking, integrity checking, 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 520 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 494 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 508 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.

Allocates 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 482 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.

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

Allocates 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 469 of file memory.hpp.

Enumeration Type Documentation

◆ 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
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

◆ aligned_alloc()

void * idfxx::aligned_alloc	(	size_t	alignment,
		size_t	size,
		flags< memory::caps >	c
	)

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.
c	Capability flags to select heap regions.

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

Definition at line 332 of file memory.hpp.

References idfxx::to_underlying().

◆ aligned_calloc()

void * idfxx::aligned_calloc	(	size_t	alignment,
		size_t	n,
		size_t	size,
		flags< memory::caps >	c
	)

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.
c	Capability flags to select heap regions.

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

Definition at line 346 of file memory.hpp.

References idfxx::to_underlying().

◆ calloc()

void * idfxx::calloc	(	size_t	n,
		size_t	size,
		flags< memory::caps >	c
	)

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.
c	Capability flags to select heap regions.

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

Definition at line 291 of file memory.hpp.

References idfxx::to_underlying().

◆ check_integrity() [1/2]

bool idfxx::memory::check_integrity ( bool print_errors = false )

inlinenoexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 240 of file memory.hpp.

◆ check_integrity() [2/2]

bool idfxx::memory::check_integrity	(	flags< caps >	c,
		bool	print_errors = `false`
	)

inlinenoexcept

Check integrity of heaps with the given capabilities, or all heaps.

When called without arguments, checks all heaps.

Parameters

c	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 235 of file memory.hpp.

References idfxx::to_underlying().

◆ dump() [1/2]

void idfxx::memory::dump ( )

inlinenoexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 260 of file memory.hpp.

◆ dump() [2/2]

void idfxx::memory::dump ( flags< caps > c )

inlinenoexcept

Dump the structure of heaps with matching capabilities, or all heaps.

Prints detailed information about every block in matching heaps to the serial console. When called without arguments, dumps all heaps.

Parameters

c	Capability flags to filter heap regions.

Definition at line 255 of file memory.hpp.

References idfxx::to_underlying().

◆ free()

void idfxx::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 319 of file memory.hpp.

◆ free_size()

size_t idfxx::memory::free_size ( flags< caps > c )

inlinenoexcept

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

Parameters

c	Capability flags to filter heap regions.

Returns: Current free bytes across all matching heap regions.

Definition at line 112 of file memory.hpp.

References idfxx::to_underlying().

◆ get_info()

info idfxx::memory::get_info ( flags< caps > c )

inlinenoexcept

Returns detailed heap statistics for regions matching the given capabilities.

Parameters

c	Capability flags to filter heap regions.

Returns: An info struct containing aggregated statistics.

Definition at line 148 of file memory.hpp.

References idfxx::to_underlying().

◆ largest_free_block()

size_t idfxx::memory::largest_free_block ( flags< caps > c )

inlinenoexcept

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

Parameters

c	Capability flags to filter heap regions.

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

Definition at line 123 of file memory.hpp.

References idfxx::to_underlying().

◆ malloc()

void * idfxx::malloc	(	size_t	size,
		flags< memory::caps >	c
	)

inlinenoexcept

Allocates memory from heap regions matching the given capabilities.

Parameters

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

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

Definition at line 278 of file memory.hpp.

References idfxx::to_underlying().

◆ minimum_free_size()

size_t idfxx::memory::minimum_free_size ( flags< caps > c )

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

c	Capability flags to filter heap regions.

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

Definition at line 137 of file memory.hpp.

References idfxx::to_underlying().

◆ 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 439 of file memory.hpp.

◆ realloc()

void * idfxx::realloc	(	void *	ptr,
		size_t	size,
		flags< memory::caps >	c
	)

inlinenoexcept

Reallocates memory from heap regions matching the given capabilities.

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

Parameters

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

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

Definition at line 307 of file memory.hpp.

References idfxx::to_underlying().

◆ total_size()

size_t idfxx::memory::total_size ( flags< caps > c )

inlinenoexcept

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

Parameters

c	Capability flags to filter heap regions.

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

Definition at line 101 of file memory.hpp.

References idfxx::to_underlying().

◆ walk() [1/2]

template<typename F >

void idfxx::memory::walk ( 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(region, block)`.

Parameters

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

Definition at line 215 of file memory.hpp.

References idfxx::memory::block::ptr, and idfxx::memory::region::start.

◆ walk() [2/2]

template<typename F >

void idfxx::memory::walk	(	flags< caps >	c,
		F &&	walker
	)

Walk all heap blocks in regions matching the given capabilities.

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

Template Parameters

F	Callable with signature `bool(region, block)`.

Parameters

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

Definition at line 196 of file memory.hpp.

References idfxx::memory::block::ptr, idfxx::memory::region::start, and idfxx::to_underlying().

Variable Documentation

◆ allocated_blocks

size_t idfxx::memory::info::allocated_blocks

Number of allocated blocks.

Definition at line 89 of file memory.hpp.

◆ end

intptr_t idfxx::memory::region::end

End address of the heap region.

Definition at line 170 of file memory.hpp.

◆ free_blocks

size_t idfxx::memory::info::free_blocks

Number of free blocks.

Definition at line 90 of file memory.hpp.

◆ largest_free_block

size_t idfxx::memory::info::largest_free_block

Size of the largest contiguous free block.

Definition at line 87 of file memory.hpp.

◆ minimum_free_bytes

size_t idfxx::memory::info::minimum_free_bytes

Minimum free bytes since boot (high-water mark).

Definition at line 88 of file memory.hpp.

◆ ptr

void* idfxx::memory::block::ptr

Pointer to the block data.

Definition at line 178 of file memory.hpp.

Referenced by idfxx::memory::walk(), and idfxx::memory::walk().

◆ size

size_t idfxx::memory::block::size

Size of the block in bytes.

Definition at line 179 of file memory.hpp.

◆ start

intptr_t idfxx::memory::region::start

Start address of the heap region.

Definition at line 169 of file memory.hpp.

Referenced by idfxx::memory::walk(), and idfxx::memory::walk().

◆ total_allocated_bytes

size_t idfxx::memory::info::total_allocated_bytes

Total allocated bytes across matching regions.

Definition at line 86 of file memory.hpp.

◆ total_blocks

size_t idfxx::memory::info::total_blocks

Total number of blocks (allocated + free).

Definition at line 91 of file memory.hpp.

◆ total_free_bytes

size_t idfxx::memory::info::total_free_bytes

Total free bytes across matching regions.

Definition at line 85 of file memory.hpp.

◆ used

bool idfxx::memory::block::used

True if allocated, false if free.

Definition at line 180 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

◆ caps

Function Documentation

◆ aligned_alloc()

◆ aligned_calloc()

◆ calloc()

◆ check_integrity() [1/2]

◆ check_integrity() [2/2]

◆ dump() [1/2]

◆ dump() [2/2]

◆ free()

◆ free_size()

◆ get_info()

◆ largest_free_block()

◆ malloc()

◆ minimum_free_size()

◆ operator==()

◆ realloc()

◆ total_size()

◆ walk() [1/2]

◆ walk() [2/2]

Variable Documentation

◆ allocated_blocks

◆ end

◆ free_blocks

◆ largest_free_block

◆ minimum_free_bytes

◆ ptr

◆ size

◆ start

◆ total_allocated_bytes

◆ total_blocks

◆ total_free_bytes

◆ used