feat(freertos/smp): Add Granular Locking V4 proposal documents

Co-authored-by: Sudeep Mohanty <sudeep.mohanty@espressif.com>

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
 jobs:
   formatting:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4.1.1
       - name: Check Formatting of FreeRTOS-Kernel Files

.github/workflows/formatting.yml

@@ -1,25 +0,0 @@
-name: Format Pull Request Files
-
-on:
-  issue_comment:
-    types: [created]
-
-env:
-  bashPass: \033[32;1mPASSED -
-  bashInfo: \033[33;1mINFO -
-  bashFail: \033[31;1mFAILED -
-  bashEnd:  \033[0m
-
-jobs:
-  Formatting:
-    name: Run Formatting Check
-    if: ${{ github.event.issue.pull_request &&
-        ( ( github.event.comment.body == '/bot run uncrustify' ) ||
-          ( github.event.comment.body == '/bot run formatting' ) ) }}
-    runs-on: ubuntu-20.04
-    steps:
-    - name: Apply Formatting Fix
-      id: check-formatting
-      uses: FreeRTOS/CI-CD-Github-Actions/formatting-bot@main
-      with:
-        exclude-dirs: portable

.github/workflows/kernel-checks.yml

@@ -5,7 +5,7 @@ on: [push, pull_request]
 jobs:
   kernel-checker:
     name: FreeRTOS Kernel Header Checks
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
       # Install python 3
       - name: Tool Setup

.github/workflows/unit-tests.yml

@@ -3,7 +3,7 @@ on: [push, pull_request]
 
 jobs:
   run:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
     - name: Checkout Parent Repository
       uses: actions/checkout@v4.1.1

examples/template_configuration/FreeRTOSConfig.h

@@ -415,6 +415,8 @@
  * number of the failing assert (for example, "vAssertCalled( __FILE__, __LINE__
  * )" or it can simple disable interrupts and sit in a loop to halt all
  * execution on the failing line for viewing in a debugger. */
+
+/* *INDENT-OFF* */
 #define configASSERT( x )         \
     if( ( x ) == 0 )              \
     {                             \
@@ -422,6 +424,7 @@
         for( ; ; )                \
         ;                         \
     }
+/* *INDENT-ON* */
 
 /******************************************************************************/
 /* FreeRTOS MPU specific definitions. *****************************************/

include/croutine.h

@@ -246,7 +246,10 @@ void vCoRoutineSchedule( void );
  * \defgroup crSTART crSTART
  * \ingroup Tasks
  */
+
+/* *INDENT-OFF* */
 #define crEND()    }
+/* *INDENT-ON* */
 
 /*
  * These macros are intended for internal use by the co-routine implementation

include/task.h

@@ -333,6 +333,7 @@ typedef enum
         portGET_SPINLOCK( xCoreID, ( portSPINLOCK_TYPE * ) &( ( pxDataGroup )->xISRSpinlock ) ); \
         /* Increment the critical nesting count */                                               \
         portINCREMENT_CRITICAL_NESTING_COUNT( xCoreID );                                         \
+        /* Return the previous interrupt status */                                               \
         uxSavedInterruptStatus;                                                                  \
     } )
 #endif /* #if ( portUSING_GRANULAR_LOCKS == 1 ) */
@@ -350,6 +351,7 @@ typedef enum
     do {                                                                                                  \
         const BaseType_t xCoreID = ( BaseType_t ) portGET_CORE_ID();                                      \
         configASSERT( portGET_CRITICAL_NESTING_COUNT( xCoreID ) > 0U );                                   \
+        /* Decrement the critical nesting count */                                                        \
         portDECREMENT_CRITICAL_NESTING_COUNT( xCoreID );                                                  \
         if( portGET_CRITICAL_NESTING_COUNT( xCoreID ) == 0 )                                              \
         {                                                                                                 \
@@ -382,7 +384,9 @@ typedef enum
     do {                                                                                         \
         const BaseType_t xCoreID = ( BaseType_t ) portGET_CORE_ID();                             \
         configASSERT( portGET_CRITICAL_NESTING_COUNT( xCoreID ) > 0U );                          \
+        /* Decrement the critical nesting count */                                               \
         portDECREMENT_CRITICAL_NESTING_COUNT( xCoreID );                                         \
+        /* Release the ISR spinlock */                                                           \
         portRELEASE_SPINLOCK( xCoreID, ( portSPINLOCK_TYPE * ) &( pxDataGroup->xISRSpinlock ) ); \
         if( portGET_CRITICAL_NESTING_COUNT( xCoreID ) == 0 )                                     \
         {                                                                                        \

portable/Common/mpu_wrappers_v2.c

@@ -1059,8 +1059,8 @@
                                                   configRUN_TIME_COUNTER_TYPE * pulTotalRunTime ) /* PRIVILEGED_FUNCTION */
         {
             UBaseType_t uxReturn = 0;
-            UBaseType_t xIsTaskStatusArrayWriteable = pdFALSE;
-            UBaseType_t xIsTotalRunTimeWriteable = pdFALSE;
+            BaseType_t xIsTaskStatusArrayWriteable = pdFALSE;
+            BaseType_t xIsTotalRunTimeWriteable = pdFALSE;
             uint32_t ulArraySize = ( uint32_t ) uxArraySize;
             uint32_t ulTaskStatusSize = ( uint32_t ) sizeof( TaskStatus_t );
 

portable/IAR/RL78/portmacro.h

@@ -187,7 +187,7 @@
               * ; * memory mode) registers the _usCriticalNesting value and the Stack Pointer
               * ; * of the active Task onto the task stack.
               * ; *---------------------------------------------------------------------------*/
-    portSAVE_CONTEXT MACRO
+portSAVE_CONTEXT MACRO
     PUSH AX; /* Save AX Register to stack. */
     PUSH HL
     #if  __CODE_MODEL__ == __CODE_MODEL_FAR__
@@ -217,7 +217,7 @@
  * ; * general purpose registers and the CS and ES (only in __far memory mode)
  * ; * of the selected task from the task stack.
  * ; *---------------------------------------------------------------------------*/
-    portRESTORE_CONTEXT MACRO
+portRESTORE_CONTEXT MACRO
     MOVW AX, _pxCurrentTCB; /* Restore the Task stack pointer. */
     MOVW HL, AX
     MOVW AX, [ HL ]

portable/MPLAB/PIC32MZ/port.c

@@ -234,6 +234,11 @@ __attribute__(( weak )) void vApplicationSetupTickTimerInterrupt( void )
 {
 const uint32_t ulCompareMatch = ( (configPERIPHERAL_CLOCK_HZ / portTIMER_PRESCALE) / configTICK_RATE_HZ ) - 1UL;
 
+    /* PR1 is 16-bit. Ensure that the configPERIPHERAL_CLOCK_HZ and
+     * configTICK_RATE_HZ are defined such that ulCompareMatch value would fit
+     * in 16-bits. */
+    configASSERT( ( ulCompareMatch & 0xFFFF0000 ) == 0 );
+
     T1CON = 0x0000;
     T1CONbits.TCKPS = portPRESCALE_BITS;
     PR1 = ulCompareMatch;

portable/ThirdParty/GCC/Posix/port.c

@@ -48,8 +48,8 @@
 * stdio (printf() and friends) should be called from a single task
 * only or serialized with a FreeRTOS primitive such as a binary
 * semaphore or mutex.
-* 
-* Note: When using LLDB (the default debugger on macOS) with this port, 
+*
+* Note: When using LLDB (the default debugger on macOS) with this port,
 * suppress SIGUSR1 to prevent debugger interference. This can be
 * done by adding the following line to ~/.lldbinit:
 * `process handle SIGUSR1 -n true -p false -s false`
@@ -324,17 +324,23 @@ BaseType_t xPortStartScheduler( void )
 void vPortEndScheduler( void )
 {
     Thread_t * pxCurrentThread;
+    BaseType_t xIsFreeRTOSThread;
 
     /* Stop the timer tick thread. */
     xTimerTickThreadShouldRun = false;
     pthread_join( hTimerTickThread, NULL );
 
+    /* Check whether the current thread is a FreeRTOS thread.
+     * This has to happen before the scheduler is signaled to exit
+     * its loop to prevent data races on the thread key. */
+    xIsFreeRTOSThread = prvIsFreeRTOSThread();
+
     /* Signal the scheduler to exit its loop. */
     xSchedulerEnd = pdTRUE;
     ( void ) pthread_kill( hMainThread, SIG_RESUME );
 
     /* Waiting to be deleted here. */
-    if( prvIsFreeRTOSThread() == pdTRUE )
+    if( xIsFreeRTOSThread == pdTRUE )
     {
         pxCurrentThread = prvGetThreadFromTask( xTaskGetCurrentTaskHandle() );
         event_wait( pxCurrentThread->ev );

queue.c

@@ -339,6 +339,14 @@ static void prvInitialiseNewQueue( const UBaseType_t uxQueueLength,
         prvUnlockQueue( ( pxQueue ) );                                          \
         portRELEASE_SPINLOCK( portGET_CORE_ID(), &( pxQueue->xTaskSpinlock ) ); \
         vTaskPreemptionEnable( NULL );                                          \
+        if( ( xYieldAPI ) == pdTRUE )                                           \
+        {                                                                       \
+            taskYIELD_WITHIN_API();                                             \
+        }                                                                       \
+        else                                                                    \
+        {                                                                       \
+            mtCOVERAGE_TEST_MARKER();                                           \
+        }                                                                       \
     } while( 0 )
 #else /* #if ( ( portUSING_GRANULAR_LOCKS == 1 ) && ( configNUMBER_OF_CORES > 1 ) ) */
     #define queueLOCK( pxQueue )     \

tasks.c

@@ -5406,11 +5406,13 @@ BaseType_t xTaskIncrementTick( void )
              * SMP port. */
             configASSERT( portGET_CRITICAL_NESTING_COUNT( xCoreID ) == 0 );
 
-            if( uxSchedulerSuspended != ( UBaseType_t ) 0U
-                #if ( configUSE_TASK_PREEMPTION_DISABLE == 1 )
-                    || ( ( taskTASK_IS_RUNNING( pxCurrentTCBs[ xCoreID ] ) ) && ( pxCurrentTCBs[ xCoreID ]->xPreemptionDisable > 0U ) )
-                #endif
-                )
+            /* vTaskSwitchContext() must not be called with a task that has
+             * preemption disabled. */
+            #if ( configUSE_TASK_PREEMPTION_DISABLE == 1 )
+                configASSERT( pxCurrentTCBs[ xCoreID ]->xPreemptionDisable == 0U );
+            #endif
+
+            if( uxSchedulerSuspended != ( UBaseType_t ) 0U )
             {
                 /* The scheduler is currently suspended or the task
                  * has requested to not be preempted - do not allow
@@ -7498,11 +7500,11 @@ static void prvResetNextTaskUnblockTime( void )
                     BaseType_t xYieldCurrentTask;
 
                     /* Get the xYieldPending stats inside the critical section. */
-                    #if ( configUSE_TASK_PREEMPTION_DISABLE == 1 )
+                    #if ( portUSING_GRANULAR_LOCKS == 1 )
                         xYieldCurrentTask = xTaskUnlockCanYield();
                     #else
                         xYieldCurrentTask = xYieldPendings[ xCoreID ];
-                    #endif /* configUSE_TASK_PREEMPTION_DISABLE */
+                    #endif /* #if ( portUSING_GRANULAR_LOCKS == 1 ) */
 
                     kernelRELEASE_ISR_LOCK( xCoreID );
                     kernelRELEASE_TASK_LOCK( xCoreID );