警告

This document is not updated for ESP32H2 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

系统

[英文]

跨核执行

跨核执行 (Inter-Processor Call, IPC) 不再是一个独立组件，现已被包含至 esp_system。

因此，若项目的 CMakeLists.txt 文件中出现 PRIV_REQUIRES esp_ipc 或 REQUIRES esp_ipc，应删除这些选项，因为项目中已默认包含 esp_system 组件。

ESP 时钟

ESP 时钟 API（即以 esp_clk 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 #include "ESP32-H2/clk.h" 和 #include "esp_clk.h" 已被移除。如仍需使用 ESP 时钟 API（并不推荐），请使用 #include "esp_private/esp_clk.h" 来包含。

注意

私有 API 不属于稳定的 API，不会遵循 ESP-IDF 的版本演进规则，因此不推荐用户在应用中使用。

缓存错误中断

缓存错误中断 API（即以 esp_cache_err 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 #include "ESP32-H2/cache_err_int.h" 已被移除。如仍需使用缓存错误中断 API（并不推荐），请使用 #include "esp_private/cache_err_int.h" 来包含。

bootloader_support

  • 函数 bootloader_common_get_reset_reason() 已被移除。请使用 ROM 组件中的函数 esp_rom_get_reset_reason()。

  • 函数 esp_secure_boot_verify_sbv2_signature_block() 和 esp_secure_boot_verify_rsa_signature_block() 已被移除，无新的替换函数。不推荐用户直接使用以上函数。如确需要，请在 GitHub 上对该功能提交请求，并解释您需要此函数的原因。

断电

断电 API（即以 esp_brownout 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 #include "brownout.h" 已被移除。如仍需使用断电 API（并不推荐），请使用 #include "esp_private/brownout.h" 来包含。

Trax

Trax API（即以 trax_ 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 #include "trax.h" 已被移除。如仍需使用 Trax API（并不推荐），请使用 #include "esp_private/trax.h" 来包含。

ROM

