docs/develop: Detail how to add symbols to mp_fun_table for native mods.

1 files changed, 13 insertions, 0 deletions

diff --git a/docs/develop/natmod.rst b/docs/develop/natmod.rst
index 1ce238164..251f21e9f 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
 ------------------------