Merge branch 'feat/esp_flash_data_slicer' into 'master'

esp_flash: refactor to be compatible with the latest ROM

Closes IDF-1664 and IDFGH-2074

See merge request espressif/esp-idf!8565

Author: ginkgm

components/soc/include/hal/spi_flash_hal.h

@@ -37,11 +37,13 @@
  * implementations that also use the SPI peripheral.
  */
 typedef struct {
+    spi_flash_host_inst_t inst; ///< Host instance, containing host data and function pointer table. May update with the host (hardware version).
     spi_dev_t *spi;             ///< Pointer to SPI peripheral registers (SP1, SPI2 or SPI3). Set before initialisation.
     int cs_num;                 ///< Which cs pin is used, 0-2.
-    int extra_dummy;
-    spi_flash_ll_clock_reg_t clock_conf;
-} spi_flash_memspi_data_t;
+    int extra_dummy;            ///< Pre-calculated extra dummy used for compensation
+    spi_flash_ll_clock_reg_t clock_conf;    ///< Pre-calculated clock configuration value
+    uint32_t reserved_config[2];            ///< The ROM has reserved some memory for configurations with one set of driver code. (e.g. QPI mode, 64-bit address mode, etc.)
+} spi_flash_hal_context_t;
 
 /// Configuration structure for the SPI driver.
 typedef struct {
@@ -50,7 +52,7 @@ typedef struct {
     bool iomux;             ///< Whether the IOMUX is used, used for timing compensation.
     int input_delay_ns;     ///< Input delay on the MISO pin after the launch clock， used for timing compensation.
     esp_flash_speed_t speed;///< SPI flash clock speed to work at.
-} spi_flash_memspi_config_t;
+} spi_flash_hal_config_t;
 
 /**
  * Configure SPI flash hal settings.
@@ -62,16 +64,16 @@ typedef struct {
  *      - ESP_OK: success
  *      - ESP_ERR_INVALID_ARG: the data buffer is not in the DRAM.
  */
-esp_err_t spi_flash_hal_init(spi_flash_memspi_data_t *data_out, const spi_flash_memspi_config_t *cfg);
+esp_err_t spi_flash_hal_init(spi_flash_hal_context_t *data_out, const spi_flash_hal_config_t *cfg);
 
 /**
  * Configure the device-related register before transactions.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  *
  * @return always return ESP_OK.
  */
-esp_err_t spi_flash_hal_device_config(spi_flash_host_driver_t *driver);
+esp_err_t spi_flash_hal_device_config(spi_flash_host_inst_t *host);
 
 /**
  * Send an user-defined spi transaction to the device.
@@ -80,60 +82,60 @@ esp_err_t spi_flash_hal_device_config(spi_flash_host_driver_t *driver);
  *      particular commands. Since this function supports timing compensation, it is
  *      also used to receive some data when the frequency is high.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  * @param trans The transaction to send, also holds the received data.
  *
  * @return always return ESP_OK.
  */
-esp_err_t spi_flash_hal_common_command(spi_flash_host_driver_t *driver, spi_flash_trans_t *trans);
+esp_err_t spi_flash_hal_common_command(spi_flash_host_inst_t *host, spi_flash_trans_t *trans);
 
 /**
  * Erase whole flash chip by using the erase chip (C7h) command.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  */
-void spi_flash_hal_erase_chip(spi_flash_host_driver_t *driver);
+void spi_flash_hal_erase_chip(spi_flash_host_inst_t *host);
 
 /**
  * Erase a specific sector by its start address through the sector erase (20h)
  * command.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  * @param start_address Start address of the sector to erase.
  */
-void spi_flash_hal_erase_sector(spi_flash_host_driver_t *driver, uint32_t start_address);
+void spi_flash_hal_erase_sector(spi_flash_host_inst_t *host, uint32_t start_address);
 
 /**
  * Erase a specific 64KB block by its start address through the 64KB block
  * erase (D8h) command.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  * @param start_address Start address of the block to erase.
  */
-void spi_flash_hal_erase_block(spi_flash_host_driver_t *driver, uint32_t start_address);
+void spi_flash_hal_erase_block(spi_flash_host_inst_t *host, uint32_t start_address);
 
 /**
  * Program a page of the flash using the page program (02h) command.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  * @param address Address of the page to program
  * @param buffer Data to program
  * @param length Size of the buffer in bytes, no larger than ``SPI_FLASH_HAL_MAX_WRITE_BYTES`` (64) bytes.
  */
