espressif/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 19:13:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(spi_flash): reorganize header files and improve API encapsulation

Browse Source 
This commit reorganizes SPI flash header files to better reflect their
visibility and intended usage:

1. Rename `esp_flash_port/` to `esp_flash_chips/`:
   - Better reflects that these headers are for chip driver implementations
   - All chip driver headers moved to `esp_flash_chips/` directory
   - Added README.md explaining semi-public nature of these headers

2. Move internal headers to `esp_private/`:
   - `esp_flash_internal.h` -> `esp_private/esp_flash_internal.h`
   - `memspi_host_driver.h` -> `esp_private/memspi_host_driver.h`

3. Move chip driver related headers to `esp_flash_chips/`:
   - `esp_private/esp_flash_types.h` -> `esp_flash_chips/esp_flash_types.h`
   - `spi_flash/spi_flash_defs.h` -> `esp_flash_chips/spi_flash_defs.h`
   - `spi_flash_override.h` -> `esp_flash_chips/spi_flash_override.h`
   - All `spi_flash_chip_*.h` headers moved to `esp_flash_chips/`

4. Code improvements:
   - Remove unused includes (e.g., `spi_flash_override.h` from `cache_utils.c`)
   - Use public API `esp_flash_get_size()` instead of direct member access
   - Add `esp_flash_is_quad_mode` to linker.lf for IRAM placement

5. Documentation updates:
   - Add README.md in `esp_flash_chips/` explaining semi-public headers
   - Update programming guide with warnings about internal headers
   - Update both English and Chinese documentation

6. Update all references across the codebase:
   - Update includes in `spi_flash` component
   - Update `bootloader_support`, `app_update`, `esp_tee`, `espcoredump`
   - Update example projects

Breaking changes:
- Headers moved to new locations require include path updates
- `custom_flash_driver` example temporarily disabled until external
  components are updated
