1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #pragma once 15 #include <stdint.h> 16 #include <stdlib.h> 17 #include <stdbool.h> 18 19 /* multi_heap is a heap implementation for handling multiple 20 heterogenous heaps in a single program. 21 22 Any contiguous block of memory can be registered as a heap. 23 */ 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** @brief Opaque handle to a registered heap */ 30 typedef struct multi_heap_info *multi_heap_handle_t; 31 32 /** 33 * @brief allocate a chunk of memory with specific alignment 34 * 35 * @param heap Handle to a registered heap. 36 * @param size size in bytes of memory chunk 37 * @param alignment how the memory must be aligned 38 * 39 * @return pointer to the memory allocated, NULL on failure 40 */ 41 void *multi_heap_aligned_alloc(multi_heap_handle_t heap, size_t size, size_t alignment); 42 43 /** @brief malloc() a buffer in a given heap 44 * 45 * Semantics are the same as standard malloc(), only the returned buffer will be allocated in the specified heap. 46 * 47 * @param heap Handle to a registered heap. 48 * @param size Size of desired buffer. 49 * 50 * @return Pointer to new memory, or NULL if allocation fails. 51 */ 52 void *multi_heap_malloc(multi_heap_handle_t heap, size_t size); 53 54 /** @brief free() a buffer aligned in a given heap. 55 * 56 * @param heap Handle to a registered heap. 57 * @param p NULL, or a pointer previously returned from multi_heap_aligned_alloc() for the same heap. 58 * @note This function is deprecated, consider using multi_heap_free() instead 59 */ 60 void __attribute__((deprecated)) multi_heap_aligned_free(multi_heap_handle_t heap, void *p); 61 62 /** @brief free() a buffer in a given heap. 63 * 64 * Semantics are the same as standard free(), only the argument 'p' must be NULL or have been allocated in the specified heap. 65 * 66 * @param heap Handle to a registered heap. 67 * @param p NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap. 68 */ 69 void multi_heap_free(multi_heap_handle_t heap, void *p); 70 71 /** @brief realloc() a buffer in a given heap. 72 * 73 * Semantics are the same as standard realloc(), only the argument 'p' must be NULL or have been allocated in the specified heap. 74 * 75 * @param heap Handle to a registered heap. 76 * @param p NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap. 77 * @param size Desired new size for buffer. 78 * 79 * @return New buffer of 'size' containing contents of 'p', or NULL if reallocation failed. 80 */ 81 void *multi_heap_realloc(multi_heap_handle_t heap, void *p, size_t size); 82 83 84 /** @brief Return the size that a particular pointer was allocated with. 85 * 86 * @param heap Handle to a registered heap. 87 * @param p Pointer, must have been previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap. 88 * 89 * @return Size of the memory allocated at this block. May be more than the original size argument, due 90 * to padding and minimum block sizes. 91 */ 92 size_t multi_heap_get_allocated_size(multi_heap_handle_t heap, void *p); 93 94 95 /** @brief Register a new heap for use 96 * 97 * This function initialises a heap at the specified address, and returns a handle for future heap operations. 98 * 99 * There is no equivalent function for deregistering a heap - if all blocks in the heap are free, you can immediately start using the memory for other purposes. 100 * 101 * @param start Start address of the memory to use for a new heap. 102 * @param size Size (in bytes) of the new heap. 103 * 104 * @return Handle of a new heap ready for use, or NULL if the heap region was too small to be initialised. 105 */ 106 multi_heap_handle_t multi_heap_register(void *start, size_t size); 107 108 109 /** @brief Associate a private lock pointer with a heap 110 * 111 * The lock argument is supplied to the MULTI_HEAP_LOCK() and MULTI_HEAP_UNLOCK() macros, defined in multi_heap_platform.h. 112 * 113 * The lock in question must be recursive. 114 * 115 * When the heap is first registered, the associated lock is NULL. 116 * 117 * @param heap Handle to a registered heap. 118 * @param lock Optional pointer to a locking structure to associate with this heap. 119 */ 120 void multi_heap_set_lock(multi_heap_handle_t heap, void* lock); 121 122 /** @brief Dump heap information to stdout 123 * 124 * For debugging purposes, this function dumps information about every block in the heap to stdout. 125 * 126 * @param heap Handle to a registered heap. 127 */ 128 void multi_heap_dump(multi_heap_handle_t heap); 129 130 /** @brief Check heap integrity 131 * 132 * Walks the heap and checks all heap data structures are valid. If any errors are detected, an error-specific message 133 * can be optionally printed to stderr. Print behaviour can be overriden at compile time by defining 134 * MULTI_CHECK_FAIL_PRINTF in multi_heap_platform.h. 135 * 136 * @param heap Handle to a registered heap. 137 * @param print_errors If true, errors will be printed to stderr. 138 * @return true if heap is valid, false otherwise. 139 */ 140 bool multi_heap_check(multi_heap_handle_t heap, bool print_errors); 141 142 /** @brief Return free heap size 143 * 144 * Returns the number of bytes available in the heap. 145 * 146 * Equivalent to the total_free_bytes member returned by multi_heap_get_heap_info(). 147 * 148 * Note that the heap may be fragmented, so the actual maximum size for a single malloc() may be lower. To know this 149 * size, see the largest_free_block member returned by multi_heap_get_heap_info(). 150 * 151 * @param heap Handle to a registered heap. 152 * @return Number of free bytes. 153 */ 154 size_t multi_heap_free_size(multi_heap_handle_t heap); 155 156 /** @brief Return the lifetime minimum free heap size 157 * 158 * Equivalent to the minimum_free_bytes member returned by multi_heap_get_info(). 159 * 160 * Returns the lifetime "low water mark" of possible values returned from multi_free_heap_size(), for the specified 161 * heap. 162 * 163 * @param heap Handle to a registered heap. 164 * @return Number of free bytes. 165 */ 166 size_t multi_heap_minimum_free_size(multi_heap_handle_t heap); 167 168 /** @brief Structure to access heap metadata via multi_heap_get_info */ 169 typedef struct { 170 size_t total_free_bytes; ///< Total free bytes in the heap. Equivalent to multi_free_heap_size(). 171 size_t total_allocated_bytes; ///< Total bytes allocated to data in the heap. 172 size_t largest_free_block; ///< Size of largest free block in the heap. This is the largest malloc-able size. 173 size_t minimum_free_bytes; ///< Lifetime minimum free heap size. Equivalent to multi_minimum_free_heap_size(). 174 size_t allocated_blocks; ///< Number of (variable size) blocks allocated in the heap. 175 size_t free_blocks; ///< Number of (variable size) free blocks in the heap. 176 size_t total_blocks; ///< Total number of (variable size) blocks in the heap. 177 } multi_heap_info_t; 178 179 /** @brief Return metadata about a given heap 180 * 181 * Fills a multi_heap_info_t structure with information about the specified heap. 182 * 183 * @param heap Handle to a registered heap. 184 * @param info Pointer to a structure to fill with heap metadata. 185 */ 186 void multi_heap_get_info(multi_heap_handle_t heap, multi_heap_info_t *info); 187 188 #ifdef __cplusplus 189 } 190 #endif 191
