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).
} \
} 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;
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);
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;
}
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
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;
}
/** @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
/** @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.
};
*
* 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.
/** @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
*
/** @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).
*
* @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
projects / esp-idf / commitdiff