Merge branch 'main' into ports/analog/add-busio

Author: Brandon-Hurst

.codespell/ignore-words.txt

@@ -26,3 +26,4 @@ ftbfs
 straightaway
 ftbs
 ftb
+curren

.gitignore

@@ -39,10 +39,12 @@ bin/
 circuitpython-stubs/
 test-stubs/
 build-*/
+docs/genrst/
 
-# Test failure outputs
+# Test failure outputs and intermediate artifacts
 ######################
 tests/results/*
+tests/ports/unix/ffi_lib.so
 
 # Python cache files
 ######################
@@ -76,6 +78,7 @@ TAGS
 ####################
 *~
 
+# MacOS desktop metadata files
 *.DS_Store
 **/*.DS_Store
 *.icloud
@@ -100,6 +103,7 @@ TAGS
 .cache
 
 **/CLAUDE.local.md
+.claude
 
 # windsurf rules
 .windsurfrules

.gitmodules

@@ -7,7 +7,7 @@
 	url = https://github.com/micropython/axtls.git
 [submodule "lib/libffi"]
 	path = lib/libffi
-	url = https://github.com/atgreen/libffi
+	url = https://github.com/libffi/libffi
 [submodule "lib/berkeley-db-1.xx"]
 	path = lib/berkeley-db-1.xx
 	url = https://github.com/micropython/berkeley-db-1.xx

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013-2023 Damien P. George
+Copyright (c) 2013-2025 Damien P. George
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -22,8 +22,6 @@ THE SOFTWARE.
 
 --------------------------------------------------------------------------------
 
-# CIRCUITPY-CHANGE:
-
 Unless specified otherwise (see below), the above license and copyright applies
 to all files derived from MicroPython in this repository.
 

Makefile

@@ -156,28 +156,22 @@ epub:
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex:
-	$(PYTHON) docs/prepare_readme_for_latex.py
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	mv README.rst.bak README.rst
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 # seems to be malfunctioning
 latexpdf:
-	$(PYTHON) docs/prepare_readme_for_latex.py
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	mv README.rst.bak README.rst
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 # seems to be malfunctioning
 latexpdfja:
-	$(PYTHON) docs/prepare_readme_for_latex.py
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	mv README.rst.bak README.rst
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
@@ -277,20 +271,20 @@ check-translate:
 
 .PHONY: stubs
 stubs:
-	@rm -rf circuitpython-stubs
-	@mkdir circuitpython-stubs
-	@$(PYTHON) tools/extract_pyi.py shared-bindings/ $(STUBDIR)
-	@$(PYTHON) tools/extract_pyi.py extmod/ulab/code/ $(STUBDIR)/ulab
-	@for d in ports/*/bindings; do \
+	rm -rf circuitpython-stubs
+	mkdir circuitpython-stubs
+	$(PYTHON) tools/extract_pyi.py shared-bindings/ $(STUBDIR)
+	$(PYTHON) tools/extract_pyi.py extmod/ulab/code/ $(STUBDIR)/ulab
+	for d in ports/*/bindings; do \
 	    $(PYTHON) tools/extract_pyi.py "$$d" $(STUBDIR); done
-	@sed -e "s,__version__,`python -msetuptools_scm`," < setup.py-stubs > circuitpython-stubs/setup.py
-	@cp README.rst-stubs circuitpython-stubs/README.rst
-	@cp MANIFEST.in-stubs circuitpython-stubs/MANIFEST.in
-	@$(PYTHON) tools/board_stubs/build_board_specific_stubs/board_stub_builder.py
-	@cp -r tools/board_stubs/circuitpython_setboard circuitpython-stubs/circuitpython_setboard
-	@$(PYTHON) -m build circuitpython-stubs
-	@touch circuitpython-stubs/board/__init__.py
-	@touch circuitpython-stubs/board_definitions/__init__.py
+	sed -e "s,__version__,`python -msetuptools_scm`," < setup.py-stubs > circuitpython-stubs/setup.py
+	cp README.rst-stubs circuitpython-stubs/README.rst
+	cp MANIFEST.in-stubs circuitpython-stubs/MANIFEST.in
+	$(PYTHON) tools/board_stubs/build_board_specific_stubs/board_stub_builder.py
+	cp -r tools/board_stubs/circuitpython_setboard circuitpython-stubs/circuitpython_setboard
+	$(PYTHON) -m build circuitpython-stubs
+	touch circuitpython-stubs/board/__init__.py
+	touch circuitpython-stubs/board_definitions/__init__.py
 
 .PHONY: check-stubs
 check-stubs: stubs

