diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
index 6f84de6f60e..97b5e558f40 100644
--- a/.git-blame-ignore-revs
+++ b/.git-blame-ignore-revs
@@ -1,3 +1,21 @@
+# all: Apply code formatting to new paths.
+48c7daaa3d7068c127c5bc395ffa72029ab9bba1
+
+# all: Prune trailing whitespace.
+dda9b9c6da5d3c31fa8769e581a753e95a270803
+
+# all: Remove the "STATIC" macro and just use "static" instead.
+decf8e6a8bb940d5829ca3296790631fcece7b21
+
+# renesas-ra: Fix spelling mistakes found by codespell.
+b3f2f18f927fa2fad10daf63d8c391331f5edf58
+
+# all: Update Python formatting to ruff-format.
+bbd8760bd9a2302e5abee29db279102bb11d7732
+
+# all: Fix various spelling mistakes found by codespell 2.2.6.
+cf490a70917a1b2d38ba9b58e763e0837d0f7ca7
+
# all: Fix spelling mistakes based on codespell check.
b1229efbd1509654dec6053865ab828d769e29db
diff --git a/.gitattributes b/.gitattributes
index e6d31d6aa31..04a84d3e098 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -8,14 +8,19 @@
# These are binary so should never be modified by git.
*.a binary
+*.FLM binary
+*.ico binary
*.png binary
*.jpg binary
*.dxf binary
*.mpy binary
+*.der binary
+*.bin binary
# These should also not be modified by git.
tests/basics/string_cr_conversion.py -text
tests/basics/string_crlf_conversion.py -text
+tests/micropython/test_normalize_newlines.py.exp -text
ports/stm32/pybcdc.inf_template -text
ports/stm32/usbhost/** -text
ports/cc3200/hal/aes.c -text
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
deleted file mode 100644
index 7bad9562964..00000000000
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-name: Bug report
-about: Report an issue
-title: ''
-labels: bug
-assignees: ''
-
----
-
-* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
-
-* In your issue, please include a clear and concise description of what the bug is, the expected output, and how to replicate it.
-
-* If this issue involves external hardware, please include links to relevant datasheets and schematics.
-
-* If you are seeing code being executed incorrectly, please provide a minimal example and expected output (e.g. comparison to CPython).
-
-* For build issues, please include full details of your environment, compiler versions, command lines, and build output.
-
-* Please provide as much information as possible about the version of MicroPython you're running, such as:
- - firmware file name
- - git commit hash and port/board
- - version information shown in the REPL (hit Ctrl-B to see the startup message)
-
-* Remove all placeholder text above before submitting.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 00000000000..1ec6c7067f9
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,109 @@
+name: Bug report
+description: Report a bug or unexpected behaviour
+labels: ["bug"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Please provide as much detail as you can, it really helps us find and fix bugs faster.
+
+ #### Not a bug report?
+
+ * If you have a question \"How Do I ...?\", please post it on [GitHub Discussions](https://github.com/orgs/micropython/discussions/) or [Discord](https://discord.gg/RB8HZSAExQ) instead of here.
+ * For missing or incorrect documentation, or feature requests, then please [choose a different issue type](https://github.com/micropython/micropython/issues/new/choose).
+
+ #### Existing issue?
+
+ * Please search for [existing issues](https://github.com/micropython/micropython/issues) matching this bug before reporting.
+ - type: input
+ id: port-board-hw
+ attributes:
+ label: Port, board and/or hardware
+ description: |
+ Which MicroPython port(s) and board(s) are you using?
+ placeholder: |
+ esp32 port, ESP32-Fantastic board.
+ validations:
+ required: true
+ - type: textarea
+ id: version
+ attributes:
+ label: MicroPython version
+ description: |
+ To find the version:
+
+ 1. Open a serial REPL.
+ 2. Type Ctrl-B to see the startup message.
+ 3. Copy-paste that output here.
+
+ If the issue is about building MicroPython, please provide output of `git describe --dirty` and as much information as possible about the build environment.
+
+ If the version or configuration is modified from the official MicroPython releases or the master branch, please tell us the details of this as well.
+ placeholder: |
+ MicroPython v6.28.3 on 2029-01-23; PyBoard 9 with STM32F9
+ validations:
+ required: true
+ - type: textarea
+ id: steps-reproduce
+ attributes:
+ label: Reproduction
+ description: |
+ What steps will reproduce the problem? Please include all details that could be relevant about the environment, configuration, etc.
+
+ If there is Python code to reproduce this issue then please either:
+ a. Type it into a code block below ([code block guide](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks)), or
+ b. Post longer code to a [GitHub gist](https://gist.github.com/), or
+ c. Create a sample project on GitHub.
+
+ For build issues, please provide the exact build commands that you ran.
+ placeholder: |
+ 1. Copy paste the code provided below into a new file
+ 2. Use `mpremote run` to execute it on the board.
+ validations:
+ required: true
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected behaviour
+ description: |
+ What did you expect MicroPython to do? If comparing output with CPython or a different MicroPython port/version then please provide that output here.
+ placeholder: |
+ Expected to print "Hello World".
+
+ Here is the correct output, seen with previous MicroPython version v3.14.159:
+
+ > [...]
+ - type: textarea
+ id: what-happened
+ attributes:
+ label: Observed behaviour
+ description: |
+ What actually happened? Where possible please paste exact output, or the complete build log, etc. Very long output can be linked in a [GitHub gist](https://gist.github.com/).
+ placeholder: |
+ This unexpected exception appears:
+
+ > [...]
+ validations:
+ required: true
+ - type: textarea
+ id: additional
+ attributes:
+ label: Additional Information
+ description: |
+ Is there anything else that might help to resolve this issue?
+ value: No, I've provided everything above.
+ - type: dropdown
+ id: code-of-conduct
+ attributes:
+ label: Code of Conduct
+ description: |
+ Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone?
+ options:
+ - "Yes, I agree"
+ multiple: true
+ validations:
+ required: true
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to help improve MicroPython.
diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md
deleted file mode 100644
index e36fa62ac29..00000000000
--- a/.github/ISSUE_TEMPLATE/documentation.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-name: Documentation issue
-about: Report areas of the documentation or examples that need improvement
-title: 'docs: '
-labels: documentation
-assignees: ''
-
----
-
-* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab instead.
-
-* Describe what was missing from the documentation and/or what was incorrect/incomplete.
-
-* If possible, please link to the relevant page on https://docs.micropython.org/
-
-* Remove all placeholder text above before submitting.
diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml
new file mode 100644
index 00000000000..93051e51c80
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/documentation.yml
@@ -0,0 +1,46 @@
+name: Documentation issue
+description: Report areas of the documentation or examples that need improvement
+title: "docs: "
+labels: ["documentation"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ This form is for reporting issues with the documentation or examples provided with MicroPython.
+
+ If you have a general question \"How Do I ...?\", please post it on [GitHub Discussions](https://github.com/orgs/micropython/discussions/) or [Discord](https://discord.gg/RB8HZSAExQ) instead of here.
+
+ #### Existing issue?
+
+ * Please search for [existing issues](https://github.com/micropython/micropython/issues) before reporting a new one.
+ - type: input
+ id: page
+ attributes:
+ label: Documentation URL
+ description: |
+ Does this issue relate to a particular page in the [online documentation](https://docs.micropython.org/en/latest/)? If yes, please paste the URL of the page:
+ placeholder: |
+ https://docs.micropython.org/en/latest/
+ - type: textarea
+ id: version
+ attributes:
+ label: Description
+ description: |
+ Please describe what was missing from the documentation and/or what was incorrect/incomplete.
+ validations:
+ required: true
+ - type: dropdown
+ id: code-of-conduct
+ attributes:
+ label: Code of Conduct
+ description: |
+ Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone?
+ options:
+ - "Yes, I agree"
+ multiple: true
+ validations:
+ required: true
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to help improve MicroPython.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
deleted file mode 100644
index 81b55d98e0d..00000000000
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-name: Feature request
-about: Request a feature or improvement
-title: ''
-labels: enhancement
-assignees: ''
-
----
-
-* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
-
-* Describe the feature you'd like to see added to MicroPython. In particular, what does this feature enable and why is it useful. MicroPython aims to strike a balance between functionality and code size, so please consider whether this feature can be optionally enabled and whether it can be provided in other ways (e.g. pure-Python library).
-
-* For core Python features, where possible please include a link to the relevant PEP.
-
-* For new architectures / ports / boards, please provide links to relevant documentation, specifications, and toolchains. Any information about the popularity and unique features about this hardware would also be useful.
-
-* For features for existing ports (e.g. new peripherals or microcontroller features), please describe which port(s) it applies too, and whether this is could be an extension to the machine API or a port-specific module?
-
-* For drivers (e.g. for external hardware), please link to datasheets and/or existing drivers from other sources.
-
-* Who do you expect will implement the feature you are requesting? Would you be willing to sponsor this work?
-
-* Remove all placeholder text above before submitting.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 00000000000..7d5162a32a4
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,74 @@
+name: Feature request
+description: Request a feature or improvement
+labels: ['enhancement']
+body:
+ - type: markdown
+ attributes:
+ value: |
+ This form is for requesting features or improvements in MicroPython.
+
+ #### Get feedback first
+
+ Before submitting a new feature idea here, suggest starting a discussion on [Discord](https://discord.gg/RB8HZSAExQ) or [GitHub Discussions](https://github.com/orgs/micropython/discussions/) to get early feedback from the community and maintainers.
+
+ #### Not a MicroPython core feature?
+
+ * If you have a question \"How Do I ...?\", please post it on GitHub Discussions or Discord instead of here.
+ * Could this feature be implemented as a pure Python library? If so, please open the request on the [micropython-lib repository](https://github.com/micropython/micropython-lib/issues) instead.
+
+ #### Existing issue?
+
+ * Please search for [existing issues](https://github.com/micropython/micropython/issues) before opening a new one.
+ - type: textarea
+ id: feature
+ attributes:
+ label: Description
+ description: |
+ Describe the feature you'd like to see added to MicroPython. What does this feature enable and why is it useful?
+
+ * For core Python features, where possible please include a link to the relevant PEP or CPython documentation.
+ * For new architectures / ports / boards, please provide links to relevant documentation, specifications, and toolchains. Any information about the popularity and unique features about this hardware would also be useful.
+ * For features for existing ports (e.g. new peripherals or microcontroller features), please describe which port(s) it applies to, and whether this is could be an extension to the machine API or a port-specific module?
+ * For drivers (e.g. for external hardware), please link to datasheets and/or existing drivers from other sources.
+
+ If there is an existing discussion somewhere about this feature, please add a link to it as well.
+ validations:
+ required: true
+ - type: textarea
+ id: size
+ attributes:
+ label: Code Size
+ description: |
+ MicroPython aims to strike a balance between functionality and code size. Can this feature be optionally enabled?
+
+ If you believe the usefulness of this feature would outweigh the additional code size, please explain. (It's OK to say you're unsure here, we're happy to discuss this with you.)
+ - type: dropdown
+ id: implementation
+ attributes:
+ label: Implementation
+ description: |
+ What is your suggestion for implementing this feature?
+
+ (See also: [How to sponsor](https://github.com/sponsors/micropython#sponsors), [How to submit a Pull Request](https://github.com/micropython/micropython/wiki/ContributorGuidelines).)
+ options:
+ - I hope the MicroPython maintainers or community will implement this feature
+ - I intend to implement this feature and would submit a Pull Request if desirable
+ - I would like to sponsor development of this feature
+ multiple: true
+ validations:
+ required: true
+ - type: dropdown
+ id: code-of-conduct
+ attributes:
+ label: Code of Conduct
+ description: |
+ Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone?
+ options:
+ - "Yes, I agree"
+ multiple: true
+ validations:
+ required: true
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to suggest improvements for MicroPython.
diff --git a/.github/ISSUE_TEMPLATE/security.md b/.github/ISSUE_TEMPLATE/security.md
deleted file mode 100644
index cfe4a4befdb..00000000000
--- a/.github/ISSUE_TEMPLATE/security.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-name: Security report
-about: Report a security issue or vulnerability in MicroPython
-title: ''
-labels: security
-assignees: ''
-
----
-
-* If you need to raise this issue privately with the MicroPython team, please email contact@micropython.org instead.
-
-* Include a clear and concise description of what the security issue is.
-
-* What does this issue allow an attacker to do?
-
-* Remove all placeholder text above before submitting.
diff --git a/.github/ISSUE_TEMPLATE/security.yml b/.github/ISSUE_TEMPLATE/security.yml
new file mode 100644
index 00000000000..57c2a5885ed
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/security.yml
@@ -0,0 +1,60 @@
+name: Security report
+description: Report a security issue or vulnerability in MicroPython
+labels: ["security"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ This form is for reporting security issues in MicroPython that are not readily exploitable.
+
+ 1. For issues that are readily exploitable or have high impact, please email contact@micropython.org instead.
+ 1. If this is a question about security, please ask it in [Discussions](https://github.com/orgs/micropython/discussions/) or [Discord](https://discord.gg/RB8HZSAExQ) instead.
+
+ #### Existing issue?
+
+ * Please search for [existing issues](https://github.com/micropython/micropython/issues) before reporting a new one.
+
+ - type: input
+ id: port-board-hw
+ attributes:
+ label: Port, board and/or hardware
+ description: |
+ Which MicroPython port(s) and board(s) are you using?
+ placeholder: |
+ esp32 port, ESP32-Duper board.
+ - type: textarea
+ id: version
+ attributes:
+ label: MicroPython version
+ description: |
+ To find the version:
+
+ 1. Open a serial REPL.
+ 2. Type Ctrl-B to see the startup message.
+ 3. Copy-paste that output here.
+
+ If the version or configuration is modified from the official MicroPython releases or the master branch, please tell us the details of this as well.
+ placeholder: |
+ MicroPython v6.28.3 on 2029-01-23; PyBoard 9 with STM32F9
+ - type: textarea
+ id: report
+ attributes:
+ label: Issue Report
+ description: |
+ Please provide a clear and concise description of the security issue.
+
+ * What does this issue allow an attacker to do?
+ * How does the attacker exploit this issue?
+ validations:
+ required: true
+ - type: dropdown
+ id: code-of-conduct
+ attributes:
+ label: Code of Conduct
+ description: |
+ Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone?
+ options:
+ - "Yes, I agree"
+ multiple: true
+ validations:
+ required: true
diff --git a/.github/actions/setup_esp32/action.yml b/.github/actions/setup_esp32/action.yml
new file mode 100644
index 00000000000..3b5da9eca87
--- /dev/null
+++ b/.github/actions/setup_esp32/action.yml
@@ -0,0 +1,47 @@
+name: Setup ESP-IDF for CI
+description: Install ESP-IDF
+inputs:
+ idf_ver:
+ required: true
+ type: string
+ ccache_key:
+ required: true
+ type: string
+
+runs:
+ using: "composite"
+
+ steps:
+ - id: python_ver
+ name: Read the Python version
+ run: echo PYTHON_VER=py$(python --version | cut -d' ' -f2) | tee "${GITHUB_OUTPUT}"
+ shell: bash
+
+ - name: Cached ESP-IDF install
+ id: cache_esp_idf
+ uses: actions/cache@v6
+ with:
+ path: |
+ ./esp-idf/
+ ~/.espressif/
+ !~/.espressif/dist/
+ ~/.cache/pip/
+ # Cache is keyed on both IDF version (from the job) and Python version (from the runner)
+ key: esp-idf-${{ inputs.idf_ver }}-${{ steps.python_ver.outputs.PYTHON_VER }}
+
+ - name: Install ESP-IDF packages
+ if: steps.cache_esp_idf.outputs.cache-hit != 'true'
+ env:
+ IDF_VER: ${{ inputs.idf_ver }}
+ run: tools/ci.sh esp32_idf_setup
+ shell: bash
+
+ - name: ccache
+ uses: hendrikmuhs/ccache-action@v1.2
+ with:
+ key: esp32-${{ inputs.idf_ver }}-${{ inputs.ccache_key }}
+
+ - name: Enable CCache for ESP-IDF
+ run: echo "IDF_CCACHE_ENABLE=1" >> ${GITHUB_ENV}
+ shell: bash
+
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000000..8be63024039
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,48 @@
+
+
+### Summary
+
+
+
+### Testing
+
+
+
+### Trade-offs and Alternatives
+
+
+
+
+### Generative AI
+
+
+
+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.
+
+
diff --git a/.github/workflows/biome.yml b/.github/workflows/biome.yml
new file mode 100644
index 00000000000..eba4e9f3908
--- /dev/null
+++ b/.github/workflows/biome.yml
@@ -0,0 +1,16 @@
+name: JavaScript code lint and formatting with Biome
+
+on: [push, pull_request]
+
+jobs:
+ eslint:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+ - name: Setup Biome
+ uses: biomejs/setup-biome@v2
+ with:
+ version: 1.5.3
+ - name: Run Biome
+ run: biome ci --indent-style=space --indent-width=4 tests/ ports/webassembly
diff --git a/.github/workflows/code_formatting.yml b/.github/workflows/code_formatting.yml
index 81a2715f1b3..5616fe33d7c 100644
--- a/.github/workflows/code_formatting.yml
+++ b/.github/workflows/code_formatting.yml
@@ -10,21 +10,11 @@ jobs:
code-formatting:
runs-on: ubuntu-22.04
steps:
- - uses: actions/checkout@v3
- - uses: actions/setup-python@v4
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
- name: Install packages
- run: source tools/ci.sh && ci_code_formatting_setup
+ run: tools/ci.sh c_code_formatting_setup
- name: Run code formatting
- run: source tools/ci.sh && ci_code_formatting_run
+ run: tools/ci.sh c_code_formatting_run
- name: Check code formatting
run: git diff --exit-code
-
- code-spelling:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v3
- - uses: actions/setup-python@v4
- - name: Install packages
- run: source tools/ci.sh && ci_code_spell_setup
- - name: Run spell checker
- run: source tools/ci.sh && ci_code_spell_run
diff --git a/.github/workflows/code_size.yml b/.github/workflows/code_size.yml
index 5d955703b66..dc3a47ded26 100644
--- a/.github/workflows/code_size.yml
+++ b/.github/workflows/code_size.yml
@@ -1,16 +1,22 @@
name: Check code size
on:
- push:
pull_request:
paths:
- '.github/workflows/*.yml'
- 'tools/**'
- 'py/**'
- 'extmod/**'
+ - 'shared/**'
- 'lib/**'
- 'ports/bare-arm/**'
+ - 'ports/esp32/**'
+ - 'ports/mimxrt/**'
- 'ports/minimal/**'
+ - 'ports/rp2/**'
+ - 'ports/samd/**'
+ - 'ports/stm32/**'
+ - 'ports/unix/**'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
@@ -18,17 +24,36 @@ concurrency:
jobs:
build:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
with:
fetch-depth: 100
- name: Install packages
- run: source tools/ci.sh && ci_code_size_setup
+ run: tools/ci.sh code_size_setup
+
+ - name: Find IDF_NEWEST_VER
+ id: idf_ver
+ run: |
+ echo "IDF_VER="$(yq .env.IDF_NEWEST_VER < .github/workflows/ports_esp32.yml) \
+ | tee "${GITHUB_OUTPUT}"
+
+ # The reference and current commit may be configured for different ESP-IDF versions
+ # but we use the same ESP-IDF version to build both, so disable the
+ # MICROPY_MAINTAINER_BUILD check (it'll be verified on the normal esp32 CI).
+ - name: Disable extra checks for older ESP-IDF
+ run: echo "MICROPY_MAINTAINER_BUILD=0" >> ${GITHUB_ENV}
+
+ - name: Setup ESP-IDF
+ uses: ./.github/actions/setup_esp32
+ with:
+ idf_ver: ${{ steps.idf_ver.outputs.IDF_VER }}
+ ccache_key: code_size
+
- name: Build
- run: source tools/ci.sh && ci_code_size_build
+ run: tools/ci.sh code_size_build
- name: Compute code size difference
- run: tools/metrics.py diff ~/size0 ~/size1 | tee diff
+ run: source tools/ci.sh && ci_code_size_report
- name: Save PR number
if: github.event_name == 'pull_request'
env:
@@ -36,7 +61,7 @@ jobs:
run: echo $PR_NUMBER > pr_number
- name: Upload diff
if: github.event_name == 'pull_request'
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v7
with:
name: code-size-report
path: |
diff --git a/.github/workflows/code_size_comment.yml b/.github/workflows/code_size_comment.yml
index 8baf76a47a7..ea9d45ddb87 100644
--- a/.github/workflows/code_size_comment.yml
+++ b/.github/workflows/code_size_comment.yml
@@ -11,11 +11,11 @@ concurrency:
jobs:
comment:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-22.04
steps:
- name: 'Download artifact'
id: download-artifact
- uses: actions/github-script@v6
+ uses: actions/github-script@v9
with:
result-encoding: string
script: |
@@ -56,7 +56,7 @@ jobs:
run: unzip code-size-report.zip
- name: Post comment to pull request
if: steps.download-artifact.outputs.result == 'ok'
- uses: actions/github-script@v6
+ uses: actions/github-script@v9
with:
github-token: ${{secrets.GITHUB_TOKEN}}
script: |
diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
new file mode 100644
index 00000000000..6155a348b5d
--- /dev/null
+++ b/.github/workflows/codespell.yml
@@ -0,0 +1,18 @@
+name: Check spelling with codespell
+
+on: [push, pull_request]
+
+jobs:
+ codespell:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ # codespell version should be kept in sync with .pre-commit-config.yml
+ - run: pip install --user codespell==2.4.1 tomli
+ - run: codespell
+ # additionally check for misspelling of "MicroPython"
+ - run: |
+ if git grep -n Micropython -- ":(exclude).github/workflows/codespell.yml"; then
+ echo "Please correct capitalisation of MicroPython on the above lines"
+ exit 1
+ fi
diff --git a/.github/workflows/commit_formatting.yml b/.github/workflows/commit_formatting.yml
index 0b27038f2d2..0e38ebcf868 100644
--- a/.github/workflows/commit_formatting.yml
+++ b/.github/workflows/commit_formatting.yml
@@ -1,6 +1,6 @@
name: Check commit message formatting
-on: [push, pull_request]
+on: [pull_request]
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
@@ -10,9 +10,9 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
with:
- fetch-depth: '100'
- - uses: actions/setup-python@v4
+ fetch-depth: 100
+ - uses: actions/setup-python@v7
- name: Check commit message formatting
- run: source tools/ci.sh && ci_commit_formatting_run
+ run: tools/ci.sh commit_formatting_run
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index e9b17007476..a27196734ad 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,9 +1,12 @@
name: Build docs
on:
+ push:
pull_request:
paths:
- docs/**
+ - py/**
+ - tests/cpydiff/**
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
@@ -14,9 +17,11 @@ jobs:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
- - uses: actions/setup-python@v4
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
- name: Install Python packages
- run: pip install Sphinx
+ run: pip install -r docs/requirements.txt
+ - name: Build unix port
+ run: tools/ci.sh unix_build_helper
- name: Build docs
run: make -C docs/ html
diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml
index 450805a6bde..bbfc93b1f64 100644
--- a/.github/workflows/examples.yml
+++ b/.github/workflows/examples.yml
@@ -18,8 +18,6 @@ jobs:
embedding:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Build
- run: make -C examples/embedding -f micropython_embed.mk && make -C examples/embedding
- - name: Run
- run: ./examples/embedding/embed | grep "hello world"
+ run: tools/ci.sh embedding_build
diff --git a/.github/workflows/mpremote.yml b/.github/workflows/mpremote.yml
index 14aef03e077..65ae823a14b 100644
--- a/.github/workflows/mpremote.yml
+++ b/.github/workflows/mpremote.yml
@@ -11,18 +11,28 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
with:
# Setting this to zero means fetch all history and tags,
# which hatch-vcs can use to discover the version tag.
fetch-depth: 0
- - uses: actions/setup-python@v4
+ - uses: actions/setup-python@v7
- name: Install build tools
run: pip install build
- name: Build mpremote wheel
- run: cd tools/mpremote && python -m build --wheel
+ run: |
+ if ! git rev-parse --verify -q v1.23.0 >/dev/null; then
+ echo "::error::mpremote wheel build requires recent MicroPython version tags in the forked repo."
+ echo ""
+ echo "To fix, push tags from upstream:"
+ echo " git remote add upstream https://github.com/micropython/micropython.git"
+ echo " git fetch upstream --tags"
+ echo " git push origin --tags"
+ exit 1
+ fi
+ cd tools/mpremote && python -m build --wheel
- name: Archive mpremote wheel
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v7
with:
name: mpremote
path: |
diff --git a/.github/workflows/mpy_format.yml b/.github/workflows/mpy_format.yml
index 66abb19b81a..965bcedc73e 100644
--- a/.github/workflows/mpy_format.yml
+++ b/.github/workflows/mpy_format.yml
@@ -6,6 +6,8 @@ on:
paths:
- '.github/workflows/*.yml'
- 'examples/**'
+ - 'mpy-cross/**'
+ - 'py/**'
- 'tests/**'
- 'tools/**'
@@ -15,10 +17,12 @@ concurrency:
jobs:
test:
- runs-on: ubuntu-20.04 # use 20.04 to get python2
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_mpy_format_setup
+ run: tools/ci.sh mpy_format_setup
- name: Test mpy-tool.py
- run: source tools/ci.sh && ci_mpy_format_test
+ run: tools/ci.sh mpy_format_test
+ - name: Test mpy-cross debug emitter
+ run: tools/ci.sh mpy_cross_debug_emitter
diff --git a/.github/workflows/ports.yml b/.github/workflows/ports.yml
index fb574ad9819..5da3f2be969 100644
--- a/.github/workflows/ports.yml
+++ b/.github/workflows/ports.yml
@@ -17,6 +17,6 @@ jobs:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Build ports download metadata
run: mkdir boards && ./tools/autobuild/build-downloads.py . ./boards
diff --git a/.github/workflows/ports_alif.yml b/.github/workflows/ports_alif.yml
new file mode 100644
index 00000000000..e7d1064c97a
--- /dev/null
+++ b/.github/workflows/ports_alif.yml
@@ -0,0 +1,33 @@
+name: alif port
+
+on:
+ push:
+ pull_request:
+ paths:
+ - '.github/workflows/*.yml'
+ - 'tools/**'
+ - 'py/**'
+ - 'extmod/**'
+ - 'shared/**'
+ - 'lib/**'
+ - 'drivers/**'
+ - 'ports/alif/**'
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ build_alif:
+ strategy:
+ fail-fast: false
+ matrix:
+ ci_func: # names are functions in ci.sh
+ - alif_ae3_build
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Install packages
+ run: tools/ci.sh alif_setup
+ - name: Build ci_${{matrix.ci_func }}
+ run: tools/ci.sh ${{ matrix.ci_func }}
diff --git a/.github/workflows/ports_cc3200.yml b/.github/workflows/ports_cc3200.yml
index b58bc24b58b..5f920efda78 100644
--- a/.github/workflows/ports_cc3200.yml
+++ b/.github/workflows/ports_cc3200.yml
@@ -21,8 +21,8 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_cc3200_setup
+ run: tools/ci.sh cc3200_setup
- name: Build
- run: source tools/ci.sh && ci_cc3200_build
+ run: tools/ci.sh cc3200_build
diff --git a/.github/workflows/ports_esp32.yml b/.github/workflows/ports_esp32.yml
index 6fc009d4fee..e1b57a24b7b 100644
--- a/.github/workflows/ports_esp32.yml
+++ b/.github/workflows/ports_esp32.yml
@@ -17,21 +17,47 @@ concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
+env:
+ # Oldest and newest supported ESP-IDF versions, should match ports/esp32/README.md
+ IDF_OLDEST_VER: &oldest "v5.3"
+ IDF_NEWEST_VER: &newest "v5.5.5"
+
jobs:
- build_idf402:
- runs-on: ubuntu-20.04
- steps:
- - uses: actions/checkout@v3
- - name: Install packages
- run: source tools/ci.sh && ci_esp32_idf402_setup
- - name: Build
- run: source tools/ci.sh && ci_esp32_build
-
- build_idf44:
- runs-on: ubuntu-20.04
+ build_idf:
+ strategy:
+ fail-fast: false
+ matrix:
+ idf_ver:
+ - *oldest
+ - *newest
+ ci_func: # names are functions in ci.sh
+ - esp32_build_cmod_spiram_d2wd
+ - esp32_build_s2_s3_c3
+ - esp32_build_c2_c5_c6
+ - esp32_build_h2_p4
+ exclude:
+ # Exclude some jobs on the oldest IDF version, to save resources
+ - idf_ver: *oldest
+ ci_func: esp32_build_c2_c5_c6
+ - idf_ver: *oldest
+ ci_func: esp32_build_h2_p4
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
- - name: Install packages
- run: source tools/ci.sh && ci_esp32_idf44_setup
- - name: Build
- run: source tools/ci.sh && ci_esp32_build
+ - uses: actions/checkout@v7
+
+ # Only the newest IDF version will build the ESP-IDF lockfiles correctly,
+ # so we need to disable MICROPY_MAINTAINER_BUILD on older versions.
+ - name: Disable extra checks for older ESP-IDF
+ id: check_newest_ver
+ if: ${{ matrix.idf_ver != env.IDF_NEWEST_VER }}
+ run: echo "MICROPY_MAINTAINER_BUILD=0" >> ${GITHUB_ENV}
+
+ - name: Setup ESP-IDF
+ uses: ./.github/actions/setup_esp32
+ with:
+ idf_ver: ${{ matrix.idf_ver }}
+ ccache_key: ${{ matrix.ci_func }}
+
+
+ - name: Build ci_${{matrix.ci_func }} on ESP-IDF ${{ matrix.idf_ver }}
+ run: tools/ci.sh ${{ matrix.ci_func }}
diff --git a/.github/workflows/ports_esp8266.yml b/.github/workflows/ports_esp8266.yml
index ba89d5e9529..156f3181bbc 100644
--- a/.github/workflows/ports_esp8266.yml
+++ b/.github/workflows/ports_esp8266.yml
@@ -21,8 +21,8 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_esp8266_setup && ci_esp8266_path >> $GITHUB_PATH
+ run: tools/ci.sh esp8266_setup && tools/ci.sh esp8266_path >> $GITHUB_PATH
- name: Build
- run: source tools/ci.sh && ci_esp8266_build
+ run: tools/ci.sh esp8266_build
diff --git a/.github/workflows/ports_mimxrt.yml b/.github/workflows/ports_mimxrt.yml
index d9156253418..4f171d11474 100644
--- a/.github/workflows/ports_mimxrt.yml
+++ b/.github/workflows/ports_mimxrt.yml
@@ -19,10 +19,15 @@ concurrency:
jobs:
build:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: 'micropython repo' # test build with space in path
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ with:
+ path: 'micropython repo'
- name: Install packages
- run: source tools/ci.sh && ci_mimxrt_setup
+ run: tools/ci.sh mimxrt_setup
- name: Build
- run: source tools/ci.sh && ci_mimxrt_build
+ run: tools/ci.sh mimxrt_build
diff --git a/.github/workflows/ports_nrf.yml b/.github/workflows/ports_nrf.yml
index 89211217800..53a5d6139d6 100644
--- a/.github/workflows/ports_nrf.yml
+++ b/.github/workflows/ports_nrf.yml
@@ -19,10 +19,10 @@ concurrency:
jobs:
build:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_nrf_setup
+ run: tools/ci.sh nrf_setup
- name: Build
- run: source tools/ci.sh && ci_nrf_build
+ run: tools/ci.sh nrf_build
diff --git a/.github/workflows/ports_powerpc.yml b/.github/workflows/ports_powerpc.yml
deleted file mode 100644
index a15c4da97fa..00000000000
--- a/.github/workflows/ports_powerpc.yml
+++ /dev/null
@@ -1,28 +0,0 @@
-name: powerpc port
-
-on:
- push:
- pull_request:
- paths:
- - '.github/workflows/*.yml'
- - 'tools/**'
- - 'py/**'
- - 'extmod/**'
- - 'shared/**'
- - 'lib/**'
- - 'drivers/**'
- - 'ports/powerpc/**'
-
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
-
-jobs:
- build:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v3
- - name: Install packages
- run: source tools/ci.sh && ci_powerpc_setup
- - name: Build
- run: source tools/ci.sh && ci_powerpc_build
diff --git a/.github/workflows/ports_psoc-edge.yml b/.github/workflows/ports_psoc-edge.yml
new file mode 100644
index 00000000000..f0f37e94939
--- /dev/null
+++ b/.github/workflows/ports_psoc-edge.yml
@@ -0,0 +1,28 @@
+name: psoc-edge port
+
+on:
+ push:
+ pull_request:
+ paths:
+ - '.github/workflows/*.yml'
+ - 'tools/**'
+ - 'py/**'
+ - 'extmod/**'
+ - 'shared/**'
+ - 'lib/**'
+ - 'drivers/**'
+ - 'ports/psoc-edge/**'
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ build_psoc_edge:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Install packages
+ run: tools/ci.sh psoc_edge_setup
+ - name: Build
+ run: tools/ci.sh psoc_edge_build
diff --git a/.github/workflows/ports_qemu-arm.yml b/.github/workflows/ports_qemu-arm.yml
deleted file mode 100644
index 93ec4da7670..00000000000
--- a/.github/workflows/ports_qemu-arm.yml
+++ /dev/null
@@ -1,32 +0,0 @@
-name: qemu-arm port
-
-on:
- push:
- pull_request:
- paths:
- - '.github/workflows/*.yml'
- - 'tools/**'
- - 'py/**'
- - 'extmod/**'
- - 'shared/**'
- - 'lib/**'
- - 'drivers/**'
- - 'ports/qemu-arm/**'
- - 'tests/**'
-
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
-
-jobs:
- build_and_test:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v3
- - name: Install packages
- run: source tools/ci.sh && ci_qemu_arm_setup
- - name: Build and run test suite
- run: source tools/ci.sh && ci_qemu_arm_build
- - name: Print failures
- if: failure()
- run: grep --before-context=100 --text "FAIL" ports/qemu-arm/build/console.out
diff --git a/.github/workflows/ports_qemu.yml b/.github/workflows/ports_qemu.yml
new file mode 100644
index 00000000000..f064930d832
--- /dev/null
+++ b/.github/workflows/ports_qemu.yml
@@ -0,0 +1,76 @@
+name: qemu port
+
+on:
+ push:
+ pull_request:
+ paths:
+ - '.github/workflows/*.yml'
+ - 'tools/**'
+ - 'py/**'
+ - 'extmod/**'
+ - 'shared/**'
+ - 'lib/**'
+ - 'drivers/**'
+ - 'ports/qemu/**'
+ - 'tests/**'
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ build_and_test_arm:
+ strategy:
+ fail-fast: false
+ matrix:
+ ci_func: # names are functions in ci.sh
+ - bigendian
+ - sabrelite
+ - thumb_softfp
+ - thumb_hardfp
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Install packages
+ run: tools/ci.sh qemu_setup_arm
+ - name: Build and run test suite ci_qemu_build_arm_${{ matrix.ci_func }}
+ run: tools/ci.sh qemu_build_arm_${{ matrix.ci_func }}
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ build_and_test_rv32:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Install packages
+ run: tools/ci.sh qemu_setup_rv32
+ - name: Build and run test suite
+ run: tools/ci.sh qemu_build_rv32
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ build_and_test_rv64:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Install packages
+ run: tools/ci.sh qemu_setup_rv64
+ - name: Build and run test suite
+ run: tools/ci.sh qemu_build_rv64
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ build_and_test_ppc64:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Install packages
+ run: tools/ci.sh qemu_setup_ppc64
+ - name: Build and run test suite
+ run: tools/ci.sh qemu_build_ppc64
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
diff --git a/.github/workflows/ports_renesas-ra.yml b/.github/workflows/ports_renesas-ra.yml
index 33e17a385a1..1e5bfb447e8 100644
--- a/.github/workflows/ports_renesas-ra.yml
+++ b/.github/workflows/ports_renesas-ra.yml
@@ -19,11 +19,11 @@ concurrency:
jobs:
build_renesas_ra_board:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_renesas_ra_setup
+ run: tools/ci.sh renesas_ra_setup
- name: Build
- run: source tools/ci.sh && ci_renesas_ra_board_build
+ run: tools/ci.sh renesas_ra_board_build
diff --git a/.github/workflows/ports_rp2.yml b/.github/workflows/ports_rp2.yml
index f042ff1151a..27d6c60a5c5 100644
--- a/.github/workflows/ports_rp2.yml
+++ b/.github/workflows/ports_rp2.yml
@@ -20,9 +20,14 @@ concurrency:
jobs:
build:
runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: 'micropython repo' # test build with space in path
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ with:
+ path: 'micropython repo'
- name: Install packages
- run: source tools/ci.sh && ci_rp2_setup
+ run: tools/ci.sh rp2_setup
- name: Build
- run: source tools/ci.sh && ci_rp2_build
+ run: tools/ci.sh rp2_build
diff --git a/.github/workflows/ports_samd.yml b/.github/workflows/ports_samd.yml
index 9833a2fae2e..04cddeb76de 100644
--- a/.github/workflows/ports_samd.yml
+++ b/.github/workflows/ports_samd.yml
@@ -21,8 +21,8 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_samd_setup
+ run: tools/ci.sh samd_setup
- name: Build
- run: source tools/ci.sh && ci_samd_build
+ run: tools/ci.sh samd_build
diff --git a/.github/workflows/ports_stm32.yml b/.github/workflows/ports_stm32.yml
index b278ea862ce..2099b8b7c03 100644
--- a/.github/workflows/ports_stm32.yml
+++ b/.github/workflows/ports_stm32.yml
@@ -18,20 +18,20 @@ concurrency:
cancel-in-progress: true
jobs:
- build_pyb:
- runs-on: ubuntu-20.04
+ build_stm32:
+ strategy:
+ fail-fast: false
+ matrix:
+ ci_func: # names are functions in ci.sh
+ - stm32_pyb_build
+ - stm32_build_cmod
+ - stm32_nucleo_build
+ - stm32_misc_build
+ runs-on: ubuntu-22.04
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_stm32_setup
- - name: Build
- run: source tools/ci.sh && ci_stm32_pyb_build
+ run: tools/ci.sh stm32_setup && tools/ci.sh stm32_path >> $GITHUB_PATH
+ - name: Build ci_${{matrix.ci_func }}
+ run: tools/ci.sh ${{ matrix.ci_func }}
- build_nucleo:
- runs-on: ubuntu-20.04
- steps:
- - uses: actions/checkout@v3
- - name: Install packages
- run: source tools/ci.sh && ci_stm32_setup
- - name: Build
- run: source tools/ci.sh && ci_stm32_nucleo_build
diff --git a/.github/workflows/ports_teensy.yml b/.github/workflows/ports_teensy.yml
deleted file mode 100644
index f1299603259..00000000000
--- a/.github/workflows/ports_teensy.yml
+++ /dev/null
@@ -1,28 +0,0 @@
-name: teensy port
-
-on:
- push:
- pull_request:
- paths:
- - '.github/workflows/*.yml'
- - 'tools/**'
- - 'py/**'
- - 'extmod/**'
- - 'shared/**'
- - 'lib/**'
- - 'drivers/**'
- - 'ports/teensy/**'
-
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
-
-jobs:
- build:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v3
- - name: Install packages
- run: source tools/ci.sh && ci_teensy_setup
- - name: Build
- run: source tools/ci.sh && ci_teensy_build
diff --git a/.github/workflows/ports_unix.yml b/.github/workflows/ports_unix.yml
index 87c58055b98..8231c1eb1ea 100644
--- a/.github/workflows/ports_unix.yml
+++ b/.github/workflows/ports_unix.yml
@@ -23,11 +23,11 @@ jobs:
minimal:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Build
- run: source tools/ci.sh && ci_unix_minimal_build
+ run: tools/ci.sh unix_minimal_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_minimal_run_tests
+ run: tools/ci.sh unix_minimal_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
@@ -35,9 +35,9 @@ jobs:
reproducible:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Build with reproducible date
- run: source tools/ci.sh && ci_unix_minimal_build
+ run: tools/ci.sh unix_minimal_build
env:
SOURCE_DATE_EPOCH: 1234567890
- name: Check reproducible build date
@@ -46,11 +46,47 @@ jobs:
standard:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Build
- run: source tools/ci.sh && ci_unix_standard_build
+ run: tools/ci.sh unix_standard_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_standard_run_tests
+ run: tools/ci.sh unix_standard_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ standard_v2:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Build
+ run: tools/ci.sh unix_standard_v2_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_standard_v2_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ standard_error_terse:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Build
+ run: tools/ci.sh unix_standard_error_terse_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_standard_error_terse_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ standard_error_none:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Build
+ run: tools/ci.sh unix_standard_error_none_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_standard_error_none_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
@@ -58,60 +94,115 @@ jobs:
coverage:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
- name: Install packages
- run: source tools/ci.sh && ci_unix_coverage_setup
+ run: tools/ci.sh unix_coverage_setup
- name: Build
- run: source tools/ci.sh && ci_unix_coverage_build
+ run: tools/ci.sh unix_coverage_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_coverage_run_tests
+ run: tools/ci.sh unix_coverage_run_tests
- name: Test merging .mpy files
- run: source tools/ci.sh && ci_unix_coverage_run_mpy_merge_tests
+ run: tools/ci.sh unix_coverage_run_mpy_merge_tests
- name: Build native mpy modules
- run: source tools/ci.sh && ci_native_mpy_modules_build
+ run: tools/ci.sh native_mpy_modules_build
- name: Test importing .mpy generated by mpy_ld.py
- run: source tools/ci.sh && ci_unix_coverage_run_native_mpy_tests
+ run: tools/ci.sh unix_coverage_run_native_mpy_tests
- name: Run gcov coverage analysis
run: |
(cd ports/unix && gcov -o build-coverage/py ../../py/*.c || true)
(cd ports/unix && gcov -o build-coverage/extmod ../../extmod/*.c || true)
- name: Upload coverage to Codecov
- uses: codecov/codecov-action@v3
+ uses: codecov/codecov-action@v7
with:
- fail_ci_if_error: true
+ # Only fail the job on error if a token is set, or we're running against upstream repo.
+ # This avoids the annoying situation of the job failing on every push to a fork (if no token is set).
+ fail_ci_if_error: ${{ secrets.CODECOV_TOKEN != '' || github.repository_owner == 'micropython' }}
verbose: true
+ flags: unix-coverage-64bit
+ name: unix-coverage-64bit
+ # note: when a fork opens a PR into MicroPython repo, the pull_request trigger can't access
+ # secrets so this token value will be empty (codecov will do a 'tokenless' upload).
+ token: ${{ secrets.CODECOV_TOKEN }}
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
coverage_32bit:
- runs-on: ubuntu-20.04 # use 20.04 to get libffi-dev:i386
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
- name: Install packages
- run: source tools/ci.sh && ci_unix_32bit_setup
+ run: tools/ci.sh unix_32bit_setup
- name: Build
- run: source tools/ci.sh && ci_unix_coverage_32bit_build
+ run: tools/ci.sh unix_coverage_32bit_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_coverage_32bit_run_tests
+ run: tools/ci.sh unix_coverage_32bit_run_tests
- name: Build native mpy modules
- run: source tools/ci.sh && ci_native_mpy_modules_32bit_build
+ run: tools/ci.sh native_mpy_modules_32bit_build
- name: Test importing .mpy generated by mpy_ld.py
- run: source tools/ci.sh && ci_unix_coverage_32bit_run_native_mpy_tests
+ run: tools/ci.sh unix_coverage_32bit_run_native_mpy_tests
+ - name: Run gcov coverage analysis
+ run: |
+ (cd ports/unix && gcov -o build-coverage/py ../../py/*.c || true)
+ (cd ports/unix && gcov -o build-coverage/extmod ../../extmod/*.c || true)
+ - name: Upload coverage to Codecov
+ uses: codecov/codecov-action@v7
+ with:
+ # See corresponding comment above.
+ fail_ci_if_error: ${{ secrets.CODECOV_TOKEN != '' || github.repository_owner == 'micropython' }}
+ verbose: true
+ flags: unix-coverage-32bit
+ name: unix-coverage-32bit
+ # See corresponding comment above.
+ token: ${{ secrets.CODECOV_TOKEN }}
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
nanbox:
- runs-on: ubuntu-20.04 # use 20.04 to get python2, and libffi-dev:i386
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
+ - name: Install packages
+ run: tools/ci.sh unix_32bit_setup
+ - name: Build
+ run: tools/ci.sh unix_nanbox_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_nanbox_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ longlong:
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
- name: Install packages
- run: source tools/ci.sh && ci_unix_32bit_setup
+ run: tools/ci.sh unix_32bit_setup
- name: Build
- run: source tools/ci.sh && ci_unix_nanbox_build
+ run: tools/ci.sh unix_longlong_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_nanbox_run_tests
+ run: tools/ci.sh unix_longlong_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
@@ -119,78 +210,106 @@ jobs:
float:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Build
- run: source tools/ci.sh && ci_unix_float_build
+ run: tools/ci.sh unix_float_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_float_run_tests
+ run: tools/ci.sh unix_float_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ gil_enabled:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - name: Build
+ run: tools/ci.sh unix_gil_enabled_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_gil_enabled_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
stackless_clang:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_unix_clang_setup
+ run: tools/ci.sh unix_clang_setup
- name: Build
- run: source tools/ci.sh && ci_unix_stackless_clang_build
+ run: tools/ci.sh unix_stackless_clang_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_stackless_clang_run_tests
+ run: tools/ci.sh unix_stackless_clang_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
float_clang:
- runs-on: ubuntu-20.04
+ runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_unix_clang_setup
+ run: tools/ci.sh unix_clang_setup
- name: Build
- run: source tools/ci.sh && ci_unix_float_clang_build
+ run: tools/ci.sh unix_float_clang_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_float_clang_run_tests
+ run: tools/ci.sh unix_float_clang_run_tests
+ - name: Build native mpy modules
+ run: tools/ci.sh native_mpy_modules_clang_build
+ - name: Test importing .mpy generated by mpy_ld.py
+ run: tools/ci.sh unix_standard_run_native_mpy_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
- settrace:
+ settrace_stackless:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
- name: Build
- run: source tools/ci.sh && ci_unix_settrace_build
+ run: tools/ci.sh unix_settrace_stackless_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_settrace_run_tests
+ run: tools/ci.sh unix_settrace_stackless_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
- settrace_stackless:
+ repr_b:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
+ - name: Install packages
+ run: tools/ci.sh unix_32bit_setup
- name: Build
- run: source tools/ci.sh && ci_unix_settrace_stackless_build
+ run: tools/ci.sh unix_repr_b_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_settrace_stackless_run_tests
+ run: tools/ci.sh unix_repr_b_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
macos:
- runs-on: macos-11.0
+ runs-on: macos-26
steps:
- - uses: actions/checkout@v3
- - uses: actions/setup-python@v4
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
with:
python-version: '3.8'
- name: Build
- run: source tools/ci.sh && ci_unix_macos_build
+ run: tools/ci.sh unix_macos_build
- name: Run tests
- run: source tools/ci.sh && ci_unix_macos_run_tests
+ run: tools/ci.sh unix_macos_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
@@ -198,13 +317,18 @@ jobs:
qemu_mips:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
- name: Install packages
- run: source tools/ci.sh && ci_unix_qemu_mips_setup
+ run: tools/ci.sh unix_qemu_mips_setup
- name: Build
- run: source tools/ci.sh && ci_unix_qemu_mips_build
+ run: tools/ci.sh unix_qemu_mips_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_qemu_mips_run_tests
+ run: tools/ci.sh unix_qemu_mips_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
@@ -212,13 +336,125 @@ jobs:
qemu_arm:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
+ - name: Install packages
+ run: tools/ci.sh unix_qemu_arm_setup
+ - name: Build
+ run: tools/ci.sh unix_qemu_arm_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_qemu_arm_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ qemu_riscv64:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
+ - name: Install packages
+ run: tools/ci.sh unix_qemu_riscv64_setup
+ - name: Build
+ run: tools/ci.sh unix_qemu_riscv64_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_qemu_riscv64_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ qemu_loong64:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
+ - name: Install packages
+ run: tools/ci.sh unix_qemu_loong64_setup
+ - name: Build
+ run: tools/ci.sh unix_qemu_loong64_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_qemu_loong64_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ qemu_x64:
+ runs-on: ubuntu-24.04-arm
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
+ - name: Install packages
+ run: tools/ci.sh unix_qemu_x64_setup
+ - name: Build
+ run: tools/ci.sh unix_qemu_x64_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_qemu_x64_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ sanitize_address:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
+ - name: Install packages
+ run: tools/ci.sh unix_coverage_setup
+ - name: Build
+ run: tools/ci.sh unix_sanitize_address_build
+ - name: Run main test suite
+ run: tools/ci.sh unix_sanitize_address_run_tests
+ - name: Test merging .mpy files
+ run: tools/ci.sh unix_coverage_run_mpy_merge_tests
+ - name: Build native mpy modules
+ run: tools/ci.sh native_mpy_modules_build
+ - name: Test importing .mpy generated by mpy_ld.py
+ run: tools/ci.sh unix_coverage_run_native_mpy_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
+
+ sanitize_undefined:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ # Python 3.12 is the default for ubuntu-24.04, but that has compatibility issues with settrace tests.
+ # Can remove this step when ubuntu-latest uses a more recent Python 3.x as the default.
+ with:
+ python-version: '3.11'
- name: Install packages
- run: source tools/ci.sh && ci_unix_qemu_arm_setup
+ run: tools/ci.sh unix_coverage_setup
- name: Build
- run: source tools/ci.sh && ci_unix_qemu_arm_build
+ run: tools/ci.sh unix_sanitize_undefined_build
- name: Run main test suite
- run: source tools/ci.sh && ci_unix_qemu_arm_run_tests
+ run: tools/ci.sh unix_sanitize_undefined_run_tests
+ - name: Test merging .mpy files
+ run: tools/ci.sh unix_coverage_run_mpy_merge_tests
+ - name: Build native mpy modules
+ run: tools/ci.sh native_mpy_modules_build
+ - name: Test importing .mpy generated by mpy_ld.py
+ run: tools/ci.sh unix_coverage_run_native_mpy_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
diff --git a/.github/workflows/ports_webassembly.yml b/.github/workflows/ports_webassembly.yml
index 2e0865662f0..ac2050129ef 100644
--- a/.github/workflows/ports_webassembly.yml
+++ b/.github/workflows/ports_webassembly.yml
@@ -11,6 +11,7 @@ on:
- 'shared/**'
- 'lib/**'
- 'ports/webassembly/**'
+ - 'tests/**'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
@@ -20,13 +21,13 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_webassembly_setup
+ run: tools/ci.sh webassembly_setup
- name: Build
- run: source tools/ci.sh && ci_webassembly_build
+ run: tools/ci.sh webassembly_build
- name: Run tests
- run: source tools/ci.sh && ci_webassembly_run_tests
+ run: tools/ci.sh webassembly_run_tests
- name: Print failures
if: failure()
run: tests/run-tests.py --print-failures
diff --git a/.github/workflows/ports_windows.yml b/.github/workflows/ports_windows.yml
index b31718c5914..af830ca194e 100644
--- a/.github/workflows/ports_windows.yml
+++ b/.github/workflows/ports_windows.yml
@@ -18,11 +18,130 @@ concurrency:
cancel-in-progress: true
jobs:
- build:
+ build-vs:
+ strategy:
+ fail-fast: false
+ matrix:
+ platform: [x86, x64]
+ configuration: [Debug, Release]
+ variant: [dev, standard]
+ visualstudio: ['2019', '2022']
+ include:
+ - visualstudio: '2019'
+ # The v142 toolset (VS 2019 compiler) is pre-installed on
+ # windows-2022 as a component of VS 2022. Use VS 2022's
+ # MSBuild and select the v142 toolset via PlatformToolset.
+ vs_version: '[17, 18)'
+ platform_toolset: v142
+ - visualstudio: '2022'
+ vs_version: '[17, 18)'
+ platform_toolset: v143
+ # trim down the number of jobs in the matrix
+ exclude:
+ - variant: standard
+ configuration: Debug
+ - visualstudio: '2019'
+ configuration: Debug
+ runs-on: windows-2022
+ env:
+ CI_BUILD_CONFIGURATION: ${{ matrix.configuration }}
+ steps:
+ - name: Install Python 3.11
+ # As of 20260112 the default Python version in Windows image is 3.12, which breaks settrace tests
+ # Use 3.11 for now
+ uses: actions/setup-python@v7
+ with:
+ python-version: '3.11'
+ - uses: microsoft/setup-msbuild@v3
+ with:
+ vs-version: ${{ matrix.vs_version }}
+ - uses: actions/checkout@v7
+ - name: Build mpy-cross.exe
+ run: msbuild mpy-cross\mpy-cross.vcxproj -maxcpucount -property:Configuration=${{ matrix.configuration }} -property:Platform=${{ matrix.platform }} -property:PlatformToolset=${{ matrix.platform_toolset }}
+ - name: Update submodules
+ run: git submodule update --init lib/micropython-lib
+ - name: Build micropython.exe
+ run: msbuild ports\windows\micropython.vcxproj -maxcpucount -property:Configuration=${{ matrix.configuration }} -property:Platform=${{ matrix.platform }} -property:PyVariant=${{ matrix.variant }} -property:PlatformToolset=${{ matrix.platform_toolset }}
+ - name: Get micropython.exe path
+ id: get_path
+ run: |
+ $exePath="$(msbuild ports\windows\micropython.vcxproj -nologo -v:m -t:ShowTargetPath -property:Configuration=${{ matrix.configuration }} -property:Platform=${{ matrix.platform }} -property:PyVariant=${{ matrix.variant }} -property:PlatformToolset=${{ matrix.platform_toolset }})"
+ echo ("micropython=" + $exePath.Trim()) >> $env:GITHUB_OUTPUT
+ - name: Run tests
+ id: test
+ env:
+ MICROPY_MICROPYTHON: ${{ steps.get_path.outputs.micropython }}
+ working-directory: tests
+ run: python run-tests.py
+ - name: Print failures
+ if: failure() && steps.test.conclusion == 'failure'
+ working-directory: tests
+ run: python run-tests.py --print-failures
+ - name: Run mpy tests
+ id: test_mpy
+ env:
+ MICROPY_MICROPYTHON: ${{ steps.get_path.outputs.micropython }}
+ working-directory: tests
+ run: python run-tests.py --via-mpy -d basics float micropython
+ - name: Print mpy failures
+ if: failure() && steps.test_mpy.conclusion == 'failure'
+ working-directory: tests
+ run: python run-tests.py --print-failures
+
+ build-mingw:
+ strategy:
+ fail-fast: false
+ matrix:
+ variant: [dev, standard]
+ sys: [mingw32, mingw64]
+ include:
+ - sys: mingw32
+ env: i686
+ - sys: mingw64
+ env: x86_64
+ runs-on: windows-latest
+ env:
+ CHERE_INVOKING: enabled_from_arguments
+ defaults:
+ run:
+ shell: msys2 {0}
+ steps:
+ - uses: actions/setup-python@v7
+ # note: can go back to installing mingw-w64-${{ matrix.env }}-python after
+ # MSYS2 updates to Python >3.12 (due to settrace compatibility issue)
+ with:
+ python-version: '3.11'
+ - uses: msys2/setup-msys2@v2
+ with:
+ msystem: ${{ matrix.sys }}
+ update: true
+ install: >-
+ make
+ mingw-w64-${{ matrix.env }}-gcc
+ pkg-config
+ git
+ diffutils
+ path-type: inherit # Remove when setup-python is removed
+ - uses: actions/checkout@v7
+ - name: Build mpy-cross.exe
+ run: make -C mpy-cross -j2
+ - name: Update submodules
+ run: make -C ports/windows VARIANT=${{ matrix.variant }} submodules
+ - name: Build micropython.exe
+ run: make -C ports/windows -j2 VARIANT=${{ matrix.variant }}
+ - name: Run tests
+ id: test
+ run: make -C ports/windows test_full VARIANT=${{ matrix.variant }}
+ - name: Print failures
+ if: failure() && steps.test.conclusion == 'failure'
+ working-directory: tests
+ run: python run-tests.py --print-failures
+
+ cross-build-on-linux:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v7
- name: Install packages
- run: source tools/ci.sh && ci_windows_setup
+ run: tools/ci.sh windows_setup
- name: Build
- run: source tools/ci.sh && ci_windows_build
+ run: tools/ci.sh windows_build
diff --git a/.github/workflows/ports_zephyr.yml b/.github/workflows/ports_zephyr.yml
index f64401b316a..8ed9845927f 100644
--- a/.github/workflows/ports_zephyr.yml
+++ b/.github/workflows/ports_zephyr.yml
@@ -11,6 +11,7 @@ on:
- 'shared/**'
- 'lib/**'
- 'ports/zephyr/**'
+ - 'tests/**'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
@@ -20,10 +21,44 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - 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@v7
+ - id: versions
+ name: Read Zephyr version
+ run: source tools/ci.sh && echo "ZEPHYR=$ZEPHYR_VERSION" | tee "$GITHUB_OUTPUT"
+ - name: Cached Zephyr Workspace
+ id: cache_workspace
+ uses: actions/cache@v6
+ with:
+ # note that the Zephyr CI docker image is 15GB. At time of writing
+ # GitHub caches are limited to 10GB total for a project. So we only
+ # cache the "workspace"
+ path: ./zephyrproject
+ key: zephyr-workspace-${{ steps.versions.outputs.ZEPHYR }}
+ - name: ccache
+ uses: hendrikmuhs/ccache-action@v1.2
+ with:
+ key: zephyr
- name: Install packages
- run: source tools/ci.sh && ci_zephyr_setup
+ run: tools/ci.sh zephyr_setup
- name: Install Zephyr
- run: source tools/ci.sh && ci_zephyr_install
+ if: steps.cache_workspace.outputs.cache-hit != 'true'
+ run: tools/ci.sh zephyr_install
- name: Build
- run: source tools/ci.sh && ci_zephyr_build
+ run: tools/ci.sh zephyr_build
+ - name: Run main test suite
+ run: tools/ci.sh zephyr_run_tests
+ - name: Print failures
+ if: failure()
+ run: tests/run-tests.py --print-failures
diff --git a/.github/workflows/ruff.yml b/.github/workflows/ruff.yml
index b8e43dc78f1..a5a6fc7e26c 100644
--- a/.github/workflows/ruff.yml
+++ b/.github/workflows/ruff.yml
@@ -1,10 +1,13 @@
-# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-name: Python code lint with ruff
+name: Python code lint and formatting with ruff
+
on: [push, pull_request]
+
jobs:
ruff:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
- - run: pip install --user ruff
- - run: ruff --format=github .
+ - uses: actions/checkout@v7
+ # ruff version should be kept in sync with .pre-commit-config.yaml & also micropython-lib
+ - run: pipx install ruff==0.11.6
+ - run: ruff check --output-format=github .
+ - run: ruff format --diff .
diff --git a/.gitignore b/.gitignore
index 2d20cb18970..b17423ca050 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,9 +10,11 @@
build/
build-*/
docs/genrst/
+.mpy_ld_cache-*/
-# Test failure outputs
+# Test failure outputs and intermediate artefacts
tests/results/*
+tests/ports/unix/ffi_lib.so
# Python cache files
__pycache__/
@@ -23,3 +25,11 @@ user.props
# MacOS desktop metadata files
.DS_Store
+
+# Created by ci.sh zephyr targets
+/.ccache
+/zephyrproject
+
+# Created by ci.sh esp8266 targets
+/xtensa-lx106-elf-standalone.tar.gz
+/xtensa-lx106-elf/
diff --git a/.gitmodules b/.gitmodules
index 992fec3d183..425bf7fd333 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -3,13 +3,13 @@
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/lwip"]
path = lib/lwip
url = https://github.com/lwip-tcpip/lwip.git
[submodule "lib/berkeley-db-1.xx"]
path = lib/berkeley-db-1.xx
- url = https://github.com/pfalcon/berkeley-db-1.xx
+ url = https://github.com/micropython/berkeley-db-1.xx
[submodule "lib/stm32lib"]
path = lib/stm32lib
url = https://github.com/micropython/stm32lib
@@ -26,7 +26,7 @@
branch = circuitpython
[submodule "lib/tinyusb"]
path = lib/tinyusb
- url = https://github.com/hathach/tinyusb
+ url = https://github.com/micropython/tinyusb.git
[submodule "lib/mynewt-nimble"]
path = lib/mynewt-nimble
url = https://github.com/micropython/mynewt-nimble.git
@@ -35,7 +35,7 @@
url = https://github.com/bluekitchen/btstack.git
[submodule "lib/nxp_driver"]
path = lib/nxp_driver
- url = https://github.com/hathach/nxp_driver.git
+ url = https://github.com/micropython/nxp_driver.git
[submodule "lib/libhydrogen"]
path = lib/libhydrogen
url = https://github.com/jedisct1/libhydrogen.git
@@ -56,3 +56,51 @@
[submodule "lib/micropython-lib"]
path = lib/micropython-lib
url = https://github.com/micropython/micropython-lib.git
+[submodule "lib/protobuf-c"]
+ path = lib/protobuf-c
+ url = https://github.com/protobuf-c/protobuf-c.git
+[submodule "lib/open-amp"]
+ path = lib/open-amp
+ url = https://github.com/OpenAMP/open-amp.git
+[submodule "lib/libmetal"]
+ path = lib/libmetal
+ url = https://github.com/OpenAMP/libmetal.git
+[submodule "lib/arduino-lib"]
+ path = lib/arduino-lib
+ url = https://github.com/arduino/arduino-lib-mpy.git
+[submodule "lib/alif_ensemble-cmsis-dfp"]
+ path = lib/alif_ensemble-cmsis-dfp
+ url = https://github.com/alifsemi/alif_ensemble-cmsis-dfp.git
+[submodule "lib/alif-security-toolkit"]
+ path = lib/alif-security-toolkit
+ url = https://github.com/micropython/alif-security-toolkit.git
+[submodule "lib/CMSIS_5"]
+ path = lib/CMSIS_5
+ url = https://github.com/ARM-software/CMSIS_5.git
+[submodule "lib/CMSIS_6"]
+ path = lib/CMSIS_6
+ url = https://github.com/ARM-software/CMSIS_6.git
+[submodule "lib/psoc-edge/TARGET_KIT_PSE84_AI"]
+ path = lib/psoc-edge/TARGET_KIT_PSE84_AI
+ url = https://github.com/Infineon/TARGET_KIT_PSE84_AI.git
+[submodule "lib/psoc-edge/core-lib"]
+ path = lib/psoc-edge/core-lib
+ url = https://github.com/Infineon/core-lib.git
+[submodule "lib/psoc-edge/mtb-dsl-pse8xxgp"]
+ path = lib/psoc-edge/mtb-dsl-pse8xxgp
+ url = https://github.com/Infineon/mtb-dsl-pse8xxgp.git
+[submodule "lib/psoc-edge/mtb-srf"]
+ path = lib/psoc-edge/mtb-srf
+ url = https://github.com/Infineon/mtb-srf.git
+[submodule "lib/psoc-edge/se-rt-services-utils"]
+ path = lib/psoc-edge/se-rt-services-utils
+ url = https://github.com/Infineon/se-rt-services-utils.git
+[submodule "lib/psoc-edge/serial-memory"]
+ path = lib/psoc-edge/serial-memory
+ url = https://github.com/Infineon/serial-memory.git
+[submodule "lib/psoc-edge/mtb-ipc"]
+ path = lib/psoc-edge/mtb-ipc
+ url = https://github.com/Infineon/mtb-ipc.git
+[submodule "lib/psoc-edge/async-transfer"]
+ path = lib/psoc-edge/async-transfer
+ url = https://github.com/Infineon/async-transfer.git
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e9815a4b2e6..ad4136c59fc 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -2,9 +2,11 @@ repos:
- repo: local
hooks:
- id: codeformat
- name: MicroPython codeformat.py for changed files
- entry: tools/codeformat.py -v -f
+ name: MicroPython codeformat.py for changed C files
+ entry: tools/codeformat.py -v -c -f
language: python
+ additional_dependencies:
+ - micropython-uncrustify==1.0.0.post1
- id: verifygitlog
name: MicroPython git commit message format checker
entry: tools/verifygitlog.py --check-file --ignore-rebase
@@ -12,6 +14,16 @@ repos:
verbose: true
stages: [commit-msg]
- repo: https://github.com/charliermarsh/ruff-pre-commit
- rev: v0.0.265
+ # Version should be kept in sync with .github/workflows/ruff.yml & also micropython-lib
+ rev: v0.11.6
hooks:
- id: ruff
+ - id: ruff-format
+ - repo: https://github.com/codespell-project/codespell
+ # Version should be kept in sync with .github/workflows/codespell.yml
+ rev: v2.4.1
+ hooks:
+ - id: codespell
+ name: Spellcheck for changed files (codespell)
+ additional_dependencies:
+ - tomli
diff --git a/CODECONVENTIONS.md b/CODECONVENTIONS.md
index d44b382b25e..0f40156b878 100644
--- a/CODECONVENTIONS.md
+++ b/CODECONVENTIONS.md
@@ -53,13 +53,16 @@ are then certifying and signing off against the following:
Code auto-formatting
====================
-Both C and Python code are auto-formatted using the `tools/codeformat.py`
-script. This uses [uncrustify](https://github.com/uncrustify/uncrustify) to
-format C code and [black](https://github.com/psf/black) to format Python code.
-After making changes, and before committing, run this tool to reformat your
-changes to the correct style. Without arguments this tool will reformat all
-source code (and may take some time to run). Otherwise pass as arguments to
-the tool the files that changed and it will only reformat those.
+Both C and Python code formatting are controlled for consistency across the
+MicroPython codebase. C code is formatted using the `tools/codeformat.py`
+script which uses [uncrustify](https://github.com/uncrustify/uncrustify).
+Python code is linted and formatted using
+[ruff & ruff format](https://github.com/astral-sh/ruff).
+After making changes, and before committing, run `tools/codeformat.py` to
+reformat your C code and `ruff format` for any Python code. Without
+arguments this tool will reformat all source code (and may take some time
+to run). Otherwise pass as arguments to the tool the files that changed,
+and it will only reformat those.
uncrustify
==========
@@ -69,36 +72,44 @@ be used for MicroPython. Different uncrustify versions produce slightly
different formatting, and the configuration file formats are often
incompatible. v0.73 or newer *will not work*.
-Depending on your operating system version, it may be possible to install a pre-compiled
-uncrustify version:
+Depending on your operating system version, it may be possible to install a
+compatible pre-compiled uncrustify version. Otherwise, a compatible version is
+available via the PyPI package archive:
-Ubuntu, Debian
---------------
-
-Ubuntu versions 21.10 or 22.04LTS, and Debian versions bullseye or bookworm all
-include v0.72 so can be installed directly:
+Pip
+---
```
-$ apt install uncrustify
+pip install micropython-uncrustify
```
-Arch Linux
-----------
-
-The current Arch uncrustify version is too new. There is an [old Arch package
-for v0.72](https://archive.archlinux.org/packages/u/uncrustify/) that can be
-installed from the Arch Linux archive ([more
-information](https://wiki.archlinux.org/title/Downgrading_packages#Arch_Linux_Archive)). Use
-the [IgnorePkg feature](https://wiki.archlinux.org/title/Pacman#Skip_package_from_being_upgraded)
-to prevent it re-updating.
+This installs a native compiled uncrustify binary as a Python executable, so it
+can be installed into a virtualenv.
-Brew
+Pipx
----
-This command may work, please raise a new Issue if it doesn't:
+It's also possible to install via [pipx](https://pipx.pypa.io/) if not using a
+virtualenv:
```
-curl -L https://github.com/Homebrew/homebrew-core/raw/2b07d8192623365078a8b855a164ebcdf81494a6/Formula/uncrustify.rb > uncrustify.rb && brew install uncrustify.rb && rm uncrustify.rb
+pipx install micropython-uncrustify
+```
+
+Code spell checking
+===================
+
+Code spell checking is done using [codespell](https://github.com/codespell-project/codespell#codespell)
+and runs in a GitHub action in CI. Codespell is configured via `pyproject.toml`
+to avoid false positives. It is recommended run codespell before submitting a
+PR. To simplify this, codespell is configured as a pre-commit hook and will be
+installed if you run `pre-commit install` (see below).
+
+If you want to install and run codespell manually, you can do so by running:
+
+```
+$ pip install codespell tomli
+$ codespell
```
Automatic Pre-Commit Hooks
@@ -108,6 +119,9 @@ To have code formatting and commit message conventions automatically checked,
a configuration file is provided for the [pre-commit](https://pre-commit.com/)
tool.
+Pre-commit will automatically install the correct version of dependencies
+such as codespell, uncrustify, etc.
+
First install `pre-commit`, either from your system package manager or via
`pip`. When installing `pre-commit` via pip, it is recommended to use a
virtual environment. Other sources, such as Brew are also available, see
@@ -120,10 +134,6 @@ $ brew install pre-commit # Brew
$ pip install pre-commit # PyPI
```
-Next, install [uncrustify (see above)](#uncrustify). Other dependencies are managed by
-pre-commit automatically, but uncrustify needs to be installed and available on
-the PATH.
-
Then, inside the MicroPython repository, register the git hooks for pre-commit
by running:
@@ -151,12 +161,22 @@ Tips:
* To ignore the pre-commit message format check temporarily, start the commit
message subject line with "WIP" (for "Work In Progress").
+Running pre-commit manually
+===========================
+
+Once pre-commit is installed as per the previous section it can be manually
+run against the MicroPython python codebase to update file formatting on
+demand, with either:
+* `pre-commit run --all-files` to fix all files in the MicroPython codebase
+* `pre-commit run --file ./path/to/my/file` to fix just one file
+* `pre-commit run --file ./path/to/my/folder/*` to fix just one folder
+
Python code conventions
=======================
Python code follows [PEP 8](https://legacy.python.org/dev/peps/pep-0008/) and
-is auto-formatted using [black](https://github.com/psf/black) with a line-length
-of 99 characters.
+is auto-formatted using [ruff format](https://docs.astral.sh/ruff/formatter)
+with a line-length of 99 characters.
Naming conventions:
- Module names are short and all lowercase; eg pyb, stm.
@@ -177,14 +197,21 @@ adhere to the existing style and use `tools/codeformat.py` to check any changes.
The main conventions, and things not enforceable via the auto-formatter, are
described below.
-White space:
+As the MicroPython code base is over ten years old, not every source file
+conforms fully to these conventions. If making small changes to existing code,
+then it's usually acceptable to follow the existing code's style. New code or
+major changes should follow the conventions described here.
+
+## White space
+
- Expand tabs to 4 spaces.
- Don't leave trailing whitespace at the end of a line.
- For control blocks (if, for, while), put 1 space between the
keyword and the opening parenthesis.
- Put 1 space after a comma, and 1 space around operators.
-Braces:
+## Braces
+
- Use braces for all blocks, even no-line and single-line pieces of
code.
- Put opening braces on the end of the line it belongs to, not on
@@ -192,18 +219,43 @@ Braces:
- For else-statements, put the else on the same line as the previous
closing brace.
-Header files:
+## Header files
+
- Header files should be protected from multiple inclusion with #if
directives. See an existing header for naming convention.
-Names:
+## Names
+
- Use underscore_case, not camelCase for all names.
- Use CAPS_WITH_UNDERSCORE for enums and macros.
- When defining a type use underscore_case and put '_t' after it.
-Integer types: MicroPython runs on 16, 32, and 64 bit machines, so it's
-important to use the correctly-sized (and signed) integer types. The
-general guidelines are:
+### Public names (declared in headers)
+
+- MicroPython-specific names (especially any declared in `py/` and `extmod/`
+ directories) should generally start with `mp_` or `MP_`.
+- Functions and variables declared in a header should generally share a longer
+ common prefix. Usually the prefix matches the file name (i.e. items defined in
+ `py/obj.c` are declared in `py/obj.h` and should be prefixed `mp_obj_`). There
+ are exceptions, for example where one header file contains declarations
+ implemented in multiple source files for expediency.
+
+### Private names (specific to a single .c file)
+
+- For static functions and variables exposed to Python (i.e. a static C function
+ that is wrapped in `MP_DEFINE_CONST_FUN_...` and attached to a module), use
+ the file-level shared common prefix, i.e. name them as if the function or
+ variable was not static.
+- Other static definitions in source files (i.e. functions or variables defined
+ in a .c file that are only used within that .c file) don't need any prefix
+ (specifically: no `s_` or `_` prefix, and generally avoid adding the
+ file-level common prefix).
+
+## Integer types
+
+MicroPython runs on 16, 32, and 64 bit machines, so it's important to use the
+correctly-sized (and signed) integer types. The general guidelines are:
+
- For most cases use mp_int_t for signed and mp_uint_t for unsigned
integer values. These are guaranteed to be machine-word sized and
therefore big enough to hold the value from a MicroPython small-int
@@ -212,11 +264,13 @@ general guidelines are:
- You can use int/uint, but remember that they may be 16-bits wide.
- If in doubt, use mp_int_t/mp_uint_t.
-Comments:
+## Comments
+
- Be concise and only write comments for things that are not obvious.
- Use `// ` prefix, NOT `/* ... */`. No extra fluff.
-Memory allocation:
+## Memory allocation
+
- Use m_new, m_renew, m_del (and friends) to allocate and free heap memory.
These macros are defined in py/misc.h.
diff --git a/LICENSE b/LICENSE
index 31eb9813f2d..b9078c7c71c 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
The MIT License (MIT)
-Copyright (c) 2013-2023 Damien P. George
+Copyright (c) 2013-2026 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
@@ -37,6 +37,8 @@ used during the build process and is not part of the compiled source code.
/drivers
/cc3100 (BSD-3-clause)
/lib
+ /CMSIS_5 (Apache-2.0)
+ /CMSIS_6 (Apache-2.0)
/asf4 (Apache-2.0)
/axtls (BSD-3-clause)
/config
@@ -45,19 +47,19 @@ used during the build process and is not part of the compiled source code.
/Rules.mak (GPL-2.0)
/berkeley-db-1xx (BSD-4-clause)
/btstack (See btstack/LICENSE)
- /cmsis (BSD-3-clause)
/crypto-algorithms (NONE)
/libhydrogen (ISC)
+ /libmetal (BSD-3-clause)
/littlefs (BSD-3-clause)
/lwip (BSD-3-clause)
/mynewt-nimble (Apache-2.0)
/nrfx (BSD-3-clause)
/nxp_driver (BSD-3-Clause)
/oofatfs (BSD-1-clause)
+ /open-amp (BSD-3-clause)
/pico-sdk (BSD-3-clause)
/re15 (BSD-3-clause)
/stm32lib (BSD-3-clause)
- /tinytest (BSD-3-clause)
/tinyusb (MIT)
/uzlib (Zlib)
/wiznet5k (MIT)
@@ -67,6 +69,11 @@ used during the build process and is not part of the compiled source code.
/hal (BSD-3-clause)
/simplelink (BSD-3-clause)
/FreeRTOS (GPL-2.0 with FreeRTOS exception)
+ /esp32
+ /ppp_set_auth.* (Apache-2.0)
+ /rp2
+ /mutex_extra.c (BSD-3-clause)
+ /clocks_extra.c (BSD-3-clause)
/stm32
/usbd*.c (MCD-ST Liberty SW License Agreement V2)
/stm32_it.* (MIT + BSD-3-clause)
@@ -76,8 +83,6 @@ used during the build process and is not part of the compiled source code.
/*/stm32*.h (BSD-3-clause)
/usbdev (MCD-ST Liberty SW License Agreement V2)
/usbhost (MCD-ST Liberty SW License Agreement V2)
- /teensy
- /core (PJRC.COM)
/zephyr
/src (Apache-2.0)
/tools
diff --git a/README.md b/README.md
index 6482899b251..51bd471e428 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-[](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [](https://codecov.io/gh/micropython/micropython)
+[](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [](https://docs.micropython.org/) [](https://codecov.io/gh/micropython/micropython)
The MicroPython project
=======================
@@ -6,20 +6,17 @@ The MicroPython project
-This is the MicroPython project, which aims to put an implementation
-of Python 3.x on microcontrollers and small embedded systems.
+This is the MicroPython project, an implementation of Python 3.x for
+microcontrollers, embedded systems and other constrained platforms.
You can find the official website at [micropython.org](http://www.micropython.org).
-WARNING: this project is in beta stage and is subject to changes of the
-code-base, including project-wide name changes and API changes.
-
MicroPython implements the entire Python 3.4 syntax (including exceptions,
`with`, `yield from`, etc., and additionally `async`/`await` keywords from
Python 3.5 and some select features from later versions). The following core
datatypes are provided: `str`(including basic Unicode support), `bytes`,
`bytearray`, `tuple`, `list`, `dict`, `set`, `frozenset`, `array.array`,
`collections.namedtuple`, classes and instances. Builtin modules include
-`os`, `sys`, `time`, `re`, and `struct`, etc. Select ports have support for
+`os`, `sys`, `time`, `re`, and `struct`, etc. Some ports have support for
`_thread` module (multithreading), `socket` and `ssl` for networking, and
`asyncio`. Note that only a subset of Python 3 functionality is implemented
for the data types and modules.
@@ -35,8 +32,8 @@ DAC, PWM, SPI, I2C, CAN, Bluetooth, and USB.
Getting started
---------------
-See the [online documentation](https://docs.micropython.org/) for API
-references and information about using MicroPython and information about how
+See the [online documentation](https://docs.micropython.org/) for the API
+reference and information about using MicroPython and information about how
it is implemented.
We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
@@ -53,6 +50,44 @@ the officially supported board from the
see the [schematics and pinouts](http://github.com/micropython/pyboard) and
[documentation](https://docs.micropython.org/en/latest/pyboard/quickref.html).
+MicroPython design values
+-------------------------
+
+"Perfection is achieved, not when there is nothing more to add, but when there
+is nothing left to take away." ―- Antoine de Saint-Exupéry.
+
+For its design and implementation, MicroPython aims to follow a set of values.
+Although not a strict set of rules, these values and principles serve as a
+useful guide for new and seasoned contributors, as well as maintainers.
+
+MicroPython is at heart a combination of "Micro" and "Python": it's about
+resource constrained systems running the Python programming language. Both of
+these concepts balance off against each other in all parts of MicroPython's
+design and implementation.
+
+The key concepts that focus the development of MicroPython are:
+- Minimalism: do lots with little.
+- Efficiency: engineering, build, execution, storage, power consumption.
+- Consistency: the whole system feels like it was designed at once.
+
+When using MicroPython, the Python language is used as the human interface to a
+system, giving fine control over the entities attached to that system.
+In a hardware setting, MicroPython aims to give the user a bare-metal feeling:
+one should feel like they have complete control over the system, with very
+little between the programmer and the physical world.
+
+MicroPython recognises that systems can be very complex. The existing Python
+libraries in combination with the MicroPython-specific libraries provide a
+user-friendly way to harness the complexity of a system.
+
+Python language compatibility is very important to MicroPython, and at first
+glance MicroPython should look just like regular Python. In the first instance,
+most Python scripts should run unchanged on MicroPython, even on devices with very
+tight resources. Beyond that, there are ways to extend MicroPython if needed to
+better match Python. The provided built-in modules are an efficient subset of
+the corresponding Python ones, without duplication of functionality, and allow
+extension in Python if needed.
+
Contributing
------------
@@ -80,9 +115,8 @@ This repository contains the following components:
- [examples/](examples/) -- a few example Python scripts.
"make" is used to build the components, or "gmake" on BSD-based systems.
-You will also need bash, gcc, and Python 3.3+ available as the command `python3`
-(if your system only has Python 2.7 then invoke make with the additional option
-`PYTHON=python2`). Some ports (rp2 and esp32) additionally use CMake.
+You will also need bash, gcc, and Python 3.3+ available as the command `python3`.
+Some ports (rp2 and esp32) additionally use CMake.
Supported platforms & architectures
-----------------------------------
@@ -99,29 +133,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).
- - [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-arm](ports/qemu-arm) -- 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)
- - [teensy](ports/teensy) -- Teensy 3.x.
- - [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 | |
+| [psoc-edge](ports/psoc-edge) | Infineon PSOC™ Edge | [here](https://docs.micropython.org/en/latest/psoc-edge/quickref.html) |
+| [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 | |
+
+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, RISC-V 64-bit, and PowerPC 64-bit architectures.
The MicroPython cross-compiler, mpy-cross
-----------------------------------------
diff --git a/docs/README.md b/docs/README.md
index 892726ba17f..9b3b036e063 100644
--- a/docs/README.md
+++ b/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
----------------------------------------------
diff --git a/docs/conf.py b/docs/conf.py
index a966b3a0257..f80ca97edca 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -19,55 +19,60 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath("."))
+
+# The MICROPY_VERSION env var should be "vX.Y.Z" (or unset).
+micropy_version = os.getenv("MICROPY_VERSION") or "latest"
+micropy_all_versions = (os.getenv("MICROPY_ALL_VERSIONS") or "latest").split(",")
+url_pattern = "%s/en/%%s" % (os.getenv("MICROPY_URL_PREFIX") or "/",)
# The members of the html_context dict are available inside topindex.html
-micropy_version = os.getenv('MICROPY_VERSION') or 'latest'
-micropy_all_versions = (os.getenv('MICROPY_ALL_VERSIONS') or 'latest').split(',')
-url_pattern = '%s/en/%%s' % (os.getenv('MICROPY_URL_PREFIX') or '/',)
html_context = {
- 'cur_version':micropy_version,
- 'all_versions':[
- (ver, url_pattern % ver) for ver in micropy_all_versions
- ],
- 'downloads':[
- ('PDF', url_pattern % micropy_version + '/micropython-docs.pdf'),
+ "cur_version": micropy_version,
+ "all_versions": [(ver, url_pattern % ver) for ver in micropy_all_versions],
+ "downloads": [
+ ("PDF", url_pattern % micropy_version + "/micropython-docs.pdf"),
],
- 'is_release': micropy_version != 'latest',
+ "is_release": micropy_version != "latest",
}
+# Authors used in various parts of the documentation.
+micropy_authors = "MicroPython authors and contributors"
+
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.doctest',
- 'sphinx.ext.intersphinx',
- 'sphinx.ext.todo',
- 'sphinx.ext.coverage',
+ "sphinx.ext.autodoc",
+ "sphinx.ext.doctest",
+ "sphinx.ext.intersphinx",
+ "sphinx.ext.todo",
+ "sphinx.ext.coverage",
+ "sphinxcontrib.jquery",
+ "sphinx_rtd_theme",
]
# Add any paths that contain templates here, relative to this directory.
-templates_path = ['templates']
+templates_path = ["templates"]
# The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ".rst"
# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+# source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+master_doc = "index"
# General information about the project.
-project = 'MicroPython'
-copyright = '- The MicroPython Documentation is Copyright © 2014-2023, Damien P. George, Paul Sokolovsky, and contributors'
+project = "MicroPython"
+copyright = "- The MicroPython Documentation is Copyright © 2014-2026, " + micropy_authors
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -79,41 +84,41 @@
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
-#language = None
+# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
-#today = ''
+# today = ''
# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
-exclude_patterns = ['build', '.venv']
+exclude_patterns = ["build", ".venv"]
# The reST default role (used for this markup: `text`) to use for all
# documents.
-default_role = 'any'
+default_role = "any"
# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
-#add_module_names = True
+# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
-#show_authors = False
+# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+# keep_warnings = False
# Global include files. Sphinx docs suggest using rst_epilog in preference
# of rst_prolog, so we follow. Absolute paths below mean "from the base
@@ -124,145 +129,138 @@
# -- Options for HTML output ----------------------------------------------
-# on_rtd is whether we are on readthedocs.org
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+import sphinx_rtd_theme
-if not on_rtd: # only import and set the theme if we're building docs locally
- try:
- import sphinx_rtd_theme
- html_theme = 'sphinx_rtd_theme'
- html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
- except:
- html_theme = 'default'
- html_theme_path = ['.']
-else:
- html_theme_path = ['.']
+html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = ['.']
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
-#html_title = None
+# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
+# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-#html_logo = '../../logo/trans-logo.png'
+# html_logo = '../../logo/trans-logo.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
-html_favicon = 'static/favicon.ico'
+html_favicon = "static/favicon.ico"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['static']
+html_static_path = ["static"]
# Add a custom CSS file for HTML generation
html_css_files = [
- 'custom.css',
+ "custom.css",
]
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
-#html_extra_path = []
+# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
-html_last_updated_fmt = '%d %b %Y'
+html_last_updated_fmt = "%d %b %Y"
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
-#html_use_smartypants = True
+# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
html_additional_pages = {"index": "topindex.html"}
# If false, no module index is generated.
-#html_domain_indices = True
+# html_domain_indices = True
# If false, no index is generated.
-#html_use_index = True
+# html_use_index = True
# If true, the index is split into individual pages for each letter.
-#html_split_index = False
+# html_split_index = False
# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
+# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
+# html_file_suffix = None
# Output file base name for HTML help builder.
-htmlhelp_basename = 'MicroPythondoc'
+htmlhelp_basename = "MicroPythondoc"
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-# Include 3 levels of headers in PDF ToC
-'preamble': r'\setcounter{tocdepth}{2}',
+ # The paper size ('letterpaper' or 'a4paper').
+ #'papersize': 'letterpaper',
+ # The font size ('10pt', '11pt' or '12pt').
+ #'pointsize': '10pt',
+ # Additional stuff for the LaTeX preamble.
+ #'preamble': '',
+ # Include 3 levels of headers in PDF ToC
+ "preamble": r"\setcounter{tocdepth}{2}",
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- (master_doc, 'MicroPython.tex', 'MicroPython Documentation',
- 'Damien P. George, Paul Sokolovsky, and contributors', 'manual'),
+ (
+ master_doc,
+ "MicroPython.tex",
+ "MicroPython Documentation",
+ micropy_authors,
+ "manual",
+ ),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
-#latex_logo = None
+# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
-#latex_use_parts = False
+# latex_use_parts = False
# If true, show page references after internal links.
-#latex_show_pagerefs = False
+# latex_show_pagerefs = False
# If true, show URL addresses after external links.
-#latex_show_urls = False
+# latex_show_urls = False
# Documents to append as an appendix to all manuals.
-#latex_appendices = []
+# latex_appendices = []
# If false, no module index is generated.
-#latex_domain_indices = True
+# latex_domain_indices = True
# Enable better Unicode support so that `make latexpdf` doesn't fail
latex_engine = "xelatex"
@@ -272,12 +270,17 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'micropython', 'MicroPython Documentation',
- ['Damien P. George, Paul Sokolovsky, and contributors'], 1),
+ (
+ "index",
+ "micropython",
+ "MicroPython Documentation",
+ [micropy_authors],
+ 1,
+ ),
]
# If true, show URL addresses after external links.
-#man_show_urls = False
+# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
@@ -286,23 +289,29 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- (master_doc, 'MicroPython', 'MicroPython Documentation',
- 'Damien P. George, Paul Sokolovsky, and contributors', 'MicroPython', 'One line description of project.',
- 'Miscellaneous'),
+ (
+ master_doc,
+ "MicroPython",
+ "MicroPython Documentation",
+ micropy_authors,
+ "MicroPython",
+ "One line description of project.",
+ "Miscellaneous",
+ ),
]
# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
+# texinfo_appendices = []
# If false, no module index is generated.
-#texinfo_domain_indices = True
+# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
+# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
+# texinfo_no_detailmenu = False
# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'python': ('https://docs.python.org/3.5', None)}
+intersphinx_mapping = {"python": ("https://docs.python.org/3.5", None)}
diff --git a/docs/develop/cmodules.rst b/docs/develop/cmodules.rst
index 75dbc953c06..e1c6658f075 100644
--- a/docs/develop/cmodules.rst
+++ b/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`) 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
@@ -59,7 +59,7 @@ A MicroPython user C module is a directory with the following files:
SRC_USERMOD_LIB_C += $(EXAMPLE_MOD_DIR)/utils/algorithm.c
Similarly, use ``SRC_USERMOD_CXX`` and ``SRC_USERMOD_LIB_CXX`` for C++
- source files.
+ source files. If you want to include assembly files use ``SRC_USERMOD_LIB_ASM``.
If you have custom compiler options (like ``-I`` to add directories to search
for header files), these should be added to ``CFLAGS_USERMOD`` for C code
@@ -264,6 +264,32 @@ structures. If not done correctly it will compile but importing will
fail to find the module.
+Specifying C modules via a manifest
+-----------------------------------
+
+As an alternative to passing ``USER_C_MODULES`` on the command line, C modules
+can be listed inside a frozen manifest using ``c_module()``. This is convenient
+when a board or project always pulls in the same set of C modules: the manifest
+becomes the single place that declares both frozen Python code and the C
+modules required to support it.
+
+.. code-block:: python3
+
+ # In ports/myboard/boards/MYBOARD/manifest.py
+ include("$(PORT_DIR)/boards/manifest.py")
+ c_module("$(MPY_DIR)/examples/usercmodule/cexample")
+ c_module("$(BOARD_DIR)/../../drivers/sensor")
+
+The manifest will need to be loaded via ``FROZEN_MANIFEST`` (either set in
+``mpconfigboard.{mk,cmake}`` or passed on the make command line), and modules
+listed with ``c_module()`` combine additively with any paths supplied via
+``USER_C_MODULES`` on the command line. Duplicate paths are de-duplicated, so
+mixing the two is safe.
+
+See :ref:`manifest` for the full ``c_module()`` API and supported
+``$(VAR)`` path substitutions.
+
+
Module usage in MicroPython
---------------------------
@@ -285,3 +311,73 @@ 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 ``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
+`_,
+where the Python module is implemented in a minimal C file wrapper around the
+C++ code.
+
diff --git a/docs/develop/compiler.rst b/docs/develop/compiler.rst
index cac92585ff4..0c25ad3a01e 100644
--- a/docs/develop/compiler.rst
+++ b/docs/develop/compiler.rst
@@ -98,7 +98,7 @@ Then also edit ``py/lexer.c`` to add the new keyword literal text:
.. code-block:: c
:emphasize-lines: 12
- STATIC const char *const tok_kw[] = {
+ static const char *const tok_kw[] = {
...
"or",
"pass",
@@ -157,7 +157,7 @@ The most relevant method you should know about is this:
mp_compile_to_raw_code(parse_tree, source_file, is_repl, &cm);
// Create and return a function object that executes the outer module.
- return mp_make_function_from_raw_code(cm.rc, cm.context, NULL);
+ return mp_make_function_from_proto_fun(cm.rc, cm.context, NULL);
}
The compiler compiles the code in four passes: scope, stack size, code size and emit.
@@ -301,7 +301,7 @@ code statement:
.. code-block:: c
- STATIC void emit_native_unary_op(emit_t *emit, mp_unary_op_t op) {
+ static void emit_native_unary_op(emit_t *emit, mp_unary_op_t op) {
vtype_kind_t vtype;
emit_pre_pop_reg(emit, &vtype, REG_ARG_2);
if (vtype == VTYPE_PYOBJ) {
diff --git a/docs/develop/gettingstarted.rst b/docs/develop/gettingstarted.rst
index c2d3816d425..a6afc5cad84 100644
--- a/docs/develop/gettingstarted.rst
+++ b/docs/develop/gettingstarted.rst
@@ -100,19 +100,19 @@ For the stm32 port, the ARM cross-compiler is required:
.. code-block:: bash
- $ sudo apt-get install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
+ $ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
See the `ARM GCC
toolchain `_
for the latest details.
-Python is also required. Python 2 is supported for now, but we recommend using Python 3.
+Python 3 is also required.
Check that you have Python available on your system:
.. code-block:: bash
$ python3
- Python 3.5.0 (default, Jul 17 2020, 14:04:10)
+ Python 3.5.0 (default, Jul 17 2020, 14:04:10)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
@@ -228,7 +228,7 @@ You can also specify which board to use:
.. code-block:: bash
$ cd ports/stm32
- $ make submodules
+ $ make BOARD= submodules
$ make BOARD=
See `ports/stm32/boards `_
@@ -245,7 +245,7 @@ that you use a virtual environment:
$ python3 -m venv env
$ source env/bin/activate
- $ pip install sphinx
+ $ pip install -r docs/requirements.txt
Navigate to the ``docs`` directory:
@@ -278,10 +278,86 @@ To run a selection of tests on a board/device connected over USB use:
.. code-block:: bash
$ cd tests
- $ ./run-tests.py --target minimal --device /dev/ttyACM0
+ $ ./run-tests.py -t /dev/ttyACM0
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
+-------------------
+
+MicroPython uses GitHub Actions for continuous integration.
+To reduce dependence on any specific CI system, the actual build steps for Unix-based builds are in the file ``tools/ci.sh``.
+This can also be used as a script on developer desktops, with caveats:
+
+* For most steps, An Ubuntu/Debian system similar to the one used during CI is assumed.
+* Some specific steps assume specific Ubuntu versions.
+* The setup steps may invoke the system package manager to install packages,
+ download and install software from the internet, etc.
+
+To get a usage message including the list of commands, run:
+
+.. code-block:: bash
+
+ $ tools/ci.sh --help
+
+As an example, you can build and test the unix minimal port with:
+
+.. code-block:: bash
+
+ $ 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)
+
+For the zsh shell, replace ``--bash-completion`` with ``--zsh-completion``.
+For the fish shell, replace ``--bash-completion`` with ``--fish-completion``.
+
+Then, typing:
+
+.. code-block:: bash
+
+ $ ci unix_cov
+
+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_
+ unix_coverage_32bit_build
+ unix_coverage_32bit_run_native_mpy_tests…
+
Folder structure
----------------
diff --git a/docs/develop/index.rst b/docs/develop/index.rst
index 327038f1978..1026b43d0c3 100644
--- a/docs/develop/index.rst
+++ b/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
diff --git a/docs/develop/library.rst b/docs/develop/library.rst
index c2a86ea1699..6ff9bfe023d 100644
--- a/docs/develop/library.rst
+++ b/docs/develop/library.rst
@@ -26,15 +26,9 @@ 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
@@ -48,16 +42,16 @@ hypothetical new module ``subsystem`` in the file ``modsubsystem.c``:
#if MICROPY_PY_SUBSYSTEM
// info()
- STATIC mp_obj_t py_subsystem_info(void) {
+ static mp_obj_t py_subsystem_info(void) {
return MP_OBJ_NEW_SMALL_INT(42);
}
MP_DEFINE_CONST_FUN_OBJ_0(subsystem_info_obj, py_subsystem_info);
- STATIC const mp_rom_map_elem_t mp_module_subsystem_globals_table[] = {
+ static const mp_rom_map_elem_t mp_module_subsystem_globals_table[] = {
{ MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_subsystem) },
{ MP_ROM_QSTR(MP_QSTR_info), MP_ROM_PTR(&subsystem_info_obj) },
};
- STATIC MP_DEFINE_CONST_DICT(mp_module_subsystem_globals, mp_module_subsystem_globals_table);
+ static MP_DEFINE_CONST_DICT(mp_module_subsystem_globals, mp_module_subsystem_globals_table);
const mp_obj_module_t mp_module_subsystem = {
.base = { &mp_type_module },
diff --git a/docs/develop/memorymgt.rst b/docs/develop/memorymgt.rst
index 5b1690cc827..4ae80120044 100644
--- a/docs/develop/memorymgt.rst
+++ b/docs/develop/memorymgt.rst
@@ -4,43 +4,80 @@ Memory Management
=================
Unlike programming languages such as C/C++, MicroPython hides memory management
-details from the developer by supporting automatic memory management.
-Automatic memory management is a technique used by operating systems or applications to automatically manage
-the allocation and deallocation of memory. This eliminates challenges such as forgetting to
-free the memory allocated to an object. Automatic memory management also avoids the critical issue of using memory
-that is already released. Automatic memory management takes many forms, one of them being
-garbage collection (GC).
-
-The garbage collector usually has two responsibilities;
-
-#. Allocate new objects in available memory.
-#. Free unused memory.
-
-There are many GC algorithms but MicroPython uses the
-`Mark and Sweep `_
-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
-module:
-
-.. code-block:: bash
-
- >>> x = 5
- >>> x
- 5
- >>> import gc
- >>> gc.enable()
- >>> gc.mem_alloc()
- 1312
- >>> gc.mem_free()
- 2071392
- >>> gc.collect()
- 19
- >>> gc.disable()
- >>>
-
-Even when ``gc.disable()`` is invoked, collection can be triggered with ``gc.collect()``.
+details from the developer by supporting automatic memory management of a
+":ref:`Python heap`" that holds all Python objects. MicroPython uses
+garbage collection (GC) for automatic memory management. The garbage collector
+is responsible for freeing memory which is no longer in use.
+
+Specifically, MicroPython uses a `Mark and Sweep
+`_
+garbage collection algorithm. This algorithm has a mark phase that scans the
+heap marking all live objects, and then a sweep phase goes through the heap
+reclaiming all unmarked objects.
+
+The MicroPython garbage collector is by default automatic, but manual control is
+available through the :mod:`gc` built-in module.
+
+.. _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
----------------
diff --git a/docs/develop/natmod.rst b/docs/develop/natmod.rst
index 6d15f867bcf..e0f7bdaaa89 100644
--- a/docs/develop/natmod.rst
+++ b/docs/develop/natmod.rst
@@ -39,11 +39,18 @@ options for the ``ARCH`` variable, see below):
* ``armv7emsp`` (ARM Thumb 2, single precision float, eg Cortex-M4F, Cortex-M7)
* ``armv7emdp`` (ARM Thumb 2, double precision float, eg Cortex-M7)
* ``xtensa`` (non-windowed, eg ESP8266)
-* ``xtensawin`` (windowed with window size 8, eg ESP32)
+* ``xtensawin`` (windowed with window size 8, eg ESP32, ESP32S3)
+* ``rv32imc`` (RISC-V 32 bits with compressed instructions, eg ESP32C3, ESP32C6)
+* ``rv64imc`` (RISC-V 64 bits with compressed instructions)
+
+If the chosen platform supports explicit architecture flags and you want to let
+the output .mpy file carry those flags' value, you must pass them to the
+``ARCH_FLAGS`` flags variable when building the .mpy file.
When compiling and linking the native .mpy file the architecture must be chosen
-and the corresponding file can only be imported on that architecture. For more
-details about .mpy files see :ref:`mpy_files`.
+and the corresponding file can only be imported on that architecture (and if
+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
@@ -66,14 +73,31 @@ The known limitations are:
* static BSS variables are not supported; workaround: use global BSS variables
+* thread-local storage variables are not supported on rv32imc; workaround: use
+ global BSS variables or allocate some space on the heap to store them
+
So, if your C code has writable data, make sure the data is defined globally,
without an initialiser, and only written to within functions.
+The native module is not automatically linked against the standard static libraries
+like ``libm.a`` and ``libgcc.a``, which can lead to ``undefined symbol`` errors.
+You can link the runtime libraries by setting ``LINK_RUNTIME = 1``
+in your Makefile. Custom static libraries can also be linked by adding
+``MPY_LD_FLAGS += -l path/to/library.a``. Note that these are linked into
+the native module and will not be shared with other modules or the system.
+
Linker limitation: the native module is not linked against the symbol table of the
full MicroPython firmware. Rather, it is linked against an explicit table of exported
symbols found in ``mp_fun_table`` (in ``py/nativeglue.h``), that is fixed at firmware
build time. It is thus not possible to simply call some arbitrary HAL/OS/RTOS/system
-function, for example.
+function, for example, unless that resides at a fixed address. In that case, the path
+of a linkerscript containing a series of symbol names and their fixed address can be
+passed to ``mpy_ld.py`` via the ``--externs`` command line argument. That way symbols
+appearing in the linkerscript will take precedence over what is provided from object
+files, but at the moment the object files' implementation will still reside in the
+final MPY file. The linkerscript parser is limited in its capabilities, and is
+currently used only for parsing the ESP8266 port ROM symbols list (see
+``ports/esp8266/boards/eagle.rom.addr.v6.ld``).
New symbols can be added to the end of the table and the firmware rebuilt.
The symbols also need to be added to ``tools/mpy_ld.py``'s ``fun_table`` dict in the
@@ -105,7 +129,8 @@ The filesystem layout consists of two main parts, the source files and the Makef
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``
as the list of source files, optionally specify the machine architecture via ``ARCH``,
- and then include ``py/dynruntime.mk``.
+ along with optional machine architecture flags specified via ``ARCH_FLAGS``, and
+ then include ``py/dynruntime.mk``.
Minimal example
---------------
@@ -128,7 +153,7 @@ The file ``factorial.c`` contains:
#include "py/dynruntime.h"
// Helper function to compute factorial
- STATIC mp_int_t factorial_helper(mp_int_t x) {
+ static mp_int_t factorial_helper(mp_int_t x) {
if (x == 0) {
return 1;
}
@@ -136,7 +161,7 @@ The file ``factorial.c`` contains:
}
// This is the function which will be called from Python, as factorial(x)
- STATIC mp_obj_t factorial(mp_obj_t x_obj) {
+ static mp_obj_t factorial(mp_obj_t x_obj) {
// Extract the integer from the MicroPython input object
mp_int_t x = mp_obj_get_int(x_obj);
// Calculate the factorial
@@ -145,7 +170,7 @@ The file ``factorial.c`` contains:
return mp_obj_new_int(result);
}
// Define a Python reference to the function above
- STATIC MP_DEFINE_CONST_FUN_OBJ_1(factorial_obj, factorial);
+ static MP_DEFINE_CONST_FUN_OBJ_1(factorial_obj, factorial);
// This is the entry point and is called when the module is imported
mp_obj_t mpy_init(mp_obj_fun_bc_t *self, size_t n_args, size_t n_kw, mp_obj_t *args) {
@@ -172,7 +197,7 @@ The file ``Makefile`` contains:
# Source files (.c or .py)
SRC = factorial.c
- # Architecture to build for (x86, x64, armv6m, armv7m, xtensa, xtensawin)
+ # Architecture to build for (x86, x64, armv6m, armv7m, xtensa, xtensawin, rv32imc, rv64imc)
ARCH = x64
# Include to get the rules for compiling and linking the module
@@ -198,6 +223,10 @@ Without modifying the Makefile you can specify the target architecture via::
$ make ARCH=armv7m
+Same applies for optional architecture flags via::
+
+ $ make ARCH=rv32imc ARCH_FLAGS=zba
+
Module usage in MicroPython
---------------------------
@@ -210,6 +239,26 @@ other module, for example::
print(factorial.factorial(10))
# should display 3628800
+Using Picolibc when building modules
+------------------------------------
+
+Using `Picolibc `_ as your C standard
+library is not only supported, but in fact it is the default for the rv32imc and
+rv64imc platforms. However, there are a couple of things worth mentioning to make
+sure you don't run into problems later when building code.
+
+Some pre-built Picolibc versions (for example, those provided by Ubuntu Linux
+as the ``picolibc-arm-none-eabi``, ``picolibc-riscv64-unknown-elf``, and
+``picolibc-xtensa-lx106-elf`` packages) assume thread-local storage (TLS) is
+available at runtime, but unfortunately MicroPython modules do not support that
+on some architectures (namely ``rv32imc`` and ``rv64imc``). This means that some
+functionalities provided by Picolibc will default to use TLS, returning an
+error either during compilation or during linking.
+
+For an example on how this may affect you, the ``examples/natmod/btree``
+example module contains a workaround to make sure ``errno`` works (look for
+``__PICOLIBC_ERRNO_FUNCTION`` in the Makefile and follow the trail from there).
+
Further examples
----------------
diff --git a/docs/develop/optimizations.rst b/docs/develop/optimizations.rst
index 7f2c8cbe728..3f07aebbc66 100644
--- a/docs/develop/optimizations.rst
+++ b/docs/develop/optimizations.rst
@@ -33,7 +33,7 @@ Variables
MicroPython processes local and global variables differently. Global variables
are stored and looked up from a global dictionary that is allocated on the heap
(note that each module has its own separate dict, so separate namespace).
-Local variables on the other hand are are stored on the Python value stack, which may
+Local variables on the other hand are stored on the Python value stack, which may
live on the C stack or on the heap. They are accessed directly by their offset
within the Python stack, which is more efficient than a global lookup in a dict.
@@ -59,6 +59,9 @@ Compiles to:
X = 1
foo(1, 2)
+See :func:`micropython.const` for complete details on usage requirements and
+limitations.
+
Allocation of memory
--------------------
diff --git a/docs/develop/porting.rst b/docs/develop/porting.rst
index fab8a751b84..28d7b3dd513 100644
--- a/docs/develop/porting.rst
+++ b/docs/develop/porting.rst
@@ -42,7 +42,6 @@ The basic MicroPython firmware is implemented in the main port file, e.g ``main.
#include "py/compile.h"
#include "py/gc.h"
#include "py/mperrno.h"
- #include "py/stackctrl.h"
#include "shared/runtime/gchelper.h"
#include "shared/runtime/pyexec.h"
@@ -51,7 +50,7 @@ The basic MicroPython firmware is implemented in the main port file, e.g ``main.
int main(int argc, char **argv) {
// Initialise the MicroPython runtime.
- mp_stack_ctrl_init();
+ mp_cstack_init_with_sp_here(2048);
gc_init(heap, heap + sizeof(heap));
mp_init();
@@ -83,7 +82,7 @@ The basic MicroPython firmware is implemented in the main port file, e.g ``main.
}
// There is no filesystem so opening a file raises an exception.
- mp_lexer_t *mp_lexer_new_from_file(const char *filename) {
+ mp_lexer_t *mp_lexer_new_from_file(qstr filename) {
mp_raise_OSError(MP_ENOENT);
}
@@ -151,9 +150,6 @@ The following is an example of an ``mpconfigport.h`` file:
#define MICROPY_ERROR_REPORTING (MICROPY_ERROR_REPORTING_TERSE)
#define MICROPY_FLOAT_IMPL (MICROPY_FLOAT_IMPL_FLOAT)
- // Enable u-modules to be imported with their standard name, like sys.
- #define MICROPY_MODULE_WEAK_LINKS (1)
-
// Fine control over Python builtins, classes, modules, etc.
#define MICROPY_PY_ASYNC_AWAIT (0)
#define MICROPY_PY_BUILTINS_SET (0)
@@ -165,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().
@@ -247,10 +241,12 @@ That should give a MicroPython REPL. You can then run commands like:
.. code-block:: bash
- MicroPython v1.13 on 2021-01-01; example-board with unknown-cpu
- >>> import sys
- >>> sys.implementation
- ('micropython', (1, 13, 0))
+ MicroPython v1.26.0-preview on 2025-08-01; minimal with unknown-cpu
+ >>> def sum(n, m):
+ ... return n + m
+ ...
+ >>> 3, 4, sum(3, 4)
+ (3, 4, 7)
>>>
Use Ctrl-D to exit, and then run ``reset`` to reset the terminal.
@@ -265,17 +261,17 @@ To add a custom module like ``myport``, first add the module definition in a fil
#include "py/runtime.h"
- STATIC mp_obj_t myport_info(void) {
+ static mp_obj_t myport_info(void) {
mp_printf(&mp_plat_print, "info about my port\n");
return mp_const_none;
}
- STATIC MP_DEFINE_CONST_FUN_OBJ_0(myport_info_obj, myport_info);
+ static MP_DEFINE_CONST_FUN_OBJ_0(myport_info_obj, myport_info);
- STATIC const mp_rom_map_elem_t myport_module_globals_table[] = {
+ static const mp_rom_map_elem_t myport_module_globals_table[] = {
{ MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_myport) },
{ MP_ROM_QSTR(MP_QSTR_info), MP_ROM_PTR(&myport_info_obj) },
};
- STATIC MP_DEFINE_CONST_DICT(myport_module_globals, myport_module_globals_table);
+ static MP_DEFINE_CONST_DICT(myport_module_globals, myport_module_globals_table);
const mp_obj_module_t myport_module = {
.base = { &mp_type_module },
diff --git a/docs/develop/support_tiers.rst b/docs/develop/support_tiers.rst
new file mode 100644
index 00000000000..6c62c495d16
--- /dev/null
+++ b/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
+ - psoc-edge
+ - renesas-ra
+ - webassembly
+ - zephyr
+
+Tier 3 ports:
+
+ - cc3200
+ - esp8266
+ - pic16bit
+
+Tier M ports:
+
+ - bare-arm
+ - minimal
+ - qemu
diff --git a/docs/develop/writingtests.rst b/docs/develop/writingtests.rst
index 9bb5178f55f..7ac7e038ca8 100644
--- a/docs/develop/writingtests.rst
+++ b/docs/develop/writingtests.rst
@@ -46,6 +46,11 @@ If you run your tests, this test should appear in the test output:
Tests are run by comparing the output from the test target against the output from CPython.
So any test should use print statements to indicate test results.
+When writing tests for name or string-related functionality, please add both English/ASCII
+as well as non-English/non-ASCII text and include Unicode examples.
+Please do add comments in English explaining the meaning and intent of the Unicode text.
+This help ensure Unicode support is tested and verified across different platforms.
+
For tests that can't be compared to CPython (i.e. micropython-specific functionality),
you can provide a ``.py.exp`` file which will be used as the truth for comparison.
@@ -60,7 +65,7 @@ Then to run on a board:
.. code-block:: bash
- $ ./run-tests.py --target minimal --device /dev/ttyACM0
+ $ ./run-tests.py -t /dev/ttyACM0
And to run only a certain set of tests (eg a directory):
@@ -68,3 +73,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:** - connect to and use the given serial port device
+- **a** - connect to and use /dev/ttyACM
+- **u** - connect to and use /dev/ttyUSB
+- **c** - connect to and use COM
+- **exec:** - execute a command and attach to it's stdin/stdout
+- **execpty:** - execute a command and attach to the printed /dev/pts/ device
+- **...** - 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 `` - 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
diff --git a/docs/differences/modules_preamble.txt b/docs/differences/modules_preamble.txt
new file mode 100644
index 00000000000..1958f0084d2
--- /dev/null
+++ b/docs/differences/modules_preamble.txt
@@ -0,0 +1,33 @@
+.. Preamble section inserted into generated output
+
+Positional-only Parameters
+--------------------------
+
+To save code size, many functions that accept keyword arguments in CPython only accept positional arguments in MicroPython.
+
+MicroPython marks positional-only parameters in the same way as CPython, by inserting a ``/`` to mark the end of the positional parameters. Any function whose signature ends in ``/`` takes *only* positional arguments. For more details, see `PEP 570 `_.
+
+Example
+~~~~~~~
+
+For example, in CPython 3.4 this is the signature of the constructor ``socket.socket``::
+
+ socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
+
+However, the signature documented in :func:`MicroPython` is::
+
+ socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP, /)
+
+The ``/`` at the end of the parameters indicates that they are all positional-only in MicroPython. The following code works in CPython but not in most MicroPython ports::
+
+ import socket
+ s = socket.socket(type=socket.SOCK_DGRAM)
+
+MicroPython will raise an exception::
+
+ TypeError: function doesn't take keyword arguments
+
+The following code will work in both CPython and MicroPython::
+
+ import socket
+ s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
diff --git a/docs/differences/python_36.rst b/docs/differences/python_36.rst
index 3315b0594da..18da79f8f84 100644
--- a/docs/differences/python_36.rst
+++ b/docs/differences/python_36.rst
@@ -25,7 +25,8 @@ Python 3.6 beta 1 was released on 12 Sep 2016, and a summary of the new features
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 468 `_ | Preserving the order of *kwargs* in a function | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
- | `PEP 487 `_ | Simpler customization of class creation | |
+ | `PEP 487 `_ | Simpler customization of class creation | Partial |
+ | | | [#setname]_ |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 520 `_ | Preserving Class Attribute Definition Order | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
@@ -198,3 +199,7 @@ Changes to built-in modules:
+--------------------------------------------------------------------------------------------------------------+----------------+
| The *compress()* and *decompress()* functions now accept keyword arguments | |
+--------------------------------------------------------------------------------------------------------------+----------------+
+
+.. rubric:: Notes
+
+.. [#setname] Currently, only :func:`__set_name__` is implemented.
diff --git a/docs/differences/python_37.rst b/docs/differences/python_37.rst
index 86d1b6e81f9..2b9a089217f 100644
--- a/docs/differences/python_37.rst
+++ b/docs/differences/python_37.rst
@@ -105,4 +105,4 @@ Changes to built-in modules:
.. rubric:: Notes
-.. [#ftimenanosec] Only :func:`time.time_ns` is implemented.
+.. [#ftimenanosec] Only :func:`time.time_ns` is implemented.
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
index e19c6ecb408..6b3fa951653 100644
--- a/docs/esp32/quickref.rst
+++ b/docs/esp32/quickref.rst
@@ -18,6 +18,9 @@ working with this board it may be useful to get an overview of the microcontroll
general.rst
tutorial/index.rst
+Note that there are several varieties of ESP32 -- ESP32, ESP32C3, ESP32C6, ESP32S2, ESP32S3 --
+supported by MicroPython, with some differences in functionality between them.
+
Installing MicroPython
----------------------
@@ -57,52 +60,57 @@ The :mod:`esp32` module::
import esp32
- esp32.hall_sensor() # read the internal hall sensor
esp32.raw_temperature() # read the internal temperature of the MCU, in Fahrenheit
- esp32.ULP() # access to the Ultra-Low-Power Co-processor
+ esp32.ULP() # access to the Ultra-Low-Power Co-processor, not on ESP32C3/C6
Note that the temperature sensor in the ESP32 will typically read higher than
ambient due to the IC getting warm while it runs. This effect can be minimised
by reading the temperature sensor immediately after waking up from sleep.
+ESP32C3, ESP32C6, ESP32S2, and ESP32S3 also have an internal temperature sensor available.
+It is implemented a bit differently to the ESP32 and returns the temperature in
+Celsius::
+
+ esp32.mcu_temperature() # read the internal temperature of the MCU, in Celsius
+
Networking
----------
WLAN
^^^^
-The :mod:`network` module::
+The :class:`network.WLAN` class in the :mod:`network` module::
import network
- wlan = network.WLAN(network.STA_IF) # create station interface
- wlan.active(True) # activate the interface
- wlan.scan() # scan for access points
- wlan.isconnected() # check if the station is connected to an AP
+ wlan = network.WLAN() # create station interface (the default, see below for an access point interface)
+ wlan.active(True) # activate the interface
+ wlan.scan() # scan for access points
+ wlan.isconnected() # check if the station is connected to an AP
wlan.connect('ssid', 'key') # connect to an AP
- wlan.config('mac') # get the interface's MAC address
- wlan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses
+ wlan.config('mac') # get the interface's MAC address
+ wlan.ipconfig('addr4') # get the interface's IPv4 addresses
- ap = network.WLAN(network.AP_IF) # create access-point interface
- ap.config(ssid='ESP-AP') # set the SSID of the access point
- ap.config(max_clients=10) # set how many clients can connect to the network
- ap.active(True) # activate the interface
+ ap = network.WLAN(network.WLAN.IF_AP) # create access-point interface
+ ap.config(ssid='ESP-AP') # set the SSID of the access point
+ ap.config(max_clients=10) # set how many clients can connect to the network
+ ap.active(True) # activate the interface
A useful function for connecting to your local WiFi network is::
def do_connect():
- import network
- wlan = network.WLAN(network.STA_IF)
+ import machine, network
+ wlan = network.WLAN()
wlan.active(True)
if not wlan.isconnected():
print('connecting to network...')
wlan.connect('ssid', 'key')
while not wlan.isconnected():
- pass
- print('network config:', wlan.ifconfig())
+ machine.idle()
+ print('network config:', wlan.ipconfig('addr4'))
Once the network is established the :mod:`socket ` module can be used
-to create and use TCP/UDP sockets as usual, and the ``urequests`` module for
+to create and use TCP/UDP sockets as usual, and the ``requests`` module for
convenient HTTP requests.
After a call to ``wlan.connect()``, the device will by default retry to connect
@@ -113,44 +121,61 @@ calling ``wlan.config(reconnects=n)``, where n are the number of desired reconne
attempts (0 means it won't retry, -1 will restore the default behaviour of trying
to reconnect forever).
+.. _esp32_network_lan:
+
LAN
^^^
-To use the wired interfaces one has to specify the pins and mode ::
+Built-in MAC (original ESP32)
+"""""""""""""""""""""""""""""
+
+The original ESP32 SoC has a built-in Ethernet MAC. Using this MAC requires an
+external Ethernet PHY to be wired to the chip's EMAC pins. Most of the EMAC pin
+assignments are fixed, consult the ESP32 datasheet for details.
+
+If the PHY is connected, the internal Ethernet MAC can be configured via
+the :class:`network.LAN` constructor::
import network
lan = network.LAN(mdc=PIN_MDC, ...) # Set the pin and mode configuration
lan.active(True) # activate the interface
- lan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses
+ lan.ipconfig('addr4') # get the interface's IPv4 addresses
+
+
+Required keyword arguments for the constructor:
+- ``mdc`` and ``mdio`` - :class:`machine.Pin` objects (or integers) specifying
+ the MDC and MDIO pins.
+- ``phy_type`` - Select the PHY device type. Supported devices are
+ ``PHY_GENERIC``,
+ ``PHY_LAN8710``, ``PHY_LAN8720``, ``PHY_IP101``, ``PHY_RTL8201``,
+ ``PHY_DP83848``, ``PHY_KSZ8041`` and ``PHY_KSZ8081``. These values are all
+ constants defined in the ``network`` module.
+- ``phy_addr`` - The address number of the PHY device. Must be an integer in the
+ range 0x00 to 0x1f, inclusive. Common values are ``0`` and ``1``.
-The keyword arguments for the constructor defining the PHY type and interface are:
+All of the above keyword arguments must be present to configure the interface.
-- mdc=pin-object # set the mdc and mdio pins.
-- mdio=pin-object
-- power=pin-object # set the pin which switches the power of the PHY device.
-- phy_type= # Select the PHY device type. Supported devices are PHY_LAN8710,
- PHY_LAN8720, PH_IP101, PHY_RTL8201, PHY_DP83848 and PHY_KSZ8041
-- phy_addr=number # The address number of the PHY device.
-- ref_clk_mode=mode # Defines, whether the ref_clk at the ESP32 is an input
- or output. Suitable values are Pin.IN and Pin.OUT.
-- ref_clk=pin-object # defines the Pin used for ref_clk.
+Optional keyword arguments:
-The options ref_clk_mode and ref_clk require at least esp-idf version 4.4. For
-earlier esp-idf versions, these parameters must be defined by kconfig board options.
+- ``reset`` - :class:`machine.Pin` object (or integer) specifying the PHY reset pin.
+- ``power`` - :class:`machine.Pin` object (or integer) specifying a pin which
+ switches the power of the PHY device.
+- ``ref_clk`` - :class:`machine.Pin` object (or integer) specifying the pin used
+ for the EMAC ``ref_clk`` signal. If not specified, the board default is used
+ (typically GPIO 0, but may be different if a particular board has Ethernet.)
+- ``ref_clk_mode`` - Defines whether the EMAC ``ref_clk`` pin of the ESP32
+ should be an input or an output. Suitable values are ``machine.Pin.IN`` and
+ ``machine.Pin.OUT``. If not specified, the board default is used
+ (typically input, but may be different if a particular board has Ethernet.)
-These are working configurations for LAN interfaces of popular boards::
+These are working configurations for LAN interfaces of some popular ESP32 boards::
# Olimex ESP32-GATEWAY: power controlled by Pin(5)
# Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
- phy_type=network.PHY_LAN8720, phy_addr=0)
-
- # or with dynamic ref_clk pin configuration
-
- lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
phy_type=network.PHY_LAN8720, phy_addr=0,
ref_clk=machine.Pin(17), ref_clk_mode=machine.Pin.OUT)
@@ -159,20 +184,86 @@ These are working configurations for LAN interfaces of popular boards::
lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18),
phy_type=network.PHY_LAN8720, phy_addr=1, power=None)
+ # Wireless-Tag's WT32-ETH01 v1.4
+
+ lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18),
+ phy_type=network.PHY_LAN8720, phy_addr=1,
+ power=machine.Pin(16))
+
# Espressif ESP32-Ethernet-Kit_A_V1.2
- lan = network.LAN(id=0, mdc=Pin(23), mdio=Pin(18), power=Pin(5),
+ lan = network.LAN(id=0, mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
phy_type=network.PHY_IP101, phy_addr=1)
-A suitable definition of the PHY interface in a sdkconfig.board file is::
+ # ESP32-WROOM-32UE with KSZ8863RLL (Integrated 3-Port 10/100 Managed Switch with PHYs)
+
+ lan = network.LAN(mdc=machine.Pin(23), # connected to SCL_MDC pin of KSZ8863RLL
+ mdio=machine.Pin(15), # connected to SDA_MDIO pin of KSZ8863RLL
+ power=machine.Pin(16), # connected to RSTN pin of KSZ8863RLL
+ phy_type=network.PHY_GENERIC,
+ phy_addr=3,
+ ref_clk_mode=machine.Pin.IN,
+ ref_clk=machine.Pin(0)) # REF_CLK 50MHz from KSZ8863RLL
+
+
+.. _esp32_spi_ethernet:
+
+SPI Ethernet Interface
+""""""""""""""""""""""
+
+All ESP32 SoCs support external SPI Ethernet interface chips. These are Ethernet
+interfaces that connect via a SPI bus, rather than an Ethernet RMII interface.
+
+.. note:: The only exception is the ESP32 ``d2wd`` variant, where this feature is disabled
+ to save code size.
+
+SPI Ethernet uses the same :class:`network.LAN` constructor, with a different
+set of keyword arguments::
+
+ import machine, network
+
+ spi = machine.SPI(1, sck=SCK_PIN, mosi=MOSI_PIN, miso=MISO_PIN)
+ lan = network.LAN(spi=spi, cs=CS_PIN, ...) # Set the pin and mode configuration
+ lan.active(True) # activate the interface
+ lan.ipconfig('addr4') # get the interface's IPv4 addresses
+
+Required keyword arguments for the constructor:
+
+- ``spi`` - Should be a :class:`machine.SPI` object configured for this
+ connection. Note that any clock speed configured on the SPI object is ignored,
+ the SPI Ethernet clock speed is configured at compile time.
+- ``cs`` - :class:`machine.Pin` object (or integer) specifying the CS pin
+ connected to the interface.
+- ``int`` - :class:`machine.Pin` object (or integer) specifying the INT pin
+ connected to the interface.
+- ``phy_type`` - Select the SPI Ethernet interface type. Supported devices are
+ ``PHY_KSZ8851SNL``, ``PHY_DM9051``, ``PHY_W5500``. These values are all
+ constants defined in the ``network`` module.
+- ``phy_addr`` - The address number of the PHY device. Must be an integer in the
+ range 0x00 to 0x1f, inclusive. This is usually ``0`` for SPI Ethernet devices.
+
+All of the above keyword arguments must be present to configure the interface.
+
+Optional keyword arguments for the constructor:
+
+- ``reset`` - :class:`machine.Pin` object (or integer) specifying the SPI Ethernet
+ interface reset pin.
+- ``power`` - :class:`machine.Pin` object (or integer) specifying a pin which
+ switches the power of the SPI Ethernet interface.
+
+Here is a sample configuration for a WIZNet W5500 chip connected to pins on
+an ESP32-S3 development board::
+
+ import machine, network
+ from machine import Pin, SPI
- CONFIG_ETH_PHY_INTERFACE_RMII=y
- CONFIG_ETH_RMII_CLK_OUTPUT=y
- CONFIG_ETH_RMII_CLK_OUT_GPIO=17
- CONFIG_LWIP_LOCAL_HOSTNAME="ESP32_POE"
+ spi = SPI(1, sck=Pin(12), mosi=Pin(13), miso=Pin(14))
+ lan = network.LAN(spi=spi, phy_type=network.PHY_W5500, phy_addr=0,
+ cs=Pin(10), int=Pin(11))
-The value assigned to CONFIG_ETH_RMII_CLK_OUT_GPIO may vary depending on the
-board's wiring.
+.. note:: WIZnet W5500 Ethernet is also supported on some other MicroPython
+ ports, but using a :ref:`different software interface
+ `.
Delay and timing
----------------
@@ -190,8 +281,10 @@ Use the :mod:`time