From 26160e8ed54410e3d630c03e1c46eb59e02c2594 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 5 Sep 2023 11:06:23 +1000 Subject: [PATCH] docs/library/esp32: Update ESP32 idf_heap_info docs to match behaviour. Signed-off-by: Angus Gratton --- docs/library/esp32.rst | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst index d6b4051a2f..7701f43539 100644 --- a/docs/library/esp32.rst +++ b/docs/library/esp32.rst @@ -56,15 +56,6 @@ Functions 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. @@ -75,6 +66,21 @@ Functions [(240, 0, 0, 0), (7288, 0, 0, 0), (16648, 4, 4, 4), (79912, 35712, 35512, 35108), (15072, 15036, 15036, 15036), (113840, 0, 0, 0)] + .. note:: 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. :func:`micropython.mem_info()` and :func:`gc.mem_free()` should + be used instead: + + The "max new split" value in :func:`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 result of :func:`gc.mem_free()` is the total of the current "free" + and "max new split" values printed by :func:`micropython.mem_info()`. + + Flash partitions ----------------