Adding user C module into the embed port?

[MHe999]

Hi,

I recently found the embed port and it seems very useful for our purposes. Now I'm wondering how to include a self made C module into the port.

I have made some very simple user modules with the minimal port and STM32 successfully, but I'm not very fluent with Make, and the makefile of the embed port looks a bit different that the one in the minimal port, so I don't really know what to add to include a C module.

Thanks in advance for any help.

[cwalther]

I am working on extending the embed port in PR #11430 and adding C modules is one of the things I have already achieved. You can follow along with the commits there, you might not need all of them (possibly even none). If you have specific questions, please ask.

[jimmo]

Just to clarify -- we have a thing called "user C modules" which is how to add an out-of-tree module into a MicroPython port. i.e. it's a mechanism for adding additional code into MicroPython's build system.

But in the case of the embed port, the idea is that you're embedding MicroPython into your own build/project. So you don't really need the "user C module" machinery, because you can just include those files in your project.

That said, if you're defining things like modules, functions, classes, etc you're going to need macros like MP_REGISTER_MODULE and MP_QSTR_... to be processed. And it turns out the user C module machinery does exactly that, but I'm not entirely sure that this is the best way for the embed port to work, I kind of figured we'd have a more direct way of just doing the preprocessing part, but leaving the actual compilation of the files to be handled by the embedding project's build. (I will try and get some time to add more detailed feedback on your PR @cwalther ).

To put that another way, if you have a file in your project which contains MicroPython classes/functions/modules/etc, you have two options:

• Add them into the MicroPython build, in which case they will become part of the output of the embed port's build, and then they get included with the embedding project's build system that way.
• The files are part of the embedding project, just that the embed port knew to process them such that just their QSTRs and module registrations (etc) became part of the embed port output. They are compiled and linked into the embedding project's build as normal.

If I understand correctly, #11430 does the former, but I think the latter is simpler and more versatile.

[cwalther]

No, I would say it does the latter. The user module source files do not end up in the micropython_embed output. But I didn’t change anything for that, I just used the existing USER_C_MODULES mechanism, and that’s what it happened to do. Maybe it does more than that (unnecessary things), I didn’t check in detail, I was satisfied when it worked.

[MHe999]

Hi @cwalther and @jimmo, and thanks very much for the comments.

I got my very simple test modules working now. Apparently I had it almost correctly already, but following @cwalther 's commits I got it now running.

The goal is to have a lot of these user modules that have a tight connection to the rest of our project. That is why I'm looking for a way to simplify the build process and maintaining as much as possible.

So far my idea has been that I have the minimum amount of code in the MicroPython side of the build, just the QSTR and module registration things. The actual implementation of the functionality is made in our project and only one header is included in the user module source file in the MicroPython build. That is also how I tested this with STM32 and FreeRTOS a while ago.

I try to include a code example below, mpy_led_blinker.c which is one of the user modules I'm testing with. It includes "led_blinker_impl.h" which declares the function int led_blinker_blink_led(int duration_ms). It is defined elsewhere in the project where MicroPython is going to be embedded.

Any suggestions on how to improve this process are very welcome.

// Include MicroPython API.
#include "py/obj.h"
#include "py/objstr.h"
#include "py/runtime.h"

#include "led_blinker_impl.h"

STATIC mp_obj_t blink_led(mp_obj_t duration_ms) {
    int retval = led_blinker_blink_led(mp_obj_get_int(duration_ms)); 
    return mp_obj_new_int(retval);
}

STATIC MP_DEFINE_CONST_FUN_OBJ_1(blink_led_obj, blink_led);

STATIC const mp_rom_map_elem_t mpy_led_blinker_globals_table[] = {
    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_mpy_led_blinker) },
    { MP_ROM_QSTR(MP_QSTR_blink_led), MP_ROM_PTR(&blink_led_obj) }
};
STATIC MP_DEFINE_CONST_DICT(mpy_led_blinker_globals, mpy_led_blinker_globals_table);

// Define module object.
const mp_obj_module_t mpy_led_blinker = {
    .base = { &mp_type_module },
    .globals = (mp_obj_dict_t *)&mpy_led_blinker_globals,
};

// Register the module to make it available in Python.
MP_REGISTER_MODULE(MP_QSTR_mpy_led_blinker, mpy_led_blinker);