1 /* 2 * SPDX-FileCopyrightText: 2017-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #pragma once 7 8 #include "esp_err.h" 9 #include "esp_heap_caps.h" 10 11 #ifdef __cplusplus 12 extern "C" { 13 #endif 14 15 /** 16 * @brief Initialize the capability-aware heap allocator. 17 * 18 * This is called once in the IDF startup code. Do not call it 19 * at other times. 20 */ 21 void heap_caps_init(void); 22 23 /** 24 * @brief Enable heap(s) in memory regions where the startup stacks are located. 25 * 26 * On startup, the pro/app CPUs have a certain memory region they use as stack, so we 27 * cannot do allocations in the regions these stack frames are. When FreeRTOS is 28 * completely started, they do not use that memory anymore and heap(s) there can 29 * be enabled. 30 */ 31 void heap_caps_enable_nonos_stack_heaps(void); 32 33 /** 34 * @brief Add a region of memory to the collection of heaps at runtime. 35 * 36 * Most memory regions are defined in soc_memory_layout.c for the SoC, 37 * and are registered via heap_caps_init(). Some regions can't be used 38 * immediately and are later enabled via heap_caps_enable_nonos_stack_heaps(). 39 * 40 * Call this function to add a region of memory to the heap at some later time. 41 * 42 * This function does not consider any of the "reserved" regions or other data in soc_memory_layout, caller needs to 43 * consider this themselves. 44 * 45 * All memory within the region specified by start & end parameters must be otherwise unused. 46 * 47 * The capabilities of the newly registered memory will be determined by the start address, as looked up in the regions 48 * specified in soc_memory_layout.c. 49 * 50 * Use heap_caps_add_region_with_caps() to register a region with custom capabilities. 51 * 52 * @note Please refer to following example for memory regions allowed for addition to heap based on an existing region 53 * (address range for demonstration purpose only): 54 @verbatim 55 Existing region: 0x1000 <-> 0x3000 56 New region: 0x1000 <-> 0x3000 (Allowed) 57 New region: 0x1000 <-> 0x2000 (Allowed) 58 New region: 0x0000 <-> 0x1000 (Allowed) 59 New region: 0x3000 <-> 0x4000 (Allowed) 60 New region: 0x0000 <-> 0x2000 (NOT Allowed) 61 New region: 0x0000 <-> 0x4000 (NOT Allowed) 62 New region: 0x1000 <-> 0x4000 (NOT Allowed) 63 New region: 0x2000 <-> 0x4000 (NOT Allowed) 64 @endverbatim 65 * 66 * @param start Start address of new region. 67 * @param end End address of new region. 68 * 69 * @return ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is invalid, ESP_ERR_NOT_FOUND if the 70 * specified start address doesn't reside in a known region, or any error returned by heap_caps_add_region_with_caps(). 71 */ 72 esp_err_t heap_caps_add_region(intptr_t start, intptr_t end); 73 74 75 /** 76 * @brief Add a region of memory to the collection of heaps at runtime, with custom capabilities. 77 * 78 * Similar to heap_caps_add_region(), only custom memory capabilities are specified by the caller. 79 * 80 * @note Please refer to following example for memory regions allowed for addition to heap based on an existing region 81 * (address range for demonstration purpose only): 82 @verbatim 83 Existing region: 0x1000 <-> 0x3000 84 New region: 0x1000 <-> 0x3000 (Allowed) 85 New region: 0x1000 <-> 0x2000 (Allowed) 86 New region: 0x0000 <-> 0x1000 (Allowed) 87 New region: 0x3000 <-> 0x4000 (Allowed) 88 New region: 0x0000 <-> 0x2000 (NOT Allowed) 89 New region: 0x0000 <-> 0x4000 (NOT Allowed) 90 New region: 0x1000 <-> 0x4000 (NOT Allowed) 91 New region: 0x2000 <-> 0x4000 (NOT Allowed) 92 @endverbatim 93 * 94 * @param caps Ordered array of capability masks for the new region, in order of priority. Must have length 95 * SOC_MEMORY_TYPE_NO_PRIOS. Does not need to remain valid after the call returns. 96 * @param start Start address of new region. 97 * @param end End address of new region. 98 * 99 * @return 100 * - ESP_OK on success 101 * - ESP_ERR_INVALID_ARG if a parameter is invalid 102 * - ESP_ERR_NO_MEM if no memory to register new heap. 103 * - ESP_ERR_INVALID_SIZE if the memory region is too small to fit a heap 104 * - ESP_FAIL if region overlaps the start and/or end of an existing region 105 */ 106 esp_err_t heap_caps_add_region_with_caps(const uint32_t caps[], intptr_t start, intptr_t end); 107 108 109 #ifdef __cplusplus 110 } 111 #endif 112