feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

Merge branch 'feature/check_efuse_blk_after_ota_v5.1' into 'release/v5.1'

Browse Source 
feat(bootloader): support to check efuse block revision (v5.1)

See merge request espressif/esp-idf!33143
This commit is contained in:
morris
2025-04-02 10:01:01 +08:00
parent d02ac835ce 34ebd4943f
commit 401f9e7efc
18 changed files with 272 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
components/bootloader_support/include/bootloader_common.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2018-2022 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2018-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -168,6 +168,20 @@ uint32_t bootloader_common_get_chip_ver_pkg(void);
*/
esp_err_t bootloader_common_check_chip_validity(const esp_image_header_t* img_hdr, esp_image_type type);
#if !CONFIG_IDF_TARGET_ESP32
/**
* @brief Check the eFuse block revision
*
* @param[in] min_rev_full The required minimum revision of the eFuse block
* @param[in] max_rev_full The required maximum revision of the eFuse block
* @return
* - ESP_OK: The eFuse block revision is in the required range.
* - ESP_OK: DISABLE_BLK_VERSION_MAJOR has been set in the eFuse of the SoC. No requirements shall be checked at this time.
* - ESP_FAIL: The eFuse block revision of this chip does not match the requirement of the current image.
*/
esp_err_t bootloader_common_check_efuse_blk_validity(uint32_t min_rev_full, uint32_t max_rev_full);
#endif // !CONFIG_IDF_TARGET_ESP32
/**
* @brief Configure VDDSDIO, call this API to rise VDDSDIO to 1.9V when VDDSDIO regulator is enabled as 1.8V mode.
*/

