micropython · tve · Dec 27, 2019 · Dec 29, 2019 · Feb 14, 2020 · Feb 14, 2020
diff --git a/docs/develop/natmod.rst b/docs/develop/natmod.rst
@@ -67,6 +67,18 @@ 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
 ------------------------