micropython · dpgeorge · Jul 20, 2025 · Jul 8, 2025 · Jul 9, 2025
diff --git a/docs/develop/natmod.rst b/docs/develop/natmod.rst
@@ -67,6 +67,9 @@ The known limitations are:
 
 * static BSS variables are not supported; workaround: use global BSS variables
 
+* thread-local storage variables are not supported on rv32imc; workaround: use
+  global BSS variables or allocate some space on the heap to store them
+
 So, if your C code has writable data, make sure the data is defined globally,
 without an initialiser, and only written to within functions.
 
@@ -225,6 +228,26 @@ other module, for example::
     print(factorial.factorial(10))
     # should display 3628800
 
+Using Picolibc when building modules
+------------------------------------
+
+Using `Picolibc <https://github.com/picolibc/picolibc>`_ as your C standard
+library is not only supported, but in fact it is the default for the rv32imc
+platform.  However, there are a couple of things worth mentioning to make sure
+you don't run into problems later when building code.
+
+Some pre-built Picolibc versions (for example, those provided by Ubuntu Linux
+as the ``picolibc-arm-none-eabi``, ``picolibc-riscv64-unknown-elf``, and
+``picolibc-xtensa-lx106-elf`` packages) assume thread-local storage (TLS) is
+available at runtime, but unfortunately MicroPython modules do not support that
+on some architectures (namely ``rv32imc``).  This means that some
+functionalities provided by Picolibc will default to use TLS, returning an
+error either during compilation or during linking.
+
+For an example on how this may affect you, the ``examples/natmod/btree``
+example module contains a workaround to make sure ``errno`` works (look for
+``__PICOLIBC_ERRNO_FUNCTION`` in the Makefile and follow the trail from there).
+
 Further examples
 ----------------
 

diff --git a/examples/natmod/btree/Makefile b/examples/natmod/btree/Makefile
@@ -36,6 +36,9 @@ ifeq ($(ARCH),xtensa)
 MPY_EXTERN_SYM_FILE=$(MPY_DIR)/ports/esp8266/boards/eagle.rom.addr.v6.ld
 endif
 
+# Use our own errno implementation if Picolibc is used
+CFLAGS += -D__PICOLIBC_ERRNO_FUNCTION=__errno
+
 include $(MPY_DIR)/py/dynruntime.mk
 
 # btree needs gnu99 defined

diff --git a/ports/qemu/Makefile b/ports/qemu/Makefile
@@ -191,12 +191,11 @@ test_full: $(BUILD)/firmware.elf
 	cd $(TOP)/tests && ./run-tests.py $(RUN_TESTS_FULL_ARGS) --via-mpy
 	cd $(TOP)/tests && ./run-tests.py $(RUN_TESTS_FULL_ARGS) --via-mpy --emit native
 
-# "btree" currently does not build for rv32imc (Picolibc TLS incompatibility).
 .PHONY: test_natmod
 test_natmod: $(BUILD)/firmware.elf
 	$(eval DIRNAME=ports/$(notdir $(CURDIR)))
 	cd $(TOP)/tests && \
-		for natmod in deflate framebuf heapq random_basic re; do \
+		for natmod in btree deflate framebuf heapq random_basic re; do \
 		./run-natmodtests.py -p -d execpty:"$(QEMU_SYSTEM) $(QEMU_ARGS) -serial pty -kernel ../$(DIRNAME)/$<" extmod/$$natmod*.py; \
 		done
 

diff --git a/tools/ci.sh b/tools/ci.sh
@@ -563,7 +563,7 @@ function ci_native_mpy_modules_build {
     else
         arch=$1
     fi
-    for natmod in deflate features1 features3 features4 framebuf heapq random re
+    for natmod in btree deflate features1 features3 features4 framebuf heapq random re
     do
         make -C examples/natmod/$natmod ARCH=$arch clean
         make -C examples/natmod/$natmod ARCH=$arch
@@ -576,12 +576,6 @@ function ci_native_mpy_modules_build {
     else
         make -C examples/natmod/features2 ARCH=$arch
     fi
-
-    # btree requires thread local storage support on rv32imc.
-    if [ $arch != "rv32imc" ]; then
-        make -C examples/natmod/btree ARCH=$arch clean
-        make -C examples/natmod/btree ARCH=$arch
-    fi
 }
 
 function ci_native_mpy_modules_32bit_build {