feat(driver_twai): new driver sleep retention support

components/esp_driver_twai/esp_twai_onchip.c

@@ -298,6 +298,16 @@ static void _node_destroy(twai_onchip_ctx_t *twai_ctx)
     if (twai_ctx->pm_lock) {
         esp_pm_lock_delete(twai_ctx->pm_lock);
     }
+#endif
+#if SOC_TWAI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    const sleep_retention_module_t retention_id = twai_reg_retention_info[twai_ctx->ctrlr_id].module_id;
+    if (sleep_retention_is_module_created(retention_id)) {
+        assert(sleep_retention_is_module_inited(retention_id));
+        sleep_retention_module_free(retention_id);
+    }
+    if (sleep_retention_is_module_inited(retention_id)) {
+        sleep_retention_module_deinit(retention_id);
+    }
 #endif
     if (twai_ctx->intr_hdl) {
         esp_intr_free(twai_ctx->intr_hdl);
@@ -644,13 +654,25 @@ static esp_err_t _node_parse_rx(twai_node_handle_t node, twai_frame_t *rx_frame)
     return ESP_OK;
 }
 
+#if SOC_TWAI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+static esp_err_t _node_create_sleep_retention_cb(void *obj)
+{
+    twai_onchip_ctx_t *twai_ctx = (twai_onchip_ctx_t *)obj;
+    return sleep_retention_entries_create(twai_reg_retention_info[twai_ctx->ctrlr_id].entry_array,
+                                          twai_reg_retention_info[twai_ctx->ctrlr_id].array_size,
+                                          REGDMA_LINK_PRI_TWAI,
+                                          twai_reg_retention_info[twai_ctx->ctrlr_id].module_id);
+}
+#endif
 /* --------------------------------- Public --------------------------------- */
 esp_err_t twai_new_node_onchip(const twai_onchip_node_config_t *node_config, twai_node_handle_t *node_ret)
 {
     esp_err_t ret = ESP_OK;
     ESP_RETURN_ON_FALSE((node_config->tx_queue_depth > 0) || node_config->flags.enable_listen_only, ESP_ERR_INVALID_ARG, TAG, "tx_queue_depth at least 1");
     ESP_RETURN_ON_FALSE(!node_config->intr_priority || (BIT(node_config->intr_priority) & ESP_INTR_FLAG_LOWMED), ESP_ERR_INVALID_ARG, TAG, "Invalid intr_priority level");
-
+#if !SOC_TWAI_SUPPORT_SLEEP_RETENTION
+    ESP_RETURN_ON_FALSE(!node_config->flags.sleep_allow_pd, ESP_ERR_NOT_SUPPORTED, TAG, "sleep retention is not supported on this target");
+#endif
     // Allocate TWAI node from internal memory because it contains atomic variable
     twai_onchip_ctx_t *node = heap_caps_calloc(1, sizeof(twai_onchip_ctx_t) + twai_hal_get_mem_requirment(), MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT);
     ESP_RETURN_ON_FALSE(node, ESP_ERR_NO_MEM, TAG, "No mem");
@@ -691,6 +713,25 @@ esp_err_t twai_new_node_onchip(const twai_onchip_node_config_t *node_config, twa
 #endif
         node->timestamp_freq_hz = node_config->timestamp_resolution_hz;
     }
+#if SOC_TWAI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    const sleep_retention_module_t retention_id = twai_reg_retention_info[node->ctrlr_id].module_id;
+    sleep_retention_module_init_param_t init_param = {
+        .cbs = {
+            .create = {
+                .handle = _node_create_sleep_retention_cb,
+                .arg = node,
+            },
+        },
+        .depends = RETENTION_MODULE_BITMAP_INIT(CLOCK_SYSTEM)
+    };
+    if (sleep_retention_module_init(retention_id, &init_param) == ESP_OK) {
+        if ((node_config->flags.sleep_allow_pd) && (sleep_retention_module_allocate(retention_id) != ESP_OK)) {
+            ESP_LOGW(TAG, "sleep retention prepare failed, power will hold on");
+        }
+    } else {
+        ESP_LOGW(TAG, "sleep retention init failed, twai may offline after sleep");
+    }
+#endif  // SOC_TWAI_SUPPORT_SLEEP_RETENTION
     _lock_release(&s_platform.intr_mutex);
 
 #if CONFIG_PM_ENABLE
@@ -744,10 +785,9 @@ esp_err_t twai_new_node_onchip(const twai_onchip_node_config_t *node_config, twa
 
     *node_ret = &node->api_base;
     return ESP_OK;
+
 err:
-    if (node) {
-        _lock_release(&s_platform.intr_mutex);
-        _node_destroy(node);
-    }
+    _lock_release(&s_platform.intr_mutex);
+    _node_destroy(node);
     return ret;
 }

components/esp_driver_twai/include/esp_twai_onchip.h

@@ -35,6 +35,7 @@ typedef struct {
         uint32_t enable_loopback: 1;        /**< The TWAI controller receives back frames that it sends out, but does not acknowledge them */
         uint32_t enable_listen_only: 1;     /**< No transmissions or acknowledgements. The controller only monitors the bus without participating */
         uint32_t no_receive_rtr: 1;         /**< Don't receive remote frames */
+        uint32_t sleep_allow_pd: 1;         /**< Allow power down during sleep to save power, driver will backup/restore the TWAI registers to guarantee the peripheral features. */
     } flags;                                /**< Misc configuration flags */
 } twai_onchip_node_config_t;
 

