系统

Xtensa

Xtensa 特殊寄存器头文件已更新，使用新的命名约定。旧的 specreg.h 头文件现已被弃用，并将在未来版本中移除。

寄存器名称已更新为使用 XT_REG_ 前缀。请使用新的 xt_specreg.h 文件。

电源管理

在旧版本的 ESP-IDF 中，使用 esp_sleep_get_wakeup_cause() API 获取芯片从睡眠中唤醒的原因，然而，该函数在多个唤醒源同时激活的情况下，只会返回其中一个唤醒源，可能导致用户遗漏其他同时发生的唤醒条件。

自 v6.0 版本起，ESP-IDF 新增 esp_sleep_get_wakeup_causes() API，此函数返回一个 bitmap，表示所有触发唤醒的唤醒源。每一位对应 esp_sleep_wakeup_cause_t 枚举中的一个值（例如 ESP_SLEEP_WAKEUP_TIMER、ESP_SLEEP_WAKEUP_EXT1 等），用户可以通过按位与操作判断是否被对应源唤醒。

原先的 esp_sleep_get_wakeup_cause() 函数现已标记为已弃用，建议用户迁移至新接口。未来版本中，该函数可能会被移除。用户可按以下示例进行迁移：

旧代码：

esp_sleep_wakeup_cause_t cause = esp_sleep_get_wakeup_cause();
if (cause == ESP_SLEEP_WAKEUP_EXT1) {
    handle_ext1_wakeup();
}

现在需要修改成：

uint32_t causes = esp_sleep_get_wakeup_causes();
if (causes & BIT(ESP_SLEEP_WAKEUP_EXT1)) {
    handle_ext1_wakeup();
}
if (causes & BIT(ESP_SLEEP_WAKEUP_TIMER)) {
    handle_timer_wakeup();
}

引导加载程序

已移除使用无优化等级 (-O0, CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_NONE) 编译引导加载程序的选项。在大多数芯片上，使用 -O0 编译引导加载程序已无法成功，因为 IRAM 段会溢出。对于调试目的，推荐使用 -Og (CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG) 优化等级，它在优化效果与可调试性之间提供了良好的平衡。

时间管理

已弃用的头文件 ESP32-P4/rtc.h 已被移除，请改用替代头文件 esp_rtc_time.h。
已弃用的 RTC_CLK_SRC_INT_RC32K 配置项已被移除，内部 RC32K 时钟在极端温度下不稳定，请不要使用该时钟作为 RTC 低速时钟的时钟源。

硬件支持

已弃用的头文件 soc_memory_types.h 已被移除，请改用替代头文件 esp_memory_utils.h。

已弃用的头文件 intr_types.h 已被移除，请改用替代头文件 esp_intr_types.h。

已弃用的头文件 esp_private/interrupt_deprecated.h （此前通过 riscv/interrupt.h 头文件提供）已被移除。相关已弃用的函数不再可用，请改用非弃用版本。

头文件 esp_fault.h 已从 esp_hw_support 组件移动到 esp_common 组件。如果应用程序在此更改后遇到构建错误，请在 CMakeLists.txt 中将 esp_common 添加到组件的 REQUIRES 或 PRIV_REQUIRES 列表中。

ROM 头文件

已从 ets_sys.h ROM 头文件中移除了已弃用的 STATUS 类型。请改用 ETS_STATUS。

App 追踪

配置更改

此前，当配置传输目标时，应用程序跟踪会自动启用。现在必须在配置任何目标前，通过 CONFIG_APPTRACE_ENABLE 选项显式启用应用程序跟踪功能。

如需启用应用程序跟踪，请在 menuconfig 中依次进入 "Component config" → "Application Level Tracing" → "Enable Application Level Tracing" 进行设置。

已移除额外数据缓冲选项。不再支持 CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX 配置项。

已移除弃用的 ESP_APPTRACE_DEST_TRAX 枚举值。请改用 ESP_APPTRACE_DEST_JTAG。

初始化流程更改

如需在运行时覆盖默认配置，可以实现 esp_apptrace_get_user_params() 回调函数。系统提供了一个弱默认实现，返回 menuconfig 的默认配置（APPTRACE_CONFIG_DEFAULT()）。您的应用程序可以通过提供自己的配置来覆盖此默认实现。

esp_apptrace_config_t esp_apptrace_get_user_params(void)
{
    esp_apptrace_config_t config = APPTRACE_CONFIG_DEFAULT();

    // 使用自定义值覆盖（UART 示例）
    config.dest_cfg.uart.uart_num = UART_NUM_0;
    config.dest_cfg.uart.baud_rate = 921600;
    config.dest_cfg.uart.tx_pin_num = GPIO_NUM_17;
    config.dest_cfg.uart.rx_pin_num = GPIO_NUM_16;

    return config;
}

重要提示：