31
components/bootloader_support/src/bootloader_common_loader.c
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -27,7 +27,7 @@
#include "bootloader_flash_priv.h"
#define ESP_PARTITION_HASH_LEN 32 /* SHA-256 digest length */
#define IS_MAX_REV_SET(max_chip_rev_full) (((max_chip_rev_full) != 65535) && ((max_chip_rev_full) != 0))
#define IS_FIELD_SET(rev_full) (((rev_full) != 65535) && ((rev_full) != 0))
static const char* TAG = "boot_comm";
@@ -57,6 +57,31 @@ int bootloader_common_get_active_otadata(esp_ota_select_entry_t *two_otadata)
return bootloader_common_select_otadata(two_otadata, valid_two_otadata, true);
}
#if !CONFIG_IDF_TARGET_ESP32
esp_err_t bootloader_common_check_efuse_blk_validity(uint32_t min_rev_full, uint32_t max_rev_full)
{
esp_err_t err = ESP_OK;
#ifndef CONFIG_IDF_ENV_FPGA
// Check whether the efuse block version satisfy the requirements of current image.
uint32_t revision = efuse_hal_blk_version();
uint32_t major_rev = revision / 100;
uint32_t minor_rev = revision % 100;
if (IS_FIELD_SET(min_rev_full) && !ESP_EFUSE_BLK_REV_ABOVE(revision, min_rev_full)) {
ESP_LOGE(TAG, "efuse blk rev = v%"PRIu32".%"PRIu32" < min rev v%"PRIu32".%"PRIu32,
major_rev, minor_rev, min_rev_full / 100, min_rev_full % 100);
err = ESP_FAIL;
}
// If burnt `disable_blk_version_major` bit, skip the max version check
if ((IS_FIELD_SET(max_rev_full) && (revision > max_rev_full) && !efuse_hal_get_disable_blk_version_major())) {
ESP_LOGE(TAG, "efuse blk rev = v%"PRIu32".%"PRIu32" > max rev v%"PRIu32".%"PRIu32,
major_rev, minor_rev, max_rev_full / 100, max_rev_full % 100);
err = ESP_FAIL;
}
#endif
return err;
}
#endif // !CONFIG_IDF_TARGET_ESP32
esp_err_t bootloader_common_check_chip_validity(const esp_image_header_t* img_hdr, esp_image_type type)
{
esp_err_t err = ESP_OK;
@@ -80,7 +105,7 @@ esp_err_t bootloader_common_check_chip_validity(const esp_image_header_t* img_hd
}
if (type == ESP_IMAGE_APPLICATION) {
unsigned max_rev = img_hdr->max_chip_rev_full;
if ((IS_MAX_REV_SET(max_rev) && (revision > max_rev) && !efuse_ll_get_disable_wafer_version_major())) {
if ((IS_FIELD_SET(max_rev) && (revision > max_rev) && !efuse_hal_get_disable_wafer_version_major())) {
ESP_LOGE(TAG, "Image requires chip rev <= v%d.%d, but chip is v%d.%d",
max_rev / 100, max_rev % 100,
major_rev, minor_rev);

15
components/bootloader_support/src/bootloader_init.c
View File

@@ -41,10 +41,17 @@ esp_err_t bootloader_read_bootloader_header(void)
esp_err_t bootloader_check_bootloader_validity(void)
{
unsigned int revision = efuse_hal_chip_revision();
unsigned int major = revision / 100;
unsigned int minor = revision % 100;
ESP_EARLY_LOGI(TAG, "chip revision: v%d.%d", major, minor);
unsigned int chip_revision = efuse_hal_chip_revision();
unsigned int chip_major_rev = chip_revision / 100;
unsigned int chip_minor_rev = chip_revision % 100;
ESP_EARLY_LOGI(TAG, "chip revision: v%d.%d", chip_major_rev, chip_minor_rev);
/* ESP32 doesn't have more memory and more efuse bits for block major version. */
#if !CONFIG_IDF_TARGET_ESP32
unsigned int efuse_revision = efuse_hal_blk_version();
unsigned int efuse_major_rev = efuse_revision / 100;
unsigned int efuse_minor_rev = efuse_revision % 100;
ESP_EARLY_LOGI(TAG, "efuse block revision: v%d.%d", efuse_major_rev, efuse_minor_rev);
#endif // !CONFIG_IDF_TARGET_ESP32
/* compare with the one set in bootloader image header */
if (bootloader_common_check_chip_validity(&bootloader_image_hdr, ESP_IMAGE_BOOTLOADER) != ESP_OK) {
return ESP_FAIL;

17
components/bootloader_support/src/esp_image_format.c
View File

@@ -692,19 +692,28 @@ static esp_err_t process_segment_data(int segment, intptr_t load_addr, uint32_t
const uint32_t *src = data;
#if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
// Case I: Bootloader verifying application
// Case II: Bootloader verifying bootloader
// Anti-rollback check should handle only Case I from above.
// The esp_app_desc_t structure is located in DROM and is always in segment #0.
// Anti-rollback check and efuse block version check should handle only Case I from above.
if (segment == 0 && metadata->start_addr != ESP_BOOTLOADER_OFFSET) {
/* ESP32 doesn't have more memory and more efuse bits for block major version. */
#if !CONFIG_IDF_TARGET_ESP32
const esp_app_desc_t *app_desc = (const esp_app_desc_t *)src;
esp_err_t ret = bootloader_common_check_efuse_blk_validity(app_desc->min_efuse_blk_rev_full, app_desc->max_efuse_blk_rev_full);
if (ret != ESP_OK) {
bootloader_munmap(data);
return ret;
}
#endif // !CONFIG_IDF_TARGET_ESP32
#if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
ESP_LOGD(TAG, "additional anti-rollback check 0x%"PRIx32, data_addr);
// The esp_app_desc_t structure is located in DROM and is always in segment #0.
size_t len = process_esp_app_desc_data(src, sha_handle, checksum, metadata);
data_len -= len;
src += len / 4;
// In BOOTLOADER_BUILD, for DROM (segment #0) we do not load it into dest (only map it), do_load = false.
}
#endif // CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
}
for (size_t i = 0; i < data_len; i += 4) {
int w_i = i / 4; // Word index

2
components/esp_app_format/esp_app_desc.c
View File

@@ -40,6 +40,8 @@ const __attribute__((weak)) __attribute__((section(".rodata_desc"))) esp_app_de
.time = "",
.date = "",
#endif
.min_efuse_blk_rev_full = CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL,
.max_efuse_blk_rev_full = CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL,
};

4
components/esp_app_format/include/esp_app_desc.h
View File

@@ -32,7 +32,9 @@ typedef struct {
char date[16]; /*!< Compile date*/
char idf_ver[32]; /*!< Version IDF */
uint8_t app_elf_sha256[32]; /*!< sha256 of elf file */
uint32_t reserv2[20]; /*!< reserv2 */
uint16_t min_efuse_blk_rev_full; /*!< Minimal eFuse block revision supported by image, in format: major * 100 + minor */
uint16_t max_efuse_blk_rev_full; /*!< Maximal eFuse block revision supported by image, in format: major * 100 + minor */
uint32_t reserv2[19]; /*!< reserv2 */
} esp_app_desc_t;
/** @cond */

17
components/esp_hw_support/port/esp32/Kconfig.hw_support
View File

@@ -66,3 +66,20 @@ config ESP32_REV_MAX_FULL
config ESP_REV_MAX_FULL
int
default ESP32_REV_MAX_FULL
config ESP_EFUSE_BLOCK_REV_MIN_FULL
int "Minimum Supported ESP32 eFuse Block Revision"
default 0
help
Required minimum eFuse Block revision. ESP-IDF will check it at the 2nd bootloader stage
whether the current image can work correctly for this eFuse Block revision.
So that to avoid running an incompatible image on a SoC that contains breaking change in the eFuse Block.
If you want to update this value to run the image that not compatible with the current eFuse Block revision,
please contact to Espressif's business team for details:
https://www.espressif.com.cn/en/contact-us/sales-questions
config ESP_EFUSE_BLOCK_REV_MAX_FULL
int
default 99
comment "Maximum Supported ESP32 eFuse Block Revision (eFuse Block Rev v0.99)"
# The revision in the comment must correspond to the default value of ESP_EFUSE_BLOCK_REV_MAX_FULL

18
components/esp_hw_support/port/esp32c2/Kconfig.hw_support
View File

@@ -45,3 +45,21 @@ config ESP32C2_REV_MAX_FULL
config ESP_REV_MAX_FULL
int
default ESP32C2_REV_MAX_FULL
config ESP_EFUSE_BLOCK_REV_MIN_FULL
int "Minimum Supported ESP32-C2 eFuse Block Revision"
default 0
help
Required minimum eFuse Block revision. ESP-IDF will check it at the 2nd bootloader stage
whether the current image can work correctly for this eFuse Block revision.
So that to avoid running an incompatible image on a SoC that contains breaking change in the eFuse Block.
If you want to update this value to run the image that not compatible with the current eFuse Block revision,
please contact to Espressif's business team for details:
https://www.espressif.com.cn/en/contact-us/sales-questions
config ESP_EFUSE_BLOCK_REV_MAX_FULL
int
default 99
comment "Maximum Supported ESP32-C2 eFuse Block Revision (eFuse Block Rev v0.99)"
# The revision in the comment must correspond to the default value of ESP_EFUSE_BLOCK_REV_MAX_FULL

17
components/esp_hw_support/port/esp32c3/Kconfig.hw_support
View File

@@ -54,3 +54,20 @@ config ESP32C3_REV_MAX_FULL
config ESP_REV_MAX_FULL
int
default ESP32C3_REV_MAX_FULL
config ESP_EFUSE_BLOCK_REV_MIN_FULL
int "Minimum Supported ESP32-C3 eFuse Block Revision"
default 0
help
Required minimum eFuse Block revision. ESP-IDF will check it at the 2nd bootloader stage
whether the current image can work correctly for this eFuse Block revision.
So that to avoid running an incompatible image on a SoC that contains breaking change in the eFuse Block.
If you want to update this value to run the image that not compatible with the current eFuse Block revision,
please contact to Espressif's business team for details:
https://www.espressif.com.cn/en/contact-us/sales-questions
config ESP_EFUSE_BLOCK_REV_MAX_FULL
int
default 199
comment "Maximum Supported ESP32-C3 eFuse Block Revision (eFuse Block Rev v1.99)"
# The revision in the comment must correspond to the default value of ESP_EFUSE_BLOCK_REV_MAX_FULL

17
components/esp_hw_support/port/esp32c6/Kconfig.hw_support
View File

@@ -42,3 +42,20 @@ config ESP32C6_REV_MAX_FULL
config ESP_REV_MAX_FULL
int
default ESP32C6_REV_MAX_FULL
config ESP_EFUSE_BLOCK_REV_MIN_FULL
int "Minimum Supported ESP32-C6 eFuse Block Revision"
default 0
help
Required minimum eFuse Block revision. ESP-IDF will check it at the 2nd bootloader stage
whether the current image can work correctly for this eFuse Block revision.
So that to avoid running an incompatible image on a SoC that contains breaking change in the eFuse Block.
If you want to update this value to run the image that not compatible with the current eFuse Block revision,
please contact to Espressif's business team for details:
https://www.espressif.com.cn/en/contact-us/sales-questions
config ESP_EFUSE_BLOCK_REV_MAX_FULL
int
default 99
comment "Maximum Supported ESP32-C6 eFuse Block Revision (eFuse Block Rev v0.99)"
# The revision in the comment must correspond to the default value of ESP_EFUSE_BLOCK_REV_MAX_FULL

17
components/esp_hw_support/port/esp32h2/Kconfig.hw_support
View File

@@ -52,3 +52,20 @@ config ESP_REV_MAX_FULL
config ESP32H2_REV100_DEVELOPMENT
bool "Develop on ESP32-H2 v1.0 and above (Preview)"
default y if IDF_CI_BUILD
config ESP_EFUSE_BLOCK_REV_MIN_FULL
int "Minimum Supported ESP32-H2 eFuse Block Revision"
default 0
help
Required minimum eFuse Block revision. ESP-IDF will check it at the 2nd bootloader stage
whether the current image can work correctly for this eFuse Block revision.
So that to avoid running an incompatible image on a SoC that contains breaking change in the eFuse Block.
If you want to update this value to run the image that not compatible with the current eFuse Block revision,
please contact to Espressif's business team for details:
https://www.espressif.com.cn/en/contact-us/sales-questions
config ESP_EFUSE_BLOCK_REV_MAX_FULL
int
default 99
comment "Maximum Supported ESP32-H2 eFuse Block Revision (eFuse Block Rev v0.99)"
# The revision in the comment must correspond to the default value of ESP_EFUSE_BLOCK_REV_MAX_FULL

17
components/esp_hw_support/port/esp32s2/Kconfig.hw_support
View File

@@ -42,3 +42,20 @@ config ESP32S2_REV_MAX_FULL
config ESP_REV_MAX_FULL
int
default ESP32S2_REV_MAX_FULL
config ESP_EFUSE_BLOCK_REV_MIN_FULL
int "Minimum Supported ESP32-S2 eFuse Block Revision"
default 0
help
Required minimum eFuse Block revision. ESP-IDF will check it at the 2nd bootloader stage
whether the current image can work correctly for this eFuse Block revision.
So that to avoid running an incompatible image on a SoC that contains breaking change in the eFuse Block.
If you want to update this value to run the image that not compatible with the current eFuse Block revision,
please contact to Espressif's business team for details:
https://www.espressif.com.cn/en/contact-us/sales-questions
config ESP_EFUSE_BLOCK_REV_MAX_FULL
int
default 99
comment "Maximum Supported ESP32-S2 eFuse Block Revision (eFuse Block Rev v0.99)"
# The revision in the comment must correspond to the default value of ESP_EFUSE_BLOCK_REV_MAX_FULL

17
components/esp_hw_support/port/esp32s3/Kconfig.hw_support
View File

@@ -45,3 +45,20 @@ config ESP32S3_REV_MAX_FULL
config ESP_REV_MAX_FULL
int
default ESP32S3_REV_MAX_FULL
config ESP_EFUSE_BLOCK_REV_MIN_FULL
int "Minimum Supported ESP32-S3 eFuse Block Revision"
default 0
help
Required minimum eFuse Block revision. ESP-IDF will check it at the 2nd bootloader stage
whether the current image can work correctly for this eFuse Block revision.
So that to avoid running an incompatible image on a SoC that contains breaking change in the eFuse Block.
If you want to update this value to run the image that not compatible with the current eFuse Block revision,
please contact to Espressif's business team for details:
https://www.espressif.com.cn/en/contact-us/sales-questions
config ESP_EFUSE_BLOCK_REV_MAX_FULL
int
default 199
comment "Maximum Supported ESP32-S3 eFuse Block Revision (eFuse Block Rev v1.99)"
# The revision in the comment must correspond to the default value of ESP_EFUSE_BLOCK_REV_MAX_FULL

7
components/hal/efuse_hal.c
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -34,6 +34,11 @@ IRAM_ATTR bool efuse_hal_get_disable_wafer_version_major(void)
return efuse_ll_get_disable_wafer_version_major();
}
IRAM_ATTR bool efuse_hal_get_disable_blk_version_major(void)
{
return efuse_ll_get_disable_blk_version_major();
}
IRAM_ATTR bool efuse_hal_flash_encryption_enabled(void)
{
uint32_t flash_crypt_cnt = efuse_ll_get_flash_crypt_cnt();

7
components/hal/esp32/include/hal/efuse_ll.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -119,6 +119,11 @@ __attribute__((always_inline)) static inline bool efuse_ll_get_disable_wafer_ver
return false;
}
__attribute__((always_inline)) static inline bool efuse_ll_get_disable_blk_version_major(void)
{
return false;
}
__attribute__((always_inline)) static inline bool efuse_ll_get_blk_version_major(void)
{
return 0;

18
components/hal/include/hal/efuse_hal.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -43,6 +43,22 @@ uint32_t efuse_hal_blk_version(void);
*/
bool efuse_hal_flash_encryption_enabled(void);
/**
* @brief Returns the status of whether the bootloader (and OTA)
* will check the maximum chip version or not.
*
* @return true - Skip the maximum chip version check.
*/
bool efuse_hal_get_disable_wafer_version_major(void);
/**
* @brief Returns the status of whether the app start-up (and OTA)
* will check the efuse block version or not.
*
* @return true - Skip the efuse block version check.
*/
bool efuse_hal_get_disable_blk_version_major(void);
/**
* @brief Returns major chip version
*/

8
components/soc/include/soc/chip_revision.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -31,6 +31,12 @@ extern "C" {
#define ESP_CHIP_REV_ABOVE(rev, min_rev) ((min_rev) <= (rev))
#define ESP_CHIP_REV_MAJOR_AND_ABOVE(rev, min_rev) (((rev) / 100 == (min_rev) / 100) && ((rev) >= (min_rev)))
/**
* eFuse block revision strategy is same as chip revision
*/
#define ESP_EFUSE_BLK_REV_ABOVE(rev, min_rev) ESP_CHIP_REV_ABOVE(rev, min_rev)
#define ESP_EFUSE_BLK_REV_MAJOR_AND_ABOVE(rev, min_rev) ESP_CHIP_REV_MAJOR_AND_ABOVE(rev, min_rev)
#ifdef __cplusplus
}
#endif

57
docs/en/api-reference/system/chip_revision.rst
View File

@@ -9,6 +9,9 @@ A new chip versioning logic was introduced in new chips. Chips have several eFus
- Major wafer version (``WAFER_VERSION_MAJOR`` eFuse)
- Minor wafer version (``WAFER_VERSION_MINOR`` eFuse)
- Ignore maximal revision (``DISABLE_WAFER_VERSION_MAJOR`` eFuse)
- 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).
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.
@@ -41,11 +44,16 @@ The ``vX.Y`` chip version format will be 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:
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`` - 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 can not be changed by user. Only Espressif can change it when a new version will be supported in IDF.
- ``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``. It reflects whether the current IDF version supports this efuse block format or not, and should not be changed by the user.
Chip Revision APIs
------------------
@@ -53,8 +61,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:
@@ -63,21 +71,44 @@ 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:
- ``CONFIG_ESP_EFUSE_BLOCK_REV_MIN_FULL``
- ``CONFIG_ESP_EFUSE_BLOCK_REV_MAX_FULL``
Maximal And Minimal 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 minimal and maximal revision fields from :cpp:type:`esp_image_header_t` before running the 2nd stage bootloader.
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 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.
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. 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 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).
Issues
------
Compatibility Checks of ESP-IDF
-------------------------------
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.
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.
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).
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.
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: