Mem alloc

API Reference

Header File

Functions

size_t heap_caps_get_free_size(uint32_t caps)

Get the total free size of all the regions that have the given capabilities.

This function takes all regions capable of having the given capabilities allocated in them and adds up the free space they have.

Return

Amount of free bytes in the regions

Parameters

  • caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory

size_t heap_caps_get_minimum_free_size(uint32_t caps)

Get the total minimum free memory of all regions with the given capabilities.

This adds all the low water marks of the regions capable of delivering the memory with the given capabilities.

Return

Amount of free bytes in the regions

Parameters

  • caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory

void esp_heap_caps_init_region(heap_region_t *region, size_t max_num)

Initialize regions of memory to the collection of heaps at runtime.

Parameters

  • region: region table head point

  • max_num: region table size

void *_heap_caps_malloc(size_t size, uint32_t caps, const char *file, size_t line)
void _heap_caps_free(void *ptr, const char *file, size_t line)
void *_heap_caps_calloc(size_t count, size_t size, uint32_t caps, const char *file, size_t line)
void *_heap_caps_realloc(void *mem, size_t newsize, uint32_t caps, const char *file, size_t line)
void *_heap_caps_zalloc(size_t size, uint32_t caps, const char *file, size_t line)

Structures

struct mem_blk

First type memory block.

Public Members

struct mem_blk *prev

Point to previous memory block.

struct mem_blk *next

Point to next memory block.

struct heap_region

User region information.

Public Members

void *start_addr

Heap region start address.

size_t total_size

Heap region total size by byte.

uint32_t caps

Heap capacity.

void *free_blk

First free memory block.

size_t free_bytes

Current free heap size by byte.

size_t min_free_bytes

Minimum free heap size by byte ever.

Macros

HEAP_ALIGN(ptr)

Get “HEAP_ALIGN_SIZE” bytes aligned data(HEAP_ALIGN(ptr) >= ptr).

MALLOC_CAP_EXEC

Memory must be able to run executable code.

MALLOC_CAP_32BIT

Memory must allow for aligned 32-bit data accesses.

MALLOC_CAP_8BIT

Memory must allow for 8-bit data accesses.

MALLOC_CAP_DMA

Memory must be able to accessed by DMA.

MALLOC_CAP_INTERNAL

Just for code compatibility.

MALLOC_CAP_SPIRAM

Just for code compatibility.

MEM_HEAD_SIZE

Size of first type memory block.

MEM2_HEAD_SIZE

Size of second type memory block.

heap_caps_malloc(size, caps)

Allocate a chunk of memory which has the given capabilities.

Equivalent semantics to libc malloc(), for capability-aware memory.

In SDK, malloc(s) is equivalent to heap_caps_malloc(s, MALLOC_CAP_32BIT).

Return

A pointer to the memory allocated on success, NULL on failure

Parameters

  • size: Size, in bytes, of the amount of memory to allocate

  • caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned

heap_caps_free(ptr)

Free memory previously allocated via heap_caps_(m/c/re/z)alloc().

Equivalent semantics to libc free(), for capability-aware memory.

In SDK, free(p) is equivalent to heap_caps_free(p).

Parameters

  • ptr: Pointer to memory previously returned from heap_caps_(m/c/re/z)alloc(). Can be NULL.

heap_caps_calloc(n, size, caps)

Allocate a chunk of memory which has the given capabilities. The initialized value in the memory is set to zero.

Equivalent semantics to libc calloc(), for capability-aware memory.

In IDF, calloc(c, s) is equivalent to heap_caps_calloc(c, s, MALLOC_CAP_32BIT).

Return

A pointer to the memory allocated on success, NULL on failure

Parameters

  • n: Number of continuing chunks of memory to allocate

  • size: Size, in bytes, of a chunk of memory to allocate

  • caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned

heap_caps_realloc(ptr, size, caps)

Reallocate memory previously allocated via heap_caps_(m/c/re/z)alloc().

Equivalent semantics to libc realloc(), for capability-aware memory.

In SDK, realloc(p, s) is equivalent to heap_caps_realloc(p, s, MALLOC_CAP_32BIT).

‘caps’ parameter can be different to the capabilities that any original ‘ptr’ was allocated with. In this way, realloc can be used to “move” a buffer if necessary to ensure it meets a new set of capabilities.

Return

Pointer to a new buffer of size ‘size’ with capabilities ‘caps’, or NULL if allocation failed.

Parameters

  • ptr: Pointer to previously allocated memory, or NULL for a new allocation.

  • size: Size of the new buffer requested, or 0 to free the buffer.

  • caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory desired for the new allocation.

heap_caps_zalloc(size, caps)

Allocate a chunk of memory which has the given capabilities. The initialized value in the memory is set to zero.

Equivalent semantics to libc calloc(), for capability-aware memory.

In IDF, calloc(c, s) is equivalent to heap_caps_calloc(c, s, MALLOC_CAP_32BIT).

Return

A pointer to the memory allocated on success, NULL on failure

Parameters

  • size: Size, in bytes, of a chunk of memory to allocate

  • caps: Bitwise OR of MALLOC_CAP_* flags indicating the type of memory to be returned

Type Definitions

typedef struct mem_blk mem_blk_t

First type memory block.

typedef mem_blk_t mem2_blk_t

Second type memory block.

typedef struct heap_region heap_region_t

User region information.

Header File

Functions

void heap_caps_init()

Initialize the capability-aware heap allocator.

This is called once in the ESP8266 startup code. Do not call it at other times.