refactor(esp_tee): Refactor the TEE heap-related APIs

components/esp_tee/subproject/main/common/multi_heap.c

@@ -34,12 +34,12 @@ static void assert_valid_block(const heap_t *heap, const block_header_t *block)
                       (uintptr_t)ptr);
 }
 
-int tee_heap_register(void *start_ptr, size_t size)
+esp_err_t esp_tee_heap_init(void *start_ptr, size_t size)
 {
     assert(start_ptr);
     if (size < (sizeof(heap_t))) {
-        //Region too small to be a heap.
+        // Region too small to be a heap.
-        return -1;
+        return ESP_ERR_INVALID_SIZE;
     }
 
     heap_t *result = (heap_t *)start_ptr;
@@ -50,7 +50,7 @@ int tee_heap_register(void *start_ptr, size_t size)
 
     result->heap_data = tlsf_create_with_pool(start_ptr + sizeof(heap_t), size, max_bytes);
     if (result->heap_data == NULL) {
-        return -1;
+        return ESP_FAIL;
     }
 
     result->lock = NULL;
@@ -60,10 +60,10 @@ int tee_heap_register(void *start_ptr, size_t size)
 
     tee_heap = (multi_heap_handle_t)result;
 
-    return 0;
+    return ESP_OK;
 }
 
