From 0c2377726fc563285cdb68536af93b0777bfc3a4 Mon Sep 17 00:00:00 2001
From: Tursiae <git@tursiae.org>
Date: Sun, 9 Feb 2025 14:34:16 +1100
Subject: [PATCH] Console: Update doco to point to `sdkconfig.local`, and
 handle no-stats cases.

When `CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS` is not set, the FreeRTOS
scheduler will not keep track of task runtime statistics, and the `tasks`
command on the console will show `nan%` for the usage.

This adds a recommendation for the user to enable the `...STATS` config in
their build, and also updates the guidance for `configUSE_TRACE_FACILITY`
to point at the supported `sdkconfig.local` configuration pathway, instead
of pointing at the `#define` that's deeper in the configuration stack.

Also, the sampling period is dropped from 2.5s to 10ms when the runtime
stats are not enabled; given that we're not measuring any usage, it's not worth
sleeping any longer than that. We might even be able to drop to zero?
---
 src/tangara/app_console/app_console.cpp | 31 ++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/src/tangara/app_console/app_console.cpp b/src/tangara/app_console/app_console.cpp
index 21dec56a..7aa7fccf 100644
--- a/src/tangara/app_console/app_console.cpp
+++ b/src/tangara/app_console/app_console.cpp
@@ -207,8 +207,11 @@ void RegisterDbInit() {
 
 int CmdTasks(int argc, char** argv) {
 #if (configUSE_TRACE_FACILITY == 0)
-  std::cout << "configUSE_TRACE_FACILITY must be enabled" << std::endl;
-  std::cout << "also consider configTASKLIST_USE_COREID" << std::endl;
+  std::cout
+    << "FreeRTOS is not configured to track task info." << std::endl
+    << "Enable CONFIG_FREERTOS_USE_TRACE_FACILITY=y in " << std::endl
+    << "sdkconfig.local, and also consider enabling " << std::endl
+    << "CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID=y" << std::endl;
   return 1;
 #endif
 
@@ -218,6 +221,14 @@ int CmdTasks(int argc, char** argv) {
     return 1;
   }
 
+  // Sample the task runtime percentage over 2.5 seconds if collecting
+  // task statistics. Else, we don't need to sample for as long.
+#ifdef CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
+  const int kSamplePeriodMs = 2500;
+#else
+  const int kSamplePeriodMs = 10;
+#endif
+
   // Pad the number of tasks so that uxTaskGetSystemState still returns info
   // if new tasks are started during measurement.
   size_t num_tasks = uxTaskGetNumberOfTasks() + 4;
@@ -229,11 +240,21 @@ int CmdTasks(int argc, char** argv) {
   size_t start_num_tasks =
       uxTaskGetSystemState(start_status, num_tasks, &start_elapsed_ticks);
 
-  vTaskDelay(pdMS_TO_TICKS(2500));
+  vTaskDelay(pdMS_TO_TICKS(kSamplePeriodMs));
 
   size_t end_num_tasks =
       uxTaskGetSystemState(end_status, num_tasks, &end_elapsed_ticks);
 
+  uint32_t elapsed_ticks = end_elapsed_ticks - start_elapsed_ticks;
+
+  if (0 == elapsed_ticks) {
+    std::cout << "Warning: the scheduler is not recording run-time" << std::endl
+              << "statistics, and this means that detailed task" << std::endl
+              << "information is not available." << std::endl
+              << "Enable CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS" << std::endl
+              << "in sdkconfig.local to capture these stats." << std::endl;
+  }
+
   std::vector<std::pair<uint32_t, std::pmr::string>> info_strings;
   for (int i = 0; i < start_num_tasks; i++) {
     int k = -1;
@@ -279,8 +300,12 @@ int CmdTasks(int argc, char** argv) {
         str << "\t\t";
       }
 
+#ifdef CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
       str << std::fixed << std::setprecision(1) << (time_percent * 100);
       str << "%";
+#else
+      str << "(unavailable)";
+#endif
 
       info_strings.push_back({run_time, std::pmr::string{str.str()}});
     }