SPI Flash API¶

概述¶

Spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射相关的 API 函数，同时也提供了更高层级的，面向分区的 API 函数（定义在分区表中）。

与 ESP-IDF V4.0 之前的 API 不同，这一版 esp_flash_* API 功能并不局限于主 SPI Flash 芯片（即运行程序的 SPI Flash 芯片）。使用不同的芯片指针，您可以访问连接到 SPI0/1 或 SPI2 总线的外部 flash 芯片。

注解

大多数 esp_flash_* API 使用 SPI1，SPI2 等外设而非通过 SPI0 上的 cache。这使得它们不仅能访问主 flash，也能访问外部 flash 。

而由于 cache 的限制，所有经过 cache 的操作都只能对主 flash 进行。这些操作的地址同样受到 cache 能力的限制。Cache 无法访问外部 flash 或者高于它能力的地址段。这些 cache 操作包括：mmap ，加密读写，执行代码或者访问在 flash 中的变量。

注解

ESP-IDF V4.0 之后的 flash API 不再是原子的。因此，如果 flash 操作地址有重叠，且写操作与读操作同时执行，读操作可能会返回一部分写入之前的数据和一部分写入之后的数据。

Kconfig 选项 CONFIG_SPI_FLASH_USE_LEGACY_IMPL 可将 spi_flash_* 函数切换至 ESP-IDF V4.0 之前的实现。但是，如果同时使用新旧 API，代码量可能会增多。

即便未启用 CONFIG_SPI_FLASH_USE_LEGACY_IMPL，加密读取和加密写入操作也均使用旧实现。因此，仅有主 flash 芯片支持加密操作，外接（经 SPI1 使用其他不同片选访问，或经其它 SPI 总线访问）的 flash 芯片则不支持加密操作。也仅有主 flash 支持从 cache 当中读取，因为这是由硬件决定的。

Flash 特性支持情况¶

不同厂家的 flash 特性有不同的操作方式，因此需要特殊的驱动支持。当前驱动支持大多数厂家 Flash 24 位地址范围内的快速/慢速读，以及二线模式 (DIO / DOUT)，因为他们不需要任何厂家的自定义命令。

当前驱动支持以下厂家/型号的 flash 的四线模式 (QIO/QOUT)：

ISSI
GD
MXIC
FM
Winbond
XMC
BOYA

当前驱动支持以下厂家/型号的 flash 的 32 位地址范围的访问：

W25Q256
GD25Q256

如果有需要，也可以自定义 flash 芯片驱动，参见 Overriding Default Chip Drivers 。

初始化 Flash 设备¶

在使用 esp_flash_* API 之前，您需要在 SPI 总线上初始化芯片。

调用 spi_bus_initialize() 初始化 SPI 总线，此函数将初始化总线上设备间共享的资源，如 I/O、DMA 及中断等。
调用 spi_bus_add_flash_device() 将 flash 设备连接到总线上。然后分配内存，填充 esp_flash_t 结构体，同时初始化 CS I/O。
调用 esp_flash_init() 与芯片进行通信。后续操作会依据芯片类型不同而有差异。

注解

当前，多个 flash 芯片可连接到同一总线。但尚不支持在同一个 SPI 总线上使用 esp_flash_* 和 spi_device_* 设备。

SPI Flash 访问 API¶

如下所示为处理 flash 中数据的函数集：

esp_flash_read()：将数据从 flash 读取到 RAM；
esp_flash_write()：将数据从 RAM 写入到 flash；
esp_flash_erase_region()：擦除 flash 中指定区域的数据；
esp_flash_erase_chip()：擦除整个 flash；
esp_flash_get_chip_size()：返回 menuconfig 中设置的 flash 芯片容量（以字节为单位）。

一般来说，请尽量避免对主 SPI flash 芯片直接使用原始 SPI flash 函数，如需对主 SPI flash 芯片进行操作，请使用分区专用函数。

SPI Flash 容量¶

SPI flash 容量存储于引导程序映像头部（烧录偏移量为 0x1000）的一个字段。

默认情况下，引导程序写入 flash 时，esptool.py 将引导程序写入 flash 时，会自动检测 SPI flash 容量，同时使用正确容量更新引导程序的头部。您也可以在工程配置中设置 CONFIG_ESPTOOLPY_FLASHSIZE，生成固定的 flash 容量。

如需在运行时覆盖已配置的 flash 容量，请配置 g_rom_flashchip 结构中的 chip_size。esp_flash_* 函数使用此容量（于软件和 ROM 中）进行边界检查。

SPI1 Flash 并发约束¶

注意

指令/数据 cache（用以执行固件）与 SPI1 外设（由像 SPI flash 驱动一样的驱动程序控制）共享 SPI0/1 总线。因此，在 SPI1 总线上调用 SPI Flash API（包括访问主 flash）会对整个系统造成显著的影响。更多细节，参见 SPI1 Flash 并发约束。

分区表 API¶

ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导程序、各种应用程序二进制文件、数据及文件系统等。请参考 here，查看详细信息。

该组件在 esp_partition.h 中声明了一些 API 函数，用以枚举在分区表中找到的分区，并对这些分区执行操作：

esp_partition_find()：在分区表中查找特定类型的条目，返回一个不透明迭代器；
esp_partition_get()：返回一个结构，描述给定迭代器的分区；
esp_partition_next()：将迭代器移至下一个找到的分区；
esp_partition_iterator_release()：释放 esp_partition_find 中返回的迭代器；
esp_partition_find_first()：返回描述 esp_partition_find 中找到的第一个分区的结构；
esp_partition_read()、esp_partition_write() 和 esp_partition_erase_range() 等同于 spi_flash_read()、spi_flash_write() 和 spi_flash_erase_range()，但在分区边界内执行。

注解

请在应用程序代码中使用上述 esp_partition_* API 函数，而非低层级的 esp_flash_* API 函数。分区表 API 函数根据存储在分区表中的数据，进行边界检查并计算在 flash 中的正确偏移量。

SPI Flash 加密¶

您可以对 SPI flash 内容进行加密，并在硬件层对其进行透明解密。

请参阅 Flash 加密文档，查看详细信息。

内存映射 API¶

ESP32 内存硬件可以将 flash 部分区域映射到指令地址空间和数据地址空间，此映射仅用于读操作。不能通过写入 flash 映射的存储区域来改变 flash 中的内容。