components/esp_driver_twai/test_apps/test_twai/main/CMakeLists.txt

@@ -2,6 +2,9 @@ set(srcs "test_app_main.c")
 
 if(CONFIG_SOC_TWAI_SUPPORTED)
     list(APPEND srcs "test_twai_common.cpp" "test_twai_network.cpp")
+    if(CONFIG_SOC_LIGHT_SLEEP_SUPPORTED)
+        list(APPEND srcs "test_twai_sleep.c")
+    endif()
 endif()
 
 if(CONFIG_SOC_TWAI_FD_SUPPORTED)
@@ -10,6 +13,6 @@ endif()
 
 idf_component_register(
     SRCS ${srcs}
-    PRIV_REQUIRES esp_driver_twai esp_timer esp_driver_uart esp_psram esp_driver_gpio
+    PRIV_REQUIRES esp_driver_twai esp_timer esp_driver_uart esp_psram esp_driver_gpio esp_pm
     WHOLE_ARCHIVE
 )

components/esp_driver_twai/test_apps/test_twai/main/test_twai_common.cpp

@@ -19,12 +19,17 @@
 #include "esp_twai.h"
 #include "esp_twai_onchip.h"
 #include "hal/twai_periph.h"
-#include "esp_private/gpio.h"
 #include "soc/gpio_sig_map.h"
+#include "esp_private/gpio.h"
 #include "driver/uart.h" // for baudrate detection
 
+#if CONFIG_IDF_TARGET_ESP32H4
+#define TEST_TX_GPIO                GPIO_NUM_2
+#define TEST_RX_GPIO                GPIO_NUM_3
+#else
 #define TEST_TX_GPIO                GPIO_NUM_4
 #define TEST_RX_GPIO                GPIO_NUM_5
+#endif
 #define TEST_TWAI_QUEUE_DEPTH       5
 #define TEST_TRANS_LEN              100
 #define TEST_FRAME_LEN              7

components/esp_driver_twai/test_apps/test_twai/main/test_twai_sleep.c

