SPI Flash API

[中文]

Overview

The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in the external flash. The spi_flash component also has higher-level API functions which work with partitions defined in the partition table.

Different from the API before IDF v4.0, the functionality of esp_flash_* APIs is not limited to the “main” SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access to external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.

Note

Instead of through the cache connected to the SPI0 peripheral, most esp_flash_* APIs go through other SPI peripherals like SPI1, SPI2, etc.. This makes them able to access to not only the main flash, but also external flash.

However due to limitations of the cache, operations through the cache are limited to the main flash. The address range limitation for these operations are also on the cache side. The cache is not able to access external flash chips or address range above its capabilities. These cache operations include: mmap, encrypted read/write, executing code or access to variables in the flash.

Note

Flash APIs after IDF v4.0 are no longer atomic. A writing operation during another on-going read operation, on the overlapped flash address, may cause the return data from the read operation to be partly same as before, and partly updated as new written.

Kconfig option CONFIG_SPI_FLASH_USE_LEGACY_IMPL can be used to switch spi_flash_* functions back to the implementation before ESP-IDF v4.0. However, the code size may get bigger if you use the new API and the old API at the same time.

Encrypted reads and writes use the old implementation, even if CONFIG_SPI_FLASH_USE_LEGACY_IMPL is not enabled. As such, encrypted flash operations are only supported with the main flash chip (and not with other flash chips, that is on SPI1 with different CS, or on other SPI buses). Reading through cache is only supported on the main flash, which is determined by the HW.

Support for features of flash chips

Flash features of different vendors are operated in different ways and need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all 24-bits address flash chips are supported, because they don’t need any vendor-specific commands.

Quad mode (QIO/QOUT) is supported on following chip types:

  1. ISSI

  2. GD

  3. MXIC

  4. FM

  5. Winbond

  6. XMC

  7. BOYA

The 32-bit address range of following chip type is supported:

  1. W25Q256

  2. GD25Q256

Users can also customize their own flash chip driver, see Overriding Default Chip Drivers for more details.

Initializing a flash device

To use esp_flash_* APIs, you need to have a chip initialized on a certain SPI bus.

  1. Call spi_bus_initialize() to properly initialize an SPI bus. This functions initialize the resources (I/O, DMA, interrupts) shared among devices attached to this bus.

  2. Call spi_bus_add_flash_device() to attach the flash device onto the bus. This allocates memory, and fill the members for the esp_flash_t structure. The CS I/O is also initialized here.

  3. Call esp_flash_init() to actually communicate with the chip. This will also detect the chip type, and influence the following operations.

Note

Multiple flash chips can be attached to the same bus now. However, using esp_flash_* devices and spi_device_* devices on the same SPI bus is not supported yet.

SPI flash access API

This is the set of API functions for working with data in flash:

Generally, try to avoid using the raw SPI flash functions to the “main” SPI flash chip in favour of partition-specific functions.

SPI Flash Size

The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000.

By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting CONFIG_ESPTOOLPY_FLASHSIZE in project configuration.

If it is necessary to override the configured flash size at runtime, it is possible to set the chip_size member of the g_rom_flashchip structure. This size is used by esp_flash_* functions (in both software & ROM) to check the bounds.

Concurrency Constraints for flash on SPI1

Attention

The SPI0/1 bus is shared between the instruction & data cache (for firmware execution) and the SPI1 peripheral (controlled by the drivers including this SPI flash driver). Hence, calling SPI Flash API on SPI1 bus (including the main flash) will cause significant influence to the whole system. See Concurrency Constraints for flash on SPI1 for more details.

Partition table API

ESP-IDF projects use a partition table to maintain information about various regions of SPI flash memory (bootloader, various application binaries, data, filesystems). More information on partition tables can be found here.

This component provides API functions to enumerate partitions found in the partition table and perform operations on them. These functions are declared in esp_partition.h:

Note

Application code should mostly use these esp_partition_* API functions instead of lower level esp_flash_* API functions. Partition table API functions do bounds checking and calculate correct offsets in flash, based on data stored in a partition table.

SPI Flash Encryption

It is possible to encrypt the contents of SPI flash and have it transparently decrypted by hardware.

Refer to the Flash Encryption documentation for more details.

Memory mapping API

ESP32 features memory hardware which allows regions of flash memory to be mapped into instruction and data address spaces. This mapping works only for read operations. It is not possible to modify contents of flash memory by writing to a mapped memory region.

Mapping happens in 64 KB pages. Memory mapping hardware can map flash into the data address space and the instruction address space. See the technical reference manual for more details and limitations about memory mapping hardware.

Note that some pages are used to map the application itself into memory, so the actual number of available pages may be less than the capability of the hardware.

Reading data from flash using a memory mapped region is the only way to decrypt contents of flash when flash encryption is enabled. Decryption is performed at the hardware level.

Memory mapping API are declared in esp_spi_flash.h and esp_partition.h:

  • spi_flash_mmap() maps a region of physical flash addresses into instruction space or data space of the CPU.

  • spi_flash_munmap() unmaps previously mapped region.

  • esp_partition_mmap() maps part of a partition into the instruction space or data space of the CPU.

Differences between spi_flash_mmap() and esp_partition_mmap() are as follows:

  • spi_flash_mmap() must be given a 64 KB aligned physical address.

  • esp_partition_mmap() may be given any arbitrary offset within the partition, it will adjust the returned pointer to mapped memory as necessary.

Note that since memory mapping happens in pages, it may be possible to read data outside of the partition provided to esp_partition_mmap, regardless of the partition boundary.

Note

mmap is supported by cache, so it can only be used on main flash.

SPI Flash Implementation

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;

  2. The chip driver, which provides compatibility service to different chips;

  3. The OS functions, provides support of some OS functions (e.g. lock, delay) in different stages (1st/2st boot, or the app).

Host driver

The host driver relies on an interface (spi_flash_host_driver_t) defined in the spi_flash_types.h (in the hal/include/hal folder). This interface provides some common functions to communicate with the chip.

In other files of the SPI HAL, some of these functions are implemented with existing ESP32 memory-spi functionalities. However due to the speed limitations of ESP32, the HAL layer can’t provide high-speed implementations to some reading commands (So we didn’t do it at all). The files (memspi_host_driver.h and .c) implement the high-speed version of these commands with the common_command function provided in the HAL, and wrap these functions as spi_flash_host_driver_t for upper layer to use.

You can also implement your own host driver, even with the GPIO. As long as all the functions in the spi_flash_host_driver_t are implemented, the esp_flash API can access to the flash regardless of the low-level hardware.

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.

Some operations need some commands to be sent first, or read some status after. Some chips need different command or value, or need special communication ways.

There is a type of chip called generic chip which stands for common chips. Other special chip drivers can be developed on the base of the generic chip.

The chip driver relies on the host driver.

OS functions

Currently the OS function layer provides entries of a lock and delay.

The lock (see SPI Bus Lock) is used to resolve the conflicts among the access of devices on the same SPI bus, and the SPI Flash chip access. E.g.

  1. On SPI1 bus, the cache (used to fetch the data (code) in the Flash and PSRAM) should be disabled when the flash chip on the SPI0/1 is being accessed.

  2. On the other buses, the flash driver needs to disable the ISR registered by SPI Master driver, to avoid conflicts.

  3. Some devices of SPI Master driver may requires to use the bus monopolized during a period. (especially when the device doesn’t have CS wire, or the wire is controlled by the software like SDSPI driver).

The delay is used by some long operations which requires the master to wait or polling periodically.

The top API wraps these the chip driver and OS functions into an entire component, and also provides some argument checking.

See also

Implementation details

In order to perform some flash operations, it is necessary to make sure that both CPUs are not running any code from flash for the duration of the flash operation: - In a single-core setup, the SDK does it by disabling interrupts/scheduler before performing the flash operation. - In a dual-core setup, this is slightly more complicated as the SDK needs to make sure that the other CPU is not running any code from flash.