Flash 在 64 KB 页进行映射。内存映射硬件既可将 flash 映射到数据地址空间，也能映射到指令地址空间。请查看技术参考手册，了解内存映射硬件的详细信息及有关限制。

请注意，有些页被用于将应用程序映射到内存中，因此实际可用的页会少于硬件提供的总数。

启用 Flash 加密时，使用内存映射区域从 flash 读取数据是解密 flash 的唯一方法，解密需在硬件层进行。

内存映射 API 在 esp_spi_flash.h 和 esp_partition.h 中声明：

spi_flash_mmap()：将 flash 物理地址区域映射到 CPU 指令空间或数据空间；
spi_flash_munmap()：取消上述区域的映射；
esp_partition_mmap()：将分区的一部分映射至 CPU 指令空间或数据空间；

spi_flash_mmap() 和 esp_partition_mmap() 的区别如下：

spi_flash_mmap()：需要给定一个 64 KB 对齐的物理地址；
esp_partition_mmap()：给定分区内任意偏移量即可，此函数根据需要将返回的指针调整至指向映射内存。

内存映射以页为单位，即使传递给 esp_partition_mmap 的是一个分区，分区外的数据也是也是可以被读取到的，不会受到分区边界的影响。

注解

由于 mmap 是由 cache 支持的，因此，mmap 也仅能用在主 flash 上。

SPI Flash 实现¶

esp_flash_t 结构包含芯片数据和该 API 的三个重要部分：

主机驱动，为访问芯片提供硬件支持；
芯片驱动，为不同芯片提供兼容性服务；
OS 函数，在不同阶段（一级或二级 Boot 或者应用程序阶段）为部分 OS 函数（如锁、延迟）提供支持。

主机驱动¶

主机驱动依赖 hal/include/hal 文件夹下 spi_flash_types.h 定义的 spi_flash_host_driver_t 接口。该接口提供了一些常用的函数，用于与芯片通信。

在 SPI HAL 文件中，有些函数是基于现有的 ESP32 memory-spi 来实现的。但是，由于 ESP32 的速度限制，HAL 层无法提供某些读命令的高速实现（所以这些命令根本没有在 HAL 的文件中被实现）。memspi_host_driver.h 和 .c 文件使用 HAL 提供的 common_command 函数实现上述读命令的高速版本，并将所有它实现的以及 HAL 函数封装为 spi_flash_host_driver_t 供更上层调用。

您甚至可以仅通过 GPIO 来实现自己的主机驱动。只要实现了 spi_flash_host_driver_t 中所有函数，不管底层硬件是什么，esp_flash API 都可以访问 flash。

芯片驱动¶

芯片驱动在 spi_flash_chip_driver.h 中进行定义，并将主机驱动提供的基本函数进行封装以供 API 层使用。

有些操作需在执行前先发送命令，或在执行后读取状态，因此有些芯片需要不同的命令或值以及通信方式。

generic chip 芯片代表了常见的 flash 芯片，其他芯片驱动可以在这种通用芯片的基础上进行开发。

芯片驱动依赖主机驱动。

OS 函数¶

OS 函数层目前提供访问锁和延迟的方法。

锁（见 SPI Bus Lock）用于解决同一 SPI 总线上的设备访问和 SPI Flash 芯片访问之间的冲突。例如：

经 SPI1 总线访问 flash 芯片时，应当禁用 cache（平时用于取代码和 PSRAM 数据）。
经其他总线访问 flash 芯片时，应当禁用 flash 上 SPI 主驱动器注册的 ISR 以避免冲突。
SPI 主驱动器上某些没有 CS 线或者 CS 线受软件（如 SDSPI）控制的设备需要在一段时间内独占总线。

延时则用于某些长时操作，需要主机处于等待状态或执行轮询。

顶层 API 将芯片驱动和 OS 函数封装成一个完整的组件，并提供参数检查。

另请参考¶

分区表
OTA API 提供了高层 API 用于更新存储在 flash 中的 app 固件。
NVS API 提供了结构化 API 用于存储 SPI flash 中的碎片数据。

实现细节¶

必须确保操作期间，两个 CPU 均未从 flash 运行代码，实现细节如下： - 单核模式下，SDK 在执行 flash 操作前将禁用中断或调度算法。 - 双核模式下，实现细节较为复杂，SDK 需确保两个 CPU 均未运行 flash 代码。

如果有 SPI flash API 在 CPU A（PRO 或 APP）上调用，它使用 esp_ipc_call API 在 CPU B 上运行 spi_flash_op_block_func 函数。esp_ipc_call API 会在 CPU B 上唤醒一个高优先级任务，即运行 spi_flash_op_block_func 函数。运行该函数将禁用 CPU B 上的 cache，并使用 s_flash_op_can_start 旗帜来标志 cache 已禁用。然后，CPU A 上的任务也会禁用 cache 并继续执行 flash 操作。

执行 flash 操作时，CPU A 和 CPU B 仍然可以执行中断操作。默认中断代码均存储于 RAM 中，如果新添加了中断分配 API，则应添加一个标志位以请求在 flash 操作期间禁用该新分配的中断。

Flash 操作完成后，CPU A 上的函数将设置另一标志位，即 s_flash_op_complete，用以通知 CPU B 上的任务可以重新启用 cache 并释放 CPU。接着，CPU A 上的函数也重新启用 cache，并将控制权返还给调用者。

另外，所有 API 函数均受互斥量 s_flash_op_mutex 保护。

在单核环境中（启用 CONFIG_FREERTOS_UNICORE），您需要禁用上述两个 cache 以防发生 CPU 间通信。

SPI Flash API 参考¶

Header File¶

components/spi_flash/include/esp_flash_spi_init.h

Functions¶

esp_err_t spi_bus_add_flash_device(esp_flash_t **out_chip, const esp_flash_spi_device_config_t *config)¶

Add a SPI Flash device onto the SPI bus.

The bus should be already initialized by spi_bus_initialization.

Return

ESP_ERR_INVALID_ARG: out_chip is NULL, or some field in the config is invalid.
ESP_ERR_NO_MEM: failed to allocate memory for the chip structures.
ESP_OK: success.

Parameters

out_chip: Pointer to hold the initialized chip.
config: Configuration of the chips to initialize.

esp_err_t spi_bus_remove_flash_device(esp_flash_t *chip)¶

Remove a SPI Flash device from the SPI bus.

Return

ESP_ERR_INVALID_ARG: The chip is invalid.
ESP_OK: success.

Parameters

chip: The flash device to remove.

