docs: scrub upstream-derived reference/ and develop/ pages for OpenMV

Make upstream-MicroPython-derived documentation OpenMV-accurate, comparing each page against current upstream so nothing new is missing.

reference/: scrubbed asm_thumb2 (added ARM Thumb-2 Quick Reference Card PDF; replaced the CRC integer-restriction example with a hardware-free one since the debug protocol uses the CRC peripheral), filesystem, glossary (+ _glossary anchor), mpremote, manifest, repl, reset_boot, isr_rules, speed_python, constrained, mpyfiles, packages, micropython2_migration; pyb->machine, external->internal links, grammar/structure fixes; pyb.Flash cleanup; conf.py excludes the superseded pyboard.py.rst.

develop/ Internals: compared every page to upstream and merged missing upstream sections (memorymgt 'MicroPython Memory from C code'; cmodules 'C Dynamic Memory Allocation' / 'C++ Modules'); grammar/link/typo fixes; redirected actionable examples to the boards OpenMV users run (PYBV11->OPENMV4, ESP32->OpenMV Cam/rp2) while keeping comprehensive cross-platform reference matrices intact.

openmvcam/: OpenMV-branded the Boards/Shields/Sensors page titles without changing the sidebar captions.

.gitattributes: mark *.pdf binary.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kwagyeman

.gitattributes

@@ -13,6 +13,7 @@
 *.jpg binary
 *.dxf binary
 *.mpy binary
+*.pdf binary
 *.der binary
 *.mp4 binary
 *.webm binary

docs/conf.py

@@ -372,6 +372,7 @@ def _render_landing_code(src):
     "library/pyb.LCD.rst",
     "library/pyb.Switch.rst",
     "library/wipy.rst",
+    "reference/pyboard.py.rst",
     "mimxrt/general.rst",
     "mimxrt/pinout.rst",
     "mimxrt/tutorial/intro.rst",

docs/develop/cmodules.rst

@@ -8,8 +8,8 @@ limitations with the Python environment, often due to an inability to access
 certain hardware resources or Python speed limitations.
 
 If your limitations can't be resolved with suggestions in :ref:`speed_python`,
-writing some or all of your module in C (and/or C++ if implemented for your port)
-is a viable option.
+writing some or all of your module in C (and/or
+:ref:`C++ if implemented for your port<cxx_support>`) is a viable option.
 
 If your module is designed to access or work with commonly available
 hardware or libraries please consider implementing it inside the MicroPython
@@ -25,7 +25,7 @@ ports.  But when compiling a particular port you will only need to use one
 method of building, either Make or CMake.
 
 An alternative approach is to use :ref:`natmod` which allows writing custom C
-code that is placed in a .mpy file, which can be imported dynamically in to
+code that is placed in a .mpy file, which can be imported dynamically into
 a running MicroPython system without the need to recompile the main firmware.
 
 
@@ -45,7 +45,7 @@ A MicroPython user C module is a directory with the following files:
 * ``micropython.mk`` contains the Makefile fragment for this module.
 
   ``$(USERMOD_DIR)`` is available in ``micropython.mk`` as the path to your
-  module directory. As it's redefined for each c module, is should be expanded
+  module directory. As it's redefined for each C module, it should be expanded
   in your ``micropython.mk`` to a local make variable,
   eg ``EXAMPLE_MOD_DIR := $(USERMOD_DIR)``
 
@@ -140,7 +140,7 @@ For building the example modules which come with MicroPython,
 set ``USER_C_MODULES`` to the ``examples/usercmodule`` directory for Make,
 or to ``examples/usercmodule/micropython.cmake`` for CMake.
 
-For example, here's how the to build the unix port with the example modules:
+For example, here's how to build the unix port with the example modules:
 
 .. code-block:: bash
 
@@ -215,12 +215,10 @@ Then build with:
 
 .. code-block:: bash
 
-    cd my_project/micropython/ports/esp32
-    make USER_C_MODULES=../../../../modules/micropython.cmake
+    cd my_project/micropython/ports/rp2
+    make USER_C_MODULES=../../../modules/micropython.cmake
 
-Note that the esp32 port needs the extra ``..`` for relative paths due to the
-location of its main ``CMakeLists.txt`` file.   You can also specify absolute
-paths to ``USER_C_MODULES``.
+You can also specify absolute paths to ``USER_C_MODULES``.
 
 All modules specified by the ``USER_C_MODULES`` variable (either found in this
 directory when using Make, or added via ``include`` when using CMake) will be
