esp32/modesp32: Implement idf_task_stats().

DvdGiessen · DvdGiessen · commit 1982e187a5c8 · 2023-10-18T15:52:39.000+02:00
Signed-off-by: Daniël van de Giessen &lt;daniel@dvdgiessen.nl&gt;
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -80,6 +80,68 @@ 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_stats()
+
+    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 signficant 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 setting
+    ``CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID=y`` and
+    ``CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS=y`` is recommended to be able to
+    retrieve the core id and runtime 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
+    name, ID, current state, priority, runtime, stack high water mark, and the
+    ID of the core it is running on.
+
+    Example displaying a constantly updating task list::
+
+        import esp32
+        import time
+        def print_task_stats(timeout_seconds=None):
+            if not hasattr(esp32, 'idf_task_stats'):
+                raise RuntimeError('esp32.idf_task_stats() is not supported!')
+            time_start = time.ticks_ms()
+            previous_total_runtime = None
+            previous_task_runtimes = {}
+            previous_line_count = 0
+            task_state_names = ['running', 'ready', 'blocked', 'suspended', 'deleted', 'invalid']
+            print('')
+            while timeout_seconds is None or abs(time.ticks_diff(time.ticks_ms(), time_start)) < 1000 * timeout_seconds:
+                total_runtime, tasks = esp32.idf_task_stats()
+                tasks.sort(key=lambda t: t[1])
+                print('\x1B[{}A'.format(previous_line_count), end='')
+                print('   CPU%  CORE  PRIORITY  STATE      STACKWATERMARK  NAME\x1B[K')
+                previous_line_count = 1
+                for task_name, task_id, task_state, task_priority, task_runtime, task_stackhighwatermark, task_coreid in tasks:
+                    task_runtime_percentage = '-'
+                    if total_runtime > 0:
+                        if previous_total_runtime is not None and task_id in previous_task_runtimes:
+                            task_cpu_percentage = 100 * (task_runtime - previous_task_runtimes[task_id]) / (total_runtime - previous_total_runtime)
+                        else:
+                            task_cpu_percentage = 100 * task_runtime / total_runtime
+                        task_runtime_percentage = '{:.2f}%'.format(task_cpu_percentage)
+                    task_state_name = 'unknown'
+                    if task_state >= 0 and task_state < len(task_state_names):
+                        task_state_name = task_state_names[task_state]
+                    print('{:>7}  {:>4d}  {:>8d}  {:<9}  {:<14d}  {}\x1B[K'.format(
+                        task_runtime_percentage,
+                        task_coreid,
+                        task_priority,
+                        task_state_name,
+                        task_stackhighwatermark,
+                        task_name
+                    ))
+                    previous_task_runtimes[task_id] = task_runtime
+                    previous_line_count += 1
+                print('\x1B[K')
+                previous_line_count += 1
+                previous_total_runtime = total_runtime
+                time.sleep_ms(1000)
 
 Flash partitions
 ----------------
diff --git a/ports/esp32/modesp32.c b/ports/esp32/modesp32.c
@@ -192,6 +192,47 @@ STATIC mp_obj_t esp32_idf_heap_info(const mp_obj_t cap_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(esp32_idf_heap_info_obj, esp32_idf_heap_info);
 
+#if configUSE_TRACE_FACILITY
+STATIC mp_obj_t esp32_idf_task_stats(void) {
+    const size_t task_count_max = uxTaskGetNumberOfTasks();
+    if (task_count_max == 0) {
+        return mp_const_none;
+    }
+
+    TaskStatus_t *task_array = m_new(TaskStatus_t, task_count_max);
+    if (task_array == NULL) {
+        return mp_const_none;
+    }
+
+    uint32_t total_time;
+    const size_t task_count = uxTaskGetSystemState(task_array, task_count_max, &total_time);
+
+    mp_obj_t task_list = mp_obj_new_list(0, 0);
+    for (size_t i = 0; i < task_count; i++) {
+        mp_obj_t task_data[] = {
+            mp_obj_new_str(task_array[i].pcTaskName, strlen(task_array[i].pcTaskName)),
+            mp_obj_new_int_from_uint(task_array[i].xTaskNumber),
+            MP_OBJ_NEW_SMALL_INT(task_array[i].eCurrentState),
+            MP_OBJ_NEW_SMALL_INT(task_array[i].uxCurrentPriority),
+            mp_obj_new_int_from_uint(task_array[i].ulRunTimeCounter),
+            mp_obj_new_int_from_uint(task_array[i].usStackHighWaterMark),
+            #if configTASKLIST_INCLUDE_COREID
+            MP_OBJ_NEW_SMALL_INT(task_array[i].xCoreID),
+            #else
+            mp_const_none,
+            #endif
+        };
+        mp_obj_t task = mp_obj_new_tuple(7, task_data);
+        mp_obj_list_append(task_list, task);
+    }
+
+    m_del(TaskStatus_t, task_array, task_count_max);
+    mp_obj_t task_stats[] = { MP_OBJ_NEW_SMALL_INT(total_time), task_list };
+    return mp_obj_new_tuple(2, task_stats);
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(esp32_idf_task_stats_obj, esp32_idf_task_stats);
+#endif
+
 STATIC const mp_rom_map_elem_t esp32_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_esp32) },
 
@@ -204,6 +245,9 @@ STATIC const mp_rom_map_elem_t esp32_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_raw_temperature), MP_ROM_PTR(&esp32_raw_temperature_obj) },
     #endif
     { MP_ROM_QSTR(MP_QSTR_idf_heap_info), MP_ROM_PTR(&esp32_idf_heap_info_obj) },
+    #if configUSE_TRACE_FACILITY
+    { MP_ROM_QSTR(MP_QSTR_idf_task_stats), MP_ROM_PTR(&esp32_idf_task_stats_obj) },
+    #endif
 
     { MP_ROM_QSTR(MP_QSTR_NVS), MP_ROM_PTR(&esp32_nvs_type) },
     { MP_ROM_QSTR(MP_QSTR_Partition), MP_ROM_PTR(&esp32_partition_type) },
