# System

[中文]

## Xtensa

The Xtensa special register header files have been updated to use a new naming convention. The old `specreg.h` header files are now deprecated and will be removed in a future release.

The register names have been updated to use the `XT_REG_` prefix. Please use the new `xt_specreg.h` file instead.

## Power Management

In previous versions of ESP-IDF, the API `esp_sleep_get_wakeup_cause()` was used to retrieve the wakeup reason after the chip exited sleep. However, this function only returns one wakeup source, even if multiple sources were triggered simultaneously, which may cause users to miss other active wakeup events.

Since ESP-IDF v6.0, a new API `esp_sleep_get_wakeup_causes()` has been introduced. This function returns a bitmap representing all wakeup sources that caused the chip to exit sleep. Each bit corresponds to a value in the `esp_sleep_wakeup_cause_t` enum (e.g., ESP_SLEEP_WAKEUP_TIMER, ESP_SLEEP_WAKEUP_EXT1, etc.). Users can check each wakeup source using bitwise operations.

The original `esp_sleep_get_wakeup_cause()` function has been marked as deprecated, and it is recommended to migrate to the new interface. This legacy API may be removed in future versions. Migration can be performed as shown in the example below:

Old Version:

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

Update to:

    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();
    }

## Bootloader

Removed option for compiling bootloader with no optimization level (-O0, CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_NONE). On most targets it was no longer possible to compile the bootloader with -O0, as IRAM sections would overflow. For debugging purposes, it is recommended to use the -Og (CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG) optimization level instead. This provides a good balance between optimization and debuggability.

## Time

- The deprecated `ESP32-P4/rtc.h` header file has been removed. Please include the replacement `esp_rtc_time.h` instead.

- The deprecated `RTC_CLK_SRC_INT_RC32K` menuconfig option has been removed. Internal RC32K clock is unstable at extreme temperatures, please don't use this clock as the RTC slow clock source.

## HW-Support

The deprecated `soc_memory_types.h` header file has been removed. Please include the replacement `esp_memory_utils.h` instead.

The deprecated `intr_types.h` header file has been removed. Please include the replacement `esp_intr_types.h` instead.

The deprecated `esp_private/interrupt_deprecated.h` header file, previously accessible through `riscv/interrupt.h` header, has been removed. The deprecated functions are no longer available; please use the non-deprecated versions instead.

The `esp_fault.h` header file has been moved from the `esp_hw_support` component to the `esp_common` component. If your application encounters build errors after this change, add `esp_common` to your component's `REQUIRES` or `PRIV_REQUIRES` list in `CMakeLists.txt`.

## ROM Headers

The deprecated `STATUS` type has been removed from `ets_sys.h` ROM header files. Please use `ETS_STATUS` instead.

## App Trace

### Configuration Changes

