Merge branch 'micropython:master' into esp32_bitstream

Author: ricksorensen

.github/workflows/ports_esp32.yml

@@ -12,6 +12,10 @@ on:
       - 'lib/**'
       - 'drivers/**'
       - 'ports/esp32/**'
+  schedule:
+     # Scheduled run exists to keep master branch ESP-IDF cache entry hot
+     # and prevent creating many redundant per-branch cache entries instead.
+     - cron: "20 0 * * *"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

.github/workflows/ports_unix.yml

@@ -217,6 +217,20 @@ jobs:
       if: failure()
       run: tests/run-tests.py --print-failures
 
+  repr_b:
+    runs-on: ubuntu-22.04 # use 22.04 to get libffi-dev:i386
+    steps:
+    - uses: actions/checkout@v5
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_32bit_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_repr_b_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_repr_b_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
   macos:
     runs-on: macos-latest
     steps:

.github/workflows/ports_windows.yml

@@ -29,8 +29,10 @@ jobs:
         include:
         - visualstudio: '2017'
           vs_version: '[15, 16)'
+          custom_vs_install: true
         - visualstudio: '2019'
           vs_version: '[16, 17)'
+          custom_vs_install: true
         - visualstudio: '2022'
           vs_version: '[17, 18)'
         # trim down the number of jobs in the matrix
@@ -43,18 +45,17 @@ jobs:
     env:
       CI_BUILD_CONFIGURATION: ${{ matrix.configuration }}
     steps:
-    - name: Install Visual Studio 2017
-      if: matrix.visualstudio == '2017'
+    - name: Install Visual Studio ${{ matrix.visualstudio }}
+      if: matrix.custom_vs_install
+      shell: bash
+      # Shell functions in this block are to retry intermittent corrupt
+      # downloads (with a clean download dir) before failing the job outright
       run: |
-        choco install visualstudio2017buildtools
-        choco install visualstudio2017-workload-vctools
-        choco install windows-sdk-8.1
-    - name: Install Visual Studio 2019
-      if: matrix.visualstudio == '2019'
-      run: |
-        choco install visualstudio2019buildtools
-        choco install visualstudio2019-workload-vctools
-        choco install windows-sdk-8.1
+        try () { ($@) || ($@) || ($@) || ($@) }
+        clean_install () ( rm -rf $TEMP/chocolatey; choco install $1 )
+        try clean_install visualstudio${{ matrix.visualstudio }}buildtools
+        try clean_install visualstudio${{ matrix.visualstudio }}-workload-vctools
+        try clean_install windows-sdk-8.1
     - uses: microsoft/setup-msbuild@v2
       with:
         vs-version: ${{ matrix.vs_version }}

.github/workflows/ports_zephyr.yml

@@ -12,6 +12,10 @@ on:
       - 'lib/**'
       - 'ports/zephyr/**'
       - 'tests/**'
+  schedule:
+     # Scheduled run exists to keep master branch Zephyr cache entry hot
+     # and prevent creating many redundant per-branch cache entries instead.
+     - cron: "40 4 * * *"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

docs/README.md

@@ -13,8 +13,7 @@ Building the documentation locally
 If you're making changes to the documentation, you may want to build the
 documentation locally so that you can preview your changes.
 
-Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme,
-preferably in a virtualenv:
+Install Sphinx and sphinx_rtd_theme, preferably in a virtualenv:
 
      pip install sphinx
      pip install sphinx_rtd_theme
@@ -25,6 +24,21 @@ In `micropython/docs`, build the docs:
 
 You'll find the index page at `micropython/docs/build/html/index.html`.
 
+Documentation autobuild
+-----------------------
+
+For a more convenient development experience, you can use `sphinx-autobuild`
+to automatically rebuild and serve the documentation when you make changes:
+
+    pip install sphinx-autobuild
+
+Then run from the `micropython/docs` directory:
+
+    sphinx-autobuild . build/html
+
+This will start a local web server (typically at `http://127.0.0.1:8000`)
+and automatically rebuild the documentation whenever you save changes to the source files.
+
 Having readthedocs.org build the documentation
 ----------------------------------------------
 

docs/develop/gettingstarted.rst

@@ -282,6 +282,34 @@ To run a selection of tests on a board/device connected over USB use:
 
 See also :ref:`writingtests`.
 
+Additional make targets for developers
+--------------------------------------
+
+In all ``make``-based ports, there is a target to print the size of a specific object file.
+When a change is confined to a single file, this is useful when testing variations to find smaller alternatives.
+
+For instance, to print the size of ``objstr.o`` in the ``py/`` directory when making a unix standard build:
+
+.. code-block:: bash
+
+   $ make build-standard/py/objstr.sz
+
+Similarly, there is a target to save the preprocessed version of a file:
+
+.. code-block:: bash
+
+   $ make build-standard/py/objstr.pp
+
+In ``ports/unix`` there are additional targets related to running tests:
+
+.. code-block:: bash
+
+   $ make test//int       # Run all tests matching the pattern "int"
+   $ make test/ports/unix # Run all tests in ports/unix
+   $ make test-failures   # Re-run only the failed tests
+   $ make print-failures  # print the differences for failed tests
+   $ make clean-failures  # delete the .exp and .out files from failed tests
+
 Using ci.sh locally
 -------------------
 
