feat(jpeg): support jpeg sleep retention on esp32p4

components/esp_driver_jpeg/include/driver/jpeg_decode.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -29,7 +29,12 @@ typedef struct {
  */
 typedef struct {
     int intr_priority;                    /*!< JPEG interrupt priority, if set to 0, driver will select the default priority (1,2,3). */
-    int timeout_ms;                  /*!< JPEG timeout threshold for handling a picture, should larger than valid decode time in ms. For example, for 30fps decode, this value must larger than 34. -1 means wait forever */
+    int timeout_ms;                       /*!< JPEG timeout threshold for handling a picture, should larger than valid decode time in ms. For example, for 30fps decode, this value must larger than 34. -1 means wait forever */
+    struct {
+        uint32_t allow_pd:               1;   /*!< If set, the driver will backup/restore the JPEG registers before/after entering/exist sleep mode.
+                                                   By this approach, the system can power off JPEG's power domain.
+                                                   This can save power, but at the expense of more RAM being consumed */
+    } flags;                              /*!< JPEG engine configuration flags */
 } jpeg_decode_engine_cfg_t;
 
 /**

components/esp_driver_jpeg/include/driver/jpeg_encode.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -32,6 +32,11 @@ typedef struct {
 typedef struct {
     int intr_priority;                    /*!< JPEG interrupt priority, if set to 0, driver will select the default priority (1,2,3). */
     int timeout_ms;                       /*!< JPEG timeout threshold for handling a picture, should larger than valid encode time in ms. For example, for 30fps encode, this value must larger than 34. -1 means wait forever */
+    struct {
+        uint32_t allow_pd:               1;   /*!< If set, the driver will backup/restore the JPEG registers before/after entering/exist sleep mode.
+                                                   By this approach, the system can power off JPEG's power domain.
+                                                   This can save power, but at the expense of more RAM being consumed */
+    } flags;                              /*!< JPEG engine configuration flags */
 } jpeg_encode_engine_cfg_t;
 
 /**

components/esp_driver_jpeg/jpeg_common.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -22,6 +22,10 @@
 #endif
 #include "esp_log.h"
 #include "esp_check.h"
+#include "hal/jpeg_periph.h"
+#if JPEG_USE_RETENTION_LINK
+#include "esp_private/sleep_retention.h"
+#endif
 
 static const char *TAG = "jpeg.common";
 
@@ -33,6 +37,30 @@ typedef struct jpeg_platform_t {
 
 static jpeg_platform_t s_jpeg_platform = {};  // singleton platform
 
+#if JPEG_USE_RETENTION_LINK
+static esp_err_t s_jpeg_sleep_retention_init_cb(void *arg)
+{
+    esp_err_t ret = sleep_retention_entries_create(jpeg_regs_retention.link_list, jpeg_regs_retention.link_num, REGDMA_LINK_PRI_JPEG, jpeg_regs_retention.module_id);
+    ESP_RETURN_ON_ERROR(ret, TAG, "failed to allocate mem for sleep retention");
+    return ret;
+}
+
+void jpeg_create_retention_module(jpeg_codec_handle_t jpeg_codec)
+{
+    _lock_acquire(&s_jpeg_platform.mutex);
+    if (jpeg_codec->retention_link_created == false) {
+        if (sleep_retention_module_allocate(jpeg_regs_retention.module_id) != ESP_OK) {
+            // even though the sleep retention module create failed, JPEG driver should still work, so just warning here
+            ESP_LOGW(TAG, "create retention module failed, power domain can't turn off");
+        } else {
+            jpeg_codec->retention_link_created = true;
+        }
+    }
+    _lock_release(&s_jpeg_platform.mutex);
+
+}
+#endif
+
 esp_err_t jpeg_acquire_codec_handle(jpeg_codec_handle_t *jpeg_new_codec)
 {
 #if CONFIG_JPEG_ENABLE_DEBUG_LOG
@@ -53,6 +81,22 @@ esp_err_t jpeg_acquire_codec_handle(jpeg_codec_handle_t *jpeg_new_codec)
             ESP_RETURN_ON_FALSE(codec->codec_mutex, ESP_ERR_NO_MEM, TAG, "No memory for codec mutex");
             SLIST_INIT(&codec->jpeg_isr_handler_list);
             xSemaphoreGive(codec->codec_mutex);
+
+#if JPEG_USE_RETENTION_LINK
+            sleep_retention_module_init_param_t init_param = {
+                .cbs = {
+                    .create = {
+                        .handle = s_jpeg_sleep_retention_init_cb,
+                        .arg = (void *)codec
+                    },
+                },
+                .depends = RETENTION_MODULE_BITMAP_INIT(CLOCK_SYSTEM)
+            };
+            esp_err_t err = sleep_retention_module_init(jpeg_regs_retention.module_id, &init_param);
+            if (err != ESP_OK) {
+                ESP_LOGW(TAG, "init sleep retention failed on jpeg, jpeg configuration maybe lost after sleep wakeup");
+            }
+#endif
             // init the clock
             PERIPH_RCC_ATOMIC() {
                 jpeg_ll_enable_bus_clock(true);
@@ -100,6 +144,14 @@ esp_err_t jpeg_release_codec_handle(jpeg_codec_handle_t jpeg_codec)
                 esp_pm_lock_delete(jpeg_codec->pm_lock);
             }
 #endif
+
+#if JPEG_USE_RETENTION_LINK
+            if (jpeg_codec->retention_link_created) {
+                sleep_retention_module_free(jpeg_regs_retention.module_id);
+            }
+            sleep_retention_module_deinit(jpeg_regs_retention.module_id);
+#endif
+
             PERIPH_RCC_ATOMIC() {
                 jpeg_ll_enable_bus_clock(false);
             }

components/esp_driver_jpeg/jpeg_decode.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -120,6 +120,11 @@ esp_err_t jpeg_new_decoder_engine(const jpeg_decode_engine_cfg_t *dec_eng_cfg, j
 
     decoder_engine->trans_desc = (dma2d_trans_t *)heap_caps_calloc(1, SIZEOF_DMA2D_TRANS_T, JPEG_MEM_ALLOC_CAPS);
     ESP_GOTO_ON_FALSE(decoder_engine->trans_desc, ESP_ERR_NO_MEM, err, TAG, "No memory for dma2d descriptor");
+#if JPEG_USE_RETENTION_LINK
+    if (dec_eng_cfg->flags.allow_pd != 0) {
+        jpeg_create_retention_module(decoder_engine->codec_base);
+    }
+#endif // JPEG_USE_RETENTION_LINK
 
     *ret_decoder = decoder_engine;
     return ESP_OK;

components/esp_driver_jpeg/jpeg_encode.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -126,6 +126,12 @@ esp_err_t jpeg_new_encoder_engine(const jpeg_encode_engine_cfg_t *enc_eng_cfg, j
     encoder_engine->header_info = (jpeg_enc_header_info_t*)heap_caps_calloc(1, sizeof(jpeg_enc_header_info_t), JPEG_MEM_ALLOC_CAPS);
     ESP_GOTO_ON_FALSE(encoder_engine->header_info, ESP_ERR_NO_MEM, err, TAG, "no memory for jpeg header information structure");
 
+#if JPEG_USE_RETENTION_LINK
+    if (enc_eng_cfg->flags.allow_pd != 0) {
+        jpeg_create_retention_module(encoder_engine->codec_base);
+    }
+#endif // JPEG_USE_RETENTION_LINK
+
     *ret_encoder = encoder_engine;
     return ESP_OK;
 err:

components/esp_driver_jpeg/jpeg_private.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -32,6 +32,9 @@ extern "C" {
 
 #define JPEG_ALIGN_UP(num, align)         (((num) + ((align) - 1)) & ~((align) - 1))
 
+// Use retention link only when the target supports sleep retention and PM is enabled
+#define JPEG_USE_RETENTION_LINK  (CONFIG_PM_ENABLE && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP)
+
 typedef struct jpeg_decoder_t jpeg_decoder_t;
 typedef struct jpeg_encoder_t jpeg_encoder_t;
 typedef struct jpeg_codec_t jpeg_codec_t;
@@ -55,6 +58,7 @@ struct jpeg_codec_t {
 #if CONFIG_PM_ENABLE
     esp_pm_lock_handle_t pm_lock; // power manage lock
 #endif
+    bool retention_link_created;     // mark if the retention link is created.
 };
 
 typedef enum {
@@ -246,6 +250,13 @@ esp_err_t jpeg_isr_deregister(jpeg_codec_handle_t jpeg_codec, jpeg_isr_handler_t
  */
 esp_err_t jpeg_check_intr_priority(jpeg_codec_handle_t jpeg_codec, int intr_priority);
 
