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