Doc how to add new symbols to mp_fun_table for native modules #5463
Conversation
docs/develop/natmod.rst
Outdated
| 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``. It is thus not possible to simply call some arbitrary function | ||
| in FreeRTOS, for example. Adding new symbols to the end of the table is relatively easy, |
There was a problem hiding this comment.
I'd rephrase this to be a bit more general, eg something like "... some arbitrary HAL/OS/RTOS/system function, for exampe".
docs/develop/natmod.rst
Outdated
| @@ -67,6 +67,14 @@ 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``. It is thus not possible to simply call some arbitrary function | |||
There was a problem hiding this comment.
Probably a good idea to state the file this struct is found in.
| in FreeRTOS, for example. Adding new symbols to the end of the table is relatively easy, | ||
| they then 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. |
There was a problem hiding this comment.
I think it'd be a good idea to actually try this out first, to see if it does work (or not).
|
This may be a dumb question, as I have never attempted any of this and am not too well versed in the details of how linkers and loaders work, but one thing is unclear to me just from the added doc snippet: Is the modification of this table something that needs to be done when building the firmware that is going to load the module, or when building the module? In other words, can a module call any function that is present in the firmware, or only the ones that were explicitly exported at the time the firmware was built? |
The former: new MicroPython firmware that loads modules needs to be rebuilt, so it includes the new functions in the
In short, a native module can only call functions explicitly exported / included in Technically it would be possible to call any MicroPython firmware function if you knew its address in ROM, but that would change across builds and ports, making it quite impractical (although still possible if you really wanted to minimise code size of the firmware, and never recompiled the main firmware). |
|
Thanks for the clarification, that makes sense. @tve, do you think you could add a note to that effect to your proposed paragraph? Something along the lines of - symbols found in ``mp_fun_table`` (in ``py/nativeglue.h``).
+ symbols found in ``mp_fun_table`` (in ``py/nativeglue.h``), fixed at firmware build time.
- Adding new symbols to the end of the table is relatively easy,
+ New symbols can be added to the end of the table and the firmware rebuilt,I guess this also means that if |
The functionality of |
Came here for this function. I believe manipulating larger data sets might be one of the main use cases for native modules. |
|
@tve this looks good, is it ready to merge? |
|
Ok, rebased, squashed and merged in be92aac |
See also #5458