feat(mmu): read flash through cache-mmu

Author: erhankur

CMakeLists.txt

@@ -18,6 +18,7 @@ endif()
 
 set(srcs
     src/cache.c
+    src/mmu.c
     src/flash.c
     src/mem_utils.c
     src/rom_wrappers.c

include/esp-stub-lib/mmu.h

@@ -0,0 +1,57 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#include <esp-stub-lib/bit_utils.h>
+
+#define STUB_MMU_PAGE_SIZE  0x10000U /* 64KB */
+#define STUB_MMU_PAGE_SHIFT 16
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+/**
+ * @brief Map a flash physical address range into the CPU virtual address space.
+ *
+ * Temporarily programs MMU entries so the CPU can read flash through cache.
+ * Only one mapping can be active at a time. The caller must call
+ * stub_lib_flash_munmap() before creating a new mapping.
+ *
+ * @param flash_paddr  Flash physical address (page-aligned internally).
+ * @param size         Number of bytes to map (rounded up to page boundary).
+ * @param[out] out_vaddr  On success, receives the virtual address corresponding
+ *                        to flash_paddr (including sub-page offset).
+ *
+ * @return 0 on success, or a negative error code.
+ */
+int stub_lib_flash_mmap(uint32_t flash_paddr, uint32_t size, const void **out_vaddr);
+
+/**
+ * @brief Unmap a previously mapped flash region and restore MMU state.
+ */
+void stub_lib_flash_munmap(void);
+
+/**
+ * @brief Read data from flash, automatically handling encrypted flash.
+ *
+ * When flash encryption is enabled, reads through the cache via MMU mapping
+ * to get decrypted data. Otherwise, reads directly via SPI.
+ *
+ * @param addr   Flash physical address.
+ * @param buffer Destination buffer.
+ * @param size   Number of bytes to read.
+ *
+ * @return 0 on success, or a negative error code.
+ */
+int stub_lib_flash_read(uint32_t addr, void *buffer, uint32_t size);
+
+#ifdef __cplusplus
+}
+#endif // __cplusplus

src/mmu.c

