py/gc & port/esp32: Add MICROPY_GC_SPLIT_HEAP_AUTO flag.

projectgus · projectgus · commit 42613b911675 · 2023-08-01T17:28:02.000+10:00
- When set, the heap is automatically extended with new areas on demand,
  and shrunk if a heap area becomes empty during a GC pass or soft reset.

- Enable this new flag for esp32 port.

Tested on ESP32 GENERIC_SPIRAM and GENERIC_S3 configurations.

One possible minor bug, the size allocated for a new heap block to
fulfill a large allocation is up to 64 bytes too large - haven't
been able to 100% reconcile the heap sizing algorithm in
gc_setup_area() with the new one in gc_try_add_heap() yet. However,
figure it's better to err (slightly) too long than to risk having
the allocation slightly too small under some circumstances.

Currently there is no API to manually add a block of a given size
to the heap, although that could easily be added if necessary.

Signed-off-by: Angus Gratton &lt;angus@redyak.com.au&gt;
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -51,13 +51,20 @@ Functions
     buffers and other data. This data is useful to get a sense of how much memory
     is available to ESP-IDF and the networking stack in particular. It may shed
     some light on situations where ESP-IDF operations fail due to allocation failures.
-    The information returned is *not* useful to troubleshoot Python allocation failures,
-    use `micropython.mem_info()` instead.
 
     The capabilities parameter corresponds to ESP-IDF's ``MALLOC_CAP_XXX`` values but the
     two most useful ones are predefined as `esp32.HEAP_DATA` for data heap regions and
     `esp32.HEAP_EXEC` for executable regions as used by the native code emitter.
 
+    Free IDF heap memory in the `esp32.HEAP_DATA` region is available to be
+    automatically added to the MicroPython heap to prevent a MicroPython
+    allocation from failing. However, the information returned here is otherwise
+    *not* useful to troubleshoot Python allocation failures, use
+    `micropython.mem_info()` instead. The "max new split" value in
+    `micropython.mem_info()` output corresponds to the largest free block of
+    ESP-IDF heap that could be automatically added on demand to the MicroPython
+    heap.
+
     The return value is a list of 4-tuples, where each 4-tuple corresponds to one heap
     and contains: the total bytes, the free bytes, the largest free block, and
     the minimum free seen over time.
diff --git a/ports/esp32/gccollect.c b/ports/esp32/gccollect.c
@@ -80,3 +80,15 @@ void gc_collect(void) {
 }
 
 #endif
+
+#if MICROPY_GC_SPLIT_HEAP_AUTO
+
+size_t gc_get_max_new_split(void) {
+    // Need to allow some overhead for heap block metadata.
+    // Am choosing a conservative value as TLSF impl is a bit opaque.
+    static const size_t HEAP_METADATA_OVERHEAD = 64;
+    size_t largest = heap_caps_get_largest_free_block(MALLOC_CAP_DEFAULT);
+    return largest < HEAP_METADATA_OVERHEAD ? 0 : largest - HEAP_METADATA_OVERHEAD;
+}
+
+#endif
diff --git a/ports/esp32/main.c b/ports/esp32/main.c
@@ -100,13 +100,9 @@ void mp_task(void *pvParameter) {
         ESP_LOGE("esp_init", "can't create event loop: 0x%x\n", err);
     }
 
-    // Allocate the uPy heap using malloc and get the largest available region,
-    // limiting to 1/2 total available memory to leave memory for the OS.
-    // When SPIRAM is enabled, this will allocate from SPIRAM.
-    uint32_t caps = MALLOC_CAP_8BIT;
-    size_t heap_total = heap_caps_get_total_size(caps);
-    size_t mp_task_heap_size = MIN(heap_caps_get_largest_free_block(caps), heap_total / 2);
-    void *mp_task_heap = heap_caps_malloc(mp_task_heap_size, caps);
+    /* Heap size starts small, grows on demand */
+    const size_t mp_task_heap_size = 64 * 1024;
+    void *mp_task_heap = malloc(mp_task_heap_size);
 
 soft_reset:
     // initialise the stack pointer for the main thread
diff --git a/ports/esp32/mpconfigport.h b/ports/esp32/mpconfigport.h
@@ -68,6 +68,9 @@
 #define MICROPY_PY_THREAD_GIL               (1)
 #define MICROPY_PY_THREAD_GIL_VM_DIVISOR    (32)
 
+#define MICROPY_GC_SPLIT_HEAP               (1)
+#define MICROPY_GC_SPLIT_HEAP_AUTO          (1)
+
 // extended modules
 #ifndef MICROPY_ESPNOW
 #define MICROPY_ESPNOW                      (1)