Structures¶

struct esp_flash_spi_device_config_t¶

Configurations for the SPI Flash to init.

Public Members

spi_host_device_t host_id¶: Bus to use.

int cs_io_num¶: GPIO pin to output the CS signal.

esp_flash_io_mode_t io_mode¶: IO mode to read from the Flash.

esp_flash_speed_t speed¶: Speed of the Flash clock.

int input_delay_ns¶: Input delay of the data pins, in ns. Set to 0 if unknown.

int cs_id¶: CS line ID, ignored when not host_id is not SPI1_HOST, or CONFIG_SPI_FLASH_SHARE_SPI1_BUS is enabled. In this case, the CS line used is automatically assigned by the SPI bus lock.

Header File¶

components/spi_flash/include/esp_flash.h

Functions¶

esp_err_t esp_flash_init(esp_flash_t *chip)¶

Initialise SPI flash chip interface.

This function must be called before any other API functions are called for this chip.

Note

Only the host and read_mode fields of the chip structure must be initialised before this function is called. Other fields may be auto-detected if left set to zero or NULL.

Note

If the chip->drv pointer is NULL, chip chip_drv will be auto-detected based on its manufacturer & product IDs. See esp_flash_registered_flash_drivers pointer for details of this process.

Return

ESP_OK on success, or a flash error code if initialisation fails.

Parameters

chip: Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.

bool esp_flash_chip_driver_initialized(const esp_flash_t *chip)¶

Check if appropriate chip driver is set.

Return

true if set, otherwise false.

Parameters

chip: Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.

esp_err_t esp_flash_read_id(esp_flash_t *chip, uint32_t *out_id)¶

Read flash ID via the common “RDID” SPI flash command.

ID is a 24-bit value. Lower 16 bits of ‘id’ are the chip ID, upper 8 bits are the manufacturer ID.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
[out] out_id: Pointer to receive ID value.

Return: ESP_OK on success, or a flash error code if operation failed.

esp_err_t esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size)¶

Detect flash size based on flash ID.

Note

Most flash chips use a common format for flash ID, where the lower 4 bits specify the size as a power of 2. If the manufacturer doesn’t follow this convention, the size may be incorrectly detected.

Return

ESP_OK on success, or a flash error code if operation failed.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
[out] out_size: Detected size in bytes.

esp_err_t esp_flash_read_unique_chip_id(esp_flash_t *chip, uint64_t *out_id)¶

Read flash unique ID via the common “RDUID” SPI flash command.

ID is a 64-bit value.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init().
[out] out_id: Pointer to receive unique ID value.

Return

ESP_OK on success, or a flash error code if operation failed.
ESP_ERR_NOT_SUPPORTED if the chip doesn’t support read id.

esp_err_t esp_flash_erase_chip(esp_flash_t *chip)¶

Erase flash chip contents.

Return

ESP_OK on success,
ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent.
Other flash error code if operation failed.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()

esp_err_t esp_flash_erase_region(esp_flash_t *chip, uint32_t start, uint32_t len)¶

Erase a region of the flash chip.

Sector size is specifyed in chip->drv->sector_size field (typically 4096 bytes.) ESP_ERR_INVALID_ARG will be returned if the start & length are not a multiple of this size.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
start: Address to start erasing flash. Must be sector aligned.
len: Length of region to erase. Must also be sector aligned.

Erase is performed using block (multi-sector) erases where possible (block size is specified in chip->drv->block_erase_size field, typically 65536 bytes). Remaining sectors are erased using individual sector erase commands.

Return

ESP_OK on success,
ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent.
Other flash error code if operation failed.

esp_err_t esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *write_protected)¶

Read if the entire chip is write protected.

Note

A correct result for this flag depends on the SPI flash chip model and chip_drv in use (via the ‘chip->drv’ field).

Return

ESP_OK on success, or a flash error code if operation failed.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
[out] write_protected: Pointer to boolean, set to the value of the write protect flag.

esp_err_t esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect)¶

Set write protection for the SPI flash chip.

Some SPI flash chips may require a power cycle before write protect status can be cleared. Otherwise, write protection can be removed via a follow-up call to this function.

Note

Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the ‘chip->drv’ field).

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
write_protect: Boolean value for the write protect flag

Return: ESP_OK on success, or a flash error code if operation failed.

esp_err_t esp_flash_get_protectable_regions(const esp_flash_t *chip, const esp_flash_region_t **out_regions, uint32_t *out_num_regions)¶

Read the list of individually protectable regions of this SPI flash chip.

Note

Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the ‘chip->drv’ field).

Return

ESP_OK on success, or a flash error code if operation failed.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
[out] out_regions: Pointer to receive a pointer to the array of protectable regions of the chip.
[out] out_num_regions: Pointer to an integer receiving the count of protectable regions in the array returned in ‘regions’.

esp_err_t esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool *out_protected)¶

Detect if a region of the SPI flash chip is protected.

Note

It is possible for this result to be false and write operations to still fail, if protection is enabled for the entire chip.

Note

Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the ‘chip->drv’ field).

Return

ESP_OK on success, or a flash error code if operation failed.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
region: Pointer to a struct describing a protected region. This must match one of the regions returned from esp_flash_get_protectable_regions(…).
[out] out_protected: Pointer to a flag which is set based on the protected status for this region.

esp_err_t esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool protect)¶

Update the protected status for a region of the SPI flash chip.

Note

It is possible for the region protection flag to be cleared and write operations to still fail, if protection is enabled for the entire chip.

Note

Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the ‘chip->drv’ field).

Return

ESP_OK on success, or a flash error code if operation failed.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
region: Pointer to a struct describing a protected region. This must match one of the regions returned from esp_flash_get_protectable_regions(…).
protect: Write protection flag to set.

esp_err_t esp_flash_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length)¶

Read data from the SPI flash chip.

There are no alignment constraints on buffer, address or length.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
buffer: Pointer to a buffer where the data will be read. To get better performance, this should be in the DRAM and word aligned.
address: Address on flash to read from. Must be less than chip->size field.
length: Length (in bytes) of data to read.

Note

If on-chip flash encryption is used, this function returns raw (ie encrypted) data. Use the flash cache to transparently decrypt data.

Return

ESP_OK: success
ESP_ERR_NO_MEM: Buffer is in external PSRAM which cannot be concurrently accessed, and a temporary internal buffer could not be allocated.
or a flash error code if operation failed.

esp_err_t esp_flash_write(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length)¶

