|
| 1 | +# Dynamic Native Modules |
| 2 | + |
| 3 | +Dynamic Native Modules are .mpy files that contain native machine code from a |
| 4 | +language other than Python. For more info see [the documentation] |
| 5 | +(https://docs.micropython.org/en/latest/develop/natmod.html). |
| 6 | + |
| 7 | +This should not be confused with [User C Modules] |
| 8 | +(https://docs.micropython.org/en/latest/develop/cmodules.html) which are a |
| 9 | +mechanism to add additional out-of-tree modules into the firmware build. |
| 10 | + |
| 11 | +## Examples |
| 12 | + |
| 13 | +This directory contains several examples of writing dynamic native modules, in |
| 14 | +two main categories: |
| 15 | + |
| 16 | +1. Feature examples. |
| 17 | + |
| 18 | + * `features0` - A module containing a single "factorial" function which |
| 19 | + demonstrates working with integers. |
| 20 | + |
| 21 | + * `features1` - A module that demonstrates some common tasks: |
| 22 | + - defining simple functions exposed to Python |
| 23 | + - defining local, helper C functions |
| 24 | + - defining constant integers and strings exposed to Python |
| 25 | + - getting and creating integer objects |
| 26 | + - creating Python lists |
| 27 | + - raising exceptions |
| 28 | + - allocating memory |
| 29 | + - BSS and constant data (rodata) |
| 30 | + - relocated pointers in rodata |
| 31 | + |
| 32 | + * `features2` - This is a hybrid module containing both Python and C code, |
| 33 | + and additionally the C code is spread over multiple files. It also |
| 34 | + demonstrates using floating point (only when the target supports |
| 35 | + hardware floating point). |
| 36 | + |
| 37 | + * `features3` - A module that shows how to use types, constant objects, |
| 38 | + and creating dictionary instances. |
| 39 | + |
| 40 | + * `features4` - A module that demonstrates how to define a class. |
| 41 | + |
| 42 | +2. Dynamic version of existing built-ins. |
| 43 | + |
| 44 | + This provides a way to add missing functionality to firmware that doesn't |
| 45 | + include certain built-in modules. See the `heapq`, `random`, `re`, |
| 46 | + `deflate`, `btree`, and `framebuf` directories. |
| 47 | + |
| 48 | + So for example, if your firmware was compiled with `MICROPY_PY_FRAMEBUF` |
| 49 | + disabled (e.g. to save flash space), then it would not include the |
| 50 | + `framebuf` module. The `framebuf` native module provides a way to add the |
| 51 | + `framebuf` module dynamically. |
| 52 | + |
| 53 | + The way these work is they define a dynamic native module which |
| 54 | + `#include`'s the original module and then does the necessary |
| 55 | + initialisation of the module's globals dict. |
| 56 | + |
| 57 | +## Build instructions |
| 58 | + |
| 59 | +To compile an example, you need to have the same toolchain available as |
| 60 | +required for your target port. e.g. `arm-none-eabi-gcc` for any ARM Cortex M |
| 61 | +target. See the port instructions for details. |
| 62 | + |
| 63 | +You also need to have the `pyelftools` Python package available, either via |
| 64 | +your system package manager or installed from PyPI in a virtual environment |
| 65 | +with `pip`. |
| 66 | + |
| 67 | +Each example provides a Makefile. You should specify the `ARCH` argument to |
| 68 | +make (one of x86, x64, armv6m, armv7m, xtensa, xtensawin): |
| 69 | + |
| 70 | +``` |
| 71 | +$ cd features0 |
| 72 | +$ make ARCH=armv7m |
| 73 | +$ mpremote cp features0.mpy : |
| 74 | +``` |
0 commit comments