-void spi_flash_hal_program_page(spi_flash_host_driver_t *driver, const void *buffer, uint32_t address, uint32_t length);
+void spi_flash_hal_program_page(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length);
 
 /**
  * Read from the flash. Call ``spi_flash_hal_configure_host_read_mode`` to
  * configure the read command before calling this function.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  * @param buffer Buffer to store the read data
  * @param address Address to read
  * @param length Length to read, no larger than ``SPI_FLASH_HAL_MAX_READ_BYTES`` (64) bytes.
  *
  * @return always return ESP_OK.
  */
-esp_err_t spi_flash_hal_read(spi_flash_host_driver_t *driver, void *buffer, uint32_t address, uint32_t read_len);
+esp_err_t spi_flash_hal_read(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len);
 
 /**
  * @brief Send the write enable (06h) or write disable (04h) command to the flash chip.
@@ -143,16 +145,16 @@ esp_err_t spi_flash_hal_read(spi_flash_host_driver_t *driver, void *buffer, uint
  *
  * @return always return ESP_OK.
  */
-esp_err_t spi_flash_hal_set_write_protect(spi_flash_host_driver_t *chip_drv, bool wp);
+esp_err_t spi_flash_hal_set_write_protect(spi_flash_host_inst_t *host, bool wp);
 
 /**
  * Check whether the SPI host is idle and can perform other operations.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  *
  * @return ture if idle, otherwise false.
  */
-bool spi_flash_hal_host_idle(spi_flash_host_driver_t *driver);
+bool spi_flash_hal_host_idle(spi_flash_host_inst_t *host);
 
 /**
  * @brief Configure the SPI host hardware registers for the specified io mode.
@@ -177,42 +179,42 @@ bool spi_flash_hal_host_idle(spi_flash_host_driver_t *driver);
  *  - Common write: set command value, address value (or length to 0 if not
  *    used), disable dummy phase, and set output data.
  *
- * @param driver The driver context
+ * @param host The driver context
  * @param io_mode The HW read mode to use
  * @param addr_bitlen Length of the address phase, in bits
  * @param dummy_cyclelen_base Base cycles of the dummy phase, some extra dummy cycles may be appended to compensate the timing.
  * @param command  Actual reading command to send to flash chip on the bus.
  *
  * @return always return ESP_OK.
  */