@@ -0,0 +1,226 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <sys/param.h>
+#include "unity.h"
+#include "test_utils.h"
+#include "esp_log.h"
+#include "esp_pm.h"
+#include "esp_timer.h"
+#include "esp_rom_sys.h"
+#include "esp_private/esp_pmu.h"
+#include "esp_private/sleep_cpu.h"
+#include "esp_private/esp_sleep_internal.h"
+#include "esp_private/gpio.h"
+#include "hal/twai_periph.h"
+#include "esp_twai.h"
+#include "esp_twai_onchip.h"
+
+#if CONFIG_IDF_TARGET_ESP32H4
+#define TEST_TX_GPIO                GPIO_NUM_2
+#define TEST_RX_GPIO                GPIO_NUM_3
+#else
+#define TEST_TX_GPIO                GPIO_NUM_4
+#define TEST_RX_GPIO                GPIO_NUM_5
+#endif
+#define TEST_TWAI_QUEUE_DEPTH       5
+#define TEST_TRANS_LEN              100
+#define TEST_FRAME_LEN              7
+#define TEST_FRAME_NUM              howmany(TEST_TRANS_LEN, TEST_FRAME_LEN)
+
+static IRAM_ATTR bool test_sleep_rx_cb(twai_node_handle_t handle, const twai_rx_done_event_data_t *edata, void *user_ctx)
+{
+    twai_frame_t *rx_frame = (twai_frame_t *)user_ctx;
+    if (ESP_OK == twai_node_receive_from_isr(handle, rx_frame)) {
+        ESP_EARLY_LOGI("RX", "timestamp %llu frame %x [%d] %s", rx_frame->header.timestamp, rx_frame->header.id, rx_frame->header.dlc, rx_frame->buffer);
+    }
+    return false;
+}
+
+TEST_CASE("twai sleep retention", "[twai]")
+{
+    // Prepare a TOP PD sleep
+    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(1 * 1000 * 1000));
+#if CONFIG_PM_ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(true));
+#endif
+    esp_sleep_context_t sleep_ctx = {};
+    esp_sleep_set_sleep_context(&sleep_ctx);
+
+    twai_node_handle_t node_hdl[SOC_TWAI_CONTROLLER_NUM];
+    twai_onchip_node_config_t node_config = {};
+    node_config.io_cfg.quanta_clk_out = GPIO_NUM_NC;
+    node_config.io_cfg.bus_off_indicator = GPIO_NUM_NC;
+    node_config.bit_timing.bitrate = 800000;
+    node_config.timestamp_resolution_hz = 1000000;
+    node_config.tx_queue_depth = TEST_FRAME_NUM;
+    node_config.flags.enable_loopback = true;
+    node_config.flags.enable_self_test = true;
+
+    twai_frame_t tx_frame = {};
+    tx_frame.buffer = (uint8_t *)"sleep";
+    tx_frame.buffer_len = strlen((const char *)tx_frame.buffer);
+
+    uint8_t rx_buffer[TWAI_FRAME_MAX_LEN] = {0};
+    twai_frame_t rx_frame = {};
+    rx_frame.buffer = rx_buffer;
+    rx_frame.buffer_len = sizeof(rx_buffer);
+
+    twai_event_callbacks_t user_cbs = {};
+    user_cbs.on_rx_done = test_sleep_rx_cb;
+    for (int power = 0; power < 2; power++) {
+        node_config.flags.sleep_allow_pd = power;
+#if !SOC_TWAI_SUPPORT_SLEEP_RETENTION
+        node_config.flags.sleep_allow_pd = false;
+#endif
+        printf("\n===> Testing sleep power %s\n", node_config.flags.sleep_allow_pd ? "DOWN" : "HOLD");
+        for (int node = 0; node < SOC_TWAI_CONTROLLER_NUM; node++) {
+            node_config.io_cfg.tx = TEST_TX_GPIO;
+            node_config.io_cfg.rx = TEST_TX_GPIO;  // Using same pin for test without transceiver
+            TEST_ESP_OK(twai_new_node_onchip(&node_config, &node_hdl[node]));
+            TEST_ESP_OK(twai_node_register_event_callbacks(node_hdl[node], &user_cbs, &rx_frame));
+        }
+
+        for (int node = 0; node < SOC_TWAI_CONTROLLER_NUM; node++) {
+            printf("\nTWAI%d\n", node);
+            // fix signal connections after all nodes are created
+            gpio_matrix_input(TEST_TX_GPIO, twai_periph_signals[node].rx_sig, false);
+            gpio_matrix_output(TEST_TX_GPIO, twai_periph_signals[node].tx_sig, false, false);
+
+            // test with 2 transactions
+            for (int i = 1; i < 3; i++) {
+                printf("Go to sleep ...\n");
+                uint64_t time_before = esp_timer_get_time();
+                TEST_ESP_OK(esp_light_sleep_start());
+#if SOC_TWAI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+                printf("Waked up! sleep %d power down %ld\n", !sleep_ctx.sleep_request_result, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+                // check if the peripheral is powered down as expected
+                TEST_ASSERT_EQUAL(node_config.flags.sleep_allow_pd ? PMU_SLEEP_PD_TOP : 0, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+#endif
+                TEST_ESP_OK(twai_node_enable(node_hdl[node]));
+
+                tx_frame.header.id = i + node * 0x10;
+                memset(&rx_frame.header, 0, sizeof(rx_frame.header));
+                memset(rx_buffer, 0, sizeof(rx_buffer));
+                // Waiting 1 second after node_enable to check timestamp correctness after wakeup
+                esp_rom_delay_us(1000 * 1000);
+                TEST_ESP_OK(twai_node_transmit(node_hdl[node], &tx_frame, 100));
+                TEST_ESP_OK(twai_node_transmit_wait_all_done(node_hdl[node], -1));
+                TEST_ASSERT_EQUAL_HEX8_ARRAY(tx_frame.buffer, rx_buffer, tx_frame.buffer_len);
+                TEST_ASSERT_EQUAL_UINT32(tx_frame.header.id, rx_frame.header.id);
+                // sleep 1s, wait 1s, so diff should be 2000000us
+                printf("Time diff: %llu, expect 2000000\n", rx_frame.header.timestamp - time_before);
+                TEST_ASSERT_INT32_WITHIN(10000, 2000000, rx_frame.header.timestamp - time_before);
+                time_before = rx_frame.header.timestamp;
+                TEST_ESP_OK(twai_node_disable(node_hdl[node]));
+            }
+        }
+        for (int node = 0; node < SOC_TWAI_CONTROLLER_NUM; node++) {
+            TEST_ESP_OK(twai_node_delete(node_hdl[node]));
+        }
+    }
+
+    esp_sleep_set_sleep_context(NULL);
+#if CONFIG_PM_ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(false));
+#endif
+}
+
+#if SOC_TWAI_SUPPORT_SLEEP_RETENTION
+static void test_random_trans_generator(twai_node_handle_t node_hdl, uint32_t trans_num)
+{
+    uint8_t send_pkg_ptr[TWAI_FRAME_MAX_LEN];
+    twai_frame_t tx_msg = {};
+    tx_msg.buffer = send_pkg_ptr;
+
+    printf("Sending %ld random trans ...\n", trans_num);
+    for (uint32_t tx_cnt = 0; tx_cnt < trans_num; tx_cnt++) {
+        tx_msg.header.id = tx_cnt | 0xf000 | (tx_cnt << 16);
+        tx_msg.header.ide = !!(tx_cnt % 2);
+        tx_msg.header.rtr = !!(tx_cnt % 3);
+        tx_msg.buffer_len = tx_cnt % TWAI_FRAME_MAX_LEN;
+        TEST_ESP_OK(twai_node_transmit(node_hdl, &tx_msg, 0));
+        TEST_ESP_OK(twai_node_transmit_wait_all_done(node_hdl, 8));
+    }
+}
+
+static IRAM_ATTR bool test_filter_rx_done_cb(twai_node_handle_t handle, const twai_rx_done_event_data_t *edata, void *user_ctx)
+{
+    uint8_t *test_ctrl = (uint8_t *)user_ctx;
+    uint8_t recv_pkg_ptr[TWAI_FRAME_MAX_LEN];
+    twai_frame_t rx_frame = {};
+    rx_frame.buffer = recv_pkg_ptr;
+    rx_frame.buffer_len = TWAI_FRAME_MAX_LEN;
+
+    if (ESP_OK == twai_node_receive_from_isr(handle, &rx_frame)) {
+        ESP_EARLY_LOGI("Recv", "RX id 0x%4x len %2d ext %d rmt %d", rx_frame.header.id, twaifd_dlc2len(rx_frame.header.dlc), rx_frame.header.ide, rx_frame.header.rtr);
+        switch (test_ctrl[0]) {
+        case 0:         // receive something
+            TEST_ASSERT(rx_frame.header.id >= 0x10);
+            TEST_ASSERT(!rx_frame.header.ide);
+            break;
+        case 1:         // receive all
+        case 2: break;  // receive none
+        default: TEST_ASSERT(false);
+        }
+        test_ctrl[1] ++;
+    }
+    return false;
+}
+
+TEST_CASE("twai mask filter sleep retention", "[twai]")
+{
+    // Prepare a TOP PD sleep
+    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(1 * 1000 * 1000));
+#if CONFIG_PM_ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(true));
+#endif
+    esp_sleep_context_t sleep_ctx = {};
+    esp_sleep_set_sleep_context(&sleep_ctx);
+
+    twai_node_handle_t node_hdl;
+    twai_onchip_node_config_t node_config = {};
+    node_config.io_cfg.tx = TEST_TX_GPIO;
+    node_config.io_cfg.rx = TEST_TX_GPIO; // Using same pin for test without transceiver
+    node_config.io_cfg.quanta_clk_out = GPIO_NUM_NC;
+    node_config.io_cfg.bus_off_indicator = GPIO_NUM_NC;
+    node_config.bit_timing.bitrate = 1000000;
+    node_config.tx_queue_depth = TEST_TWAI_QUEUE_DEPTH;
+    node_config.flags.enable_self_test = true;
+    node_config.flags.enable_loopback = true;
+    node_config.flags.sleep_allow_pd = true;
+    TEST_ESP_OK(twai_new_node_onchip(&node_config, &node_hdl));
+
+    uint8_t test_ctrl[2] = {0, 0};
+    twai_event_callbacks_t user_cbs = {};
+    user_cbs.on_rx_done = test_filter_rx_done_cb;
+    TEST_ESP_OK(twai_node_register_event_callbacks(node_hdl, &user_cbs, test_ctrl));
+
+    twai_mask_filter_config_t mfilter_cfg = {};
+    mfilter_cfg.id = 0x10,
+    mfilter_cfg.mask = 0xf0,
+    mfilter_cfg.is_ext = false,
+    printf("Testing mask filter: id 0x%lx mask 0x%lx is_ext %d\n", mfilter_cfg.id, mfilter_cfg.mask, mfilter_cfg.is_ext);
+    TEST_ESP_OK(twai_node_config_mask_filter(node_hdl, 0, &mfilter_cfg));
+
+    printf("Go to sleep ...\n");
+    TEST_ESP_OK(esp_light_sleep_start());
+    printf("Waked up! sleep %d power down %ld\n", !sleep_ctx.sleep_request_result, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+#if SOC_TWAI_SUPPORT_SLEEP_RETENTION && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
+    TEST_ASSERT_EQUAL(PMU_SLEEP_PD_TOP, sleep_ctx.sleep_flags & PMU_SLEEP_PD_TOP);
+#endif
+    TEST_ESP_OK(twai_node_enable(node_hdl));
+    test_random_trans_generator(node_hdl, 30);
+    TEST_ASSERT_EQUAL(7, test_ctrl[1]);     // must receive 7 of 30 frames under filter config
+
+    TEST_ESP_OK(twai_node_disable(node_hdl));
+    TEST_ESP_OK(twai_node_delete(node_hdl));
+    esp_sleep_set_sleep_context(NULL);
+#if CONFIG_PM_ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(false));
+#endif
+}
+#endif  //SOC_TWAI_SUPPORT_SLEEP_RETENTION

