From caf121e4b6a67e7ce1746a69bc246257f972da1b Mon Sep 17 00:00:00 2001 From: "Michael (XIAO Xufeng)" Date: Wed, 19 Jun 2019 16:37:55 +0800 Subject: [PATCH 1/3] esp_flash: break the inappropriate include chain in spi_flash_host_drv.h --- components/soc/esp32/include/hal/spi_flash_ll.h | 13 +------------ components/soc/include/hal/spi_flash_hal.h | 2 +- .../{spi_flash_host_drv.h => spi_flash_types.h} | 14 +++++++++++++- components/spi_flash/include/esp_flash.h | 2 +- 4 files changed, 16 insertions(+), 15 deletions(-) rename components/soc/include/hal/{spi_flash_host_drv.h => spi_flash_types.h} (87%) diff --git a/components/soc/esp32/include/hal/spi_flash_ll.h b/components/soc/esp32/include/hal/spi_flash_ll.h index f9adbd5f1b..7155e0a872 100644 --- a/components/soc/esp32/include/hal/spi_flash_ll.h +++ b/components/soc/esp32/include/hal/spi_flash_ll.h @@ -24,6 +24,7 @@ #include #include "soc/spi_periph.h" +#include "hal/spi_flash_types.h" #include // For MIN/MAX #include #include @@ -43,18 +44,6 @@ ///Slowest io mode supported by ESP32, currently SlowRd #define SPI_FLASH_READ_MODE_MIN SPI_FLASH_SLOWRD -/** @brief Mode used for reading from SPI flash */ -typedef enum { - 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_READ_MODE_MAX, ///< The fastest io mode supported by the host is ``ESP_FLASH_READ_MODE_MAX-1``. -} esp_flash_read_mode_t; - /// type to store pre-calculated register value in above layers typedef typeof(SPI1.clock) spi_flash_ll_clock_reg_t; diff --git a/components/soc/include/hal/spi_flash_hal.h b/components/soc/include/hal/spi_flash_hal.h index 1a5c373614..49972c5199 100644 --- a/components/soc/include/hal/spi_flash_hal.h +++ b/components/soc/include/hal/spi_flash_hal.h @@ -23,7 +23,7 @@ #pragma once #include "hal/spi_flash_ll.h" -#include "hal/spi_flash_host_drv.h" +#include "hal/spi_flash_types.h" #include "soc/soc_memory_layout.h" #define ESP_FLASH_DEFAULT_FREQ ESP_FLASH_20MHZ diff --git a/components/soc/include/hal/spi_flash_host_drv.h b/components/soc/include/hal/spi_flash_types.h similarity index 87% rename from components/soc/include/hal/spi_flash_host_drv.h rename to components/soc/include/hal/spi_flash_types.h index 5095bc8f50..067d10fd4b 100644 --- a/components/soc/include/hal/spi_flash_host_drv.h +++ b/components/soc/include/hal/spi_flash_types.h @@ -14,7 +14,7 @@ #pragma once -#include "hal/spi_flash_ll.h" +#include #include "hal/esp_flash_err.h" /** Definition of a common transaction. Also holds the return value. */ @@ -26,6 +26,18 @@ typedef struct { uint32_t miso_data[2]; ///< [out] Input data from slave, little endian } spi_flash_trans_t; +/** @brief Mode used for reading from SPI flash */ +typedef enum { + 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_READ_MODE_MAX, ///< The fastest io mode supported by the host is ``ESP_FLASH_READ_MODE_MAX-1``. +} esp_flash_read_mode_t; + struct spi_flash_host_driver_t; typedef struct spi_flash_host_driver_t spi_flash_host_driver_t; diff --git a/components/spi_flash/include/esp_flash.h b/components/spi_flash/include/esp_flash.h index 904b09b493..48eedcda37 100644 --- a/components/spi_flash/include/esp_flash.h +++ b/components/spi_flash/include/esp_flash.h @@ -17,7 +17,7 @@ #include #include -#include "hal/spi_flash_host_drv.h" +#include "hal/spi_flash_types.h" struct spi_flash_chip_t; typedef struct spi_flash_chip_t spi_flash_chip_t; From 026533cd72190bff864af971238bdeff0964fd32 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Wed, 19 Jun 2019 16:37:11 +0800 Subject: [PATCH 2/3] esp_flash: fix C++ compilation and some typos --- components/soc/include/hal/esp_flash_err.h | 8 +++- components/soc/include/hal/spi_flash_hal.h | 23 ---------- components/soc/include/hal/spi_flash_types.h | 28 ++++++++++++ components/spi_flash/README.rst | 10 ++--- components/spi_flash/esp_flash_api.c | 10 ++--- components/spi_flash/include/esp_flash.h | 46 ++++++++++++-------- components/spi_flash/spi_flash_os_func_app.c | 8 ++-- 7 files changed, 76 insertions(+), 57 deletions(-) diff --git a/components/soc/include/hal/esp_flash_err.h b/components/soc/include/hal/esp_flash_err.h index c760f19fe6..cde56aa507 100644 --- a/components/soc/include/hal/esp_flash_err.h +++ b/components/soc/include/hal/esp_flash_err.h @@ -17,6 +17,10 @@ #include #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 @@ -36,4 +40,6 @@ #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 diff --git a/components/soc/include/hal/spi_flash_hal.h b/components/soc/include/hal/spi_flash_hal.h index 49972c5199..cd0fb5d361 100644 --- a/components/soc/include/hal/spi_flash_hal.h +++ b/components/soc/include/hal/spi_flash_hal.h @@ -26,33 +26,10 @@ #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 diff --git a/components/soc/include/hal/spi_flash_types.h b/components/soc/include/hal/spi_flash_types.h index 067d10fd4b..28e591f82a 100644 --- a/components/soc/include/hal/spi_flash_types.h +++ b/components/soc/include/hal/spi_flash_types.h @@ -17,6 +17,10 @@ #include #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 @@ -26,6 +30,27 @@ typedef struct { 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 @@ -122,3 +147,6 @@ struct spi_flash_host_driver_t { bool (*region_protected)(spi_flash_host_driver_t* driver, uint32_t addr, uint32_t size); }; +#ifdef __cplusplus +} +#endif diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index e65b1ad4c6..26387c04a5 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -146,7 +146,7 @@ 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 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). @@ -167,7 +167,7 @@ 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 lowlevel hardware. +esp_flash API can access to the flash regardless of the low-level hardware. Chip driver ^^^^^^^^^^^ @@ -188,17 +188,17 @@ The chip driver relies on the host 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 diff --git a/components/spi_flash/esp_flash_api.c b/components/spi_flash/esp_flash_api.c index 3a48154c7b..48533ec573 100644 --- a/components/spi_flash/esp_flash_api.c +++ b/components/spi_flash/esp_flash_api.c @@ -448,11 +448,11 @@ static esp_err_t find_region(const esp_flash_t *chip, const esp_flash_region_t * 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; } @@ -470,13 +470,13 @@ esp_err_t IRAM_ATTR esp_flash_get_protected_region(esp_flash_t *chip, const esp_ 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); @@ -494,7 +494,7 @@ esp_err_t IRAM_ATTR esp_flash_set_protected_region(esp_flash_t *chip, const esp_ 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); diff --git a/components/spi_flash/include/esp_flash.h b/components/spi_flash/include/esp_flash.h index 48eedcda37..81524dc5d2 100644 --- a/components/spi_flash/include/esp_flash.h +++ b/components/spi_flash/include/esp_flash.h @@ -19,6 +19,10 @@ #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; @@ -50,11 +54,11 @@ typedef struct { 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. @@ -65,7 +69,7 @@ struct esp_flash_t { * * 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 @@ -175,15 +179,14 @@ esp_err_t esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect * * @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. * @@ -192,13 +195,13 @@ esp_flash_get_protectable_regions(const esp_flash_t *chip, const esp_flash_regio * * @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. * @@ -207,7 +210,7 @@ esp_err_t esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_regi * * @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 * @@ -271,24 +274,29 @@ esp_err_t esp_flash_init_default_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 diff --git a/components/spi_flash/spi_flash_os_func_app.c b/components/spi_flash/spi_flash_os_func_app.c index 9b9738becf..8b293e5ebf 100644 --- a/components/spi_flash/spi_flash_os_func_app.c +++ b/components/spi_flash/spi_flash_os_func_app.c @@ -89,13 +89,13 @@ static app_func_arg_t spi3_arg = { }; //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, @@ -105,11 +105,11 @@ esp_err_t esp_flash_init_os_functions(esp_flash_t *chip, int host_id) { 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; From 37cb673cd720d1e0ee19e5f92a4f3e2ad253e1a6 Mon Sep 17 00:00:00 2001 From: "Michael (XIAO Xufeng)" Date: Wed, 19 Jun 2019 20:35:55 +0800 Subject: [PATCH 3/3] esp_flash: update the document to the latest API --- components/spi_flash/README.rst | 12 +++++- components/spi_flash/esp_flash_api.c | 28 ++++++------- components/spi_flash/include/esp_flash.h | 44 +++++++++++---------- docs/Doxyfile | 3 +- docs/en/api-reference/storage/spi_flash.rst | 3 +- docs/sphinx-known-warnings.txt | 2 + 6 files changed, 53 insertions(+), 39 deletions(-) diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index 26387c04a5..a6f37b53cb 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -13,13 +13,21 @@ the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access to external flashes chips on not only SPI0/1 but also HSPI/VSPI buses. -Kconfig option :ref:``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` can be used to switch +.. 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 :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` can be used to switch ``spi_flash_*`` functions back to the implementation before IDF v4.0. However, the code size may get bigger if you use the new API and the old API the same time. Encrypted reads and writes use the old implementation, even if -:ref:``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` is not enabled. As such, encrypted +:ref:`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 on SPI1 with different CS). diff --git a/components/spi_flash/esp_flash_api.c b/components/spi_flash/esp_flash_api.c index 48533ec573..58a8c30f2a 100644 --- a/components/spi_flash/esp_flash_api.c +++ b/components/spi_flash/esp_flash_api.c @@ -241,7 +241,7 @@ static esp_err_t IRAM_ATTR detect_spi_flash_chip(esp_flash_t *chip) } \ } while (0) -esp_err_t IRAM_ATTR esp_flash_read_id(esp_flash_t *chip, uint32_t *id) +esp_err_t IRAM_ATTR esp_flash_read_id(esp_flash_t *chip, uint32_t *out_id) { if (chip == NULL) { chip = esp_flash_default_chip; @@ -249,7 +249,7 @@ esp_err_t IRAM_ATTR esp_flash_read_id(esp_flash_t *chip, uint32_t *id) if (chip == NULL || !esp_flash_chip_driver_initialized(chip)) { return ESP_ERR_FLASH_NOT_INITIALISED; } - if (id == NULL) { + if (out_id == NULL) { return ESP_ERR_INVALID_ARG; } esp_err_t err = spiflash_start(chip); @@ -257,19 +257,19 @@ esp_err_t IRAM_ATTR esp_flash_read_id(esp_flash_t *chip, uint32_t *id) return err; } - err = chip->host->read_id(chip->host, id); + err = chip->host->read_id(chip->host, out_id); return spiflash_end(chip, err); } -esp_err_t IRAM_ATTR esp_flash_get_size(esp_flash_t *chip, uint32_t *size) +esp_err_t IRAM_ATTR esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size) { VERIFY_OP(detect_size); - if (size == NULL) { + if (out_size == NULL) { return ESP_ERR_INVALID_ARG; } if (chip->size != 0) { - *size = chip->size; + *out_size = chip->size; return ESP_OK; } @@ -401,7 +401,7 @@ esp_err_t IRAM_ATTR esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *wr return spiflash_end(chip, err); } -esp_err_t IRAM_ATTR esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect_chip) +esp_err_t IRAM_ATTR esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect) { VERIFY_OP(set_chip_write_protect); //TODO: skip writing if already locked or unlocked @@ -411,24 +411,24 @@ esp_err_t IRAM_ATTR esp_flash_set_chip_write_protect(esp_flash_t *chip, bool wri return err; } - err = chip->chip_drv->set_chip_write_protect(chip, write_protect_chip); + err = chip->chip_drv->set_chip_write_protect(chip, write_protect); return spiflash_end(chip, err); } -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 **out_regions, uint32_t *out_num_regions) { - if(num_regions != NULL) { - *num_regions = 0; // In case caller doesn't check result + if(out_num_regions != NULL) { + *out_num_regions = 0; // In case caller doesn't check result } VERIFY_OP(get_protected_regions); - if(regions == NULL || num_regions == NULL) { + if(out_regions == NULL || out_num_regions == NULL) { return ESP_ERR_INVALID_ARG; } - *num_regions = chip->chip_drv->num_protectable_regions; - *regions = chip->chip_drv->protectable_regions; + *out_num_regions = chip->chip_drv->num_protectable_regions; + *out_regions = chip->chip_drv->protectable_regions; return ESP_OK; } diff --git a/components/spi_flash/include/esp_flash.h b/components/spi_flash/include/esp_flash.h index 81524dc5d2..84a349b489 100644 --- a/components/spi_flash/include/esp_flash.h +++ b/components/spi_flash/include/esp_flash.h @@ -30,11 +30,11 @@ typedef struct esp_flash_t esp_flash_t; /** @brief Structure for describing a region of flash */ typedef struct { - uint32_t offset; - uint32_t size; + uint32_t offset; ///< Start address of this region + uint32_t size; ///< Size of the region } esp_flash_region_t; -/* OS-level integration hooks for accessing flash chips inside a running OS */ +/** OS-level integration hooks for accessing flash chips inside a running OS */ typedef struct { /** * Called before commencing any flash operation. Does not need to be @@ -51,16 +51,16 @@ typedef struct { /** @brief Structure to describe a SPI flash chip connected to the system. - Structure must be passed to esp_flash_init() before use. + Structure must be initialized before use (passed to esp_flash_init()). */ struct esp_flash_t { + spi_flash_host_driver_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. - 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 hook structure. - void *os_func_data; ///< Pointer to argument for os-specific hooks. + 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_read_mode_t read_mode; ///< Configured SPI flash read mode. Set before initialisation. + esp_flash_read_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. }; @@ -69,11 +69,13 @@ struct esp_flash_t { * * This function must be called before any other API functions are called for this chip. * - * @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 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 autodetected based on its manufacturer & product IDs. See - * esp_flash_registered_flash_drivers pointer for details of this process. + * @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. * * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted. * @return ESP_OK on success, or a flash error code if initialisation fails. @@ -92,25 +94,25 @@ bool esp_flash_chip_driver_initialized(const esp_flash_t *chip); /** @brief Read flash ID via the common "RDID" SPI flash command. * * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() - * @param[out] Pointer to receive ID value. + * @param[out] out_id Pointer to receive ID value. * * ID is a 24-bit value. Lower 16 bits of 'id' are the chip ID, upper 8 bits are the manufacturer ID. * * @return ESP_OK on success, or a flash error code if operation failed. */ -esp_err_t esp_flash_read_id(esp_flash_t *chip, uint32_t *id); +esp_err_t esp_flash_read_id(esp_flash_t *chip, uint32_t *out_id); /** @brief Detect flash size based on flash ID. * * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() - * @param[out] Detected size in bytes. + * @param[out] out_size Detected size in bytes. * * @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. */ -esp_err_t esp_flash_get_size(esp_flash_t *chip, uint32_t *size); +esp_err_t esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size); /** @brief Erase flash chip contents * @@ -153,7 +155,7 @@ esp_err_t esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *write_protec /** @brief Set write protection for the SPI flash chip * * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() - * @param write_protected Boolean value for the write protect flag + * @param write_protect Boolean value for the write protect flag * * @note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv' * field). @@ -165,21 +167,21 @@ esp_err_t esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *write_protec * * @return 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_chip); +esp_err_t esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect); /** @brief Read the list of individually protectable regions of this SPI flash chip. * * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init() - * @param regions[out] Pointer to receive a pointer to the array of protectable regions of the chip. - * @param[out] Pointer to an integer receiving the count of protectable regions in the array returned in 'regions'. + * @param[out] out_regions Pointer to receive a pointer to the array of protectable regions of the chip. + * @param[out] out_num_regions Pointer to an integer receiving the count of protectable regions in the array returned in 'regions'. * * @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. */ -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 **out_regions, uint32_t *out_num_regions); /** @brief Detect if a region of the SPI flash chip is protected diff --git a/docs/Doxyfile b/docs/Doxyfile index 858a6a39e0..3434ec5082 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -127,9 +127,10 @@ INPUT = \ ## Storage - API Reference ## ## SPI Flash and Partition APIs - ../../components/spi_flash/include/esp_spi_flash.h \ + ../../components/spi_flash/include/esp_flash.h \ ../../components/spi_flash/include/esp_partition.h \ ../../components/bootloader_support/include/esp_flash_encrypt.h \ + ../../components/soc/include/hal/spi_flash_types.h \ ## SPIFFS ../../components/spiffs/include/esp_spiffs.h \ ## SD/MMC Card Host diff --git a/docs/en/api-reference/storage/spi_flash.rst b/docs/en/api-reference/storage/spi_flash.rst index 5595011d77..ff70cfd35b 100644 --- a/docs/en/api-reference/storage/spi_flash.rst +++ b/docs/en/api-reference/storage/spi_flash.rst @@ -31,7 +31,8 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need API Reference - SPI Flash ------------------------- -.. include:: /_build/inc/esp_spi_flash.inc +.. include:: /_build/inc/esp_flash.inc +.. include:: /_build/inc/spi_flash_types.inc API Reference - Partition Table ------------------------------- diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index 72fb40a5b6..fe496b067f 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -77,6 +77,8 @@ If type alias or template alias: # spi_master.inc:line: WARNING: Duplicate declaration, struct spi_transaction_t spi_transaction_t spi_slave.inc:line: WARNING: Duplicate declaration, struct spi_slave_transaction_t spi_slave_transaction_t +esp_flash.inc:line: WARNING: Duplicate declaration, struct esp_flash_t esp_flash_t +spi_flash_types.inc:line: WARNING: Duplicate declaration, struct spi_flash_host_driver_t spi_flash_host_driver_t wear-levelling.rst:line: WARNING: Duplicate declaration, bool esp_vfs_fat_mount_config_t::format_if_mount_failed wear-levelling.rst:line: WARNING: Duplicate declaration, int esp_vfs_fat_mount_config_t::max_files wear-levelling.rst:line: WARNING: Duplicate declaration, size_t esp_vfs_fat_mount_config_t::allocation_unit_size