Merge pull request #8508 from dhalbert/v1.21-merge

V1.21 merge

Author: tannewt

.git-blame-ignore-revs

@@ -1,3 +1,9 @@
+# all: Fix various spelling mistakes found by codespell 2.2.6.
+cf490a70917a1b2d38ba9b58e763e0837d0f7ca7
+
+# all: Fix spelling mistakes based on codespell check.
+b1229efbd1509654dec6053865ab828d769e29db
+
 # top: Update Python formatting to black "2023 stable style".
 8b2748269244304854b3462cb8902952b4dcb892
 

.github/workflows/run-tests.yml

@@ -57,11 +57,10 @@ jobs:
       run: |
         make -C examples/natmod/features1
         make -C examples/natmod/features2
-        make -C examples/natmod/uheapq
-        make -C examples/natmod/urandom
-        make -C examples/natmod/ure
-        make -C examples/natmod/uzlib
+        make -C examples/natmod/heapq
+        make -C examples/natmod/random
+        make -C examples/natmod/re
     - name: Test native modules
       if: matrix.test == 'all'
-      run: ./run-natmodtests.py extmod/{uheapq*,ure*,uzlib*}.py
+      run: ./run-natmodtests.py extmod/{heapq*,re*,zlib*}.py
       working-directory: tests

docs/library/gc.rst

@@ -24,7 +24,7 @@ Functions
 
 .. function:: mem_alloc()
 
-   Return the number of bytes of heap RAM that are allocated.
+   Return the number of bytes of heap RAM that are allocated by Python code.
 
    .. admonition:: Difference to CPython
       :class: attention
@@ -33,8 +33,8 @@ Functions
 
 .. function:: mem_free()
 
-   Return the number of bytes of available heap RAM, or -1 if this amount
-   is not known.
+   Return the number of bytes of heap RAM that is available for Python
+   code to allocate, or -1 if this amount is not known.
 
    .. admonition:: Difference to CPython
       :class: attention

docs/library/index.rst

@@ -17,7 +17,7 @@ limited flash memory:
 ``binascii``, ``errno``, ``json``, ``re``.
 
 These libraries are not currently enabled in any CircuitPython build, but may be in the future:
-``ctypes``
+``ctypes``, ``platform``
 
 .. toctree::
    :maxdepth: 1
@@ -31,6 +31,7 @@ These libraries are not currently enabled in any CircuitPython build, but may be
    gc.rst
    io.rst
    json.rst
+   platform.rst
    re.rst
    sys.rst
    ctypes.rst

docs/library/platform.rst

@@ -0,0 +1,38 @@
+:mod:`platform` -- access to underlying platform’s identifying data
+===================================================================
+
+.. module:: platform
+   :synopsis: access to underlying platform’s identifying data
+
+|see_cpython_module| :mod:`python:platform`.
+
+This module tries to retrieve as much platform-identifying data as possible. It
+makes this information available via function APIs.
+
+Functions
+---------
+
+.. function:: platform()
+
+   Returns a string identifying the underlying platform. This string is composed
+   of several substrings in the following order, delimited by dashes (``-``):
+
+   - the name of the platform system (e.g. Unix, Windows or MicroPython)
+   - the MicroPython version
+   - the architecture of the platform
+   - the version of the underlying platform
+   - the concatenation of the name of the libc that MicroPython is linked to
+     and its corresponding version.
+
+   For example, this could be
+   ``"MicroPython-1.20.0-xtensa-IDFv4.2.4-with-newlib3.0.0"``.
+
+.. function:: python_compiler()
+
+   Returns a string identifying the compiler used for compiling MicroPython.
+
+.. function:: libc_ver()
+
+   Returns a tuple of strings *(lib, version)*, where *lib* is the name of the
+   libc that MicroPython is linked to, and *version* the corresponding version
+   of this libc.

docs/library/sys.rst

@@ -33,6 +33,7 @@ Constants
 
    * *name* - string "circuitpython"
    * *version* - tuple (major, minor, micro), e.g. (1, 7, 0)
+   * *_machine* - string describing the underlying machine
    * *_mpy* - supported mpy file-format version (optional attribute)
 
    This object is the recommended way to distinguish CircuitPython from other

docs/reference/glossary.rst

@@ -32,7 +32,7 @@ Glossary
 
     callee-owned tuple
         This is a MicroPython-specific construct where, for efficiency
