[casaroli]

Summary

Four commits for __thread variables with a toolchain that has no native TLS. The arm64 TPIDR_EL0 work is in #20821.

1. boards: Five boards linked libgcc inside the group of the user libraries of a protected build (at32f437-mini, qemu-armv7r, stm32f4discovery, lm3s6965-ek, fvp-armv8r). A function that both libc and libgcc define then came from libgcc. They now link libgcc after the group, as the other boards do.
2. libs/libc/tls: A toolchain without native TLS (for example the Arm GNU toolchain for aarch64-none-elf, or for arm-none-eabi 13.2) compiles __thread into calls to __emutls_get_address(), and that toolchain's libgcc keeps one copy per program. libc now provides __wrap___emutls_get_address() and __wrap___emutls_register_common() with one copy per thread, and the image links with --wrap=__emutls_get_address --wrap=__emutls_register_common (Make and CMake), so the calls go to libc and never to libgcc. tools/Config.mk gives the same options as EMUTLS_LDFLAGS. The Toolchain.defs of each architecture that can have CONFIG_TLS_EMUTLS (and the sim Make.defs) adds it to LDELFFLAGS and LDMODULEFLAGS, and the export keeps it, so the modules and programs of the apps build get it with no change in apps (cmake: Link the emutls calls of an ELF program to libc. #20812 does the same for CMake). The boards that set these variables again in their Make.defs get it after boards: Remove the ELF and module flags that replace the arch values. #20844. The real names stay as weak aliases, for a link without --wrap: libc comes before libgcc there, and in a --whole-archive link the strong symbols of libgcc win without a conflict. With LTO the link also gets -u for the two __wrap_ names, because the compiler makes the calls only after the linker has chosen the archive members. CONFIG_TLS_EMUTLS (no prompt) builds this for the GCC and clang toolchains, but not for armclang, GHS or 8-bit AVR (no atomic pointer loads); without it nothing changes. The sim has it with GCC and the GNU linker (Linux, MinGW, whose GCC uses emulated TLS): it links NuttX into nuttx.rel with --wrap, and nuttx-names.in renames the weak real names, so the host program keeps the copy of its own libgcc. The macOS and MSVC linkers have no --wrap, so the sim there does not have it. The control object and __wrap___emutls_register_common() use the integer types of libgcc (mode(word), mode(pointer)), as GCC declares its built-in. The TLS info of each thread points to its copies; exit(), quick_exit() and pthread_exit() free them after the exit functions and the TLS destructors. It does not use pthread keys and does not need CONFIG_TLS_NELEM. libc.csv lists both __wrap_ functions, so code loaded at run time finds them in the system symbol table.
3. libs/libc: When a module or shared library is unloaded, the loader gives libc the data range of the module. libc frees the copies of its variables in every thread and reuses their indexes. Before, each load took a new index and the old copies stayed until the threads exited.
4. Documentation: thread_local_storage.rst said that libgcc's emutls implements __thread.

Impact

__thread variables are per thread in flat, protected and kernel builds, with any value of CONFIG_TLS_NELEM, on every architecture whose GCC has no native TLS. An image without __thread variables links only two pointers and their checks (lm3s6965-ek:qemu-flat: +64 bytes text). exit(), pthread_exit() and the loader call the code through these pointers, which libc sets on the first use, so a program without __thread variables does not link it. armclang, GHS, 8-bit AVR and the sim on macOS or with MSVC do not change. On the Linux sim, GCC uses native TLS, so only code that calls __emutls_get_address() (as code built for emulated TLS does) uses it.

Testing

QEMU 11 with HVF on an Apple M4 (arm64), TCG for mps2-an500. Test programs: several threads that use __thread variables (copy per thread, initial value, alignment, 12 variables, a makecontext() stack, C++ thread_local, an atexit() handler that reads __thread), and a load test that loads and unloads a module with a __thread variable 300 times from two threads (dlopen() and exec()).