docs/library/array.rst

@@ -19,6 +19,10 @@ Classes
     array are given by an `iterable`. If it is not provided, an empty
     array is created.
 
+    In addition to the methods below, array objects also implement the buffer
+    protocol. This means the contents of the entire array can be accessed as raw
+    bytes via a `memoryview` or other interfaces which use this protocol.
+
     .. method:: append(val)
 
         Append new element ``val`` to the end of array, growing it.

docs/library/binascii.rst

@@ -39,6 +39,6 @@ Functions
 
 .. function:: crc32(data, value=0, /)
 
-   Compute CRC-32, the 32-bit checksum of the bytes in *data* starting with an
+   Compute CRC-32, the 32-bit checksum of the bytes in ``data`` starting with an
    initial CRC of *value*. The default initial CRC is 0. The algorithm is
    consistent with the ZIP file checksum.

docs/library/builtins.rst

@@ -31,6 +31,8 @@ Functions and types
 
 .. class:: bytearray()
 
+    |see_cpython| `python:bytearray`.
+
 .. class:: bytes()
 
     |see_cpython| `python:bytes`.
@@ -86,15 +88,9 @@ Functions and types
 
 .. class:: int()
 
-   .. classmethod:: from_bytes(bytes, byteorder)
-
-      In CircuitPython, the ``byteorder`` parameter must be positional (this is
-      compatible with CPython).
-
-   .. method:: to_bytes(size, byteorder)
+   .. classmethod:: from_bytes(bytes, byteorder="big", *, signed=False)
 
-      In CircuitPython, the ``byteorder`` parameter must be positional (this is
-      compatible with CPython).
+   .. method:: to_bytes(length=1, byteorder="big", *, signed=False)
 
 .. function:: isinstance()
 

docs/library/index.rst

@@ -33,8 +33,8 @@ These libraries are not currently enabled in any CircuitPython build, but may be
    json.rst
    platform.rst
    re.rst
-   sys.rst
    select.rst
+   sys.rst
 
 Omitted ``string`` functions
 ----------------------------

docs/library/micropython.rst

@@ -1,5 +1,5 @@
-:mod:`micropython` -- MicroPython extensions and internals
-==========================================================
+:mod:`micropython` -- access and control MicroPython internals
+==============================================================
 
 .. module:: micropython
    :synopsis: access and control MicroPython internals
@@ -26,3 +26,132 @@ Functions
    provided as part of the :mod:`micropython` module mainly so that scripts can be
    written which run under both CPython and MicroPython, by following the above
    pattern.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: opt_level([level])