@@ -0,0 +1,132 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#include <stddef.h>
+#include <string.h>
+
+#include <esp-stub-lib/bit_utils.h>
+#include <esp-stub-lib/cache.h>
+#include <esp-stub-lib/flash.h>
+#include <esp-stub-lib/log.h>
+#include <esp-stub-lib/security.h>
+
+#include <target/mmu.h>
+
+#define STUB_MMAP_MAX_PAGES 8 // TODO: check if 8 pages is enough
+
+static struct {
+    uint32_t vaddr_base;
+    uint32_t entry_start;
+    uint32_t page_count;
+    uint32_t saved_entries[STUB_MMAP_MAX_PAGES];
+} s_mmap_state;
+
+int stub_lib_flash_mmap(uint32_t flash_paddr, uint32_t size, const void **out_vaddr)
+{
+    uint32_t aligned = ALIGN_DOWN(flash_paddr, STUB_MMU_PAGE_SIZE);
+    uint32_t offset = flash_paddr - aligned;
+    uint32_t map_size = size + offset;
+    uint32_t page_count = (map_size + STUB_MMU_PAGE_SIZE - 1) >> STUB_MMU_PAGE_SHIFT;
+
+    STUB_LOGD("aligned: %x, offset: %x, map_size: %x, page_count: %d\n", aligned, offset, map_size, page_count);
+
+    if (page_count == 0 || page_count > STUB_MMAP_MAX_PAGES) {
+        STUB_LOGE("invalid page_count: %d\n", page_count);
+        return -1;
+    }
+
+    uint32_t drom_start = stub_target_mmu_get_drom_entry_start();
+    uint32_t drom_end = stub_target_mmu_get_drom_entry_end();
+    uint32_t drom_count = drom_end - drom_start;
+    if (page_count > drom_count) {
+        STUB_LOGE("invalid page_count: %d, drom_count: %d\n", page_count, drom_count);
+        return -1;
+    }
+
+    /* Use the last N entries of the DROM region (least likely to conflict) */
+    uint32_t entry_start = drom_end - page_count;
+    uint32_t drom_vaddr = stub_target_mmu_get_drom_vaddr();
+    uint32_t vaddr_base = drom_vaddr + (entry_start - drom_start) * STUB_MMU_PAGE_SIZE;
+
+    STUB_LOGD("drom_start: %d, drom_end: %d, entry_start: %d, vaddr_base: %x\n",
+              drom_start,
+              drom_end,
+              entry_start,
+              vaddr_base);
+
+    uint32_t autoload = stub_lib_cache_suspend();
+
+    /* Save existing MMU entries */
+    for (uint32_t i = 0; i < page_count; i++)
+        s_mmap_state.saved_entries[i] = stub_target_mmu_read_entry(entry_start + i);
+
+    /* Write new flash mappings */
+    uint32_t flash_page = aligned >> STUB_MMU_PAGE_SHIFT;
+    for (uint32_t i = 0; i < page_count; i++)
+        stub_target_mmu_write_entry(entry_start + i, flash_page + i);
+
+    s_mmap_state.vaddr_base = vaddr_base;
+    s_mmap_state.entry_start = entry_start;
+    s_mmap_state.page_count = page_count;
+
+    stub_lib_cache_resume(autoload);
+
+    /* Invalidate cache for the mapped region */
+    uint32_t caps = stub_lib_cache_get_caps();
+    if (caps & STUB_CACHE_CAP_HAS_INVALIDATE_ADDR)
+        stub_lib_cache_invalidate_addr(vaddr_base, page_count * STUB_MMU_PAGE_SIZE);
+    else
+        stub_lib_cache_invalidate_all();
+
+    *out_vaddr = (const void *)(vaddr_base + offset);
+
+    STUB_LOGD("mmap: 0x%x is mapped to 0x%x\n", flash_paddr, *out_vaddr);
+
+    return 0;
+}
+
+void stub_lib_flash_munmap(void)
+{
+    if (s_mmap_state.page_count == 0)
+        return;
+
+    uint32_t autoload = stub_lib_cache_suspend();
+
+    /* Restore saved MMU entries */
+    for (uint32_t i = 0; i < s_mmap_state.page_count; i++)
+        stub_target_mmu_restore_entry(s_mmap_state.entry_start + i, s_mmap_state.saved_entries[i]);
+
+    stub_lib_cache_resume(autoload);
+
+    /* Invalidate stale cache lines */
+    uint32_t caps = stub_lib_cache_get_caps();
+    if (caps & STUB_CACHE_CAP_HAS_INVALIDATE_ADDR)
+        stub_lib_cache_invalidate_addr(s_mmap_state.vaddr_base, s_mmap_state.page_count * STUB_MMU_PAGE_SIZE);
+    else
+        stub_lib_cache_invalidate_all();
+
+    s_mmap_state.page_count = 0;
+}
+
+int stub_lib_flash_read(uint32_t addr, void *buffer, uint32_t size)
+{
+    // if (!stub_lib_security_flash_is_encrypted())
+    if (0)
+        return stub_lib_flash_read_buff(addr, buffer, size);
+
+    /* Encrypted flash: read through cache via MMU mapping */
+    const void *vaddr;
+    int rc = stub_lib_flash_mmap(addr, size, &vaddr);
+    if (rc != 0) {
+        STUB_LOGE("mmap failed (%d) @ %x\n", rc, addr);
+        return rc;
+    }
+
+    memcpy(buffer, vaddr, size);
+    stub_lib_flash_munmap();
+
+    return 0;
+}

src/target/base/include/target/mmu.h