@@ -306,6 +334,22 @@ As an example, you can build and test the unix minimal port with:
 
    $ tools/ci.sh unix_minimal_build unix_minimal_run_tests
 
+If you use the bash shell, you can add a ``ci`` command with tab completion:
+
+.. code-block:: bash
+
+   $ eval `tools/ci.sh --bash-completion`
+   $ ci unix_cov<tab>
+
+This will complete the ci step name to ``unix_coverage_``.
+Pressing tab a second time will show the list of matching steps:
+
+.. code-block:: bash
+
+   $ ci unix_coverage_<tab>
+   unix_coverage_32bit_build
+   unix_coverage_32bit_run_native_mpy_tests…
+
 Folder structure
 ----------------
 

docs/esp32/quickref.rst

@@ -287,6 +287,10 @@ with a timer ID of 0, 0 and 1, or from 0 to 3 (inclusive)::
 The period is in milliseconds. When using UART.IRQ_RXIDLE, timer 0 is needed for
 the IRQ_RXIDLE mechanism and must not be used otherwise.
 
+Timer callbacks are scheduled as soft interrupts on this port; hard
+callbacks are not implemented. Specifying ``hard=True`` will raise
+a ValueError.
+
 Virtual timers are not currently supported on this port.
 
 .. _Pins_and_GPIO:

docs/esp8266/quickref.rst

@@ -108,6 +108,9 @@ with timer ID of -1::
 
 The period is in milliseconds.
 
+By default, timer callbacks are scheduled as soft interrupts on this port.
+Specify ``hard=True`` to run them in hard interrupt context instead.
+
 Pins and GPIO
 -------------
 

docs/library/machine.Timer.rst

@@ -18,8 +18,9 @@ Timer callbacks.
 
     Memory can't be allocated inside irq handlers (an interrupt) and so
     exceptions raised within a handler don't give much information.  See
-    :func:`micropython.alloc_emergency_exception_buf` for how to get around this
-    limitation.
+    :func:`micropython.alloc_emergency_exception_buf` for how to get around
+    this limitation, which applies to all callbacks of Timers created with
+    ``hard=True``.
 
 If you are using a WiPy board please refer to :ref:`machine.TimerWiPy <machine.TimerWiPy>`
 instead of this class.
@@ -38,7 +39,7 @@ Constructors
 Methods
 -------
 
-.. method:: Timer.init(*, mode=Timer.PERIODIC, freq=-1, period=-1, callback=None)
+.. method:: Timer.init(*, mode=Timer.PERIODIC, freq=-1, period=-1, callback=None, hard=True)
 
    Initialise the timer. Example::
 
@@ -76,6 +77,19 @@ Methods
        will occur upon timer expiration:
        ``TypeError: 'NoneType' object isn't callable``
 
+     - ``hard`` can be one of:
+
+       - ``True`` - The callback will be executed in hard interrupt
+         context, which minimises delay and jitter but is subject to the
+         limitations described in :ref:`isr_rules` including being unable
+         to allocate on the heap.
+       - ``False`` - The callback will be scheduled as a soft interrupt,
+         allowing it to allocate but possibly also introducing
+         garbage-collection delays and jitter.
+
+       The default value of this option is port-specific for historical
+       reasons.
+
 .. method:: Timer.deinit()
 
    Deinitialises the timer. Stops the timer, and disables the timer peripheral.

docs/library/os.rst

@@ -133,6 +133,37 @@ Terminal redirection and duplication
 
    The function returns the previous stream-like object in the given slot.
 
+.. function:: dupterm_notify(obj_in, /)
+
+    Notify the MicroPython REPL that input is available on a stream-like object
+    previously registered via `os.dupterm()`.
+
+    This function should be called by custom stream implementations (e.g., UART,
+    Bluetooth, or other non-USB REPL streams) to inform the REPL that input is
+    ready to be read. Proper use ensures that special characters such as
+    Ctrl+C (used to trigger KeyboardInterrupt) are processed promptly by the
+    REPL, enabling expected interruption behavior for user code.
+
+    The *obj_in* parameter is ignored by `os.dupterm_notify()`, but is required to allow calling
+    dupterm_notify from an interrupt handler such as `UART.irq()`.
+
+    Example:
+
+    .. code-block:: python
+
+        from machine import UART
+        import os
+        uart = UART(0)
+        os.dupterm(uart, 0)
+        uart.irq(os.dupterm_notify, machine.UART.IRQ_RX)
+
+    .. note::
+        If the ``dupterm_notify()`` function is not called, input from the custom stream
+        may not be detected or processed until the next REPL poll, potentially delaying
+        KeyboardInterrupts or other control signals.
+        This is especially important for UART, Bluetooth and other
+        non-standard REPL connections, where automatic notification is not guaranteed.
+
 Filesystem mounting
 -------------------