Add Thread Local Storage (TLS) support using Picolibc functions

Thread Local Storage (TLS) offers a platform-native mechanism for
managing per-task variables that doesn't rely on custom support in
FreeRTOS for things like errno.

Picolibc uses TLS internally for all variables that are intended to be
task-local. Because of the TLS architecture, only variables which are
actually used end up getting allocate space in the TLS block. Contrast
this with the newlib 'struct _reent' block which holds all possible
task-local values, even for APIs not used by the application.

Picolibc also has TLS helper functions that provide the necessary
platform-specific code which makes the FreeRTOS changes platform
independent. This patch uses those hooks instead of providing the
platform specific code in FreeRTOS itself.

The picolibc helper functions rely on elements within the linker
script to arrange the TLS data in memory and define some symbols.
Applications wanting to use this mechanism will need changes in their
linker script when migrating to picolibc.

Signed-off-by: Keith Packard <[email protected]>

Author: keith-packard

.github/lexicon.txt

@@ -1063,6 +1063,7 @@ mclk
 mconfigintcoresw
 mcr
 mcu
+md
 mddr
 mder
 mdh
@@ -1344,6 +1345,7 @@ phy
 phya
 pic
 picnt
+picolibc
 pien
 piir
 pimr

include/FreeRTOS.h

@@ -74,6 +74,14 @@
     #include <reent.h>
 #endif
 
+#ifndef configUSE_PICOLIBC_TLS
+    #ifdef PICOLIBC_TLS
+        #define configUSE_PICOLIBC_TLS 1
+    #else
+        #define configUSE_PICOLIBC_TLS 0
+    #endif
+#endif
+
 /*
  * Check all the required application specific macros have been defined.
  * These macros are application specific and (as downloaded) are defined
@@ -1223,6 +1231,9 @@ typedef struct xSTATIC_TCB
     #if ( configUSE_POSIX_ERRNO == 1 )
         int iDummy22;
     #endif
+    #if ( configUSE_PICOLIBC_TLS == 1)
+        void *pvDummy23;
+    #endif
 } StaticTask_t;
 
 /*

tasks.c

@@ -58,6 +58,17 @@
     #include <stdio.h>
 #endif /* configUSE_STATS_FORMATTING_FUNCTIONS == 1 ) */
 
+#if ( configUSE_PICOLIBC_TLS == 1)
+
+/* If picolibc TLS support is being used, then initialize a per-thread
+ * TLS block off the end of the stack and set the TLS pointer at each
+ * task switch. More information about picolibc's thread local storage
+ * support is provided on the following link:
+ * https://github.com/picolibc/picolibc/blob/main/doc/tls.md */
+
+    #include <picotls.h>
+#endif
+
 #if ( configUSE_PREEMPTION == 0 )
 
 /* If the cooperative scheduler is being used then a yield should not be
@@ -328,6 +339,13 @@ typedef struct tskTaskControlBlock       /* The old naming convention is used to
     #if ( configUSE_POSIX_ERRNO == 1 )
         int iTaskErrno;
     #endif
+    #if ( configUSE_PICOLIBC_TLS == 1)
+        /* Pointer to thread-local variables for this task.
+         * These are allocated from the task stack and managed
+         * using Picolibc TLS support functions.
+         */
+        void *pvTls;
+    #endif
 } tskTCB;
 
 /* The old tskTCB name is maintained above then typedefed to the new TCB_t name
@@ -986,6 +1004,29 @@ static void prvInitialiseNewTask( TaskFunction_t pxTaskCode,
         }
     #endif
 
+    #if ( configUSE_PICOLIBC_TLS == 1)
+        {
+            /* Allocate thread local storage block off the end of the
+             * stack. The _tls_size() function returns the size (in
+             * bytes) of the total TLS area used by the application */
+            #if ( portSTACK_GROWTH < 0 )
+                {
+                    pxTopOfStack = ( StackType_t *) ( ( ( portPOINTER_SIZE_TYPE) pxTopOfStack) - _tls_size() );
+                    pxNewTCB->pvTls = pxTopOfStack;
+                }
+            #else /* portSTACK_GROWTH */
+                {
+                    pxNewTCB->pvTls = pxTopOfStack;
+                    pxTopOfStack = ( StackType_t *) ( ( ( portPOINTER_SIZE_TYPE) pxTopOfStack) + _tls_size() );
+                }
+            #endif /* portSTACK_GROWTH */
+            /* Initialize the thread local storage block. This copies
+             * the initialization data to initialized variables and
+             * clears uninitialized variables to zero */
+            _init_tls(pxNewTCB->pvTls);
+        }
+    #endif
+
     #if ( configUSE_NEWLIB_REENTRANT == 1 )
         {
             /* Initialise this task's Newlib reent structure.
@@ -2068,6 +2109,11 @@ void vTaskStartScheduler( void )
                 _impure_ptr = &( pxCurrentTCB->xNewLib_reent );
             }
         #endif /* configUSE_NEWLIB_REENTRANT */
+        #if ( configUSE_PICOLIBC_TLS == 1)
+            {
+                _set_tls(pxCurrentTCB->pvTls);
+            }
+        #endif 
 
         xNextTaskUnblockTime = portMAX_DELAY;
         xSchedulerRunning = pdTRUE;
@@ -3081,6 +3127,11 @@ void vTaskSwitchContext( void )
                 _impure_ptr = &( pxCurrentTCB->xNewLib_reent );
             }
         #endif /* configUSE_NEWLIB_REENTRANT */
+        #if ( configUSE_PICOLIBC_TLS == 1)
+            {
+                _set_tls(pxCurrentTCB->pvTls);
+            }
+        #endif 
     }
 }
 /*-----------------------------------------------------------*/