When SPI flash API is called on CPU A (can be PRO or APP), start the spi_flash_op_block_func function on CPU B using the esp_ipc_call API. This API wakes up a high priority task on CPU B and tells it to execute a given function, in this case, spi_flash_op_block_func. This function disables cache on CPU B and signals that the cache is disabled by setting the s_flash_op_can_start flag. Then the task on CPU A disables cache as well and proceeds to execute flash operation.

While a flash operation is running, interrupts can still run on CPUs A and B. It is assumed that all interrupt code is placed into RAM. Once the interrupt allocation API is added, a flag should be added to request the interrupt to be disabled for the duration of a flash operations.

Once the flash operation is complete, the function on CPU A sets another flag, s_flash_op_complete, to let the task on CPU B know that it can re-enable cache and release the CPU. Then the function on CPU A re-enables the cache on CPU A as well and returns control to the calling code.

Additionally, all API functions are protected with a mutex (s_flash_op_mutex).

In a single core environment (CONFIG_FREERTOS_UNICORE enabled), you need to disable both caches, so that no inter-CPU communication can take place.

API Reference - SPI Flash

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.

Parameters

  • out_chip – Pointer to hold the initialized chip.

  • config – Configuration of the chips to initialize.

Returns

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

esp_err_t spi_bus_remove_flash_device(esp_flash_t *chip)

Remove a SPI Flash device from the SPI bus.

Parameters

chip – The flash device to remove.

Returns

  • ESP_ERR_INVALID_ARG: The chip is invalid.

  • ESP_OK: success.

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.

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.

Parameters

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

Returns

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

bool esp_flash_chip_driver_initialized(const esp_flash_t *chip)

Check if appropriate chip driver is set.

Parameters

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

Returns

true if set, otherwise false.

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_id – [out] Pointer to receive ID value.

Returns

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.

Parameters

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

  • out_size – [out] Detected size in bytes.

Returns

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

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_id – [out] Pointer to receive unique ID value.

Returns

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

Parameters

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

Returns

  • 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_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.

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.

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.

Returns

  • 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).

Parameters

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

  • write_protected – [out] Pointer to boolean, set to the value of the write protect flag.

Returns

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

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

Returns

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

Parameters

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

  • out_regions – [out] Pointer to receive a pointer to the array of protectable regions of the chip.

  • out_num_regions – [out] Pointer to an integer receiving the count of protectable regions in the array returned in ‘regions’.

Returns

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

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

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_protected – [out] Pointer to a flag which is set based on the protected status for this region.

Returns

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

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

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.

Returns

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

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.

Note

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

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.

Returns

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

Returns

  • 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

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.

Returns

  • 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().

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.

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.

Returns

  • 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().

static inline 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.

Parameters

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

Returns

true if flash works in quad mode, otherwise false

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

This flag is used to verify chip’s status.

uint32_t reserved_flags

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

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

Read flash status register(2) command.

uint32_t sus_cmd

Flash suspend command.

uint32_t res_cmd

Flash resume command.

uint32_t reserved

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.

Param address

The destination address in flash for the write operation.

Param buffer

Data for programming

Param 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

Param address

the address of written flash partition.

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

Param address

Beginning flash address to write

Param len

Length request to write

Param align_addr

Output of the aligned address to write to

Param page_size

Physical page size of the flash chip

Return

Length that can be actually written in one program_page call

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.

Param address

Beginning flash address to read

Param len

Length request to read

Param align_addr

Output of the aligned address to read

Param page_size

Physical page size of the flash chip

Return

Length that can be actually read in one read call

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:

enumerator ESP_FLASH_5MHZ

The flash runs under 5MHz.

enumerator ESP_FLASH_10MHZ

The flash runs under 10MHz.

enumerator ESP_FLASH_20MHZ

The flash runs under 20MHz.

enumerator ESP_FLASH_26MHZ

The flash runs under 26MHz.

enumerator ESP_FLASH_40MHZ

The flash runs under 40MHz.

enumerator ESP_FLASH_80MHZ

The flash runs under 80MHz.

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

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

enumerator SPI_FLASH_SLOWRD

Data read using single I/O, some limits on speed.

enumerator SPI_FLASH_FASTRD

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

enumerator SPI_FLASH_DOUT

