系统

[英文]

跨核执行

跨核执行 (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-S3/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-S3/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-S3/``（新的包含路径为 ``ESP32-S3/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() 更新后有如下变化：

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

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

FreeRTOS

遗留 API 及数据类型

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

• 更新代码，删除以往的 FreeRTOS 名称或类型。

• 启用 CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY 以显式调用这些名称或类型。

任务快照

头文件 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_ESP32S3_REV_MIN 和 < CONFIG_ESP32S3_REV_MAX_FULL 时，应用程序才能成功加载。

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

提供有关此文档的反馈