-        reasons, some built-in functions or methods may re-use the same
+        reasons, some built-in functions or methods may reuse the same
         underlying tuple object to return data. This avoids having to allocate
         a new tuple for every call, and reduces heap fragmentation. Programs
         should not hold references to callee-owned tuples and instead only
@@ -120,7 +120,7 @@ Glossary
         <https://github.com/micropython/micropython-lib>`_ which provides
         implementations for many modules from CPython's standard library.
 
-        Some of the modules are are implemented in pure Python, and are able to
+        Some of the modules are implemented in pure Python, and are able to
         be used on all ports. However, the majority of these modules use
         :term:`FFI` to access operating system functionality, and as such can
         only be used on the :term:`MicroPython Unix port` (with limited support

docs/shared_bindings_matrix.py

@@ -63,7 +63,7 @@
 }
 
 ADDITIONAL_MODULES = {
-    "_asyncio": "MICROPY_PY_UASYNCIO",
+    "_asyncio": "MICROPY_PY_ASYNCIO",
     "adafruit_bus_device": "CIRCUITPY_BUSDEVICE",
     "adafruit_pixelbuf": "CIRCUITPY_PIXELBUF",
     "array": "CIRCUITPY_ARRAY",
@@ -79,7 +79,7 @@
     "keypad.Keys": "CIRCUITPY_KEYPAD_KEYS",
     "keypad.ShiftRegisterKeys": "CIRCUITPY_KEYPAD_SHIFTREGISTERKEYS",
     "os.getenv": "CIRCUITPY_OS_GETENV",
-    "select": "MICROPY_PY_USELECT_SELECT",
+    "select": "MICROPY_PY_SELECT_SELECT",
     "sys": "CIRCUITPY_SYS",
     "terminalio": "CIRCUITPY_DISPLAYIO",
     "usb": "CIRCUITPY_USB_HOST",

examples/natmod/README.md

@@ -0,0 +1,74 @@
+# 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 :
+```

examples/natmod/uzlib/Makefile renamed to examples/natmod/deflate/Makefile

@@ -2,10 +2,10 @@
 MPY_DIR = ../../..
 
 # Name of module (different to built-in uzlib so it can coexist)
-MOD = uzlib_$(ARCH)
+MOD = deflate_$(ARCH)
 
 # Source files (.c or .py)
-SRC = uzlib.c
+SRC = deflate.c
 
 # Architecture to build for (x86, x64, armv7m, xtensa, xtensawin)
 ARCH = x64

examples/natmod/deflate/deflate.c

@@ -0,0 +1,70 @@
+#define MICROPY_PY_DEFLATE (1)
+#define MICROPY_PY_DEFLATE_COMPRESS (1)
+
+#include "py/dynruntime.h"
+
+#if !defined(__linux__)
+void *memcpy(void *dst, const void *src, size_t n) {
+    return mp_fun_table.memmove_(dst, src, n);
+}
+void *memset(void *s, int c, size_t n) {
+    return mp_fun_table.memset_(s, c, n);
+}
+#endif
+
+mp_obj_full_type_t deflateio_type;
+
+#include "extmod/moddeflate.c"
+
+// Re-implemented from py/stream.c, not yet available in dynruntime.h.
+mp_obj_t mp_stream_close(mp_obj_t stream) {
+    const mp_stream_p_t *stream_p = mp_get_stream(stream);
+    int error;
+    mp_uint_t res = stream_p->ioctl(stream, MP_STREAM_CLOSE, 0, &error);
+    if (res == MP_STREAM_ERROR) {
+        mp_raise_OSError(error);
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(mp_stream_close_obj, mp_stream_close);
+
+// Re-implemented from py/stream.c, not yet available in dynruntime.h.
+STATIC mp_obj_t mp_stream___exit__(size_t n_args, const mp_obj_t *args) {
+    (void)n_args;
+    return mp_stream_close(args[0]);
+}
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_stream___exit___obj, 4, 4, mp_stream___exit__);
+
+// Re-implemented from obj.c, not yet available in dynruntime.h.
+mp_obj_t mp_identity(mp_obj_t self) {
+    return self;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(mp_identity_obj, mp_identity);
+
+mp_map_elem_t deflateio_locals_dict_table[7];
+STATIC MP_DEFINE_CONST_DICT(deflateio_locals_dict, deflateio_locals_dict_table);
+
+mp_obj_t mpy_init(mp_obj_fun_bc_t *self, size_t n_args, size_t n_kw, mp_obj_t *args) {
+    MP_DYNRUNTIME_INIT_ENTRY
+
+    deflateio_type.base.type = mp_fun_table.type_type;
+    deflateio_type.name = MP_QSTR_DeflateIO;
+    MP_OBJ_TYPE_SET_SLOT(&deflateio_type, make_new, &deflateio_make_new, 0);
+    MP_OBJ_TYPE_SET_SLOT(&deflateio_type, protocol, &deflateio_stream_p, 1);
+    deflateio_locals_dict_table[0] = (mp_map_elem_t){ MP_OBJ_NEW_QSTR(MP_QSTR_read), MP_OBJ_FROM_PTR(&mp_stream_read_obj) };
+    deflateio_locals_dict_table[1] = (mp_map_elem_t){ MP_OBJ_NEW_QSTR(MP_QSTR_readinto), MP_OBJ_FROM_PTR(&mp_stream_readinto_obj) };
+    deflateio_locals_dict_table[2] = (mp_map_elem_t){ MP_OBJ_NEW_QSTR(MP_QSTR_readline), MP_OBJ_FROM_PTR(&mp_stream_unbuffered_readline_obj) };
+    deflateio_locals_dict_table[3] = (mp_map_elem_t){ MP_OBJ_NEW_QSTR(MP_QSTR_write), MP_OBJ_FROM_PTR(&mp_stream_write_obj) };
+    deflateio_locals_dict_table[4] = (mp_map_elem_t){ MP_OBJ_NEW_QSTR(MP_QSTR_close), MP_OBJ_FROM_PTR(&mp_stream_close_obj) };
+    deflateio_locals_dict_table[5] = (mp_map_elem_t){ MP_OBJ_NEW_QSTR(MP_QSTR___enter__), MP_OBJ_FROM_PTR(&mp_identity_obj) };
+    deflateio_locals_dict_table[6] = (mp_map_elem_t){ MP_OBJ_NEW_QSTR(MP_QSTR___exit__), MP_OBJ_FROM_PTR(&mp_stream___exit___obj) };
+    MP_OBJ_TYPE_SET_SLOT(&deflateio_type, locals_dict, (void*)&deflateio_locals_dict, 2);
+
+    mp_store_global(MP_QSTR___name__, MP_OBJ_NEW_QSTR(MP_QSTR_deflate));
+    mp_store_global(MP_QSTR_DeflateIO, MP_OBJ_FROM_PTR(&deflateio_type));
+    mp_store_global(MP_QSTR_RAW, MP_OBJ_NEW_SMALL_INT(DEFLATEIO_FORMAT_RAW));
+    mp_store_global(MP_QSTR_ZLIB, MP_OBJ_NEW_SMALL_INT(DEFLATEIO_FORMAT_ZLIB));
+    mp_store_global(MP_QSTR_GZIP, MP_OBJ_NEW_SMALL_INT(DEFLATEIO_FORMAT_GZIP));
+
+    MP_DYNRUNTIME_INIT_EXIT
+}

examples/natmod/features1/features1.c

@@ -88,7 +88,7 @@ mp_obj_t mpy_init(mp_obj_fun_bc_t *self, size_t n_args, size_t n_kw, mp_obj_t *a
     // This must be first, it sets up the globals dict and other things
     MP_DYNRUNTIME_INIT_ENTRY
 
-    // Messages can be printed as usually
+    // Messages can be printed as usual
     mp_printf(&mp_plat_print, "initialising module self=%p\n", self);
 
     // Make the functions available in the module's namespace

examples/natmod/features2/test.py

@@ -1,5 +1,7 @@
 # This Python code will be merged with the C code in main.c
 
+# ruff: noqa: F821 - this file is evaluated with C-defined names in scope
+
 import array
 
 

examples/natmod/features4/Makefile

@@ -0,0 +1,14 @@
+# Location of top-level MicroPython directory
+MPY_DIR = ../../..
+
+# Name of module
+MOD = features4
+
+# Source files (.c or .py)
+SRC = features4.c
+
+# Architecture to build for (x86, x64, armv7m, xtensa, xtensawin)
+ARCH = x64
+
+# Include to get the rules for compiling and linking the module
+include $(MPY_DIR)/py/dynruntime.mk