tests/run-tests.py: Add automatic retry for known-flaky tests.

.github/pull_request_template.md

@@ -3,7 +3,6 @@
      others can review your Pull Request.
 
      Before submitting, please read:
-     https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md
      https://github.com/micropython/micropython/wiki/ContributorGuidelines
 
      Please check any CI failures that appear after your Pull Request is opened.
@@ -12,16 +11,15 @@
 ### Summary
 
 <!-- Explain the reason for making this change. What problem does the pull request
-     solve, or what improvement does it add? Add links if relevant. -->
-
+     solve, or what improvement does it add? Add links if relevant,
+     especially links to open issues. -->
 
 ### Testing
 
 <!-- Explain what testing you did, and on which boards/ports. If there are
      boards or ports that you couldn't test, please mention this here as well.
 
-     If you leave this empty then your Pull Request may be closed. -->
-
+     If you leave this section empty then your Pull Request may be closed. -->
 
 ### Trade-offs and Alternatives
 
@@ -31,3 +29,20 @@
 
      Delete this heading if not relevant (i.e. small fixes) -->
 
+
+### Generative AI
+
+<!-- Please delete the answer below which doesn't apply, or write your own
+     answer with more details. -->
+
+I did not use generative AI tools when creating this PR.
+
+I used generative AI tools when creating this PR, but a human has checked the
+code and is responsible for the code and the description above.
+
+<!-- We require everyone to answer this question. If you delete this section or
+     ignore it then your PR may be closed.
+
+     For more information, consult the MicroPython Generative AI Policy:
+     https://github.com/micropython/micropython/wiki/ContributorGuidelines#generative-ai-policy
+     -->

.github/workflows/code_size.yml

@@ -66,7 +66,7 @@ jobs:
       run: echo $PR_NUMBER > pr_number
     - name: Upload diff
       if: github.event_name == 'pull_request'
-      uses: actions/upload-artifact@v6
+      uses: actions/upload-artifact@v7
       with:
         name: code-size-report
         path: |

.github/workflows/mpremote.yml

@@ -22,7 +22,7 @@ jobs:
     - name: Build mpremote wheel
       run: cd tools/mpremote && python -m build --wheel
     - name: Archive mpremote wheel
-      uses: actions/upload-artifact@v6
+      uses: actions/upload-artifact@v7
       with:
         name: mpremote
         path: |

docs/develop/writingtests.rst

@@ -68,3 +68,76 @@ And to run only a certain set of tests (eg a directory):
 
    $ ./run-tests.py -d basics
    $ ./run-tests.py float/builtin*.py