components/esp_driver_twai/test_apps/test_twai/pytest_driver_twai.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 
 import subprocess
@@ -17,11 +17,21 @@ from pytest_embedded_idf.utils import soc_filtered_targets
 # ---------------------------------------------------------------------------
 @pytest.mark.generic
 @pytest.mark.parametrize('config', ['release', 'cache_safe'], indirect=True)
-@idf_parametrize('target', soc_filtered_targets('SOC_TWAI_SUPPORTED == 1'), indirect=['target'])
+@idf_parametrize(
+    'target', soc_filtered_targets('SOC_TWAI_SUPPORTED == 1 and IDF_TARGET not in ["esp32c5"]'), indirect=['target']
+)
 def test_driver_twai_loopbk(dut: Dut) -> None:
     dut.run_all_single_board_cases(group='twai', reset=True)
 
 
+@pytest.mark.generic
+@pytest.mark.esp32c5_eco3
+@pytest.mark.parametrize('config', ['release', 'cache_safe'], indirect=True)
+@idf_parametrize('target', ['esp32c5'], indirect=['target'])
+def test_driver_twai_loopbk_c5eco3(dut: Dut) -> None:
+    dut.run_all_single_board_cases(group='twai', reset=True)
+
+
 # ---------------------------------------------------------------------------
 # Helper Functions
 # ---------------------------------------------------------------------------

components/esp_driver_twai/test_apps/test_twai/sdkconfig.defaults

@@ -1,2 +1,4 @@
 CONFIG_FREERTOS_HZ=1000
 CONFIG_ESP_TASK_WDT_INIT=n
+# primitives for checking sleep internal state
+CONFIG_ESP_SLEEP_DEBUG=y