esp32/modesp32: Implement esp32.idf_task_info().

This adds a new function, `esp32.idf_task_info()`, that can be used to
retrieve task statistics which is useful for diagnosing issues where some
tasks are using up a lot of CPU time.

It's best used in conjunction with the `utop` module from micropython-lib.

Signed-off-by: Daniël van de Giessen <daniel@dvdgiessen.nl>

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
index dc35e7905..24831c58d 100644
--- a/docs/library/esp32.rst
+++ b/docs/library/esp32.rst
@@ -80,6 +80,29 @@ Functions
        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()`.
 
+.. function:: idf_task_info()
+
+    Returns information about running ESP-IDF/FreeRTOS tasks, which include
+    MicroPython threads. This data is useful to gain insight into how much time
+    tasks spend running or if they are blocked for significant parts of time,
+    and to determine if allocated stacks are fully utilized or might be reduced.
+
+    ``CONFIG_FREERTOS_USE_TRACE_FACILITY=y`` must be set in the board
+    configuration to make this method available. Additionally configuring
+    ``CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS=y`` and
+    ``CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID=y`` is recommended to be able to
+    retrieve the total and per-task runtime and the core ID respectively.
+
+    The return value is a 2-tuple where the first value is the total runtime,
+    and the second a list of tasks. Each task is a 7-tuple containing: the task
+    ID, name, current state, priority, runtime, stack high water mark, and the
+    ID of the core it is running on. Runtime and core ID will be None when the
+    respective FreeRTOS configuration option is not enabled.
+
+    .. note:: For an easier to use output based on this function you can use the
+       `utop library <https://github.com/micropython/micropython-lib/tree/master/micropython/utop>`_,
+       which implements a live overview similar to the Unix ``top`` command.
+
 
 Flash partitions
 ----------------