Chapter 2. API Reference
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-S2 memory-spi function-
alities. However due to the speed limitations of ESP32-S2, 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
• Partition Table documentation
• Over The Air Update (OTA) API provides high-level API for updating app firmware stored in flash.
• Non-Volatile Storage (NVS) API provides a structured API for storing small pieces of data in SPI flash.
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.
Espressif Systems 745
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General