@@ -285,3 +283,72 @@ can now be accessed in Python just like any other builtin module, e.g.
     sleep_ms(1000)
     print(watch.time())
     # should display approximately 1000
+
+
+.. _c_heap:
+
+C Dynamic Memory Allocation
+---------------------------
+
+MicroPython uses its own "Python heap" for `memorymanagement`,
+which is not the same as the "C heap" used by C library functions ``malloc()``,
+``free()``, etc. Not every MicroPython port comes with a "C heap" at all.
+
+Tier 1 & 2 ports have varying support for C dynamic memory allocation via a "C
+heap":
+
+- unix, windows, esp32 and webassembly ports support C dynamic memory
+  allocation.
+- rp2 port will fail to allocate any memory at runtime unless the firmware is
+  built with ``MICROPY_C_HEAP_SIZE=n`` to reserve ``n`` bytes of memory for a C
+  heap. This memory will not be available for Python code to use.
+- alif, mimxrt, nrf, renesas-ra, samd, and stm32 port builds that include
+  dynamic C allocation will fail at link-time with errors such as ``undefined
+  reference to `malloc'``. MicroPython has no built-in support for dynamic C
+  allocation on these ports. Any solution requires manually adding a C heap
+  implementation to the custom build.
+- zephyr port currently does not support building with user modules.
+
+Python heap as C heap
+~~~~~~~~~~~~~~~~~~~~~
+
+It may be practical for C code to call "Python heap" dynamic allocation
+functions such as ``m_malloc()``, ``m_malloc0()`` and ``m_free()`` instead.
+
+See `python_memory_from_c` for more information about this approach.
+
+.. _cxx_support:
+
+C++ Modules
+-----------
+
+Most Tier 1 & 2 MicroPython ports (and some Tier 3) support building C++ user
+modules, using the C++-specific environment variables described above.
+
+Integrating C++ and MicroPython successfully involves some additional
+considerations:
+
+C++ Dynamic Memory Allocation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+C++ programs (as well as C++ Standard Library features) typically use dynamic
+memory allocation. The C++ default memory allocator (i.e. operators ``new`` and
+``delete``) is typically implemented as a layer on top of `c_heap`.
+
+For MicroPython ports which don't include C dynamic memory allocation support,
+C++ dynamic memory allocation can be supported in one of two ways:
+
+- Implement C dynamic memory allocation in your custom build.
+- Implement a custom C++ allocator in your custom build.
+
+Linkage Considerations
+~~~~~~~~~~~~~~~~~~~~~~
+
+Because MicroPython is a C-based project, any symbols which link to or from
+MicroPython need to be qualified ``extern "C"`` in C++ code.
+
+It's strongly recommended to follow the pattern demonstrated in
+`examples/usercmodule/cppexample
+<https://github.com/micropython/micropython/blob/master/examples/usercmodule/cppexample>`_,
+where the Python module is implemented in a minimal C file wrapper around the
+C++ code.

docs/develop/compiler.rst

@@ -10,7 +10,7 @@ The compilation process in MicroPython involves the following steps:
 * Then bytecode or native code is emitted based on the parse tree.
 
 For purposes of this discussion we are going to add a simple language feature ``add1``
-that can be use in Python as:
+that can be used in Python as:
 
 .. code-block:: bash
 
@@ -44,7 +44,7 @@ in ``py/compile.c`` to turn this rule into executable code.
 The third required argument can be ``or`` or ``and``. This specifies the number of nodes associated
 with a statement. For example, in this case, our ``add1`` statement is similar to ADD1 in assembly
 language. It takes one numeric argument. Therefore, the ``add1_stmt`` has two nodes associated with it.
-One node is for the statement itself, i.e the literal ``add1`` corresponding to ``KW_ADD1``,
+One node is for the statement itself, i.e. the literal ``add1`` corresponding to ``KW_ADD1``,
 and the other for its argument, a ``testlist`` rule which is the top-level expression rule.
 
 .. note::
@@ -250,7 +250,7 @@ There is also support for *inline assembly code*, where assembly instructions ar
 written as Python function calls but are emitted directly as the corresponding
 machine code. This assembler has only three passes (scope, code size, emit)
 and uses a different implementation, not the ``compile_scope`` function.
-See the `inline assembler tutorial <https://docs.micropython.org/en/latest/pyboard/tutorial/assembler.html#pyboard-tutorial-assembler>`_
+See the :ref:`inline assembler reference <asm_thumb2_index>`
 for more details.
 
 Fourth pass

docs/develop/gettingstarted.rst