+
+   If *level* is given then this function sets the optimisation level for subsequent
+   compilation of scripts, and returns ``None``.  Otherwise it returns the current
+   optimisation level.
+
+   The optimisation level controls the following compilation features:
+
+   - Assertions: at level 0 assertion statements are enabled and compiled into the
+     bytecode; at levels 1 and higher assertions are not compiled.
+   - Built-in ``__debug__`` variable: at level 0 this variable expands to ``True``;
+     at levels 1 and higher it expands to ``False``.
+   - Source-code line numbers: at levels 0, 1 and 2 source-code line number are
+     stored along with the bytecode so that exceptions can report the line number
+     they occurred at; at levels 3 and higher line numbers are not stored.
+
+   The default optimisation level is usually level 0.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: alloc_emergency_exception_buf(size)
+
+   Allocate *size* bytes of RAM for the emergency exception buffer (a good
+   size is around 100 bytes).  The buffer is used to create exceptions in cases
+   when normal RAM allocation would fail (eg within an interrupt handler) and
+   therefore give useful traceback information in these situations.
+
+   A good way to use this function is to put it at the start of your main script
+   (eg ``boot.py`` or ``main.py``) and then the emergency exception buffer will be active
+   for all the code following it.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: mem_info([verbose])
+
+   Print information about currently used memory.  If the *verbose* argument
+   is given then extra information is printed.
+
+   The information that is printed is implementation dependent, but currently
+   includes the amount of stack and heap used.  In verbose mode it prints out
+   the entire heap indicating which blocks are used and which are free.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: qstr_info([verbose])
+
+   Print information about currently interned strings.  If the *verbose*
+   argument is given then extra information is printed.
+
+   The information that is printed is implementation dependent, but currently
+   includes the number of interned strings and the amount of RAM they use.  In
+   verbose mode it prints out the names of all RAM-interned strings.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: stack_use()
+
+   Return an integer representing the current amount of stack that is being
+   used.  The absolute value of this is not particularly useful, rather it
+   should be used to compute differences in stack usage at different points.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: heap_lock()
+.. CIRCUITPY-CHANGE: REMOVE .. function:: heap_unlock()
+.. CIRCUITPY-CHANGE: REMOVE .. function:: heap_locked()
+
+   Lock or unlock the heap.  When locked no memory allocation can occur and a
+   `builtins.MemoryError` will be raised if any heap allocation is attempted.
+   `heap_locked()` returns a true value if the heap is currently locked.
+
+   These functions can be nested, ie `heap_lock()` can be called multiple times
+   in a row and the lock-depth will increase, and then `heap_unlock()` must be
+   called the same number of times to make the heap available again.
+
+   Both `heap_unlock()` and `heap_locked()` return the current lock depth
+   (after unlocking for the former) as a non-negative integer, with 0 meaning
+   the heap is not locked.
+
+   If the REPL becomes active with the heap locked then it will be forcefully
+   unlocked.
+
+   Note: `heap_locked()` is not enabled on most ports by default,
+   requires ``MICROPY_PY_MICROPYTHON_HEAP_LOCKED``.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: kbd_intr(chr)
+
+   Set the character that will raise a `KeyboardInterrupt` exception.  By
+   default this is set to 3 during script execution, corresponding to Ctrl-C.
+   Passing -1 to this function will disable capture of Ctrl-C, and passing 3
+   will restore it.
+
+   This function can be used to prevent the capturing of Ctrl-C on the
+   incoming stream of characters that is usually used for the REPL, in case
+   that stream is used for other purposes.
+
+.. CIRCUITPY-CHANGE: REMOVE .. function:: schedule(func, arg)
+
+   Schedule the function *func* to be executed "very soon".  The function
+   is passed the value *arg* as its single argument.  "Very soon" means that
+   the MicroPython runtime will do its best to execute the function at the
+   earliest possible time, given that it is also trying to be efficient, and
+   that the following conditions hold:
+
+   - A scheduled function will never preempt another scheduled function.
+   - Scheduled functions are always executed "between opcodes" which means
+     that all fundamental Python operations (such as appending to a list)
+     are guaranteed to be atomic.
+   - A given port may define "critical regions" within which scheduled
+     functions will never be executed.  Functions may be scheduled within
+     a critical region but they will not be executed until that region
+     is exited.  An example of a critical region is a preempting interrupt
+     handler (an IRQ).
+
+   A use for this function is to schedule a callback from a preempting IRQ.
+   Such an IRQ puts restrictions on the code that runs in the IRQ (for example
+   the heap may be locked) and scheduling a function to call later will lift
+   those restrictions.
+
+   On multi-threaded ports, the scheduled function's behaviour depends on
+   whether the Global Interpreter Lock (GIL) is enabled for the specific port:
+
+   - If GIL is enabled, the function can preempt any thread and run in its
+     context.
+   - If GIL is disabled, the function will only preempt the main thread and run
+     in its context.
+
+   Note: If `schedule()` is called from a preempting IRQ, when memory
+   allocation is not allowed and the callback to be passed to `schedule()` is
+   a bound method, passing this directly will fail. This is because creating a
+   reference to a bound method causes memory allocation. A solution is to
+   create a reference to the method in the class constructor and to pass that
+   reference to `schedule()`. This is discussed in detail here
+   :ref:`reference documentation <isr_rules>` under "Creation of Python
+   objects".
+
+   There is a finite queue to hold the scheduled functions and `schedule()`
+   will raise a `RuntimeError` if the queue is full.