-void *tee_heap_malloc(size_t size)
+void *esp_tee_heap_malloc(size_t size)
 {
     if (tee_heap == NULL || size == 0) {
         return NULL;
@@ -81,17 +81,17 @@ void *tee_heap_malloc(size_t size)
     return result;
 }
 
-void *tee_heap_calloc(size_t n, size_t size)
+void *esp_tee_heap_calloc(size_t n, size_t size)
 {
     size_t reg_size = n * size;
-    void *ptr = tee_heap_malloc(reg_size);
+    void *ptr = esp_tee_heap_malloc(reg_size);
     if (ptr != NULL) {
         memset(ptr, 0x00, reg_size);
     }
     return ptr;
 }
 
-void *tee_heap_aligned_alloc(size_t size, size_t alignment)
+void *esp_tee_heap_aligned_alloc(size_t size, size_t alignment)
 {
     if (tee_heap == NULL || size == 0) {
         return NULL;
@@ -114,7 +114,7 @@ void *tee_heap_aligned_alloc(size_t size, size_t alignment)
     return result;
 }
 
-void tee_heap_free(void *p)
+void esp_tee_heap_free(void *p)
 {
     if (tee_heap == NULL || p == NULL) {
         return;
@@ -129,25 +129,27 @@ void tee_heap_free(void *p)
 
 void *malloc(size_t size)
 {
-    return tee_heap_malloc(size);
+    return esp_tee_heap_malloc(size);
 }
 
 void *calloc(size_t n, size_t size)
 {
-    return tee_heap_calloc(n, size);
+    return esp_tee_heap_calloc(n, size);
 }
 
 void free(void *ptr)
 {
-    tee_heap_free(ptr);
+    esp_tee_heap_free(ptr);
 }
 
-void tee_heap_dump_free_size(void)
+size_t esp_tee_heap_get_free_size(void)
 {
-    if (tee_heap == NULL) {
+    return tee_heap->free_bytes;
-        return;
+}
-    }
+
-    printf("Free: %uB | Minimum free: %uB\n", tee_heap->free_bytes, tee_heap->minimum_free_bytes);
+size_t esp_tee_heap_get_min_free_size(void)
+{
+    return tee_heap->minimum_free_bytes;
 }
 
 static bool tee_heap_dump_tlsf(void* ptr, size_t size, int used, void* user)
@@ -160,14 +162,10 @@ static bool tee_heap_dump_tlsf(void* ptr, size_t size, int used, void* user)
     return true;
 }
 
-void tee_heap_dump_info(void)
+void esp_tee_heap_dump_info(void)
 {
-    if (tee_heap == NULL) {
+    printf("Showing data for TEE heap: %p (%uB)\n", (void *)tee_heap, tee_heap->pool_size);
-        return;
+    tlsf_walk_pool(tlsf_get_pool(tee_heap->heap_data), heap_dump_tlsf, NULL);
-    }
-    printf("Showing data for TEE heap: %p\n", (void *)tee_heap);
-    tee_heap_dump_free_size();
-    tlsf_walk_pool(tlsf_get_pool(tee_heap->heap_data), tee_heap_dump_tlsf, NULL);
 }
 
 /* Definitions for functions from the heap component, used in files shared with ESP-IDF */
@@ -175,13 +173,13 @@ void tee_heap_dump_info(void)
 void *heap_caps_malloc(size_t alignment, size_t size, uint32_t caps)
 {
     (void) caps;
-    return tee_heap_malloc(size);
+    return esp_tee_heap_malloc(size);
 }
 
 void *heap_caps_aligned_alloc(size_t alignment, size_t size, uint32_t caps)
 {
     (void) caps;
-    return tee_heap_aligned_alloc(size, alignment);
+    return esp_tee_heap_aligned_alloc(size, alignment);
 }
 
 void *heap_caps_aligned_calloc(size_t alignment, size_t n, size_t size, uint32_t caps)
@@ -189,7 +187,7 @@ void *heap_caps_aligned_calloc(size_t alignment, size_t n, size_t size, uint32_t
     (void) caps;
     uint32_t reg_size = n * size;
 
-    void *ptr = tee_heap_aligned_alloc(reg_size, alignment);
+    void *ptr = esp_tee_heap_aligned_alloc(reg_size, alignment);
     if (ptr != NULL) {
         memset(ptr, 0x00, reg_size);
     }

components/esp_tee/subproject/main/core/esp_tee_init.c

@@ -132,7 +132,7 @@ void __attribute__((noreturn)) esp_tee_init(uint32_t ree_entry_addr, uint32_t re
     tee_init_app_config();
 
     /* TEE Secure World heap initialization. */
-    assert(tee_heap_register(((void *)&_tee_heap_start), TEE_HEAP_SIZE) == 0);
+    assert(esp_tee_heap_init(((void *)&_tee_heap_start), TEE_HEAP_SIZE) == ESP_OK);
 
     /* SoC specific secure initialization. */
     esp_tee_soc_secure_sys_init();

components/esp_tee/subproject/main/include/multi_heap.h

@@ -1,11 +1,11 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
 #include <string.h>
-#include "tlsf.h"
+#include "esp_err.h"
 
 /* multi_heap is a heap implementation for handling multiple
    heterogeneous heaps in a single program.
@@ -29,70 +29,89 @@ typedef struct multi_heap_info heap_t;
 /** @brief Opaque handle to a registered heap */
 typedef struct multi_heap_info *multi_heap_handle_t;
 
-/** @brief malloc() a buffer in a given heap
+/** @brief Initialize the TEE heap
  *
- * Semantics are the same as standard malloc(), only the returned buffer will be allocated in the TEE heap.
+ * This function initialises the TEE heap at the specified address, and
+ * sets up a handle for future heap operations.
  *
- * @param size Size of desired buffer.
+ * @param start Start address of the memory to use for the TEE heap.
+ * @param size Size (in bytes) of the TEE heap.
  *
- * @return Pointer to new memory, or NULL if allocation fails.
+ * @return ESP_OK on success, or an `esp_err_t` error code on failure.
  */
-void *tee_heap_malloc(size_t size);
+esp_err_t esp_tee_heap_init(void *start, size_t size);
-
-/** @brief calloc() a buffer in a given heap
- *
- * Semantics are the same as standard calloc(), only the returned buffer will be allocated in the TEE heap.
- *
- * @param size Size of desired buffer.
- *
- * @return Pointer to new memory, or NULL if allocation fails.
- */
-void *tee_heap_calloc(size_t n, size_t size);
 
 /**
- * @brief allocate a chunk of memory with specific alignment
+ * @brief Allocate a buffer (malloc) in the TEE heap
  *
- * @param heap  Handle to a registered heap.
+ * This function allocates a buffer of the specified size in the TEE heap.
- * @param size  size in bytes of memory chunk
+ * The semantics are the same as the standard malloc().
- * @param alignment  how the memory must be aligned
  *
- * @return pointer to the memory allocated, NULL on failure
+ * @param size The size of the desired buffer in bytes.
+ *
+ * @return A pointer to the newly allocated memory, or NULL if the allocation fails.
  */
-void *tee_heap_aligned_alloc(size_t size, size_t alignment);
+void *esp_tee_heap_malloc(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 TEE heap.
- *
- * @param p NULL, or a pointer previously returned from multi_heap_malloc() or multi_heap_realloc() for the same heap.
- */
-void tee_heap_free(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.
- */
-int tee_heap_register(void *start, size_t size);
 
 /**
- * @brief Dump free and minimum free TEE heap information to stdout
+ * @brief Allocate and zero-initialize (calloc) a buffer in the TEE heap
  *
+ * This function allocates a buffer for an array of 'n' elements, each of 'size' bytes,
+ * and initializes all bytes in the allocated storage to zero. The semantics are the same
+ * as the standard calloc().
+ *
+ * @param n The number of elements to allocate.
+ * @param size The size of each element in bytes.
+ *
+ * @return A pointer to the newly allocated and zero-initialized memory, or NULL if the allocation fails.
  */
-void tee_heap_dump_free_size(void);
+void *esp_tee_heap_calloc(size_t n, size_t size);
 
-/** @brief Dump TEE heap information to stdout
+/**
+ * @brief Allocate a memory chunk with specific alignment in the TEE heap
  *
- * For debugging purposes, this function dumps information about every block in the heap to stdout.
+ * This function allocates a chunk of memory of the specified size with the specified alignment
+ * in the TEE heap.
  *
+ * @param size The size in bytes of the memory chunk.
+ * @param alignment The alignment requirement for the memory chunk.
+ *
+ * @return A pointer to the allocated memory, or NULL if the allocation fails.
  */
-void tee_heap_dump_info(void);
+void *esp_tee_heap_aligned_alloc(size_t size, size_t alignment);
+
+/**
+ * @brief Free a buffer in the TEE heap
+ *
+ * This function frees a buffer that was previously allocated in the TEE heap.
+ * The semantics are the same as the standard free().
+ *
+ * @param p A pointer to the memory to be freed, or NULL. The pointer must have been
+ *          returned from esp_tee_heap_malloc(), esp_tee_heap_calloc(), or esp_tee_heap_aligned_alloc().
+ */
+void esp_tee_heap_free(void *p);
+
+/**
+ * @brief Get the size of available TEE heap
+ *
+ * @return Available TEE heap size, in bytes
+ */
+size_t esp_tee_heap_get_free_size(void);
+
+/**
+ * @brief Get the minimum TEE heap that has ever been available
+ *
+ * @return Minimum free TEE heap ever available, in bytes
+ */
+size_t esp_tee_heap_get_min_free_size(void);
+
+/**
+ * @brief Dump info about the entire structure of the TEE heap
+ *
+ * This function outputs detailed information about every block in the TEE heap to stdout.
+ * (Intended for debugging purposes)
+ */
+void esp_tee_heap_dump_info(void);
 
 #ifdef __cplusplus
 }

components/esp_tee/test_apps/tee_test_fw/components/test_sec_srv/src/test_dummy_srv.c

@@ -1,16 +1,19 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 #include "secure_service_num.h"
-#include "esp_tee.h"
-#include "esp_err.h"
 #include "esp_rom_sys.h"
 #include "esp_attr.h"
 
+#include "multi_heap.h"
+
 void NOINLINE_ATTR _ss_dummy_secure_service(int a, int b, int c, int d, int e, int f, int g, int h, int *i)
 {
     esp_rom_printf("Dummy secure service\n");
     *i = a + b + c + d + e + f + g + h;
+
+    esp_rom_printf("[TEE] Heap: Free - %uB | Min free - %uB\n", esp_tee_heap_get_free_size(), esp_tee_heap_get_min_free_size());
+    esp_tee_heap_dump_info();
 }