sysview: FreeRTOS trace hooks, stack high-water and heap tracking

hw/bsp/sysview_freertos_hooks.h maps the FreeRTOS trace macros onto
SystemView task records (task names, switches, ready/blocked) and adds heap
tracking; the FreeRTOSConfig.h of the families used on the rig include it
when SYSVIEW is on.

The FreeRTOS examples grow their USB task stacks when CFG_TU*_SYSVIEW is
enabled, the same way they already do for CFG_TUSB_DEBUG -- the
instrumentation's stack cost is real (measured overflows on lpc55 before
the bump).

20 files changed, 88 insertions, 33 deletions

diff --git a/examples/device/audio_4_channel_mic_freertos/src/main.c b/examples/device/audio_4_channel_mic_freertos/src/main.c
index eac66a4ef..e23ece633 100644
--- a/examples/device/audio_4_channel_mic_freertos/src/main.c
+++ b/examples/device/audio_4_channel_mic_freertos/src/main.c
@@ -57,8 +57,8 @@
   #include "task.h"
   #include "timers.h"
 
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE (4 * configMINIMAL_STACK_SIZE / 2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE (4 * configMINIMAL_STACK_SIZE / 2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
 #endif
 
 #define BLINKY_STACK_SIZE configMINIMAL_STACK_SIZE
diff --git a/examples/device/audio_test_freertos/src/main.c b/examples/device/audio_test_freertos/src/main.c
index cf2fb74d1..41cdaae0e 100644
--- a/examples/device/audio_test_freertos/src/main.c
+++ b/examples/device/audio_test_freertos/src/main.c
@@ -56,8 +56,8 @@
   #include "task.h"
   #include "timers.h"
 
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE (4 * configMINIMAL_STACK_SIZE / 2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE (4 * configMINIMAL_STACK_SIZE / 2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
 #endif
 
 #define BLINKY_STACK_SIZE configMINIMAL_STACK_SIZE
diff --git a/examples/device/cdc_msc_freertos/src/main.c b/examples/device/cdc_msc_freertos/src/main.c
index 4a920c90b..5677f72a7 100644
--- a/examples/device/cdc_msc_freertos/src/main.c
+++ b/examples/device/cdc_msc_freertos/src/main.c
@@ -33,11 +33,11 @@
 #ifdef ESP_PLATFORM
   #define USBD_STACK_SIZE     4096
 #else
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE    (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 4 : 2))
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE    (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 4 : 2))
 #endif
 
-#define CDC_STACK_SIZE      (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 3 : 2))
+#define CDC_STACK_SIZE      (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 3 : 2))
 #define BLINKY_STACK_SIZE   configMINIMAL_STACK_SIZE
 
 //--------------------------------------------------------------------+
diff --git a/examples/device/hid_composite_freertos/src/main.c b/examples/device/hid_composite_freertos/src/main.c
index 35fdfea9e..00e48983d 100644
--- a/examples/device/hid_composite_freertos/src/main.c
+++ b/examples/device/hid_composite_freertos/src/main.c
@@ -49,11 +49,11 @@
   #include "task.h"
   #include "timers.h"
 
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
 #endif
 
-#define HID_STACK_SIZE      (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 2 : 1))
+#define HID_STACK_SIZE      (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1))
 
 //--------------------------------------------------------------------+
 // MACRO CONSTANT TYPEDEF PROTYPES
diff --git a/examples/device/midi_test_freertos/src/main.c b/examples/device/midi_test_freertos/src/main.c
index f5267214e..4fc9eba92 100644
--- a/examples/device/midi_test_freertos/src/main.c
+++ b/examples/device/midi_test_freertos/src/main.c
@@ -43,12 +43,12 @@
 #ifdef ESP_PLATFORM
   #define USBD_STACK_SIZE     4096
 #else
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
 #endif
 
 #define BLINKY_STACK_SIZE   configMINIMAL_STACK_SIZE
-#define MIDI_STACK_SIZE     (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 2 : 1))
+#define MIDI_STACK_SIZE     (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1))
 
 // static task
 #if configSUPPORT_STATIC_ALLOCATION
diff --git a/examples/device/msc_dual_lun/src/main.c b/examples/device/msc_dual_lun/src/main.c
index 1d764f12c..f13e79c2e 100644
--- a/examples/device/msc_dual_lun/src/main.c
+++ b/examples/device/msc_dual_lun/src/main.c
@@ -164,7 +164,7 @@ void led_blinking_task(RTOS_PARAM param) {
 #ifdef ESP_PLATFORM
 #define USBD_STACK_SIZE   4096
 #else
-#define USBD_STACK_SIZE   (3*configMINIMAL_STACK_SIZE/2 * (CFG_TUSB_DEBUG ? 2 : 1))
+#define USBD_STACK_SIZE   (3*configMINIMAL_STACK_SIZE/2 * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1))
 #endif
 #define BLINKY_STACK_SIZE   configMINIMAL_STACK_SIZE
 
diff --git a/examples/device/usbtest/src/main.c b/examples/device/usbtest/src/main.c
index e57a90161..eff564e7f 100644
--- a/examples/device/usbtest/src/main.c
+++ b/examples/device/usbtest/src/main.c
@@ -289,8 +289,8 @@ void led_blinking_task(void* param) {
     main();
   }
 #else
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
 #endif
 
 // static task allocation
diff --git a/examples/device/video_capture/src/main.c b/examples/device/video_capture/src/main.c
index d366a17e8..f22ccdae8 100644
--- a/examples/device/video_capture/src/main.c
+++ b/examples/device/video_capture/src/main.c
@@ -342,8 +342,8 @@ void led_blinking_task(void* param) {
     main();
   }
 #else
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
 #endif
 
 // static task
diff --git a/examples/device/video_capture_2ch/src/main.c b/examples/device/video_capture_2ch/src/main.c
index fb45038c8..bb8c25b93 100644
--- a/examples/device/video_capture_2ch/src/main.c
+++ b/examples/device/video_capture_2ch/src/main.c
@@ -304,8 +304,8 @@ void led_blinking_task(void* param) {
     main();
   }
 #else
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
 #endif
 
 // static task
diff --git a/examples/dual/dynamic_switch/src/main.c b/examples/dual/dynamic_switch/src/main.c
index f67cd885c..6c4abb458 100644
--- a/examples/dual/dynamic_switch/src/main.c
+++ b/examples/dual/dynamic_switch/src/main.c
@@ -41,12 +41,12 @@
     #define USBD_STACK_SIZE     4096
     #define USBH_STACK_SIZE     4096
   #else
-    // Increase stack size when debug log is enabled
-    #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
-    #define USBH_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
+    // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+    #define USBD_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1)
+    #define USBH_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUH_SYSVIEW) ? 2 : 1)
   #endif
 
-  #define CDC_STACK_SIZE      (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 2 : 1))
+  #define CDC_STACK_SIZE      (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 2 : 1))
   #define BLINKY_STACK_SIZE   configMINIMAL_STACK_SIZE
 #endif
 
diff --git a/examples/dual/host_info_to_device_cdc/src/main.c b/examples/dual/host_info_to_device_cdc/src/main.c
index 5186f91dc..d76cfd962 100644
--- a/examples/dual/host_info_to_device_cdc/src/main.c
+++ b/examples/dual/host_info_to_device_cdc/src/main.c
@@ -380,9 +380,9 @@ static void print_utf16(uint16_t *temp_buf, size_t buf_len) {
     main();
   }
 #else
-  // Increase stack size when debug log is enabled
-  #define USBD_STACK_SIZE    (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 4 : 2))
-  #define USBH_STACK_SIZE    (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 4 : 2))
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBD_STACK_SIZE    (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUD_SYSVIEW) ? 4 : 2))
+  #define USBH_STACK_SIZE    (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUH_SYSVIEW) ? 4 : 2))
 #endif
 
 #define MAIN_STACK_SIZE    (configMINIMAL_STACK_SIZE*4)
diff --git a/examples/host/cdc_msc_hid_freertos/src/main.c b/examples/host/cdc_msc_hid_freertos/src/main.c
index a41de2769..e21441c5c 100644
--- a/examples/host/cdc_msc_hid_freertos/src/main.c
+++ b/examples/host/cdc_msc_hid_freertos/src/main.c
@@ -34,8 +34,8 @@
 #ifdef ESP_PLATFORM
   #define USBH_STACK_SIZE     4096
 #else
-  // Increase stack size when debug log is enabled
-  #define USBH_STACK_SIZE    (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 4 : 2))
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USBH_STACK_SIZE    (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUH_SYSVIEW) ? 4 : 2))
 #endif
 
 