@@ -168,7 +168,9 @@ below but other unixes ought to work with little modification:
    gcc (Ubuntu 9.3.0-10ubuntu2) 9.3.0
    Copyright (C) 2019 Free Software Foundation, Inc.
    This is free software; see the source for copying conditions.  There is NO
-   warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.then build:
+   warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+then build:
 
 .. code-block:: bash
 
@@ -232,7 +234,7 @@ You can also specify which board to use:
    $ make BOARD=<board>
 
 See `ports/stm32/boards <https://github.com/micropython/micropython/tree/master/ports/stm32/boards>`_
-for the available boards. e.g. "PYBV11" or "NUCLEO_WB55".
+for the available boards. e.g. "OPENMV4" or "OPENMV4P".
 
 Building the documentation
 --------------------------
@@ -399,7 +401,7 @@ tests
 tools
 
   Contains scripts used by the build and CI process, as well as user tools such
-  as ``pyboard.py`` and ``mpremote``.
+  as ``mpremote``.
 
 examples
 

docs/develop/index.rst

@@ -6,7 +6,7 @@ to MicroPython. It acts as a comprehensive resource on the implementation detail
 for both novice and expert contributors.
 
 Development around MicroPython usually involves modifying the core runtime, porting or
-maintaining a new library. This guide describes at great depth, the implementation
+maintaining a new library. This guide describes in great depth the implementation
 details of MicroPython including a getting started guide, compiler internals, porting
 MicroPython to a new platform and implementing a core MicroPython library.
 

docs/develop/library.rst

@@ -6,7 +6,7 @@ Implementing a Module
 This chapter details how to implement a core module in MicroPython.
 MicroPython modules can be one of the following:
 
-- Built-in module: A general module that is be part of the MicroPython repository.
+- Built-in module: A general module that is part of the MicroPython repository.
 - User module: A module that is useful for your specific project that you maintain
   in your own repository or private codebase.
 - Dynamic module: A module that can be deployed and imported at runtime to your device.
@@ -26,15 +26,15 @@ Implementing a core module
 --------------------------
 
 Like CPython, MicroPython has core builtin modules that can be accessed through import statements.
-An example is the ``gc`` module discussed in :ref:`memorymanagement`.
+An example is the :mod:`gc` module discussed in :ref:`memorymanagement`.
 
 .. code-block:: bash
 
    >>> import gc
    >>> gc.enable()
    >>>
 
-MicroPython has several other builtin standard/core modules like ``io``, ``array`` etc.
+MicroPython has several other builtin standard/core modules like :mod:`io`, :mod:`array`, etc.
 Adding a new core module involves several modifications.
 
 First, create the ``C`` file in the ``py/`` directory. In this example we are adding a

docs/develop/maps.rst

@@ -30,10 +30,10 @@ placing the item in the next free slot which is slot ``4`` in our example:
 
 .. image:: img/linprob.png
 
-The same methods i.e open addressing and linear probing are used to search for an item in a dictionary.
+The same methods, i.e. open addressing and linear probing, are used to search for an item in a dictionary.
 Assume we want to search for the data item ``33``. The computed hash value will be 2. Looking at slot 2
-reveals ``33``, at this point, we return ``True``. Searching for ``70`` is quite different as there was a
-collision at the time of insertion. Therefore computing the hash value is ``0`` which is currently
+reveals ``33``. At this point, we return ``True``. Searching for ``70`` is quite different as there was a
+collision at the time of insertion. Therefore the computed hash value is ``0``, which is currently
 holding ``44``. Instead of simply returning ``False``, we perform a sequential search starting at point
 ``1`` until the item ``70`` is found or we encounter a free slot. This is the general way of performing
 look-ups in hashes:

docs/develop/memorymgt.rst

@@ -21,7 +21,7 @@ There are many GC algorithms but MicroPython uses the
 policy for managing memory. This algorithm has a mark phase that traverses the heap marking all
 live objects while the sweep phase goes through the heap reclaiming all unmarked objects.
 
-Garbage collection functionality in MicroPython is available through the ``gc`` built-in
+Garbage collection functionality in MicroPython is available through the :mod:`gc` built-in
 module:
 
 .. code-block:: bash
@@ -42,12 +42,73 @@ module:
 
 Even when ``gc.disable()`` is invoked, collection can be triggered with ``gc.collect()``.
 
