Skip to content

Commit 658acfe

Browse files
me-no-devme-no-dev
committed
Add missing headers
1 parent 27d54b3 commit 658acfe

File tree

6 files changed

+595
-178
lines changed

6 files changed

+595
-178
lines changed

‎tools/sdk/include/heap/esp_heap_alloc_caps.h

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
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+
#warning "This header is deprecated, please use functions defined in esp_heap_caps.h instead."
16+
#include "esp_heap_caps.h"
17+
18+
#ifdef __cplusplus
19+
extern "C" {
20+
#endif
21+
22+
/* Deprecated FreeRTOS-style esp_heap_alloc_caps.h functions follow */
23+
24+
/* Please use heap_caps_malloc() instead of this function */
25+
void *pvPortMallocCaps(size_t xWantedSize, uint32_t caps) asm("heap_caps_malloc") __attribute__((deprecated));
26+
27+
/* Please use heap_caps_get_minimum_free_heap_size() instead of this function */
28+
size_t xPortGetMinimumEverFreeHeapSizeCaps( uint32_t caps ) asm("heap_caps_get_minimum_free_heap_size") __attribute__((deprecated));
29+
30+
/* Please use heap_caps_get_free_size() instead of this function */
31+
size_t xPortGetFreeHeapSizeCaps( uint32_t caps ) asm("heap_caps_get_free_heap_size") __attribute__((deprecated));
32+
33+
#ifdef __cplusplus
34+
}
35+
#endif

‎tools/sdk/include/heap/esp_heap_caps.h

