1 // Copyright 2017 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 16 #include "esp_err.h" 17 #include "esp_heap_caps.h" 18 #include "soc/soc_memory_layout.h" 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** 25 * @brief Initialize the capability-aware heap allocator. 26 * 27 * This is called once in the IDF startup code. Do not call it 28 * at other times. 29 */ 30 void heap_caps_init(void); 31 32 /** 33 * @brief Enable heap(s) in memory regions where the startup stacks are located. 34 * 35 * On startup, the pro/app CPUs have a certain memory region they use as stack, so we 36 * cannot do allocations in the regions these stack frames are. When FreeRTOS is 37 * completely started, they do not use that memory anymore and heap(s) there can 38 * be enabled. 39 */ 40 void heap_caps_enable_nonos_stack_heaps(void); 41 42 /** 43 * @brief Add a region of memory to the collection of heaps at runtime. 44 * 45 * Most memory regions are defined in soc_memory_layout.c for the SoC, 46 * and are registered via heap_caps_init(). Some regions can't be used 47 * immediately and are later enabled via heap_caps_enable_nonos_stack_heaps(). 48 * 49 * Call this function to add a region of memory to the heap at some later time. 50 * 51 * This function does not consider any of the "reserved" regions or other data in soc_memory_layout, caller needs to 52 * consider this themselves. 53 * 54 * All memory within the region specified by start & end parameters must be otherwise unused. 55 * 56 * The capabilities of the newly registered memory will be determined by the start address, as looked up in the regions 57 * specified in soc_memory_layout.c. 58 * 59 * Use heap_caps_add_region_with_caps() to register a region with custom capabilities. 60 * 61 * @param start Start address of new region. 62 * @param end End address of new region. 63 * 64 * @return ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is invalid, ESP_ERR_NOT_FOUND if the 65 * specified start address doesn't reside in a known region, or any error returned by heap_caps_add_region_with_caps(). 66 */ 67 esp_err_t heap_caps_add_region(intptr_t start, intptr_t end); 68 69 70 /** 71 * @brief Add a region of memory to the collection of heaps at runtime, with custom capabilities. 72 * 73 * Similar to heap_caps_add_region(), only custom memory capabilities are specified by the caller. 74 * 75 * @param caps Ordered array of capability masks for the new region, in order of priority. Must have length 76 * SOC_MEMORY_TYPE_NO_PRIOS. Does not need to remain valid after the call returns. 77 * @param start Start address of new region. 78 * @param end End address of new region. 79 * 80 * @return 81 * - ESP_OK on success 82 * - ESP_ERR_INVALID_ARG if a parameter is invalid 83 * - ESP_ERR_NO_MEM if no memory to register new heap. 84 * - ESP_ERR_INVALID_SIZE if the memory region is too small to fit a heap 85 * - ESP_FAIL if region overlaps the start and/or end of an existing region 86 */ 87 esp_err_t heap_caps_add_region_with_caps(const uint32_t caps[], intptr_t start, intptr_t end); 88 89 90 #ifdef __cplusplus 91 } 92 #endif 93
