Merge branch 'master' into esp32p4_new2

Signed-off-by: Vincent1-python <pywei201209@163.com>

Author: Vincent1-python

.github/workflows/ports_zephyr.yml

@@ -28,11 +28,14 @@ jobs:
     - uses: jlumbroso/free-disk-space@main
       with:
         # Only free up a few things so this step runs quickly.
+        # (android would save 9.6GiB, but takes about 13m)
+        # (large-packages would save 4.6GiB, but takes about 3m)
         android: false
         dotnet: true
         haskell: true
         large-packages: false
         docker-images: false
+        tool-cache: true
         swap-storage: false
     - uses: actions/checkout@v5
     - id: versions

README.md

@@ -98,28 +98,74 @@ development and testing of MicroPython itself, as well as providing
 lightweight alternative to CPython on these platforms (in particular on
 embedded Linux systems).
 
-The ["minimal"](ports/minimal) port provides an example of a very basic
-MicroPython port and can be compiled as both a standalone Linux binary as
-well as for ARM Cortex M4. Start with this if you want to port MicroPython to
-another microcontroller. Additionally the ["bare-arm"](ports/bare-arm) port
-is an example of the absolute minimum configuration, and is used to keep
-track of the code size of the core runtime and VM.
-
-In addition, the following ports are provided in this repository:
- - [cc3200](ports/cc3200) -- Texas Instruments CC3200 (including PyCom WiPy).
- - [esp32](ports/esp32) -- Espressif ESP32 SoC (including ESP32S2, ESP32S3, ESP32C3, ESP32C6).
- - [esp8266](ports/esp8266) -- Espressif ESP8266 SoC.
- - [mimxrt](ports/mimxrt) -- NXP m.iMX RT (including Teensy 4.x).
- - [nrf](ports/nrf) -- Nordic Semiconductor nRF51 and nRF52.
- - [pic16bit](ports/pic16bit) -- Microchip PIC 16-bit.
- - [powerpc](ports/powerpc) -- IBM PowerPC (including Microwatt)
- - [qemu](ports/qemu) -- QEMU-based emulated target (for testing)
- - [renesas-ra](ports/renesas-ra) -- Renesas RA family.
- - [rp2](ports/rp2) -- Raspberry Pi RP2040 (including Pico and Pico W).
- - [samd](ports/samd) -- Microchip (formerly Atmel) SAMD21 and SAMD51.
- - [stm32](ports/stm32) -- STMicroelectronics STM32 family (including F0, F4, F7, G0, G4, H7, L0, L4, WB)
- - [webassembly](ports/webassembly) -- Emscripten port targeting browsers and NodeJS.
- - [zephyr](ports/zephyr) -- Zephyr RTOS.
+Over twenty different MicroPython ports are provided in this repository,
+split across three
+[MicroPython Support Tiers](https://docs.micropython.org/en/latest/develop/support_tiers.html).
+
+Tier 1 Ports
+============
+
+👑 Ports in [Tier 1](https://docs.micropython.org/en/latest/develop/support_tiers.html)
+are mature and have the most active development, support and testing:
+
+| Port                     | Target                                                                                 | Quick Reference                                                      |
+|--------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------|
+| [esp32](ports/esp32)*    | Espressif ESP32 SoCs (ESP32, ESP32S2, ESP32S3, ESP32C3, ESP32C6)                       | [here](https://docs.micropython.org/en/latest/esp32/quickref.html)   |
+| [mimxrt](ports/mimxrt)   | NXP m.iMX RT                                                                           | [here](https://docs.micropython.org/en/latest/mimxrt/quickref.html)  |
+| [rp2](ports/rp2)         | Raspberry Pi RP2040 and RP2350                                                         | [here](https://docs.micropython.org/en/latest/rp2/quickref.html)     |
+| [samd](ports/samd)       | Microchip (formerly Atmel) SAMD21 and SAMD51                                           | [here](https://docs.micropython.org/en/latest/samd/quickref.html)    |
+| [stm32](ports/stm32)     | STMicroelectronics STM32 MCUs (F0, F4, F7, G0, G4, H5, H7, L0, L1, L4, N6, WB, WL)     | [here](https://docs.micropython.org/en/latest/pyboard/quickref.html) |
+| [unix](ports/unix)       | Linux, BSD, macOS, WSL                                                                 | [here](https://docs.micropython.org/en/latest/unix/quickref.html)    |
+| [windows](ports/windows) | Microsoft Windows                                                                      | [here](https://docs.micropython.org/en/latest/unix/quickref.html)    |
+
+An asterisk indicates that the port has ongoing financial support from the vendor.
+
+Tier 2 Ports
+============
+
+✔ Ports in [Tier 2](https://docs.micropython.org/en/latest/develop/support_tiers.html)
+are less mature and less actively developed and tested than Tier 1, but
+still fully supported:
+
+| Port                             | Target                                                      | Quick Reference                                                         |
+|----------------------------------|-------------------------------------------------------------|-------------------------------------------------------------------------|
+| [alif](ports/alif)               | Alif Semiconductor Ensemble MCUs (E3, E7)                   |                                                                         |
+| [embed](ports/embed)             | Generates a set of .c/.h files for embedding into a project |                                                                         |
+| [nrf](ports/nrf)                 | Nordic Semiconductor nRF51 and nRF52                        |                                                                         |
+| [renesas-ra](ports/renesas-ra)   | Renesas RA family                                           | [here](https://docs.micropython.org/en/latest/renesas-ra/quickref.html) |
+| [webassembly](ports/webassembly) | Emscripten port targeting browsers and NodeJS               |                                                                         |
+| [zephyr](ports/zephyr)           | Zephyr RTOS                                                 | [here](https://docs.micropython.org/en/latest/zephyr/quickref.html)     |
+
+Tier 3 Ports
+============
+
+Ports in [Tier 3](https://docs.micropython.org/en/latest/develop/support_tiers.html)
+are built in CI but not regularly tested by the MicroPython maintainers:
+
+| Port                       | Target                                                            | Quick Reference                                                         |
+|----------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------|
+| [cc3200](ports/cc3200)     | Texas Instruments CC3200                                          | [For WiPy](https://docs.micropython.org/en/latest/wipy/quickref.html)   |
+| [esp8266](ports/esp8266)   | Espressif ESP8266 SoC                                             | [here](https://docs.micropython.org/en/latest/esp8266/quickref.html)    |
+| [pic16bit](ports/pic16bit) | Microchip PIC 16-bit                                              |                                                                         |
+| [powerpc](ports/powerpc)   | IBM PowerPC (including Microwatt)                                 |                                                                         |
+
+Additional Ports
+================
+
+In addition to the above there is a Tier M containing ports that are used
+primarily for maintenance, development and testing:
+
+- The ["bare-arm"](ports/bare-arm) port is an example of the absolute minimum
+  configuration that still includes the compiler, and is used to keep track
+  of the code size of the core runtime and VM.
+
+- The ["minimal"](ports/minimal) port provides an example of a very basic
+  MicroPython port and can be compiled as both a standalone Linux binary as
+  well as for ARM Cortex-M4. Start with this if you want to port MicroPython
+  to another microcontroller.
+
+- The [qemu](ports/qemu) port is a QEMU-based emulated target for Cortex-A,
+  Cortex-M, RISC-V 32-bit and RISC-V 64-bit architectures.
 
 The MicroPython cross-compiler, mpy-cross
 -----------------------------------------

docs/develop/index.rst

@@ -24,3 +24,4 @@ MicroPython to a new platform and implementing a core MicroPython library.
    publiccapi.rst
    extendingmicropython.rst
    porting.rst
+   support_tiers.rst

docs/develop/porting.rst

@@ -161,8 +161,6 @@ The following is an example of an ``mpconfigport.h`` file:
 
    // Type definitions for the specific machine.
 
-   typedef intptr_t mp_int_t; // must be pointer size
-   typedef uintptr_t mp_uint_t; // must be pointer size
    typedef long mp_off_t;
 
    // We need to provide a declaration/definition of alloca().

docs/develop/support_tiers.rst

@@ -0,0 +1,68 @@
+MicroPython Support Tiers
+=========================
+
+MicroPython operates with a set of Support Tier levels for the various ports.
+Tiers 1, 2 and 3 are the main Tier levels with Tier 1 being the most mature and
+actively maintained.  There is also Tier M for additional ports used primarily
+for maintenance, development and testing. These Tier levels are defined in the
+table below.
+
+.. table::
+  :widths: 40 9 9 9 9
+
+  +-----------------------------------------------+--------+--------+--------+--------+
+  |                                               | Tier 1 | Tier 2 | Tier 3 | Tier M |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | builds pass under CI                          | ✔      | ✔      | ✔      | ✔      |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | tests run under CI (where possible)           | ✔      | ✔      | ✔      | ✔      |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | actively maintained                           | ✔      | ✔      |        | ✔      |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | stable Python API                             | ✔      | ✔      |        |        |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | new features actively developed               | ✔      | ✔      |        |        |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | tested on hardware for releases               | ✔      | ✔      |        |        |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | prioritized bug reports                       | ✔      |        |        | ✔      |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | regressions warrant a patch release           | ✔      |        |        | ✔      |
+  +-----------------------------------------------+--------+--------+--------+--------+
+  | has port-specific documentation               | ✔      |        |        |        |
+  +-----------------------------------------------+--------+--------+--------+--------+
+
+Lower Tiers may tick more boxes, but the above table defines the minimum requirements
+for a port to belong to a Tier.
+
+Tier 1 ports:
+
+  - esp32
+  - mimxrt
+  - rp2
+  - samd
+  - stm32
+  - unix
+  - windows
+
+Tier 2 ports:
+
+  - alif
+  - embed
+  - nrf
+  - renesas-ra
+  - webassembly
+  - zephyr
+
+Tier 3 ports:
+
+  - cc3200
+  - esp8266
+  - pic16bit
+  - powerpc
+
+Tier M ports:
+
+  - bare-arm
+  - minimal
+  - qemu

docs/library/esp32.rst

@@ -43,6 +43,15 @@ Functions
 
     .. note:: This is only available for boards that have ext1 support.
 
+.. function:: wake_on_gpio(pins, level)
+
+    Configure how GPIO wakes the device from sleep.  *pins* can be ``None``
+    or a tuple/list of valid Pin objects.  *level* should be ``esp32.WAKEUP_ALL_LOW``
+    or ``esp32.WAKEUP_ANY_HIGH``.
+
+    .. note:: Some boards don't support waking on GPIO from deep sleep,
+       on those boards, the pins set here can only be used to wake from light sleep.
+
 .. function:: gpio_deep_sleep_hold(enable)
 
     Configure whether non-RTC GPIO pin configuration is retained during

docs/reference/mpyfiles.rst

@@ -58,12 +58,14 @@ If importing an .mpy file fails then try the following:
     sys_mpy = sys.implementation._mpy
     arch = [None, 'x86', 'x64',
         'armv6', 'armv6m', 'armv7m', 'armv7em', 'armv7emsp', 'armv7emdp',
-        'xtensa', 'xtensawin', 'rv32imc', 'rv64imc'][sys_mpy >> 10]
+        'xtensa', 'xtensawin', 'rv32imc', 'rv64imc'][(sys_mpy >> 10) & 0x0F]
     print('mpy version:', sys_mpy & 0xff)
     print('mpy sub-version:', sys_mpy >> 8 & 3)
     print('mpy flags:', end='')
     if arch:
         print(' -march=' + arch, end='')
+    if (sys_mpy >> 16) != 0:
+        print(' -march-flags=' + (sys_mpy >> 16), end='')
     print()
 
 * Check the validity of the .mpy file by inspecting the first two bytes of
@@ -80,6 +82,10 @@ If importing an .mpy file fails then try the following:
   above, or by inspecting the ``MPY_CROSS_FLAGS`` Makefile variable for the
   port that you are using.
 
+* If the third byte of the .mpy file has bit #6 set, then check whether the
+  encoded architecture-specific flag bits vuint is compatible with the
+  target you're importing the file on.
+
 The following table shows the correspondence between MicroPython release
 and .mpy version.
 
@@ -153,10 +159,42 @@ size    field
 ======  ================================
 byte    value 0x4d (ASCII 'M')
 byte    .mpy major version number
-byte    native arch and minor version number (was feature flags in older versions)
+byte    feature flags, native arch, minor version number (was feature flags in older versions)
 byte    number of bits in a small int
 ======  ================================
 
+The third byte is split as follows (MSB first):
+
+======  ================================
+bit     meaning
+======  ================================
+7       reserved, must be 0
+6       an architecture-specific flags vuint follows the header
+5..2    native arch number
+1..0    minor version number
+======  ================================
+
+Architecture-specific flags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If bit #6 of the header's feature flags byte is set, then a vuint containing
+optional architecture-specific information will follow the header. The contents
+of this integer depends on which native architecture the file is meant for.
+
+This is currently used to store which RISC-V processor extensions the MPY file
+needs to operate correctly besides I, M, C, and Zicsr.  Different flavours of
+ArmV7 are identified by their native architecture number, but reusing that
+mechanism would complicate things for RV32 and RV64.
+
+MPY files targeting RV32 or RV64 that do not need any particular processor
+extensions do not need to provide a flags integer (along with setting the
+appropriate bit in the header).  The lack of a flags value for RV32 and RV64
+MPY files is used to indicate that no specific extensions are needed, and saves
+one byte in the final output binary.
+
+See also the ``-march-flags`` command-line option in both ``mpy-tool.py`` and
+``mpy-cross`` to set this value when creating MPY files.
+
 The global qstr and constant tables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/zephyr/quickref.rst

@@ -135,11 +135,14 @@ the ``io-channels`` property containing all the ADC channels)::
 Disk Access
 -----------
 
-Use the :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class to support filesystem::
+Storage devices such as SD cards are automatically mounted at startup (e.g., at ``/sd``).
+For manual mounting, use the :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class::
 
     import vfs
     from zephyr import DiskAccess
 
+    print(DiskAccess.disks)             # list available disk names, e.g., ('SDHC',)
+
     block_dev = DiskAccess('SDHC')      # create a block device object for an SD card
     vfs.VfsFat.mkfs(block_dev)          # create FAT filesystem object using the disk storage block
     vfs.mount(block_dev, '/sd')         # mount the filesystem at the SD card subdirectory
@@ -152,12 +155,15 @@ Use the :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class to support filesystem
 Flash Area
 ----------
 
-Use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class to support filesystem::
+Flash storage is automatically mounted at ``/flash`` at startup with automatic filesystem creation.
+For manual mounting, use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class::
 
     import vfs
     from zephyr import FlashArea
 
-    block_dev = FlashArea(4, 4096)      # creates a block device object in the frdm-k64f flash scratch partition
+    print(FlashArea.areas)              # list available areas, e.g., {'storage': 1, 'scratch': 4}
+
+    block_dev = FlashArea(FlashArea.areas['scratch'], 4096)  # creates a block device object using the scratch partition
     vfs.VfsLfs2.mkfs(block_dev)         # create filesystem in lfs2 format using the flash block device
     vfs.mount(block_dev, '/flash')      # mount the filesystem at the flash subdirectory
 
@@ -166,8 +172,6 @@ Use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class to support filesystem::
         f.write('Hello world')                  # write to the file
     print(open('/flash/hello.txt').read())      # print contents of the file
 
-The ``FlashAreas``' IDs that are available are listed in the FlashArea module, as ``ID_*``.
-
 Sensor
 ------