Write data to the SPI flash chip.

There are no alignment constraints on buffer, address or length.

Parameters

chip: Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
address: Address on flash to write to. Must be previously erased (SPI NOR flash can only write bits 1->0).
buffer: Pointer to a buffer with the data to write. To get better performance, this should be in the DRAM and word aligned.
length: Length (in bytes) of data to write.

Return

ESP_OK on success,
ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent.
Other flash error code if operation failed.

esp_err_t esp_flash_write_encrypted(esp_flash_t *chip, uint32_t address, const void *buffer, uint32_t length)¶

Encrypted and write data to the SPI flash chip using on-chip hardware flash encryption.

Note

Both address & length must be 16 byte aligned, as this is the encryption block size

Return

ESP_OK: on success
ESP_ERR_NOT_SUPPORTED: encrypted write not supported for this chip.
ESP_ERR_INVALID_ARG: Either the address, buffer or length is invalid.
or other flash error code from spi_flash_write_encrypted().

Parameters

chip: Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, encrypted write is not supported.
address: Address on flash to write to. 16 byte aligned. Must be previously erased (SPI NOR flash can only write bits 1->0).
buffer: Pointer to a buffer with the data to write.
length: Length (in bytes) of data to write. 16 byte aligned.

esp_err_t esp_flash_read_encrypted(esp_flash_t *chip, uint32_t address, void *out_buffer, uint32_t length)¶

Read and decrypt data from the SPI flash chip using on-chip hardware flash encryption.

Return

ESP_OK: on success
ESP_ERR_NOT_SUPPORTED: encrypted read not supported for this chip.
or other flash error code from spi_flash_read_encrypted().

Parameters

chip: Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, encrypted read is not supported.
address: Address on flash to read from.
out_buffer: Pointer to a buffer for the data to read to.
length: Length (in bytes) of data to read.

static bool esp_flash_is_quad_mode(const esp_flash_t *chip)¶

Returns true if chip is configured for Quad I/O or Quad Fast Read.

Return

true if flash works in quad mode, otherwise false

Parameters

chip: Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.

Structures¶

struct esp_flash_region_t¶

Structure for describing a region of flash.

Public Members

uint32_t offset¶: Start address of this region.

uint32_t size¶: Size of the region.

struct esp_flash_os_functions_t¶

OS-level integration hooks for accessing flash chips inside a running OS.

It’s in the public header because some instances should be allocated statically in the startup code. May be updated according to hardware version and new flash chip feature requirements, shouldn’t be treated as public API.

For advanced developers, you may replace some of them with your implementations at your own risk.

Public Members

esp_err_t (*start)(void *arg)¶: Called before commencing any flash operation. Does not need to be recursive (ie is called at most once for each call to ‘end’).

esp_err_t (*end)(void *arg)¶: Called after completing any flash operation.

esp_err_t (*region_protected)(void *arg, size_t start_addr, size_t size)¶: Called before any erase/write operations to check whether the region is limited by the OS

esp_err_t (*delay_us)(void *arg, uint32_t us)¶: Delay for at least ‘us’ microseconds. Called in between ‘start’ and ‘end’.

void *(*get_temp_buffer)(void *arg, size_t reqest_size, size_t *out_size)¶: Called for get temp buffer when buffer from application cannot be directly read into/write from.

void (*release_temp_buffer)(void *arg, void *temp_buf)¶: Called for release temp buffer.

esp_err_t (*check_yield)(void *arg, uint32_t chip_status, uint32_t *out_request)¶

Yield to other tasks. Called during erase operations.

Return: ESP_OK means yield needs to be called (got an event to handle), while ESP_ERR_TIMEOUT means skip yield.

esp_err_t (*yield)(void *arg, uint32_t *out_status)¶: Yield to other tasks. Called during erase operations.

int64_t (*get_system_time)(void *arg)¶: Called for get system time.

struct esp_flash_t¶

Structure to describe a SPI flash chip connected to the system.

Structure must be initialized before use (passed to esp_flash_init()). It’s in the public header because some instances should be allocated statically in the startup code. May be updated according to hardware version and new flash chip feature requirements, shouldn’t be treated as public API.

For advanced developers, you may replace some of them with your implementations at your own risk.

Public Members

spi_flash_host_inst_t *host¶: Pointer to hardware-specific “host_driver” structure. Must be initialized before used.

const spi_flash_chip_t *chip_drv¶: Pointer to chip-model-specific “adapter” structure. If NULL, will be detected during initialisation.

const esp_flash_os_functions_t *os_func¶: Pointer to os-specific hook structure. Call esp_flash_init_os_functions() to setup this field, after the host is properly initialized.

void *os_func_data¶: Pointer to argument for os-specific hooks. Left NULL and will be initialized with os_func.

esp_flash_io_mode_t read_mode¶: Configured SPI flash read mode. Set before esp_flash_init is called.

uint32_t size¶: Size of SPI flash in bytes. If 0, size will be detected during initialisation.

uint32_t chip_id¶: Detected chip id.

uint32_t busy : 1¶: This flag is used to verify chip’s status.

uint32_t reserved_flags : 31¶: reserved.

Macros¶

SPI_FLASH_YIELD_REQ_YIELD¶

SPI_FLASH_YIELD_REQ_SUSPEND¶

SPI_FLASH_YIELD_STA_RESUME¶

Type Definitions¶

typedef struct spi_flash_chip_t spi_flash_chip_t¶

typedef struct esp_flash_t esp_flash_t

Header File¶

components/hal/include/hal/spi_flash_types.h

Structures¶

struct spi_flash_trans_t¶

Definition of a common transaction. Also holds the return value.

Public Members

uint8_t reserved¶: Reserved, must be 0.

uint8_t mosi_len¶: Output data length, in bytes.

uint8_t miso_len¶: Input data length, in bytes.

uint8_t address_bitlen¶: Length of address in bits, set to 0 if command does not need an address.

uint32_t address¶: Address to perform operation on.

const uint8_t *mosi_data¶: Output data to salve.

uint8_t *miso_data¶: [out] Input data from slave, little endian

uint32_t flags¶: Flags for this transaction. Set to 0 for now.

uint16_t command¶: Command to send.

uint8_t dummy_bitlen¶: Basic dummy bits to use.

uint32_t io_mode¶: Flash working mode when SPI_FLASH_IGNORE_BASEIO is specified.

struct spi_flash_sus_cmd_conf¶

Configuration structure for the flash chip suspend feature.

