mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-08 20:21:04 +00:00
heap: Refactor heap regions/capabilities out of FreeRTOS
Remove tagged heap API, rename caps_xxx to heap_caps_xxx Also includes additional heap_caps_xxx inspection functions.
This commit is contained in:
Angus Gratton
committed by
Angus Gratton
Angus Gratton
parent
5ee49fd311
commit
71c70cb15c
@@ -11,103 +11,25 @@
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
#ifndef HEAP_ALLOC_CAPS_H
|
||||
#define HEAP_ALLOC_CAPS_H
|
||||
#pragma once
|
||||
#warning "This header is deprecated, please use functions defined in esp_heap_caps.h instead."
|
||||
#include "esp_heap_caps.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stdlib.h>
|
||||
/* Deprecated FreeRTOS-style esp_heap_alloc_caps.h functions follow */
|
||||
|
||||
/**
|
||||
* @brief Flags to indicate the capabilities of the various memory systems
|
||||
*/
|
||||
#define MALLOC_CAP_EXEC (1<<0) ///< Memory must be able to run executable code
|
||||
#define MALLOC_CAP_32BIT (1<<1) ///< Memory must allow for aligned 32-bit data accesses
|
||||
#define MALLOC_CAP_8BIT (1<<2) ///< Memory must allow for 8/16/...-bit data accesses
|
||||
#define MALLOC_CAP_DMA (1<<3) ///< Memory must be able to accessed by DMA
|
||||
#define MALLOC_CAP_PID2 (1<<4) ///< Memory must be mapped to PID2 memory space
|
||||
#define MALLOC_CAP_PID3 (1<<5) ///< Memory must be mapped to PID3 memory space
|
||||
#define MALLOC_CAP_PID4 (1<<6) ///< Memory must be mapped to PID4 memory space
|
||||
#define MALLOC_CAP_PID5 (1<<7) ///< Memory must be mapped to PID5 memory space
|
||||
#define MALLOC_CAP_PID6 (1<<8) ///< Memory must be mapped to PID6 memory space
|
||||
#define MALLOC_CAP_PID7 (1<<9) ///< Memory must be mapped to PID7 memory space
|
||||
#define MALLOC_CAP_SPISRAM (1<<10) ///< Memory must be in SPI SRAM
|
||||
#define MALLOC_CAP_INVALID (1<<31) ///< Memory can't be used / list end marker
|
||||
/* Please use heap_caps_malloc() instead of this function */
|
||||
void *pvPortMallocCaps(size_t xWantedSize, uint32_t caps) asm("heap_caps_malloc") __attribute__((deprecated));
|
||||
|
||||
/* Please use heap_caps_get_minimum_free_heap_size() instead of this function */
|
||||
size_t xPortGetMinimumEverFreeHeapSizeCaps( uint32_t caps ) asm("heap_caps_get_minimum_free_heap_size") __attribute__((deprecated));
|
||||
|
||||
/**
|
||||
* @brief Initialize the capability-aware heap allocator.
|
||||
*
|
||||
* For the ESP32, this is called once in the startup code.
|
||||
*/
|
||||
void heap_alloc_caps_init();
|
||||
|
||||
/**
|
||||
* @brief Enable the memory region where the startup stacks are located for allocation
|
||||
*
|
||||
* On startup, the pro/app CPUs have a certain memory region they use as stack, so we
|
||||
* cannot do allocations in the regions these stack frames are. When FreeRTOS is
|
||||
* completely started, they do not use that memory anymore and allocation there can
|
||||
* be re-enabled.
|
||||
*/
|
||||
void heap_alloc_enable_nonos_stack_tag();
|
||||
|
||||
/**
|
||||
* @brief Allocate a chunk of memory which has the given capabilities
|
||||
*
|
||||
* @param xWantedSize Size, in bytes, of the amount of memory to allocate
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory to be returned
|
||||
*
|
||||
* @return A pointer to the memory allocated on success, NULL on failure
|
||||
*/
|
||||
void *pvPortMallocCaps(size_t xWantedSize, uint32_t caps);
|
||||
|
||||
/**
|
||||
* @brief 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.
|
||||
*
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory
|
||||
*
|
||||
* @return Amount of free bytes in the regions
|
||||
*/
|
||||
size_t xPortGetFreeHeapSizeCaps( uint32_t caps );
|
||||
|
||||
/**
|
||||
* @brief Get the total minimum free memory of all regions with the given capabilities
|
||||
*
|
||||
* This adds all the lowmarks of the regions capable of delivering the memory with the
|
||||
* given capabilities
|
||||
*
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory
|
||||
*
|
||||
* @return Amount of free bytes in the regions
|
||||
*/
|
||||
size_t xPortGetMinimumEverFreeHeapSizeCaps( uint32_t caps );
|
||||
|
||||
|
||||
|
||||
/**
|
||||
* @brief Convenience function to check if a pointer is DMA-capable.
|
||||
*
|
||||
* @param ptr Pointer to check
|
||||
*
|
||||
* @return True if DMA-capable, false if not.
|
||||
*/
|
||||
static inline bool esp_ptr_dma_capable( const void *ptr )
|
||||
{
|
||||
return ( (int)ptr >= 0x3FFAE000 && (int)ptr < 0x40000000 );
|
||||
}
|
||||
/* Please use heap_caps_get_free_heap_size() instead of this function */
|
||||
size_t xPortGetFreeHeapSizeCaps( uint32_t caps ) asm("heap_caps_get_free_heap_size") __attribute__((deprecated));
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif //HEAP_ALLOC_CAPS_H
|
||||
|
||||
175
components/heap/include/esp_heap_caps.h
Normal file
175
components/heap/include/esp_heap_caps.h
Normal file
@@ -0,0 +1,175 @@
|
||||
// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
#pragma once
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stdlib.h>
|
||||
#include "multi_heap.h"
|
||||
|
||||
/**
|
||||
* @brief Flags to indicate the capabilities of the various memory systems
|
||||
*/
|
||||
#define MALLOC_CAP_EXEC (1<<0) ///< Memory must be able to run executable code
|
||||
#define MALLOC_CAP_32BIT (1<<1) ///< Memory must allow for aligned 32-bit data accesses
|
||||
#define MALLOC_CAP_8BIT (1<<2) ///< Memory must allow for 8/16/...-bit data accesses
|
||||
#define MALLOC_CAP_DMA (1<<3) ///< Memory must be able to accessed by DMA
|
||||
#define MALLOC_CAP_PID2 (1<<4) ///< Memory must be mapped to PID2 memory space (PIDs are not currently used)
|
||||
#define MALLOC_CAP_PID3 (1<<5) ///< Memory must be mapped to PID3 memory space (PIDs are not currently used)
|
||||
#define MALLOC_CAP_PID4 (1<<6) ///< Memory must be mapped to PID4 memory space (PIDs are not currently used)
|
||||
#define MALLOC_CAP_PID5 (1<<7) ///< Memory must be mapped to PID5 memory space (PIDs are not currently used)
|
||||
#define MALLOC_CAP_PID6 (1<<8) ///< Memory must be mapped to PID6 memory space (PIDs are not currently used)
|
||||
#define MALLOC_CAP_PID7 (1<<9) ///< Memory must be mapped to PID7 memory space (PIDs are not currently used)
|
||||
#define MALLOC_CAP_SPISRAM (1<<10) ///< Memory must be in SPI SRAM
|
||||
#define MALLOC_CAP_INVALID (1<<31) ///< Memory can't be used / list end marker
|
||||
|
||||
|
||||
/**
|
||||
* @brief Initialize the capability-aware heap allocator.
|
||||
*
|
||||
* This is called once in the IDF startup code. Do not call it
|
||||
* at other times.
|
||||
*/
|
||||
void heap_caps_init();
|
||||
|
||||
/**
|
||||
* @brief Enable heap(s) in memory regions where the startup stacks are located.
|
||||
*
|
||||
* On startup, the pro/app CPUs have a certain memory region they use as stack, so we
|
||||
* cannot do allocations in the regions these stack frames are. When FreeRTOS is
|
||||
* completely started, they do not use that memory anymore and heap(s) there can
|
||||
* be enabled.
|
||||
*/
|
||||
void heap_caps_enable_nonos_stack_heaps();
|
||||
|
||||
/**
|
||||
* @brief Allocate a chunk of memory which has the given capabilities
|
||||
*
|
||||
* Equivalent semantics to libc malloc(), for capability-aware memory.
|
||||
*
|
||||
* In IDF, malloc(p) is equivalent to heaps_caps_malloc(p, MALLOC_CAP_8BIT);
|
||||
*
|
||||
* @param size Size, in bytes, of the amount of memory to allocate
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory to be returned
|
||||
*
|
||||
* @return A pointer to the memory allocated on success, NULL on failure
|
||||
*/
|
||||
void *heap_caps_malloc(size_t size, uint32_t caps);
|
||||
|
||||
/**
|
||||
* @brief Free memory previously allocated via heap_caps_malloc() or heap_caps_realloc().
|
||||
*
|
||||
* Equivalent semantics to libc free(), for capability-aware memory.
|
||||
*
|
||||
* In IDF, free(p) is equivalent to heap_caps_free(p).
|
||||
*
|
||||
* @param ptr Pointer to memory previously returned from heap_caps_malloc() or heap_caps_realloc(). Can be NULL.
|
||||
*/
|
||||
void heap_caps_free( void *ptr);
|
||||
|
||||
/**
|
||||
* @brief Reallocate memory previously allocated via heaps_caps_malloc() or heaps_caps_realloc().
|
||||
*
|
||||
* Equivalent semantics to libc realloc(), for capability-aware memory.
|
||||
*
|
||||
* In IDF, realloc(p, s) is equivalent to heap_caps_realloc(p, s, MALLOC_CAP_8BIT).
|
||||
*
|
||||
* '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 new set of capabilities.
|
||||
*
|
||||
* @param ptr Pointer to previously allocated memory, or NULL for a new allocation.
|
||||
* @param size Size of the new buffer requested, or 0 to free the buffer.
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory desired for the new allocation.
|
||||
*
|
||||
* @return Pointer to a new buffer of size 'size' with capabilities 'caps', or NULL if allocation failed.
|
||||
*/
|
||||
void *heap_caps_realloc( void *ptr, size_t size, int caps);
|
||||
|
||||
|
||||
/**
|
||||
* @brief 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.
|
||||
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory
|
||||
*
|
||||
* @return Amount of free bytes in the regions
|
||||
*/
|
||||
size_t heap_caps_get_free_size( uint32_t caps );
|
||||
|
||||
|
||||
/**
|
||||
* @brief 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.
|
||||
*
|
||||
* Note the result may be less than the global all-time minimum available heap of this kind, as "low water marks" are
|
||||
* tracked per-heap. Individual heaps may have reached their "low water marks" at different points in time. However
|
||||
* this result still gives a "worst case" indication for all-time free heap.
|
||||
*
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory
|
||||
*
|
||||
* @return Amount of free bytes in the regions
|
||||
*/
|
||||
size_t heap_caps_get_minimum_free_size( uint32_t caps );
|
||||
|
||||
/**
|
||||
* @brief 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.
|
||||
*
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory
|
||||
*
|
||||
* @return Size of largest free block in bytes.
|
||||
*/
|
||||
size_t heap_caps_get_largest_free_block( uint32_t caps );
|
||||
|
||||
|
||||
/**
|
||||
* @brief Get heap info for all regions with the given capabilities.
|
||||
*
|
||||
* Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggregate
|
||||
* across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except that
|
||||
* minimum_free_bytes has the same caveats described in heap_caps_get_minimum_free_size().
|
||||
*
|
||||
* @param info Pointer to a structure which will be filled with relevant
|
||||
* heap metadata.
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory
|
||||
*
|
||||
*/
|
||||
void heap_caps_get_info( multi_heap_info_t *info, uint32_t caps );
|
||||
|
||||
|
||||
/**
|
||||
* @brief Print a summary of all memory with the given capabilities.
|
||||
*
|
||||
* Calls multi_heap_info() on all heaps which share the given capabilities, and
|
||||
* prints a two-line summary for each, then a total summary.
|
||||
*
|
||||
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
|
||||
* of memory
|
||||
*
|
||||
*/
|
||||
void heap_caps_print_heap_info( uint32_t caps );
|
||||
|
||||
@@ -104,7 +104,7 @@ void multi_heap_set_lock(multi_heap_handle_t heap, void* lock);
|
||||
*
|
||||
* @param heap Handle to a registered heap.
|
||||
*/
|
||||
void multi_heap_dump(multi_heap_handle_t handle);
|
||||
void multi_heap_dump(multi_heap_handle_t heap);
|
||||
|
||||
/** @brief Check heap integrity
|
||||
*
|
||||
@@ -144,6 +144,7 @@ size_t multi_heap_free_size(multi_heap_handle_t heap);
|
||||
*/
|
||||
size_t multi_heap_minimum_free_size(multi_heap_handle_t heap);
|
||||
|
||||
/** @brief Structure to access heap metadata via multi_get_heap_info */
|
||||
typedef struct {
|
||||
size_t total_free_bytes; ///< Total free bytes in the heap. Equivalent to multi_free_heap_size().
|
||||
size_t total_allocated_bytes; ///< Total bytes allocated to data in the heap.
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
// Copyright 2015-2017 Espressif Systems (Shanghai) PTE LTD
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
#pragma once
|
||||
|
||||
/* Simple wrapper means that mumm_malloc src/ directory doesn't need
|
||||
to be in the global search path.
|
||||
*/
|
||||
#include "../mumm_malloc/src/mumm_malloc.h"
|
||||
@@ -1,117 +0,0 @@
|
||||
/*
|
||||
* Configuration for mumm_malloc in IDF
|
||||
*
|
||||
* Unlike umm_malloc, this config doesn't include
|
||||
* much heap configuration - just compiler configuration
|
||||
*/
|
||||
|
||||
#ifndef _MUMM_MALLOC_CFG_H
|
||||
#define _MUMM_MALLOC_CFG_H
|
||||
|
||||
#include <freertos/FreeRTOS.h>
|
||||
#include <freertos/task.h>
|
||||
|
||||
/* A couple of macros to make packing structures less compiler dependent */
|
||||
|
||||
#define MUMM_H_ATTPACKPRE
|
||||
#define MUMM_H_ATTPACKSUF __attribute__((__packed__))
|
||||
|
||||
#define MUMM_INFO
|
||||
|
||||
#ifdef MUMM_INFO
|
||||
typedef struct MUMM_HEAP_INFO_t {
|
||||
unsigned short int totalEntries;
|
||||
unsigned short int usedEntries;
|
||||
unsigned short int freeEntries;
|
||||
|
||||
unsigned short int totalBlocks;
|
||||
unsigned short int usedBlocks;
|
||||
unsigned short int freeBlocks;
|
||||
|
||||
unsigned short int maxFreeContiguousBlocks;
|
||||
|
||||
unsigned short int blockSize;
|
||||
unsigned short int numBlocks; /* configured, not counted */
|
||||
}
|
||||
MUMM_HEAP_INFO;
|
||||
|
||||
void *mumm_info( mumm_heap_handle heap, void *ptr, int force, MUMM_HEAP_INFO* info );
|
||||
size_t mumm_free_heap_size( mumm_heap_handle heap );
|
||||
|
||||
#else
|
||||
#endif
|
||||
|
||||
#define MUMM_CRITICAL_ENTRY(PLOCK) taskENTER_CRITICAL((portMUX_TYPE *)(PLOCK))
|
||||
#define MUMM_CRITICAL_EXIT(PLOCK) taskEXIT_CRITICAL((portMUX_TYPE *)(PLOCK))
|
||||
|
||||
/*
|
||||
* -D MUMM_INTEGRITY_CHECK :
|
||||
*
|
||||
* Enables heap integrity check before any heap operation. It affects
|
||||
* performance, but does NOT consume extra memory.
|
||||
*
|
||||
* If integrity violation is detected, the message is printed and user-provided
|
||||
* callback is called: `UMM_HEAP_CORRUPTION_CB()`
|
||||
*
|
||||
* Note that not all buffer overruns are detected: each buffer is aligned by
|
||||
* 4 bytes, so there might be some trailing "extra" bytes which are not checked
|
||||
* for corruption.
|
||||
*/
|
||||
|
||||
//#define MUMM_INTEGRITY_CHECK
|
||||
|
||||
#ifdef MUMM_INTEGRITY_CHECK
|
||||
int mumm_integrity_check( mumm_heap_handle heap );
|
||||
# define INTEGRITY_CHECK(HEAP) mumm_integrity_check(HEAP)
|
||||
extern void mumm_corruption(void);
|
||||
# define MUMM_HEAP_CORRUPTION_CB(heap) printf( "Heap Corruption in heap %p!\n", heap )
|
||||
#else
|
||||
# define INTEGRITY_CHECK(HEAP) 0
|
||||
#endif
|
||||
|
||||
/*
|
||||
* -D MUMM_POISON :
|
||||
*
|
||||
* Enables heap poisoning: add predefined value (poison) before and after each
|
||||
* allocation, and check before each heap operation that no poison is
|
||||
* corrupted.
|
||||
*
|
||||
* Other than the poison itself, we need to store exact user-requested length
|
||||
* for each buffer, so that overrun by just 1 byte will be always noticed.
|
||||
*
|
||||
* Customizations:
|
||||
*
|
||||
* UMM_POISON_SIZE_BEFORE:
|
||||
* Number of poison bytes before each block, e.g. 2
|
||||
* UMM_POISON_SIZE_AFTER:
|
||||
* Number of poison bytes after each block e.g. 2
|
||||
* UMM_POISONED_BLOCK_LEN_TYPE
|
||||
* Type of the exact buffer length, e.g. `short`
|
||||
*
|
||||
* NOTE: each allocated buffer is aligned by 4 bytes. But when poisoning is
|
||||
* enabled, actual pointer returned to user is shifted by
|
||||
* `(sizeof(UMM_POISONED_BLOCK_LEN_TYPE) + UMM_POISON_SIZE_BEFORE)`.
|
||||
* It's your responsibility to make resulting pointers aligned appropriately.
|
||||
*
|
||||
* If poison corruption is detected, the message is printed and user-provided
|
||||
* callback is called: `UMM_HEAP_CORRUPTION_CB()`
|
||||
*/
|
||||
|
||||
//#define MUMM_POISON_CHECK
|
||||
|
||||
#define UMM_POISON_SIZE_BEFORE 4
|
||||
#define UMM_POISON_SIZE_AFTER 4
|
||||
#define UMM_POISONED_BLOCK_LEN_TYPE short
|
||||
|
||||
#ifdef MUMM_POISON_CHECK
|
||||
void *mumm_poison_malloc( mumm_heap_handle heap, size_t size );
|
||||
void *mumm_poison_calloc( mumm_heap_handle heap, size_t num, size_t size );
|
||||
void *mumm_poison_realloc( mumm_heap_handle heap, void *ptr, size_t size );
|
||||
void mumm_poison_free( mumm_heap_handle heap, void *ptr );
|
||||
int mumm_poison_check( mumm_heap_handle heap );
|
||||
# define POISON_CHECK(HEAP) mumm_poison_check(HEAP)
|
||||
#else
|
||||
# define POISON_CHECK(HEAP) 0
|
||||
#endif
|
||||
|
||||
#endif /* _MUMM_MALLOC_CFG_H */
|
||||
Reference in New Issue
Block a user