diff --git a/py/gc.c b/py/gc.c
@@ -79,7 +79,7 @@
 #define ATB_3_IS_FREE(a) (((a) & ATB_MASK_3) == 0)
 
 #if MICROPY_GC_SPLIT_HEAP
-#define NEXT_AREA(area) (area->next)
+#define NEXT_AREA(area) ((area)->next)
 #else
 #define NEXT_AREA(area) (NULL)
 #endif
@@ -129,7 +129,13 @@ STATIC void gc_setup_area(mp_state_mem_area_t *area, void *start, void *end) {
     // => T = A * (1 + BLOCKS_PER_ATB / BLOCKS_PER_FTB + BLOCKS_PER_ATB * BYTES_PER_BLOCK)
     size_t total_byte_len = (byte *)end - (byte *)start;
     #if MICROPY_ENABLE_FINALISER
-    area->gc_alloc_table_byte_len = (total_byte_len - ALLOC_TABLE_GAP_BYTE) * MP_BITS_PER_BYTE / (MP_BITS_PER_BYTE + MP_BITS_PER_BYTE * BLOCKS_PER_ATB / BLOCKS_PER_FTB + MP_BITS_PER_BYTE * BLOCKS_PER_ATB * BYTES_PER_BLOCK);
+    area->gc_alloc_table_byte_len = (total_byte_len - ALLOC_TABLE_GAP_BYTE)
+        * MP_BITS_PER_BYTE
+        / (
+            MP_BITS_PER_BYTE
+            + MP_BITS_PER_BYTE * BLOCKS_PER_ATB / BLOCKS_PER_FTB
+            + MP_BITS_PER_BYTE * BLOCKS_PER_ATB * BYTES_PER_BLOCK
+           );
     #else
     area->gc_alloc_table_byte_len = (total_byte_len - ALLOC_TABLE_GAP_BYTE) / (1 + MP_BITS_PER_BYTE / 2 * BYTES_PER_BLOCK);
     #endif
@@ -164,11 +170,19 @@ STATIC void gc_setup_area(mp_state_mem_area_t *area, void *start, void *end) {
     #endif
 
     DEBUG_printf("GC layout:\n");
-    DEBUG_printf("  alloc table at %p, length " UINT_FMT " bytes, " UINT_FMT " blocks\n", MP_STATE_MEM(area).gc_alloc_table_start, MP_STATE_MEM(area).gc_alloc_table_byte_len, MP_STATE_MEM(area).gc_alloc_table_byte_len * BLOCKS_PER_ATB);
+    DEBUG_printf("  alloc table at %p, length " UINT_FMT " bytes, "
+        UINT_FMT " blocks\n",
+        area->gc_alloc_table_start, area->gc_alloc_table_byte_len,
+        area->gc_alloc_table_byte_len * BLOCKS_PER_ATB);
     #if MICROPY_ENABLE_FINALISER
-    DEBUG_printf("  finaliser table at %p, length " UINT_FMT " bytes, " UINT_FMT " blocks\n", MP_STATE_MEM(area).gc_finaliser_table_start, gc_finaliser_table_byte_len, gc_finaliser_table_byte_len * BLOCKS_PER_FTB);
+    DEBUG_printf("  finaliser table at %p, length " UINT_FMT " bytes, "
+        UINT_FMT " blocks\n", area->gc_finaliser_table_start,
+        gc_finaliser_table_byte_len,
+        gc_finaliser_table_byte_len * BLOCKS_PER_FTB);
     #endif
-    DEBUG_printf("  pool at %p, length " UINT_FMT " bytes, " UINT_FMT " blocks\n", MP_STATE_MEM(area).gc_pool_start, gc_pool_block_len * BYTES_PER_BLOCK, gc_pool_block_len);
+    DEBUG_printf("  pool at %p, length " UINT_FMT " bytes, "
+        UINT_FMT " blocks\n", area->gc_pool_start,
+        gc_pool_block_len * BYTES_PER_BLOCK, gc_pool_block_len);
 }
 
 void gc_init(void *start, void *end) {
@@ -221,6 +235,106 @@ void gc_add(void *start, void *end) {
     // Add this area to the linked list
     prev_area->next = area;
 }
+
+#if MICROPY_GC_SPLIT_HEAP_AUTO
+// Try to automatically add a heap area large enough to
+// fulfill 'failed_alloc'
+STATIC bool gc_try_add_heap(size_t failed_alloc) {
+    // Equation to find a heap large enough to hold failed_alloc is derived from
+    // the equation for gc_setup_area(), above:
+    //
+    // T = A + F + P
+    // P == failed_alloc rounded up to next block size
+    // A = P / (BLOCKS_PER_ATB * BYTES_PER_BLOCK
+    // F = A * BLOCKS_PER_ATB / BLOCKS_PER_FTB
+    size_t p_blocks = (failed_alloc + BYTES_PER_BLOCK - 1) / BYTES_PER_BLOCK;
+    // Round up to use full allocation block(s)
+    p_blocks = (p_blocks + BLOCKS_PER_ATB - 1) & ~(BLOCKS_PER_ATB - 1);
+
+    // Unclear why these extra blocks needed, but necessary for the new heap
+    // pool to be large enough
+    p_blocks += BLOCKS_PER_ATB;
+
+    size_t p = p_blocks * BYTES_PER_BLOCK; // should match gc_pool_end - gc_pool_start
+
+    size_t a = p_blocks / BLOCKS_PER_ATB;
+
+    #if MICROPY_ENABLE_FINALISER
+    // should match gc_finaliser_table_byte_len
+    size_t f = (p_blocks + BLOCKS_PER_FTB - 1) / BLOCKS_PER_FTB;
+    #else
+    size_t f = 0;
+    #endif
+
+    // T = ... (plus implementation overheads)
+    size_t needed = p + a + f + sizeof(mp_state_mem_area_t) + ALLOC_TABLE_GAP_BYTE;
+
+    size_t avail = gc_get_max_new_split();
+
+    DEBUG_printf("gc_try_add_heap failed_alloc " UINT_FMT ", "
+        "p " UINT_FMT " bytes " UINT_FMT " blocks, "
+        "a " UINT_FMT " bytes, "
+        "f " UINT_FMT " bytes, "
+        "needed " UINT_FMT ", avail " UINT_FMT " bytes \n",
+        failed_alloc,
+        p,
+        p_blocks,
+        a,
+        f,
+        needed,
+        avail);
+
+    if (avail < needed) {
+        return false; // Can't fit
+    }
+
+    // Deciding how much to grow the total heap by each time is tricky:
+    //
+    // - Grow by too small amounts, leads to heap fragmentation issues.
+    //
+    // - Grow by too large amounts, may lead to system heap running out of
+    //   space.
+    //
+    // Currently, this implementation is:
+    //
+    // - At minimum, aim to double the total heap size each time we add a new
+    //   heap.  i.e. without any large single allocations, total size will be
+    //   64KB -> 128KB -> 256KB -> 512KB -> 1MB, etc
+    //
+    // - If the failed allocation is too large to fit in that size, the new
+    //   heap is made exactly large enough for that allocation. Future growth
+    //   will double the total heap size again.
+    //
+    // - If the new heap won't fit in the available free space, add the largest
+    //   new heap that will fit (this may lead to failed system heap allocations
+    //   elsewhere, but some allocation will likely fail in this circumstance!)
+    size_t total_heap = 0;
+    for (mp_state_mem_area_t *area = &MP_STATE_MEM(area);
+         area != NULL;
+         area = NEXT_AREA(area)) {
+        total_heap += area->gc_pool_end - area->gc_alloc_table_start;
+        total_heap += ALLOC_TABLE_GAP_BYTE + sizeof(mp_state_mem_area_t);
+    }
+
+    DEBUG_printf("total_heap " UINT_FMT " bytes\n", total_heap);
+
+    size_t to_alloc = MIN(avail, MAX(total_heap, needed));
+
+    mp_state_mem_area_t *new_heap = malloc(to_alloc);
+
+    DEBUG_printf("gc_try_add_heap malloc " UINT_FMT " = %p\n",
+        to_alloc, new_heap);
+
+    if (new_heap == NULL) {
+        return false;
+    }
+
+    gc_add(new_heap, (void *)new_heap + to_alloc);
+
+    return true;
+}
+#endif
+
 #endif
 
 void gc_lock(void) {
@@ -377,7 +491,13 @@ STATIC void gc_sweep(void) {
     #endif
     // free unmarked heads and their tails
     int free_tail = 0;
+    #if MICROPY_GC_SPLIT_HEAP_AUTO
+    mp_state_mem_area_t *prev_area = NULL;
+    #endif
     for (mp_state_mem_area_t *area = &MP_STATE_MEM(area); area != NULL; area = NEXT_AREA(area)) {
+        #if MICROPY_GC_SPLIT_HEAP_AUTO
+        bool area_empty = true;
+        #endif
         for (size_t block = 0; block < area->gc_alloc_table_byte_len * BLOCKS_PER_ATB; block++) {
             MICROPY_GC_HOOK_LOOP(block);
             switch (ATB_GET_KIND(area, block)) {
@@ -424,9 +544,23 @@ STATIC void gc_sweep(void) {
                 case AT_MARK:
                     ATB_MARK_TO_HEAD(area, block);
                     free_tail = 0;
+                    #if MICROPY_GC_SPLIT_HEAP_AUTO
+                    area_empty = false;
+                    #endif
                     break;
             }
         }
+
+        #if MICROPY_GC_SPLIT_HEAP_AUTO
+        // Free any empty area, aside from the first one
+        if (area_empty && prev_area != NULL) {
+            DEBUG_printf("gc_sweep free empty area %p\n", area);
+            NEXT_AREA(prev_area) = NEXT_AREA(area);
+            free(area);
+            area = prev_area;
+        }
+        prev_area = area;
+        #endif
     }
 }
 
@@ -609,6 +743,9 @@ void *gc_alloc(size_t n_bytes, unsigned int alloc_flags) {
     size_t start_block;
     size_t n_free;
     int collected = !MP_STATE_MEM(gc_auto_collect_enabled);
+    #if MICROPY_GC_SPLIT_HEAP_AUTO
+    bool added = false;
+    #endif
 
     #if MICROPY_GC_ALLOC_THRESHOLD
     if (!collected && MP_STATE_MEM(gc_alloc_amount) >= MP_STATE_MEM(gc_alloc_threshold)) {
@@ -654,6 +791,12 @@ void *gc_alloc(size_t n_bytes, unsigned int alloc_flags) {
         GC_EXIT();
         // nothing found!
         if (collected) {
+            #if MICROPY_GC_SPLIT_HEAP_AUTO
+            if (!added && gc_try_add_heap(n_bytes)) {
+                added = true;
+                continue;
+            }
+            #endif
             return NULL;
         }
         DEBUG_printf("gc_alloc(" UINT_FMT "): no free mem, triggering GC\n", n_bytes);
@@ -1024,9 +1167,12 @@ void *gc_realloc(void *ptr_in, size_t n_bytes, bool allow_move) {
 void gc_dump_info(const mp_print_t *print) {
     gc_info_t info;
     gc_info(&info);
-    mp_printf(print, "GC: total: %u, used: %u, free: %u\n",
+    mp_printf(print, "GC: total: %u, used: %u, free: %u",
         (uint)info.total, (uint)info.used, (uint)info.free);
-    mp_printf(print, " No. of 1-blocks: %u, 2-blocks: %u, max blk sz: %u, max free sz: %u\n",
+    #if MICROPY_GC_SPLIT_HEAP_AUTO
+    mp_printf(print, ", max new split: %u", (uint)gc_get_max_new_split());
+    #endif
+    mp_printf(print, "\n No. of 1-blocks: %u, 2-blocks: %u, max blk sz: %u, max free sz: %u\n",
         (uint)info.num_1block, (uint)info.num_2block, (uint)info.max_block, (uint)info.max_free);
 }
 
diff --git a/py/gc.h b/py/gc.h
@@ -35,7 +35,13 @@ void gc_init(void *start, void *end);
 #if MICROPY_GC_SPLIT_HEAP
 // Used to add additional memory areas to the heap.
 void gc_add(void *start, void *end);
-#endif
+
+#if MICROPY_GC_SPLIT_HEAP_AUTO
+// Port must implement this function to return the maximum available
+// block of RAM to allocate a new heap area into using malloc().
+size_t gc_get_max_new_split(void);
+#endif // MICROPY_GC_SPLIT_HEAP_AUTO
+#endif // MICROPY_GC_SPLIT_HEAP
 
 // These lock/unlock functions can be nested.
 // They can be used to prevent the GC from allocating/freeing.
diff --git a/py/mpconfig.h b/py/mpconfig.h
@@ -616,6 +616,11 @@
 #define MICROPY_GC_SPLIT_HEAP (0)
 #endif
 
+// Whether regions should be added/removed from the split heap as needed.
+#ifndef MICROPY_GC_SPLIT_HEAP_AUTO
+#define MICROPY_GC_SPLIT_HEAP_AUTO (0)
+#endif
+
 // Hook to run code during time consuming garbage collector operations
 // *i* is the loop index variable (e.g. can be used to run every x loops)
 #ifndef MICROPY_GC_HOOK_LOOP