Public Members

uint32_t sus_mask¶: SUS/SUS1/SUS2 bit in flash register.

uint32_t cmd_rdsr : 8¶: Read flash status register(2) command.

uint32_t sus_cmd : 8¶: Flash suspend command.

uint32_t res_cmd : 8¶: Flash resume command.

uint32_t reserved : 8¶: Reserved, set to 0.

struct spi_flash_encryption_t¶

Structure for flash encryption operations.

Public Members

void (*flash_encryption_enable)(void)¶: Enable the flash encryption.

void (*flash_encryption_disable)(void)¶: Disable the flash encryption.

void (*flash_encryption_data_prepare)(uint32_t address, const uint32_t *buffer, uint32_t size)¶

Prepare flash encryption before operation.

Note

address and buffer must be 8-word aligned.

Parameters

address: The destination address in flash for the write operation.
buffer: Data for programming
size: Size to program.

void (*flash_encryption_done)(void)¶: flash data encryption operation is done.

void (*flash_encryption_destroy)(void)¶: Destroy encrypted result

bool (*flash_encryption_check)(uint32_t address, uint32_t length)¶

Check if is qualified to encrypt the buffer

Parameters

address: the address of written flash partition.
length: Buffer size.

struct spi_flash_host_inst_t¶

SPI Flash Host driver instance

Public Members

const struct spi_flash_host_driver_s *driver¶: Pointer to the implementation function table.

struct spi_flash_host_driver_s¶

Host driver configuration and context structure.

Public Members

esp_err_t (*dev_config)(spi_flash_host_inst_t *host)¶: Configure the device-related register before transactions. This saves some time to re-configure those registers when we send continuously

esp_err_t (*common_command)(spi_flash_host_inst_t *host, spi_flash_trans_t *t)¶: Send an user-defined spi transaction to the device.

esp_err_t (*read_id)(spi_flash_host_inst_t *host, uint32_t *id)¶: Read flash ID.

void (*erase_chip)(spi_flash_host_inst_t *host)¶: Erase whole flash chip.

void (*erase_sector)(spi_flash_host_inst_t *host, uint32_t start_address)¶: Erase a specific sector by its start address.

void (*erase_block)(spi_flash_host_inst_t *host, uint32_t start_address)¶: Erase a specific block by its start address.

esp_err_t (*read_status)(spi_flash_host_inst_t *host, uint8_t *out_sr)¶: Read the status of the flash chip.

esp_err_t (*set_write_protect)(spi_flash_host_inst_t *host, bool wp)¶: Disable write protection.

void (*program_page)(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length)¶: Program a page of the flash. Check max_write_bytes for the maximum allowed writing length.

bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p)¶: Check whether given buffer can be directly used to write

int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size)¶

Slicer for write data. The program_page should be called iteratively with the return value of this function.

Return

Length that can be actually written in one program_page call

Parameters

address: Beginning flash address to write
len: Length request to write
align_addr: Output of the aligned address to write to
page_size: Physical page size of the flash chip

esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len)¶: Read data from the flash. Check max_read_bytes for the maximum allowed reading length.

bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p)¶: Check whether given buffer can be directly used to read

int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size)¶

Slicer for read data. The read should be called iteratively with the return value of this function.

Return

Length that can be actually read in one read call

Parameters

address: Beginning flash address to read
len: Length request to read
align_addr: Output of the aligned address to read
page_size: Physical page size of the flash chip

uint32_t (*host_status)(spi_flash_host_inst_t *host)¶: Check the host status, 0:busy, 1:idle, 2:suspended.

esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command, uint32_t addr_bitlen, int dummy_bitlen_base, esp_flash_io_mode_t io_mode)¶: Configure the host to work at different read mode. Responsible to compensate the timing and set IO mode.

void (*poll_cmd_done)(spi_flash_host_inst_t *host)¶: Internal use, poll the HW until the last operation is done.

esp_err_t (*flush_cache)(spi_flash_host_inst_t *host, uint32_t addr, uint32_t size)¶: For some host (SPI1), they are shared with a cache. When the data is modified, the cache needs to be flushed. Left NULL if not supported.

void (*check_suspend)(spi_flash_host_inst_t *host)¶: Suspend check erase/program operation, reserved for ESP32-C3 and ESP32-S3 spi flash ROM IMPL.

void (*resume)(spi_flash_host_inst_t *host)¶: Resume flash from suspend manually

void (*suspend)(spi_flash_host_inst_t *host)¶: Set flash in suspend status manually

esp_err_t (*sus_setup)(spi_flash_host_inst_t *host, const spi_flash_sus_cmd_conf *sus_conf)¶: Suspend feature setup for setting cmd and status register mask.

Macros¶

SPI_FLASH_TRANS_FLAG_CMD16¶: Send command of 16 bits.

SPI_FLASH_TRANS_FLAG_IGNORE_BASEIO¶: Not applying the basic io mode configuration for this transaction.

SPI_FLASH_TRANS_FLAG_BYTE_SWAP¶: Used for DTR mode, to swap the bytes of a pair of rising/falling edge.

ESP_FLASH_SPEED_MIN¶: Lowest speed supported by the driver, currently 5 MHz.

SPI_FLASH_CONFIG_CONF_BITS¶: OR the io_mode with this mask, to enable the dummy output feature or replace the first several dummy bits into address to meet the requirements of conf bits. (Used in DIO/QIO/OIO mode)

SPI_FLASH_OPI_FLAG¶: A flag for flash work in opi mode, the io mode below are opi, above are SPI/QSPI mode. DO NOT use this value in any API.

SPI_FLASH_READ_MODE_MIN¶: Slowest io mode supported by ESP32, currently SlowRd.

Type Definitions¶

typedef struct spi_flash_host_driver_s spi_flash_host_driver_t¶

Enumerations¶

enum esp_flash_speed_t¶

SPI flash clock speed values, always refer to them by the enum rather than the actual value (more speed may be appended into the list).

A strategy to select the maximum allowed speed is to enumerate from the ESP_FLSH_SPEED_MAX-1 or highest frequency supported by your flash, and decrease the speed until the probing success.

Values:

ESP_FLASH_5MHZ = 0¶: The flash runs under 5MHz.

ESP_FLASH_10MHZ¶: The flash runs under 10MHz.

ESP_FLASH_20MHZ¶: The flash runs under 20MHz.

ESP_FLASH_26MHZ¶: The flash runs under 26MHz.

