alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

esp_flash: update the document to the latest API

Browse Source
This commit is contained in:
Michael (XIAO Xufeng) 2019-06-19 20:35:55 +08:00
parent 026533cd72
commit 37cb673cd7
6 changed files with 53 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
components/spi_flash/README.rst
View File

@ -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 With different chip pointers, you can access to external flashes chips on not
only SPI0/1 but also HSPI/VSPI buses. 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. ``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 However, the code size may get bigger if you use the new API and the old API
the same time. the same time.
Encrypted reads and writes use the old implementation, even if 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 flash operations are only supported with the main flash chip (and not with
other flash chips on SPI1 with different CS). other flash chips on SPI1 with different CS).

28
components/spi_flash/esp_flash_api.c
View File

@ -241,7 +241,7 @@ static esp_err_t IRAM_ATTR detect_spi_flash_chip(esp_flash_t *chip)
} \ } \
} while (0) } 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) { if (chip == NULL) {
chip = esp_flash_default_chip; 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)) { if (chip == NULL || !esp_flash_chip_driver_initialized(chip)) {
return ESP_ERR_FLASH_NOT_INITIALISED; return ESP_ERR_FLASH_NOT_INITIALISED;
} }
if (id == NULL) { if (out_id == NULL) {
return ESP_ERR_INVALID_ARG; return ESP_ERR_INVALID_ARG;
} }
esp_err_t err = spiflash_start(chip); 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; return err;
} }
err = chip->host->read_id(chip->host, id); err = chip->host->read_id(chip->host, out_id);
return spiflash_end(chip, err); 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); VERIFY_OP(detect_size);
if (size == NULL) { if (out_size == NULL) {
return ESP_ERR_INVALID_ARG; return ESP_ERR_INVALID_ARG;
} }
if (chip->size != 0) { if (chip->size != 0) {
*size = chip->size; *out_size = chip->size;
return ESP_OK; 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); 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); VERIFY_OP(set_chip_write_protect);
//TODO: skip writing if already locked or unlocked //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; 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); 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) { if(out_num_regions != NULL) {
*num_regions = 0; // In case caller doesn't check result *out_num_regions = 0; // In case caller doesn't check result
} }
VERIFY_OP(get_protected_regions); VERIFY_OP(get_protected_regions);
if(regions == NULL || num_regions == NULL) { if(out_regions == NULL || out_num_regions == NULL) {
return ESP_ERR_INVALID_ARG; return ESP_ERR_INVALID_ARG;
} }
*num_regions = chip->chip_drv->num_protectable_regions; *out_num_regions = chip->chip_drv->num_protectable_regions;
*regions = chip->chip_drv->protectable_regions; *out_regions = chip->chip_drv->protectable_regions;
return ESP_OK; return ESP_OK;
} }

44
components/spi_flash/include/esp_flash.h
View File

@ -30,11 +30,11 @@ typedef struct esp_flash_t esp_flash_t;
/** @brief Structure for describing a region of flash */ /** @brief Structure for describing a region of flash */
typedef struct { typedef struct {
uint32_t offset; uint32_t offset; ///< Start address of this region
uint32_t size; uint32_t size; ///< Size of the region
} esp_flash_region_t; } 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 { typedef struct {
/** /**
* Called before commencing any flash operation. Does not need to be * 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. /** @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 { 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. 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. 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. 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. 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. * 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 * @note Only the ``host`` and ``read_mode`` fields of the chip structure must
* if left set to zero or NULL. * 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 * @note If the chip->drv pointer is NULL, chip chip_drv will be auto-detected
* esp_flash_registered_flash_drivers pointer for details of this process. * 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. * @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. * @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. /** @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 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. * 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. * @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. /** @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 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 * @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. * 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. * @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 /** @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 /** @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 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' * @note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv'
* field). * 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. * @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. /** @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 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] out_regions 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_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' * @note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv'
* field). * field).
* *
* @return ESP_OK on success, or a flash error code if operation failed. * @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 /** @brief Detect if a region of the SPI flash chip is protected

3
docs/Doxyfile
View File

@ -127,9 +127,10 @@ INPUT = \
## Storage - API Reference ## Storage - API Reference
## ##
## SPI Flash and Partition APIs ## 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/spi_flash/include/esp_partition.h \
../../components/bootloader_support/include/esp_flash_encrypt.h \ ../../components/bootloader_support/include/esp_flash_encrypt.h \
../../components/soc/include/hal/spi_flash_types.h \
## SPIFFS ## SPIFFS
../../components/spiffs/include/esp_spiffs.h \ ../../components/spiffs/include/esp_spiffs.h \
## SD/MMC Card Host ## SD/MMC Card Host

3
docs/en/api-reference/storage/spi_flash.rst
View File

@ -31,7 +31,8 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need
API Reference - SPI Flash 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 API Reference - Partition Table
------------------------------- -------------------------------

2
docs/sphinx-known-warnings.txt
View File

@ -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_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 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, 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, 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 wear-levelling.rst:line: WARNING: Duplicate declaration, size_t esp_vfs_fat_mount_config_t::allocation_unit_size