This commit is contained in:
Xiao Xufeng
2025-12-19 11:18:18 +08:00
parent 758cf6e1a3
commit 8dbf23630a
82 changed files with 375 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/app_update/esp_ota_ops.c
+1 -1
View File
@@ -31,7 +31,7 @@
#include "esp_attr.h"
#include "esp_bootloader_desc.h"
#include "esp_flash.h"
#include "esp_flash_internal.h"
#include "esp_private/esp_flash_internal.h" //For dangerous write protection
#define OTA_SLOT(i) (i & 0x0F)
#define ALIGN_UP(num, align) (((num) + ((align) - 1)) & ~((align) - 1))
components/app_update/test_apps/test_app_update/main/test_bootloader_update.c
+1 -1
View File
@@ -10,7 +10,7 @@
#include "unity.h"
#include "esp_log.h"
#include "esp_efuse.h"
#include "esp_flash_internal.h"
#include "esp_private/esp_flash_internal.h" //For dangerous write protection
#include "esp_rom_sys.h"
#include "utils_update.h"
#include "sdkconfig.h"
components/app_update/test_apps/test_app_update/main/test_ota_partitions.c
+3 -6
View File
@@ -6,7 +6,7 @@
#include "esp_ota_ops.h"
#include "esp_partition.h"
#include "esp_flash_partitions.h"
#include "esp_flash_internal.h"
#include "esp_flash.h"
#include "spi_flash_mmap.h"
#include "esp_image_format.h"
#include "esp_system.h"
@@ -34,12 +34,9 @@ static uint32_t find_unused_space(size_t required_size)
esp_partition_iterator_release(it);
TEST_ASSERT_NOT_NULL(latest_partition);
#if CONFIG_IDF_TARGET_LINUX
uint32_t flash_chip_size;
esp_flash_get_size(NULL, &flash_chip_size);
#else
uint32_t flash_chip_size = esp_flash_default_chip->size;
#endif // CONFIG_IDF_TARGET_LINUX
esp_err_t ret = esp_flash_get_size(esp_flash_default_chip, &flash_chip_size);
TEST_ASSERT_EQUAL(ESP_OK, ret);
uint32_t unused_offset = latest_partition->address + latest_partition->size;
TEST_ASSERT_GREATER_OR_EQUAL_UINT32(required_size, flash_chip_size - unused_offset);
return unused_offset;
components/bootloader_support/bootloader_flash/src/bootloader_flash.c
+1 -1
View File
@@ -131,7 +131,7 @@ esp_err_t bootloader_flash_erase_range(uint32_t start_addr, uint32_t size)
#elif CONFIG_IDF_TARGET_ESP32C5
#include "esp32c5/rom/opi_flash.h"
#endif
#include "spi_flash/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_defs.h"
#if ESP_TEE_BUILD
#include "esp_fault.h"
components/esp_hal_mspi/esp32c5/include/hal/mspi_ll.h
+1 -1
View File
@@ -40,7 +40,7 @@ extern "C" {
#define MSPI_TIMING_LL_CORE_CLOCK_MHZ_DEFAULT MSPI_LL_CORE_CLOCK_80_MHZ
// PSRAM frequency should be constrained by AXI frequency to avoid FIFO underflow.
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_LL_ADDR_INT_SUPPORTED 1
#define MSPI_LL_PMS_INT_SUPPORTED 1
components/esp_hal_mspi/esp32c61/include/hal/mspi_ll.h
+1 -1
View File
@@ -40,7 +40,7 @@ extern "C" {
#define MSPI_TIMING_LL_CORE_CLOCK_MHZ_DEFAULT MSPI_LL_CORE_CLOCK_80_MHZ
// PSRAM frequency should be constrained by AXI frequency to avoid FIFO underflow.
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_LL_EVENT_SLV_ST_END (1<<3)
#define MSPI_LL_EVENT_MST_ST_END (1<<4)
components/esp_hal_mspi/esp32h4/include/hal/mspi_ll.h
+4 -3
View File
@@ -33,6 +33,10 @@
#define MSPI_LL_PERIPH_NUM 2
#define MSPI_TIMING_LL_MSPI_ID_0 0
#define MSPI_TIMING_LL_MSPI_ID_1 1
// PSRAM frequency should be constrained by AXI frequency to avoid FIFO underflow.
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_LL_EVENT_SLV_ST_END (1<<3)
#define MSPI_LL_EVENT_MST_ST_END (1<<4)
#define MSPI_LL_EVENT_ECC_ERR (1<<5)
@@ -50,9 +54,6 @@
extern "C" {
#endif
// PSRAM frequency should be constrained by AXI frequency to avoid FIFO underflow.
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
/************************** MSPI pll clock configurations **************************/
/*
* @brief Select FLASH clock source
components/esp_hal_mspi/esp32p4/include/hal/mspi_ll.h
+1 -1
View File
@@ -48,7 +48,7 @@ extern "C" {
#define MSPI_TIMING_LL_MSPI_ID_1 1
// PSRAM frequency should be constrained by AXI frequency to avoid FIFO underflow.
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_TIMING_LL_HP_FLASH_CORE_CLK_DIV 4
#define MSPI_TIMING_LL_LP_FLASH_CORE_CLK_DIV 6
components/esp_hal_mspi/esp32s31/include/hal/mspi_ll.h
+1 -1
View File
@@ -45,7 +45,7 @@ extern "C" {
#define MSPI_TIMING_LL_MSPI_ID_1 1
// PSRAM frequency should be constrained by AXI frequency to avoid FIFO underflow.
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_TIMING_LL_PSRAM_FREQ_AXI_CONSTRAINED 1
#define MSPI_LL_AXI_DISABLE_SUPPORTED 1
#define MSPI_LL_INTR_EVENT_SUPPORTED 1
components/esp_pm/CMakeLists.txt
+5
View File
@@ -24,3 +24,8 @@ idf_component_register(SRCS "${srcs}"
INCLUDE_DIRS include
PRIV_REQUIRES "${priv_requires}"
LDFRAGMENTS linker.lf)
if(CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED)
# Force linking init_flash ESP_SYSTEM_INIT_FN to ensure it's not discarded by linker
target_link_libraries(${COMPONENT_LIB} INTERFACE "-u pm_c5_flash_freq_limit_init_include_func")
endif()
components/esp_pm/include/esp_private/pm_impl.h
-9
View File
@@ -140,15 +140,6 @@ esp_err_t esp_pm_register_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
*/
esp_err_t esp_pm_unregister_skip_light_sleep_callback(skip_light_sleep_cb_t cb);
/**
* @brief Initialize flash frequency limit
*
* This function initializes the flash frequency limit.
* @note This function is only available when CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED is enabled.
*/
void esp_pm_flash_freq_limit_init(void);
#ifdef CONFIG_PM_PROFILING
#define WITH_PROFILING
#include "esp_timer.h"
components/esp_pm/pm_c5_flash_freq_limit.c
+19 -12
View File
@@ -16,6 +16,7 @@
#include "soc/rtc.h"
#include "hal/efuse_hal.h"
#include "esp_private/startup_internal.h"
#include "esp_private/pm_impl_freq_limit.h"
#include "esp_private/spi_flash_freq_limit_cbs.h"
#include "esp_private/esp_clk_utils.h"
@@ -39,18 +40,6 @@ static uint32_t IRAM_ATTR get_encrypt_lock_freq_limit(void)
}
}
void esp_pm_flash_freq_limit_init(void)
{
uint32_t limit_freq_mhz = get_encrypt_lock_freq_limit();
ESP_EARLY_LOGW("spi_flash", "CPU frequency is set to 240MHz. esp_flash_write_encrypted() will automatically limit CPU frequency to %dMHz during execution.", limit_freq_mhz);
#ifdef CONFIG_PM_ENABLE
/* Pre-calculate and store forced frequency configuration during initialization.
* This is done here to avoid runtime calculation overhead in lock/unlock functions.
*/
esp_pm_impl_cpu_max_freq_force_init(limit_freq_mhz);
#endif
}
#if !CONFIG_PM_ENABLE
/* Saved original frequency for !PM_ENABLE case (0 means no change was made) */
static uint32_t s_saved_freq_mhz = 0;
@@ -136,6 +125,24 @@ static void IRAM_ATTR unlimit_cpu_freq(void)
}
#endif // !CONFIG_PM_ENABLE
ESP_SYSTEM_INIT_FN(init_pm_flash_freq_limit, SECONDARY, BIT(0), 202)
{
uint32_t limit_freq_mhz = get_encrypt_lock_freq_limit();
ESP_EARLY_LOGW("spi_flash", "CPU frequency is set to 240MHz. esp_flash_write_encrypted() will automatically limit CPU frequency to %dMHz during execution.", limit_freq_mhz);
#ifdef CONFIG_PM_ENABLE
/* Pre-calculate and store forced frequency configuration during initialization.
* This is done here to avoid runtime calculation overhead in lock/unlock functions.
*/
esp_pm_impl_cpu_max_freq_force_init(limit_freq_mhz);
#endif
return ESP_OK;
}
void pm_c5_flash_freq_limit_init_include_func(void)
{
// Linker hook function, exists to make the linker examine this file
}
void IRAM_ATTR esp_flash_freq_limit_cb(void)
{
/* Limit the frequency */
components/esp_rom/esp32c2/include/esp32c2/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32c3/include/esp32c3/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32c5/include/esp32c5/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32c6/include/esp32c6/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32c61/include/esp32c61/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32h2/include/esp32h2/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32h21/include/esp32h21/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32h4/include/esp32h4/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32p4/include/esp32p4/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_rom/esp32s31/include/esp32s31/rom/esp_flash.h
-1
View File
@@ -16,7 +16,6 @@ extern "C" {
just adds ROM-specific parts
*/
struct spi_flash_chip_t;
typedef struct esp_flash_t esp_flash_t;
/* Structure to wrap "global" data used by esp_flash in ROM */
components/esp_system/startup_funcs.c
+1 -15
View File
@@ -12,17 +12,12 @@
#include "esp_err.h"
#include "esp_check.h"
#include "esp_system.h"
#include "esp_private/log_util.h"
#include "esp_log.h"
#include "esp_private/cache_utils.h"
#include "spi_flash_mmap.h"
#include "esp_private/mspi_intr.h"
#include "esp_newlib.h"
#include "esp_xt_wdt.h"
#include "esp_cpu.h"
#include "esp_private/startup_internal.h"
#include "esp_private/pm_impl.h"
#include "freertos/portmacro.h"
#include "freertos/FreeRTOS.h"
#include "soc/soc_caps.h"
#include "hal/wdt_hal.h"
#include "hal/uart_types.h"
@@ -38,7 +33,6 @@
#endif
#include "esp_private/esp_clk.h"
#include "esp_private/spi_flash_os.h"
#include "esp_private/brownout.h"
#include "esp_private/vbat.h"
@@ -124,14 +118,6 @@ ESP_SYSTEM_INIT_FN(init_pm, SECONDARY, BIT(0), 201)
}
#endif // CONFIG_PM_ENABLE
#if CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED
ESP_SYSTEM_INIT_FN(init_pm_flash_freq_limit, SECONDARY, BIT(0), 202)
{
esp_pm_flash_freq_limit_init();
return ESP_OK;
}
#endif // CONFIG_PM_WORKAROUND_FREQ_LIMIT_ENABLED
#if SOC_APB_BACKUP_DMA
ESP_SYSTEM_INIT_FN(init_apb_dma, SECONDARY, BIT(0), 203)
{
components/esp_system/system_init_fn.txt
+1 -1
View File
@@ -114,7 +114,7 @@ SECONDARY: 151: nvs_sec_provider_register_hmac_scheme in components/nvs_sec_prov
# the rest of the components which are initialized from startup_funcs.c
# [refactor-todo]: move init calls into respective components
SECONDARY: 201: init_pm in components/esp_system/startup_funcs.c on BIT(0)
SECONDARY: 202: init_pm_flash_freq_limit in components/esp_system/startup_funcs.c on BIT(0)
SECONDARY: 202: init_pm_flash_freq_limit in components/esp_pm/pm_c5_flash_freq_limit.c on BIT(0)
SECONDARY: 203: init_apb_dma in components/esp_system/startup_funcs.c on BIT(0)
SECONDARY: 204: init_coexist in components/esp_system/startup_funcs.c on BIT(0)
SECONDARY: 205: init_bootloader_offset in components/esp_system/startup_funcs.c on BIT(0)
components/esp_tee/subproject/main/core/esp_secure_services_iram.c
+2 -2
View File
@@ -16,8 +16,8 @@
#include "hal/spi_flash_hal.h"
#include "hal/spi_flash_types.h"
#include "spi_flash_chip_generic.h"
#include "memspi_host_driver.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#include "esp_private/memspi_host_driver.h"
#include "esp_private/mspi_timing_tuning.h"
#include "esp_flash.h"
#include "riscv/rv_utils.h"
components/espcoredump/src/core_dump_flash.c
+1 -1
View File
@@ -10,7 +10,7 @@
#include "esp_log.h"
#include "esp_core_dump_types.h"
#include "core_dump_checksum.h"
#include "esp_flash_internal.h"
#include "esp_private/esp_flash_internal.h"
#include "esp_flash_encrypt.h"
#include "esp_rom_crc.h"
#include "esp_private/spi_flash_os.h"
components/soc/esp32s31/include/soc/soc_caps.h
-1
View File
@@ -212,7 +212,6 @@
#define SOC_MEMSPI_IS_INDEPENDENT 1
#define SOC_MEMSPI_SUPPORT_CONTROL_DUMMY_OUT 1
#define SOC_MEMSPI_FLASH_PSRAM_INDEPENDENT 1
/*-------------------------- SYSTIMER CAPS ----------------------------------*/
components/spi_flash/CMakeLists.txt
+2 -4
View File
@@ -7,8 +7,7 @@ if(${target} STREQUAL "linux")
"linux/flash_mmap.c"
"spi_flash_blockdev.c"
INCLUDE_DIRS include
REQUIRES esp_hal_mspi esp_blockdev
PRIV_INCLUDE_DIRS include/spi_flash)
REQUIRES esp_hal_mspi esp_blockdev)
return()
endif()
@@ -71,7 +70,6 @@ idf_component_register(SRCS "${srcs}"
REQUIRES hal esp_hal_mspi esp_blockdev
PRIV_REQUIRES "${priv_requires}"
INCLUDE_DIRS include
PRIV_INCLUDE_DIRS include/spi_flash
LDFRAGMENTS linker.lf)
# Avoid cache miss by unexpected inlineing when built by -Os
@@ -89,5 +87,5 @@ if(NOT non_os_build AND NOT CONFIG_APP_BUILD_TYPE_PURE_RAM_APP)
idf_component_optional_requires(PRIVATE esp_psram)
endif()
# Force linking init_flash ESP_SYSTEM_INIT_FN to ensure it's not discarded by linker
target_link_libraries(${COMPONENT_LIB} INTERFACE "-u esp_flash_app_init")
target_link_libraries(${COMPONENT_LIB} INTERFACE "-u esp_flash_spi_init_include_func")
endif()
components/spi_flash/cache_utils.c
-1
View File
@@ -32,7 +32,6 @@
#include "esp_attr.h"
#include "esp_memory_utils.h"
#include "esp_intr_alloc.h"
#include "spi_flash_override.h"
#include "esp_private/esp_cache_private.h"
#include "esp_private/cache_utils.h"
#include "esp_private/spi_flash_os.h"
components/spi_flash/esp32s3/opi_flash_cmd_format_mxic.h
+1 -1
View File
@@ -5,7 +5,7 @@
*/
#include <stdint.h>
#include "spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_defs.h"
//MXIC OPI mode needs two bytes of command - 2nd byte is the inversion of the command (1st) byte. S3 HW send LSB first
#define MXIC_CMD16(cmd8) ( (uint8_t)(cmd8) | ((uint8_t)(~(cmd8)) << 8) )
components/spi_flash/esp_flash_api.c
+9 -7
View File
@@ -9,21 +9,23 @@
#include <sys/param.h>
#include <string.h>
#include "esp_cpu.h"
#include "esp_memory_utils.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "memspi_host_driver.h"
#include "esp_log.h"
#include "sdkconfig.h"
#include "esp_flash_internal.h"
#include "spi_flash_defs.h"
#include "spi_flash_mmap.h"
#include "esp_rom_caps.h"
#include "esp_rom_spiflash.h"
#include "esp_private/esp_clk.h"
#include "esp_spi_flash_counters.h"
#include "esp_check.h"
#include "hal/efuse_hal.h"
#include "soc/chip_revision.h"
#include "hal/efuse_hal.h"
#include "esp_spi_flash_counters.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "esp_private/memspi_host_driver.h"
#include "esp_private/esp_flash_internal.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "spi_flash_mmap.h"
#if CONFIG_IDF_TARGET_ESP32S2
#include "esp_crypto_lock.h" // for locking flash encryption peripheral
components/spi_flash/esp_flash_spi_init.c
+15 -11
View File
@@ -1,13 +1,10 @@
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#include "sdkconfig.h"
#include "esp_flash.h"
#include "memspi_host_driver.h"
#include "esp_flash_spi_init.h"
#include "driver/gpio.h"
#include "esp_rom_gpio.h"
#include "esp_rom_efuse.h"
@@ -17,12 +14,8 @@
#include "esp_private/spi_share_hw_ctrl.h"
#include "esp_private/mspi_intr.h"
#include "esp_ldo_regulator.h"
#include "hal/spi_flash_hal.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "hal/gpio_hal.h"
#include "esp_flash_internal.h"
#include "esp_rom_gpio.h"
#include "esp_private/spi_flash_os.h"
#include "esp_private/cache_utils.h"
#include "esp_private/log_util.h"
#include "esp_private/startup_internal.h"
@@ -33,8 +26,16 @@
#include "esp_private/esp_clk_tree_common.h"
#include "clk_ctrl_os.h"
#include "soc/soc_caps.h"
#include "hal/spi_flash_hal.h"
#include "hal/mspi_ll.h"
#include "esp_flash.h"
#include "esp_flash_spi_init.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "esp_private/memspi_host_driver.h"
#include "esp_private/esp_flash_internal.h"
#include "esp_private/spi_flash_os.h"
__attribute__((unused)) static const char TAG[] = "spi_flash";
#if CONFIG_SPI_FLASH_ROM_IMPL && (CONFIG_ESPTOOLPY_FLASHSIZE_32MB || CONFIG_ESPTOOLPY_FLASHSIZE_64MB || CONFIG_ESPTOOLPY_FLASHSIZE_128MB)
@@ -357,12 +358,10 @@ static void deinit_gpspi_clock(esp_flash_t *chip)
// Disable the clock source
esp_clk_tree_enable_src(chip->clock_source, false);
#if SOC_SPI_SUPPORT_CLK_RC_FAST
// Disable RC_FAST clock if it was used
if (chip->clock_source == SPI_CLK_SRC_RC_FAST) {
if ((soc_module_clk_t)chip->clock_source == SOC_MOD_CLK_RC_FAST) {
periph_rtc_dig_clk8m_disable();
}
#endif
#endif // !CONFIG_IDF_TARGET_ESP32
}
@@ -668,3 +667,8 @@ ESP_SYSTEM_INIT_FN(init_flash, CORE, BIT(0), 130)
return ESP_OK;
}
#endif // !CONFIG_APP_BUILD_TYPE_PURE_RAM_APP
void esp_flash_spi_init_include_func(void)
{
// Linker hook function, exists to make the linker examine this file
}
components/spi_flash/include/esp_flash.h
-3
View File
@@ -16,9 +16,6 @@
extern "C" {
#endif
struct spi_flash_chip_t;
typedef struct spi_flash_chip_t spi_flash_chip_t;
/** @cond */
typedef struct esp_flash_t esp_flash_t;
/** @endcond */
components/spi_flash/include/esp_flash_chips/README.md
+50
View File
@@ -0,0 +1,50 @@
# ESP Flash Chips Directory
## Overview
This directory contains header files for implementing custom SPI flash chip drivers. These headers are **semi-public** - they are intended for expert users who need to implement custom chip drivers for unsupported flash chips, but they are **not considered stable API** and may change without notice.
## Intended Use
These headers are provided for:
- **Expert users** who need to implement custom chip drivers for flash chips not supported by ESP-IDF
- **Advanced developers** who need to extend or modify existing chip driver behavior
- **Internal ESP-IDF development** for implementing official chip drivers
## Important Warnings
⚠️ **These headers are NOT stable API**
- The structure and content of these headers may change in any ESP-IDF release
- No backward compatibility is guaranteed
- These headers are not part of the public API contract
- Changes may break custom chip driver implementations without notice
⚠️ **Use at your own risk**
- Custom chip drivers using these headers may break when upgrading ESP-IDF
- Thorough testing is required after each ESP-IDF version upgrade
- Consider contributing your chip driver to ESP-IDF or [3rd party flash drivers repo](https://github.com/espressif/esp-flash-drivers) instead of maintaining it separately
## Directory Contents
- `spi_flash_chip_driver.h` - Core chip driver interface definitions
- `esp_flash_types.h` - Internal flash type definitions
- `spi_flash_chip_*.h` - Header files for specific chip driver implementations that you may reuse (especially the generic driver)
- `spi_flash_override.h` - Flash override configuration structures for those parts outside the scope of esp_flash driver, usually used in the startup code
## When to Use These Headers
✅ **Appropriate use cases:**
- Implementing a driver for a new flash chip model
- Extending functionality of an existing chip driver
- Debugging chip-specific flash issues
See [example](examples/storage/custom_flash_driver) on how to implement the driver for a custom flash chip.
❌ **Not appropriate for:**
- Regular application development (use public APIs in `esp_flash.h` instead)
- Production code that needs stable API guarantees
components/spi_flash/include/esp_private/esp_flash_types.h → components/spi_flash/include/esp_flash_chips/esp_flash_types.h
+1 -2
View File
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -98,4 +98,3 @@ struct esp_flash_t {
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash_chip_boya.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_boya.h
+9 -1
View File
@@ -8,11 +8,19 @@
#include <stdint.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "sdkconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
#ifdef CONFIG_SPI_FLASH_SUPPORT_BOYA_CHIP
extern const spi_flash_chip_t esp_flash_chip_boya;
#else
extern __attribute__((weak)) const spi_flash_chip_t esp_flash_chip_boya;
#endif
#ifdef __cplusplus
}
#endif
components/spi_flash/include/esp_flash_port/spi_flash_chip_driver.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_driver.h
+9 -1
View File
@@ -7,7 +7,11 @@
#pragma once
#include "esp_flash.h"
#include "esp_attr.h"
#include "esp_private/esp_flash_types.h"
#include "esp_flash_chips/esp_flash_types.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef struct spi_flash_chip_t spi_flash_chip_t;
@@ -222,3 +226,7 @@ extern const spi_flash_chip_t **esp_flash_registered_chips;
* This ID is used to match the chip against known drivers.
*/
void spi_flash_chip_list_check(esp_flash_t *chip, uint32_t device_id);
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash_chip_gd.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_gd.h
+8 -1
View File
@@ -8,9 +8,12 @@
#include <stdint.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "sdkconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* GD (GigaDevice) SPI flash chip_drv, uses all the above functions for its operations. In
@@ -31,3 +34,7 @@ extern const spi_flash_chip_t esp_flash_chip_gd;
#else
extern __attribute__((weak)) const spi_flash_chip_t esp_flash_chip_gd;
#endif
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash_chip_generic.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_generic.h
+9 -2
View File
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -8,8 +8,11 @@
#include <stdint.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#ifdef __cplusplus
extern "C" {
#endif
/*
* The 'chip_generic' SPI flash operations are a lowest common subset of SPI
@@ -401,3 +404,7 @@ esp_err_t spi_flash_chip_generic_read_unique_id_none(esp_flash_t *chip, uint64_t
/// Default timeout configuration used by most chips
extern const flash_chip_op_timeout_t spi_flash_chip_generic_timeout;
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash_chip_issi.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_issi.h
+8 -1
View File
@@ -8,9 +8,12 @@
#include <stdint.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "sdkconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* ISSI SPI flash chip_drv, uses all the above functions for its operations. In
@@ -26,3 +29,7 @@ extern const spi_flash_chip_t esp_flash_chip_issi;
#else
extern __attribute__((weak)) const spi_flash_chip_t esp_flash_chip_issi;
#endif
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash_chip_mxic.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_mxic.h
+9 -1
View File
@@ -8,9 +8,13 @@
#include <stdint.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "sdkconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* MXIC SPI flash chip_drv, uses all the above functions for its operations. In
* default autodetection, this is used as a catchall if a more specific chip_drv
@@ -32,3 +36,7 @@ extern const spi_flash_chip_t esp_flash_chip_mxic_opi;
#else
extern __attribute__((weak)) const spi_flash_chip_t esp_flash_chip_mxic_opi;
#endif
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash_chip_th.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_th.h
+9 -1
View File
@@ -8,11 +8,19 @@
#include <stdint.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "sdkconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
#ifdef CONFIG_SPI_FLASH_SUPPORT_TH_CHIP
extern const spi_flash_chip_t esp_flash_chip_th;
#else
extern __attribute__((weak)) const spi_flash_chip_t esp_flash_chip_th;
#endif
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash_chip_winbond.h → components/spi_flash/include/esp_flash_chips/spi_flash_chip_winbond.h
+9 -1
View File
@@ -8,9 +8,13 @@
#include <stdint.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "sdkconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* Winbond SPI flash chip_drv, uses all the above functions for its operations. In
* default autodetection, this is used as a catchall if a more specific chip_drv
@@ -22,3 +26,7 @@ extern const spi_flash_chip_t esp_flash_chip_winbond;
#else
extern __attribute__((weak)) const spi_flash_chip_t esp_flash_chip_winbond;
#endif
#ifdef __cplusplus
}
#endif
components/spi_flash/include/spi_flash/spi_flash_defs.h → components/spi_flash/include/esp_flash_chips/spi_flash_defs.h
View File
components/spi_flash/include/spi_flash_override.h → components/spi_flash/include/esp_flash_chips/spi_flash_override.h
View File
components/spi_flash/include/esp_flash_internal.h → components/spi_flash/include/esp_private/esp_flash_internal.h
+1 -1
View File
@@ -12,7 +12,7 @@
#include "sdkconfig.h"
#include "esp_flash.h"
#include "esp_private/esp_flash_types.h"
#include "esp_flash_chips/esp_flash_types.h"
/** Internal API, don't use in the applications */
components/spi_flash/include/memspi_host_driver.h → components/spi_flash/include/esp_private/memspi_host_driver.h
+8
View File
@@ -7,6 +7,10 @@
#pragma once
#include "hal/spi_flash_hal.h"
#ifdef __cplusplus
extern "C" {
#endif
/** Default configuration for the memspi (high speed version) */
#define ESP_FLASH_DEFAULT_HOST_DRIVER() (spi_flash_host_driver_t) { \
.dev_config = spi_flash_hal_device_config, \
@@ -183,3 +187,7 @@ int memspi_host_read_data_slicer(spi_flash_host_inst_t *host, uint32_t address,
* @return Length that can actually be written in one `program_page` call in `spi_flash_host_driver_t`.
*/
int memspi_host_write_data_slicer(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_address, uint32_t page_size);
#ifdef __cplusplus
}
#endif
components/spi_flash/include/esp_private/spi_flash_os.h
+6 -4
View File
@@ -14,13 +14,15 @@
#include "sdkconfig.h"
#include "esp_rom_spiflash.h"
#include "esp_err.h"
#include "esp_flash.h"
#include "esp_private/esp_flash_types.h"
#include "hal/spi_flash_hal.h"
#include "spi_flash_override.h"
#include "soc/soc_caps.h"
#include "soc/clk_tree_defs.h"
#include "hal/spi_flash_hal.h"
#include "esp_flash.h"
#include "esp_flash_chips/esp_flash_types.h"
#include "esp_flash_chips/spi_flash_override.h"
#ifdef __cplusplus
extern "C" {
#endif
components/spi_flash/linker.lf
+1
View File
@@ -18,6 +18,7 @@ entries:
esp_flash_api: esp_flash_chip_driver_initialized (noflash)
esp_flash_api: esp_flash_init (noflash)
esp_flash_api: esp_flash_init_main (noflash)
esp_flash_api: esp_flash_is_quad_mode (noflash)
esp_flash_api: read_unique_id (noflash)
esp_flash_api: detect_spi_flash_chip (noflash)
esp_flash_api: esp_flash_get_physical_size (noflash)
components/spi_flash/memspi_host_driver.c
+4 -4
View File
@@ -6,15 +6,15 @@
#include "sdkconfig.h"
#include "soc/soc_caps.h"
#include "spi_flash_defs.h"
#include "memspi_host_driver.h"
#include "string.h"
#include "esp_log.h"
#include "esp_private/cache_utils.h"
#include "esp_flash_partitions.h"
#include "esp_memory_utils.h"
#include "hal/mspi_ll.h"
#include "esp_flash_partitions.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_private/cache_utils.h"
#include "esp_private/memspi_host_driver.h"
#define SPI_FLASH_HAL_MAX_WRITE_BYTES 64
#define SPI_FLASH_HAL_MAX_READ_BYTES 64
components/spi_flash/spi_flash_blockdev.c
+3 -2
View File
@@ -6,11 +6,12 @@
#include <inttypes.h>
#include <string.h>
#include "esp_flash.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_heap_caps.h"
#include "esp_blockdev.h"
#include "esp_flash.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
static inline esp_err_t esp_flash_blockdev_read(esp_blockdev_handle_t handle, uint8_t* dst_buf, size_t dst_buf_size, uint64_t src_addr, size_t data_read_len)
{
if (handle == NULL || dst_buf_size < data_read_len) {
components/spi_flash/spi_flash_chip_boya.c
+8 -16
View File
@@ -1,21 +1,13 @@
// Copyright 2015-2021 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <stdlib.h>
#include "spi_flash_chip_generic.h"
#include "spi_flash_chip_gd.h"
#include "spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#include "esp_flash_chips/spi_flash_chip_gd.h"
esp_err_t spi_flash_chip_boya_probe(esp_flash_t *chip, uint32_t flash_id)
{
components/spi_flash/spi_flash_chip_drivers.c
+10 -9
View File
@@ -5,18 +5,19 @@
*/
#include <stdlib.h>
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "spi_flash_chip_generic.h"
#include "spi_flash_chip_issi.h"
#include "spi_flash_chip_mxic.h"
#include "spi_flash_chip_gd.h"
#include "spi_flash_chip_winbond.h"
#include "spi_flash_chip_boya.h"
#include "spi_flash_chip_th.h"
#include "spi_flash_defs.h"
#include "sdkconfig.h"
#include "esp_log.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#include "esp_flash_chips/spi_flash_chip_issi.h"
#include "esp_flash_chips/spi_flash_chip_mxic.h"
#include "esp_flash_chips/spi_flash_chip_gd.h"
#include "esp_flash_chips/spi_flash_chip_winbond.h"
#include "esp_flash_chips/spi_flash_chip_boya.h"
#include "esp_flash_chips/spi_flash_chip_th.h"
ESP_LOG_ATTR_TAG(TAG, "spi_flash");
#define FORMAT_STR "Detected %s flash chip but using generic driver. For optimal functionality, enable `SPI_FLASH_SUPPORT_%s_CHIP` in menuconfig"
components/spi_flash/spi_flash_chip_gd.c
+4 -3
View File
@@ -8,11 +8,12 @@
#include <string.h>
#include <sys/param.h> // For MIN/MAX
#include "esp_log.h"
#include "spi_flash_chip_generic.h"
#include "spi_flash_chip_gd.h"
#include "spi_flash_defs.h"
#include "sdkconfig.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#include "esp_flash_chips/spi_flash_chip_gd.h"
#define ADDR_32BIT(addr) (addr >= (1<<24))
#define REGION_32BIT(start, len) ((start) + (len) > (1<<24))
components/spi_flash/spi_flash_chip_generic.c
+5 -4
View File
@@ -7,14 +7,15 @@
#include <stdlib.h>
#include <string.h>
#include <sys/param.h> // For MIN/MAX
#include "spi_flash_chip_generic.h"
#include "spi_flash_defs.h"
#include "hal/spi_flash_encrypt_hal.h"
#include "esp_log.h"
#include "esp_attr.h"
#include "esp_private/spi_flash_os.h"
#include "esp_rom_caps.h"
#include "hal/spi_flash_encrypt_hal.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#include "esp_private/spi_flash_os.h"
#define IS_REGION_32BIT(start, len) ((start) + (len) > (1<<24))
#define IS_ADDR_32BIT(addr) (addr >= (1<<24))
components/spi_flash/spi_flash_chip_issi.c
+8 -16
View File
@@ -1,21 +1,13 @@
// Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <stdlib.h>
#include "spi_flash_chip_generic.h"
#include "spi_flash_chip_issi.h"
#include "spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#include "esp_flash_chips/spi_flash_chip_issi.h"
/* Driver for ISSI flash chip, as used in ESP32 D2WD */
components/spi_flash/spi_flash_chip_mxic.c
+3 -2
View File
@@ -5,10 +5,11 @@
*/
#include <stdlib.h>
#include "spi_flash_chip_generic.h"
#include "spi_flash_defs.h"
#include "esp_log.h"
#include "hal/spi_flash_hal.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
/* Driver for MXIC flash chip */
components/spi_flash/spi_flash_chip_mxic_opi.c
+3 -2
View File
@@ -5,12 +5,13 @@
*/
#include <stdlib.h>
#include "spi_flash_chip_generic.h"
#include "spi_flash_defs.h"
#include "esp_log.h"
#include "string.h"
#include <sys/param.h> // For MIN/MAX
#include "hal/spi_flash_hal.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#define CMD_OPI_FLASH_MXIC(cmd) ((((~(cmd) & 0xff) << 8)) | ((cmd) & 0xff))
#define CMD_OPI_FLASH_MXIC_CHIP_ERASE 0x9F60
components/spi_flash/spi_flash_chip_th.c
+2 -2
View File
@@ -5,8 +5,8 @@
*/
#include <stdlib.h>
#include "spi_flash_chip_generic.h"
#include "spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
esp_err_t spi_flash_chip_th_probe(esp_flash_t *chip, uint32_t flash_id)
{
components/spi_flash/spi_flash_chip_winbond.c
+3 -2
View File
@@ -8,8 +8,9 @@
#include <string.h>
#include <sys/param.h> // For MIN/MAX
#include "esp_log.h"
#include "spi_flash_chip_generic.h"
#include "spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#define REGION_32BIT(start, len) ((start) + (len) > (1<<24))
components/spi_flash/spi_flash_dpd_enable.c
+2 -1
View File
@@ -9,8 +9,9 @@
#include "esp_err.h"
#include "esp_log.h"
#include "esp_attr.h"
#include "spi_flash_chip_generic.h"
#include "hal/spi_flash_hal.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
/*******************************************************************************
* Flash deep power-down mode.
components/spi_flash/spi_flash_hpm_enable.c
+3 -2
View File
@@ -8,10 +8,11 @@
#include "sdkconfig.h"
#include "esp_err.h"
#include "esp_log.h"
#include "spi_flash_defs.h"
#include "esp_rom_sys.h"
#include "esp_rom_spiflash.h"
#include "spi_flash_override.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_override.h"
// TODO: These dependencies will be removed after remove bootloader_flash to G0.IDF-4609
#include "bootloader_flash_override.h"
components/spi_flash/spi_flash_os_func_app.c
+5 -3
View File
@@ -9,9 +9,6 @@
#include <sys/param.h> //For max/min
#include "esp_attr.h"
#include "esp_private/system_internal.h"
#include "esp_flash.h"
#include "esp_private/esp_flash_types.h"
#include "esp_flash_partitions.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "hal/spi_types.h"
@@ -19,6 +16,11 @@
#include "esp_log.h"
#include "esp_compiler.h"
#include "esp_rom_sys.h"
#include "esp_flash.h"
#include "esp_flash_chips/esp_flash_types.h"
#include "esp_flash_partitions.h"
#include "esp_private/spi_flash_os.h"
#include "esp_private/cache_utils.h"
#include "esp_private/spi_share_hw_ctrl.h"
components/spi_flash/spi_flash_os_func_noos.c
+4 -3
View File
@@ -6,15 +6,16 @@
#include <stdarg.h>
#include "sdkconfig.h"
#include "esp_flash.h"
#include "esp_private/esp_flash_types.h"
#include "esp_attr.h"
#include "esp_rom_sys.h"
#include "esp_cpu.h"
#include "rom/cache.h"
#include "soc/soc_caps.h"
#include "hal/cache_hal.h"
#include "hal/cache_ll.h"
#include "soc/soc_caps.h"
#include "esp_flash.h"
#include "esp_flash_chips/esp_flash_types.h"
static IRAM_ATTR esp_err_t start(void *arg, uint32_t flags)
{
components/spi_flash/spi_flash_wrap.c
+3 -2
View File
@@ -9,11 +9,12 @@
#include "sdkconfig.h"
#include "esp_err.h"
#include "esp_log.h"
#include "spi_flash_defs.h"
#include "esp_rom_sys.h"
#include "esp_rom_spiflash.h"
#include "rom/spi_flash.h"
#include "spi_flash_override.h"
#include "esp_flash_chips/spi_flash_defs.h"
#include "esp_flash_chips/spi_flash_override.h"
#include "esp_private/spi_flash_os.h"
// TODO: These dependencies will be removed after remove bootloader_flash to G0.IDF-4609
components/spi_flash/test_apps/esp_flash/main/test_esp_flash_drv.c
+1 -1
View File
@@ -14,7 +14,7 @@
#include "esp_flash.h"
#include "esp_private/spi_common_internal.h"
#include "esp_flash_spi_init.h"
#include "memspi_host_driver.h"
#include "esp_private/memspi_host_driver.h"
#include <esp_attr.h>
#include "esp_log.h"
#include "test_utils.h"
components/spi_flash/test_apps/esp_flash_blockdev/main/test_spi_flash.c
+1 -1
View File
@@ -9,7 +9,7 @@
#include "esp_log.h"
#include "unity.h"
#include "esp_flash_port/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "test_flash_utils.h"
TEST_CASE("spi_flash BDL test", "[esp_flash]")
components/spi_flash/test_apps/esp_flash_freq_limit/main/idf_component.yml
+3
View File
@@ -0,0 +1,3 @@
dependencies:
test_utils:
path: ${IDF_PATH}/tools/test_apps/components/test_utils
components/spi_flash/test_apps/esp_flash_freq_limit/main/test_esp_flash_freq_limit.c
+1 -1
View File
@@ -14,7 +14,7 @@
#include <inttypes.h>
#include "unity.h"
#include "esp_flash.h"
#include "esp_private/esp_flash_types.h"
#include "esp_flash_chips/esp_flash_types.h"
#include "soc/rtc.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
docs/en/api-reference/peripherals/spi_flash/index.rst
+5 -1
View File
@@ -175,6 +175,10 @@ Note that since memory mapping happens in pages, it may be possible to read data
SPI Flash Implementation
------------------------
.. note::
The header files in ``components/spi_flash/include/esp_flash_chips/`` directory are **semi-public** - they are intended for expert users who need to implement custom chip drivers for unsupported flash chips, but they are **not considered stable API** and may change without notice. For most use cases, you should use the public APIs in ``esp_flash.h`` instead.
The ``esp_flash_t`` structure holds chip data as well as three important parts of this API:
1. The host driver, which provides the hardware support to access the chip;
@@ -193,7 +197,7 @@ You can also implement your own host driver, even with the GPIO. As long as all
Chip Driver
^^^^^^^^^^^
The chip driver, defined in ``spi_flash_chip_driver.h``, wraps basic functions provided by the host driver for the API layer to use.
The chip driver, defined in ``esp_flash_chips/spi_flash_chip_driver.h``, wraps basic functions provided by the host driver for the API layer to use.
Some operations need some commands to be sent first, or read some status afterwards. Some chips need different commands or values, or need special communication ways.
docs/en/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst
+6 -1
View File
@@ -149,7 +149,12 @@ Generic Flash Driver
The flash driver in the application is used to read, write, erase, and save data. It also supports some advanced features like OTA. Below is a guide on how to customize the driver for your specific flash model.
- Step 1: The last item of `default_registered_chips` should be the `generic chip driver <https://github.com/espressif/esp-idf/blob/master/components/spi_flash/spi_flash_chip_generic.c>`_. If your flash chip does not match any of the chip drivers listed above, it will use the generic driver. Check for any differences in behavior between your flash and the generic driver, including but not limited to different commands, dummy cycles, data bytes, and status registers.
- Step 2: If you have found something different from the generic driver, you need to implement your own chip driver. Create a new file named ``spi_flash_chip_<vendor>.c`` to implement the specific behavior, and copy the ``esp_flash_chip_generic`` structure into it as a starting point. Remember to include ``spi_flash_chip_generic.h``. Here is an example `esp_flash_nor <https://github.com/espressif/esp-flash-drivers/tree/main/esp_flash_nor/>`_.
- Step 2: If you have found something different from the generic driver, you need to implement your own chip driver. Create a new file named ``spi_flash_chip_<vendor>.c`` to implement the specific behavior, and copy the ``esp_flash_chip_generic`` structure into it as a starting point. Remember to include ``esp_flash_chips/spi_flash_chip_generic.h``. Here is an example `esp_flash_nor <https://github.com/espressif/esp-flash-drivers/tree/main/esp_flash_nor/>`_.
.. note::
The chip driver header files are located in the ``esp_flash_chips/`` directory (e.g., ``components/spi_flash/include/esp_flash_chips/``). These headers are **semi-public** - they are intended for expert users who need to implement custom chip drivers, but they are **not considered stable API** and may change without notice.
- Step 3: Implement the functions with difference and point to them from the ``spi_flash_chip_t``. Note: if some behavior of your flash is the same as the generic one, retain the generic driver functions without customization. Only implement the parts that differ. Here is an example:
.. important::
docs/en/migration-guides/release-6.x/6.0/peripherals.rst
+21 -2
View File
@@ -310,9 +310,28 @@ SPI Flash Driver
- New argument ``flags`` is added to ``esp_flash_os_functions_t::start``. Caller and implementer should handle this argument properly.
- Kconfig option ``CONFIG_SPI_FLASH_ROM_DRIVER_PATCH`` has been removed. Considering that this option is unlikely to be widely used by users and may cause serious issues if misused, it has been decided to remove it.
.. note::
Header File Reorganization
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note that enabling :ref:`CONFIG_FREERTOS_IN_IRAM` will increase IRAM usage. Consider this trade-off when optimizing for SPI performance.
Several internal header files have been reorganized to better reflect their visibility and intended usage:
- **Flash chip driver related headers** have been moved to ``esp_flash_chips/`` directory:
- ``spi_flash_chip_driver.h``
- ``spi_flash_chip_*.h``
- ``spi_flash_defs.h``
- ``spi_flash_override.h``
- ``esp_flash_types.h``
- The ``esp_flash_t`` structure definition has been moved from ``esp_flash.h`` to ``esp_flash_chips/esp_flash_types.h``. Applications should not access structure members directly; use the public APIs instead (e.g., use :cpp:func:`esp_flash_get_size` instead of accessing ``chip->size`` directly).
- The ``esp_flash_os_functions_t`` structure definition has been moved from ``esp_flash.h`` to ``esp_flash_chips/esp_flash_types.h``.
- The ``spi_flash_chip_t`` type forward declaration has been removed from ``esp_flash.h`` and all ROM headers (``components/esp_rom/esp32xx/include/esp32xx/rom/esp_flash.h``). The type is now only defined in ``esp_flash_chips/esp_flash_types.h``. Applications should not use this type directly; it is only intended for custom chip driver implementations.
.. note::
The headers in ``esp_flash_chips/`` are **semi-public** - they are intended for expert users who need to implement custom chip drivers for unsupported flash chips, but they are **not considered stable API** and may change without notice. For most use cases, you should use the public APIs in ``esp_flash.h`` instead. See :doc:`Override Driver for SPI Flash <../../../api-reference/peripherals/spi_flash/spi_flash_override_driver>` for more details.
- **Internal headers** have been moved to ``esp_private/`` directory and not included in the public (stable) header files:
- ``esp_flash_internal.h``
- ``memspi_host_driver.h``
Touch Element
-------------
docs/zh_CN/api-reference/peripherals/spi_flash/index.rst
+5 -1
View File
@@ -175,6 +175,10 @@ flash 在 {IDF_TARGET_CACHE_SIZE} 页进行映射。内存映射硬件既可将
SPI flash 实现
--------------
.. note::
实现部分的头文件（例如 ``esp_flash_chips/``、``esp_private/``）是**内部**的 - 它们面向需要为不支持的 flash 芯片实现自定义芯片驱动的专家用户，但**不被视为稳定 API**，可能会在不通知的情况下更改。对于大多数用例，您应该使用 ``esp_flash.h`` 中的公共 API。
``esp_flash_t`` 结构体包含芯片数据和该 API 的三个重要部分：
1. 主机驱动，为访问芯片提供硬件支持；
@@ -193,7 +197,7 @@ SPI flash 实现
芯片驱动
^^^^^^^^^^^
芯片驱动在 ``spi_flash_chip_driver.h`` 中进行定义，并将主机驱动提供的基本函数进行封装以供 API 层使用。
芯片驱动在 ``esp_flash_chips/spi_flash_chip_driver.h`` 中进行定义，并将主机驱动提供的基本函数进行封装以供 API 层使用。
有些操作需在执行前先发送命令，或在执行后读取状态，因此有些芯片需要不同的命令或值以及通信方式。
docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst
+6 -1
View File
@@ -149,7 +149,12 @@
应用程序中的 flash 驱动程序用于读取、写入、擦除、保存数据等操作，且支持 OTA 等高级功能。可参考下列指南，为你的 flash 芯片自定义驱动程序。
- 步骤 1：`default_registered_chips` 的最后一项应为 `通用芯片驱动程序 <https://github.com/espressif/esp-idf/blob/master/components/spi_flash/spi_flash_chip_generic.c>`_。如果你的 flash 芯片无法匹配以上列出的任何一个芯片驱动程序，则将使用通用驱动。请检查你的 flash 芯片行为与通用驱动是否存在差异，包括但不限于不同的命令、dummy 周期、数据字节以及状态寄存器。
- 步骤 2：如果你的 flash 芯片行为与通用驱动存在差异，则需要实现自定义的芯片驱动程序。请创建一个名为 ``spi_flash_chip_<vendor>.c`` 的新文件，在其中实现特定行为。可以将 ``esp_flash_chip_generic`` 结构体复制到文件中进行修改。记得在文件中包含 ``spi_flash_chip_generic.h``。详情请参阅示例 `esp_flash_nor <https://github.com/espressif/esp-flash-drivers/tree/main/esp_flash_nor/>`_。
- 步骤 2：如果你的 flash 芯片行为与通用驱动存在差异，则需要实现自定义的芯片驱动程序。请创建一个名为 ``spi_flash_chip_<vendor>.c`` 的新文件，在其中实现特定行为。可以将 ``esp_flash_chip_generic`` 结构体复制到文件中进行修改。记得在文件中包含 ``esp_flash_chips/spi_flash_chip_generic.h``。详情请参阅示例 `esp_flash_nor <https://github.com/espressif/esp-flash-drivers/tree/main/esp_flash_nor/>`_。
.. note::
芯片驱动程序头文件位于 ``esp_flash_chips/`` 目录中（例如 ``components/spi_flash/include/esp_flash_chips/``）。这些头文件是**半公开的** - 它们面向需要实现自定义芯片驱动程序的高级用户，但**不被视为稳定的 API**，可能会在未通知的情况下更改。
- 步骤 3：实现与通用驱动程序存在差异的函数，并从 ``spi_flash_chip_t`` 结构体中指向这些函数。注意：如果 flash 芯片的某些行为与通用驱动相同，那么可以保留通用驱动程序的函数，无需自定义，只要为与通用驱动不同的部分编写自定义函数即可。请参考以下示例：
.. important::
docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst
+21 -2
View File
@@ -310,9 +310,28 @@ SPI flash 驱动
- ``esp_flash_os_functions_t::start`` 新增了一个参数 ``flags``。调用者和实现者应正确处理此参数。
- Kconfig 选项 ``CONFIG_SPI_FLASH_ROM_DRIVER_PATCH`` 已被移除，考虑到这个选项不会被广泛被用户使用，且有因误用而导致出现严重的问题，遂决定移除。
.. note::
头文件重组
~~~~~~~~~~
启用 :ref:`CONFIG_FREERTOS_IN_IRAM` 会显著增加 IRAM 使用量。在优化 SPI 性能时，需进行权衡。
为了更好地反映其可见性和预期用途，多个内部头文件已重新组织：
- **Flash 芯片驱动相关头文件** 已移至 ``esp_flash_chips/`` 目录：
- ``spi_flash_chip_driver.h``
- ``spi_flash_chip_*.h``
- ``spi_flash_defs.h``
- ``spi_flash_override.h``
- ``esp_flash_types.h``
- ``esp_flash_t`` 结构体定义已从 ``esp_flash.h`` 移至 ``esp_flash_chips/esp_flash_types.h``。应用程序不应直接访问结构体成员；请改用公开 API（例如，使用 :cpp:func:`esp_flash_get_size` 而不是直接访问 ``chip->size``）。
- ``esp_flash_os_functions_t`` 结构体定义已从 ``esp_flash.h`` 移至 ``esp_flash_chips/esp_flash_types.h``。
- ``spi_flash_chip_t`` 类型的前向声明已从 ``esp_flash.h`` 和所有 ROM 头文件（``components/esp_rom/esp32xx/include/esp32xx/rom/esp_flash.h``）中移除。该类型现在仅在 ``esp_flash_chips/esp_flash_types.h`` 中定义。应用程序不应直接使用此类型；它仅用于自定义芯片驱动实现。
.. note::
``esp_flash_chips/`` 中的头文件是**半公开的** - 它们面向需要为不支持的 flash 芯片实现自定义芯片驱动的专家用户，但**不被视为稳定 API**，可能会在不通知的情况下更改。对于大多数用例，您应该改用 ``esp_flash.h`` 中的公开 API。更多详情请参阅 :doc:`SPI Flash 驱动覆盖 <../../../api-reference/peripherals/spi_flash/spi_flash_override_driver>`。
- **内部头文件** 已移至 ``esp_private/`` 目录，且不包含在公共（稳定）头文件中：
- ``esp_flash_internal.h``
- ``memspi_host_driver.h``
Touch Element
-------------
examples/storage/.build-test-rules.yml
+4
View File
@@ -3,6 +3,10 @@
examples/storage/custom_flash_driver:
depends_components:
- spi_flash
disable:
- if: 1 == 1
temporary: true
reason: breaking change needs external component to fix first (IDF-15134)
examples/storage/emmc:
depends_components:
examples/storage/custom_flash_driver/components/custom_chip_driver/chip_drivers.c
+7 -7
View File
@@ -12,13 +12,13 @@
CONDITIONS OF ANY KIND, either express or implied.
*/
#include "spi_flash_chip_driver.h"
#include "spi_flash_chip_generic.h"
#include "spi_flash_chip_issi.h"
#include "spi_flash_chip_mxic.h"
#include "spi_flash_chip_gd.h"
#include "spi_flash_chip_winbond.h"
#include "spi_flash_chip_boya.h"
#include "esp_flash_chips/spi_flash_chip_driver.h"
#include "esp_flash_chips/spi_flash_chip_generic.h"
#include "esp_flash_chips/spi_flash_chip_issi.h"
#include "esp_flash_chips/spi_flash_chip_mxic.h"
#include "esp_flash_chips/spi_flash_chip_gd.h"
#include "esp_flash_chips/spi_flash_chip_winbond.h"
#include "esp_flash_chips/spi_flash_chip_boya.h"
// `spi_flash_chip_custom.h` is the header for the structure of customize flash driver,
// in this example is `esp_flash_chip_eon`.
#include "spi_flash_chip_custom.h"
examples/storage/fatfs/ext_flash/main/fatfs_ext_flash_example_main.c
+9 -5
View File
@@ -161,22 +161,26 @@ static esp_flash_t* example_init_ext_flash(void)
// Print out the ID and size
uint32_t id;
uint32_t size;
ESP_ERROR_CHECK(esp_flash_read_id(ext_flash, &id));
ESP_LOGI(TAG, "Initialized external Flash, size=%" PRIu32 " KB, ID=0x%" PRIx32, ext_flash->size / 1024, id);
ESP_ERROR_CHECK(esp_flash_get_size(ext_flash, &size));
ESP_LOGI(TAG, "Initialized external Flash, size=%" PRIu32 " KB, ID=0x%" PRIx32, size / 1024, id);
return ext_flash;
}
static const esp_partition_t* example_add_partition(esp_flash_t* ext_flash, const char* partition_label)
{
ESP_LOGI(TAG, "Adding external Flash as a partition, label=\"%s\", size=%" PRIu32 " KB", partition_label, ext_flash->size / 1024);
uint32_t size;
ESP_ERROR_CHECK(esp_flash_get_size(ext_flash, &size));
ESP_LOGI(TAG, "Adding external Flash as a partition, label=\"%s\", size=%" PRIu32 " KB", partition_label, size / 1024);
const esp_partition_t* fat_partition;
const size_t offset = 0;
ESP_ERROR_CHECK(esp_partition_register_external(ext_flash, offset, ext_flash->size, partition_label, ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, &fat_partition));
ESP_ERROR_CHECK(esp_partition_register_external(ext_flash, offset, size, partition_label, ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, &fat_partition));
// Erase space of partition on the external flash chip
ESP_LOGI(TAG, "Erasing partition range, offset=%u size=%" PRIu32 " KB", offset, ext_flash->size / 1024);
ESP_ERROR_CHECK(esp_partition_erase_range(fat_partition, offset, ext_flash->size));
ESP_LOGI(TAG, "Erasing partition range, offset=%u size=%" PRIu32 " KB", offset, size / 1024);
ESP_ERROR_CHECK(esp_partition_erase_range(fat_partition, offset, size));
return fat_partition;
}
examples/system/ota/partitions_ota/main/partition_utils.c
+7 -2
View File
@@ -10,7 +10,6 @@
#include <stdio.h>
#include <sys/param.h>
#include "esp_flash_partitions.h"
#include "esp_flash_internal.h"
#include "esp_image_format.h"
#include "esp_flash.h"
#include "esp_partition.h"
@@ -103,7 +102,13 @@ esp_err_t partition_utils_find_unallocated(esp_flash_t *flash_chip, size_t requi
// Check for unallocated space after the last partition
last_end_address = MAX(last_end_address, start_offset);
size_t unallocated_size = flash_chip->size - last_end_address;
uint32_t flash_size = 0;
esp_err_t ret = esp_flash_get_size(flash_chip, &flash_size);
if (ret != ESP_OK) {
free(sorted_partitions);
return ret;
}
size_t unallocated_size = flash_size - last_end_address;
if (unallocated_size >= required_size) {
*found_offset = last_end_address;
if (found_size != NULL) {
tools/ci/check_copyright_ignore.txt
-2
View File
@@ -490,8 +490,6 @@ components/soc/esp32s2/include/soc/fe_reg.h
components/soc/esp32s2/include/soc/memprot_defs.h
components/soc/esp32s2/include/soc/nrx_reg.h
components/soc/esp32s2/include/soc/soc_ulp.h
components/spi_flash/spi_flash_chip_boya.c
components/spi_flash/spi_flash_chip_issi.c
components/tcp_transport/include/esp_transport_ws.h
components/wpa_supplicant/esp_supplicant/src/esp_wpa_err.h
components/wpa_supplicant/include/utils/wpa_debug.h
tools/ci/check_public_headers_exceptions.txt
-8
View File
@@ -26,14 +26,6 @@ components/lwip/lwip/src/include/netif/ppp/
components/lwip/lwip/src/include/lwip/apps/tftp_server.h
components/lwip/lwip/src/include/lwip/apps/tftp_client.h
components/spi_flash/include/spi_flash_chip_issi.h
components/spi_flash/include/spi_flash_chip_mxic.h
components/spi_flash/include/spi_flash_chip_gd.h
components/spi_flash/include/spi_flash_chip_winbond.h
components/spi_flash/include/spi_flash_chip_boya.h
components/spi_flash/include/spi_flash_chip_th.h
components/spi_flash/include/memspi_host_driver.h
components/spi_flash/include/spi_flash_chip_generic.h
components/wpa_supplicant/include/
tools/test_apps/system/g1_components/check_dependencies.py
+1 -1
View File
@@ -54,7 +54,7 @@ g1_g0_components = g1_g0_components_base + get_all_esp_hal_components()
# Global expected dependency violations that apply to all targets
expected_dep_violations = {
'esp_system': ['esp_timer', 'bootloader_support', 'esp_pm', 'esp_usb_cdc_rom_console'],
'spi_flash': ['bootloader_support', 'esp_blockdev'],
'spi_flash': ['bootloader_support', 'esp_blockdev', 'esp_driver_gpio'],
'esp_hw_support': ['efuse', 'bootloader_support', 'esp_driver_gpio', 'esp_timer', 'esp_pm'],
'cxx': ['pthread'],
}