ESP_FLASH_40MHZ¶: The flash runs under 40MHz.

ESP_FLASH_80MHZ¶: The flash runs under 80MHz.

ESP_FLASH_120MHZ¶: The flash runs under 120MHz, 120MHZ can only be used by main flash after timing tuning in system. Do not use this directely in any API.

ESP_FLASH_SPEED_MAX¶: The maximum frequency supported by the host is ESP_FLASH_SPEED_MAX-1.

enum esp_flash_io_mode_t¶

Mode used for reading from SPI flash.

Values:

SPI_FLASH_SLOWRD = 0¶: Data read using single I/O, some limits on speed.

SPI_FLASH_FASTRD¶: Data read using single I/O, no limit on speed.

SPI_FLASH_DOUT¶: Data read using dual I/O.

SPI_FLASH_DIO¶: Both address & data transferred using dual I/O.

SPI_FLASH_QOUT¶: Data read using quad I/O.

SPI_FLASH_QIO¶: Both address & data transferred using quad I/O.

SPI_FLASH_OPI_STR = SPI_FLASH_OPI_FLAG¶: Only support on OPI flash, flash read and write under STR mode.

SPI_FLASH_OPI_DTR¶: Only support on OPI flash, flash read and write under DTR mode.

SPI_FLASH_READ_MODE_MAX¶: The fastest io mode supported by the host is ESP_FLASH_READ_MODE_MAX-1.

分区表 API 参考¶

Header File¶

components/spi_flash/include/esp_partition.h

Functions¶

esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label)¶

Find partition based on one or more parameters.

Return

iterator which can be used to enumerate all the partitions found, or NULL if no partitions were found. Iterator obtained through this function has to be released using esp_partition_iterator_release when not used any more.

Parameters

type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.
subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer. To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

const esp_partition_t *esp_partition_find_first(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label)¶

Find first partition based on one or more parameters.

Return

pointer to esp_partition_t structure, or NULL if no partition is found. This pointer is valid for the lifetime of the application.

Parameters

type: Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer. To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set subtype argument to ESP_PARTITION_SUBTYPE_ANY.
subtype: Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
label: (optional) Partition label. Set this value if looking for partition with a specific name. Pass NULL otherwise.

const esp_partition_t *esp_partition_get(esp_partition_iterator_t iterator)¶

Get esp_partition_t structure for given partition.

Return

pointer to esp_partition_t structure. This pointer is valid for the lifetime of the application.

Parameters

iterator: Iterator obtained using esp_partition_find. Must be non-NULL.

esp_partition_iterator_t esp_partition_next(esp_partition_iterator_t iterator)¶

Move partition iterator to the next partition found.

Any copies of the iterator will be invalid after this call.

Return

NULL if no partition was found, valid esp_partition_iterator_t otherwise.

Parameters

iterator: Iterator obtained using esp_partition_find. Must be non-NULL.

void esp_partition_iterator_release(esp_partition_iterator_t iterator)¶

Release partition iterator.

Parameters

iterator: Iterator obtained using esp_partition_find. The iterator is allowed to be NULL, so it is not necessary to check its value before calling this function.

const esp_partition_t *esp_partition_verify(const esp_partition_t *partition)¶

Verify partition data.

Given a pointer to partition data, verify this partition exists in the partition table (all fields match.)

This function is also useful to take partition data which may be in a RAM buffer and convert it to a pointer to the permanent partition data stored in flash.

Pointers returned from this function can be compared directly to the address of any pointer returned from esp_partition_get(), as a test for equality.

Return

If partition not found, returns NULL.
If found, returns a pointer to the esp_partition_t structure in flash. This pointer is always valid for the lifetime of the application.

Parameters

partition: Pointer to partition data to verify. Must be non-NULL. All fields of this structure must match the partition table entry in flash for this function to return a successful match.

esp_err_t esp_partition_read(const esp_partition_t *partition, size_t src_offset, void *dst, size_t size)¶

Read data from the partition.

Partitions marked with an encryption flag will automatically be be read and decrypted via a cache mapping.

Return

ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes from lower-level flash driver.

Parameters

partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
dst: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least ‘size’ bytes long.
src_offset: Address of the data to be read, relative to the beginning of the partition.
size: Size of data to be read, in bytes.

esp_err_t esp_partition_write(const esp_partition_t *partition, size_t dst_offset, const void *src, size_t size)¶

Write data to the partition.

Before writing data to flash, corresponding region of flash needs to be erased. This can be done using esp_partition_erase_range function.

Partitions marked with an encryption flag will automatically be written via the spi_flash_write_encrypted() function. If writing to an encrypted partition, all write offsets and lengths must be multiples of 16 bytes. See the spi_flash_write_encrypted() function for more details. Unencrypted partitions do not have this restriction.

Note

Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call.

Return

ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; or one of error codes from lower-level flash driver.

Parameters

partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
dst_offset: Address where the data should be written, relative to the beginning of the partition.
src: Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least ‘size’ bytes long.
size: Size of data to be written, in bytes.

esp_err_t esp_partition_read_raw(const esp_partition_t *partition, size_t src_offset, void *dst, size_t size)¶

Read data from the partition without any transformation/decryption.

Note

This function is essentially the same as esp_partition_read() above. It just never decrypts data but returns it as is.

Return

ESP_OK, if data was read successfully; ESP_ERR_INVALID_ARG, if src_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if read would go out of bounds of the partition; or one of error codes from lower-level flash driver.

Parameters

partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
dst: Pointer to the buffer where data should be stored. Pointer must be non-NULL and buffer must be at least ‘size’ bytes long.
src_offset: Address of the data to be read, relative to the beginning of the partition.
size: Size of data to be read, in bytes.

esp_err_t esp_partition_write_raw(const esp_partition_t *partition, size_t dst_offset, const void *src, size_t size)¶

Write data to the partition without any transformation/encryption.

Before writing data to flash, corresponding region of flash needs to be erased. This can be done using esp_partition_erase_range function.

Note: This function is essentially the same as esp_partition_write() above. It just never encrypts data but writes it as is.

Note

Prior to writing to flash memory, make sure it has been erased with esp_partition_erase_range call.

Return

ESP_OK, if data was written successfully; ESP_ERR_INVALID_ARG, if dst_offset exceeds partition size; ESP_ERR_INVALID_SIZE, if write would go out of bounds of the partition; or one of the error codes from lower-level flash driver.

Parameters

partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
dst_offset: Address where the data should be written, relative to the beginning of the partition.
src: Pointer to the source buffer. Pointer must be non-NULL and buffer must be at least ‘size’ bytes long.
size: Size of data to be written, in bytes.

esp_err_t esp_partition_erase_range(const esp_partition_t *partition, size_t offset, size_t size)¶

Erase part of the partition.

Return

ESP_OK, if the range was erased successfully; ESP_ERR_INVALID_ARG, if iterator or dst are NULL; ESP_ERR_INVALID_SIZE, if erase would go out of bounds of the partition; or one of error codes from lower-level flash driver.

Parameters

partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
offset: Offset from the beginning of partition where erase operation should start. Must be aligned to 4 kilobytes.
size: Size of the range which should be erased, in bytes. Must be divisible by 4 kilobytes.

esp_err_t esp_partition_mmap(const esp_partition_t *partition, size_t offset, size_t size, spi_flash_mmap_memory_t memory, const void **out_ptr, spi_flash_mmap_handle_t *out_handle)¶

Configure MMU to map partition into data memory.

Unlike spi_flash_mmap function, which requires a 64kB aligned base address, this function doesn’t impose such a requirement. If offset results in a flash address which is not aligned to 64kB boundary, address will be rounded to the lower 64kB boundary, so that mapped region includes requested range. Pointer returned via out_ptr argument will be adjusted to point to the requested offset (not necessarily to the beginning of mmap-ed region).

To release mapped memory, pass handle returned via out_handle argument to spi_flash_munmap function.

Return

ESP_OK, if successful

Parameters

partition: Pointer to partition structure obtained using esp_partition_find_first or esp_partition_get. Must be non-NULL.
offset: Offset from the beginning of partition where mapping should start.
size: Size of the area to be mapped.
memory: Memory space where the region should be mapped
out_ptr: Output, pointer to the mapped memory region
out_handle: Output, handle which should be used for spi_flash_munmap call

esp_err_t esp_partition_get_sha256(const esp_partition_t *partition, uint8_t *sha_256)¶

Get SHA-256 digest for required partition.

For apps with SHA-256 appended to the app image, the result is the appended SHA-256 value for the app image content. The hash is verified before returning, if app content is invalid then the function returns ESP_ERR_IMAGE_INVALID. For apps without SHA-256 appended to the image, the result is the SHA-256 of all bytes in the app image. For other partition types, the result is the SHA-256 of the entire partition.

Return

ESP_OK: In case of successful operation.
ESP_ERR_INVALID_ARG: The size was 0 or the sha_256 was NULL.
ESP_ERR_NO_MEM: Cannot allocate memory for sha256 operation.
ESP_ERR_IMAGE_INVALID: App partition doesn’t contain a valid app image.
ESP_FAIL: An allocation error occurred.

Parameters

[in] partition: Pointer to info for partition containing app or data. (fields: address, size and type, are required to be filled).
[out] sha_256: Returned SHA-256 digest for a given partition.

bool esp_partition_check_identity(const esp_partition_t *partition_1, const esp_partition_t *partition_2)¶

Check for the identity of two partitions by SHA-256 digest.

Return

True: In case of the two firmware is equal.
False: Otherwise

Parameters

[in] partition_1: Pointer to info for partition 1 containing app or data. (fields: address, size and type, are required to be filled).
[in] partition_2: Pointer to info for partition 2 containing app or data. (fields: address, size and type, are required to be filled).

esp_err_t esp_partition_register_external(esp_flash_t *flash_chip, size_t offset, size_t size, const char *label, esp_partition_type_t type, esp_partition_subtype_t subtype, const esp_partition_t **out_partition)¶

Register a partition on an external flash chip.

This API allows designating certain areas of external flash chips (identified by the esp_flash_t structure) as partitions. This allows using them with components which access SPI flash through the esp_partition API.

Return

ESP_OK on success
ESP_ERR_NOT_SUPPORTED if CONFIG_CONFIG_SPI_FLASH_USE_LEGACY_IMPL is enabled
ESP_ERR_NO_MEM if memory allocation has failed
ESP_ERR_INVALID_ARG if the new partition overlaps another partition on the same flash chip
ESP_ERR_INVALID_SIZE if the partition doesn’t fit into the flash chip size

Parameters

flash_chip: Pointer to the structure identifying the flash chip
offset: Address in bytes, where the partition starts
size: Size of the partition in bytes
label: Partition name
type: One of the partition types (ESP_PARTITION_TYPE_*), or an integer. Note that applications can not be booted from external flash chips, so using ESP_PARTITION_TYPE_APP is not supported.
subtype: One of the partition subtypes (ESP_PARTITION_SUBTYPE_*), or an integer.
[out] out_partition: Output, if non-NULL, receives the pointer to the resulting esp_partition_t structure

esp_err_t esp_partition_deregister_external(const esp_partition_t *partition)¶

Deregister the partition previously registered using esp_partition_register_external.

Return

ESP_OK on success
ESP_ERR_NOT_FOUND if the partition pointer is not found
ESP_ERR_INVALID_ARG if the partition comes from the partition table
ESP_ERR_INVALID_ARG if the partition was not registered using esp_partition_register_external function.

Parameters

partition: pointer to the partition structure obtained from esp_partition_register_external,

Structures¶

struct esp_partition_t¶

partition information structure

This is not the format in flash, that format is esp_partition_info_t.

However, this is the format used by this API.

Public Members

esp_flash_t *flash_chip¶: SPI flash chip on which the partition resides

esp_partition_type_t type¶: partition type (app/data)

esp_partition_subtype_t subtype¶: partition subtype

uint32_t address¶: starting address of the partition in flash

uint32_t size¶: size of the partition, in bytes

char label[17]¶: partition label, zero-terminated ASCII string

bool encrypted¶: flag is set to true if partition is encrypted

Macros¶

ESP_PARTITION_SUBTYPE_OTA(i)¶: Convenience macro to get esp_partition_subtype_t value for the i-th OTA partition.

Type Definitions¶

typedef struct esp_partition_iterator_opaque_ *esp_partition_iterator_t¶: Opaque partition iterator type.

Enumerations¶

enum esp_partition_type_t¶

Partition type.

Note: Partition types with integer value 0x00-0x3F are reserved for partition types defined by ESP-IDF. Any other integer value 0x40-0xFE can be used by individual applications, without restriction.

Values:

ESP_PARTITION_TYPE_APP = 0x00¶: Application partition type.