+/**
+ * @brief Create sleep retention link
+ *
+ * @param jpeg_codec JPEG handle
+ */
+void jpeg_create_retention_module(jpeg_codec_handle_t jpeg_codec);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_driver_jpeg/test_apps/jpeg_test_apps/main/CMakeLists.txt

@@ -5,6 +5,9 @@ if(CONFIG_SOC_JPEG_DECODE_SUPPORTED)
     list(APPEND srcs
                     "test_jpeg_decode.c"
     )
+    if(CONFIG_PM_ENABLE)
+        list(APPEND srcs "test_jpeg_sleep_retention.c")
+    endif()
 endif()
 
 if(CONFIG_SOC_JPEG_ENCODE_SUPPORTED)
@@ -14,5 +17,5 @@ if(CONFIG_SOC_JPEG_ENCODE_SUPPORTED)
 endif()
 
 idf_component_register(SRCS ${srcs}
-                       PRIV_REQUIRES esp_driver_jpeg unity esp_psram test_utils
+                       PRIV_REQUIRES esp_driver_jpeg unity esp_psram test_utils esp_pm
                        WHOLE_ARCHIVE)

components/esp_driver_jpeg/test_apps/jpeg_test_apps/main/test_app_main.c

@@ -11,7 +11,7 @@
 
 // Some resources are lazy allocated in JPEG driver, so we reserved this threshold when checking memory leak
 // A better way to check a potential memory leak is running a same case by twice, for the second time, the memory usage delta should be zero
