Update IDF to 3a271a4 (#735)

tools/sdk/include/heap/esp_heap_caps.h

@@ -81,6 +81,21 @@ void heap_caps_free( void *ptr);
  */
 void *heap_caps_realloc( void *ptr, size_t size, int caps);
 
+/**
+ * @brief Allocate a chunk of memory which has the given capabilities. The initialized value in the memory is set to zero.
+ *
+ * Equivalent semantics to libc calloc(), for capability-aware memory.
+ *
+ * In IDF, ``calloc(p)`` is equivalent to ``heaps_caps_calloc(p, MALLOC_CAP_8BIT)``.
+ *
+ * @param n    Number of continuing chunks of memory to allocate
+ * @param size Size, in bytes, of a chunk 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_calloc(size_t n, size_t size, uint32_t caps);
 
 /**
  * @brief Get the total free size of all the regions that have the given capabilities
@@ -148,7 +163,7 @@ 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
+ * 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
@@ -157,14 +172,29 @@ void heap_caps_get_info( multi_heap_info_t *info, uint32_t caps );
  */
 void heap_caps_print_heap_info( uint32_t caps );
 
+/**
+ * @brief Check integrity of all heap memory in the system.
+ *
+ * Calls multi_heap_check on all heaps. Optionally print errors if heaps are corrupt.
+ *
+ * Calling this function is equivalent to calling heap_caps_check_integrity
+ * with the caps argument set to MALLOC_CAP_INVALID.
+ *
+ * @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_all(bool print_errors);
+
 /**
  * @brief Check integrity of all heaps with the given capabilities.
  *
- * Calls multi_heap_check() on all heaps which share the given capabilities. Optionally
+ * 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.
+ * See also heap_caps_check_integrity_all to check all heap memory
+ * in the system and heap_caps_check_integrity_addr to check memory
+ * around a single address.
  *
  * @param caps        Bitwise OR of MALLOC_CAP_* flags indicating the type
  *                    of memory
@@ -174,7 +204,28 @@ void heap_caps_print_heap_info( uint32_t caps );
  */
 bool heap_caps_check_integrity(uint32_t caps, bool print_errors);
 
-
+/**
+ * @brief Check integrity of heap memory around a given address.
+ *
+ * This function can be used to check the integrity of a single region of heap memory,
+ * which contains the given address.
+ *
+ * This can be useful if debugging heap integrity for corruption at a known address,
+ * as it has a lower overhead than checking all heap regions. Note that if the corrupt
+ * address moves around between runs (due to timing or other factors) then this approach
+ * won't work and you should call heap_caps_check_integrity or
+ * heap_caps_check_integrity_all instead.
+ *
+ * @note The entire heap region around the address is checked, not only the adjacent
+ * heap blocks.
+ *
+ * @param addr Address in memory. Check for corruption in region containing this address.
+ * @param print_errors Print specific errors if heap corruption is found.
+ *
+ * @return True if the heap containing the specified address is valid,
+ * False if at least one heap is corrupt or the address doesn't belong to a heap region.
+ */
+bool heap_caps_check_integrity_addr(intptr_t addr, bool print_errors);
 
 /**
  * @brief Enable malloc() in external memory and set limit below which 
@@ -188,3 +239,40 @@ bool heap_caps_check_integrity(uint32_t caps, bool print_errors);
  * @param limit       Limit, in bytes.
  */
 void heap_caps_malloc_extmem_enable(size_t limit);
+
+/**
+ * @brief Allocate a chunk of memory as preference in decreasing order.
+ *
+ * @attention The variable parameters are bitwise OR of MALLOC_CAP_* flags indicating the type of memory.
+ *            This API prefers to allocate memory with the first parameter. If failed, allocate memory with
+ *            the next parameter. It will try in this order until allocating a chunk of memory successfully
+ *            or fail to allocate memories with any of the parameters.
+ *
+ * @param size Size, in bytes, of the amount of memory to allocate
+ * @param num Number of variable paramters
+ *
+ * @return A pointer to the memory allocated on success, NULL on failure
+ */
+void *heap_caps_malloc_prefer( size_t size, size_t num, ... );
+
+/**
+ * @brief Allocate a chunk of memory as preference in decreasing order.
+ *
+ * @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 num Number of variable paramters
+ *
+ * @return Pointer to a new buffer of size 'size', or NULL if allocation failed.
+ */
+void *heap_caps_realloc_prefer( void *ptr, size_t size, size_t num, ... );
+
+/**
+ * @brief Allocate a chunk of memory as preference in decreasing order.
+ *
+ * @param n    Number of continuing chunks of memory to allocate
+ * @param size Size, in bytes, of a chunk of memory to allocate
+ * @param num  Number of variable paramters
+ *
+ * @return A pointer to the memory allocated on success, NULL on failure
+ */
+void *heap_caps_calloc_prefer( size_t n, size_t size, size_t num, ... );

tools/sdk/include/heap/multi_heap.h

@@ -134,7 +134,7 @@ 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().
+ * Equivalent to the minimum_free_bytes member returned by multi_heap_get_info().
  *
  * Returns the lifetime "low water mark" of possible values returned from multi_free_heap_size(), for the specified
  * heap.
@@ -144,7 +144,7 @@ size_t multi_heap_free_size(multi_heap_handle_t heap);
  */
 size_t multi_heap_minimum_free_size(multi_heap_handle_t heap);
 
-/** @brief Structure to access heap metadata via multi_get_heap_info */
+/** @brief Structure to access heap metadata via multi_heap_get_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.