+172
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
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+
16+
#include <stdint.h>
17+
#include <stdlib.h>
18+
#include "multi_heap.h"
19+
20+
/**
21+
* @brief Flags to indicate the capabilities of the various memory systems
22+
*/
23+
#define MALLOC_CAP_EXEC (1<<0) ///< Memory must be able to run executable code
24+
#define MALLOC_CAP_32BIT (1<<1) ///< Memory must allow for aligned 32-bit data accesses
25+
#define MALLOC_CAP_8BIT (1<<2) ///< Memory must allow for 8/16/...-bit data accesses
26+
#define MALLOC_CAP_DMA (1<<3) ///< Memory must be able to accessed by DMA
27+
#define MALLOC_CAP_PID2 (1<<4) ///< Memory must be mapped to PID2 memory space (PIDs are not currently used)
28+
#define MALLOC_CAP_PID3 (1<<5) ///< Memory must be mapped to PID3 memory space (PIDs are not currently used)
29+
#define MALLOC_CAP_PID4 (1<<6) ///< Memory must be mapped to PID4 memory space (PIDs are not currently used)
30+
#define MALLOC_CAP_PID5 (1<<7) ///< Memory must be mapped to PID5 memory space (PIDs are not currently used)
31+
#define MALLOC_CAP_PID6 (1<<8) ///< Memory must be mapped to PID6 memory space (PIDs are not currently used)
32+
#define MALLOC_CAP_PID7 (1<<9) ///< Memory must be mapped to PID7 memory space (PIDs are not currently used)
33+
#define MALLOC_CAP_SPISRAM (1<<10) ///< Memory must be in SPI SRAM
34+
#define MALLOC_CAP_INVALID (1<<31) ///< Memory can't be used / list end marker
35+
36+
/**
37+
* @brief Allocate a chunk of memory which has the given capabilities
38+
*
39+
* Equivalent semantics to libc malloc(), for capability-aware memory.
40+
*
41+
* In IDF, ``malloc(p)`` is equivalent to ``heaps_caps_malloc(p, MALLOC_CAP_8BIT)``.
42+
*
43+
* @param size Size, in bytes, of the amount of memory to allocate
44+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
45+
* of memory to be returned
46+
*
47+
* @return A pointer to the memory allocated on success, NULL on failure
48+
*/
49+
void *heap_caps_malloc(size_t size, uint32_t caps);
50+
51+
/**
52+
* @brief Free memory previously allocated via heap_caps_malloc() or heap_caps_realloc().
53+
*
54+
* Equivalent semantics to libc free(), for capability-aware memory.
55+
*
56+
* In IDF, ``free(p)`` is equivalent to ``heap_caps_free(p)``.
57+
*
58+
* @param ptr Pointer to memory previously returned from heap_caps_malloc() or heap_caps_realloc(). Can be NULL.
59+
*/
60+
void heap_caps_free( void *ptr);
61+
62+
/**
63+
* @brief Reallocate memory previously allocated via heaps_caps_malloc() or heaps_caps_realloc().
64+
*
65+
* Equivalent semantics to libc realloc(), for capability-aware memory.
66+
*
67+
* In IDF, ``realloc(p, s)`` is equivalent to ``heap_caps_realloc(p, s, MALLOC_CAP_8BIT)``.
68+
*
69+
* 'caps' parameter can be different to the capabilities that any original 'ptr' was allocated with. In this way,
70+
* realloc can be used to "move" a buffer if necessary to ensure it meets a new set of capabilities.
71+
*
72+
* @param ptr Pointer to previously allocated memory, or NULL for a new allocation.
73+
* @param size Size of the new buffer requested, or 0 to free the buffer.
74+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
75+
* of memory desired for the new allocation.
76+
*
77+
* @return Pointer to a new buffer of size 'size' with capabilities 'caps', or NULL if allocation failed.
78+
*/
79+
void *heap_caps_realloc( void *ptr, size_t size, int caps);
80+
81+
82+
/**
83+
* @brief Get the total free size of all the regions that have the given capabilities
84+
*
85+
* This function takes all regions capable of having the given capabilities allocated in them
86+
* and adds up the free space they have.
87+
*
88+
* Note that because of heap fragmentation it is probably not possible to allocate a single block of memory
89+
* of this size. Use heap_caps_get_largest_free_block() for this purpose.
90+
91+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
92+
* of memory
93+
*
94+
* @return Amount of free bytes in the regions
95+
*/
96+
size_t heap_caps_get_free_size( uint32_t caps );
97+
98+
99+
/**
100+
* @brief Get the total minimum free memory of all regions with the given capabilities
101+
*
102+
* This adds all the low water marks of the regions capable of delivering the memory
103+
* with the given capabilities.
104+
*
105+
* Note the result may be less than the global all-time minimum available heap of this kind, as "low water marks" are
106+
* tracked per-region. Individual regions' heaps may have reached their "low water marks" at different points in time. However
107+
* this result still gives a "worst case" indication for all-time minimum free heap.
108+
*
109+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
110+
* of memory
111+
*
112+
* @return Amount of free bytes in the regions
113+
*/
114+
size_t heap_caps_get_minimum_free_size( uint32_t caps );
115+
116+
/**
117+
* @brief Get the largest free block of memory able to be allocated with the given capabilities.
118+
*
119+
* Returns the largest value of ``s`` for which ``heap_caps_malloc(s, caps)`` will succeed.
120+
*
121+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
122+
* of memory
123+
*
124+
* @return Size of largest free block in bytes.
125+
*/
126+
size_t heap_caps_get_largest_free_block( uint32_t caps );
127+
128+
129+
/**
130+
* @brief Get heap info for all regions with the given capabilities.
131+
*
132+
* Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggregate
133+
* across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except that
134+
* ``minimum_free_bytes`` has the same caveats described in heap_caps_get_minimum_free_size().
135+
*
136+
* @param info Pointer to a structure which will be filled with relevant
137+
* heap metadata.
138+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
139+
* of memory
140+
*
141+
*/
142+
void heap_caps_get_info( multi_heap_info_t *info, uint32_t caps );
143+
144+
145+
/**
146+
* @brief Print a summary of all memory with the given capabilities.
147+
*
148+
* Calls multi_heap_info() on all heaps which share the given capabilities, and
149+
* prints a two-line summary for each, then a total summary.
150+
*
151+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
152+
* of memory
153+
*
154+
*/
155+
void heap_caps_print_heap_info( uint32_t caps );
156+
157+
/**
158+
* @brief Check integrity of all heaps with the given capabilities.
159+
*
160+
* Calls multi_heap_check() on all heaps which share the given capabilities. Optionally
161+
* print errors if the heaps are corrupt.
162+
*
163+
* Call ``heap_caps_check_integrity(MALLOC_CAP_INVALID, print_errors)`` to check
164+
* all regions' heaps.
165+
*
166+
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
167+
* of memory
168+
* @param print_errors Print specific errors if heap corruption is found.
169+
*
170+
* @return True if all heaps are valid, False if at least one heap is corrupt.
171+
*/
172+
bool heap_caps_check_integrity(uint32_t caps, bool print_errors);

‎tools/sdk/include/heap/esp_heap_caps_init.h

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

0 commit comments

Comments
 (0)