b63e528076
This commit fixes building the "btree" example natmod on RV32 when Picolibc is being used and uses thread-local storage for storing the errno variable. The fix is surprisingly simple: Picolibc allows overriding the function that will provide a pointer to the "errno" variable, and the btree natmod integration code already has all of this machinery set up as part of its library integration. Redirecting Picolibc to the already existing pointer provider function via a compile-time definition is enough to let the module compile and pass QEMU tests. This workaround will work on any Picolibc versions (Arm, RV32, Xtensa, etc.) even if TLS support was not enabled to begin with, and will effectively do nothing if the toolchain used will rely on Newlib to provide standard C library functions. Given that the btree module now builds and passes the relevant natmod tests, said module is now part of the QEMU port's natmod testing procedure, and CI now will build the btree module for RV32 as part to its checks. Signed-off-by: Alessandro Gatti <a.gatti@frob.it>
Dynamic Native Modules
Dynamic Native Modules are .mpy files that contain native machine code from a language other than Python. For more info see the documentation.
This should not be confused with User C Modules which are a mechanism to add additional out-of-tree modules into the firmware build.
Examples
This directory contains several examples of writing dynamic native modules, in two main categories:
-
Feature examples.
-
features0- A module containing a single "factorial" function which demonstrates working with integers. -
features1- A module that demonstrates some common tasks:- defining simple functions exposed to Python
- defining local, helper C functions
- defining constant integers and strings exposed to Python
- getting and creating integer objects
- creating Python lists
- raising exceptions
- allocating memory
- BSS and constant data (rodata)
- relocated pointers in rodata
-
features2- This is a hybrid module containing both Python and C code, and additionally the C code is spread over multiple files. It also demonstrates using floating point (only when the target supports hardware floating point). -
features3- A module that shows how to use types, constant objects, and creating dictionary instances. -
features4- A module that demonstrates how to define a class.
-
-
Dynamic version of existing built-ins.
This provides a way to add missing functionality to firmware that doesn't include certain built-in modules. See the
heapq,random,re,deflate,btree, andframebufdirectories.So for example, if your firmware was compiled with
MICROPY_PY_FRAMEBUFdisabled (e.g. to save flash space), then it would not include theframebufmodule. Theframebufnative module provides a way to add theframebufmodule dynamically.The way these work is they define a dynamic native module which
#include's the original module and then does the necessary initialisation of the module's globals dict.
Build instructions
To compile an example, you need to have the same toolchain available as
required for your target port. e.g. arm-none-eabi-gcc for any ARM Cortex M
target. See the port instructions for details.
You also need to have the pyelftools Python package available, either via
your system package manager or installed from PyPI in a virtual environment
with pip.
Each example provides a Makefile. You should specify the ARCH argument to
make (one of x86, x64, armv6m, armv7m, xtensa, xtensawin, rv32imc):
$ cd features0
$ make ARCH=armv7m
$ mpremote cp features0.mpy :