kopia lustrzana https://github.com/espressif/esp-idf
Merge branch 'feat/compatibility_revisions' into 'master'
doc: add documentation for compatibility between IDF version and chip revision See merge request espressif/esp-idf!23973pull/12097/head
Michael (XIAO Xufeng)
commit
026c155c9c
|
|
@ -56,6 +56,7 @@
|
|||
/.pre-commit-config.yaml @esp-idf-codeowners/ci
|
||||
/.readthedocs.yml @esp-idf-codeowners/docs
|
||||
/CMakeLists.txt @esp-idf-codeowners/build-config
|
||||
/COMPATIBILITY*.md @esp-idf-codeowners/peripherals
|
||||
/CONTRIBUTING.md @esp-idf-codeowners/docs
|
||||
/Kconfig @esp-idf-codeowners/build-config
|
||||
/README*.md @esp-idf-codeowners/docs
|
||||
|
|
|
|||
|
|
@ -0,0 +1,99 @@
|
|||
# Compatibility Between ESP-IDF Releases and Revisions of Espressif SoCs
|
||||
|
||||
* [中文版](./COMPATIBILITY_CN.md)
|
||||
|
||||
Espressif keeps improving the performance of its SoCs by providing new chip revisions. However, some of the improvements require special software support. Some of the software supports are even mandatory for the chip revisions to run normally.
|
||||
|
||||
This document describes the compatibility between ESP-IDF releases and Espressif SoC revisions.
|
||||
|
||||
NOTE: This document on release branches may be out-of-date. Check the [Compatibility file on master](https://github.com/espressif/esp-idf/blob/master/COMPATIBILITY.md) for the most accurate information.
|
||||
|
||||
See [Compatibility Advisory for Chip Revision Numbering Scheme](https://www.espressif.com.cn/sites/default/files/advisory_downloads/AR2022-005%20Compatibility%20Advisory%20for%20Chip%20Revision%20Numbering%20%20Scheme.pdf) on the versioning of Espressif SoC revisions.
|
||||
|
||||
You can run `esptool chip_id` to detect the series and revision of an SoC. See [SoC Errata](https://www.espressif.com.cn/en/support/documents/technical-documents?keys=errata) for more on how to distinguish between chip revisions, and the improvements provided by chip revisions. And run `idf.py --version` to know the version of current ESP-IDF.
|
||||
|
||||
## ESP-IDF Support for Different Chip Revisions
|
||||
|
||||
The sections below show the requirements to ESP-IDF version of chip revisions. Each chip revision corresponds to specific `Recommended` and `Required` versions of ESP-IDF:
|
||||
|
||||
- `Recommended`: shows from which version of ESP-IDF you can make use of all the improvements of the chip revision. Running binary compiled with ESP-IDF below the `Recommended` version of a chip revision, software may not benefit from the bugfix/features provided by the chip revision. The chip will have almost the same behavior as its previous revision.
|
||||
|
||||
- `Required`: shows the minimum version required to run the chip revision normally. Running binary compiled below the `Required` version, the binary may have unpredictable behavior.
|
||||
|
||||
Though the software can make use of all the features of a chip revision, if its version is higher than the `Recommended` version of the chip, it is still recommended to use the latest bugfix version of the release branch. The latest bugfix version fixes a number of issues and helps improve product stability.
|
||||
|
||||
For example, if we have a chip, whose `Required`/`Recommended` version of `release/v5.1` branch is `v5.1.2`/`v5.1.4`, and the latest release on that branch is `v5.1.6`. Then the chip will not boot up with ESP-IDF `v5.1`-`v5.1.1` or will have unpredictable behavior, and application may not make use of all benefits of the chip, when running with ESP-IDF `v5.1.2` or `v5.1.3`. Though `v5.1.4` well supports the chip revision, it is still recommended to upgrade ESP-IDF to `v5.1.6`.
|
||||
|
||||
### ESP32
|
||||
|
||||
#### v0.0, v1.0, v3.0
|
||||
|
||||
Supported since initial version of ESP-IDF.
|
||||
|
||||
#### v1.1
|
||||
|
||||
To be added.
|
||||
|
||||
#### v2.0
|
||||
|
||||
To be added.
|
||||
|
||||
#### v3.1
|
||||
|
||||
To be added.
|
||||
|
||||
### ESP32-S2
|
||||
|
||||
#### v0.0
|
||||
|
||||
Supported since ESP-IDF v4.2.
|
||||
|
||||
#### v1.0
|
||||
|
||||
| Release branch | Recommended | Required |
|
||||
|------------------------|-------------|----------|
|
||||
| release/v4.2 | v4.2.3 | v4.2.3 |
|
||||
| release/v4.3 | v4.3.3 | v4.3.3 |
|
||||
| release/v4.4 | v4.4.1 | v4.4.1 |
|
||||
| release/v5.0 and above | v5.0 | v5.0 |
|
||||
|
||||
### ESP32-C3
|
||||
|
||||
#### v0.2, v0.3
|
||||
|
||||
Supported since ESP-IDF v4.3.
|
||||
|
||||
#### v0.4
|
||||
|
||||
To be added.
|
||||
|
||||
### ESP32-S3
|
||||
|
||||
#### v0.1
|
||||
|
||||
Supported since ESP-IDF v4.4.
|
||||
|
||||
#### v0.2
|
||||
|
||||
To be added.
|
||||
|
||||
### ESP32-C2 & ESP8684
|
||||
|
||||
#### v1.0
|
||||
|
||||
Supported since ESP-IDF v5.0.
|
||||
|
||||
#### v1.1
|
||||
|
||||
To be added.
|
||||
|
||||
#### v1.2
|
||||
|
||||
To be added.
|
||||
|
||||
|
||||
## What If the ESP-IDF Version Is Lower than the `Required` Version?
|
||||
|
||||
Latest ESP-IDF versions can prevent from downloading to, or even execute binaries on unsupported chips. ESP-IDF of versions v4.4.5+, v5.0.1+, v5.1 and above have both esptool download check and bootloader loading check against the chip revision. While ESP-IDF v4.3.5 has only esptool downloading check.
|
||||
|
||||
For earlier ESP-IDF versions without such checking, which is incompatible with the given chip revision, the chips running such versions will have unpredictable behavior.
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
# ESP-IDF 版本与乐鑫芯片版本兼容性
|
||||
|
||||
* [English Version](./COMPATIBILITY.md)
|
||||
|
||||
为不断提高芯片性能，乐鑫会为其芯片发布新版本。但新芯片版本中的某些性能提升依赖特殊的软件支持，有时候新芯片版本必须在一定的软件版本下才能正常运行。
|
||||
|
||||
本文档介绍了具体 ESP-IDF 版本与乐鑫芯片版本之间的兼容性情况。
|
||||
|
||||
注意：各分支上的兼容性文档可能不是最新版本，请参考 [master 分支上的兼容性文件](https://github.com/espressif/esp-idf/blob/master/COMPATIBILITY_CN.md) 以获取最新信息。
|
||||
|
||||
有关乐鑫芯片版本的编码方式，请参考 [关于芯片版本 (Chip Revision) 编码方式的兼容性公告](https://www.espressif.com/sites/default/files/advisory_downloads/AR2022-005%20%E5%85%B3%E4%BA%8E%E8%8A%AF%E7%89%87%E7%89%88%E6%9C%AC%E7%BC%96%E7%A0%81%E6%96%B9%E5%BC%8F%20%28Chip%20Revision%29%20%E7%9A%84%E5%85%BC%E5%AE%B9%E6%80%A7%E5%85%AC%E5%91%8A.pdf)。
|
||||
|
||||
运行 `esptool chip_id` 可查看芯片系列及其版本。有关区分芯片版本及版本改进内容的更多信息，请参考 [芯片勘误表](https://www.espressif.com.cn/zh-hans/support/documents/technical-documents?keys=%E5%8B%98%E8%AF%AF%E8%A1%A8)。运行 `idf.py --version` 可查看当前的 ESP-IDF 版本。
|
||||
|
||||
## ESP-IDF 对各芯片版本的支持
|
||||
|
||||
下文介绍了 ESP-IDF 对各芯片版本的支持情况，每个芯片版本都有对应的 ESP-IDF `推荐版本` 和 `需求版本`：
|
||||
|
||||
- `推荐版本`：表示从该版本的 ESP-IDF 开始，软件可以利用芯片版本提升的性能。如果在该芯片版本上运行低于 `推荐版本` 的 ESP-IDF 来编译二进制文件，软件可能无法利用该芯片版本修复的错误或新增的功能，芯片行为将与其上一版本几乎相同。
|
||||
|
||||
- `需求版本`：表示该芯片版本正常运行所需的最低 ESP-IDF 版本。如果在该芯片版本上运行低于 `需求版本` 的 ESP-IDF 来编译二进制文件，可能会出现不可预测的芯片行为。
|
||||
|
||||
即便使用的软件版本已高于该芯片版本的对应 `推荐版本`，软件已经能够利用该芯片版本的所有功能，我们仍建议用户升级到该发布分支的最新 bugfix 版本。新的 bugfix 版本修复了一些问题，有助于提升产品稳定性。
|
||||
|
||||
例如，对于某一芯片版本，其 `release/v5.1` 分支的 `需求版本` 和 `推荐版本` 分别是 `v5.1.2` 和 `v5.1.4`，而该分支的最新版本是 `v5.1.6`。那么，在使用 ESP-IDF `v5.1` - `v5.1.1` 时，芯片将无法启动，或会出现不可预测的行为，而在使用 ESP-IDF `v5.1.2` 或 `v5.1.3` 时，应用程序可能无法使用芯片的部分性能。此外，虽然 `v5.1.4` 已支持该芯片版本，但仍建议将 ESP-IDF 升级到 `v5.1.6`。
|
||||
|
||||
### ESP32
|
||||
|
||||
#### v0.0、v1.0 和 v3.0
|
||||
|
||||
从最初版本的 ESP-IDF 开始支持。
|
||||
|
||||
#### v1.1
|
||||
|
||||
待更新。
|
||||
|
||||
#### v2.0
|
||||
|
||||
待更新。
|
||||
|
||||
#### v3.1
|
||||
|
||||
待更新。
|
||||
|
||||
### ESP32-S2
|
||||
|
||||
#### v0.0
|
||||
|
||||
从 ESP-IDF v4.2 开始支持。
|
||||
|
||||
#### v1.0
|
||||
|
||||
| 发布分支 | 推荐版本 | 需求版本 |
|
||||
|------------------------|-------------|----------|
|
||||
| release/v4.2 | v4.2.3 | v4.2.3 |
|
||||
| release/v4.3 | v4.3.3 | v4.3.3 |
|
||||
| release/v4.4 | v4.4.1 | v4.4.1 |
|
||||
| release/v5.0 及以上 | v5.0 | v5.0 |
|
||||
|
||||
### ESP32-C3
|
||||
|
||||
#### v0.2 和 v0.3
|
||||
|
||||
从 ESP-IDF v4.3 开始支持。
|
||||
|
||||
#### v0.4
|
||||
|
||||
待更新。
|
||||
|
||||
### ESP32-S3
|
||||
|
||||
#### v0.1
|
||||
|
||||
从 ESP-IDF v4.4 开始支持。
|
||||
|
||||
#### v0.2
|
||||
|
||||
待更新。
|
||||
|
||||
### ESP32-C2 & ESP8684
|
||||
|
||||
#### v1.0
|
||||
|
||||
从 ESP-IDF v5.0 开始支持。
|
||||
|
||||
#### v1.1
|
||||
|
||||
待更新。
|
||||
|
||||
#### v1.2
|
||||
|
||||
待更新。
|
||||
|
||||
|
||||
## 如果 ESP-IDF 版本低于 `需求版本` 会出现什么情况？
|
||||
|
||||
使用最新的 ESP-IDF 版本时，软件会阻止下载二进制文件到不支持的芯片版本上，甚至可以防止二进制文件在不支持的芯片版本上被执行。v4.4.5+、v5.0.1+、v5.1 及以上版本的 ESP-IDF 都支持针对芯片版本的 esptool 下载检查和引导加载器加载检查，但 ESP-IDF v4.3.5 只支持 esptool 下载检查。
|
||||
|
||||
更早的 ESP-IDF 版本没有此类检查，若与芯片版本不兼容，芯片运行软件时可能会出现不可预测的行为。
|
||||
|
|
@ -28,6 +28,8 @@ The following table shows ESP-IDF support of Espressif SoCs where ![alt text][pr
|
|||
[supported]: https://img.shields.io/badge/-supported-green "supported"
|
||||
[preview]: https://img.shields.io/badge/-preview-orange "preview"
|
||||
|
||||
There are variants of revisions for a series of chips. See [Compatibility Between ESP-IDF Releases and Revisions of Espressif SoCs](https://github.com/espressif/esp-idf/blob/master/COMPATIBILITY.md) for the details of the compatibility between ESP-IDF and chip revisions.
|
||||
|
||||
Espressif SoCs released before 2016 (ESP8266 and ESP8285) are supported by [RTOS SDK](https://github.com/espressif/ESP8266_RTOS_SDK) instead.
|
||||
|
||||
# Developing With ESP-IDF
|
||||
|
|
|
|||
|
|
@ -28,6 +28,8 @@ ESP-IDF 是乐鑫官方推出的物联网开发框架，支持 Windows、Linux
|
|||
[supported]: https://img.shields.io/badge/-%E6%94%AF%E6%8C%81-green "supported"
|
||||
[preview]: https://img.shields.io/badge/-%E9%A2%84%E8%A7%88-orange "preview"
|
||||
|
||||
每款乐鑫芯片都可能有不同版本。建议参考 [ESP-IDF 版本与乐鑫芯片版本兼容性](https://github.com/espressif/esp-idf/blob/master/COMPATIBILITY_CN.md)，了解 ESP-IDF 版本与各芯片版本之间的兼容性。
|
||||
|
||||
对于 2016 年之前发布的乐鑫芯片（包括 ESP8266 和 ESP8285），请参考 [RTOS SDK](https://github.com/espressif/ESP8266_RTOS_SDK)。
|
||||
|
||||
# 使用 ESP-IDF 进行开发
|
||||
|
|
|
|||
|
|
@ -4,51 +4,54 @@ Chip Revision
|
|||
Overview
|
||||
--------
|
||||
|
||||
A new chip versioning logic was introduced in new chips. Chips have several eFuse version fields:
|
||||
{IDF_TARGET_NAME} may have different revisions. These revisions mainly fix some issues, sometimes also bring new features to the chip. :ref:`versioning scheme` describes the versioning of these chip revisions, and the APIs to read the versions at runtime.
|
||||
|
||||
There are some considerations of compatibility among application, ESP-IDF version, and chip revisions.
|
||||
|
||||
- Application may depends on some fixes/features provided by a chip revision.
|
||||
- When using updated version of hardware, sometimes it's not compatible with earlier version of ESP-IDF.
|
||||
|
||||
:ref:`revision_limitation` describes how the application can specify its requirement and the way ESP-IDF checks the compatibility. After that, there is troubleshooting information for this mechanism.
|
||||
|
||||
.. _versioning scheme:
|
||||
|
||||
Versioning Scheme
|
||||
-----------------
|
||||
|
||||
A new chip versioning logic was introduced in new chips. Chip Revision ``vX.Y``, where:
|
||||
|
||||
- ``X`` means Major wafer version. If it is changed, it means that the current software version is not compatible with this released chip and the software must be updated to use this chip.
|
||||
|
||||
- ``Y`` means Minor wafer version. If it is changed that means the current software version is compatible with the released chip, and there is no need to update the software.
|
||||
|
||||
The ``vX.Y`` chip version format is used further instead of the ECO number.
|
||||
|
||||
If the newly released chip does not have breaking changes, that means it can run the same software as the previous chip, then in that chip we keep the same major version and increment the minor version by 1. Otherwise, if there is a breaking change in the newly released chip, meaning it can not run the same software as the previous chip, then in that chip we increase the major version and set the minor version to 0.
|
||||
|
||||
The new versioning logic is being introduced to indicate the derivation relationship of chip revisions, and distinguish changes in chips as breaking changes and non-breaking changes.
|
||||
|
||||
Software is supposed to execute on a future chip revision with the same logic as the chip's nearest previous revision. This way user can directly port their compiled binaries to newer MINOR chip revisions without upgrading their ESP-IDF version and re-compile the whole project.
|
||||
|
||||
When a binary is executed on a chip revision of unexpected MAJOR revision, the software is also able to report issues according to the MAJOR revision.
|
||||
|
||||
The major and minor versioning scheme also allows hardware changes to be branchable.
|
||||
|
||||
EFuse Bits for Chip Revisions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Chips have several eFuse version fields:
|
||||
|
||||
- Major wafer version (``WAFER_VERSION_MAJOR`` eFuse)
|
||||
- Minor wafer version (``WAFER_VERSION_MINOR`` eFuse)
|
||||
- Ignore maximal revision (``DISABLE_WAFER_VERSION_MAJOR`` eFuse)
|
||||
|
||||
The new versioning logic is being introduced to distinguish changes in chips as breaking changes and non-breaking changes. Chips with non-breaking changes can run the same software as the previous chip. The previous chip means that the major version is the same.
|
||||
|
||||
If the newly released chip does not have breaking changes, that means it can run the same software as the previous chip, then in that chip we keep the same major version and increment the minor version by 1. Otherwise, if there is a breaking change in the newly released chip, meaning it cannot run the same software as the previous chip, then in that chip we increase the major version and set the minor version to 0.
|
||||
|
||||
The software supports a number of revisions, from the minimum to the maximum (the min/max configs are defined in Kconfig). If the software is unaware of a new chip (when the chip version is out of range), it will refuse to run on it unless the Ignore maximum revision restrictions bit is set. This bit removes the upper revision limit.
|
||||
|
||||
Minimum versions limits the software to only run on a chip revision that is high enough to support some features. Maximum version is the maximum version that is well-supported by current software. When chip version is above the maximum version, software will reject to boot, because it may not work on, or work with risk on the chip.
|
||||
|
||||
Adding the major and minor wafer revision make the versioning logic is branchable.
|
||||
- Ignore maximum revision (``DISABLE_WAFER_VERSION_MAJOR`` eFuse). See :ref:`revision_limitation` on how this is used.
|
||||
|
||||
.. note::
|
||||
|
||||
The previous versioning logic was based on a single eFuse version field (``WAFER_VERSION``). This approach makes it impossible to mark chips as breaking or non-breaking changes, and the versioning logic becomes linear.
|
||||
|
||||
Using the branched versioning scheme allows us to support more chips in the software without updating the software when a new released compatible chip is used. Thus, the software will be compatible with as many new chip revisions as possible. If the software is no longer compatible with a new chip with breaking changes, the software will abort.
|
||||
|
||||
Revisions
|
||||
---------
|
||||
|
||||
.. include:: inc/revisions_{IDF_TARGET_NAME}.rst
|
||||
|
||||
Chip Revision ``vX.Y``, where:
|
||||
|
||||
- ``X`` means Major wafer version. If it is changed, it means that the current software version is not compatible with this released chip and the software must be updated to use this chip.
|
||||
- ``Y`` means Minor wafer version. If it is changed that means the current software version is compatible with the released chip, and there is no need to update the software.
|
||||
|
||||
The ``vX.Y`` chip version format is used further instead of the ECO number.
|
||||
|
||||
Representing Revision Requirement Of A Binary Image
|
||||
---------------------------------------------------
|
||||
|
||||
The 2nd stage bootloader and the application binary images have the :cpp:type:`esp_image_header_t` header, which stores the revision numbers of the chip on which the software can be run. This header has 3 fields related to revisions:
|
||||
|
||||
- ``min_chip_rev`` - Minimal chip MAJOR revision required by image (but for ESP32-C3 it is MINOR revision). Its value is determined by :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN`.
|
||||
- ``min_chip_rev_full`` - Minimal chip MINOR revision required by image in format: ``major * 100 + minor``. Its value is determined by :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN`.
|
||||
- ``max_chip_rev_full`` - Maximal chip revision required by image in format: ``major * 100 + minor``. Its value is determined by ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``. It cannot be changed by user. Only Espressif can change it when a new version will be supported in ESP-IDF.
|
||||
|
||||
Chip Revision APIs
|
||||
------------------
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These APIs helps to get chip revision from eFuses:
|
||||
|
||||
|
|
@ -63,21 +66,22 @@ The following Kconfig definitions (in ``major * 100 + minor`` format) that can h
|
|||
- ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``
|
||||
- ``CONFIG_ESP_REV_MAX_FULL``
|
||||
|
||||
Maximal And Minimal Revision Restrictions
|
||||
-----------------------------------------
|
||||
|
||||
The order for checking the minimum and maximum revisions:
|
||||
.. _revision_limitation:
|
||||
|
||||
1. The 1st stage bootloader (ROM bootloader) does not check minimal and maximal revision fields from :cpp:type:`esp_image_header_t` before running the 2nd stage bootloader.
|
||||
Compatibility Checks of ESP-IDF
|
||||
-------------------------------
|
||||
|
||||
2. The 2nd stage bootloader checks at the initialization phase that bootloader itself can be launched on the chip of this revision. It extracts the minimum revision from the header of the bootloader image and checks against the chip revision from eFuses. If the chip revision is less than the minimum revision, the bootloader refuses to boot up and aborts. The maximum revision is not checked at this phase.
|
||||
The application supports a number of chip revisions, from the minimum to the maximum (the min/max configs are defined in Kconfig).
|
||||
|
||||
3. Then the 2nd stage bootloader checks the revision requirements of the application. It extracts the minimum and maximum revisions from the header of the application image and checks against the chip revision from eFuses. If the chip revision is less than the minimum revision or higher than the maximum revision, the bootloader refuses to boot up and aborts. However, if the Ignore maximal revision bit is set, the maximum revision constraint can be ignored. The ignore bit is set by the customer themself when there is confirmation that the software is able to work with this chip revision.
|
||||
Minimum version, selected by Kconfig option :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN`, limits the software to only run on a chip revision that is high enough to support some features or include some bugfixes.
|
||||
|
||||
4. Further, at the OTA update stage, the running application checks if the new software matches the chip revision. It extracts the minimum and maximum revisions from the header of the new application image and checks against the chip revision from eFuses. It checks for revision matching in the same way that the bootloader does, so that the chip revision is between the min and max revisions (logic of ignoring max revision also applies).
|
||||
Maximum version, determined by the version of ESP-IDF used, is the maximum chip revision that is well-supported by current ESP-IDF. It's usually ``maxinum supported MAJOR version + 99``. When chip revision is above the maximum version, it means that ESP-IDF is unaware of the new chip revision. In this case, software will reject to boot, unless the Ignore maximum revision restrictions bit is set (which bypasses the maximum revision limitation). However, the software may not work on, or work with risk on the chip.
|
||||
|
||||
Issues
|
||||
------
|
||||
Below is the information about troubleshooting when the chip revision fails the compatibility check. Then there are technical details of the checking and software behavior on earlier version of ESP-IDF.
|
||||
|
||||
Troubleshooting
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
1. If the 2nd stage bootloader is run on the chip revision < minimum revision shown in the image, a reboot occurs. The following message will be printed:
|
||||
|
||||
|
|
@ -90,7 +94,7 @@ To resolve this issue:
|
|||
- make sure the chip you are using is suitable for the software, or use a chip with the required minimum revision or higher.
|
||||
- update the software with :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` to get it ``<=`` the revision of chip being used
|
||||
|
||||
2. If application does not match minimal and maximal chip revisions, a reboot occurs. The following message will be printed:
|
||||
2. If application does not match minimum and maximum chip revisions, a reboot occurs. The following message will be printed:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
|
@ -98,8 +102,30 @@ To resolve this issue:
|
|||
|
||||
To resolve this issue, update the ESP-IDF to a newer version that supports the used chip (``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``). Another way to fix this is to set the ``Ignore maximal revision`` bit in eFuse or use a chip that is suitable for the software.
|
||||
|
||||
Representing Revision Requirement of a Binary Image
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The 2nd stage bootloader and the application binary images have the :cpp:type:`esp_image_header_t` header, which stores the revision numbers of the chip on which the software can be run. This header has 3 fields related to revisions:
|
||||
|
||||
- ``min_chip_rev`` - Minumum chip MAJOR revision required by image (but for ESP32-C3 it is MINOR revision). Its value is determined by :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN`.
|
||||
- ``min_chip_rev_full`` - Minimum chip MINOR revision required by image in format: ``major * 100 + minor``. Its value is determined by :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN`.
|
||||
- ``max_chip_rev_full`` - Maximum chip revision required by image in format: ``major * 100 + minor``. Its value is determined by ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``. It can not be changed by user. Only Espressif can change it when a new version will be supported in ESP-IDF.
|
||||
|
||||
Maximum And Minumum Revision Restrictions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The order for checking the minimum and maximum revisions:
|
||||
|
||||
1. The 1st stage bootloader (ROM bootloader) does not check minimum and maximum revision fields from :cpp:type:`esp_image_header_t` before running the 2nd stage bootloader.
|
||||
|
||||
2. The 2nd stage bootloader checks at the initialization phase that bootloader itself can be launched on the chip of this revision. It extracts the minimum revision from the header of the bootloader image and checks against the chip revision from eFuses. If the chip revision is less than the minimum revision, the bootloader refuses to boot up and aborts. The maximum revision is not checked at this phase.
|
||||
|
||||
3. Then the 2nd stage bootloader checks the revision requirements of the application. It extracts the minimum and maximum revisions from the header of the application image and checks against the chip revision from eFuses. If the chip revision is less than the minimum revision or higher than the maximum revision, the bootloader refuses to boot up and aborts. However, if the Ignore maximum revision bit is set, the maximum revision constraint can be ignored. The ignore bit is set by the customer themself when there is confirmation that the software is able to work with this chip revision.
|
||||
|
||||
4. Further, at the OTA update stage, the running application checks if the new software matches the chip revision. It extracts the minimum and maximum revisions from the header of the new application image and checks against the chip revision from eFuses. It checks for revision matching in the same way that the bootloader does, so that the chip revision is between the min and max revisions (logic of ignoring max revision also applies).
|
||||
|
||||
Backward Compatible With Bootloaders Built By Older ESP-IDF Versions
|
||||
--------------------------------------------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32 or esp32c3 or esp32s2 or esp32s3
|
||||
|
||||
|
|
@ -123,6 +149,14 @@ Backward Compatible With Bootloaders Built By Older ESP-IDF Versions
|
|||
|
||||
Please check the chip version using ``esptool chip_id`` command.
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
- `Compatibility Advisory for Chip Revision Numbering Scheme <https://www.espressif.com.cn/sites/default/files/advisory_downloads/AR2022-005%20Compatibility%20Advisory%20for%20Chip%20Revision%20Numbering%20%20Scheme.pdf>`_
|
||||
- `Compatibility Between ESP-IDF Releases and Revisions of Espressif SoCs <https://github.com/espressif/esp-idf/blob/master/COMPATIBILITY.md>`_
|
||||
- `SoC Errata <https://www.espressif.com.cn/en/support/documents/technical-documents?keys=errata>`_
|
||||
- :doc:`/versions`
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ The full history of releases can be found on the GitHub repository `Releases pag
|
|||
Which Version Should I Start With?
|
||||
----------------------------------
|
||||
|
||||
- For production purposes, use the `current stable version`_. Stable versions have been manually tested, and are updated with "bugfix releases" which fix bugs without changing other functionality (see `Versioning Scheme`_ for more details). Every stable release version can be found on the `Releases page`_.
|
||||
- For production purposes, use the `current stable version`_. Stable versions have been manually tested, and are updated with "bugfix releases" which fix bugs without changing other functionality (see `Versioning Scheme`_ for more details). Every stable release version can be found on the `Releases page`_. Also refer to `Compatibility Between ESP-IDF Releases and Revisions of Espressif SoCs <https://github.com/espressif/esp-idf/blob/master/COMPATIBILITY.md>`_ to make sure the ESP-IDF version you selected is compatible with the chip revision you are going to produce with.
|
||||
|
||||
- For prototyping, experimentation or for developing new ESP-IDF features, use the `latest version (master branch in Git) <https://docs.espressif.com/projects/esp-idf/en/latest/>`_. The latest version in the master branch has all the latest features and has passed automated testing, but has not been completely manually tested ("bleeding edge").
|
||||
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。
|
|||
我该选择哪个版本？
|
||||
----------------------
|
||||
|
||||
- 如有量产需求，请使用 `最新稳定版本`_ 。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 :ref:`versioning-scheme` ）。请访问 `发布说明页面`_ 界面查看每一个稳定发布版本。
|
||||
- 如有量产需求，请使用 `最新稳定版本`_ 。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 :ref:`versioning-scheme` ）。请访问 `发布说明页面`_ 界面查看每一个稳定发布版本。另外，为确保使用的 ESP-IDF 版本与需生产的芯片版本兼容，可参考 `ESP-IDF 版本与乐鑫芯片版本兼容性 <https://github.com/espressif/esp-idf/blob/master/COMPATIBILITY_CN.md>`_。
|
||||
|
||||
- 如需尝试/测试 ESP-IDF 的最新特性，请使用 `最新版本（在 master 分支上） <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/>`_。最新版本包含 ESP-IDF 的所有最新特性，已通过自动化测试，但尚未全部完成人工测试（因此存在一定风险）。
|
||||
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue