#include <stdint.h>
#include "esp_err.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+
/*
* Possible errors returned from esp flash internal functions, these error codes
* should be consistent with esp_err_t codes. But in order to make the source
#define ESP_ERR_FLASH_UNSUPPORTED_CHIP (ESP_ERR_FLASH_ERR_BASE+5) ///< Requested operation isn't supported by this model of SPI flash chip.
#define ESP_ERR_FLASH_PROTECTED (ESP_ERR_FLASH_ERR_BASE+6) ///< Write operation failed due to chip's write protection being enabled.
-
+#ifdef __cplusplus
+}
+#endif
#include "hal/spi_flash_types.h"
#include "soc/soc_memory_layout.h"
-#define ESP_FLASH_DEFAULT_FREQ ESP_FLASH_20MHZ
-
/* Hardware host-specific constants */
#define SPI_FLASH_HAL_MAX_WRITE_BYTES 64
#define SPI_FLASH_HAL_MAX_READ_BYTES 64
-///Lowest speed supported by the driver, currently 5 MHz
-#define ESP_FLASH_SPEED_MIN ESP_FLASH_5MHZ
-
-/**
- * @brief 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.
- */
-typedef enum {
- 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_SPEED_MAX, ///< The maximum frequency supported by the host is ``ESP_FLASH_SPEED_MAX-1``.
-} esp_flash_speed_t;
-
/**
* Generic driver context structure for all chips using the SPI peripheral.
* Include this into the HEAD of the driver data for other driver
#include <esp_types.h>
#include "hal/esp_flash_err.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+
/** Definition of a common transaction. Also holds the return value. */
typedef struct {
uint8_t command; ///< Command to send, always 8bits
uint32_t miso_data[2]; ///< [out] Input data from slave, little endian
} spi_flash_trans_t;
+/**
+ * @brief 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.
+ */
+typedef enum {
+ 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_SPEED_MAX, ///< The maximum frequency supported by the host is ``ESP_FLASH_SPEED_MAX-1``.
+} esp_flash_speed_t;
+
+///Lowest speed supported by the driver, currently 5 MHz
+#define ESP_FLASH_SPEED_MIN ESP_FLASH_5MHZ
+
/** @brief Mode used for reading from SPI flash */
typedef enum {
SPI_FLASH_SLOWRD = 0, ///< Data read using single I/O, some limits on speed
bool (*region_protected)(spi_flash_host_driver_t* driver, uint32_t addr, uint32_t size);
};
+#ifdef __cplusplus
+}
+#endif
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 compability service to different chips;
+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).
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 lowlevel hardware.
+esp_flash API can access to the flash regardless of the low-level hardware.
Chip driver
^^^^^^^^^^^
OS functions
^^^^^^^^^^^^
-Currently the OS function layer provides a lock and a delay entrance.
+Currently the OS function layer provides a lock and a delay entries.
The lock is used to resolve the conflicts between the SPI chip access and
-other functions. E.g. the cache (used for the code and psram data fetch)
+other functions. E.g. the cache (used for the code and PSRAM data fetch)
should be disabled when the flash chip on the SPI0/1 is being accessed. Also,
some devices which don't have CS wire, or the wire is controlled by the
software (e.g. SD card via SPI interface), requires the bus to be monopolized
during a period.
The delay is used by some long operations which requires the master to wait
-or polling periodly.
+or polling periodically.
The top API wraps these the chip driver and OS functions into an entire
return ESP_ERR_NOT_FOUND;
}
-esp_err_t IRAM_ATTR esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool *protected)
+esp_err_t IRAM_ATTR esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool *out_protected)
{
VERIFY_OP(get_protected_regions);
- if (protected == NULL) {
+ if (out_protected == NULL) {
return ESP_ERR_INVALID_ARG;
}
err = chip->chip_drv->get_protected_regions(chip, &protection_mask);
if (err == ESP_OK) {
- *protected = protection_mask & (1LL << index);
+ *out_protected = protection_mask & (1LL << index);
}
return spiflash_end(chip, err);
}
-esp_err_t IRAM_ATTR esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool protected)
+esp_err_t IRAM_ATTR esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool protect)
{
VERIFY_OP(set_protected_regions);
err = chip->chip_drv->get_protected_regions(chip, &protection_mask);
if (err == ESP_OK) {
- if (protected) {
+ if (protect) {
protection_mask |= (1LL << index);
} else {
protection_mask &= ~(1LL << index);
#include "hal/spi_flash_types.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+
struct spi_flash_chip_t;
typedef struct spi_flash_chip_t spi_flash_chip_t;
Structure must be passed to esp_flash_init() before use.
*/
struct esp_flash_t {
- const spi_flash_chip_t *chip_drv; ///< Pointer to chip-model-specific "adpater" structure. If NULL, will be detected during initialisatiopn.
+ const spi_flash_chip_t *chip_drv; ///< Pointer to chip-model-specific "adapter" structure. If NULL, will be detected during initialisation.
spi_flash_host_driver_t *host; ///< Pointer to hardware-specific "host_driver" structure.
- const esp_flash_os_functions_t *os_func; ///< Pointer to os-specific hooker strcuture.
- void *os_func_data; ///< Pointer to argument for os-specific hooker.
+ const esp_flash_os_functions_t *os_func; ///< Pointer to os-specific hook structure.
+ void *os_func_data; ///< Pointer to argument for os-specific hooks.
esp_flash_read_mode_t read_mode; ///< Configured SPI flash read mode. Set before initialisation.
uint32_t size; ///< Size of SPI flash in bytes. If 0, size will be detected during initialisation.
*
* This function must be called before any other API functions are called for this chip.
*
- * @note Only the spi, speed & read_mode fields of the chip structure need to be initialised. Other fields will be auto-detected
+ * @note Only the host, speed & read_mode fields of the chip structure need to be initialised. Other fields will be auto-detected
* if left set to zero or NULL.
*
* @note If the chip->drv pointer is NULL, chip chip_drv will be autodetected based on its manufacturer & product IDs. See
*
* @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 **regions, uint32_t *num_regions);
+esp_err_t esp_flash_get_protectable_regions(const esp_flash_t *chip, const esp_flash_region_t **regions, uint32_t *num_regions);
/** @brief Detect if a region of the SPI flash chip is protected
*
* @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
* @param region Pointer to a struct describing a protected region. This must match one of the regions returned from esp_flash_get_protectable_regions(...).
- * @param[out] protected Pointer to a flag which is set based on the protected status for this region.
+ * @param[out] out_protected Pointer to a flag which is set based on the protected status for this region.
*
* @note It is possible for this result to be false and write operations to still fail, if protection is enabled for the entire chip.
*
*
* @return 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 *protected);
+esp_err_t esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool *out_protected);
/** @brief Update the protected status for a region of the SPI flash chip
*
* @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
* @param region Pointer to a struct describing a protected region. This must match one of the regions returned from esp_flash_get_protectable_regions(...).
- * @param protected Write protection flag to set.
+ * @param protect Write protection flag to set.
*
* @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.
*
*
* @return 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 protected);
+esp_err_t esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool protect);
/** @brief Read data from the SPI flash chip
*
/**
* Enable OS-level SPI flash protections in IDF
*
+ * Called by OS startup code. You do not need to call this in your own applications.
+ *
* @return ESP_OK if success, otherwise failed. See return value of ``esp_flash_init_os_functions``.
*/
-esp_err_t esp_flash_app_init(); /* ROM TODO move this to IDF */
+esp_err_t esp_flash_app_init();
/**
* Enable OS-level SPI flash for a specific chip.
*
* @param chip The chip to init os functions.
- * @param host_id Which SPI host to use, 0 for SPI1, 1 for HSPI2 and 2 for VSPI.
+ * @param host_id Which SPI host to use, 1 for SPI1, 2 for SPI2 (HSPI), 3 for SPI3 (VSPI)
*
- * @return ESP_OK if success, otherwise failed. See return value of ``esp_flash_init_os_functions``.
+ * @return
+ * - ESP_OK if success
+ * - ESP_ERR_INVALID_ARG if host_id is invalid
*/
esp_err_t esp_flash_init_os_functions(esp_flash_t *chip, int host_id);
-/* The default (ie initial boot) no-OS ROM esp_flash_os_functions_t */
-extern const esp_flash_os_functions_t spi1_default_os_functions; //todo: put into non-ROM headers
-
-/* Pointer to the current esp_flash_os_functions_t structure in use.
- Can be changed at runtime to reflect different running conditions.
+/**
+ * The default FreeRTOS-compatible esp_flash_os_functions_t, used for flash chips attached to the SPI1
*/
-//extern const esp_flash_os_functions_t *os_func;
+extern const esp_flash_os_functions_t esp_flash_spi1_default_os_functions;
+
+#ifdef __cplusplus
+}
+#endif
};
//for SPI1, we have to disable the cache and interrupts before using the SPI bus
-const DRAM_ATTR esp_flash_os_functions_t spi1_default_os_functions = {
+const DRAM_ATTR esp_flash_os_functions_t esp_flash_spi1_default_os_functions = {
.start = spi1_start,
.end = spi1_end,
.delay_ms = delay_ms,
};
-const esp_flash_os_functions_t spi23_default_os_functions = {
+const esp_flash_os_functions_t esp_flash_spi23_default_os_functions = {
.start = spi23_start,
.end = spi23_end,
.delay_ms = delay_ms,
{
if (host_id == 0) {
//SPI1
- chip->os_func = &spi1_default_os_functions;
+ chip->os_func = &esp_flash_spi1_default_os_functions;
chip->os_func_data = &spi1_arg;
} else if (host_id == 1 || host_id == 2) {
//SPI2,3
- chip->os_func = &spi23_default_os_functions;
+ chip->os_func = &esp_flash_spi23_default_os_functions;
chip->os_func_data = (host_id == 1) ? &spi2_arg : &spi3_arg;
} else {
return ESP_ERR_INVALID_ARG;
projects / esp-idf / commitdiff