Previously, application tracing was automatically enabled when a destination was configured. Now you must explicitly enable application tracing through `CONFIG_APPTRACE_ENABLE`` option before configuring any destination.

To enable application tracing, go to "Component config" → "Application Level Tracing" → "Enable Application Level Tracing" in menuconfig.

Removed extra data buffering option. `CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX` is no longer supported.

Removed deprecated `ESP_APPTRACE_DEST_TRAX` enum value. Use `ESP_APPTRACE_DEST_JTAG` instead.

### Initialization Flow Changes

If you need to override the default configuration at runtime, you can implement the `esp_apptrace_get_user_params()` callback function. A weak default implementation exists that returns menuconfig defaults (`APPTRACE_CONFIG_DEFAULT()`). Your application can override this by providing its own configuration.

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

>         // Override with custom values (example for 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;
>     }

> Important:

> - Do not add `__attribute__((weak))` to your implementation

> - You can also use destination-specific macros: `APPTRACE_JTAG_CONFIG_DEFAULT()` or `APPTRACE_UART_CONFIG_DEFAULT()`

### API Changes

The destination parameter has been removed from all apptrace APIs.

Old Version:

    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);

Update to:

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

The destination is now configured in menuconfig under "Application Level Tracing" → "Data Destination".

The UART destination configuration has been simplified:

- Removed: Individual UART selection via `CONFIG_APPTRACE_DEST_UARTx=y`

- Added: Single UART port selection via `CONFIG_APPTRACE_DEST_UART_NUM`

To migrate, update your sdkconfig:

Old configuration:

    CONFIG_APPTRACE_DEST_UART0=y
    # or
    CONFIG_APPTRACE_DEST_UART1=y

New configuration:

    CONFIG_APPTRACE_DEST_UART=y
    CONFIG_APPTRACE_DEST_UART_NUM=0  # or 1, 2 depending on target

### SystemView Destination

The SystemView destination is now controlled by the same configuration as the application trace destination. When SystemView is enabled, it will use the destination configured under "Application Level Tracing" → "Data Destination".

This means that if you have both application tracing and SystemView enabled, they will share the same destination (JTAG or UART) as configured in the menuconfig. SystemView will not have its own destination configuration.

## FreeRTOS

### Removed Functions

The following deprecated FreeRTOS functions have been removed in ESP-IDF v6.0:

- `xTaskGetAffinity()` – Use `xTaskGetCoreID()` instead.

- `xTaskGetIdleTaskHandleForCPU()` – Use `xTaskGetIdleTaskHandleForCore()` instead.

- `xTaskGetCurrentTaskHandleForCPU()` – Use `xTaskGetCurrentTaskHandleForCore()` instead.

The following compatibility functions have been removed in ESP-IDF v6.0. These functions were maintained for backward compatibility with previous ESP-IDF versions as they were changed to either macros or separate functions in FreeRTOS. This compatibility has been removed.

- `xQueueGenericReceive()` - Use `xQueueReceive()`, `xQueuePeek()`, or `xQueueSemaphoreTake()` instead, depending on your use case.

- `vTaskDelayUntil()` - Use `xTaskDelayUntil()` instead.

- `ulTaskNotifyTake()` - Use the macro `ulTaskNotifyTake` instead.

- `xTaskNotifyWait()` - Use the macro `xTaskNotifyWait` instead.

### Deprecated Functions

The function `pxTaskGetStackStart()` has been deprecated. Use `xTaskGetStackStart()` instead for improved type safety.

### API Added

Task snapshot APIs have been made public to support external frameworks like ESP Insights. These APIs are now provided through `freertos/freertos_debug.h` instead of the deprecated `freertos/task_snapshot.h`.

For safe use while the scheduler is running, use `vTaskSuspendAll()` before calling snapshot functions, and `xTaskResumeAll()` afterward.

### Memory Placement

- To reduce IRAM usage, the default placement for most FreeRTOS functions has been changed from IRAM to flash. Consequently, the `CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, you can restore the previous behavior by enabling the new CONFIG_FREERTOS_IN_IRAM option.

- Before enabling `CONFIG_FREERTOS_IN_IRAM`, it is recommended to run performance tests to measure the actual impact on your specific use case. The performance difference between flash and IRAM configurations depends on factors such as flash cache efficiency, API usage patterns, and system load.

- A baseline performance test is provided in `components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c`. This test measures the execution time of commonly used FreeRTOS APIs and can help you evaluate the effect of memory placement for your target hardware and application requirements.

- Task snapshot functions are automatically placed in IRAM when `CONFIG_ESP_PANIC_HANDLER_IRAM` is enabled, ensuring they remain accessible during panic handling.

- `vTaskGetSnapshot` is kept in IRAM unless `CONFIG_FREERTOS_PLACE_ISR_FUNCTIONS_INTO_FLASH` is enabled, as it is used by the Task Watchdog interrupt handler.

### Removed Configuration Options

The following hidden (and always true) configuration options have been removed:

- `CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT`

- `CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH`

## Ring Buffer

### Memory Placement