Data read using dual I/O.

enumerator SPI_FLASH_DIO

Both address & data transferred using dual I/O.

enumerator SPI_FLASH_QOUT

Data read using quad I/O.

enumerator SPI_FLASH_QIO

Both address & data transferred using quad I/O.

enumerator SPI_FLASH_OPI_STR

Only support on OPI flash, flash read and write under STR mode.

enumerator SPI_FLASH_OPI_DTR

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

enumerator SPI_FLASH_READ_MODE_MAX

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

API Reference - Partition Table

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.

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.

Returns

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.

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.

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.

Returns

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

const esp_partition_t *esp_partition_get(esp_partition_iterator_t iterator)

Get esp_partition_t structure for given partition.

Parameters

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

Returns

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

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.

Parameters

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

Returns

NULL if no partition was found, valid esp_partition_iterator_t otherwise.

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.

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.

Returns

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

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.

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.

Returns

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.

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.

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.

Returns

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.

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.

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.

Returns

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.

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.

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.

Returns

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.

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

Erase part of the partition.

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.

Returns

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.

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.

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

Returns

ESP_OK, if successful

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.

Parameters

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

  • sha_256 – [out] Returned SHA-256 digest for a given partition.

Returns

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

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.

Parameters

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

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

Returns

  • True: In case of the two firmware is equal.

  • False: Otherwise

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.

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_partition – [out] Output, if non-NULL, receives the pointer to the resulting esp_partition_t structure

Returns

  • 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

esp_err_t esp_partition_deregister_external(const esp_partition_t *partition)

Deregister the partition previously registered using esp_partition_register_external.

Parameters

partition – pointer to the partition structure obtained from esp_partition_register_external,

Returns

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

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:

enumerator ESP_PARTITION_TYPE_APP

Application partition type.

enumerator ESP_PARTITION_TYPE_DATA

Data partition type.

enumerator ESP_PARTITION_TYPE_ANY

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:

enumerator ESP_PARTITION_SUBTYPE_APP_FACTORY

Factory application partition.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_MIN

Base for OTA partition subtypes.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_0

OTA partition 0.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_1

OTA partition 1.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_2

OTA partition 2.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_3

OTA partition 3.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_4

OTA partition 4.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_5

OTA partition 5.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_6

OTA partition 6.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_7

OTA partition 7.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_8

OTA partition 8.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_9

OTA partition 9.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_10

OTA partition 10.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_11

OTA partition 11.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_12

OTA partition 12.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_13

OTA partition 13.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_14

OTA partition 14.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_15

OTA partition 15.

enumerator ESP_PARTITION_SUBTYPE_APP_OTA_MAX

Max subtype of OTA partition.

enumerator ESP_PARTITION_SUBTYPE_APP_TEST

Test application partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_OTA

OTA selection partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_PHY

PHY init data partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_NVS

NVS partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_COREDUMP

COREDUMP partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_NVS_KEYS

Partition for NVS keys.

enumerator ESP_PARTITION_SUBTYPE_DATA_EFUSE_EM

Partition for emulate eFuse bits.

enumerator ESP_PARTITION_SUBTYPE_DATA_UNDEFINED

Undefined (or unspecified) data partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_ESPHTTPD

ESPHTTPD partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_FAT

FAT partition.

enumerator ESP_PARTITION_SUBTYPE_DATA_SPIFFS

SPIFFS partition.

enumerator ESP_PARTITION_SUBTYPE_ANY

Used to search for partitions with any subtype.

API Reference - Flash Encrypt

Functions

static inline 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.

Returns

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.

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.

Returns

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

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

Returns

void esp_flash_encryption_init_checks(void)

Check the flash encryption mode during startup.

Verifies the flash encryption config during startup:

  • 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

Note

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

esp_err_t esp_flash_encryption_enable_secure_features(void)

Set all secure eFuse features related to flash encryption.

Returns

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

enumerator ESP_FLASH_ENC_MODE_DISABLED
enumerator ESP_FLASH_ENC_MODE_DEVELOPMENT
enumerator ESP_FLASH_ENC_MODE_RELEASE

Provide feedback about this document