mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'bugfix/spi_flash_remove_include_chain_in_host_drv' into 'master'
esp_flash: support C++ and improve the document See merge request idf/esp-idf!5287
This commit is contained in:
Angus Gratton
commit
bd9590502c
@ -24,6 +24,7 @@
|
||||
|
||||
#include <stdlib.h>
|
||||
#include "soc/spi_periph.h"
|
||||
#include "hal/spi_flash_types.h"
|
||||
#include <sys/param.h> // For MIN/MAX
|
||||
#include <stdbool.h>
|
||||
#include <string.h>
|
||||
@ -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;
|
||||
|
||||
|
||||
@ -17,6 +17,10 @@
|
||||
#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
|
||||
@ -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
|
||||
|
||||
@ -23,36 +23,13 @@
|
||||
#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
|
||||
|
||||
/* 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
|
||||
|
||||
@ -14,9 +14,13 @@
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "hal/spi_flash_ll.h"
|
||||
#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
|
||||
@ -26,6 +30,39 @@ 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
|
||||
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;
|
||||
@ -110,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
|
||||
@ -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).
|
||||
|
||||
@ -146,7 +154,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 +175,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 +196,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
|
||||
|
||||
@ -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;
|
||||
}
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -17,7 +17,11 @@
|
||||
#include <stdint.h>
|
||||
#include <stdbool.h>
|
||||
|
||||
#include "hal/spi_flash_host_drv.h"
|
||||
#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;
|
||||
@ -26,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
|
||||
@ -47,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 {
|
||||
const spi_flash_chip_t *chip_drv; ///< Pointer to chip-model-specific "adpater" structure. If NULL, will be detected during initialisatiopn.
|
||||
spi_flash_host_driver_t *host; ///< Pointer to hardware-specific "host_driver" structure.
|
||||
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 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. 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.
|
||||
};
|
||||
|
||||
@ -65,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 spi, 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.
|
||||
@ -88,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
|
||||
*
|
||||
@ -149,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).
|
||||
@ -161,29 +167,28 @@ 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
|
||||
*
|
||||
* @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 +197,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 +212,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 +276,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
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -129,9 +129,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
|
||||
|
||||
@ -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
|
||||
-------------------------------
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user