Update Chapter 12 - Developer Support

ch12.md

@@ -101,26 +101,26 @@ void vAssertCalled( const char *pcFile, uint32_t ulLine )
 /*-----------------------------------------------------------*/
 
 /* These following two lines must be placed in FreeRTOSConfig.h. */
-extern void vAssertCalled( const char *pcFile, uint32_t ulLine );
+extern void vAssertCalled( const char *pcFile, unsigned long ulLine );
 #define configASSERT( x ) if( ( x ) == 0 ) vAssertCalled( __FILE__, __LINE__ )
 ```
 * * *
 *Listing 12.3. A configASSERT() definition that records the source code line that failed an assertion*
 
 
-## 12.3 FreeRTOS+Trace
+## 12.3 Tracealyzer for FreeRTOS
 
-FreeRTOS+Trace is a run-time diagnostic and optimization tool provided
+Tracealyzer for FreeRTOS is a run-time diagnostic and optimization tool provided
 by our partner company, Percepio.
 
-FreeRTOS+Trace captures valuable dynamic behavior information, then
+Tracealyzer for FreeRTOS captures valuable dynamic behavior information, then
 presents the captured information in interconnected graphical views. The
 tool is also capable of displaying multiple synchronized views.
 
 The captured information is invaluable when analyzing, troubleshooting,
 or simply optimizing a FreeRTOS application.
 
-FreeRTOS+Trace can be used side-by-side with a traditional debugger, and
+Tracealyzer for FreeRTOS can be used side-by-side with a traditional debugger, and
 complements the debugger's view with a higher level time based
 perspective.
 
@@ -250,8 +250,8 @@ has proven more practical to define them in `FreeRTOSConfig.h`.
   has been running, in run-time statistics clock units, since the
   application first booted.
 
-  If the first macro is used it must be defined to evaluate to the
-  current clock value. If the second macro is used it must be defined to
+  If the first macro is used, it must be defined to evaluate to the
+  current clock value. If the second macro is used, it must be defined to
   set its 'Time' parameter to the current clock value.
 
 
@@ -267,8 +267,9 @@ below.
 ```c
 UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
                                   const UBaseType_t uxArraySize,
-                                  uint32_t * const pulTotalRunTime );
+                                  configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime );
 ```
+Note: configRUN_TIME_COUNTER_TYPE defaults to uint32_t for backward compatibility, but can be overridden in FreeRTOSConfig.h if uint32_t is too restrictive.
 * * *
 *Listing 12.4. The uxTaskGetSystemState() API function prototype*
 
@@ -321,8 +322,16 @@ typedef struct xTASK_STATUS
     eTaskState eCurrentState;
     UBaseType_t uxCurrentPriority;
     UBaseType_t uxBasePriority;
-    uint32_t ulRunTimeCounter;
+    configRUN_TIME_COUNTER_TYPE ulRunTimeCounter;
+    StackType_t * pxStackBase;
+    #if ( ( portSTACK_GROWTH > 0 ) || ( configRECORD_STACK_HIGH_ADDRESS == 1 ) )
+        StackType_t * pxTopOfStack;
+        StackType_t * pxEndOfStack;
+    #endif
     uint16_t usStackHighWaterMark;
+    #if ( ( configUSE_CORE_AFFINITY == 1 ) && ( configNUMBER_OF_CORES > 1 ) )
+        UBaseType_t uxCoreAffinityMask;
+    #endif
 } TaskStatus_t;
 ```
 * * *
@@ -389,6 +398,24 @@ typedef struct xTASK_STATUS
   provided by the application writer for the collection of run-time
   statistics. `ulRunTimeCounter` is only valid if
   `configGENERATE_RUN_TIME_STATS` is set to 1 in FreeRTOSConfig.h.
+
+- `pxStackBase`
+
+   Points to the base address of the stack region allotted to this task.
+
+- `pxTopOfStack`
+
+   Points to the current top address of the stack region allotted to this task.
+   The field `pxTopOfStack` is only valid if either the stack grows upwards (i.e.
+   `portSTACK_GROWTH` is greater than zero) or `configRECORD_STACK_HIGH_ADDRESS`
+   is set to 1 in FreeRTOSConfig.h.
+
+- `pxEndOfStack`
+
+   Points to the end address of the of the stack region allotted to this task.
+   The field `pxEndOfStack` is only valid if either the stack grows upwards (i.e.
+   `portSTACK_GROWTH` is greater than zero) or `configRECORD_STACK_HIGH_ADDRESS`
+   is set to 1 in FreeRTOSConfig.h.
 
 - `usStackHighWaterMark`
 