+
+Using run-tests.py
+------------------
+
+The ``run-tests.py`` script supports several parameters to customize test execution:
+
+**Target and Device Selection:**
+
+* ``-t, --test-instance``
+
+The -t option accepts the following for the test instance:
+
+- **unix** - use the unix port of MicroPython, specified by the MICROPY_MICROPYTHON
+  environment variable (which defaults to the standard variant of either the unix
+  or windows ports, depending on the host platform)
+- **webassembly** - use the webassembly port of MicroPython, specified by the
+  MICROPY_MICROPYTHON_MJS environment variable (which defaults to the standard
+  variant of the webassembly port)
+- **port:<device>** - connect to and use the given serial port device
+- **a<n>** - connect to and use /dev/ttyACM<n>
+- **u<n>** - connect to and use /dev/ttyUSB<n>
+- **c<n>** - connect to and use COM<n>
+- **exec:<command>** - execute a command and attach to it's stdin/stdout
+- **execpty:<command>** - execute a command and attach to the printed /dev/pts/<n> device
+- **<a>.<b>.<c>.<d>** - connect to the given IPv4 address
+- anything else specifies a serial port
+
+**Test Selection:**
+
+* ``-d, --test-dirs`` - Specify one or more test directories to run
+* ``-i, --include REGEX`` - Include tests matching regex pattern
+* ``-e, --exclude REGEX`` - Exclude tests matching regex pattern
+* ``files`` - Specific test files to run
+
+**Execution Options:**
+
+* ``--emit <EMITTER>`` - MicroPython emitter, EMITTER can be bytecode or native. Default: bytecode
+* ``--via-mpy`` - Compile .py files to .mpy first
+* ``--heapsize`` - Set heap size for tests
+* ``-j, --jobs N`` - Number of tests to run simultaneously
+
+Set the MICROPY_MPYCROSS environment variable to use a specific version of ``mpy-cross`` when using ``--via-mpy``.
+
+**Result Management:**
+
+* ``-r, --result-dir`` - Directory for test results. Default: results/
+* ``--print-failures`` - Show diff of failed tests and exit
+* ``--clean-failures`` - Delete .exp and .out files from prior failed tests
+* ``--run-failures`` - Re-run only previously failed tests
+
+**Examples:**
+
+.. code-block:: bash
+
+   # Run only basic tests with native emitter
+   $ ./run-tests.py --emit native -d basics extmod
+
+   # Run tests excluding async functionality
+   $ ./run-tests.py -e async
+
+   # Run tests matching *_pep_*
+   $ ./run-tests.py -i *_pep_*
+
+   # Run specific test files in parallel
+   $ ./run-tests.py -j 4 basics/list*.py
+
+   # Test on connected ESP32 board
+   $ ./run-tests.py -t /dev/ttyUSB0
+   # or
+   $ ./run-tests.py -t u0
+
+   # Re-run only failed tests from previous run
+   $ ./run-tests.py --run-failures

docs/library/index.rst

@@ -78,6 +78,7 @@ library.
    select.rst
    socket.rst
    ssl.rst
+   string.templatelib.rst
    struct.rst
    sys.rst
    time.rst

docs/library/machine.Counter.rst

@@ -7,14 +7,14 @@ class Counter -- pulse counter
 Counter implements pulse counting by monitoring an input signal and counting
 rising or falling edges.
 
-Minimal example usage::
+Minimal ESP32 example usage::
 
     from machine import Pin, Counter
 
     counter = Counter(0, Pin(0, Pin.IN))  # create Counter for pin 0 and begin counting
     value = counter.value()               # retrieve current pulse count
 
-Availability: **ESP32**
+Availability: **ESP32, MIMXRT**
 
 Constructors
 ------------
@@ -47,12 +47,49 @@ Methods
      or ``Counter.FALLING``. *(Supported on ESP32)*
 
    - *direction* specifies the direction to count. Either ``Counter.UP`` (the
-     default) or ``Counter.DOWN``. *(Supported on ESP32)*
+     default) or ``Counter.DOWN``. *(Supported on ESP32 and MIMXRT)*
+     A :ref:`machine.Pin <machine.Pin>` object as parameter argument specifies a
+     pin which controls the counting direction. Low: Count up, High: Count down.
+     *(Supported on MIMXRT)*
 
    - *filter_ns* specifies a minimum period of time in nanoseconds that the
      source signal needs to be stable for a pulse to be counted. Implementations
      should use the longest filter supported by the hardware that is less than
