From be92aacba3fab9f726428168b7c2e61e589ab2be Mon Sep 17 00:00:00 2001 From: Thorsten von Eicken Date: Fri, 27 Dec 2019 13:28:40 -0800 Subject: [PATCH] docs/develop: Detail how to add symbols to mp_fun_table for native mods. --- docs/develop/natmod.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/develop/natmod.rst b/docs/develop/natmod.rst index 1ce2381640dd..251f21e9f4d1 100644 --- a/docs/develop/natmod.rst +++ b/docs/develop/natmod.rst @@ -67,6 +67,19 @@ The known limitations are: So, if your C code has writable data, make sure the data is defined globally, without an initialiser, and only written to within functions. +Linker limitation: the native module is not linked against the symbol table of the +full MicroPython firmware. Rather, it is linked against an explicit table of exported +symbols found in ``mp_fun_table`` (in ``py/nativeglue.h``), that is fixed at firmware +build time. It is thus not possible to simply call some arbitrary HAL/OS/RTOS/system +function, for example. + +New symbols can be added to the end of the table and the firmware rebuilt. +The symbols also need to be added to ``tools/mpy_ld.py``'s ``fun_table`` dict in the +same location. This allows ``mpy_ld.py`` to be able to pick the new symbols up and +provide relocations for them when the mpy is imported. Finally, if the symbol is a +function, a macro or stub should be added to ``py/dynruntime.h`` to make it easy to +call the function. + Defining a native module ------------------------