From 231dc0e8845e680ab4ff636b51e6f7f8582fa97c Mon Sep 17 00:00:00 2001
From: Mahavir Jain <mahavir@espressif.com>
Date: Wed, 20 May 2026 10:28:06 +0530
Subject: [PATCH] feat(esp_psram): add esp_psram_ptr_is_no_enc() helper

Drivers that allocate from the unencrypted PSRAM carve-out via
MALLOC_CAP_SPIRAM_NO_ENC currently have no way to verify after the fact
which pool a buffer came from. This is particularly relevant for callers
using heap_caps_malloc_prefer(MALLOC_CAP_SPIRAM_NO_ENC, MALLOC_CAP_SPIRAM),
where a silent fallback to encrypted PSRAM would still pass the typical
esp_ptr_external_ram() check.

Expose esp_psram_ptr_is_no_enc() in the public esp_psram.h header. It
performs a range check against the carve-out's virtual-address window and
returns false when PSRAM is not initialized or CONFIG_SPIRAM_ENC_EXEMPT is
disabled, so callers do not need to guard the call site with #if.

Also reference the helper from the External RAM documentation alongside
the heap_caps_malloc(MALLOC_CAP_SPIRAM_NO_ENC) usage example.
---
 components/esp_psram/include/esp_psram.h      | 18 ++++++++++++++++++
 components/esp_psram/system_layer/esp_psram.c | 15 +++++++++++++++
 docs/en/api-guides/external-ram.rst           |  2 ++
 3 files changed, 35 insertions(+)

diff --git a/components/esp_psram/include/esp_psram.h b/components/esp_psram/include/esp_psram.h
index 27c7f7b4a55..562e851d1e9 100644
--- a/components/esp_psram/include/esp_psram.h
+++ b/components/esp_psram/include/esp_psram.h
@@ -42,6 +42,24 @@ bool esp_psram_is_initialized(void);
  */
 size_t esp_psram_get_size(void);
 
+/**
+ * @brief Check if the pointer falls inside the unencrypted PSRAM carve-out region
+ *
+ * When @c CONFIG_SPIRAM_ENC_EXEMPT is enabled, esp_psram reserves a region of PSRAM
+ * that is mapped without encryption and exposed through the @c MALLOC_CAP_SPIRAM_NO_ENC
+ * heap capability. This function lets drivers verify whether a buffer returned by the
+ * heap allocator actually lives in that unencrypted region — useful for example after
+ * a @c heap_caps_malloc_prefer() call that may have fallen back to encrypted PSRAM.
+ *
+ * @param[in] p  The pointer to check
+ *
+ * @return
+ *        - true:  the pointer is within the unencrypted PSRAM carve-out
+ *        - false: the pointer is not in the carve-out, PSRAM is not initialized,
+ *                 or @c CONFIG_SPIRAM_ENC_EXEMPT is disabled
+ */
+bool esp_psram_ptr_is_no_enc(const void *p);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/components/esp_psram/system_layer/esp_psram.c b/components/esp_psram/system_layer/esp_psram.c
index 86c7b4d56dc..c58ffe41219 100644
--- a/components/esp_psram/system_layer/esp_psram.c
+++ b/components/esp_psram/system_layer/esp_psram.c
@@ -628,6 +628,21 @@ bool IRAM_ATTR esp_psram_check_ptr_addr(const void *p)
     return false;
 }
 
+bool IRAM_ATTR esp_psram_ptr_is_no_enc(const void *p)
+{
+#if CONFIG_SPIRAM_ENC_EXEMPT
+    if (!s_psram_ctx.is_initialised) {
+        return false;
+    }
+
+    return ((intptr_t)p >= s_psram_ctx.mapped_regions[PSRAM_MEM_ENC_EXEMPT].vaddr_start &&
+            (intptr_t)p < s_psram_ctx.mapped_regions[PSRAM_MEM_ENC_EXEMPT].vaddr_end);
+#else
+    (void)p;
+    return false;
+#endif
+}
+
 esp_err_t esp_psram_extram_reserve_dma_pool(size_t size)
 {
     if (size == 0) {
diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst
index 55030aba2d0..f68ab4721f1 100644
--- a/docs/en/api-guides/external-ram.rst
+++ b/docs/en/api-guides/external-ram.rst
@@ -271,6 +271,8 @@ By default, failure to initialize external RAM will cause the ESP-IDF startup to
 
         ``MALLOC_CAP_SPIRAM_NO_ENC`` must be requested explicitly. It is intentionally not combined with ``MALLOC_CAP_SPIRAM`` or ``MALLOC_CAP_DEFAULT``, so ordinary SPIRAM/heap allocations cannot accidentally land in the unencrypted region.
 
+        To verify after the fact that a buffer was allocated from the unencrypted carve-out (for example after a ``heap_caps_malloc_prefer()`` call that may have fallen back to encrypted PSRAM), use :cpp:func:`esp_psram_ptr_is_no_enc`.
+
     .. only:: SOC_PSRAM_ENCRYPTION_SEPARATE_KEY
 
         On {IDF_TARGET_NAME}, PSRAM encryption can use an independent encryption key. If the PSRAM encryption key is not programmed, the flash encryption key will be used as the PSRAM encryption key.