请勿在您的实现中添加 __attribute__((weak))
您也可以使用特定目标的宏：APPTRACE_JTAG_CONFIG_DEFAULT() 或 APPTRACE_UART_CONFIG_DEFAULT()

API 更改

所有 apptrace API 中的目标参数已被移除。

旧版本：

esp_apptrace_write(ESP_APPTRACE_DEST_JTAG, data, size, timeout);
esp_apptrace_read(ESP_APPTRACE_DEST_UART, buffer, &size, timeout);
esp_apptrace_flush(ESP_APPTRACE_DEST_JTAG, min_sz, timeout);

更新为：

esp_apptrace_write(data, size, timeout);
esp_apptrace_read(buffer, &size, timeout);
esp_apptrace_flush(min_sz, timeout);

目标现在在 menuconfig 中的 "Application Level Tracing" → "Data Destination" 下全局配置。

UART 目标配置已简化：

移除：通过 CONFIG_APPTRACE_DEST_UARTx=y 选择单个 UART
新增：通过 CONFIG_APPTRACE_DEST_UART_NUM 选择 UART 端口

迁移方法，更新你的 sdkconfig 配置：

旧配置：

CONFIG_APPTRACE_DEST_UART0=y
# 或
CONFIG_APPTRACE_DEST_UART1=y

新配置：

CONFIG_APPTRACE_DEST_UART=y
CONFIG_APPTRACE_DEST_UART_NUM=0  # 或 1、2，具体取决于目标芯片

SystemView 的传输目标

SystemView 的传输目标现在由与应用程序跟踪目标相同的配置控制。启用 SystemView 后，它将使用在 "Application Level Tracing" → "Data Destination" 下配置的目标传输方式。

这意味着如果同时启用了应用程序跟踪和 SystemView，它们将共享在 menuconfig 中配置的相同目标传输方式（JTAG 或 UART）。SystemView 将不再拥有独立的传输目标配置。

FreeRTOS

已移除的函数

以下已弃用的 FreeRTOS 函数已在 ESP-IDF v6.0 中移除：

xTaskGetAffinity() – 请使用 xTaskGetCoreID() 替代。
xTaskGetIdleTaskHandleForCPU() – 请使用 xTaskGetIdleTaskHandleForCore() 替代。
xTaskGetCurrentTaskHandleForCPU() – 请使用 xTaskGetCurrentTaskHandleForCore() 替代。

以下兼容性函数已在 ESP-IDF v6.0 中移除。这些函数原本是为了向后兼容旧版本 ESP-IDF 而维护的，因为它们在 FreeRTOS 中已被更改为宏或独立函数。现已移除此兼容性支持。

xQueueGenericReceive() - 请根据具体使用场景选择 xQueueReceive()、xQueuePeek() 或 xQueueSemaphoreTake() 替代。
vTaskDelayUntil() - 请使用 xTaskDelayUntil() 替代。
ulTaskNotifyTake() - 请使用宏 ulTaskNotifyTake 替代。
xTaskNotifyWait() - 请使用宏 xTaskNotifyWait 替代。

已弃用的函数

函数 pxTaskGetStackStart() 已弃用。请使用 xTaskGetStackStart() 替代以提高类型安全性。

新增 API

任务快照 API 已对外公开，以支持 ESP Insights 等外部框架。这些 API 现通过 freertos/freertos_debug.h 头文件提供，不再使用已弃用的 freertos/task_snapshot.h。

在调度程序运行时安全使用的方案是：调用快照函数前先执行 vTaskSuspendAll() 暂停所有任务，完成后调用 xTaskResumeAll() 恢复运行。

内存布局

为了减少 IRAM 的使用，大多数 FreeRTOS 函数的默认存储位置已从 IRAM 更改为 flash。因此，CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH 选项已被移除。这项变更可显著节省 IRAM 空间，但可能会对性能造成轻微影响。如果应用对性能有严苛要求，可通过启用新选项 CONFIG_FREERTOS_IN_IRAM 恢复原先配置。
启用 CONFIG_FREERTOS_IN_IRAM 前，建议进行性能测试以评估对具体应用场景的实际影响。flash 和 IRAM 配置的性能差异取决于 flash 缓存效率、API 调用模式和系统负载等因素。
components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c 中提供了基准性能测试。该测试测量常用 FreeRTOS API 的执行时长，可帮助开发者根据目标硬件和应用需求评估内存布局方案带来的性能影响。
当启用 CONFIG_ESP_PANIC_HANDLER_IRAM 时，任务快照函数会自动存入 IRAM，确保在系统崩溃处理期间仍可调用。
除非启用 CONFIG_FREERTOS_PLACE_ISR_FUNCTIONS_INTO_FLASH，否则 vTaskGetSnapshot 将始终保留在 IRAM 中，因为该函数被任务看门狗中断处理程序所调用。

已移除的配置选项

以下隐藏（且始终启用）的配置选项已被移除：

CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH

环形缓冲区

内存布局

