MicroPython移植(2) : 实现一个MicroPython Module 的基本流程

本文以module board为例, 说明mpy的module实现, board module包含一个 LED class和一个__name__方法

1. 使用模板代码进行基础函数的实现

使用mpy提供的模板代码, 声明python 方法及进行对应的c实现, 示例代码格式(忽略掉无关的实现细节):

static inline void led_off(board_led_obj_t * const led_obj) {
    //ignore the details
}

static inline void led_on(board_led_obj_t * const led_obj) {
    //ignore the details
}

void mp_led_init(void) {
    //ignore the details
}

void led_state(board_led_obj_t * led_obj, int state) {
    if (state == 1) {
        led_on(led_obj);
    } else {
        led_off(led_obj);
    }
}

void led_toggle(board_led_obj_t * led_obj) {
    if(led_obj->led_state == LED_ON) {
        led_off(led_obj);
    } else {
        led_on(led_obj);
    }    
}

void led_obj_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
    ...
}

STATIC mp_obj_t led_obj_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
    ...
}

mp_obj_t led_obj_on(mp_obj_t self_in) {
    board_led_obj_t *self = self_in;
    led_state(self, 1);
    return mp_const_none;
}

mp_obj_t led_obj_off(mp_obj_t self_in) {
    board_led_obj_t *self = self_in;
    led_state(self, 0);
    return mp_const_none;
}

mp_obj_t led_obj_toggle(mp_obj_t self_in) {
    board_led_obj_t *self = self_in;
    led_toggle(self);
    return mp_const_none;
}

2. 建立 c代码和python 方法对象的映射关系

通过以下代码, 将LED class 的on/off/toggle 方法分别建立对应c函数的映射实现, 到目前, 还没有声明class名为LED

STATIC MP_DEFINE_CONST_FUN_OBJ_1(led_obj_on_obj, led_obj_on);
STATIC MP_DEFINE_CONST_FUN_OBJ_1(led_obj_off_obj, led_obj_off);	
STATIC MP_DEFINE_CONST_FUN_OBJ_1(led_obj_toggle_obj, led_obj_toggle);

STATIC const mp_rom_map_elem_t led_locals_dict_table[] = {
    { MP_ROM_QSTR(MP_QSTR_on),      MP_ROM_PTR(&led_obj_on_obj) },
    { MP_ROM_QSTR(MP_QSTR_off),     MP_ROM_PTR(&led_obj_off_obj) },
    { MP_ROM_QSTR(MP_QSTR_toggle),  MP_ROM_PTR(&led_obj_toggle_obj) },
};

3. 建立字典关系，并声明 mp_obj_type_t (mpy对象)基本类型

STATIC MP_DEFINE_CONST_DICT(led_locals_dict, led_locals_dict_table);

const mp_obj_type_t board_led_type = {
    { &mp_type_type },
    .name = MP_QSTR_LED,
    .print = led_obj_print,
    .make_new = led_obj_make_new,
    .locals_dict = (mp_obj_dict_t*)&led_locals_dict,
};

截止目前,完成了 class 对象的实现和映射

4. 进行mpy module的声明

STATIC const mp_rom_map_elem_t board_module_globals_table[] = {
    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_myboard) },             //set board name as 'myboard'
    { MP_ROM_QSTR(MP_QSTR_LED), MP_ROM_PTR(&board_led_type) },
};

STATIC MP_DEFINE_CONST_DICT(board_module_globals, board_module_globals_table);

const mp_obj_module_t board_module = {
    .base = { &mp_type_module },
    .globals = (mp_obj_dict_t*)&board_module_globals,
};

在 board_module_globals_table 表中, 声明了两个元素:

• 元素1为 name, 及board的name属性

• 元素2为 LED class, 映射为 board_led_type 对象, 在这里, 就将class 名映射为LED

5. 定义所有涉及的qstr

宏MP_ROM_QSTR引用的参数, 会扩展成一个字符串, 但这个字符串默认是没有声明状态, 编译的时候会造成类似如下错误:

 error: 'MP_QSTR_LED' undeclared here (not in a function)
     {MP_ROM_QSTR(MP_QSTR_LED), MP_ROM_PTR(&board_led_type)},
                  ^
../../py/obj.h:92:56: note: in definition of macro 'MP_OBJ_NEW_QSTR'
 #define MP_OBJ_NEW_QSTR(qst) ((mp_obj_t)((((mp_uint_t)(qst)) << 2) | 2))

这个时候, 需要在 qstrdefsport.h 文件里面, 使用宏定义Q进行缺失字符串的声明, 声明不用包含 MP_QSTR_， 如上述代码中, 需要声明的qstr有:

Q(LED)			//board模块的LED类的类名
Q(on)			//LED类 on方法名
Q(off)			//LED类 off方法名
Q(toggle)		//LED类 toggle方法名
Q(myboard)		//将board的__name__属性设置为 myboard

在Makefile中, 会有变量QSTR_DEFS对 qstrdefsport.h 进行编译引用并生成 qstr

6. 向系统注册自定义的mpy module

通过以上步骤, 实现了一个自定义module的声明和实现, 但还未向系统注册, 这个时候系统还无法引用此module，通过定义如下宏向系统注册module:

extern const struct _mp_obj_module_t board_module;

#define MICROPY_PORT_BUILTIN_MODULES \
	... \ //其他注册模块
    { MP_ROM_QSTR(MP_QSTR_board), MP_ROM_PTR(&board_module) }, \
    ... \ //其他注册模块

注册的module 名称为 board, 对应的对象属性为board_module, 宏 MICROPY_PORT_BUILTIN_MODULES 会被 objmodule.c 进行引用:

STATIC const mp_rom_map_elem_t mp_builtin_module_table[] = {
    { MP_ROM_QSTR(MP_QSTR___main__), MP_ROM_PTR(&mp_module___main__) },
    ......

    // extra builtin modules as defined by a port
    MICROPY_PORT_BUILTIN_MODULES

    #ifdef MICROPY_REGISTERED_MODULES
    // builtin modules declared with MP_REGISTER_MODULE()
    MICROPY_REGISTERED_MODULES
    #endif
};

​ 一般情况下, 通过如上步骤,即可完成一个自定义的module