-esp_err_t spi_flash_hal_configure_host_io_mode(spi_flash_host_driver_t *driver, uint32_t command, uint32_t addr_bitlen,
+esp_err_t spi_flash_hal_configure_host_io_mode(spi_flash_host_inst_t *host, uint32_t command, uint32_t addr_bitlen,
                                                int dummy_cyclelen_base, esp_flash_io_mode_t io_mode);
 
 /**
  * Poll until the last operation is done.
  *
- * @param driver The driver context.
+ * @param host The driver context.
  */
-void spi_flash_hal_poll_cmd_done(spi_flash_host_driver_t *driver);
+void spi_flash_hal_poll_cmd_done(spi_flash_host_inst_t *host);
 
 /**
  * Check whether the given buffer can be used as the write buffer directly. If 'chip' is connected to the main SPI bus, we can only write directly from
  * regions that are accessible ith cache disabled. *
  *
- * @param driver The driver context
+ * @param host The driver context
  * @param p The buffer holding data to send.
  *
  * @return True if the buffer can be used to send data, otherwise false.
  */
-bool spi_flash_hal_supports_direct_write(spi_flash_host_driver_t *driver, const void *p);
+bool spi_flash_hal_supports_direct_write(spi_flash_host_inst_t *host, const void *p);
 
 /**
  * Check whether the given buffer can be used as the read buffer directly. If 'chip' is connected to the main SPI bus, we can only read directly from
  * regions that are accessible ith cache disabled. *
  *
- * @param driver The driver context
+ * @param host The driver context
  * @param p The buffer to hold the received data.
  *
  * @return True if the buffer can be used to receive data, otherwise false.
  */
-bool spi_flash_hal_supports_direct_read(spi_flash_host_driver_t *driver, const void *p);
+bool spi_flash_hal_supports_direct_read(spi_flash_host_inst_t *host, const void *p);

components/soc/include/hal/spi_flash_types.h

@@ -68,84 +68,105 @@ typedef enum {
 ///Slowest io mode supported by ESP32, currently SlowRd
 #define SPI_FLASH_READ_MODE_MIN SPI_FLASH_SLOWRD
 
-struct spi_flash_host_driver_t;
-typedef struct spi_flash_host_driver_t spi_flash_host_driver_t;
+struct spi_flash_host_driver_s;
+typedef struct spi_flash_host_driver_s spi_flash_host_driver_t;
+
+/** SPI Flash Host driver instance */
+typedef struct {
+    const struct spi_flash_host_driver_s* driver;  ///< Pointer to the implementation function table
+    // Implementations can wrap this structure into their own ones, and append other data here
+} spi_flash_host_inst_t ;
+
 
 /** Host driver configuration and context structure. */
-struct spi_flash_host_driver_t {
-    /**
-     * Configuration and static data used by the specific host driver. The type
-     * is determined by the host driver.
-     */
-    void *driver_data;
+struct spi_flash_host_driver_s {
     /**
      * Configure the device-related register before transactions. This saves
      * some time to re-configure those registers when we send continuously
      */
-    esp_err_t (*dev_config)(spi_flash_host_driver_t *driver);
+    esp_err_t (*dev_config)(spi_flash_host_inst_t *host);
     /**
      * Send an user-defined spi transaction to the device.
      */
-    esp_err_t (*common_command)(spi_flash_host_driver_t *driver, spi_flash_trans_t *t);
+    esp_err_t (*common_command)(spi_flash_host_inst_t *host, spi_flash_trans_t *t);
     /**
      * Read flash ID.
      */
-    esp_err_t (*read_id)(spi_flash_host_driver_t *driver, uint32_t *id);
+    esp_err_t (*read_id)(spi_flash_host_inst_t *host, uint32_t *id);
     /**
      * Erase whole flash chip.
      */
-    void (*erase_chip)(spi_flash_host_driver_t *driver);
+    void (*erase_chip)(spi_flash_host_inst_t *host);
     /**
      * Erase a specific sector by its start address.
      */
-    void (*erase_sector)(spi_flash_host_driver_t *driver, uint32_t start_address);
+    void (*erase_sector)(spi_flash_host_inst_t *host, uint32_t start_address);
     /**
      * Erase a specific block by its start address.
      */
-    void (*erase_block)(spi_flash_host_driver_t *driver, uint32_t start_address);
+    void (*erase_block)(spi_flash_host_inst_t *host, uint32_t start_address);
     /**
      * Read the status of the flash chip.
      */
-    esp_err_t (*read_status)(spi_flash_host_driver_t *driver, uint8_t *out_sr);
+    esp_err_t (*read_status)(spi_flash_host_inst_t *host, uint8_t *out_sr);
     /**
      * Disable write protection.
      */
-    esp_err_t (*set_write_protect)(spi_flash_host_driver_t *driver, bool wp);
+    esp_err_t (*set_write_protect)(spi_flash_host_inst_t *host, bool wp);
     /**
      * Program a page of the flash. Check ``max_write_bytes`` for the maximum allowed writing length.
      */
-    void (*program_page)(spi_flash_host_driver_t *driver, const void *buffer, uint32_t address, uint32_t length);
-    /** Check whether need to allocate new buffer to write */
-    bool (*supports_direct_write)(spi_flash_host_driver_t *driver, const void *p);
-    /** Check whether need to allocate new buffer to read */
-    bool (*supports_direct_read)(spi_flash_host_driver_t *driver, const void *p);
-    /** maximum length of program_page */
-    int max_write_bytes;
+    void (*program_page)(spi_flash_host_inst_t *host, const void *buffer, uint32_t address, uint32_t length);
+    /** Check whether given buffer can be directly used to write */
+    bool (*supports_direct_write)(spi_flash_host_inst_t *host, const void *p);
+    /**
+     * Slicer for write data. The `program_page` should be called iteratively with the return value
+     * of this function.
+     *
+     * @param address Beginning flash address to write
+     * @param len Length request to write
+     * @param align_addr Output of the aligned address to write to
+     * @param page_size Physical page size of the flash chip
+     * @return Length that can be actually written in one `program_page` call
+     */
+    int (*write_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr,
+                             uint32_t page_size);
     /**
      * Read data from the flash. Check ``max_read_bytes`` for the maximum allowed reading length.
      */
-    esp_err_t (*read)(spi_flash_host_driver_t *driver, void *buffer, uint32_t address, uint32_t read_len);
-    /** maximum length of read */
-    int max_read_bytes;
+    esp_err_t (*read)(spi_flash_host_inst_t *host, void *buffer, uint32_t address, uint32_t read_len);
+    /** Check whether given buffer can be directly used to read */
+    bool (*supports_direct_read)(spi_flash_host_inst_t *host, const void *p);
+    /**
+     * Slicer for read data. The `read` should be called iteratively with the return value
+     * of this function.
+     *
+     * @param address Beginning flash address to read
+     * @param len Length request to read
+     * @param align_addr Output of the aligned address to read
+     * @param page_size Physical page size of the flash chip
+     * @return Length that can be actually read in one `read` call
+     */
+    int (*read_data_slicer)(spi_flash_host_inst_t *host, uint32_t address, uint32_t len, uint32_t *align_addr, uint32_t page_size);
     /**
      * Check whether the host is idle to perform new operations.
      */
-    bool (*host_idle)(spi_flash_host_driver_t *driver);
+    bool (*host_idle)(spi_flash_host_inst_t *host);
     /**
      * Configure the host to work at different read mode. Responsible to compensate the timing and set IO mode.
      */
-    esp_err_t (*configure_host_io_mode)(spi_flash_host_driver_t *driver, uint32_t command,
+    esp_err_t (*configure_host_io_mode)(spi_flash_host_inst_t *host, uint32_t command,
                                         uint32_t addr_bitlen, int dummy_bitlen_base,
                                         esp_flash_io_mode_t io_mode);
     /**
      *  Internal use, poll the HW until the last operation is done.
      */
-    void (*poll_cmd_done)(spi_flash_host_driver_t *driver);
+    void (*poll_cmd_done)(spi_flash_host_inst_t *host);
     /**
      * For some host (SPI1), they are shared with a cache. When the data is
      * modified, the cache needs to be flushed. Left NULL if not supported.
      */
-    esp_err_t (*flush_cache)(spi_flash_host_driver_t* driver, uint32_t addr, uint32_t size);
+    esp_err_t (*flush_cache)(spi_flash_host_inst_t* host, uint32_t addr, uint32_t size);
 };
 
 #ifdef __cplusplus

components/soc/src/hal/spi_flash_hal.c

@@ -63,7 +63,7 @@ static inline int get_dummy_n(bool gpio_is_used, int input_delay_ns, int eff_clk
     return apb_period_n / apbclk_n;
 }
 
-esp_err_t spi_flash_hal_init(spi_flash_memspi_data_t *data_out, const spi_flash_memspi_config_t *cfg)
+esp_err_t spi_flash_hal_init(spi_flash_hal_context_t *data_out, const spi_flash_hal_config_t *cfg)
 {
     if (!esp_ptr_internal(data_out)) {
         return ESP_ERR_INVALID_ARG;
@@ -77,7 +77,8 @@ esp_err_t spi_flash_hal_init(spi_flash_memspi_data_t *data_out, const spi_flash_
     }
 #endif
 
-    *data_out = (spi_flash_memspi_data_t) {
+    *data_out = (spi_flash_hal_context_t) {
+        .inst = data_out->inst, // Keeps the function pointer table
         .spi = spi_flash_ll_get_hw(cfg->host_id),
         .cs_num = cfg->cs_num,
         .extra_dummy = get_dummy_n(!cfg->iomux, cfg->input_delay_ns, clock_cfg.freq),
@@ -88,18 +89,18 @@ esp_err_t spi_flash_hal_init(spi_flash_memspi_data_t *data_out, const spi_flash_
     return ESP_OK;
 }
 
-bool spi_flash_hal_supports_direct_write(spi_flash_host_driver_t *host, const void *p)
+bool spi_flash_hal_supports_direct_write(spi_flash_host_inst_t *host, const void *p)
 {
-    bool direct_write = ( ((spi_flash_memspi_data_t *)host->driver_data)->spi != spi_flash_ll_get_hw(SPI_HOST)
+    bool direct_write = ( ((spi_flash_hal_context_t *)host)->spi != spi_flash_ll_get_hw(SPI_HOST)
                           || esp_ptr_in_dram(p) );
     return direct_write;
 }
 
 
-bool spi_flash_hal_supports_direct_read(spi_flash_host_driver_t *host, const void *p)
+bool spi_flash_hal_supports_direct_read(spi_flash_host_inst_t *host, const void *p)
 {
   //currently the host doesn't support to read through dma, no word-aligned requirements
-    bool direct_read = ( ((spi_flash_memspi_data_t *)host->driver_data)->spi != spi_flash_ll_get_hw(SPI_HOST)
+    bool direct_read = ( ((spi_flash_hal_context_t *)host)->spi != spi_flash_ll_get_hw(SPI_HOST)
                          || esp_ptr_in_dram(p) );
     return direct_read;
 }