Add tracing macros for core scheduling functions and enhance documentation

Author: kuopinghsu

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

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

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 ) ) */