@@ -0,0 +1,71 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#include <esp-stub-lib/mmu.h>
+
+/**
+ * @brief Get the DROM virtual address base for mmap operations.
+ *
+ * @return Start of the DROM virtual address region (e.g. SOC_DROM_LOW).
+ */
+uint32_t stub_target_mmu_get_drom_vaddr(void);
+
+/**
+ * @brief Get the first MMU entry index in the DROM region.
+ *
+ * On chips with partitioned MMU tables (e.g. ESP32 where entries 0–63 are
+ * DROM, 64–127 are IRAM0, etc.), this returns the first DROM entry index.
+ * On chips with unified IROM/DROM tables, this typically returns 0.
+ *
+ * @return First DROM entry index (e.g. SOC_MMU_DROM0_PAGES_START).
+ */
+uint32_t stub_target_mmu_get_drom_entry_start(void);
+
+/**
+ * @brief Get the one-past-last MMU entry index in the DROM region.
+ *
+ * @return One past the last DROM entry index (e.g. SOC_MMU_DROM0_PAGES_END).
+ */
+uint32_t stub_target_mmu_get_drom_entry_end(void);
+
+/**
+ * @brief Write a single MMU entry mapping a flash page.
+ *
+ * The implementation must add the chip-specific valid bit(s).
+ *
+ * @param entry_id        MMU entry index.
+ * @param flash_page_num  Flash page number (paddr >> STUB_MMU_PAGE_SHIFT).
+ */
+void stub_target_mmu_write_entry(uint32_t entry_id, uint32_t flash_page_num);
+
+/**
+ * @brief Read a single MMU entry (raw value for save/restore).
+ *
+ * @param entry_id  MMU entry index.
+ * @return Raw MMU entry value.
+ */
+uint32_t stub_target_mmu_read_entry(uint32_t entry_id);
+
+/**
+ * @brief Set a single MMU entry to invalid.
+ *
+ * @param entry_id  MMU entry index.
+ */
+void stub_target_mmu_set_entry_invalid(uint32_t entry_id);
+
+/**
+ * @brief Restore a single MMU entry from a previously saved raw value.
+ *
+ * Unlike write_entry, this writes the raw value as-is (no valid bit added).
+ *
+ * @param entry_id   MMU entry index.
+ * @param raw_value  Raw value previously returned by stub_target_mmu_read_entry().
+ */
+void stub_target_mmu_restore_entry(uint32_t entry_id, uint32_t raw_value);

src/target/common/CMakeLists.txt

@@ -1,6 +1,7 @@
 set(common_srcs
     src/aes_xts.c
     src/cache.c
+    src/mmu.c
     src/flash.c
     src/flash_4byte.c
     src/mem_utils.c

src/target/common/src/mmu.c

@@ -0,0 +1,47 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR MIT
+ */
+
+#include <stdint.h>
+
+#include <target/mmu.h>
+
+uint32_t __attribute__((weak)) stub_target_mmu_get_drom_vaddr(void)
+{
+    return 0;
+}
+
+uint32_t __attribute__((weak)) stub_target_mmu_get_drom_entry_start(void)
+{
+    return 0;
+}
+
+uint32_t __attribute__((weak)) stub_target_mmu_get_drom_entry_end(void)
+{
+    return 0;
+}
+
+void __attribute__((weak)) stub_target_mmu_write_entry(uint32_t entry_id, uint32_t flash_page_num)
+{
+    (void)entry_id;
+    (void)flash_page_num;
+}
+
+uint32_t __attribute__((weak)) stub_target_mmu_read_entry(uint32_t entry_id)
+{
+    (void)entry_id;
+    return 0;
+}
+
+void __attribute__((weak)) stub_target_mmu_set_entry_invalid(uint32_t entry_id)
+{
+    (void)entry_id;
+}
+
+void __attribute__((weak)) stub_target_mmu_restore_entry(uint32_t entry_id, uint32_t raw_value)
+{
+    (void)entry_id;
+    (void)raw_value;
+}

src/target/esp32/CMakeLists.txt

@@ -1,5 +1,6 @@
 set(srcs
     src/cache.c
+    src/mmu.c
     src/flash.c
     src/sha256.c
     src/trax.c

src/target/esp32/include/soc/dport_reg.h

@@ -25,3 +25,7 @@
 
 /* CTRL1 bus mask: bits [5:0] — each bit disables one bus when set */
 #define DPORT_CACHE_BUS_MASK        0x3fU
+#define DPORT_PRO_CACHE_MASK_DROM0  BIT(4)
+
+/* PRO CPU flash MMU table (memory-mapped, 384 entries) */
+#define DPORT_PRO_FLASH_MMU_TABLE   ((volatile uint32_t *)0x3FF10000)

src/target/esp32/include/soc/ext_mem_defs.h

@@ -8,5 +8,8 @@
 
 #include <esp-stub-lib/bit_utils.h>
 
-#define SOC_MMU_ENTRY_NUM  384
-#define SOC_MMU_INVALID    BIT(8)
+#define SOC_MMU_ENTRY_NUM           384
+#define SOC_MMU_INVALID             BIT(8)
+
+#define SOC_MMU_DROM0_PAGES_START   0
+#define SOC_MMU_DROM0_PAGES_END     64