diff --git a/examples/host/device_info/src/main.c b/examples/host/device_info/src/main.c
index f32ed1a3e..1f5db7695 100644
--- a/examples/host/device_info/src/main.c
+++ b/examples/host/device_info/src/main.c
@@ -304,8 +304,8 @@ void led_blinking_task(void* param) {
 #ifdef ESP_PLATFORM
   #define USB_STACK_SIZE     4096
 #else
-  // Increase stack size when debug log is enabled
-  #define USB_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * (CFG_TUSB_DEBUG ? 2 : 1)
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled
+  #define USB_STACK_SIZE    (3*configMINIMAL_STACK_SIZE/2) * ((CFG_TUSB_DEBUG || CFG_TUH_SYSVIEW) ? 2 : 1)
 #endif
 
 
diff --git a/examples/host/msc_file_explorer_freertos/src/main.c b/examples/host/msc_file_explorer_freertos/src/main.c
index d1e627f4f..b40bee90d 100644
--- a/examples/host/msc_file_explorer_freertos/src/main.c
+++ b/examples/host/msc_file_explorer_freertos/src/main.c
@@ -47,8 +47,8 @@
 #ifdef ESP_PLATFORM
   #define USBH_STACK_SIZE     4096
 #else
-  // Increase stack size when debug log is enabled.
-  #define USBH_STACK_SIZE    (configMINIMAL_STACK_SIZE * (CFG_TUSB_DEBUG ? 4 : 3))
+  // Increase stack size when debug log or SYSVIEW instrumentation is enabled.
+  #define USBH_STACK_SIZE    (configMINIMAL_STACK_SIZE * ((CFG_TUSB_DEBUG || CFG_TUH_SYSVIEW) ? 4 : 3))
 #endif
 
 enum {
diff --git a/hw/bsp/nrf/FreeRTOSConfig/FreeRTOSConfig.h b/hw/bsp/nrf/FreeRTOSConfig/FreeRTOSConfig.h
index b6395306f..764c20146 100644
--- a/hw/bsp/nrf/FreeRTOSConfig/FreeRTOSConfig.h
+++ b/hw/bsp/nrf/FreeRTOSConfig/FreeRTOSConfig.h
@@ -152,4 +152,7 @@ to all Cortex-M ports, and do not rely on any particular library functions. */
 See http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html. */
 #define configMAX_SYSCALL_INTERRUPT_PRIORITY 	        ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
 
+/* SEGGER SystemView instrumentation (SYSVIEW=<level> build) — must be last */
+#include "sysview_freertos_hooks.h"
+
 #endif
diff --git a/hw/bsp/samd5x_e5x/FreeRTOSConfig/FreeRTOSConfig.h b/hw/bsp/samd5x_e5x/FreeRTOSConfig/FreeRTOSConfig.h
index a283560fe..64847262b 100644
--- a/hw/bsp/samd5x_e5x/FreeRTOSConfig/FreeRTOSConfig.h
+++ b/hw/bsp/samd5x_e5x/FreeRTOSConfig/FreeRTOSConfig.h
@@ -146,4 +146,7 @@ to all Cortex-M ports, and do not rely on any particular library functions. */
 See http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html. */
 #define configMAX_SYSCALL_INTERRUPT_PRIORITY 	        ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
 
+/* SEGGER SystemView instrumentation (SYSVIEW=<level> build) — must be last */
+#include "sysview_freertos_hooks.h"
+
 #endif
diff --git a/hw/bsp/stm32f4/FreeRTOSConfig/FreeRTOSConfig.h b/hw/bsp/stm32f4/FreeRTOSConfig/FreeRTOSConfig.h
index e9828cbb2..55a3c9419 100644
--- a/hw/bsp/stm32f4/FreeRTOSConfig/FreeRTOSConfig.h
+++ b/hw/bsp/stm32f4/FreeRTOSConfig/FreeRTOSConfig.h
@@ -146,4 +146,7 @@ to all Cortex-M ports, and do not rely on any particular library functions. */
 See http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html. */
 #define configMAX_SYSCALL_INTERRUPT_PRIORITY 	        ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
 
+/* SEGGER SystemView instrumentation (SYSVIEW=<level> build) — must be last */
+#include "sysview_freertos_hooks.h"
+
 #endif
diff --git a/hw/bsp/stm32f7/FreeRTOSConfig/FreeRTOSConfig.h b/hw/bsp/stm32f7/FreeRTOSConfig/FreeRTOSConfig.h
index 31fb7942f..fa2f1fea9 100644
--- a/hw/bsp/stm32f7/FreeRTOSConfig/FreeRTOSConfig.h
+++ b/hw/bsp/stm32f7/FreeRTOSConfig/FreeRTOSConfig.h
@@ -146,4 +146,7 @@ to all Cortex-M ports, and do not rely on any particular library functions. */
 See http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html. */
 #define configMAX_SYSCALL_INTERRUPT_PRIORITY 	        ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
 
+/* SEGGER SystemView instrumentation (SYSVIEW=<level> build) — must be last */
+#include "sysview_freertos_hooks.h"
+
 #endif
diff --git a/hw/bsp/stm32h7/FreeRTOSConfig/FreeRTOSConfig.h b/hw/bsp/stm32h7/FreeRTOSConfig/FreeRTOSConfig.h
index 8bbeefcc7..67d8aeb8d 100644
--- a/hw/bsp/stm32h7/FreeRTOSConfig/FreeRTOSConfig.h
+++ b/hw/bsp/stm32h7/FreeRTOSConfig/FreeRTOSConfig.h
@@ -146,4 +146,7 @@ to all Cortex-M ports, and do not rely on any particular library functions. */
 See http://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html. */
 #define configMAX_SYSCALL_INTERRUPT_PRIORITY 	        ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) )
 
+/* SEGGER SystemView instrumentation (SYSVIEW=<level> build) — must be last */
+#include "sysview_freertos_hooks.h"
+
 #endif
diff --git a/hw/bsp/sysview_freertos_hooks.h b/hw/bsp/sysview_freertos_hooks.h
new file mode 100644
index 000000000..2669e42f5
--- /dev/null
+++ b/hw/bsp/sysview_freertos_hooks.h
@@ -0,0 +1,40 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2019 Ha Thach (tinyusb.org)
+ * SPDX-License-Identifier: MIT
+ *
+ * This file is part of the TinyUSB stack.
+ */
+
+// SEGGER SystemView instrumentation for FreeRTOSConfig.h (SYSVIEW=<level> build). #include this
+// from the bottom of FreeRTOSConfig.h, after every other config option -- CFG_TUD_SYSVIEW /
+// CFG_TUH_SYSVIEW must already be visible (from tusb_option.h by way of tusb_config.h) for the
+// guard below to see them, and traceMALLOC/traceFREE must be defined before any FreeRTOS header
+// that reads them is included. Shared verbatim across every FreeRTOS-capable family instead of
+// pasting the same block into each FreeRTOSConfig.h; hw/bsp/family_support.cmake's SYSVIEW
+// detector greps for the #include line this replaces, not this file's content.
+#if (defined(CFG_TUD_SYSVIEW) && CFG_TUD_SYSVIEW) || (defined(CFG_TUH_SYSVIEW) && CFG_TUH_SYSVIEW)
+  #undef  INCLUDE_uxTaskPriorityGet
+  #define INCLUDE_uxTaskPriorityGet       1
+  #undef  INCLUDE_xTaskGetIdleTaskHandle
+  #define INCLUDE_xTaskGetIdleTaskHandle  1
+  // Both macros below are generic FreeRTOS.h knobs (FreeRTOS.h supplies a "#ifndef ... 0"
+  // default for each, identically on every port -- verified against lib/FreeRTOS-Kernel), not
+  // architecture-specific, so forcing them here is safe for any family this header is wired
+  // into. tusb_sysview_stack_report() (src/common/tusb_sysview.c) needs
+  // configRECORD_STACK_HIGH_ADDRESS=1 to compute true "bytes used at peak" instead of
+  // (inverted) headroom; without it the number it publishes is the exact opposite of the
+  // "stack high-water" label the PR-comment legend gives it. configUSE_TRACE_FACILITY=1 is
+  // what makes TaskStatus_t/uxTaskGetSystemState() available at all for that same report.
+  #undef  configUSE_TRACE_FACILITY
+  #define configUSE_TRACE_FACILITY        1
+  #undef  configRECORD_STACK_HIGH_ADDRESS
+  #define configRECORD_STACK_HIGH_ADDRESS 1
+  #ifndef TU_SYSVIEW_HEAP_HOOKS_DECLARED /* avoid -Werror=redundant-decls vs tusb_sysview.h */
+  #define TU_SYSVIEW_HEAP_HOOKS_DECLARED
+  extern void tusb_sysview_heap_alloc(void* ptr, unsigned size);
+  extern void tusb_sysview_heap_free(void* ptr);
+  #endif
+  #define traceMALLOC(pvAddress, uiSize) tusb_sysview_heap_alloc(pvAddress, uiSize)
+  #define traceFREE(pvAddress, uiSize)   tusb_sysview_heap_free(pvAddress)
+  #include "SEGGER_SYSVIEW_FreeRTOS.h"
+#endif