Configuration	master	This PR
qemu-armv8a:nsh (flat), tests built in, CONFIG_TLS_NELEM 0, 4 and 16	all threads share one copy	pass
qemu-armv8a:nsh, CMake; and CMake with LTO	all threads share one copy	pass
qemu-armv8a:knsh (kernel build), programs from the apps build and from the export	all threads share one copy	pass
qemu-armv8a:nsh, apps master, tlsgroup as a loadable module (CONFIG_EXAMPLES_HELLO=m, CONFIG_EXECFUNCS_SYSTEM_SYMTAB)	the module has libgcc's __emutls_get_address; tlsgroup: FAIL	the module has U __wrap___emutls_get_address; tlsgroup: PASS
qemu-armv8a:knsh export, scripts/Make.defs	LDELFFLAGS = -r -e _start, LDMODULEFLAGS = -r	both end with --wrap=__emutls_get_address --wrap=__emutls_register_common
qemu-armv8a:nsh load test, CONFIG_TLS_NELEM 0 and 4, 1 and 4 CPUs	index grows to 2400, heap grows	index 1 or 2, heap flat
mps2-an500:nsh, Arm GNU Toolchain 13.2, LTO (links through gcc)		pass
mps2-an500:knsh (protected), 13.2		pass
Pimoroni Pico Plus 2 (RP2350, Cortex-M33), pimoroni-pico-2-plus:nsh, Arm GNU 13.2 (emulated TLS), tlsgroup run twice	the two threads and main use one copy (all at the same address); tlsgroup: FAIL	each thread has its own copy; tlsgroup: PASS both runs; ostest_main: Exiting with status 0
ostest on qemu-armv8a:knsh and qemu-armv8a:nsh		ostest_main: Exiting with status 0
CONFIG_DEBUG_OPT_UNUSED_SECTIONS + CONFIG_DEBUG_LINK_WHOLE_ARCHIVE, qemu-armv7a:nsh and mps2-an500:nsh, Arm GNU 13.2 and 15.3; qemu-armv7a:nsh with CMake; rv-virt:nsh	links	links, no multiple definition
sim:nsh, Linux x86_64, GCC 12 (Make and CMake)		CONFIG_TLS_EMUTLS on, nuttx.rel linked with --wrap, the host link without it; ostest_main: Exiting with status 0
sim:nsh, Linux x86_64, a program with the code that a compiler with emulated TLS makes for __thread (2 threads)	emutest: main has 219 ..., bad 41 / FAIL (host libgcc __emutls_get_address@GCC_4.3.0)	emutest: PASS
sim:nsh, macOS (clang)		CONFIG_TLS_EMUTLS off, no --wrap; ostest_main: Exiting with status 0
sim:windows configuration (CMake): nuttx/tls.h compiled without GNU C		no emutls declarations, compiles

Builds: each commit on qemu-armv8a:nsh, qemu-armv8a:knsh and lm3s6965-ek:qemu-flat; the protected configurations of the five boards: qemu-armv7r:pnsh, stm32f4discovery:kostest, lm3s6965-ek:qemu-kostest, lm3s6965-ek:qemu-protected, fvp-armv8r:pnsh.

tools/checkpatch.sh -c -u -m -g passes.

[github-actions]

MemBrowse Memory Report · Explore what changed →

esp32-devkitc

• ROM: .flash.text +28 B (+0.0%, 127,200 B / 4,194,272 B, total: 3% used)
• irom0_0_seg: .flash.text +28 B (+0.0%, 91,216 B / 3,342,304 B, total: 3% used)

mirtoo

• kseg0_progmem: .text +20 B (+0.0%, 67,404 B / 131,072 B, total: 51% used)
• kseg1_datamem: .sbss +4 B (+0.2%, 2,604 B / 32,256 B, total: 8% used)

qemu-armv8a

• Code: .text.exit +16 B, .text.pthread_exit +16 B (+0.0%, 351,920 B)
• Data: +8 B (+0.0%, 77,711 B)

qemu-intel64

• Code: .text +48 B (+0.0%, 8,685,725 B)
• Data: .bss +64 B (+0.1%, 125,113 B)

s698pm-dkit

• Code: .text +192 B (+0.1%, 379,408 B)
• Data: .bss +16 B (+0.1%, 11,883 B)

stm32-nucleo-f103rb

• flash: .text +16 B (+0.0%, 34,612 B / 131,072 B, total: 26% used)
• sram: .bss +4 B (+0.2%, 2,476 B / 20,480 B, total: 12% used)

No memory changes detected for:

• arduino-mega2560
• hifive1-revb
• rx65n-rsk2mb

---

_{Catch memory regressions in CI with MemBrowse. Free for open source.}