micropython/examples/natmod
Jim Mussared 607548f32d examples/natmod: Add features4 as a class definition example.
Also provide a basic README.md for dynamic native modules.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-09-02 00:16:16 +10:00
..
btree examples: Mark asm, pio, etc. as noqa: F821 (undefined-name). 2023-08-16 16:12:33 +10:00
deflate examples/natmod/deflate: Add deflate as a dynamic native module. 2023-07-21 19:32:42 +10:00
features0 examples/natmod: Add very simple features0 example to compute factorial. 2019-12-19 17:06:27 +11:00
features1 all: Fix spelling mistakes based on codespell check. 2023-04-27 18:03:06 +10:00
features2 examples: Mark asm, pio, etc. as noqa: F821 (undefined-name). 2023-08-16 16:12:33 +10:00
features3 examples/natmod/features3: Add example to test more natmod features. 2022-06-10 16:42:43 +10:00
features4 examples/natmod: Add features4 as a class definition example. 2023-09-02 00:16:16 +10:00
framebuf py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
heapq examples/natmod: Rename umodule to module. 2023-06-08 17:54:24 +10:00
random examples/natmod: Rename umodule to module. 2023-06-08 17:54:24 +10:00
re examples/natmod: Rename umodule to module. 2023-06-08 17:54:24 +10:00
.gitignore examples/natmod: Add .gitignore to ignore generated example .mpy files. 2020-03-03 12:54:17 +11:00
README.md examples/natmod: Add features4 as a class definition example. 2023-09-02 00:16:16 +10:00

README.md

Dynamic Native Modules

Dynamic Native Modules are .mpy files that contain native machine code from a language other than Python. For more info see [the documentation] (https://docs.micropython.org/en/latest/develop/natmod.html).

This should not be confused with [User C Modules] (https://docs.micropython.org/en/latest/develop/cmodules.html) which are a mechanism to add additional out-of-tree modules into the firmware build.

Examples

This directory contains several examples of writing dynamic native modules, in two main categories:

  1. Feature examples.

    • features0 - A module containing a single "factorial" function which demonstrates working with integers.

    • features1 - A module that demonstrates some common tasks:

      • defining simple functions exposed to Python
      • defining local, helper C functions
      • defining constant integers and strings exposed to Python
      • getting and creating integer objects
      • creating Python lists
      • raising exceptions
      • allocating memory
      • BSS and constant data (rodata)
      • relocated pointers in rodata
    • features2 - This is a hybrid module containing both Python and C code, and additionally the C code is spread over multiple files. It also demonstrates using floating point (only when the target supports hardware floating point).

    • features3 - A module that shows how to use types, constant objects, and creating dictionary instances.

    • features4 - A module that demonstrates how to define a class.

  2. Dynamic version of existing built-ins.

    This provides a way to add missing functionality to firmware that doesn't include certain built-in modules. See the heapq, random, re, deflate, btree, and framebuf directories.

    So for example, if your firmware was compiled with MICROPY_PY_FRAMEBUF disabled (e.g. to save flash space), then it would not include the framebuf module. The framebuf native module provides a way to add the framebuf module dynamically.

    The way these work is they define a dynamic native module which #include's the original module and then does the necessary initialisation of the module's globals dict.

Build instructions

To compile an example, you need to have the same toolchain available as required for your target port. e.g. arm-none-eabi-gcc for any ARM Cortex M target. See the port instructions for details.

You also need to have the pyelftools Python package available, either via your system package manager or installed from PyPI in a virtual environment with pip.

Each example provides a Makefile. You should specify the ARCH argument to make (one of x86, x64, armv6m, armv7m, xtensa, xtensawin):

$ cd features0
$ make ARCH=armv7m
$ mpremote cp features0.mpy :