kopia lustrzana https://github.com/espressif/esp-idf
docs: Provide Chinese translation for api-reference/system/chip_revision.rst
renpeiying
rodzic
1af5e870f1
commit
cd1133df82
|
|
@ -1,40 +1,44 @@
|
|||
Chip Revision
|
||||
=============
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
{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.
|
||||
{IDF_TARGET_NAME} may have different revisions. These revisions mainly fix some issues, and 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.
|
||||
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.
|
||||
- Applications may depend on some fixes/features provided by a chip revision.
|
||||
- When using updated version of hardware, the hardware may be incompatible with earlier versions 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.
|
||||
:ref:`revision_limitation` describes how the application can specify its chip revision requirements, 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:
|
||||
A chip's revision number is typically expressed as ``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.
|
||||
- ``X`` means a **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.
|
||||
- ``Y`` means a **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 a newly released chip does not contain breaking changes, the chip can run the same software as the previous chip. As such, the new chip's revision number will only increment the minor version while keeping the major version the same (e.g., ``v1.1`` to ``v1.2``).
|
||||
|
||||
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.
|
||||
Conversely, if a newly released chip contains breaking changes, the chip **cannot** run the same software as the previous chip. As such, the new chip's revision number will increment the major version and set the minor version to 0 (e.g., ``v1.1`` to ``v2.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.
|
||||
This versioning scheme was selected to indicate the derivation relationship of chip revisions, and clearly distinguish changes in chips between 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.
|
||||
ESP-IDF is designed to execute seamlessly on future chip minor revisions with the same logic as the chip's nearest previous minor revision. Thus，users 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.
|
||||
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.
|
||||
|
||||
The major and minor versioning scheme also allows hardware changes to be branchable.
|
||||
.. note::
|
||||
|
||||
The current chip revision scheme using major and minor versions was introduced from ESP-IDF v5.0 onwards. Thus bootloaders built using earlier versions of ESP-IDF will still use the legacy chip revision scheme of wafer versions.
|
||||
|
||||
EFuse Bits for Chip Revisions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -72,27 +76,27 @@ The following Kconfig definitions (in ``major * 100 + minor`` format) that can h
|
|||
Compatibility Checks of ESP-IDF
|
||||
-------------------------------
|
||||
|
||||
The application supports a number of chip revisions, from the minimum to the maximum (the min/max configs are defined in Kconfig).
|
||||
When building an application that needs to support multiple revisions of a particular chip, the minimum and maximum chip revision numbers supported by the build are specified via Kconfig.
|
||||
|
||||
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.
|
||||
The minimum chip revision can be configured via the :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` option. Specifying the minimum chip revision will limit the software to only run on a chip revisions that are high enough to support some features or bugfixes.
|
||||
|
||||
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.
|
||||
The maximum chip revision cannot be configured and is automatically determined by the current ESP-IDF version being used. ESP-IDF will refuse to boot any chip revision exceeding the maximum chip revision. Given that it is impossible for a particular ESP-IDF version to foresee all future chip revisions, the maximum chip revision is usually set to ``maximum supported MAJOR version + 99``. The "Ignore Maximum Revision" eFuse can be set to bypass the maximum revision limitation. However, the software is not guaranteed to work if the maximum revision is ignored.
|
||||
|
||||
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:
|
||||
1. If the 2nd stage bootloader is run on a chip revision smaller than minimum revision specified in the image (i.e., the application), a reboot occurs. The following message will be printed:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Image requires chip rev >= v3.0, but chip is v1.0
|
||||
|
||||
To resolve this issue:
|
||||
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
|
||||
- Use a chip with the required minimum revision or higher.
|
||||
- Lower the :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` value and rebuild the image so that it is compatible with the chip revision being used.
|
||||
|
||||
2. If application does not match minimum and maximum chip revisions, a reboot occurs. The following message will be printed:
|
||||
|
||||
|
|
@ -100,32 +104,32 @@ To resolve this issue:
|
|||
|
||||
Image requires chip rev <= v2.99, but chip is v3.0
|
||||
|
||||
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.
|
||||
To resolve this issue, update ESP-IDF to a newer version that supports the chip's revision (``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``). Alternatively, set the ``Ignore maximal revision`` bit in eFuse or use a chip revision that is compatible with the current version of ESP-IDF.
|
||||
|
||||
Representing Revision Requirement of a Binary Image
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Representing Revision Requirements 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:
|
||||
The 2nd stage bootloader and the application binary images contain the :cpp:type:`esp_image_header_t` header, which stores information specifying the chip revisions that the image is permitted to run on. 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`` - Minimum 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
|
||||
Maximum And Minimum Revision Restrictions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The order for checking the minimum and maximum revisions:
|
||||
The order for checking the minimum and maximum revisions during application boot up is as follows:
|
||||
|
||||
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.
|
||||
2. The initialization phase of the 2nd stage bootloader checks that the 2nd stage 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.
|
||||
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 themselves 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).
|
||||
4. Furthermore, 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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Backward Compatibility with Bootloaders Built by Older ESP-IDF Versions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32 or esp32c3 or esp32s2 or esp32s3
|
||||
|
||||
|
|
@ -133,19 +137,19 @@ Backward Compatible With Bootloaders Built By Older ESP-IDF Versions
|
|||
|
||||
.. only:: esp32
|
||||
|
||||
The old bootloaders did not read the minor wafer version eFuse, the major version can be only <= v3. So it means that the old bootloader can detect correctly only chip version in range v0.0 - v3.0, where the minor version is always set to 0.
|
||||
The old bootloaders did not read the minor wafer version eFuse, and the major version can be only lower than or equal to v3. This means that the old bootloader can detect correctly only chip version in range ``v0.0`` to ``v3.0``, where the minor version is always set to ``0``.
|
||||
|
||||
.. only:: esp32c2
|
||||
|
||||
{IDF_TARGET_NAME} chip support was added in ESP-IDF v5.0. The bootloader is able to detect any chip versions in range v0.0 - v3.15.
|
||||
{IDF_TARGET_NAME} chip support was added in ESP-IDF v5.0. The bootloader is able to detect any chip versions in range ``v0.0`` to ``v3.15``.
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
{IDF_TARGET_NAME} chip support was added in ESP-IDF v4.3. The old bootloaders cannot read all bits of the wafer version eFuse, it can read only the first 3 low bits. So it means that the old bootloader cannot detect chip version correctly. Chips v0.0 - v0.8 are detected correctly, but other chip versions will be recognized as a version from this range.
|
||||
{IDF_TARGET_NAME} chip support was added in ESP-IDF v4.3. The old bootloaders cannot read all bits of the wafer version eFuse, it can read only the first 3 least significant bits. This means that the old bootloader cannot detect chip version correctly. Chips ``v0.0`` to ``v0.8`` are detected correctly, but other chip versions will be recognized as a version from this range.
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
{IDF_TARGET_NAME} chip support was added in ESP-IDF v4.2. {IDF_TARGET_NAME} chips have ``rev_min`` in :cpp:type:`esp_image_header_t` header = 0 because ``Minimum Supported ESP32-S2 Revision`` Kconfig option was not introduced, which means that the old bootloader does not check the chip revision. Any app can be loaded by such bootloader in range v0.0 - v3.15.
|
||||
{IDF_TARGET_NAME} chip support was added in ESP-IDF v4.2. {IDF_TARGET_NAME} chips have ``rev_min`` in :cpp:type:`esp_image_header_t` header set to ``0`` because ``Minimum Supported ESP32-S2 Revision`` Kconfig option was not introduced, which means that the old bootloader does not check the chip revision. Any app can be loaded by such bootloader in range ``v0.0`` to ``v3.15``.
|
||||
|
||||
Please check the chip version using ``esptool chip_id`` command.
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1,167 @@
|
|||
.. include:: ../../../en/api-reference/system/chip_revision.rst
|
||||
芯片版本
|
||||
=============
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
{IDF_TARGET_NAME} 可能包含多个芯片版本。引入不同的版本主要用于修复问题，有时也用于添加新功能。:ref:`versioning scheme` 描述了这些芯片修订的版本以及运行时读取版本信息所用的 API。
|
||||
|
||||
须考虑应用程序、ESP-IDF 版本和芯片版本之间的兼容性：
|
||||
|
||||
- 应用程序可能依赖于某个芯片版本的修复内容或功能。
|
||||
- 较新版本的硬件可能与较早版本的 ESP-IDF 不兼容。
|
||||
|
||||
本文档的 :ref:`revision_limitation` 部分描述了应用程序如何明确芯片版本需求，以及 ESP-IDF 如何对兼容性进行检查。文档最后提供了此方案的故障排除相关信息。
|
||||
|
||||
.. _versioning scheme:
|
||||
|
||||
版本控制方案
|
||||
-----------------
|
||||
|
||||
芯片版本号通常以 ``vX.Y`` 的形式表示，其中：
|
||||
|
||||
- ``X`` 表示主版本号。该号码变更表示在旧版芯片上使用的软件与新版芯片不兼容，必须升级软件方可使用。
|
||||
|
||||
- ``Y`` 表示次版本号。该号码变更表示在旧版芯片上使用的软件与新版芯片兼容，无需升级软件。
|
||||
|
||||
如果新版芯片不包含重大变更，则可以兼容旧版芯片上运行的软件。此时，新版芯片的主版本号不变，次版本号加 1。例如，版本号从 ``v1.1`` 变为 ``v1.2``。
|
||||
|
||||
相反，如果新版芯片包含重大变更，则 **无法兼容** 旧版芯片的软件。此时，新版芯片的主版本号增加，次版本号设置为 0。例如，版本号从 ``v1.1`` 变为 ``v2.0``。
|
||||
|
||||
此版本控制方式能够表示芯片版本之间的衍生关系，并清晰表明芯片变更是否为重大变更。
|
||||
|
||||
在芯片发生非重大变更时，ESP-IDF 的执行逻辑应与此前最近版本的逻辑相同，从而达到无缝衔接。在这样便可直接将编译后的二进制文件迁移到更新了次版本的芯片上，无需升级 ESP-IDF 版本并重新编译整个项目。
|
||||
|
||||
当二进制文件在更新了主版本的芯片上意外执行时，软件也能够根据主版本报告问题。此主次版本方案还允许硬件变更分支化。
|
||||
|
||||
.. note::
|
||||
|
||||
目前的主次版本号芯片版本方案是从 ESP-IDF v5.0 开始引入的。因此，早期 ESP-IDF 创建的引导加载程序将继续使用晶圆版本表示的芯片版本方案。
|
||||
|
||||
用于芯片版本的 eFuse 位
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
芯片使用以下几个 eFuse 字段来进行版本控制：
|
||||
|
||||
- 主版本号 (``WAFER_VERSION_MAJOR`` eFuse)
|
||||
- 次版本号 (``WAFER_VERSION_MINOR`` eFuse)
|
||||
- 忽略最大版本限制位 (``DISABLE_WAFER_VERSION_MAJOR`` eFuse)。请参考 :ref:`revision_limitation` 了解此 eFuse 字段。
|
||||
|
||||
.. note::
|
||||
|
||||
此前的版本控制逻辑基于单一的 eFuse 版本字段，即 ``WAFER_VERSION``。这种方式无法表明芯片的更新是否为重大更新，是一种线性的版本控制逻辑。
|
||||
|
||||
|
||||
芯片版本 API
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
使用下列 API 从 eFuse 中读取芯片版本：
|
||||
|
||||
- :cpp:func:`efuse_hal_chip_revision`，返回的版本格式为 ``major * 100 + minor``。
|
||||
- :cpp:func:`efuse_hal_get_major_chip_version` 返回主版本号。
|
||||
- :cpp:func:`efuse_hal_get_minor_chip_version` 返回次版本号。
|
||||
|
||||
下列 Kconfig 选项（格式为 ``major * 100 + minor``）可以将芯片版本依赖添加到代码中：
|
||||
|
||||
- ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN_FULL``
|
||||
- ``CONFIG_ESP_REV_MIN_FULL``
|
||||
- ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``
|
||||
- ``CONFIG_ESP_REV_MAX_FULL``
|
||||
|
||||
|
||||
.. _revision_limitation:
|
||||
|
||||
ESP-IDF 兼容性检查
|
||||
-------------------------------
|
||||
|
||||
如果构建的应用程序需要支持特定芯片的多个版本，可通过 Kconfig 指定支持的最小和最大芯片版本号。
|
||||
|
||||
最小芯片版本号可以通过 Kconfig 选项 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 来选择。设置最小芯片版本后，软件只能在较新的芯片版本上运行，以便支持某些功能或修复某些错误。
|
||||
|
||||
最大芯片版本号无法指定，只能由当前使用的 ESP-IDF 版本自动决定。ESP-IDF 会拒绝启动任何超过最大芯片版本号的芯片版本。由于特定版本的 ESP-IDF 无法预知未来的芯片版本更新，因此最大芯片版本号通常设置为 ``maxinum supported MAJOR version + 99``。可以设置 “忽略最大版本” eFuse 来绕过最大版本限制，但这不能确保软件正常工作。
|
||||
|
||||
下文介绍了芯片版本未通过兼容性检查时显示的故障排除信息及解决方法，并描述了在早期 ESP-IDF 版本中与软件行为和兼容性检查相关的技术细节。
|
||||
|
||||
故障排除
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
1. 如果第二阶段引导加载程序所运行的芯片版本低于镜像（如软件镜像）中指定的最小版本，会发生重启并显示以下消息：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Image requires chip rev >= v3.0, but chip is v1.0
|
||||
|
||||
要解决此问题，
|
||||
|
||||
- 确保使用的芯片达到了要求的最低版本及以上。
|
||||
- 减小 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 的值并重建镜像，使镜像的版本与当前芯片版本兼容。
|
||||
|
||||
1. 如果应用程序所需的芯片版本不处于最小和最大芯片版本的区间范围内，会发生重启并显示以下消息：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Image requires chip rev <= v2.99, but chip is v3.0
|
||||
|
||||
为解决此问题，需更新 ESP-IDF 到较新版本，以支持该芯片版本 (``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``)。也可以在 eFuse 中设置 ``Ignore maximal revision`` 位，或使用与当前 ESP-IDF 版本兼容的其他芯片版本。
|
||||
|
||||
二进制镜像的常见版本需求
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
二级引导程序和应用程序二进制镜像中包含 :cpp:type:`esp_image_header_t` 头文件，其中记录了可以运行该软件的芯片版本号。这一头文件有 3 个与版本相关的字段：
|
||||
|
||||
- ``min_chip_rev`` - 镜像所需芯片的最小主版本号（但对于 ESP32-C3，该字段指次版本号）。其值由 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 确定。
|
||||
- ``min_chip_rev_full`` - 镜像所需芯片的最小次版本号，格式为 ``major * 100 + minor``。其值由 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 确定。
|
||||
- ``max_chip_rev_full`` - 镜像所需芯片的最大版本，格式为 ``major * 100 + minor``。其值由 ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL`` 确定。用户无法对其进行修改，仅当 ESP-IDF 支持新版本时由乐鑫官方进行更改。
|
||||
|
||||
最大和最小版本限制
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
应用启动过程中，检查最小和最大版本的顺序如下：
|
||||
|
||||
1. 在运行第 2 阶段引导启动程序前，第 1 阶段引导启动程序（ROM 引导启动程序）不会在 :cpp:type:`esp_image_header_t` 中检查最小和最大版本字段。
|
||||
|
||||
2. 在第 2 阶段引导启动程序的初始化阶段，会检查引导程序自身是否可以在此版本的芯片上启动。它从引导启动程序镜像的头文件中读取最小版本，并与 eFuse 中的芯片版本进行比较。如果芯片版本低于最小版本，引导启动程序会拒绝启动并中止运行。此阶段不检查最大版本。
|
||||
|
||||
3. 然后，第 2 阶段引导启动程序会检查应用程序的版本要求。它从应用程序镜像的头文件中读取最小和最大版本，并与 eFuse 中的芯片版本进行比较。如果该芯片版本低于最小版本或高于最大版本，引导程序会拒绝启动并中止。然而，如果设置了忽略最大版本位，则可以忽略最大版本限制。软件确定可以使用此芯片版本时，用户可以自行设置忽略位。
|
||||
|
||||
4. 在空中升级 (OTA) 阶段，运行中的应用程序会检查新软件是否与芯片版本相匹配。它会从新应用程序镜像的标头中提取最小和最大版本，并与 eFuse 中的芯片版本进行比较。应用程序检查版本匹配的方式与引导启动程序相同，即芯片版本须处在最小和最大版本之间（忽略最大版本的逻辑也相同）。
|
||||
|
||||
向后兼容旧版 ESP-IDF 构建的引导启动程序
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: esp32 or esp32c3 or esp32s2 or esp32s3
|
||||
|
||||
主要版本号和次版本号的 eFuse 位对于旧版引导启动程序（由早于 v5.0 版本的 ESP-IDF 进行构建）而言是未知的。旧版启动引导程序只使用一个 eFuse 位来表示芯片版本。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
旧版引导启动程序不读取次版本号的 eFuse 位，且主版本号只能低于或等于 v3。这表明，旧版引导启动程序只能正确检测范围在 ``v0.0`` 至 ``v3.0`` 的芯片版本，其中，次版本号总是设置为 ``0``。
|
||||
|
||||
.. only:: esp32c2
|
||||
|
||||
ESP-IDF v5.0 中添加了对 {IDF_TARGET_NAME} 芯片的支持。引导启动程序能够检测范围在 ``v0.0`` 至 ``v3.15`` 内的所有芯片版本。
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
在 ESP-IDF v4.3 中添加了对 {IDF_TARGET_NAME} 芯片的支持。旧版引导启动程序无法读取晶圆版本 eFuse 的所有位，只能读取前 3 个最低有效位。因此，旧版引导启动程序无法正确检测芯片版本。具体而言，只能正确检测 ``v0.0`` 至 ``v0.8`` 范围内的芯片版本，其他芯片版本则会被错误识别为该范围内的某个版本。
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
在 ESP-IDF v4.2 中添加了对 {IDF_TARGET_NAME} 芯片的支持。 由于 ``Minimum Supported ESP32-S2 Revision`` Kconfig 选项未引入，{IDF_TARGET_NAME} 芯片在 :cpp:type:`esp_image_header_t` 头文件中将 ``rev_min`` 设置为 0。这表明旧版引导启动程序不会检查芯片版本。在 v0.0 至 v3.15 范围内，任何应用程序都可以通过此类引导加载程序加载。
|
||||
|
||||
请使用 ``esptool chip_id`` 命令查看芯片版本。
|
||||
|
||||
参考链接
|
||||
----------
|
||||
|
||||
- `芯片版本编号方案兼容指南 <https://www.espressif.com.cn/sites/default/files/advisory_downloads/AR2022-005%20Compatibility%20Advisory%20for%20Chip%20Revision%20Numbering%20%20Scheme.pdf>`_
|
||||
- `ESP-IDF 版本与乐鑫芯片版本兼容性 <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 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/efuse_hal.inc
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue