mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 19:13:21 +00:00

Files

T

Xiao Xufeng 8dbf23630a refactor(spi_flash): reorganize header files and improve API encapsulation

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

2026-01-23 03:38:54 +08:00

2.2 KiB

Raw Blame History

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 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 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

2.2 KiB Raw Blame History