@@ -397,6 +424,15 @@ typedef struct xTASK_STATUS
   It is an indication of how close the task has come to overflowing its
   stack; the closer this value is to zero, the closer the task has come to
   overflowing its stack. `usStackHighWaterMark` is specified in bytes.
+
+- `uxCoreAffinityMask`
+
+   A bitwise value that indicates the cores on which the task can run. 
+   Cores are numbered from 0 to `configNUMBER_OF_CORES` - 1. For example, a
+   task that can run on core 0 and core 1 will have its `uxCoreAffinityMask`
+   set to 0x03. The field `uxCoreAffinityMask` is only available if both
+   `configUSE_CORE_AFFINITY` is set to 1 and `configNUMBER_OF_CORES`
+   is set to greater than 1 in FreeRTOSConfig.h.
 
 
 ### 12.5.5 The vTaskList() Helper Function
@@ -410,13 +446,13 @@ scheduler suspended for an extended period. Therefore, it is recommended
 the function is used for debug purposes only, and not in a production
 real-time system.
 
-`vTaskList()` is available if `configUSE_TRACE_FACILITY` and
-`configUSE_STATS_FORMATTING_FUNCTIONS` are both set to 1 in
+`vTaskList()` is available if `configUSE_TRACE_FACILITY` is set to 1 and
+`configUSE_STATS_FORMATTING_FUNCTIONS` is set to greater than 0 in
 FreeRTOSConfig.h.
 
 * * *
 ```c
-void vTaskList( signed char *pcWriteBuffer );
+void vTaskList( char *pcWriteBuffer );
 ```
 * * *
 *Listing 12.6. The vTaskList() API function prototype*
@@ -437,7 +473,7 @@ In the output:
 
 - The first column is the task's name.
 
-- The second column is the task's state, where 'R' means Ready, 'B'
+- The second column is the task's state, where 'X' means Running, 'R' means Ready, 'B'
   means Blocked, 'S' means Suspended, and 'D' means the task has been
   deleted. A task will only be reported as being in the deleted state
   for the short period between the time the task was deleted by a call
@@ -468,9 +504,9 @@ the scheduler suspended for an extended period. Therefore, it is
 recommended the function is used for debug purposes only, and not in a
 production real-time system.
 
-`vTaskGetRunTimeStats()` is available when `configGENERATE_RUN_TIME_STATS`
-and `configUSE_STATS_FORMATTING_FUNCTIONS` are both set to 1 in
-FreeRTOSConfig.h.
+`vTaskGetRunTimeStats()` is available when `configGENERATE_RUN_TIME_STATS` is set to
+1, `configUSE_STATS_FORMATTING_FUNCTIONS` is set greater than 0, and 
+`configUSE_TRACE_FACILITY` is set to 1 in FreeRTOSConfig.h.
 
 * * *
 ```c
@@ -608,7 +644,7 @@ static void prvStatsTask( void *pvParameters )
     for( ;; )
     {
         /* Wait until it is time to run this task again. */
-        vTaskDelayUntil( &xLastExecutionTime, xBlockPeriod );
+        xTaskDelayUntil( &xLastExecutionTime, xBlockPeriod );
 
         /* Generate a text table from the run-time stats. This must fit into
            the cStringBuffer array. */
@@ -663,7 +699,7 @@ that is called from the FreeRTOS/Source/tasks.c source file.
 
 - `traceTASK_INCREMENT_TICK(xTickCount)`
 
-  Called during the tick interrupt, after the tick count is incremented. The `xTickCount` parameter 
+  Called during the tick interrupt, before the tick count is incremented. The `xTickCount` parameter 
   passes the new tick count value into the macro.
 
 - `traceTASK_SWITCHED_OUT()`
@@ -735,9 +771,9 @@ that is called from the FreeRTOS/Source/tasks.c source file.
   Called from within `xQueueReceiveFromISR()` when the receive operation fails due to the queue already 
   being empty. The `pxQueue` parameter passes the handle of the target queue into the macro.
 
-- `traceTASK_DELAY_UNTIL()`
+- `traceTASK_DELAY_UNTIL( xTimeToWake )`
 
-  Called from within `vTaskDelayUntil()` immediately before the calling task enters the Blocked state.
+  Called from within `xTaskDelayUntil()` immediately before the calling task enters the Blocked state.
 
 - `traceTASK_DELAY()`
 
@@ -794,3 +830,4 @@ following IDEs. This list may not be an exhaustive:
 
 - iSYSTEM WinIDEA
 
+- STM32CubeIDE