ESP-IDF 引导加载程序Bootloader完全指南二级引导流程、恢复出厂设置、看门狗与自定义扩展【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf导读引导加载程序Bootloader是 ESP32 系列芯片上电后最先执行的用户可控固件决定了整个设备能否正确选择并启动应用程序。本文以 ESP-IDF 官方文档《引导加载程序 (Bootloader)》为骨架结合 components/bootloader 的 Kconfig 配置项与 bootloader_start.c 源码系统讲解二级引导加载程序的工作职责、SPI Flash 配置机制、恢复出厂设置、测试固件引导、看门狗、大小约束、深度睡眠快速启动、自定义扩展以及恢复引导加载程序与防回滚等新特性。阅读完本文你将掌握引导加载程序的全部核心配置项CONFIG_BOOTLOADER_*系列并能依据实际产品需求正确裁剪与扩展引导加载程序。一、二级引导加载程序它到底做什么ESP-IDF 的**二级引导加载程序second stage bootloader**主要负责以下四项任务内部模块的最小化初始配置对时钟、Flash 缓存等基础硬件做最低限度的初始化安全特性初始化如果配置了 Flash 加密 和/或 Secure Boot V2则在此阶段完成相应初始化选择引导分区根据分区表以及 ota_data 数据如果存在选择需要引导的应用程序app分区加载应用镜像到 RAM将应用程序镜像加载到 RAMIRAM 与 DRAM最后把控制权转交给该应用程序。ESP-IDF 二级引导加载程序位于 Flash 的CONFIG_BOOTLOADER_OFFSET_IN_FLASH偏移地址处。该偏移由 ROM 引导加载程序决定ESP-IDF 内部不可配置见 Kconfig.projbuild 中的注释说明。从源码看上述流程对应 bootloader_start.c 中的call_start_cpu0()函数调用bootloader_init()完成硬件初始化失败则bootloader_reset()复位调用bootloader_utility_load_partition_table()加载分区表调用bootloader_utility_get_selected_boot_partition()选择引导分区最终通过bootloader_utility_load_boot_image()把应用镜像加载进 RAM 并跳转执行。完整的启动流程包括一级 ROM 引导加载程序与二级引导加载程序的协作可参考 startup.rst。提示在使用本文提到的功能前建议将 ESP-IDF 更新到最新发布版本详见 版本说明。二、引导加载程序兼容性为何 OTA 不能更新 BootloaderOTA空中升级机制可以在现场烧录新的应用程序但不能烧录一个新的引导加载程序。因此引导加载程序必须保持向后兼容引导加载程序支持引导从 ESP-IDF 新版本构建的应用程序引导加载程序不支持引导从 ESP-IDF 旧版本构建的应用程序。如果现有产品可能需要将应用程序降级到旧版本那么在手动更新 ESP-IDF 时请继续使用旧版本引导加载程序的二进制文件。注意生产环境测试如果在生产中测试现有产品的 OTA 更新请确保测试中使用的引导加载程序二进制文件与生产中部署的完全相同。针对 ESP32 的历史兼容选项以下配置选项仅适用于 ESP32 目标对应文档中.. only:: esp32条件块历史版本差异说明兼容处理ESP-IDF V2.1 之前早期引导加载程序对硬件的配置更少启用CONFIG_APP_COMPATIBLE_PRE_V2_1_BOOTLOADERSESP-IDF V3.1 之前不支持分区表二进制文件中的 MD5 校验启用CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERSESP-IDF V5.1 之前不支持CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM使用这些旧版本引导加载程序时不应启用该选项三、SPI Flash 配置两级引导加载程序如何接力每个 ESP-IDF 应用程序或引导加载程序的.bin文件头部都内嵌了以下三个配置CONFIG_ESPTOOLPY_FLASHMODEFlash 工作模式CONFIG_ESPTOOLPY_FLASHFREQFlash 时钟频率CONFIG_ESPTOOLPY_FLASHSIZEFlash 容量两级接力流程**一级引导加载程序ROM**从 Flash 中读取二级引导加载程序文件头中的配置信息并用这些信息加载剩余的二级引导加载程序。但此时系统时钟速度低于配置值且只支持部分 Flash 模式二级引导加载程序运行时会从当前选中的应用程序二进制文件头中读取配置而不是从二级引导加载程序自己的文件头读取并用这些数据重新配置 Flash。这样的设计使得OTA 更新可以改变当前使用的 SPI Flash 配置如从 DIO 切换到 QIO、调整频率等。ESP32 历史背景ESP-IDF V4.0 之前的引导加载程序使用自身文件头配置 SPI Flash导致 OTA 更新时无法更改 Flash 配置。为兼容旧引导加载程序ESP32 应用程序在启动期间会使用应用程序文件头中的配置重新初始化 Flash 配置。与 Flash 配置相关的引导加载程序选项还包括见 Kconfig.projbuild 的 Serial Flash Configurations 菜单CONFIG_BOOTLOADER_SPI_CUSTOM_WP_PIN/CONFIG_BOOTLOADER_SPI_WP_PIN在 eFuse 覆盖了 SPI Flash 引脚且使用 QIO/QOUT 模式时自定义 WP 引脚默认 GPIO 7CONFIG_BOOTLOADER_FLASH_DC_AWARE允许应用程序为更高频率调整 SPI Flash 的 Dummy Cycle 位CONFIG_BOOTLOADER_FLASH_XMC_SUPPORTXMC Flash 芯片的启动流程支持默认启用不建议关闭CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH使 CPU 可访问 16MB 以上 32 位地址范围的 Flash实验特性。四、日志级别用启动时间换可调试性引导加载程序日志的默认级别为Info。通过配置CONFIG_BOOTLOADER_LOG_LEVEL可以增加或减少这个级别。该日志级别与应用程序中使用的日志级别相互独立应用日志级别见 log.rst。值得注意的是降低引导加载程序日志的详细程度可以稍微缩短整个项目的启动时间同时也会减小二进制体积详见下文引导加载程序大小一节。五、恢复出厂设置Factory Reset当 OTA 更新出现问题时设备需要一个回到已知正常状态的机制这就是恢复出厂设置。在引导加载程序中启用CONFIG_BOOTLOADER_FACTORY_RESET后设备可以恢复原始出厂设置并清除所有用户设置。5.1 两种恢复方式恢复出厂设置支持以下两种方式两者可以独立启用或同时启用方式一清除一个或多个数据分区CONFIG_BOOTLOADER_DATA_FACTORY_RESET选项用于指定恢复出厂设置时需要擦除的数据分区。分区名称使用逗号分隔的列表为提高可读性可加空格例如nvs, phy_init, nvs_custom注意事项选项里指定的分区名称必须与分区表中的名称完全一致此处不能指定类型为 app 的分区。方式二从工厂应用分区启动启用CONFIG_BOOTLOADER_OTA_DATA_ERASE后恢复出厂设置后设备将从默认的工厂应用分区启动如果分区表中没有工厂应用分区则从默认的 OTA 应用分区启动。该恢复过程通过擦除 OTA 数据分区完成——OTA 数据分区中保存了当前选择的 OTA 分区槽。工厂应用分区槽如果存在永远不会通过 OTA 更新因此重置为从工厂分区启动即意味着让固件应用程序恢复正常状态。从源码看恢复出厂设置的触发与执行逻辑位于 bootloader_start.c检测到 GPIO 长时间保持配置电平后调用bootloader_common_erase_part_type_data()擦除指定分区并通过bootloader_common_set_rtc_retain_mem_factory_reset_state()记录出厂重置状态。5.2 触发条件相关配置以下配置项控制恢复出厂设置的触发条件配置项说明默认值CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET用于触发出厂重置的输入 GPIO 编号4CONFIG_BOOTLOADER_HOLD_TIME_GPIO管脚电平保持时间秒5CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL触发电平高/低Reset on GPIO low/Reset on GPIO high低电平必须在设备重置时将指定管脚拉低或拉高电平可配置并保持CONFIG_BOOTLOADER_HOLD_TIME_GPIO设定的时间才能触发出厂长重置事件。如果管脚具有内部上拉上拉会在管脚采样前生效具体内部上拉能力请查阅对应芯片的技术规格书。注意部分 SoC 上并非所有引脚都有内部上拉且部分引脚已被 ROM 引导加载程序用作启动bootstrapping引脚请参考对应芯片的技术参考手册见 Kconfig.projbuild 中的帮助文本。5.3 应用如何获知出厂重置已发生支持 RTC FAST 内存的芯片应用可通过调用bootloader_common_get_rtc_retain_mem_factory_reset_state函数判断读到状态为true说明设备已触发出厂重置函数随后会把状态重置为 false以便后续判断读到状态为false说明设备并未触发出厂重置或保存该状态的内存区域已失效。注意该功能会占用部分 RTC FAST 内存占用大小与CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP特性相同。不支持 RTC FAST 内存的芯片没有对应的 API 可用于监测。替代方案是设置一个在出厂重置时会被引导加载程序擦除的 NVS 分区需将该分区加入CONFIG_BOOTLOADER_DATA_FACTORY_RESET并在该 NVS 分区保存一个自增令牌factory_reset_state。当应用读取到factory_reset_state为 0 时即表明触发了出厂重置。六、从测试固件启动Boot from Test Firmware用户可以编写用于生产环境测试的特殊固件并在需要时运行。该机制需要在项目分区表中专门申请一个测试固件分区类型为app子类型为test详见 partition-tables.rst为测试应用创建完全独立的 ESP-IDF 项目ESP-IDF 中每个项目仅构建一个应用可独立于主项目开发和测试在生成测试时将测试应用的预编译 .bin 文件烧录到主项目测试应用分区的地址。6.1 主项目引导加载程序配置在主项目的引导加载程序中启用CONFIG_BOOTLOADER_APP_TEST后需配置以下三个选项配置项说明默认值CONFIG_BOOTLOADER_NUM_PIN_APP_TEST触发 TEST 分区启动的 GPIO 编号该引脚被配置为输入并启用内部上拉18CONFIG_BOOTLOADER_HOLD_TIME_GPIOGPIO 电平保持时间秒5CONFIG_BOOTLOADER_APP_TEST_PIN_LEVEL触发电平高/低Enter test app on GPIO low/Enter test app on GPIO high低电平在设备重置时必须将指定管脚拉低或拉高可配置并保持设定时间才会触发测试应用引导。释放管脚输入并重启设备后将重新启用默认的启动顺序——即启动工厂分区或任意 OTA 应用分区槽。注意CONFIG_BOOTLOADER_APP_TEST依赖!CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK即启用应用防回滚时无法使用测试固件引导功能见 Kconfig.projbuild。源码对应逻辑位于 bootloader_start.c检测到 GPIO 长时间保持后检查bs-test.offset ! 0分区表中存在 test 分区则将引导索引设为TEST_APP_INDEX否则报错并复位。七、回滚Rollback回滚和反回滚功能也必须在引导加载程序中配置。相关选项位于 Kconfig.app_rollbackCONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE启用应用回滚支持。OTA 更新后引导加载程序会以ESP_OTA_IMG_PENDING_VERIFY状态运行新应用应用首次启动后需在用户代码中调用接口确认可操作性若应用工作正常则标记为有效否则标记为无效并回滚到上一个正常工作的应用。注意如果在首次启动新应用时断电或看门狗触发也会发生回滚CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK启用应用防回滚防止回滚到安全版本号更低的固件。启用后分区表需使用ota_0 ota_1无 factory的方案CONFIG_BOOTLOADER_APP_SECURE_VERSION固件的安全版本号记录在 eFuse 字段中引导加载程序只会选择安全版本号大于或等于 eFuse 记录值的应用启动CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELDeFuse 安全版本字段的大小ESP32 为 32 位、ESP32-C2 为 4 位、ESP32-C5 为 9 位、其他目标 16 位决定了安全版本可递增的次数CONFIG_BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE仅用于测试可在不烧写 eFuse 的情况下模拟安全版本读写需在分区表中添加emul_efuse, data, efuse, , 0x2000条目。详细的回滚/防回滚 API 请参考 ota.rst 中的 回滚 (app_rollback) 与 防回滚 (anti-rollback) 章节。八、看门狗Watchdog芯片配备两组看门狗定时器主系统看门狗定时器MWDT_WDTRTC 看门狗定时器RTC_WDT芯片上电时两组看门狗都会被启用但在引导加载程序中会被禁用。启用CONFIG_BOOTLOADER_WDT_ENABLE默认开启后RTC 看门狗定时器会被重新启用用于跟踪从引导加载程序启用直到调用用户main函数的时间。此期间 RTC 看门狗始终可用如果在 9 秒内没有应用程序成功启动RTC 看门狗会自动复位芯片可有效防止启动过程中因电源不稳定导致的死机。相关配置项配置项说明默认值CONFIG_BOOTLOADER_WDT_ENABLE在启动代码中使用 RTC 看门狗yCONFIG_BOOTLOADER_WDT_TIME_MSRTC 看门狗超时时间ms需大于启动代码实际执行时间9000范围 0~120000CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE允许在用户代码中禁用 RTC 看门狗n注意事项调整超时时间需修改CONFIG_BOOTLOADER_WDT_TIME_MS并重新编译引导加载程序通过禁用CONFIG_BOOTLOADER_WDT_ENABLE并重新编译可以在引导加载程序中禁用 RTC 看门狗但不建议这样做若启用CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE应用必须显式调用wdt_hal_feed()或 ESP32/ESP32-S2 的rtc_wdt_feed()喂狗、或wdt_hal_disable()或rtc_wdt_disable()禁用 RTC_WDT注意恢复出厂设置、触发测试分区、启动时加密等操作会增加启动代码执行时间需相应调整超时值见 Kconfig.projbuild。应用程序中使用 RTC_WDT 的方法参见硬件看门狗定时器章节。九、引导加载程序大小一个必须监控的指标9.1 各芯片的引导加载程序上限不同芯片的引导加载程序最大尺寸不同ESP3248 KB0xC000 字节ESP32-S2 / ESP32-S3 / ESP32-C2 / ESP32-C3 / ESP32-C6 / ESP32-H2 / ESP32-H21 / ESP32-P464 KB0x10000 字节其他默认80 KB0x14000 字节对应可用的最大分区表偏移默认引导加载程序大小 0x1000 签名扇区 起始保留区为ESP320xE000ESP32-C5 / ESP32-H4 / ESP32-S310x17000起始 0x2000 引导加载程序 0x1000 签名扇区支持 Key Manager 的目标ESP32-C610x15000ESP32-P40x13000其他默认0x11000当启用额外的引导加载程序功能包括 Flash 加密 或 Secure Boot尤其是设置了较高的CONFIG_BOOTLOADER_LOG_LEVEL日志级别时监控引导加载程序 .bin 文件的大小变得非常重要。使用默认的CONFIG_PARTITION_TABLE_OFFSET值 0x8000 时二进制文件最大可为 0x8000 字节即分区表偏移量本身。9.2 过大导致的后果构建失败报错Bootloader binary size [..] is too large for partition table offset如果二进制文件已被强行烧录芯片将无法启动——日志中会记录无效分区表或无效引导加载程序校验和的错误。9.3 解决方法恢复编译器优化级别将CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION重新设置回默认值 Size-OsClang 下为-Oz。可选级别见 Kconfig.projbuildSize默认、Debug-Og、Performance-O2降低引导加载程序日志级别CONFIG_BOOTLOADER_LOG_LEVEL设置为 Warning、Error 或 None 都会显著减小最终二进制大小但可能让调试更困难增大分区表偏移将CONFIG_PARTITION_TABLE_OFFSET设置为高于 0x8000 的值把分区表放到 Flash 更靠后的位置从而为引导加载程序腾出更多空间。如果分区表 CSV 文件包含显式分区偏移量需修改这些偏移量保证没有分区的偏移量低于CONFIG_PARTITION_TABLE_OFFSET 0x1000包括 ESP-IDF 自带的默认分区 CSV 文件。9.4 Secure Boot V2 的绝对限制启用 Secure Boot V2 时由于引导加载程序最先被加载到固定大小的缓冲区中进行验证其二进制大小存在绝对限制——即上表中的最大尺寸不含 4 KB 签名。十、从深度睡眠中快速启动引导加载程序提供CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP选项可减少从深度睡眠中唤醒的时间有利于降低功耗。其原理是跳过镜像校验。可用条件该选项在CONFIG_SECURE_BOOT禁用时可用也可在启用 Secure Boot 的同时开启 允许不安全选项CONFIG_SECURE_BOOT_INSECURE时使用——但强烈不建议这样做因为可能绕过 Secure Boot 校验见 Kconfig.projbuild。不同芯片的实现机制支持 RTC FAST 内存的芯片首次启动时引导加载程序将启动的应用程序地址存储在 RTC FAST 存储器中唤醒时直接使用该地址启动而无需任何检查实现快速加载不支持 RTC 存储器的芯片无法保存正在运行的分区状态每次唤醒会读取整个分区表并加载正确的应用程序但不进行额外检查因此加载速度也更快。此外还有两个相关选项仅在不启用 Secure Boot 签名校验时可用CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON跳过上电复位的镜像校验显著缩短上电启动时间。但此时引导加载程序无法检测应用镜像损坏也就无法安全回退到其他应用分区建议同时保持CONFIG_BOOTLOADER_WDT_ENABLE开启以增加从 Flash 损坏中恢复的概率CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS完全跳过镜像校验任何所选应用分区的 Flash 损坏都会导致整个芯片无法启动不推荐仅在启动时间成为唯一关键因素时考虑。十一、自定义引导加载程序用户可以扩展或修改当前的引导加载程序有两种方式实现钩子hooks或重写覆盖override。两种方式在 examples/custom_bootloader 示例中均有呈现custom_bootloader/bootloader_hooks介绍如何将钩子与引导加载程序初始化连接custom_bootloader/bootloader_override介绍如何覆盖引导加载程序的实现另有 custom_bootloader/bootloader_multiboot 与 custom_bootloader/bootloader_extra_dir 展示更多自定义场景。11.1 钩子机制Hooks钩子函数的声明位于 bootloader_hooks.h两个函数均为weak 符号用户项目可按需重新定义bootloader_before_init()在二级引导加载程序初始化之前执行bootloader_after_init()在二级引导加载程序初始化之后执行。示例实现见 hooks.cvoid bootloader_hooks_include(void){ /* 该函数用于告知链接器包含此文件及其全部符号 */ } void bootloader_before_init(void) { /* 注意此时系统尚未完成初始化 * 包括 BSS、SPI flash、内存保护等 * 因此很多函数不能在此调用。 */ ESP_LOGI(HOOK, This hook is called BEFORE bootloader initialization); } void bootloader_after_init(void) { ESP_LOGI(HOOK, This hook is called AFTER bootloader initialization); }在 bootloader_start.c 中可以看到钩子的调用时机硬件初始化前调用bootloader_before_init()初始化完成后调用bootloader_after_init()。11.2 覆盖机制Override通过覆盖call_start_cpu0()函数可以完全接管引导流程。示例见 bootloader_override 的 bootloader_start.c其在原有流程基础上加入了自定义打印void __attribute__((noreturn)) call_start_cpu0(void) { // 1. Hardware initialization if (bootloader_init() ! ESP_OK) { bootloader_reset(); } // 2. Select the number of boot partition bootloader_state_t bs {0}; int boot_index select_partition_number(bs); if (boot_index INVALID_INDEX) { bootloader_reset(); } // 2.1 Print a custom message! esp_rom_printf([%s] %s\n, TAG, CONFIG_EXAMPLE_BOOTLOADER_WELCOME_MESSAGE); // 3. Load the app image for booting bootloader_utility_load_boot_image(bs, boot_index); }11.3 使用限制与 bootloader_components 目录在引导加载程序的代码中不能使用其他组件提供的驱动和函数除非某个驱动或函数明确声明支持在引导加载程序中运行。如果确实需要应将所需功能放在项目的bootloader_components目录中注意这会增加引导加载程序的大小。可以在引导加载程序中使用的组件示例nvs_bootloader见 examples/storage/nvs/nvs_bootloader支持在引导加载程序阶段读取 NVS 数据。如果引导加载程序过大可能与内存中的分区表重叠分区表默认烧录在偏移 0x8000 处。此时可增大分区表偏移量CONFIG_PARTITION_TABLE_OFFSET将分区表放到 Flash 更靠后的区域以增加引导加载程序的可用空间。十二、恢复引导加载程序与防回滚Recovery / Anti-rollback Bootloader对于支持SOC_RECOVERY_BOOTLOADER_SUPPORTED的目标芯片如 ESP32-C5 等新一代 SoCESP-IDF 引入了恢复引导加载程序Recovery Bootloader与防回滚引导加载程序Anti-rollback Bootloader功能。这两项功能在ROM 引导加载程序中实现用于提升设备在 OTA 升级过程中的安全性和可靠性。相关配置位于 Kconfig.bootloader_rollback。12.1 恢复引导加载程序为 Bootloader 本身提供 OTA 安全回退恢复引导加载程序功能可在 OTA 升级失败时为引导加载程序提供安全回退机制eFuse 字段ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR指定恢复引导加载程序的 Flash 地址以扇区为单位如果位于CONFIG_BOOTLOADER_OFFSET_IN_FLASH的主引导加载程序加载失败ROM 引导加载程序会尝试从指定地址加载恢复引导加载程序。关键配置与操作配置项说明默认值CONFIG_BOOTLOADER_RECOVERY_ENABLE启用恢复引导加载程序依赖SOC_RECOVERY_BOOTLOADER_SUPPORTEDnCONFIG_BOOTLOADER_RECOVERY_OFFSET恢复引导加载程序的 Flash 偏移地址必须是 Flash 扇区大小0x1000 字节的整数倍该 Kconfig 选项可帮助验证其不与现有分区重叠0x3F0000范围 0x0~0xFFE000操作要点eFuse 可使用espefuse工具或在用户应用程序中调用esp_efuse_set_recovery_bootloader_offset()设置eFuse 字段存储的是以扇区为单位的偏移量将其设置为最大值0xFFF可禁用恢复引导加载程序功能默认情况下CONFIG_BOOTLOADER_RECOVERY_OFFSET处的恢复引导加载程序镜像不会被烧录但可以作为 OTA 升级流程的一部分写入。主引导加载程序加载失败时的引导日志示例ESP-ROM:esp32c5-eco2-20250121 Build:Jan 21 2025 rst:0x1 (POWERON),boot:0x18 (SPI_FAST_FLASH_BOOT) invalid header: 0xffffffff invalid header: 0xffffffff invalid header: 0xffffffff PRIMARY - FAIL Loading RECOVERY Bootloader... SPI mode:DIO, clock div:1 load:0x408556b0,len:0x17cc load:0x4084bba0,len:0xdac load:0x4084e5a0,len:0x3140 entry 0x4084bbaa I (46) boot: ESP-IDF v6.0-dev-172-g12c5d730097-dirty 2nd stage bootloader I (46) boot: compile time May 22 2025 12:41:59 I (47) boot: chip revision: v1.0 I (48) boot: efuse block revision: v0.1 I (52) boot.esp32c5: SPI Speed : 80MHz I (55) boot.esp32c5: SPI Mode : DIO I (59) boot.esp32c5: SPI Flash Size : 4MB I (63) boot: Enabling RNG early entropy source... I (67) boot: Partition Table: ...日志中的PRIMARY - FAIL表示主引导加载程序验证失败随后Loading RECOVERY Bootloader...加载恢复引导加载程序最终正常进入二级引导加载程序流程。12.2 防回滚功能Anti-Rollback防回滚功能可防止降级到可能存在安全漏洞的旧版引导加载程序引导加载程序头部包含安全版本号由CONFIG_BOOTLOADER_SECURE_VERSION定义默认 0范围 0~4设置EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN后ROM 引导加载程序将该安全版本号与EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION中存储的值比对只有版本号大于或等于 eFuse 值的引导加载程序才允许启动。相关机制如果设置了EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROMROM 引导加载程序可以更新 eFuse 中的安全版本号随着新引导加载程序版本的发布安全版本号会递增且不能降低如果 ROM 引导加载程序未更新 eFuse 中的安全版本号应用程序可以通过esp_efuse_write_field_blob函数更新。配置入口Kconfig.bootloader_rollbackCONFIG_BOOTLOADER_ANTI_ROLLBACK_ENABLE启用引导加载程序防回滚支持依赖恢复引导加载程序启用CONFIG_BOOTLOADER_SECURE_VERSION引导加载程序的安全版本号。当旧版本存在重大安全漏洞且不可接受时应提高该值。12.3 相关 eFuse 一览eFuse 字段位数说明EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR12 位恢复引导加载程序的 Flash 扇区地址。默认值 0禁用设置为其他值则启用设置为 0xFFF 时永久禁用EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN1 位在 ROM 引导加载程序中启用防回滚检查EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION4 位防回滚保护的安全版本号该值随位数增加而递增——0x0、0x1、0x3、0x7、0xFEFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM1 位允许 ROM 引导加载程序更新 eFuse 中的安全版本号重要提醒建议使用以上功能提升设备在 OTA 升级过程中的安全性和可靠性但请谨慎规划 eFuse 的烧录——这些设置是永久性的可能影响未来的升级策略。总结引导加载程序配置速查功能领域核心配置项默认值日志CONFIG_BOOTLOADER_LOG_LEVELInfo编译器优化CONFIG_BOOTLOADER_COMPILER_OPTIMIZATIONSize-Os恢复出厂设置CONFIG_BOOTLOADER_FACTORY_RESET/CONFIG_BOOTLOADER_DATA_FACTORY_RESET/CONFIG_BOOTLOADER_OTA_DATA_ERASE/CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET/CONFIG_BOOTLOADER_HOLD_TIME_GPIO/CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVELn / nvs / n / 4 / 5s / 低电平测试固件引导CONFIG_BOOTLOADER_APP_TEST/CONFIG_BOOTLOADER_NUM_PIN_APP_TEST/CONFIG_BOOTLOADER_APP_TEST_PIN_LEVELn / 18 / 低电平看门狗CONFIG_BOOTLOADER_WDT_ENABLE/CONFIG_BOOTLOADER_WDT_TIME_MS/CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODEy / 9000ms / n深度睡眠快速启动CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP/CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON/CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYSn / n / n应用回滚CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE/CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK/CONFIG_BOOTLOADER_APP_SECURE_VERSIONn / n / 0恢复/防回滚CONFIG_BOOTLOADER_RECOVERY_ENABLE/CONFIG_BOOTLOADER_RECOVERY_OFFSET/CONFIG_BOOTLOADER_ANTI_ROLLBACK_ENABLE/CONFIG_BOOTLOADER_SECURE_VERSIONn / 0x3F0000 / n / 0引导加载程序的所有配置均可在项目的sdkconfig或通过idf.py menuconfig完成修改后需重新编译并烧录引导加载程序idf.py bootloader-flash才会生效。合理规划这些选项是构建稳定、可维护、可安全升级的 ESP-IDF 产品的第一步。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP-IDF 引导加载程序（Bootloader）完全指南：二级引导流程、恢复出厂设置、看门狗与自定义扩展
ESP-IDF 引导加载程序Bootloader完全指南二级引导流程、恢复出厂设置、看门狗与自定义扩展【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf导读引导加载程序Bootloader是 ESP32 系列芯片上电后最先执行的用户可控固件决定了整个设备能否正确选择并启动应用程序。本文以 ESP-IDF 官方文档《引导加载程序 (Bootloader)》为骨架结合 components/bootloader 的 Kconfig 配置项与 bootloader_start.c 源码系统讲解二级引导加载程序的工作职责、SPI Flash 配置机制、恢复出厂设置、测试固件引导、看门狗、大小约束、深度睡眠快速启动、自定义扩展以及恢复引导加载程序与防回滚等新特性。阅读完本文你将掌握引导加载程序的全部核心配置项CONFIG_BOOTLOADER_*系列并能依据实际产品需求正确裁剪与扩展引导加载程序。一、二级引导加载程序它到底做什么ESP-IDF 的**二级引导加载程序second stage bootloader**主要负责以下四项任务内部模块的最小化初始配置对时钟、Flash 缓存等基础硬件做最低限度的初始化安全特性初始化如果配置了 Flash 加密 和/或 Secure Boot V2则在此阶段完成相应初始化选择引导分区根据分区表以及 ota_data 数据如果存在选择需要引导的应用程序app分区加载应用镜像到 RAM将应用程序镜像加载到 RAMIRAM 与 DRAM最后把控制权转交给该应用程序。ESP-IDF 二级引导加载程序位于 Flash 的CONFIG_BOOTLOADER_OFFSET_IN_FLASH偏移地址处。该偏移由 ROM 引导加载程序决定ESP-IDF 内部不可配置见 Kconfig.projbuild 中的注释说明。从源码看上述流程对应 bootloader_start.c 中的call_start_cpu0()函数调用bootloader_init()完成硬件初始化失败则bootloader_reset()复位调用bootloader_utility_load_partition_table()加载分区表调用bootloader_utility_get_selected_boot_partition()选择引导分区最终通过bootloader_utility_load_boot_image()把应用镜像加载进 RAM 并跳转执行。完整的启动流程包括一级 ROM 引导加载程序与二级引导加载程序的协作可参考 startup.rst。提示在使用本文提到的功能前建议将 ESP-IDF 更新到最新发布版本详见 版本说明。二、引导加载程序兼容性为何 OTA 不能更新 BootloaderOTA空中升级机制可以在现场烧录新的应用程序但不能烧录一个新的引导加载程序。因此引导加载程序必须保持向后兼容引导加载程序支持引导从 ESP-IDF 新版本构建的应用程序引导加载程序不支持引导从 ESP-IDF 旧版本构建的应用程序。如果现有产品可能需要将应用程序降级到旧版本那么在手动更新 ESP-IDF 时请继续使用旧版本引导加载程序的二进制文件。注意生产环境测试如果在生产中测试现有产品的 OTA 更新请确保测试中使用的引导加载程序二进制文件与生产中部署的完全相同。针对 ESP32 的历史兼容选项以下配置选项仅适用于 ESP32 目标对应文档中.. only:: esp32条件块历史版本差异说明兼容处理ESP-IDF V2.1 之前早期引导加载程序对硬件的配置更少启用CONFIG_APP_COMPATIBLE_PRE_V2_1_BOOTLOADERSESP-IDF V3.1 之前不支持分区表二进制文件中的 MD5 校验启用CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERSESP-IDF V5.1 之前不支持CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM使用这些旧版本引导加载程序时不应启用该选项三、SPI Flash 配置两级引导加载程序如何接力每个 ESP-IDF 应用程序或引导加载程序的.bin文件头部都内嵌了以下三个配置CONFIG_ESPTOOLPY_FLASHMODEFlash 工作模式CONFIG_ESPTOOLPY_FLASHFREQFlash 时钟频率CONFIG_ESPTOOLPY_FLASHSIZEFlash 容量两级接力流程**一级引导加载程序ROM**从 Flash 中读取二级引导加载程序文件头中的配置信息并用这些信息加载剩余的二级引导加载程序。但此时系统时钟速度低于配置值且只支持部分 Flash 模式二级引导加载程序运行时会从当前选中的应用程序二进制文件头中读取配置而不是从二级引导加载程序自己的文件头读取并用这些数据重新配置 Flash。这样的设计使得OTA 更新可以改变当前使用的 SPI Flash 配置如从 DIO 切换到 QIO、调整频率等。ESP32 历史背景ESP-IDF V4.0 之前的引导加载程序使用自身文件头配置 SPI Flash导致 OTA 更新时无法更改 Flash 配置。为兼容旧引导加载程序ESP32 应用程序在启动期间会使用应用程序文件头中的配置重新初始化 Flash 配置。与 Flash 配置相关的引导加载程序选项还包括见 Kconfig.projbuild 的 Serial Flash Configurations 菜单CONFIG_BOOTLOADER_SPI_CUSTOM_WP_PIN/CONFIG_BOOTLOADER_SPI_WP_PIN在 eFuse 覆盖了 SPI Flash 引脚且使用 QIO/QOUT 模式时自定义 WP 引脚默认 GPIO 7CONFIG_BOOTLOADER_FLASH_DC_AWARE允许应用程序为更高频率调整 SPI Flash 的 Dummy Cycle 位CONFIG_BOOTLOADER_FLASH_XMC_SUPPORTXMC Flash 芯片的启动流程支持默认启用不建议关闭CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH使 CPU 可访问 16MB 以上 32 位地址范围的 Flash实验特性。四、日志级别用启动时间换可调试性引导加载程序日志的默认级别为Info。通过配置CONFIG_BOOTLOADER_LOG_LEVEL可以增加或减少这个级别。该日志级别与应用程序中使用的日志级别相互独立应用日志级别见 log.rst。值得注意的是降低引导加载程序日志的详细程度可以稍微缩短整个项目的启动时间同时也会减小二进制体积详见下文引导加载程序大小一节。五、恢复出厂设置Factory Reset当 OTA 更新出现问题时设备需要一个回到已知正常状态的机制这就是恢复出厂设置。在引导加载程序中启用CONFIG_BOOTLOADER_FACTORY_RESET后设备可以恢复原始出厂设置并清除所有用户设置。5.1 两种恢复方式恢复出厂设置支持以下两种方式两者可以独立启用或同时启用方式一清除一个或多个数据分区CONFIG_BOOTLOADER_DATA_FACTORY_RESET选项用于指定恢复出厂设置时需要擦除的数据分区。分区名称使用逗号分隔的列表为提高可读性可加空格例如nvs, phy_init, nvs_custom注意事项选项里指定的分区名称必须与分区表中的名称完全一致此处不能指定类型为 app 的分区。方式二从工厂应用分区启动启用CONFIG_BOOTLOADER_OTA_DATA_ERASE后恢复出厂设置后设备将从默认的工厂应用分区启动如果分区表中没有工厂应用分区则从默认的 OTA 应用分区启动。该恢复过程通过擦除 OTA 数据分区完成——OTA 数据分区中保存了当前选择的 OTA 分区槽。工厂应用分区槽如果存在永远不会通过 OTA 更新因此重置为从工厂分区启动即意味着让固件应用程序恢复正常状态。从源码看恢复出厂设置的触发与执行逻辑位于 bootloader_start.c检测到 GPIO 长时间保持配置电平后调用bootloader_common_erase_part_type_data()擦除指定分区并通过bootloader_common_set_rtc_retain_mem_factory_reset_state()记录出厂重置状态。5.2 触发条件相关配置以下配置项控制恢复出厂设置的触发条件配置项说明默认值CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET用于触发出厂重置的输入 GPIO 编号4CONFIG_BOOTLOADER_HOLD_TIME_GPIO管脚电平保持时间秒5CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL触发电平高/低Reset on GPIO low/Reset on GPIO high低电平必须在设备重置时将指定管脚拉低或拉高电平可配置并保持CONFIG_BOOTLOADER_HOLD_TIME_GPIO设定的时间才能触发出厂长重置事件。如果管脚具有内部上拉上拉会在管脚采样前生效具体内部上拉能力请查阅对应芯片的技术规格书。注意部分 SoC 上并非所有引脚都有内部上拉且部分引脚已被 ROM 引导加载程序用作启动bootstrapping引脚请参考对应芯片的技术参考手册见 Kconfig.projbuild 中的帮助文本。5.3 应用如何获知出厂重置已发生支持 RTC FAST 内存的芯片应用可通过调用bootloader_common_get_rtc_retain_mem_factory_reset_state函数判断读到状态为true说明设备已触发出厂重置函数随后会把状态重置为 false以便后续判断读到状态为false说明设备并未触发出厂重置或保存该状态的内存区域已失效。注意该功能会占用部分 RTC FAST 内存占用大小与CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP特性相同。不支持 RTC FAST 内存的芯片没有对应的 API 可用于监测。替代方案是设置一个在出厂重置时会被引导加载程序擦除的 NVS 分区需将该分区加入CONFIG_BOOTLOADER_DATA_FACTORY_RESET并在该 NVS 分区保存一个自增令牌factory_reset_state。当应用读取到factory_reset_state为 0 时即表明触发了出厂重置。六、从测试固件启动Boot from Test Firmware用户可以编写用于生产环境测试的特殊固件并在需要时运行。该机制需要在项目分区表中专门申请一个测试固件分区类型为app子类型为test详见 partition-tables.rst为测试应用创建完全独立的 ESP-IDF 项目ESP-IDF 中每个项目仅构建一个应用可独立于主项目开发和测试在生成测试时将测试应用的预编译 .bin 文件烧录到主项目测试应用分区的地址。6.1 主项目引导加载程序配置在主项目的引导加载程序中启用CONFIG_BOOTLOADER_APP_TEST后需配置以下三个选项配置项说明默认值CONFIG_BOOTLOADER_NUM_PIN_APP_TEST触发 TEST 分区启动的 GPIO 编号该引脚被配置为输入并启用内部上拉18CONFIG_BOOTLOADER_HOLD_TIME_GPIOGPIO 电平保持时间秒5CONFIG_BOOTLOADER_APP_TEST_PIN_LEVEL触发电平高/低Enter test app on GPIO low/Enter test app on GPIO high低电平在设备重置时必须将指定管脚拉低或拉高可配置并保持设定时间才会触发测试应用引导。释放管脚输入并重启设备后将重新启用默认的启动顺序——即启动工厂分区或任意 OTA 应用分区槽。注意CONFIG_BOOTLOADER_APP_TEST依赖!CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK即启用应用防回滚时无法使用测试固件引导功能见 Kconfig.projbuild。源码对应逻辑位于 bootloader_start.c检测到 GPIO 长时间保持后检查bs-test.offset ! 0分区表中存在 test 分区则将引导索引设为TEST_APP_INDEX否则报错并复位。七、回滚Rollback回滚和反回滚功能也必须在引导加载程序中配置。相关选项位于 Kconfig.app_rollbackCONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE启用应用回滚支持。OTA 更新后引导加载程序会以ESP_OTA_IMG_PENDING_VERIFY状态运行新应用应用首次启动后需在用户代码中调用接口确认可操作性若应用工作正常则标记为有效否则标记为无效并回滚到上一个正常工作的应用。注意如果在首次启动新应用时断电或看门狗触发也会发生回滚CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK启用应用防回滚防止回滚到安全版本号更低的固件。启用后分区表需使用ota_0 ota_1无 factory的方案CONFIG_BOOTLOADER_APP_SECURE_VERSION固件的安全版本号记录在 eFuse 字段中引导加载程序只会选择安全版本号大于或等于 eFuse 记录值的应用启动CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELDeFuse 安全版本字段的大小ESP32 为 32 位、ESP32-C2 为 4 位、ESP32-C5 为 9 位、其他目标 16 位决定了安全版本可递增的次数CONFIG_BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE仅用于测试可在不烧写 eFuse 的情况下模拟安全版本读写需在分区表中添加emul_efuse, data, efuse, , 0x2000条目。详细的回滚/防回滚 API 请参考 ota.rst 中的 回滚 (app_rollback) 与 防回滚 (anti-rollback) 章节。八、看门狗Watchdog芯片配备两组看门狗定时器主系统看门狗定时器MWDT_WDTRTC 看门狗定时器RTC_WDT芯片上电时两组看门狗都会被启用但在引导加载程序中会被禁用。启用CONFIG_BOOTLOADER_WDT_ENABLE默认开启后RTC 看门狗定时器会被重新启用用于跟踪从引导加载程序启用直到调用用户main函数的时间。此期间 RTC 看门狗始终可用如果在 9 秒内没有应用程序成功启动RTC 看门狗会自动复位芯片可有效防止启动过程中因电源不稳定导致的死机。相关配置项配置项说明默认值CONFIG_BOOTLOADER_WDT_ENABLE在启动代码中使用 RTC 看门狗yCONFIG_BOOTLOADER_WDT_TIME_MSRTC 看门狗超时时间ms需大于启动代码实际执行时间9000范围 0~120000CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE允许在用户代码中禁用 RTC 看门狗n注意事项调整超时时间需修改CONFIG_BOOTLOADER_WDT_TIME_MS并重新编译引导加载程序通过禁用CONFIG_BOOTLOADER_WDT_ENABLE并重新编译可以在引导加载程序中禁用 RTC 看门狗但不建议这样做若启用CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE应用必须显式调用wdt_hal_feed()或 ESP32/ESP32-S2 的rtc_wdt_feed()喂狗、或wdt_hal_disable()或rtc_wdt_disable()禁用 RTC_WDT注意恢复出厂设置、触发测试分区、启动时加密等操作会增加启动代码执行时间需相应调整超时值见 Kconfig.projbuild。应用程序中使用 RTC_WDT 的方法参见硬件看门狗定时器章节。九、引导加载程序大小一个必须监控的指标9.1 各芯片的引导加载程序上限不同芯片的引导加载程序最大尺寸不同ESP3248 KB0xC000 字节ESP32-S2 / ESP32-S3 / ESP32-C2 / ESP32-C3 / ESP32-C6 / ESP32-H2 / ESP32-H21 / ESP32-P464 KB0x10000 字节其他默认80 KB0x14000 字节对应可用的最大分区表偏移默认引导加载程序大小 0x1000 签名扇区 起始保留区为ESP320xE000ESP32-C5 / ESP32-H4 / ESP32-S310x17000起始 0x2000 引导加载程序 0x1000 签名扇区支持 Key Manager 的目标ESP32-C610x15000ESP32-P40x13000其他默认0x11000当启用额外的引导加载程序功能包括 Flash 加密 或 Secure Boot尤其是设置了较高的CONFIG_BOOTLOADER_LOG_LEVEL日志级别时监控引导加载程序 .bin 文件的大小变得非常重要。使用默认的CONFIG_PARTITION_TABLE_OFFSET值 0x8000 时二进制文件最大可为 0x8000 字节即分区表偏移量本身。9.2 过大导致的后果构建失败报错Bootloader binary size [..] is too large for partition table offset如果二进制文件已被强行烧录芯片将无法启动——日志中会记录无效分区表或无效引导加载程序校验和的错误。9.3 解决方法恢复编译器优化级别将CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION重新设置回默认值 Size-OsClang 下为-Oz。可选级别见 Kconfig.projbuildSize默认、Debug-Og、Performance-O2降低引导加载程序日志级别CONFIG_BOOTLOADER_LOG_LEVEL设置为 Warning、Error 或 None 都会显著减小最终二进制大小但可能让调试更困难增大分区表偏移将CONFIG_PARTITION_TABLE_OFFSET设置为高于 0x8000 的值把分区表放到 Flash 更靠后的位置从而为引导加载程序腾出更多空间。如果分区表 CSV 文件包含显式分区偏移量需修改这些偏移量保证没有分区的偏移量低于CONFIG_PARTITION_TABLE_OFFSET 0x1000包括 ESP-IDF 自带的默认分区 CSV 文件。9.4 Secure Boot V2 的绝对限制启用 Secure Boot V2 时由于引导加载程序最先被加载到固定大小的缓冲区中进行验证其二进制大小存在绝对限制——即上表中的最大尺寸不含 4 KB 签名。十、从深度睡眠中快速启动引导加载程序提供CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP选项可减少从深度睡眠中唤醒的时间有利于降低功耗。其原理是跳过镜像校验。可用条件该选项在CONFIG_SECURE_BOOT禁用时可用也可在启用 Secure Boot 的同时开启 允许不安全选项CONFIG_SECURE_BOOT_INSECURE时使用——但强烈不建议这样做因为可能绕过 Secure Boot 校验见 Kconfig.projbuild。不同芯片的实现机制支持 RTC FAST 内存的芯片首次启动时引导加载程序将启动的应用程序地址存储在 RTC FAST 存储器中唤醒时直接使用该地址启动而无需任何检查实现快速加载不支持 RTC 存储器的芯片无法保存正在运行的分区状态每次唤醒会读取整个分区表并加载正确的应用程序但不进行额外检查因此加载速度也更快。此外还有两个相关选项仅在不启用 Secure Boot 签名校验时可用CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON跳过上电复位的镜像校验显著缩短上电启动时间。但此时引导加载程序无法检测应用镜像损坏也就无法安全回退到其他应用分区建议同时保持CONFIG_BOOTLOADER_WDT_ENABLE开启以增加从 Flash 损坏中恢复的概率CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS完全跳过镜像校验任何所选应用分区的 Flash 损坏都会导致整个芯片无法启动不推荐仅在启动时间成为唯一关键因素时考虑。十一、自定义引导加载程序用户可以扩展或修改当前的引导加载程序有两种方式实现钩子hooks或重写覆盖override。两种方式在 examples/custom_bootloader 示例中均有呈现custom_bootloader/bootloader_hooks介绍如何将钩子与引导加载程序初始化连接custom_bootloader/bootloader_override介绍如何覆盖引导加载程序的实现另有 custom_bootloader/bootloader_multiboot 与 custom_bootloader/bootloader_extra_dir 展示更多自定义场景。11.1 钩子机制Hooks钩子函数的声明位于 bootloader_hooks.h两个函数均为weak 符号用户项目可按需重新定义bootloader_before_init()在二级引导加载程序初始化之前执行bootloader_after_init()在二级引导加载程序初始化之后执行。示例实现见 hooks.cvoid bootloader_hooks_include(void){ /* 该函数用于告知链接器包含此文件及其全部符号 */ } void bootloader_before_init(void) { /* 注意此时系统尚未完成初始化 * 包括 BSS、SPI flash、内存保护等 * 因此很多函数不能在此调用。 */ ESP_LOGI(HOOK, This hook is called BEFORE bootloader initialization); } void bootloader_after_init(void) { ESP_LOGI(HOOK, This hook is called AFTER bootloader initialization); }在 bootloader_start.c 中可以看到钩子的调用时机硬件初始化前调用bootloader_before_init()初始化完成后调用bootloader_after_init()。11.2 覆盖机制Override通过覆盖call_start_cpu0()函数可以完全接管引导流程。示例见 bootloader_override 的 bootloader_start.c其在原有流程基础上加入了自定义打印void __attribute__((noreturn)) call_start_cpu0(void) { // 1. Hardware initialization if (bootloader_init() ! ESP_OK) { bootloader_reset(); } // 2. Select the number of boot partition bootloader_state_t bs {0}; int boot_index select_partition_number(bs); if (boot_index INVALID_INDEX) { bootloader_reset(); } // 2.1 Print a custom message! esp_rom_printf([%s] %s\n, TAG, CONFIG_EXAMPLE_BOOTLOADER_WELCOME_MESSAGE); // 3. Load the app image for booting bootloader_utility_load_boot_image(bs, boot_index); }11.3 使用限制与 bootloader_components 目录在引导加载程序的代码中不能使用其他组件提供的驱动和函数除非某个驱动或函数明确声明支持在引导加载程序中运行。如果确实需要应将所需功能放在项目的bootloader_components目录中注意这会增加引导加载程序的大小。可以在引导加载程序中使用的组件示例nvs_bootloader见 examples/storage/nvs/nvs_bootloader支持在引导加载程序阶段读取 NVS 数据。如果引导加载程序过大可能与内存中的分区表重叠分区表默认烧录在偏移 0x8000 处。此时可增大分区表偏移量CONFIG_PARTITION_TABLE_OFFSET将分区表放到 Flash 更靠后的区域以增加引导加载程序的可用空间。十二、恢复引导加载程序与防回滚Recovery / Anti-rollback Bootloader对于支持SOC_RECOVERY_BOOTLOADER_SUPPORTED的目标芯片如 ESP32-C5 等新一代 SoCESP-IDF 引入了恢复引导加载程序Recovery Bootloader与防回滚引导加载程序Anti-rollback Bootloader功能。这两项功能在ROM 引导加载程序中实现用于提升设备在 OTA 升级过程中的安全性和可靠性。相关配置位于 Kconfig.bootloader_rollback。12.1 恢复引导加载程序为 Bootloader 本身提供 OTA 安全回退恢复引导加载程序功能可在 OTA 升级失败时为引导加载程序提供安全回退机制eFuse 字段ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR指定恢复引导加载程序的 Flash 地址以扇区为单位如果位于CONFIG_BOOTLOADER_OFFSET_IN_FLASH的主引导加载程序加载失败ROM 引导加载程序会尝试从指定地址加载恢复引导加载程序。关键配置与操作配置项说明默认值CONFIG_BOOTLOADER_RECOVERY_ENABLE启用恢复引导加载程序依赖SOC_RECOVERY_BOOTLOADER_SUPPORTEDnCONFIG_BOOTLOADER_RECOVERY_OFFSET恢复引导加载程序的 Flash 偏移地址必须是 Flash 扇区大小0x1000 字节的整数倍该 Kconfig 选项可帮助验证其不与现有分区重叠0x3F0000范围 0x0~0xFFE000操作要点eFuse 可使用espefuse工具或在用户应用程序中调用esp_efuse_set_recovery_bootloader_offset()设置eFuse 字段存储的是以扇区为单位的偏移量将其设置为最大值0xFFF可禁用恢复引导加载程序功能默认情况下CONFIG_BOOTLOADER_RECOVERY_OFFSET处的恢复引导加载程序镜像不会被烧录但可以作为 OTA 升级流程的一部分写入。主引导加载程序加载失败时的引导日志示例ESP-ROM:esp32c5-eco2-20250121 Build:Jan 21 2025 rst:0x1 (POWERON),boot:0x18 (SPI_FAST_FLASH_BOOT) invalid header: 0xffffffff invalid header: 0xffffffff invalid header: 0xffffffff PRIMARY - FAIL Loading RECOVERY Bootloader... SPI mode:DIO, clock div:1 load:0x408556b0,len:0x17cc load:0x4084bba0,len:0xdac load:0x4084e5a0,len:0x3140 entry 0x4084bbaa I (46) boot: ESP-IDF v6.0-dev-172-g12c5d730097-dirty 2nd stage bootloader I (46) boot: compile time May 22 2025 12:41:59 I (47) boot: chip revision: v1.0 I (48) boot: efuse block revision: v0.1 I (52) boot.esp32c5: SPI Speed : 80MHz I (55) boot.esp32c5: SPI Mode : DIO I (59) boot.esp32c5: SPI Flash Size : 4MB I (63) boot: Enabling RNG early entropy source... I (67) boot: Partition Table: ...日志中的PRIMARY - FAIL表示主引导加载程序验证失败随后Loading RECOVERY Bootloader...加载恢复引导加载程序最终正常进入二级引导加载程序流程。12.2 防回滚功能Anti-Rollback防回滚功能可防止降级到可能存在安全漏洞的旧版引导加载程序引导加载程序头部包含安全版本号由CONFIG_BOOTLOADER_SECURE_VERSION定义默认 0范围 0~4设置EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN后ROM 引导加载程序将该安全版本号与EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION中存储的值比对只有版本号大于或等于 eFuse 值的引导加载程序才允许启动。相关机制如果设置了EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROMROM 引导加载程序可以更新 eFuse 中的安全版本号随着新引导加载程序版本的发布安全版本号会递增且不能降低如果 ROM 引导加载程序未更新 eFuse 中的安全版本号应用程序可以通过esp_efuse_write_field_blob函数更新。配置入口Kconfig.bootloader_rollbackCONFIG_BOOTLOADER_ANTI_ROLLBACK_ENABLE启用引导加载程序防回滚支持依赖恢复引导加载程序启用CONFIG_BOOTLOADER_SECURE_VERSION引导加载程序的安全版本号。当旧版本存在重大安全漏洞且不可接受时应提高该值。12.3 相关 eFuse 一览eFuse 字段位数说明EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR12 位恢复引导加载程序的 Flash 扇区地址。默认值 0禁用设置为其他值则启用设置为 0xFFF 时永久禁用EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN1 位在 ROM 引导加载程序中启用防回滚检查EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION4 位防回滚保护的安全版本号该值随位数增加而递增——0x0、0x1、0x3、0x7、0xFEFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM1 位允许 ROM 引导加载程序更新 eFuse 中的安全版本号重要提醒建议使用以上功能提升设备在 OTA 升级过程中的安全性和可靠性但请谨慎规划 eFuse 的烧录——这些设置是永久性的可能影响未来的升级策略。总结引导加载程序配置速查功能领域核心配置项默认值日志CONFIG_BOOTLOADER_LOG_LEVELInfo编译器优化CONFIG_BOOTLOADER_COMPILER_OPTIMIZATIONSize-Os恢复出厂设置CONFIG_BOOTLOADER_FACTORY_RESET/CONFIG_BOOTLOADER_DATA_FACTORY_RESET/CONFIG_BOOTLOADER_OTA_DATA_ERASE/CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET/CONFIG_BOOTLOADER_HOLD_TIME_GPIO/CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVELn / nvs / n / 4 / 5s / 低电平测试固件引导CONFIG_BOOTLOADER_APP_TEST/CONFIG_BOOTLOADER_NUM_PIN_APP_TEST/CONFIG_BOOTLOADER_APP_TEST_PIN_LEVELn / 18 / 低电平看门狗CONFIG_BOOTLOADER_WDT_ENABLE/CONFIG_BOOTLOADER_WDT_TIME_MS/CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODEy / 9000ms / n深度睡眠快速启动CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP/CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON/CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYSn / n / n应用回滚CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE/CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK/CONFIG_BOOTLOADER_APP_SECURE_VERSIONn / n / 0恢复/防回滚CONFIG_BOOTLOADER_RECOVERY_ENABLE/CONFIG_BOOTLOADER_RECOVERY_OFFSET/CONFIG_BOOTLOADER_ANTI_ROLLBACK_ENABLE/CONFIG_BOOTLOADER_SECURE_VERSIONn / 0x3F0000 / n / 0引导加载程序的所有配置均可在项目的sdkconfig或通过idf.py menuconfig完成修改后需重新编译并烧录引导加载程序idf.py bootloader-flash才会生效。合理规划这些选项是构建稳定、可维护、可安全升级的 ESP-IDF 产品的第一步。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考