为了减少 IRAM 的使用，esp_ringbuf 函数的默认位置已从 IRAM 更改为 flash。因此，CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH 选项已被移除。此举可节省大量 IRAM，但可能会对性能造成轻微影响。对于性能要求严苛的应用程序，可通过启用新增的 CONFIG_RINGBUF_IN_IRAM 选项来恢复之前的行为。

Log

已移除的函数

以下已弃用的 Log 函数已在 ESP-IDF v6.0 中移除：

esp_log_buffer_hex() – 请使用 ESP_LOG_BUFFER_HEX() 替代。
esp_log_buffer_char() – 请使用 ESP_LOG_BUFFER_CHAR() 替代。

已移除的头文件

esp_log_internal.h – 请使用 esp_log_buffer.h 替代。

ESP-Event

不必要的 FreeRTOS 头文件已从 esp_event.h 中移除。此前依赖这些隐式包含的代码，现在必须显式添加以下头文件：#include "freertos/queue.h" 和 #include "freertos/semphr.h"。

核心转储

二进制数据格式已被弃用。CONFIG_ESP_COREDUMP_DATA_FORMAT_BIN 表示该功能已完全删除，不再可用。现在默认的数据格式是 ELF。

CRC 数据完整性检查已被弃用。ESP_COREDUMP_CHECKSUM_CRC32 表示该功能已完全删除，不再可用。现在默认的校验和算法为 SHA256。

函数 esp_core_dump_partition_and_size_get() 现在对空白（已擦除）分区返回 ESP_ERR_NOT_FOUND，而不是 ESP_ERR_INVALID_SIZE。

OTA 更新

ESP HTTPS OTA 的分段下载功能已移至配置选项下，以便在未使用分段下载时减少内存占用。

如果要在 OTA 应用中使用分段下载功能，需要在 menuconfig 中启用组件级配置 CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD (Component config → ESP HTTPS OTA → Enable partial HTTP download for OTA)。

已移除的废弃 API

以下废弃函数已从 app_update 组件中移除：

esp_ota_get_app_description() – 请使用 esp_app_get_description() 代替。
esp_ota_get_app_elf_sha256() – 请使用 esp_app_get_elf_sha256() 代替。

这些函数已移至 esp_app_format 组件。请将包含文件从 esp_ota_ops.h 更新为 esp_app_desc.h，如有需要请将 esp_app_format 添加到您的组件依赖项中。

Gcov

gcov 组件已移至独立仓库。esp_gcov 现为托管组件。

组件依赖

使用 gcov 功能的项目现在必须在 idf_component.yml 清单文件中添加 esp_gcov 组件作为依赖项：

dependencies:
  espressif/esp_gcov: ^1

配置更改

gcov 配置选项已从应用程序级别追踪菜单移至专用的 GNU Code Coverage 菜单。

CONFIG_APPTRACE_GCOV_ENABLE 选项已重命名为 CONFIG_ESP_GCOV_ENABLE。

头文件更改

对于 gcov 功能，请改用 esp_gcov.h 头文件替代原有的 esp_app_trace.h。

系统控制台 (STDIO)

esp_vfs_cdcacm.h 头文件已移至新组件 esp_usb_cdc_romconsole 中。若需使用该头文件中的任何函数，现在需要显式添加对 esp_usb_cdc_rom_console 的 REQUIRES 依赖项。

LibC

CONFIG_COMPILER_ASSERT_NDEBUG_EVALUATE 的默认值已改为 n。这意味着当设置了 NDEBUG 时，断言将不再对断言内的表达式进行求值。此更改将默认行为恢复为与 C 语言标准一致。

ULP

LP-Core 在深度睡眠期间遇到异常时，将唤醒主 CPU。此功能默认启用，若不需要此行为，可以通过 CONFIG_ULP_TRAP_WAKEUP Kconfig 配置选项禁用。

`esp_common`

EXT_RAM_ATTR 自 v5.0 已弃用，现已移除。请使用 EXT_RAM_BSS_ATTR 宏将 .bss 放在 PSRAM 上。
RTC 相关内存属性 (RTC_x_ATTR) 已从没有 RTC 存储的芯片中移除。

此文档对您有帮助吗？

反馈已收到，谢谢！
如果您有其他意见，欢迎填写乐鑫文档反馈表。

我们重视您的反馈。
您可以填写乐鑫文档反馈表告诉我们如何改进该文档。

系统

Xtensa

电源管理

引导加载程序

时间管理

硬件支持

ROM 头文件

App 追踪

配置更改

初始化流程更改

API 更改

SystemView 的传输目标

FreeRTOS

已移除的函数

已弃用的函数

新增 API

内存布局

已移除的配置选项

环形缓冲区

内存布局

Log

已移除的函数

已移除的头文件

ESP-Event

核心转储

OTA 更新

已移除的废弃 API

Gcov

组件依赖

配置更改

头文件更改

系统控制台 (STDIO)

LibC

ULP

esp_common

`esp_common`