components/esp32/rom/ 路径下存放的已弃用的 ROM 相关头文件已被移除（原包含路径为 rom/*.h）。请使用新的特定目标的路径 components/esp_rom/include/ESP32-H2/``（新的包含路径为 ``ESP32-H2/rom/*.h）。

esp_hw_support

  • 头文件 soc/cpu.h 及弃用的 CPU util 函数都已被移除。请包含 esp_cpu.h 来代替相同功能的函数。

  • 头文件 hal/cpu_ll.h、hal/cpu_hal.h、hal/soc_ll.h、hal/soc_hal.h 和 interrupt_controller_hal.h 的 CPU API 函数已弃用。请包含 esp_cpu.h 来代替相同功能的函数。

  • 头文件 compare_set.h 已被移除。请使用 esp_cpu.h 中提供的 esp_cpu_compare_and_set() 函数来代替。

  • esp_cpu_get_ccount()、esp_cpu_set_ccount() 和 esp_cpu_in_ocd_debug_mode() 已从 esp_cpu.h 中移除。请分别使用 esp_cpu_get_cycle_count()、esp_cpu_set_cycle_count() 和 esp_cpu_dbgr_is_attached() 代替。

  • 头文件 esp_intr.h 已被移除。请包含 esp_intr_alloc.h 以分配和操作中断。

  • Panic API（即以 esp_panic 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 #include "esp_panic.h" 已被移除。如仍需使用 Panic API（并不推荐），请使用 #include "esp_private/panic_reason.h" 来包含。此外，请包含 esp_debug_helpers.h 以使用与调试有关的任意辅助函数，如打印回溯。

  • 头文件 soc_log.h 现更名为 esp_hw_log.h，并已更新为私有。建议用户使用 esp_log.h 头文件下的日志 API。

  • 包含头文件 spinlock.h、clk_ctrl_os.h 和 rtc_wdt.h 时不应当使用 soc 前缀，如 #include "spinlock.h"。

  • esp_chip_info() 命令返回芯片版本，格式为 = 100 * 主要 eFuse 版本 + 次要 eFuse 版本。因此，为适应新格式， esp_chip_info_t 结构体中的 revision 被扩展为 uint16_t。

PSRAM

  • 针对特定目标的头文件 spiram.h 及头文件 esp_spiram.h 已被移除，创建新组件 esp_psram。对于与 PSRAM 或 SPIRAM 相关的函数，请包含 esp_psram.h，并在 CMakeLists.txt 项目文件中将 esp_psram 设置为必需组件。

  • esp_spiram_get_chip_size 和 esp_spiram_get_size 已被移除，请使用 esp_psram_get_size。

eFuse

  • 函数 esp_secure_boot_read_key_digests() 的参数类型从 ets_secure_boot_key_digests_t* 更新为 esp_secure_boot_key_digests_t*。新类型与旧类型相同，仅移除了 allow_key_revoke 标志。在当前代码中，后者总是被设置为 true，并未提供额外信息。

  • 针对 eFuse 晶圆增加主要修订版本和次要修订版本。API esp_efuse_get_chip_ver() 与新修订不兼容，因此已被移除。请使用 API efuse_hal_get_major_chip_version()、efuse_hal_get_minor_chip_version() 或 efuse_hal_chip_revision() 来代替原有 API。

esp_common

EXT_RAM_ATTR 已被弃用。请使用新的宏 EXT_RAM_BSS_ATTR 以将 .bss 放在 PSRAM 上。

esp_system

  • 头文件 esp_random.h、esp_mac.h 和 esp_chip_info.h 以往都是通过头文件 esp_system.h 间接包含，更新后必须直接包含。已移除从 esp_system.h 中的间接包含功能。

  • 回溯解析器 API（即以 esp_eh_frame_ 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 #include "eh_frame_parser.h" 已被移除。如仍需使用回溯解析器 API（并不推荐），请使用 #include "esp_private/eh_frame_parser.h" 来包含。

  • 中断看门狗定时器 API（即以 esp_int_wdt_ 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 #include "esp_int_wdt.h" 已被移除。如仍需使用中断看门狗定时器 API（并不推荐），请使用 #include "esp_private/esp_int_wdt.h" 来包含。

SOC 依赖性

  • Doxyfiles 中列出的公共 API 头文件中不会显示不稳定和非必要的 SOC 头文件，如 soc/soc.h 和 soc/rtc.h。这意味着，如果用户仍然需要这些“缺失”的头文件，就必须在代码中明确包含这些文件。

  • Kconfig 选项 LEGACY_INCLUDE_COMMON_HEADERS 也已被移除。

  • 头文件 soc/soc_memory_types.h 已被弃用。请使用 esp_memory_utils.h。包含 soc/soc_memory_types.h 将触发构建警告，如 soc_memory_types.h is deprecated, please migrate to esp_memory_utils.h。

应用跟踪

其中一个时间戳源已从定时器组驱动改为新的 GPTimer。Kconfig 选项已重新命名，例如 APPTRACE_SV_TS_SOURCE_TIMER00 已更改为 APPTRACE_SV_TS_SOURCE_GPTIMER。用户已无需选择组和定时器 ID。

esp_timer

基于 FRC2 的 esp_timer 过去可用于 ESP32，现在已被移除，更新后仅可使用更简单有效的 LAC 定时器。

ESP 镜像

ESP 镜像中关于 SPI 速度的枚举成员已重新更名：

  • ESP_IMAGE_SPI_SPEED_80M 已被重新命名为 ESP_IMAGE_SPI_SPEED_DIV_1。

  • ESP_IMAGE_SPI_SPEED_40M 已被重新命名为 ESP_IMAGE_SPI_SPEED_DIV_2。

  • ESP_IMAGE_SPI_SPEED_26M 已被重新命名为 ESP_IMAGE_SPI_SPEED_DIV_3。

  • ESP_IMAGE_SPI_SPEED_20M 已被重新命名为 ESP_IMAGE_SPI_SPEED_DIV_4。

任务看门狗定时器

  • API esp_task_wdt_init() 更新后有如下变化：

    • 以结构体的形式传递配置。

    • 可将该函数配置为订阅空闲任务。

  • 原先的配置选项 CONFIG_ESP_TASK_WDT 被重新命名为 CONFIG_ESP_TASK_WDT_INIT 并引入了一个新选项 CONFIG_ESP_TASK_WDT_EN。

FreeRTOS

遗留 API 及数据类型

在以往版本中，ESP-IDF 默认设置 configENABLE_BACKWARD_COMPATIBILITY 选项，因此可使用 FreeRTOS v8.0.0 之前的函数名称和数据类型。该选项现在已默认禁用，因此默认情况下不再支持以往的 FreeRTOS 名称或类型。用户可以选择以下一种解决方式：

任务快照

头文件 task_snapshot.h 已从 freertos/task.h 中移除。如需使用任务快照 API，请包含 freertos/task_snapshot.h。

函数 vTaskGetSnapshot() 现返回 BaseType_t，成功时返回值为 pdTRUE，失败则返回 pdFALSE。

FreeRTOS 断言

在以往版本中，FreeRTOS 断言通过 FREERTOS_ASSERT kconfig 选项独立配置，不同于系统的其他部分。该选项已被移除，现在需要通过 COMPILER_OPTIMIZATION_ASSERTION_LEVEL 来完成配置。

FreeRTOS 移植相关的宏

已移除用以保证弃用 API 向后兼容性的 portmacro_deprecated.h 文件。建议使用下列函数来代替弃用 API。

  • portENTER_CRITICAL_NESTED() 已被移除，请使用 portSET_INTERRUPT_MASK_FROM_ISR() 宏。

  • portEXIT_CRITICAL_NESTED() 已被移除，请使用 portCLEAR_INTERRUPT_MASK_FROM_ISR() 宏。

  • vPortCPUInitializeMutex() 已被移除，请使用 spinlock_initialize() 函数。

  • vPortCPUAcquireMutex() 已被移除，请使用 spinlock_acquire() 函数。

  • vPortCPUAcquireMutexTimeout() 已被移除，请使用 spinlock_acquire() 函数。

  • vPortCPUReleaseMutex() 已被移除，请使用 spinlock_release() 函数。

应用程序更新

引导加载程序支持

芯片版本

在应用程序开始加载时，引导加载程序会检查芯片版本。只有当版本为 >= CONFIG_ESP32H2_REV_MIN 和 < CONFIG_ESP32H2_REV_MAX_FULL 时，应用程序才能成功加载。

在 OTA 升级时，会检查应用程序头部中的版本需求和芯片版本是否符合条件。只有当版本为 >= CONFIG_ESP32H2_REV_MIN 和 < CONFIG_ESP32H2_REV_MAX_FULL 时，应用程序才能成功更新。

提供有关此文档的反馈