-     or equal to this value. The default is 0 (no filter). *(Supported on ESP32)*
+     or equal to this value. The default is 0 (no filter). *(Supported on ESP32 and MIMXRT)*
+
+   - *max* Specify the upper counting range. The position counter will count up
+     from a *min* start value up to *max*, then roll over to the init value and
+     increase the cycles counter by one. When counting down, the cycles counter
+     decreases at the transition from *min* to *max*. The range is reset by defining
+     both *max* and *min* to 0. The default value is the hardware's counter range.
+     *(Supported by MIMXRT and the ESP32 PCNT module)*
+
+   - *min* Specify the lower counting range. The default value is 0.
+     *(Supported by MIMXRT and the ESP32 PCNT module)*
+
+   - *index* A Pin specifier telling to which pin the index pulse is connected.
+     At a rising slope of the index pulse the pulse counter is reset to the min value and
+     the cycles counter is increased or decreased by one, depending on the counting direction.
+     A *value* of *None* disables the index
+     input. *(Supported on MIMXRT)*
+
+   - *reset* A Pin specifier telling to which pin the reset pulse is connected.
+     At a rising slope of the reset pulse the counter is set to the init
+     value, but the cycles counter is not changed. A *value* of *None* disables the reset input.
+     *(Supported on MIMXRT)*
+
+   - *match* Set the counter value at which the interrupt IRQ_MATCH shall trigger.
+     The value is not checked for being in the bounds of the counter range. This option
+     if equivalent to the *threshold* options of the ESP32 PCNT module.
+     A *value* of *None* resets the match value and disables the IRQ_MATCH interrupt.
+     *(Supported on MIMXRT)*
+
+   - *match_pin* A Pin specifier telling to which pin the match output is connected.
+     This output will have a high level as long as the counter matches the
+     match value. The signal is generated by the encoder logic and requires no
+     further software support. The pulse width is defined by the input signal frequency
+     and can be very short, like 20ns, or stay, if the counter stops at the match value.
+     A *value* of *None* disables the match output. *(Supported on MIMXRT)*
 
 .. method:: Counter.deinit()
 
@@ -79,15 +116,63 @@ Methods
    the counter (i.e. to measure the counts since the last call), and this will
    avoid this problem.
 
+.. method:: Counter.cycles([value])
+
+   Get or set the current cycles counter of the counter as signed 16 bit integer.
+   The value represents the overflow or underflow events of the count range.
+   With no arguments the actual cycles counter value is returned.
+   With a single *value* argument the cycles counter is set to that value. The
+   base counter is not changed. The method returns the previous value.
+   *(Supported on MIMXRT)*
+
+.. method:: Counter.irq(handler=None, trigger=0, hard=False)
+
+   Specifies, that the *handler* is called when the respective *event* happens.
+
+   *event* may be:
+    - Counter.IRQ_RESET Triggered with a transition at the *reset* input.
+    - Counter.IRQ_INDEX Triggered with a transition at the *index* input.
+    - Counter.IRQ_MATCH Triggered when the positions counter matches the match value. For fast signals,
+      the actual position counter value when retrieved in the callback may be different from the trigger value.
+    - Counter.IRQ_ROLL_OVER Triggered when the position counter rolls over from the highest
+      to the lowest value.
+    - Counter.IRQ_ROLL_UNDER Triggered when the position counter rolls under from the lowest
+      to the highest value.
+
+   The callback function *handler* receives a single argument, which is the Counter object. All
+   events share the same callback. The event which triggers the callback can be identified
+   with the irq.flags() method. The argument *hard* specifies, whether the callback is called
+   as a hard interrupt or as regular scheduled function. Hard interrupts have always a short latency,
+   but are limited in that they must not allocate memory. Regular scheduled functions are not limited
+   in what can be used, but depending on the load of the device execution may be delayed.
+   Under low load, the difference in latency is minor.
+
+   The default arguments values are handler=None, trigger=0, hard=False. The callback will be
+   disabled, when called with handler=None.
+
+   The position match event is triggered as long as the position and match value are identical.
+   Therefore the position match callback is run in a one-shot fashion, and has to be enabled
+   again when the position has changed. It will be enabled by re-defining the trigger with either
+   :meth:`Counter.irq()` or :meth:`irq().trigger()`. For ESP32, Counter interrupts are handled
+   by the :ref:`PCNT<esp32.PCNT>`. *(Supported on MIMXRT)*
+
 Constants
 ---------
 
 .. data:: Counter.RISING
           Counter.FALLING
 
-   Select the pulse edge.
+   Select the pulse edge. *(Supported on ESP32)*
 
 .. data:: Counter.UP
           Counter.DOWN
 
    Select the counting direction.
+
+.. data:: Counter.IRQ_RESET
+          Counter.IRQ_INDEX
+          Counter.IRQ_MATCH
+          Counter.IRQ_ROLL_OVER
+          Counter.IRQ_ROLL_UNDER
+
+   Select the IRQ trigger event.  *(Supported on MIMXRT)*