Thread Local Storage

Thread local storage (TLS) is a mechanism that allows each thread to have its own copy of a variable. This is useful for variables that are used by multiple functions in a thread, but should not be shared with other threads.

There are some approaches to using TLS in NuttX:

1. Use the pthread_key_create() and pthread_setspecific() that from the POSIX standard. This is the most portable approach, but it requires that the platform support pthreads. 2. Use the thread_local or __thread keyword from the C standard: https://gcc.gnu.org/onlinedocs/gcc/extensions-to-the-c-language-family/thread-local-storage.html

Configuration

CONFIG_SCHED_THREAD_LOCAL  /* Enable native thread local storage support */

Enable it to support native thread local storage, which is required that the compiler configured with --enable-tls option, this approach is more efficient if the compiler support it.

If your compiler support it then you still need further configuration to use it:

  1. Enable CONFIG_SCHED_THREAD_LOCAL in menuconfig

  2. Handle tbss and tdata sections in linker script, your can refer to the example in rv-virt

To confirm that your compiler supports TLS, you can try this command:

arm-none-eabi-gcc --verbose
COLLECT_GCC=arm-none-eabi-gcc
COLLECT_LTO_WRAPPER=/home/huang/.local/pkg/arm/bin/../libexec/gcc/arm-none-eabi/13.3.1/lto-wrapper
Target: arm-none-eabi
Configured with: /data/jenkins/workspace/GNU-toolchain/arm-13/src/gcc/configure --target=arm-none-eabi --prefix=/data/jenkins/workspace/GNU-toolchain/arm-13/build-arm-none-eabi/install --with-gmp=/data/jenkins/workspace/GNU-toolchain/arm-13/build-arm-none-eabi/host-tools --with-mpfr=/data/jenkins/workspace/GNU-toolchain/arm-13/build-arm-none-eabi/host-tools --with-mpc=/data/jenkins/workspace/GNU-toolchain/arm-13/build-arm-none-eabi/host-tools --with-isl=/data/jenkins/workspace/GNU-toolchain/arm-13/build-arm-none-eabi/host-tools --disable-shared --disable-nls --disable-threads --disable-tls --enable-checking=release --enable-languages=c,c++,fortran --with-newlib --with-gnu-as --with-headers=yes --with-gnu-ld --with-native-system-header-dir=/include --with-sysroot=/data/jenkins/workspace/GNU-toolchain/arm-13/build-arm-none-eabi/install/arm-none-eabi --with-multilib-list=aprofile,rmprofile --with-pkgversion='Arm GNU Toolchain 13.3.Rel1 (Build arm-13.24)' --with-bugurl=https://bugs.linaro.org/
Thread model: single
Supported LTO compression algorithms: zlib
gcc version 13.3.1 20240614 (Arm GNU Toolchain 13.3.Rel1 (Build arm-13.24))

Then you can see --disable-tls in the output, which means that your compiler does not support TLS.

In this case, you can still use the thread local relative keyword, but it would be implemented by libgcc’s emutls.

NuttX’s libc provides its own version (CONFIG_TLS_EMUTLS, set for the GCC and clang toolchains when libgcc is the builtin library, CONFIG_BUILTIN_TOOLCHAIN; the sim has it with GCC and the GNU linker, as on Linux and MinGW), and the link sends the calls to __emutls_get_address() there with --wrap. A libgcc built with the single thread model (Thread model: single above) keeps one copy of each variable for the whole program; with the libc version, each thread gets its own copy, made on the first use and freed when the thread exits. CONFIG_TLS_EMUTLS is on by default. With LTO every program links this code (about 800 bytes on Cortex-M), so a board that has no space for it can disable it; then all threads share one copy of each variable, as with libgcc.

The image, the modules and the programs of a kernel build are linked with --wrap; code loaded at run time finds the libc version in the system symbol table (CONFIG_EXECFUNCS_SYSTEM_SYMTAB).