ESP_PARTITION_TYPE_DATA = 0x01¶: Data partition type.

ESP_PARTITION_TYPE_ANY = 0xff¶: Used to search for partitions with any type.

enum esp_partition_subtype_t¶

Partition subtype.

Application-defined partition types (0x40-0xFE) can set any numeric subtype value.

Note: These ESP-IDF-defined partition subtypes apply to partitions of type ESP_PARTITION_TYPE_APP and ESP_PARTITION_TYPE_DATA.

Values:

ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00¶: Factory application partition.

ESP_PARTITION_SUBTYPE_APP_OTA_MIN = 0x10¶: Base for OTA partition subtypes.

ESP_PARTITION_SUBTYPE_APP_OTA_0 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 0¶: OTA partition 0.

ESP_PARTITION_SUBTYPE_APP_OTA_1 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 1¶: OTA partition 1.

ESP_PARTITION_SUBTYPE_APP_OTA_2 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 2¶: OTA partition 2.

ESP_PARTITION_SUBTYPE_APP_OTA_3 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 3¶: OTA partition 3.

ESP_PARTITION_SUBTYPE_APP_OTA_4 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 4¶: OTA partition 4.

ESP_PARTITION_SUBTYPE_APP_OTA_5 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 5¶: OTA partition 5.

ESP_PARTITION_SUBTYPE_APP_OTA_6 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 6¶: OTA partition 6.

ESP_PARTITION_SUBTYPE_APP_OTA_7 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 7¶: OTA partition 7.

ESP_PARTITION_SUBTYPE_APP_OTA_8 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 8¶: OTA partition 8.

ESP_PARTITION_SUBTYPE_APP_OTA_9 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 9¶: OTA partition 9.

ESP_PARTITION_SUBTYPE_APP_OTA_10 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 10¶: OTA partition 10.

ESP_PARTITION_SUBTYPE_APP_OTA_11 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 11¶: OTA partition 11.

ESP_PARTITION_SUBTYPE_APP_OTA_12 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 12¶: OTA partition 12.

ESP_PARTITION_SUBTYPE_APP_OTA_13 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 13¶: OTA partition 13.

ESP_PARTITION_SUBTYPE_APP_OTA_14 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 14¶: OTA partition 14.

ESP_PARTITION_SUBTYPE_APP_OTA_15 = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 15¶: OTA partition 15.

ESP_PARTITION_SUBTYPE_APP_OTA_MAX = ESP_PARTITION_SUBTYPE_APP_OTA_MIN + 16¶: Max subtype of OTA partition.

ESP_PARTITION_SUBTYPE_APP_TEST = 0x20¶: Test application partition.

ESP_PARTITION_SUBTYPE_DATA_OTA = 0x00¶: OTA selection partition.

ESP_PARTITION_SUBTYPE_DATA_PHY = 0x01¶: PHY init data partition.

ESP_PARTITION_SUBTYPE_DATA_NVS = 0x02¶: NVS partition.

ESP_PARTITION_SUBTYPE_DATA_COREDUMP = 0x03¶: COREDUMP partition.

ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS = 0x04¶: Partition for NVS keys.

ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM = 0x05¶: Partition for emulate eFuse bits.

ESP_PARTITION_SUBTYPE_DATA_UNDEFINED = 0x06¶: Undefined (or unspecified) data partition.

ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD = 0x80¶: ESPHTTPD partition.

ESP_PARTITION_SUBTYPE_DATA_FAT = 0x81¶: FAT partition.

ESP_PARTITION_SUBTYPE_DATA_SPIFFS = 0x82¶: SPIFFS partition.

ESP_PARTITION_SUBTYPE_ANY = 0xff¶: Used to search for partitions with any subtype.

Flash 加密 API 参考¶

Header File¶

components/bootloader_support/include/esp_flash_encrypt.h

Functions¶

static bool esp_flash_encryption_enabled(void)¶

Is flash encryption currently enabled in hardware?

Flash encryption is enabled if the FLASH_CRYPT_CNT efuse has an odd number of bits set.

Return: true if flash encryption is enabled.

esp_err_t esp_flash_encrypt_check_and_update(void)¶

esp_err_t esp_flash_encrypt_region(uint32_t src_addr, size_t data_length)¶

Encrypt-in-place a block of flash sectors.

Note

This function resets RTC_WDT between operations with sectors.

Return

ESP_OK if all operations succeeded, ESP_ERR_FLASH_OP_FAIL if SPI flash fails, ESP_ERR_FLASH_OP_TIMEOUT if flash times out.

Parameters

src_addr: Source offset in flash. Should be multiple of 4096 bytes.
data_length: Length of data to encrypt in bytes. Will be rounded up to next multiple of 4096 bytes.

void esp_flash_write_protect_crypt_cnt(void)¶

Write protect FLASH_CRYPT_CNT.

Intended to be called as a part of boot process if flash encryption is enabled but secure boot is not used. This should protect against serial re-flashing of an unauthorised code in absence of secure boot.

Note: On ESP32 V3 only, write protecting FLASH_CRYPT_CNT will also prevent disabling UART Download Mode. If both are wanted, call esp_efuse_disable_rom_download_mode() before calling this function.

esp_flash_enc_mode_t esp_get_flash_encryption_mode(void)¶

Return the flash encryption mode.

The API is called during boot process but can also be called by application to check the current flash encryption mode of ESP32

Return

void esp_flash_encryption_init_checks(void)¶

Check the flash encryption mode during startup.

Verifies the flash encryption config during startup:

Note: This function is called automatically during app startup, it doesn’t need to be called from the app.

Correct any insecure flash encryption settings if hardware Secure Boot is enabled.
Log warnings if the efuse config doesn’t match the project config in any way

esp_err_t esp_flash_encryption_enable_secure_features(void)¶

Set all secure eFuse features related to flash encryption.

Return

ESP_OK - Successfully

void esp_flash_encryption_set_release_mode(void)¶

Switches Flash Encryption from “Development” to “Release”.

If already in “Release” mode, the function will do nothing. If flash encryption efuse is not enabled yet then abort. It burns:

”disable encrypt in dl mode”
set FLASH_CRYPT_CNT efuse to max

Enumerations¶

enum esp_flash_enc_mode_t¶

Values:

ESP_FLASH_ENC_MODE_DISABLED¶

ESP_FLASH_ENC_MODE_DEVELOPMENT¶

ESP_FLASH_ENC_MODE_RELEASE¶

提供有关此文档的反馈