diff --git a/tools/sdk/include/heap/esp_heap_alloc_caps.h b/tools/sdk/include/heap/esp_heap_alloc_caps.h new file mode 100644 index 00000000..f92e92e3 --- /dev/null +++ b/tools/sdk/include/heap/esp_heap_alloc_caps.h @@ -0,0 +1,35 @@ +// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +#pragma once +#warning "This header is deprecated, please use functions defined in esp_heap_caps.h instead." +#include "esp_heap_caps.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* Deprecated FreeRTOS-style esp_heap_alloc_caps.h functions follow */ + +/* Please use heap_caps_malloc() instead of this function */ +void *pvPortMallocCaps(size_t xWantedSize, uint32_t caps) asm("heap_caps_malloc") __attribute__((deprecated)); + +/* Please use heap_caps_get_minimum_free_heap_size() instead of this function */ +size_t xPortGetMinimumEverFreeHeapSizeCaps( uint32_t caps ) asm("heap_caps_get_minimum_free_heap_size") __attribute__((deprecated)); + +/* Please use heap_caps_get_free_size() instead of this function */ +size_t xPortGetFreeHeapSizeCaps( uint32_t caps ) asm("heap_caps_get_free_heap_size") __attribute__((deprecated)); + +#ifdef __cplusplus +} +#endif diff --git a/tools/sdk/include/heap/esp_heap_caps.h b/tools/sdk/include/heap/esp_heap_caps.h new file mode 100644 index 00000000..2b2eb579 --- /dev/null +++ b/tools/sdk/include/heap/esp_heap_caps.h @@ -0,0 +1,172 @@ +// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +#pragma once + +#include +#include +#include "multi_heap.h" + +/** + * @brief Flags to indicate the capabilities of the various memory systems + */ +#define MALLOC_CAP_EXEC (1<<0) ///< Memory must be able to run executable code +#define MALLOC_CAP_32BIT (1<<1) ///< Memory must allow for aligned 32-bit data accesses +#define MALLOC_CAP_8BIT (1<<2) ///< Memory must allow for 8/16/...-bit data accesses +#define MALLOC_CAP_DMA (1<<3) ///< Memory must be able to accessed by DMA +#define MALLOC_CAP_PID2 (1<<4) ///< Memory must be mapped to PID2 memory space (PIDs are not currently used) +#define MALLOC_CAP_PID3 (1<<5) ///< Memory must be mapped to PID3 memory space (PIDs are not currently used) +#define MALLOC_CAP_PID4 (1<<6) ///< Memory must be mapped to PID4 memory space (PIDs are not currently used) +#define MALLOC_CAP_PID5 (1<<7) ///< Memory must be mapped to PID5 memory space (PIDs are not currently used) +#define MALLOC_CAP_PID6 (1<<8) ///< Memory must be mapped to PID6 memory space (PIDs are not currently used) +#define MALLOC_CAP_PID7 (1<<9) ///< Memory must be mapped to PID7 memory space (PIDs are not currently used) +#define MALLOC_CAP_SPISRAM (1<<10) ///< Memory must be in SPI SRAM +#define MALLOC_CAP_INVALID (1<<31) ///< Memory can't be used / list end marker + +/** + * @brief Allocate a chunk of memory which has the given capabilities + * + * Equivalent semantics to libc malloc(), for capability-aware memory. + * + * In IDF, ``malloc(p)`` is equivalent to ``heaps_caps_malloc(p, MALLOC_CAP_8BIT)``. + * + * @param size Size, in bytes, of the amount of memory to allocate + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory to be returned + * + * @return A pointer to the memory allocated on success, NULL on failure + */ +void *heap_caps_malloc(size_t size, uint32_t caps); + +/** + * @brief Free memory previously allocated via heap_caps_malloc() or heap_caps_realloc(). + * + * Equivalent semantics to libc free(), for capability-aware memory. + * + * In IDF, ``free(p)`` is equivalent to ``heap_caps_free(p)``. + * + * @param ptr Pointer to memory previously returned from heap_caps_malloc() or heap_caps_realloc(). Can be NULL. + */ +void heap_caps_free( void *ptr); + +/** + * @brief Reallocate memory previously allocated via heaps_caps_malloc() or heaps_caps_realloc(). + * + * Equivalent semantics to libc realloc(), for capability-aware memory. + * + * In IDF, ``realloc(p, s)`` is equivalent to ``heap_caps_realloc(p, s, MALLOC_CAP_8BIT)``. + * + * 'caps' parameter can be different to the capabilities that any original 'ptr' was allocated with. In this way, + * realloc can be used to "move" a buffer if necessary to ensure it meets a new set of capabilities. + * + * @param ptr Pointer to previously allocated memory, or NULL for a new allocation. + * @param size Size of the new buffer requested, or 0 to free the buffer. + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory desired for the new allocation. + * + * @return Pointer to a new buffer of size 'size' with capabilities 'caps', or NULL if allocation failed. + */ +void *heap_caps_realloc( void *ptr, size_t size, int caps); + + +/** + * @brief Get the total free size of all the regions that have the given capabilities + * + * This function takes all regions capable of having the given capabilities allocated in them + * and adds up the free space they have. + * + * Note that because of heap fragmentation it is probably not possible to allocate a single block of memory + * of this size. Use heap_caps_get_largest_free_block() for this purpose. + + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory + * + * @return Amount of free bytes in the regions + */ +size_t heap_caps_get_free_size( uint32_t caps ); + + +/** + * @brief Get the total minimum free memory of all regions with the given capabilities + * + * This adds all the low water marks of the regions capable of delivering the memory + * with the given capabilities. + * + * Note the result may be less than the global all-time minimum available heap of this kind, as "low water marks" are + * tracked per-region. Individual regions' heaps may have reached their "low water marks" at different points in time. However + * this result still gives a "worst case" indication for all-time minimum free heap. + * + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory + * + * @return Amount of free bytes in the regions + */ +size_t heap_caps_get_minimum_free_size( uint32_t caps ); + +/** + * @brief Get the largest free block of memory able to be allocated with the given capabilities. + * + * Returns the largest value of ``s`` for which ``heap_caps_malloc(s, caps)`` will succeed. + * + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory + * + * @return Size of largest free block in bytes. + */ +size_t heap_caps_get_largest_free_block( uint32_t caps ); + + +/** + * @brief Get heap info for all regions with the given capabilities. + * + * Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggregate + * across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except that + * ``minimum_free_bytes`` has the same caveats described in heap_caps_get_minimum_free_size(). + * + * @param info Pointer to a structure which will be filled with relevant + * heap metadata. + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory + * + */ +void heap_caps_get_info( multi_heap_info_t *info, uint32_t caps ); + + +/** + * @brief Print a summary of all memory with the given capabilities. + * + * Calls multi_heap_info() on all heaps which share the given capabilities, and + * prints a two-line summary for each, then a total summary. + * + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory + * + */ +void heap_caps_print_heap_info( uint32_t caps ); + +/** + * @brief Check integrity of all heaps with the given capabilities. + * + * Calls multi_heap_check() on all heaps which share the given capabilities. Optionally + * print errors if the heaps are corrupt. + * + * Call ``heap_caps_check_integrity(MALLOC_CAP_INVALID, print_errors)`` to check + * all regions' heaps. + * + * @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type + * of memory + * @param print_errors Print specific errors if heap corruption is found. + * + * @return True if all heaps are valid, False if at least one heap is corrupt. + */ +bool heap_caps_check_integrity(uint32_t caps, bool print_errors); diff --git a/tools/sdk/include/heap/esp_heap_caps_init.h b/tools/sdk/include/heap/esp_heap_caps_init.h new file mode 100644 index 00000000..b29e7852 --- /dev/null +++ b/tools/sdk/include/heap/esp_heap_caps_init.h @@ -0,0 +1,83 @@ +// Copyright 2017 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +#pragma once + +#include "esp_err.h" +#include "esp_heap_caps.h" +#include "soc/soc_memory_layout.h" + +/** + * @brief Initialize the capability-aware heap allocator. + * + * This is called once in the IDF startup code. Do not call it + * at other times. + */ +void heap_caps_init(); + +/** + * @brief Enable heap(s) in memory regions where the startup stacks are located. + * + * On startup, the pro/app CPUs have a certain memory region they use as stack, so we + * cannot do allocations in the regions these stack frames are. When FreeRTOS is + * completely started, they do not use that memory anymore and heap(s) there can + * be enabled. + */ +void heap_caps_enable_nonos_stack_heaps(); + +/** + * @brief Add a region of memory to the collection of heaps at runtime. + * + * Most memory regions are defined in soc_memory_layout.c for the SoC, + * and are registered via heap_caps_init(). Some regions can't be used + * immediately and are later enabled via heap_caps_enable_nonos_stack_heaps(). + * + * Call this function to add a region of memory to the heap at some later time. + * + * This function does not consider any of the "reserved" regions or other data in soc_memory_layout, caller needs to + * consider this themselves. + * + * All memory within the region specified by start & end parameters must be otherwise unused. + * + * The capabilities of the newly registered memory will be determined by the start address, as looked up in the regions + * specified in soc_memory_layout.c. + * + * Use heap_caps_add_region_with_caps() to register a region with custom capabilities. + * + * @param start Start address of new region. + * @param end End address of new region. + * + * @return ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is invalid, ESP_ERR_NOT_FOUND if the + * specified start address doesn't reside in a known region, or any error returned by heap_caps_add_region_with_caps(). + */ +esp_err_t heap_caps_add_region(intptr_t start, intptr_t end); + + +/** + * @brief Add a region of memory to the collection of heaps at runtime, with custom capabilities. + * + * Similar to heap_caps_add_region(), only custom memory capabilities are specified by the caller. + * + * @param caps Ordered array of capability masks for the new region, in order of priority. Must have length + * SOC_MEMORY_TYPE_NO_PRIOS. Does not need to remain valid after the call returns. + * @param start Start address of new region. + * @param end End address of new region. + * + * @return ESP_OK on success, ESP_ERR_INVALID_ARG if a parameter is invalid, ESP_ERR_NO_MEM if no + * memory to register new heap. + */ +esp_err_t heap_caps_add_region_with_caps(const uint32_t caps[], intptr_t start, intptr_t end); + + + + diff --git a/tools/sdk/include/heap/esp_heap_trace.h b/tools/sdk/include/heap/esp_heap_trace.h new file mode 100644 index 00000000..24b5c60f --- /dev/null +++ b/tools/sdk/include/heap/esp_heap_trace.h @@ -0,0 +1,136 @@ +// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +#pragma once + +#include "sdkconfig.h" +#include +#include + +#if !defined(CONFIG_HEAP_TRACING) && !defined(HEAP_TRACE_SRCFILE) +#warning "esp_heap_trace.h is included but heap tracing is disabled in menuconfig, functions are no-ops" +#endif + +#ifndef CONFIG_HEAP_TRACING_STACK_DEPTH +#define CONFIG_HEAP_TRACING_STACK_DEPTH 0 +#endif + +typedef enum { + HEAP_TRACE_ALL, + HEAP_TRACE_LEAKS, +} heap_trace_mode_t; + +/** + * @brief Trace record data type. Stores information about an allocated region of memory. + */ +typedef struct { + uint32_t ccount; ///< CCOUNT of the CPU when the allocation was made. LSB (bit value 1) is the CPU number (0 or 1). */ + void *address; ///< Address which was allocated + size_t size; ///< Size of the allocation + void *alloced_by[CONFIG_HEAP_TRACING_STACK_DEPTH]; ///< Call stack of the caller which allocated the memory. + void *freed_by[CONFIG_HEAP_TRACING_STACK_DEPTH]; ///< Call stack of the caller which freed the memory (all zero if not freed.) +} heap_trace_record_t; + +/** + * @brief Initialise heap tracing in standalone mode. + * @note Standalone mode is the only mode currently supported. + * + * This function must be called before any other heap tracing functions. + * + * To disable heap tracing and allow the buffer to be freed, stop tracing and then call heap_trace_init_standalone(NULL, 0); + * + * @param record_buffer Provide a buffer to use for heap trace data. Must remain valid any time heap tracing is enabled, meaning + * it must be allocated from internal memory not in PSRAM. + * @param num_records Size of the heap trace buffer, as number of record structures. + * @return + * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. + * - ESP_ERR_INVALID_STATE Heap tracing is currently in progress. + * - ESP_OK Heap tracing initialised successfully. + */ +esp_err_t heap_trace_init_standalone(heap_trace_record_t *record_buffer, size_t num_records); + +/** + * @brief Start heap tracing. All heap allocations & frees will be traced, until heap_trace_stop() is called. + * + * @note heap_trace_init_standalone() must be called to provide a valid buffer, before this function is called. + * + * @note Calling this function while heap tracing is running will reset the heap trace state and continue tracing. + * + * @param mode Mode for tracing. + * - HEAP_TRACE_ALL means all heap allocations and frees are traced. + * - HEAP_TRACE_LEAKS means only suspected memory leaks are traced. (When memory is freed, the record is removed from the trace buffer.) + * @return + * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. + * - ESP_ERR_INVALID_STATE A non-zero-length buffer has not been set via heap_trace_init_standalone(). + * - ESP_OK Tracing is started. + */ +esp_err_t heap_trace_start(heap_trace_mode_t mode); + +/** + * @brief Stop heap tracing. + * + * @return + * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. + * - ESP_ERR_INVALID_STATE Heap tracing was not in progress. + * - ESP_OK Heap tracing stopped.. + */ +esp_err_t heap_trace_stop(void); + +/** + * @brief Resume heap tracing which was previously stopped. + * + * Unlike heap_trace_start(), this function does not clear the + * buffer of any pre-existing trace records. + * + * The heap trace mode is the same as when heap_trace_start() was + * last called (or HEAP_TRACE_ALL if heap_trace_start() was never called). + * + * @return + * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. + * - ESP_ERR_INVALID_STATE Heap tracing was already started. + * - ESP_OK Heap tracing resumed. + */ +esp_err_t heap_trace_resume(void); + +/** + * @brief Return number of records in the heap trace buffer + * + * It is safe to call this function while heap tracing is running. + */ +size_t heap_trace_get_count(void); + +/** + * @brief Return a raw record from the heap trace buffer + * + * @note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode record indexing may + * skip entries unless heap tracing is stopped first. + * + * @param index Index (zero-based) of the record to return. + * @param[out] record Record where the heap trace record will be copied. + * @return + * - ESP_ERR_NOT_SUPPORTED Project was compiled without heap tracing enabled in menuconfig. + * - ESP_ERR_INVALID_STATE Heap tracing was not initialised. + * - ESP_ERR_INVALID_ARG Index is out of bounds for current heap trace record count. + * - ESP_OK Record returned successfully. + */ +esp_err_t heap_trace_get(size_t index, heap_trace_record_t *record); + +/** + * @brief Dump heap trace record data to stdout + * + * @note It is safe to call this function while heap tracing is running, however in HEAP_TRACE_LEAK mode the dump may skip + * entries unless heap tracing is stopped first. + * + * + */ +void heap_trace_dump(void); diff --git a/tools/sdk/include/heap/esp_ota_ops.h b/tools/sdk/include/heap/esp_ota_ops.h deleted file mode 100755 index a089a92b..00000000 --- a/tools/sdk/include/heap/esp_ota_ops.h +++ /dev/null @@ -1,178 +0,0 @@ -// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at - -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -#ifndef _OTA_OPS_H -#define _OTA_OPS_H - -#include -#include -#include -#include "esp_err.h" -#include "esp_partition.h" -#include "esp_spi_flash.h" - -#ifdef __cplusplus -extern "C" -{ -#endif - -#define OTA_SIZE_UNKNOWN 0xffffffff /*!< Used for esp_ota_begin() if new image size is unknown */ - -#define ESP_ERR_OTA_BASE 0x1500 /*!< Base error code for ota_ops api */ -#define ESP_ERR_OTA_PARTITION_CONFLICT (ESP_ERR_OTA_BASE + 0x01) /*!< Error if request was to write or erase the current running partition */ -#define ESP_ERR_OTA_SELECT_INFO_INVALID (ESP_ERR_OTA_BASE + 0x02) /*!< Error if OTA data partition contains invalid content */ -#define ESP_ERR_OTA_VALIDATE_FAILED (ESP_ERR_OTA_BASE + 0x03) /*!< Error if OTA app image is invalid */ - -/** - * @brief Opaque handle for an application OTA update - * - * esp_ota_begin() returns a handle which is then used for subsequent - * calls to esp_ota_write() and esp_ota_end(). - */ -typedef uint32_t esp_ota_handle_t; - -/** - * @brief Commence an OTA update writing to the specified partition. - - * The specified partition is erased to the specified image size. - * - * If image size is not yet known, pass OTA_SIZE_UNKNOWN which will - * cause the entire partition to be erased. - * - * On success, this function allocates memory that remains in use - * until esp_ota_end() is called with the returned handle. - * - * @param partition Pointer to info for partition which will receive the OTA update. Required. - * @param image_size Size of new OTA app image. Partition will be erased in order to receive this size of image. If 0 or OTA_SIZE_UNKNOWN, the entire partition is erased. - * @param out_handle On success, returns a handle which should be used for subsequent esp_ota_write() and esp_ota_end() calls. - - * @return - * - ESP_OK: OTA operation commenced successfully. - * - ESP_ERR_INVALID_ARG: partition or out_handle arguments were NULL, or partition doesn't point to an OTA app partition. - * - ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation. - * - ESP_ERR_OTA_PARTITION_CONFLICT: Partition holds the currently running firmware, cannot update in place. - * - ESP_ERR_NOT_FOUND: Partition argument not found in partition table. - * - ESP_ERR_OTA_SELECT_INFO_INVALID: The OTA data partition contains invalid data. - * - ESP_ERR_INVALID_SIZE: Partition doesn't fit in configured flash size. - * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. - */ -esp_err_t esp_ota_begin(const esp_partition_t* partition, size_t image_size, esp_ota_handle_t* out_handle); - -/** - * @brief Write OTA update data to partition - * - * This function can be called multiple times as - * data is received during the OTA operation. Data is written - * sequentially to the partition. - * - * @param handle Handle obtained from esp_ota_begin - * @param data Data buffer to write - * @param size Size of data buffer in bytes. - * - * @return - * - ESP_OK: Data was written to flash successfully. - * - ESP_ERR_INVALID_ARG: handle is invalid. - * - ESP_ERR_OTA_VALIDATE_FAILED: First byte of image contains invalid app image magic byte. - * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. - * - ESP_ERR_OTA_SELECT_INFO_INVALID: OTA data partition has invalid contents - */ -esp_err_t esp_ota_write(esp_ota_handle_t handle, const void* data, size_t size); - -/** - * @brief Finish OTA update and validate newly written app image. - * - * @param handle Handle obtained from esp_ota_begin(). - * - * @note After calling esp_ota_end(), the handle is no longer valid and any memory associated with it is freed (regardless of result). - * - * @return - * - ESP_OK: Newly written OTA app image is valid. - * - ESP_ERR_NOT_FOUND: OTA handle was not found. - * - ESP_ERR_INVALID_ARG: Handle was never written to. - * - ESP_ERR_OTA_VALIDATE_FAILED: OTA image is invalid (either not a valid app image, or - if secure boot is enabled - signature failed to verify.) - * - ESP_ERR_INVALID_STATE: If flash encryption is enabled, this result indicates an internal error writing the final encrypted bytes to flash. - */ -esp_err_t esp_ota_end(esp_ota_handle_t handle); - -/** - * @brief Configure OTA data for a new boot partition - * - * @note If this function returns ESP_OK, calling esp_restart() will boot the newly configured app partition. - * - * @param partition Pointer to info for partition containing app image to boot. - * - * @return - * - ESP_OK: OTA data updated, next reboot will use specified partition. - * - ESP_ERR_INVALID_ARG: partition argument was NULL or didn't point to a valid OTA partition of type "app". - * - ESP_ERR_OTA_VALIDATE_FAILED: Partition contained invalid app image. Also returned if secure boot is enabled and signature validation failed. - * - ESP_ERR_NOT_FOUND: OTA data partition not found. - * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash erase or write failed. - */ -esp_err_t esp_ota_set_boot_partition(const esp_partition_t* partition); - -/** - * @brief Get partition info of currently configured boot app - * - * If esp_ota_set_boot_partition() has been called, the partition which was set by that function will be returned. - * - * If esp_ota_set_boot_partition() has not been called, the result is usually the same as esp_ota_get_running_partition(). - * The two results are not equal if the configured boot partition does not contain a valid app (meaning that the running partition - * will be an app that the bootloader chose via fallback). - * - * If the OTA data partition is not present or not valid then the result is the first app partition found in the - * partition table. In priority order, this means: the factory app, the first OTA app slot, or the test app partition. - * - * Note that there is no guarantee the returned partition is a valid app. Use esp_image_load(ESP_IMAGE_VERIFY, ...) to verify if the - * returned partition contains a bootable image. - * - * @return Pointer to info for partition structure, or NULL if partition table is invalid or a flash read operation failed. Any returned pointer is valid for the lifetime of the application. - */ -const esp_partition_t* esp_ota_get_boot_partition(void); - - -/** - * @brief Get partition info of currently running app - * - * This function is different to esp_ota_get_boot_partition() in that - * it ignores any change of selected boot partition caused by - * esp_ota_set_boot_partition(). Only the app whose code is currently - * running will have its partition information returned. - * - * The partition returned by this function may also differ from esp_ota_get_boot_partition() if the configured boot - * partition is somehow invalid, and the bootloader fell back to a different app partition at boot. - * - * @return Pointer to info for partition structure, or NULL if no partition is found or flash read operation failed. Returned pointer is valid for the lifetime of the application. - */ -const esp_partition_t* esp_ota_get_running_partition(void); - - -/** - * @brief Return the next OTA app partition which should be written with a new firmware. - * - * Call this function to find an OTA app partition which can be passed to esp_ota_begin(). - * - * Finds next partition round-robin, starting from the current running partition. - * - * @param start_from If set, treat this partition info as describing the current running partition. Can be NULL, in which case esp_ota_get_running_partition() is used to find the currently running partition. The result of this function is never the same as this argument. - * - * @return Pointer to info for partition which should be updated next. NULL result indicates invalid OTA data partition, or that no eligible OTA app slot partition was found. - * - */ -const esp_partition_t* esp_ota_get_next_update_partition(const esp_partition_t *start_from); - -#ifdef __cplusplus -} -#endif - -#endif /* OTA_OPS_H */ diff --git a/tools/sdk/include/heap/multi_heap.h b/tools/sdk/include/heap/multi_heap.h new file mode 100644 index 00000000..1bad09a9 --- /dev/null +++ b/tools/sdk/include/heap/multi_heap.h @@ -0,0 +1,169 @@ +// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +#pragma once +#include +#include +#include + +/* multi_heap is a heap implementation for handling multiple + heterogenous heaps in a single program. + + Any contiguous block of memory can be registered as a heap. +*/ + +#ifdef __cplusplus +extern "C" { +#endif + +/** @brief Opaque handle to a registered heap */ +typedef struct multi_heap_info *multi_heap_handle_t; + +/** @brief malloc() a buffer in a given heap + * + * Semantics are the same as standard malloc(), only the returned buffer will be allocated in the specified heap. + * + * @param heap Handle to a registered heap. + * @param size Size of desired buffer. + * + * @return Pointer to new memory, or NULL if allocation fails. + */ +void *multi_heap_malloc(multi_heap_handle_t heap, size_t size); + +/** @brief free() a buffer in a given heap. + * + * Semantics are the same as standard free(), only the argument 'p' must be NULL or have been allocated in the specified heap. + * + * @param heap Handle to a registered heap. + * @param p NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap. + */ +void multi_heap_free(multi_heap_handle_t heap, void *p); + +/** @brief realloc() a buffer in a given heap. + * + * Semantics are the same as standard realloc(), only the argument 'p' must be NULL or have been allocated in the specified heap. + * + * @param heap Handle to a registered heap. + * @param p NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap. + * @param size Desired new size for buffer. + * + * @return New buffer of 'size' containing contents of 'p', or NULL if reallocation failed. + */ +void *multi_heap_realloc(multi_heap_handle_t heap, void *p, size_t size); + + +/** @brief Return the size that a particular pointer was allocated with. + * + * @param heap Handle to a registered heap. + * @param p Pointer, must have been previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap. + * + * @return Size of the memory allocated at this block. May be more than the original size argument, due + * to padding and minimum block sizes. + */ +size_t multi_heap_get_allocated_size(multi_heap_handle_t heap, void *p); + + +/** @brief Register a new heap for use + * + * This function initialises a heap at the specified address, and returns a handle for future heap operations. + * + * 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. + * + * @param start Start address of the memory to use for a new heap. + * @param size Size (in bytes) of the new heap. + * + * @return Handle of a new heap ready for use, or NULL if the heap region was too small to be initialised. + */ +multi_heap_handle_t multi_heap_register(void *start, size_t size); + + +/** @brief Associate a private lock pointer with a heap + * + * The lock argument is supplied to the MULTI_HEAP_LOCK() and MULTI_HEAP_UNLOCK() macros, defined in multi_heap_platform.h. + * + * When the heap is first registered, the associated lock is NULL. + * + * @param heap Handle to a registered heap. + * @param lock Optional pointer to a locking structure to associate with this heap. + */ +void multi_heap_set_lock(multi_heap_handle_t heap, void* lock); + +/** @brief Dump heap information to stdout + * + * For debugging purposes, this function dumps information about every block in the heap to stdout. + * + * @param heap Handle to a registered heap. + */ +void multi_heap_dump(multi_heap_handle_t heap); + +/** @brief Check heap integrity + * + * Walks the heap and checks all heap data structures are valid. If any errors are detected, an error-specific message + * can be optionally printed to stderr. Print behaviour can be overriden at compile time by defining + * MULTI_CHECK_FAIL_PRINTF in multi_heap_platform.h. + * + * @param heap Handle to a registered heap. + * @param print_errors If true, errors will be printed to stderr. + * @return true if heap is valid, false otherwise. + */ +bool multi_heap_check(multi_heap_handle_t heap, bool print_errors); + +/** @brief Return free heap size + * + * Returns the number of bytes available in the heap. + * + * Equivalent to the total_free_bytes member returned by multi_heap_get_heap_info(). + * + * Note that the heap may be fragmented, so the actual maximum size for a single malloc() may be lower. To know this + * size, see the largest_free_block member returned by multi_heap_get_heap_info(). + * + * @param heap Handle to a registered heap. + * @return Number of free bytes. + */ +size_t multi_heap_free_size(multi_heap_handle_t heap); + +/** @brief Return the lifetime minimum free heap size + * + * Equivalent to the minimum_free_bytes member returned by multi_get_heap_info(). + * + * Returns the lifetime "low water mark" of possible values returned from multi_free_heap_size(), for the specified + * heap. + * + * @param heap Handle to a registered heap. + * @return Number of free bytes. + */ +size_t multi_heap_minimum_free_size(multi_heap_handle_t heap); + +/** @brief Structure to access heap metadata via multi_get_heap_info */ +typedef struct { + size_t total_free_bytes; ///< Total free bytes in the heap. Equivalent to multi_free_heap_size(). + size_t total_allocated_bytes; ///< Total bytes allocated to data in the heap. + size_t largest_free_block; ///< Size of largest free block in the heap. This is the largest malloc-able size. + size_t minimum_free_bytes; ///< Lifetime minimum free heap size. Equivalent to multi_minimum_free_heap_size(). + size_t allocated_blocks; ///< Number of (variable size) blocks allocated in the heap. + size_t free_blocks; ///< Number of (variable size) free blocks in the heap. + size_t total_blocks; ///< Total number of (variable size) blocks in the heap. +} multi_heap_info_t; + +/** @brief Return metadata about a given heap + * + * Fills a multi_heap_info_t structure with information about the specified heap. + * + * @param heap Handle to a registered heap. + * @param info Pointer to a structure to fill with heap metadata. + */ +void multi_heap_get_info(multi_heap_handle_t heap, multi_heap_info_t *info); + +#ifdef __cplusplus +} +#endif