From 4f32c359efdff594213c7d1a6404b7d1a13f2742 Mon Sep 17 00:00:00 2001
From: Kuoping Hsu <kuoping.hsu@gmail.com>
Date: Fri, 15 May 2026 20:27:13 +0800
Subject: [PATCH] Add tracing macros for core scheduling functions and enhance
 documentation

---
 include/FreeRTOS.h | 16 ++++++++++++++++
 include/task.h     | 15 ++++++++++++---
 tasks.c            |  8 ++++++++
 3 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/include/FreeRTOS.h b/include/FreeRTOS.h
index 729e7c249..ec6ea5940 100644
--- a/include/FreeRTOS.h
+++ b/include/FreeRTOS.h
@@ -1854,6 +1854,22 @@
     #define traceRETURN_vTaskCoreAffinityGet( uxCoreAffinityMask )
 #endif
 
+#ifndef traceENTER_vTaskSetSchedulerCoreMask
+    #define traceENTER_vTaskSetSchedulerCoreMask( uxCoreMask )
+#endif
+
+#ifndef traceRETURN_vTaskSetSchedulerCoreMask
+    #define traceRETURN_vTaskSetSchedulerCoreMask()
+#endif
+
+#ifndef traceENTER_uxTaskGetSchedulerCoreMask
+    #define traceENTER_uxTaskGetSchedulerCoreMask()
+#endif
+
+#ifndef traceRETURN_uxTaskGetSchedulerCoreMask
+    #define traceRETURN_uxTaskGetSchedulerCoreMask( uxCoreMask )
+#endif
+
 #ifndef traceENTER_vTaskPreemptionDisable
     #define traceENTER_vTaskPreemptionDisable( xTask )
 #endif
diff --git a/include/task.h b/include/task.h
index 048d043a1..317a985c4 100644
--- a/include/task.h
+++ b/include/task.h
@@ -1425,9 +1425,18 @@ BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume ) PRIVILEGED_FUNCTION;
 /**
  *
  * Controls which cores are allowed to run non-idle tasks system-wide.
- * Bit N = 1 means core N may run tasks; bit N = 0 means core N will only
- * run its idle task.  configNUMBER_OF_CORES must be greater than 1 for this
- * function to be available.
+ * Bit N = 1 means core N may run non-idle tasks; bit N = 0 means core N will
+ * only run its idle task.  configNUMBER_OF_CORES must be greater than 1 for
+ * this function to be available.
+ *
+ * Masking a core (including core 0) does NOT power it off or stop its tick
+ * ISR and scheduler from executing.  All cores remain active; the mask only
+ * controls whether the scheduler may dispatch a non-idle task onto a core.
+ * A masked core continues to service its tick interrupt and enters the
+ * scheduler normally, but will always be assigned the idle task.
+ *
+ * Passing 0 as the mask is valid; every core will run only its idle task
+ * until a new mask is applied.
  *
  * If a core that is currently running a non-idle task becomes disabled by
  * the new mask, it is yielded immediately so the scheduler can replace the
diff --git a/tasks.c b/tasks.c
index 9e210b782..d9fb2fc79 100644
--- a/tasks.c
+++ b/tasks.c
@@ -3135,6 +3135,8 @@ static void prvInitialiseNewTask( TaskFunction_t pxTaskCode,
         UBaseType_t uxOldMask;
         UBaseType_t uxDisabledCores;
 
+        traceENTER_vTaskSetSchedulerCoreMask( uxCoreMask );
+
         taskENTER_CRITICAL();
         {
             uxOldMask = uxSchedulerCoreMask;
@@ -3162,6 +3164,8 @@ static void prvInitialiseNewTask( TaskFunction_t pxTaskCode,
             }
         }
         taskEXIT_CRITICAL();
+
+        traceRETURN_vTaskSetSchedulerCoreMask();
     }
 #endif /* #if ( ( configNUMBER_OF_CORES > 1 ) && ( configUSE_SCHEDULER_CORE_MASK == 1 ) ) */
 
@@ -3172,12 +3176,16 @@ static void prvInitialiseNewTask( TaskFunction_t pxTaskCode,
     {
         UBaseType_t uxCoreMask;
 
+        traceENTER_uxTaskGetSchedulerCoreMask();
+
         portBASE_TYPE_ENTER_CRITICAL();
         {
             uxCoreMask = uxSchedulerCoreMask;
         }
         portBASE_TYPE_EXIT_CRITICAL();
 
+        traceRETURN_uxTaskGetSchedulerCoreMask( uxCoreMask );
+
         return uxCoreMask;
     }
 #endif /* #if ( ( configNUMBER_OF_CORES > 1 ) && ( configUSE_SCHEDULER_CORE_MASK == 1 ) ) */