Heap

概述

堆（heap）是一种非线性的数据结构，其本身是一块连续内存。本工程代码主要面向实时操作系统，故选用tlsf内存管理算法，该算法有分配速度块，内存碎片少的优点。

功能特性

  • 支持多 heap 块的同时使用。

  • 支持 heap 的分块使用，每个 heap 块都有其特定属性， 可申请特定属性的 heap 块。

  • 支持申请内存块时的4字节、8字节、16字节、32字节等地址对齐。

配置说明

caps 说明

wq_heap_caps_t 一共32位可以用来定义，bit0~15 用来修饰 heap 属性，bit16~19 用来修饰 heap 申请时的内存对齐方式，bit20~30 为保留位给用户自定义.

静态初始化

wq_heap_caps_init() 为静态初始化接口，在程序 heap 使用前需被调用，完成初始化。 其原理是根据在linker文件中，section(".heap_region.") 段中占用空间，预定义的 heap 参数完成初始化。 heap 预定义通过 WQ_HEAP_REGION_ADD_STATIC() 完成。

动态初始化

wq_heap_caps_region_add_dynamic() 是动态初始化接口。 其可在程序运行中被初始化，将一些已经用不到的内存，重新加载到堆组中。

核心api

功能特点

  • 支持非连续内存的多个堆空间。

  • 支持静态初始化分配堆内存段，同时也支持动态添加新的堆内存段。

  • 支持堆内存类型配置，参考caps参数。

用法流程

API 介绍

Defines

MALLOC_CAP_NONE

Memory have no caps attribute.

MALLOC_CAP_SPIRAM

Memory caps is SPI RAM.

MALLOC_CAP_AON

Memory must alloc in ALWAYS-ON domain.

MALLOC_CAP_SHARE_MEMORY

Memory must alloc in ALWAYS-ON domain for share memory.

MALLOC_CAP_8BYTE

Memory address must be 8byte alignment.

MALLOC_CAP_16BYTE

Memory address must be 16byte alignment.

MALLOC_CAP_32BYTE

Memory address must be 32byte alignment.

MALLOC_CAP_64BYTE

Memory address must be 64byte alignment.

MALLOC_CAP_INVALID

Memory can't be used / list end marker.

MALLOC_ONLY_USE_HEAP_TYPE

caps bit0~15 is heap type, use only heap type here.

HEAP_REGION_SECTION()
HEAP_REGION_DEF(heap_name, start, size, cap, section)
WQ_HEAP_REGION_ADD_STATIC(heap_name, start, size, cap)

heap region static define part. It will be initilized at first.

MAX_HEAP_BLOCK

maximum number of heap blocks

Typedefs

typedef uint32_t wq_heap_caps_t

caps bit0~15 is heap type. bit16~19 is memory address align type. bit20~30 is reserved.

typedef void (*alloc_failed_hook_t)(size_t size, wq_heap_caps_t caps, const char *function_name)

hook function called when an allocation operation fails, if registered

Param size:

in bytes of failed allocation

Param caps:

capabilities requested of failed allocation

Param function_name:

function which generated the failure

Functions

WQ_RET wq_heap_register_alloc_failed_hook(alloc_failed_hook_t hook)

registers a hook function to be invoked if a memory allocation operation fails

参数:

hook -- caller defined hook to be invoked

返回:

WQ_RET_OK if hook was registered.

void *wq_heap_caps_malloc(size_t size, wq_heap_caps_t caps)

Allocate a chunk of memory which has the given capabilities.

参数:

  • 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

返回:

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

void wq_heap_caps_free(void *ptr)

Free memory previously allocated via heap_caps_malloc() or heap_caps_realloc().

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

参数:

ptr -- Pointer to memory previously returned from heap_caps_malloc() or heap_caps_realloc(). CAN NOT be NULL.

void *wq_heap_caps_realloc(size_t size, wq_heap_caps_t caps, void *ptr)

Reallocate memory previously allocated via heap_caps_malloc() or heap_caps_realloc().

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

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

参数:

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

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

返回:

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

void *wq_heap_caps_aligned_alloc(size_t size, size_t alignment, wq_heap_caps_t caps)