To reduce IRAM usage, the default placement for esp_ringbuf functions has been changed from IRAM to Flash. Consequently, the `CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, the previous behavior can be restored by enabling the new CONFIG_RINGBUF_IN_IRAM option.

## Log

### Removed Functions

The following deprecated Log functions have been removed in ESP-IDF v6.0:

- `esp_log_buffer_hex()` - Use `ESP_LOG_BUFFER_HEX()` instead.

- `esp_log_buffer_char()` - Use `ESP_LOG_BUFFER_CHAR()` instead.

### Removed Headers

- `esp_log_internal.h` - Use `esp_log_buffer.h` instead.

## ESP-Event

Unnecessary FreeRTOS headers have been removed from `esp_event.h`. Code that previously depended on these implicit includes must now include the headers explicitly: `#include "freertos/queue.h"` and `#include "freertos/semphr.h"` to your files.

## Core Dump

Binary data format has been dropped. CONFIG_ESP_COREDUMP_DATA_FORMAT_BIN is no longer supported. ELF is now the default data format.

CRC data integrity check has been dropped. ESP_COREDUMP_CHECKSUM_CRC32 is no longer supported. SHA256 is now the default checksum algorithm.

The function `esp_core_dump_partition_and_size_get()` now returns ESP_ERR_NOT_FOUND for blank (erased) partitions instead of ESP_ERR_INVALID_SIZE.

## OTA Updates

The partial download functionality in ESP HTTPS OTA has been moved under a configuration option in order to reduce the memory footprint if partial download is not used.

To use partial download features in your OTA applications, you need to enable the component-level configuration CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD in menuconfig (`Component config` → `ESP HTTPS OTA` → `Enable partial HTTP download for OTA`).

### Removed Deprecated APIs

The following deprecated functions have been removed from the `app_update` component:

- `esp_ota_get_app_description()` – Use `esp_app_get_description()` instead.

- `esp_ota_get_app_elf_sha256()` – Use `esp_app_get_elf_sha256()` instead.

These functions have moved to the `esp_app_format` component. Update your include from `esp_ota_ops.h` to `esp_app_desc.h` and add `esp_app_format` to your component dependencies if needed.

## Gcov

The gcov component has been moved to a separate repository. esp_gcov is now a managed component.

### Component Dependency

Projects using gcov functionality must now add the esp_gcov component as a dependency in their `idf_component.yml` manifest file:

    dependencies:
      espressif/esp_gcov: ^1

### Configuration Changes

The gcov configuration options have moved from the Application Level Tracing menu to a dedicated `GNU Code Coverage` menu section.

The `CONFIG_APPTRACE_GCOV_ENABLE` option has been renamed to `CONFIG_ESP_GCOV_ENABLE`.

### Header File Changes

For the gcov functionality, include the `esp_gcov.h` header file instead of `esp_app_trace.h`.

## System Console (STDIO)

`esp_vfs_cdcacm.h` has been moved to the new component `esp_usb_cdc_romconsole`, you will now have to add an explicit `REQUIRES` for `esp_usb_cdc_rom_console` if using any functions from this header.

## LibC

CONFIG_COMPILER_ASSERT_NDEBUG_EVALUATE default value is changed to n. This means asserts will no longer evaluate the expression inside the assert when `NDEBUG` is set. This reverts the default behavior to be in line with the C standard.

## ULP

The LP-Core will now wake up the main CPU when it encounters an exception during deep sleep. This feature is enabled by default but can be disabled via the CONFIG_ULP_TRAP_WAKEUP Kconfig option is this behavior is not desired.

## Heap

In previous versions of ESP-IDF, the capability MALLOC_CAP_EXEC would be available regardless of the memory protection configuration state. This implied that a call to e.g., `heap_caps_malloc()` with MALLOC_CAP_EXEC would return NULL when CONFIG_ESP_SYSTEM_MEMPROT_FEATURE or CONFIG_ESP_SYSTEM_PMP_IDRAM_SPLIT are enabled.

Since ESP-IDF v6.0, the definition of MALLOC_CAP_EXEC is conditional, meaning that if CONFIG_ESP_SYSTEM_MEMPROT is enabled, MALLOC_CAP_EXEC will not be defined. Therefore, using it will generate a compile time error.

## `esp_common`

- `EXT_RAM_ATTR` was deprecated since v5.0, Now it has been removed. Please use the macro `EXT_RAM_BSS_ATTR` to put `.bss` on PSRAM.

- RTC related memory attributes (`RTC_x_ATTR`) have been removed on those chips without RTC memory.

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.