change(flash): deprecate bootloader_flash_priv.h

components/bootloader_support/bootloader_flash/include/bootloader_flash_override.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -16,6 +16,26 @@ extern "C" {
 typedef unsigned (*bootloader_flash_read_status_fn_t)(void);
 typedef void (*bootloader_flash_write_status_fn_t)(unsigned);
 
+/**
+ * @brief Execute a user command on the flash
+ *
+ * @param command The command value to execute.
+ * @param mosi_data MOSI data to send
+ * @param mosi_len Length of MOSI data, in bits
+ * @param miso_len Length of MISO data to receive, in bits
+ * @return Received MISO data
+ */
+uint32_t bootloader_execute_flash_command(uint8_t command, uint32_t mosi_data, uint8_t mosi_len, uint8_t miso_len);
+
+/**
+ * @brief Read the SFDP of the flash
+ *
+ * @param sfdp_addr Address of the parameter to read
+ * @param miso_byte_num Bytes to read
+ * @return The read SFDP, little endian, 4 bytes at most
+ */
+uint32_t bootloader_flash_read_sfdp(uint32_t sfdp_addr, unsigned int miso_byte_num);
+
 typedef struct __attribute__((packed))
 {
     const char *manufacturer;

components/bootloader_support/bootloader_flash/include/esp_private/bootloader_flash_internal.h

@@ -1,17 +1,161 @@
 /*
- * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
+
 #include <stdint.h>
-#include <esp_err.h>
+#include <stddef.h>
+#include <stdbool.h>
+#include "esp_err.h"
+#include "sdkconfig.h"
+#include "bootloader_flash.h"
+#include "bootloader_flash_override.h"
 #include "soc/soc_caps.h"
+#include "soc/ext_mem_defs.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+//-------------------------------- Utilities -------------------------------- //
+/**
+ * This file provides a Flash API for bootloader_support code,
+ * that can be used from bootloader or app code.
+ * This header is available to source code in the ESP-IDF components only.
+ */
+
+#define FLASH_SECTOR_SIZE 0x1000
+#define FLASH_BLOCK_SIZE 	0x10000
+
+#define MMAP_ALIGNED_MASK 	(CONFIG_MMU_PAGE_SIZE - 1)
+#define MMU_FLASH_MASK    (~(CONFIG_MMU_PAGE_SIZE - 1))
+#define MMU_FLASH_MASK_FROM_VAL(PAGE_SZ) (~((PAGE_SZ) - 1))
+#define MMU_DROM_END_ENTRY_VADDR_FROM_VAL(PAGE_SZ) (SOC_DRAM_FLASH_ADDRESS_HIGH - (PAGE_SZ))
+
+/**
+ * MMU mapping must always be in the unit of a CONFIG_MMU_PAGE_SIZE
+ * This macro is a helper for you to get needed page nums to be mapped. e.g.:
+ * Let's say CONFIG_MMU_PAGE_SIZE is 64KB.
+ * - v_start = 0x4200_0004
+ * - size = 4 * 64KB
+ *
+ * You should map from 0x4200_0000, then map 5 pages.
+ */
+#define GET_REQUIRED_MMU_PAGES(size, v_start)    ((size + (v_start - (v_start & MMU_FLASH_MASK)) + CONFIG_MMU_PAGE_SIZE - 1) / CONFIG_MMU_PAGE_SIZE)
+
+/**
+ * @brief Get number of free pages
+ *
+ * @return Number of free pages
+ */
+uint32_t bootloader_mmap_get_free_pages(void);
+
+/**
+ * @brief Map a region of flash to data memory
+ *
+ * @important In bootloader code, only one region can be bootloader_mmaped at once. The previous region must be bootloader_munmapped before another region is mapped.
+ *
+ * @important In app code, these functions are not thread safe.
+ *
+ * Call bootloader_munmap once for each successful call to bootloader_mmap.
+ *
+ * In esp-idf app, this function maps directly to spi_flash_mmap with the @ref
+ * spi_flash_mmap_flag_t::SPI_FLASH_MMAP_FLAG_BLOCKS_WRITE flag set. When XIP on PSRAM (`CONFIG_SPIRAM_XIP_FROM_PSRAM`)  enabled, flash erasing/writing
+ * will be blocked until unmap.
+ *
+ * @param offset - Starting flash offset to map to memory.
+ * @param length - Length of data to map.
+ *
+ * @return Pointer to mapped data memory (at src_addr), or NULL
+ * if an allocation error occurred.
+ */
+const void *bootloader_mmap(uint32_t src_addr, uint32_t size);
+
+
+/**
+ * @brief Unmap a previously mapped region of flash
+ *
+ * Call bootloader_munmap once for each successful call to bootloader_mmap.
+ */
+void bootloader_munmap(const void *mapping);
+
+/**
+ * @brief  Read data from Flash.
+ *
+ *
+ * @note All of src, dest and size have to be 4-byte aligned.
+ *
+ * @param  src   source address of the data in Flash.
+ * @param  dest  pointer to the destination buffer
+ * @param  size  length of data
+ * @param  allow_decrypt If true and flash encryption is enabled, data on flash
+ *         will be decrypted transparently as part of the read.
+ *
+ * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
+ * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
+ */
+esp_err_t bootloader_flash_read(size_t src_addr, void *dest, size_t size, bool allow_decrypt);
+
+
+/**
+ * @brief  Write data to Flash.
+ *
+ * @note All of dest_addr, src and size have to be 4-byte aligned. If write_encrypted is set, dest_addr and size must be 32-byte aligned.
+ *
+ * @note In bootloader, when write_encrypted == true, the src buffer is encrypted in place.
+ *
+ * @note [ESP-TEE] Using this API from the TEE will return an error if the dest_addr lies
+ *       within the active TEE partition range.
+ *
+ * @param  dest_addr Destination address to write in Flash.
+ * @param  src Pointer to the data to write to flash
+ * @param  size Length of data in bytes.
+ * @param  write_encrypted If true, data will be written encrypted on flash.
+ *
+ * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
+ * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
+ */
+esp_err_t bootloader_flash_write(size_t dest_addr, void *src, size_t size, bool write_encrypted);
+
+/**
+ * @brief  Erase the Flash sector.
+ *
+ * @param  sector  Sector number, the count starts at sector 0, 4KB per sector.
+ *
+ * @return esp_err_t
+ */
+esp_err_t bootloader_flash_erase_sector(size_t sector);
+
+/**
+ * @brief  Erase the Flash range.
+ *
+ * @note   [ESP-TEE] Using this API from the TEE will return an error if the start_addr lies
+ *         within the active TEE partition range.
+ *
+ * @param  start_addr start address of flash offset
+ * @param  size       sector aligned size to be erased
+ *
+ * @return esp_err_t
+ */
+esp_err_t bootloader_flash_erase_range(uint32_t start_addr, uint32_t size);
+
+/**
+ * @brief Enable the flash write protect (WEL bit).
+ */
+void bootloader_enable_wp(void);
+
+/**
+ * @brief Once this function is called,
+ * any on-going internal operations will be terminated and the device will return to its default power-on
+ * state and lose all the current volatile settings, such as Volatile Status Register bits, Write Enable Latch
+ * (WEL) status, Program/Erase Suspend status, etc.
+ */
+void bootloader_spi_flash_reset(void);
+
+//-------------------------------- Init APIs -------------------------------- //
+//For SDK usage only
 /**
  * @brief Initialize spi_flash in bootloader and print flash info
  *
@@ -33,6 +177,7 @@ void bootloader_flash_hardware_init(void);
  */
 void bootloader_init_mspi_clock(void);
 
+
 #ifdef __cplusplus
 }
 #endif

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32.c

@@ -25,7 +25,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_common.h"
 #include "bootloader_flash_config.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 
 #define FLASH_CLK_IO    MSPI_IOMUX_PIN_NUM_CLK

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32c2.c

@@ -17,7 +17,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "soc/spi_pins.h"
 #include "hal/mmu_hal.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32c3.c

@@ -19,7 +19,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32c5.c

@@ -22,7 +22,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32c6.c

@@ -18,7 +18,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32c61.c

@@ -18,7 +18,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32h2.c

@@ -18,7 +18,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32h21.c

@@ -12,7 +12,8 @@
 #include "esp_rom_gpio.h"
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/cache_hal.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32h4.c

@@ -20,7 +20,8 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32p4.c

@@ -16,7 +16,7 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"
@@ -24,6 +24,7 @@
 #include "hal/cache_hal.h"
 #include "hal/cache_ll.h"
 #include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 
 void IRAM_ATTR bootloader_flash_update_id(void)
 {

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32s2.c

@@ -20,7 +20,8 @@
 #include "soc/soc_caps.h"
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 #include "bootloader_common.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32s31.c

@@ -16,7 +16,7 @@
 #include "flash_qio_mode.h"
 #include "bootloader_flash_config.h"
 #include "bootloader_common.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
 #include "bootloader_init.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"
@@ -25,6 +25,7 @@
 #include "hal/cache_ll.h"
 #include "hal/clk_tree_ll.h"
 #include "esp_private/bootloader_flash_internal.h"
+#include "spi_flash_defs.h"
 
 void IRAM_ATTR bootloader_flash_update_id(void)
 {

components/bootloader_support/bootloader_flash/src/flash_qio_mode.c

@@ -8,7 +8,7 @@
 #include "bootloader_flash_config.h"
 #include "flash_qio_mode.h"
 #include "sdkconfig.h"
-#include "bootloader_flash_priv.h"
+#include "esp_private/bootloader_flash_internal.h"
 #include "esp_log.h"
 #include "esp_err.h"
 #include "esp_attr.h"
@@ -19,6 +19,7 @@
 #include "soc/io_mux_reg.h"
 #include "esp_private/spi_flash_os.h"
 #include "bootloader_flash_override.h"
+#include "spi_flash_defs.h"
 
 
 ESP_LOG_ATTR_TAG(TAG, "qio_mode");