Allocate an aligned chunk of memory which has the given capabilities.

参数:

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

  • alignment -- How the pointer received needs to be aligned must be a power of two

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

返回:

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

void *wq_heap_caps_aligned_calloc(size_t size, size_t alignment, wq_heap_caps_t caps, size_t n)

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

参数:

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

  • alignment -- How the pointer received needs to be aligned must be a power of two

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

  • n -- Number of continuing chunks of memory to allocate

返回:

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

void *wq_heap_caps_calloc(size_t size, wq_heap_caps_t caps, size_t n)

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

参数:

  • 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

  • n -- Number of continuing chunks of memory to allocate

返回:

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

size_t wq_heap_caps_get_total_size(wq_heap_caps_t caps)

Get the total 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 total space they have.

参数:

caps -- Bitwise OR of MALLOC_CAP_* flags indicating the type of memory

返回:

total size in bytes

size_t wq_heap_caps_get_free_size(wq_heap_caps_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.

备注

Note that because of heap fragmentation it is probably not possible to allocate a single block of memory of this size. Use heap_caps_get_largest_free_block() for this purpose.

参数:

caps -- Bitwise OR of MALLOC_CAP_* flags indicating the type of memory

返回:

Amount of free bytes in the regions

size_t wq_heap_caps_get_minimum_free_size(wq_heap_caps_t caps)

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

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

备注

Note the result may be less than the global all-time minimum available heap of this kind, as "low watermarks" are tracked per-region. Individual regions' heaps may have reached their "low watermarks" at different points in time. However, this result still gives a "worst case" indication for all-time minimum free heap.

参数:

caps -- Bitwise OR of MALLOC_CAP_* flags indicating the type of memory

返回:

Amount of free bytes in the regions

size_t wq_heap_caps_get_largest_free_block(wq_heap_caps_t caps)

Get the largest free block of memory able to be allocated with the given capabilities.

Returns the largest value of s for which heap_caps_malloc(s, caps) will succeed.

参数:

caps -- Bitwise OR of MALLOC_CAP_* flags indicating the type of memory

返回:

Size of the largest free block in bytes.

size_t wq_heap_caps_get_allocated_size(void *ptr)

Return the size that a particular pointer was allocated with.

备注

The app will crash with an assertion failure if the pointer is not valid.

参数:

ptr -- Pointer to currently allocated heap memory. Must be a pointer value previously returned by heap_caps_malloc, malloc, calloc, etc. and not yet freed.

返回:

Size of the memory allocated at this block.

uint32_t wq_heap_get_total_size(void)

Get heap total size.

备注

This is called to get heap total size.

返回:

Size of the heap total size.

size_t wq_heap_get_free_size(void)

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

This function takes all regions in them and adds up the free space they have.

备注

Note that because of heap fragmentation it is probably not possible to allocate a single block of memory of this size. Use heap_caps_get_largest_free_block() for this purpose.

返回:

Amount of free bytes in the regions

size_t wq_heap_get_minimum_free_size(void)

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

备注

Note the result may be less than the global all-time minimum available heap of this kind, as "low watermarks" are tracked per-region. Individual regions' heaps may have reached their "low watermarks" at different points in time. However, this result still gives a "worst case" indication for all-time minimum free heap.

返回:

Amount of free bytes in the regions

uint8_t wq_heap_get_multi_heap_list(wq_heap_region_t *heap_vector)

Get all heaps.

参数:

heap_vector -- get heap group information

返回:

number of heaps

void wq_heap_check_self(void)

check if the heap is damaged.

备注

User can register it as a hook in idle task or others. For example, user can call interface 'os_hook_idle_register_callback(wq_heap_check_self);', which will be executed in idle.

WQ_RET wq_heap_caps_init(void)

Initialize the capability-aware heap allocator.

备注

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

WQ_RET wq_heap_caps_region_add_dynamic(const wq_heap_region_t *const regions)

dynamic add heap allocator.

备注

Dynamic heaps can be allocated at any time after static heap initilization allocation.

参数:

regions -- add heap regions

struct wq_heap_region_t

Public Members

uint8_t *start_addr

memory start address

size_t len

memory length

wq_heap_caps_t caps

memory capabilities