From 89c22c63e61e2ce243560e7a01e4d2dc502f14eb Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Tue, 14 May 2024 23:01:50 +0800 Subject: [PATCH] refactor(freertos/idf): Add critical section requirements to function description This commit adds a note regarding the critical section calling requires of some internal functions. --- components/freertos/FreeRTOS-Kernel/tasks.c | 31 +++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/components/freertos/FreeRTOS-Kernel/tasks.c b/components/freertos/FreeRTOS-Kernel/tasks.c index df7835de70..182d2f5ae2 100644 --- a/components/freertos/FreeRTOS-Kernel/tasks.c +++ b/components/freertos/FreeRTOS-Kernel/tasks.c @@ -141,6 +141,11 @@ * - If a yield is required on the current core, this macro return pdTRUE * - if a yield is required on the other core, this macro will internally * trigger it. + * + * - In SMP, these macros must be called from a critical section (where the + * kernel locks are taken). + * - In single-core, these macros must be called from a critical section or when + * the scheduler is suspended. */ #if ( configNUMBER_OF_CORES > 1 ) #define taskIS_YIELD_REQUIRED( pxTCB, xYieldEqualPriority ) prvIsYieldRequiredSMP( ( pxTCB ), ( pxTCB )->uxPriority, xYieldEqualPriority ) @@ -177,7 +182,12 @@ #endif /* configNUMBER_OF_CORES > 1 */ /*-----------------------------------------------------------*/ -/* Macros to check if a particular task is a currently running. */ +/* Macros to check if a particular task is a currently running. + * + * - In SMP, these macros must be called from a critical section (where the + * kernel lock is taken). + * - In single-core, these macros must be called from a critical section or when + * the scheduler is suspended */ #if ( configNUMBER_OF_CORES > 1 ) #define taskIS_CURRENTLY_RUNNING( pxTCB ) ( ( ( ( pxTCB ) == pxCurrentTCBs[ 0 ] ) || ( ( pxTCB ) == pxCurrentTCBs[ 1 ] ) ) ? pdTRUE : pdFALSE ) #define taskIS_CURRENTLY_RUNNING_ON_CORE( pxTCB, xCoreID ) ( ( ( pxTCB ) == pxCurrentTCBs[ ( xCoreID ) ] ) ? pdTRUE : pdFALSE ) @@ -193,7 +203,12 @@ /*-----------------------------------------------------------*/ /* Macro to check if a particular task can currently be scheduled (i.e., is - * the scheduler suspended). */ + * the scheduler suspended). + * + * - In SMP, these macros must be called from a critical section (where the + * kernel lock is taken). + * - In single-core, these macros must be called from a critical section or when + * the scheduler is suspended */ #if ( configNUMBER_OF_CORES > 1 ) #define taskCAN_BE_SCHEDULED( pxTCB ) prvCheckTaskCanBeScheduledSMP( pxTCB ) #else @@ -569,6 +584,9 @@ static BaseType_t prvCreateIdleTasks( void ); * Exit: * - Returns pdTRUE if the current core requires yielding * - The other core will be triggered to yield if required + * + * @note This function must be called from a critical section where the kernel + * lock is taken). */ #if ( configNUMBER_OF_CORES > 1 ) @@ -589,6 +607,9 @@ static BaseType_t prvCreateIdleTasks( void ); * - If a task is unpinned, check the scheduler suspension state on both cores. * The task can be scheduled if the scheduler is not suspended on either of * the cores. + * + * @note This function must be called from a critical section (where the kernel + * lock is taken). */ #if ( configNUMBER_OF_CORES > 1 ) @@ -772,6 +793,9 @@ static void prvAddNewTaskToReadyList( TCB_t * pxNewTCB ) PRIVILEGED_FUNCTION; UBaseType_t uxTaskPriority, BaseType_t xYieldEqualPriority ) { + /* This function must be called from a critical section (where the kernel + * lock is taken). */ + configASSERT( uxTaskPriority < configMAX_PRIORITIES ); /* Save core ID as we can no longer be preempted. */ @@ -825,6 +849,9 @@ static void prvAddNewTaskToReadyList( TCB_t * pxNewTCB ) PRIVILEGED_FUNCTION; static BaseType_t prvCheckTaskCanBeScheduledSMP( TCB_t * pxTCB ) { + /* This function must be called from a critical section (where the kernel + * lock is taken). */ + BaseType_t xReturn; if( pxTCB->xCoreID == tskNO_AFFINITY )