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

components/soc/esp32/include/hal/spi_flash_ll.h

@@ -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;
 

components/soc/include/hal/esp_flash_err.h

@@ -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

components/soc/include/hal/spi_flash_hal.h

@@ -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

components/soc/include/hal/spi_flash_host_drv.h → components/soc/include/hal/spi_flash_types.h

@@ -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

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).
 
@@ -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

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;
 }
 
@@ -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);

components/spi_flash/include/esp_flash.h

@@ -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

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;

docs/Doxyfile

@@ -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

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
 -------------------------------

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