-#define LEAKS (400)
+#define LEAKS (500)
 
 void setUp(void)
 {

components/esp_driver_jpeg/test_apps/jpeg_test_apps/main/test_jpeg_sleep_retention.c

@@ -0,0 +1,99 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include "sdkconfig.h"
+#include "unity.h"
+#include "test_utils.h"
+#include "esp_err.h"
+#include "freertos/FreeRTOS.h"
+#include "esp_private/periph_ctrl.h"
+#include "driver/jpeg_decode.h"
+#include "esp_log.h"
+#include "test_jpeg_performance.h"
+#include "esp_system.h"
+#include "ccomp_timer.h"
+#include "esp_sleep.h"
+#include "esp_private/sleep_cpu.h"
+#include "esp_pm.h"
+#include "esp_private/esp_sleep_internal.h"
+#include "esp_private/esp_pmu.h"
+
+extern const uint8_t image_esp1080_jpg_start[] asm("_binary_esp1080_jpg_start");
+extern const uint8_t image_esp1080_jpg_end[]   asm("_binary_esp1080_jpg_end");
+
+#if SOC_LIGHT_SLEEP_SUPPORTED && CONFIG_PM_ENABLE
+static void test_jpeg_sleep_retention(bool allow_pd)
+{
+    jpeg_decoder_handle_t jpgd_handle;
+
+    jpeg_decode_engine_cfg_t decode_eng_cfg = {
+        .intr_priority = 0,
+        .timeout_ms = 40,
+        .flags = {
+            .allow_pd = allow_pd,
+        },
+    };
+
+    jpeg_decode_cfg_t decode_cfg = {
+        .output_format = JPEG_DECODE_OUT_FORMAT_RGB565,
+    };
+
+    jpeg_decode_memory_alloc_cfg_t rx_mem_cfg = {
+        .buffer_direction = JPEG_DEC_ALLOC_OUTPUT_BUFFER,
+    };
+
+    jpeg_decode_memory_alloc_cfg_t tx_mem_cfg = {
+        .buffer_direction = JPEG_DEC_ALLOC_INPUT_BUFFER,
+    };
+
+    size_t rx_buffer_size;
+    uint8_t *rx_buf_1080p = (uint8_t*)jpeg_alloc_decoder_mem(1080 * 1920 * 3, &rx_mem_cfg, &rx_buffer_size);
+    uint32_t out_size_1080p = 0;
+
+    size_t bit_stream_length = (size_t)image_esp1080_jpg_end - (size_t)image_esp1080_jpg_start;
+
+    size_t tx_buffer_size;
+    uint8_t *tx_buf_1080p = (uint8_t*)jpeg_alloc_decoder_mem(bit_stream_length, &tx_mem_cfg, &tx_buffer_size);
+    // Copy bit stream to psram
+    memcpy(tx_buf_1080p, image_esp1080_jpg_start, bit_stream_length);
+    TEST_ESP_OK(jpeg_new_decoder_engine(&decode_eng_cfg, &jpgd_handle));
+
+    TEST_ESP_OK(jpeg_decoder_process(jpgd_handle, &decode_cfg, tx_buf_1080p, bit_stream_length, rx_buf_1080p, rx_buffer_size, &out_size_1080p));
+
+    esp_sleep_context_t sleep_ctx;
+    esp_sleep_set_sleep_context(&sleep_ctx);
+
+#if CONFIG_PM_ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(true));
+#endif
+
+    TEST_ESP_OK(esp_sleep_enable_timer_wakeup(2 * 1000 * 1000));
+    TEST_ESP_OK(esp_light_sleep_start());
+#if CONFIG_PM_ESP_SLEEP_POWER_DOWN_CPU
+    TEST_ESP_OK(sleep_cpu_configure(false));
+#endif
+    printf("check if the sleep happened as expected\r\n");
+    TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
+
+    // check if the power domain also is powered down
+    TEST_ASSERT_EQUAL(allow_pd ? PMU_SLEEP_PD_TOP : 0, (sleep_ctx.sleep_flags) & PMU_SLEEP_PD_TOP);
+
+    TEST_ESP_OK(jpeg_decoder_process(jpgd_handle, &decode_cfg, tx_buf_1080p, bit_stream_length, rx_buf_1080p, rx_buffer_size, &out_size_1080p));
+
+    free(rx_buf_1080p);
+    free(tx_buf_1080p);
+    esp_sleep_set_sleep_context(NULL);
+    TEST_ESP_OK(jpeg_del_decoder_engine(jpgd_handle));
+}
+
+TEST_CASE("jpeg sleep retention test", "[jpeg]")
+{
+    test_jpeg_sleep_retention(false);
+    test_jpeg_sleep_retention(true);
+}
+#endif

components/esp_driver_jpeg/test_apps/jpeg_test_apps/sdkconfig.ci.release

@@ -1,5 +1,6 @@
 CONFIG_PM_ENABLE=y
 CONFIG_FREERTOS_USE_TICKLESS_IDLE=y
+CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP=y
 CONFIG_PM_DFS_INIT_AUTO=y
 CONFIG_COMPILER_OPTIMIZATION_SIZE=y
 CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_SIZE=y

components/esp_driver_jpeg/test_apps/jpeg_test_apps/sdkconfig.defaults

@@ -1,5 +1,5 @@
 CONFIG_FREERTOS_HZ=1000
-CONFIG_ESP_TASK_WDT=n
+CONFIG_ESP_TASK_WDT_EN=n
 
 # SPIRAM configurations
 
@@ -13,3 +13,6 @@ CONFIG_IDF_EXPERIMENTAL_FEATURES=y
 CONFIG_PARTITION_TABLE_CUSTOM=y
 CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
 CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+
+# primitives for checking sleep internal state
+CONFIG_ESP_SLEEP_DEBUG=y

components/esp_hal_jpeg/CMakeLists.txt

@@ -14,7 +14,7 @@ set(srcs)
 
 # JPEG related source files
 if(CONFIG_SOC_JPEG_CODEC_SUPPORTED)
-    list(APPEND srcs "jpeg_hal.c")
+    list(APPEND srcs "jpeg_hal.c" "${target}/jpeg_periph.c")
 endif()
 
 idf_component_register(SRCS ${srcs}

components/esp_hal_jpeg/esp32p4/jpeg_periph.c

@@ -0,0 +1,28 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "hal/jpeg_periph.h"
+
+// JPEG_CONFIG_REG JPEG_INT_ENA_REG
+#define JPEG_RETENTION_REGS_CNT 2
+#define JPEG_RETENTION_REGS_BASE (DR_REG_JPEG_BASE + 0x0)
+static const uint32_t jpeg_regs_map[4] = {0x8001, 0x0, 0x0, 0x0};
+static const regdma_entries_config_t jpeg_regdma_entries[] = {
+    [0] = {
+        .config = REGDMA_LINK_ADDR_MAP_INIT(REGDMA_JPEG_LINK(0x00),
+                                            JPEG_RETENTION_REGS_BASE, JPEG_RETENTION_REGS_BASE,
+                                            JPEG_RETENTION_REGS_CNT, 0, 0,
+                                            jpeg_regs_map[0], jpeg_regs_map[1],
+                                            jpeg_regs_map[2], jpeg_regs_map[3]),
+        .owner = ENTRY(0) | ENTRY(2),
+    },
+};
+
+const jpeg_reg_ctx_link_t jpeg_regs_retention = {
+    .link_list = jpeg_regdma_entries,
+    .link_num = ARRAY_SIZE(jpeg_regdma_entries),
+    .module_id = SLEEP_RETENTION_MODULE_JPEG,
+};

components/esp_hal_jpeg/include/hal/jpeg_periph.h

@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#if SOC_JPEG_CODEC_SUPPORTED
+#include "soc/regdma.h"
+#include "soc/interrupts.h"
+#include "soc/retention_periph_defs.h"
+#include "soc/jpeg_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    const regdma_entries_config_t *link_list;
+    uint32_t link_num;
+    periph_retention_module_t module_id;
+} jpeg_reg_ctx_link_t;
+
+extern const jpeg_reg_ctx_link_t jpeg_regs_retention;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // SOC_JPEG_CODEC_SUPPORTED

components/esp_hw_support/port/esp32p4/peripheral_domain_pd.c

@@ -96,6 +96,9 @@ bool peripheral_domain_pd_allowed(void)
     // ESP32P4 supports EMAC sleep retention
     RETENTION_MODULE_BITMAP_SET(&mask, SLEEP_RETENTION_MODULE_EMAC);
 
+    // ESP32P4 supports JPEG sleep retention
+    RETENTION_MODULE_BITMAP_SET(&mask, SLEEP_RETENTION_MODULE_JPEG);
+
     const sleep_retention_module_bitmap_t peripheral_domain_inited_modules = sleep_retention_module_bitmap_and(inited_modules, mask);
     const sleep_retention_module_bitmap_t peripheral_domain_created_modules = sleep_retention_module_bitmap_and(created_modules, mask);
     return sleep_retention_module_bitmap_eq(peripheral_domain_inited_modules, peripheral_domain_created_modules);

components/soc/esp32p4/include/soc/retention_periph_defs.h

@@ -61,6 +61,7 @@ typedef enum periph_retention_module {
     SLEEP_RETENTION_MODULE_MCPWM1       = 35,
     SLEEP_RETENTION_MODULE_SDM0         = 36,
     SLEEP_RETENTION_MODULE_EMAC         = 37,
+    SLEEP_RETENTION_MODULE_JPEG         = 38,
 
     SLEEP_RETENTION_MODULE_MAX          = SOC_PM_RETENTION_MODULE_NUM - 1
 } periph_retention_module_t;
@@ -103,6 +104,7 @@ typedef enum periph_retention_module {
     : ((m) == SLEEP_RETENTION_MODULE_MCPWM0)       ? true \
     : ((m) == SLEEP_RETENTION_MODULE_MCPWM1)       ? true \
     : ((m) == SLEEP_RETENTION_MODULE_SDM0)         ? true \
+    : ((m) == SLEEP_RETENTION_MODULE_JPEG)         ? true \
     : false)
 
 #ifdef __cplusplus

components/soc/include/soc/regdma.h

@@ -66,6 +66,7 @@ extern "C" {
 #define REGDMA_MCPWM_LINK(_pri)             ((0x25 << 8) | _pri)
 #define REGDMA_SDM_LINK(_pri)               ((0x26 << 8) | _pri)
 #define REGDMA_EMAC_LINK(_pri)              ((0x27 << 8) | _pri)
+#define REGDMA_JPEG_LINK(_pri)              ((0x28 << 8) | _pri)
 
 #define REGDMA_MODEM_FE_LINK(_pri)          ((0xFF << 8) | _pri)
 
@@ -94,6 +95,7 @@ extern "C" {
 #define REGDMA_LINK_PRI_MCPWM                   REGDMA_LINK_PRI_GENERAL_PERIPH
 #define REGDMA_LINK_PRI_SDM                     REGDMA_LINK_PRI_GENERAL_PERIPH
 #define REGDMA_LINK_PRI_EMAC                    REGDMA_LINK_PRI_GENERAL_PERIPH
+#define REGDMA_LINK_PRI_JPEG                    REGDMA_LINK_PRI_GENERAL_PERIPH
 
 typedef enum {
     REGDMA_LINK_PRI_0 = 0,