mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs(chip_revision): update eFuse block revision info
This commit is contained in:
laokaiyao
parent
f71f0fc627
commit
f3879f7615
@ -47,12 +47,20 @@ Chips have several eFuse version fields:
|
||||
|
||||
- Major wafer version (``WAFER_VERSION_MAJOR`` eFuse)
|
||||
- Minor wafer version (``WAFER_VERSION_MINOR`` eFuse)
|
||||
- Ignore maximum revision (``DISABLE_WAFER_VERSION_MAJOR`` eFuse). See :ref:`revision_limitation` on how this is used.
|
||||
- Ignore maximum wafer 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.
|
||||
|
||||
EFuse Bits for eFuse Block Revisions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
EFuse block has version fields:
|
||||
|
||||
- Major efuse block version (``BLK_VERSION_MAJOR`` eFuse)
|
||||
- Minor efuse block version (``BLK_VERSION_MINOR`` eFuse)
|
||||
- Ignore maximum efuse block revision (``DISABLE_BLK_VERSION_MAJOR`` eFuse). See :ref:`revision_limitation` on how this is used.
|
||||
|
||||
Chip Revision APIs
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
@ -60,8 +68,8 @@ Chip Revision APIs
|
||||
These APIs helps to get chip revision from eFuses:
|
||||
|
||||
- :cpp:func:`efuse_hal_chip_revision`. It returns revision in the ``major * 100 + minor`` format.
|
||||
- :cpp:func:`efuse_hal_get_major_chip_version`. It returns Major revision.
|
||||
- :cpp:func:`efuse_hal_get_minor_chip_version`. It returns Minor revision.
|
||||
- :cpp:func:`efuse_hal_get_major_chip_version`. It returns Major revision of wafer.
|
||||
- :cpp:func:`efuse_hal_get_minor_chip_version`. It returns Minor revision of wafer.
|
||||
|
||||
The following Kconfig definitions (in ``major * 100 + minor`` format) that can help add the chip revision dependency to the code:
|
||||
|
||||
@ -70,6 +78,19 @@ 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``
|
||||
|
||||
EFuse Block Revision APIs
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These APIs helps to get eFuse block revision from eFuses:
|
||||
|
||||
- :cpp:func:`efuse_hal_blk_version`. It returns revision in the ``major * 100 + minor`` format.
|
||||
- :cpp:func:`efuse_ll_get_blk_version_major`. It returns Major revision of eFuse block.
|
||||
- :cpp:func:`efuse_ll_get_blk_version_minor`. It returns Minor revision of eFuse block.
|
||||
|
||||
The following Kconfig definitions (in ``major * 100 + minor`` format) that can help add the eFuse block revision dependency to the code:
|
||||
|
||||
- :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL`
|
||||
- :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL`
|
||||
|
||||
.. _revision_limitation:
|
||||
|
||||
@ -82,6 +103,8 @@ The minimum chip revision can be configured via the :ref:`CONFIG_{IDF_TARGET_CFG
|
||||
|
||||
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.
|
||||
|
||||
The eFuse block revision is similar to the chip revision, but it mainly affects the coefficients that are specified in the eFuse (e.g. ADC calibration coefficients). If eFuse block revision is not important in your application, you can also ignore this check by enabling :ref:`CONFIG_ESP_IGNORE_EFUSE_BLOCK_REV_CHECK`
|
||||
|
||||
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
|
||||
@ -109,12 +132,17 @@ To resolve this issue, update ESP-IDF to a newer version that supports the chip'
|
||||
Representing Revision Requirements of a Binary Image
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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:
|
||||
For the chip revision, 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 the chip revisions:
|
||||
|
||||
- ``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.
|
||||
|
||||
For the eFuse revision, the requirements are stored in :cpp:type:`esp_app_desc_t`, which is contained in the application binary image. We only check the application image because the eFuse block revision mostly affects the ADC calibration, which does not really matter in the bootloader. There are 2 fields related to eFuse block revisions:
|
||||
|
||||
- ``min_efuse_blk_rev_full`` - Minimum eFuse block MINOR revision required by image in format: ``major * 100 + minor``. Its value is determined by ``CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL``.
|
||||
- ``max_efuse_blk_rev_full`` - Maximum eFuse block MINOR revision required by image in format: ``major * 100 + minor``. Its value is determined by ``CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL``. Since it is a hardware specific value, it should not be changed by user. Espressif shall update it appropriately when a new eFuse block version is supported in ESP-IDF.
|
||||
|
||||
Maximum And Minimum Revision Restrictions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -124,9 +152,14 @@ The order for checking the minimum and maximum revisions during application boot
|
||||
|
||||
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 themselves 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 of the chip from the application image header, and the eFuse block from the segment header. Then the bootloader checks these versions against the chip and eFuse block revision from eFuses. If the these revisions are less than their 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 bits are set by the customer themselves when there is confirmation that the software is able to work with this chip revision or eFuse block revision.
|
||||
|
||||
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).
|
||||
4. Then at the start-up stage of the application image, the efuse block revision will be checked. The minimum and maximum requirements of the eFuse block revision come from the following Kconfig macros,
|
||||
|
||||
* :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL`
|
||||
* :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL`
|
||||
|
||||
5. Furthermore, at the OTA update stage, the running application checks if the new software matches the chip revision and eFuse block revision. It extracts the minimum and maximum chip revisions from the header of the new application image and the eFuse block constraints from the application description to check against the these revisions from eFuses. It checks for revisions matching in the same way that the bootloader does, so that the chip and eFuse block revisions are between their min and max revisions (logic of ignoring max revision also applies).
|
||||
|
||||
Backward Compatibility with Bootloaders Built by Older ESP-IDF Versions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -45,14 +45,22 @@
|
||||
|
||||
芯片使用以下几个 eFuse 字段来进行版本控制：
|
||||
|
||||
- 主版本号 (``WAFER_VERSION_MAJOR`` eFuse)
|
||||
- 次版本号 (``WAFER_VERSION_MINOR`` eFuse)
|
||||
- 忽略最大版本限制位 (``DISABLE_WAFER_VERSION_MAJOR`` eFuse)。请参考 :ref:`revision_limitation` 了解此 eFuse 字段。
|
||||
- 主芯片版本号 (``WAFER_VERSION_MAJOR`` eFuse)
|
||||
- 次芯片版本号 (``WAFER_VERSION_MINOR`` eFuse)
|
||||
- 忽略最大芯片版本限制位 (``DISABLE_WAFER_VERSION_MAJOR`` eFuse)。请参考 :ref:`revision_limitation` 了解此 eFuse 字段。
|
||||
|
||||
.. note::
|
||||
|
||||
此前的版本控制逻辑基于单一的 eFuse 版本字段，即 ``WAFER_VERSION``。这种方式无法表明芯片的更新是否为重大更新，是一种线性的版本控制逻辑。
|
||||
|
||||
用于 eFuse 块版本的 eFuse 位
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
EFuse 既有以下几个版本字段：
|
||||
|
||||
- 主 eFuse 块版本号 (``BLK_VERSION_MAJOR`` eFuse)
|
||||
- 次 efuse 块版本号 (``BLK_VERSION_MINOR`` eFuse)
|
||||
- 忽略最大 efuse 块版本限制位 (``DISABLE_BLK_VERSION_MAJOR`` eFuse). 请参考 :ref:`revision_limitation` 了解此 eFuse 字段。
|
||||
|
||||
芯片版本 API
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
@ -60,8 +68,8 @@
|
||||
使用下列 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` 返回次版本号。
|
||||
- :cpp:func:`efuse_hal_get_major_chip_version` 返回主芯片版本号。
|
||||
- :cpp:func:`efuse_hal_get_minor_chip_version` 返回次芯片版本号。
|
||||
|
||||
下列 Kconfig 选项（格式为 ``major * 100 + minor``）可以将芯片版本依赖添加到代码中：
|
||||
|
||||
@ -70,6 +78,19 @@
|
||||
- ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``
|
||||
- ``CONFIG_ESP_REV_MAX_FULL``
|
||||
|
||||
EFuse 块版本 API
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
使用下列 API 从 eFuse 中读取 eFuse 块版本：
|
||||
|
||||
- :cpp:func:`efuse_hal_blk_version`，返回的版本格式为 ``major * 100 + minor``。
|
||||
- :cpp:func:`efuse_ll_get_blk_version_major`。 返回主 eFuse 块版本号
|
||||
- :cpp:func:`efuse_ll_get_blk_version_minor`。 返回次 eFuse 块版本号
|
||||
|
||||
下列 Kconfig 选项（格式为 ``major * 100 + minor``）可以将 eFuse 块版本依赖添加到代码中：
|
||||
|
||||
- :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL`
|
||||
- :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL`
|
||||
|
||||
.. _revision_limitation:
|
||||
|
||||
@ -80,7 +101,9 @@ ESP-IDF 兼容性检查
|
||||
|
||||
最小芯片版本号可以通过 Kconfig 选项 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 来选择。设置最小芯片版本后，软件只能在较新的芯片版本上运行，以便支持某些功能或修复某些错误。
|
||||
|
||||
最大芯片版本号无法指定，只能由当前使用的 ESP-IDF 版本自动决定。ESP-IDF 会拒绝启动任何超过最大芯片版本号的芯片版本。由于特定版本的 ESP-IDF 无法预知未来的芯片版本更新，因此最大芯片版本号通常设置为 ``maxinum supported MAJOR version + 99``。可以设置 “忽略最大版本” eFuse 来绕过最大版本限制，但这不能确保软件正常工作。
|
||||
最大芯片版本号无法指定，只能由当前使用的 ESP-IDF 版本自动决定。ESP-IDF 会拒绝启动任何超过最大芯片版本号的芯片版本。由于特定版本的 ESP-IDF 无法预知未来的芯片版本更新，因此最大芯片版本号通常设置为 ``maximum supported MAJOR version + 99``。可以设置 “忽略最大版本” eFuse 来绕过最大版本限制，但这不能确保软件正常工作。
|
||||
|
||||
EFuse 块版本号与芯片版本号类似，但是它主要影响在 eFuse 中指定的参数（如 ADC 校正参数等）。如果 eFuse 块版本号在您的应用中并不重要，你可以通过使能 Kconfig 选项 :ref:`CONFIG_ESP_IGNORE_EFUSE_BLOCK_REV_CHECK` 来禁用 eFuse 块版本号检查。
|
||||
|
||||
下文介绍了芯片版本未通过兼容性检查时显示的故障排除信息及解决方法，并描述了在早期 ESP-IDF 版本中与软件行为和兼容性检查相关的技术细节。
|
||||
|
||||
@ -109,11 +132,16 @@ ESP-IDF 兼容性检查
|
||||
二进制镜像的常见版本需求
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
二级引导程序和应用程序二进制镜像中包含 :cpp:type:`esp_image_header_t` 头文件，其中记录了可以运行该软件的芯片版本号。这一头文件有 3 个与版本相关的字段：
|
||||
芯片版本号检查主要根据二级引导程序和应用程序二进制镜像中包含的 :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 支持新版本时由乐鑫官方进行更改。
|
||||
- ``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 支持新版本时由乐鑫官方进行更改。
|
||||
|
||||
而 eFuse 块版本的要求则存储在 :cpp:type:`esp_app_desc_t` 结构体中。该结构体对象位于应用程序的二进制进项文件中。由于 eFuse 块版本信息主要影响 ADC 校准，而二级引导程序的镜像不涉及 ADC，因此我们只需要检查应用程序镜像的 eFuse 块版本信息。有 2 个与 eFuse 块版本相关的字段：
|
||||
|
||||
- ``min_efuse_blk_rev_full`` - 镜像所需 eFuse 块的最小版本号，格式为 ``major * 100 + minor``。其值由 ``CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL`` 确定。
|
||||
- ``max_efuse_blk_rev_full`` - 镜像所需 eFuse 块的最大版本号，格式为 ``major * 100 + minor``。其值由 ``CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL`` 确定。这个值由硬件决定，用户不应对其进行修改，仅当 ESP-IDF 支持新版本时由乐鑫官方进行更改。
|
||||
|
||||
最大和最小版本限制
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -122,11 +150,16 @@ ESP-IDF 兼容性检查
|
||||
|
||||
1. 在运行第 2 阶段引导启动程序前，第 1 阶段引导启动程序（ROM 引导启动程序）不会在 :cpp:type:`esp_image_header_t` 中检查最小和最大版本字段。
|
||||
|
||||
2. 在第 2 阶段引导启动程序的初始化阶段，会检查引导程序自身是否可以在此版本的芯片上启动。它从引导启动程序镜像的头文件中读取最小版本，并与 eFuse 中的芯片版本进行比较。如果芯片版本低于最小版本，引导启动程序会拒绝启动并中止运行。此阶段不检查最大版本。
|
||||
2. 在第 2 阶段引导启动程序的初始化阶段，会检查引导程序自身是否可以在此版本的芯片上启动。它从引导启动程序镜像的标头中读取最小版本，并与 eFuse 中的芯片版本进行比较。如果芯片版本低于最小版本，引导启动程序会拒绝启动并中止运行。此阶段不检查最大版本。
|
||||
|
||||
3. 然后，第 2 阶段引导启动程序会检查应用程序的版本要求。它从应用程序镜像的头文件中读取最小和最大版本，并与 eFuse 中的芯片版本进行比较。如果该芯片版本低于最小版本或高于最大版本，引导程序会拒绝启动并中止。然而，如果设置了忽略最大版本位，则可以忽略最大版本限制。软件确定可以使用此芯片版本时，用户可以自行设置忽略位。
|
||||
3. 然后，第 2 阶段引导启动程序会检查应用程序的版本要求。它从应用程序镜像的标头中读取支持的芯片最小和最大版本，以及从段的标头中读取 eFuse 块版本信息，并与 eFuse 中的芯片版本进行比较。如果该芯片版本或 eFuse 块版本低于各自的最小版本或高于最大版本，引导程序会拒绝启动并中止。然而，如果设置了忽略最大版本位，则可以忽略最大版本限制。软件确定可以使用此芯片版本时，用户可以自行设置忽略位。
|
||||
|
||||
4. 在空中升级 (OTA) 阶段，运行中的应用程序会检查新软件是否与芯片版本相匹配。它会从新应用程序镜像的标头中提取最小和最大版本，并与 eFuse 中的芯片版本进行比较。应用程序检查版本匹配的方式与引导启动程序相同，即芯片版本须处在最小和最大版本之间（忽略最大版本的逻辑也相同）。
|
||||
4. 接着在应用程序的启动阶段将会检查 eFuse 块版本信息。允许的 eFuse 块最大和最小版本由以下 Kconfig 宏指定：
|
||||
|
||||
* :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL`
|
||||
* :ref:`CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL`
|
||||
|
||||
5. 在空中升级 (OTA) 阶段，运行中的应用程序会检查新软件是否与芯片版本及 eFuse 块版本相匹配。它会从新应用程序镜像的标头中提取最小和最大芯片版本，以及应用程序描述中提取最大和最小 eFuse 块版本，并与 eFuse 中的芯片版本和块版本进行比较。应用程序检查版本匹配的方式与引导启动程序相同，即芯片版本和 eFuse 块版本须处在最小和最大版本之间（忽略最大版本的逻辑也相同）。
|
||||
|
||||
向后兼容旧版 ESP-IDF 构建的引导启动程序
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Loading…
Reference in New Issue
Block a user