+.. _python_memory_from_c:
+
+MicroPython Memory from C code
+------------------------------
+
+Awareness of the garbage collector is needed when writing C code that allocates
+memory from the "Python heap" (i.e. functions ``m_malloc()``, ``m_malloc0()``,
+``m_free()``, etc).
+
+The mark phase of the garbage collector scans for live pointers to heap memory
+starting from the following roots:
+
+- The stack of the main Python runtime (or REPL).
+- The stacks of each "Python thread", for ports which implement Python threads
+  on top of native operating system threads or tasks.
+- The "root pointers" defined in C code using the macro
+  ``MP_REGISTER_ROOT_POINTER``. These are the recommended way to have statically
+  scoped pointers to the Python heap.
+- Tracked allocations made with the ``m_tracked_calloc()``, ``m_tracked_realloc``
+  and ``m_tracked_free()`` functions. These special functions allow allocating a
+  block of memory which is always considered live by the garbage collector.
+  Similar to memory allocation in C, this memory is only freed by calling
+  ``m_tracked_free()`` or by soft reset. There is a small memory usage and
+  runtime overhead to each tracked allocation. This feature is not enabled by
+  default on all ports.
+
+The garbage collector then recursively scans and marks all the memory pointed to
+by the root pointers, until all addresses are exhausted. This is sufficient to
+find all Python objects that are still in use by the MicroPython runtime.
+
+However, the following memory will **not** be scanned by the garbage collector
+and could be freed prematurely:
+
+- Static or global C variables which contain pointers to heap memory.
+- Pointers which don't point to the "head" of an allocated buffer (i.e. to the
+  exact address returned by ``m_malloc()``), but instead to an address inside
+  the allocated buffer (for example, a pointer to a nested struct). For
+  performance reasons, the garbage collector doesn't mark the enclosing buffer
+  in these cases.
+- The stack of any thread or RTOS task which isn't running Python code or
+  manually registered as a "Python thread" (for ports which support native
+  threads or tasks).
+
+Ways to avoid use-after-free in these scenarios:
+
+- Use the tracked allocation API ``m_tracked_calloc()``, ``m_tracked_realloc()``
+  and ``m_tracked_free()``.
+- Register a root pointer (see above), instead of storing a pointer in a static
+  variable.
+- Restructure the code, for example by having an API where Python code
+  initialises a singleton Python object (implemented in C) which holds all of the
+  relevant pointers instead of having them in static variables.
+
+.. note:: :ref:`soft_reset` always clears the Python heap and frees all memory.
+          It's important not to hold any pointers to the heap after a soft
+          reset, as they will become dangling pointers to freed memory.
+
+          Some ports support a "C heap" as well (see `c_heap`), in which case
+          you can allocate memory that will stay valid over soft reset by
+          calling standard C functions ``malloc``, etc.
+
 The object model
 ----------------
 
 All MicroPython objects are referred to by the ``mp_obj_t`` data type.
 This is usually word-sized (i.e. the same size as a pointer on the target architecture),
-and can be typically 32-bit (STM32, nRF, ESP32, Unix x86) or 64-bit (Unix x64).
+and can be typically 32-bit (STM32, RP2, nRF, Unix x86) or 64-bit (Unix x64).
 It can also be greater than a word-size for certain object representations, for
 example ``OBJ_REPR_D`` has a 64-bit sized ``mp_obj_t`` on a 32-bit architecture.
 

docs/develop/natmod.rst

@@ -21,7 +21,7 @@ language which can be compiled to stand-alone machine code can be put into a
 
 A native .mpy module is built using the ``mpy_ld.py`` tool, which is found in the
 ``tools/`` directory of the project.  This tool takes a set of object files
-(.o files) and links them together to create a native .mpy files.  It requires
+(.o files) and links them together to create a native .mpy file.  It requires
 CPython 3 and the library pyelftools v0.25 or greater.
 
 Supported features and limitations
@@ -53,7 +53,7 @@ architecture flags are present, only if they match the target's capabilities).
 For more details about .mpy files see :ref:`mpy_files`.
 
 Native code must be compiled as position independent code (PIC) and use a global
-offset table (GOT), although the details of this varies from architecture to
+offset table (GOT), although the details of this vary from architecture to
 architecture.  When importing .mpy files with native code the import machinery
 is able to do some basic relocation of the native code.  This includes
 relocating text, rodata and BSS sections.
@@ -124,7 +124,7 @@ The filesystem layout consists of two main parts, the source files and the Makef
   both C source files as well as any Python files which will be included in the
   resulting .mpy file.
 
-* The ``Makefile`` contains the build configuration for the module and list the
+* The ``Makefile`` contains the build configuration for the module and lists the
   source files used to build the .mpy module.  It should define ``MPY_DIR`` as the
   location of the MicroPython repository (to find header files, the relevant Makefile
   fragment, and the ``mpy_ld.py`` tool), ``MOD`` as the name of the module, ``SRC``