From e993f53877027bc46b226d026845e523c2cc94ca Mon Sep 17 00:00:00 2001 From: Alessandro Gatti Date: Wed, 9 Jul 2025 17:14:13 +0200 Subject: [PATCH] docs/develop/natmod: Add notes on Picolibc and natmods. This commit adds some documentation on what are the limitations of using Picolibc as a standard C library for native modules. This also contains a reference to the "errno" issue when building natmods on RV32 that the PR this commit is part of, as it is not obvious how to approach this issue when encountered for the first time. Signed-off-by: Alessandro Gatti --- docs/develop/natmod.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/develop/natmod.rst b/docs/develop/natmod.rst index 2ccd832885..072d78b207 100644 --- 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 `_ 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 ----------------