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