From fecf27e54c318dc3bd2707486529a213ce8f6823 Mon Sep 17 00:00:00 2001
From: Cao Sen Miao <caosenmiao@espressif.com>
Date: Tue, 18 May 2021 12:05:41 +0800
Subject: [PATCH] spi_flash: add support for 32Mbit address GD flash, for
 GD25Q256

---
 components/spi_flash/esp_flash_api.c          | 29 ++++++++++++++
 .../spi_flash/include/spi_flash_chip_driver.h | 13 +++++++
 .../include/spi_flash_chip_generic.h          |  2 +-
 components/spi_flash/spi_flash_chip_boya.c    | 11 ++++++
 components/spi_flash/spi_flash_chip_gd.c      | 39 +++++++++++++++++--
 components/spi_flash/spi_flash_chip_generic.c | 17 ++++++++
 components/spi_flash/spi_flash_chip_issi.c    | 11 ++++++
 components/spi_flash/spi_flash_chip_mxic.c    | 10 +++++
 components/spi_flash/spi_flash_chip_winbond.c | 14 +++++++
 docs/en/api-reference/storage/spi_flash.rst   |  1 +
 .../storage/spi_flash_override_driver.rst     | 29 ++++++++++++++
 .../zh_CN/api-reference/storage/spi_flash.rst |  1 +
 .../custom_chip_driver/spi_flash_chip_eon.c   | 10 +++++
 13 files changed, 182 insertions(+), 5 deletions(-)

diff --git a/components/spi_flash/esp_flash_api.c b/components/spi_flash/esp_flash_api.c
index a5301d4a59..33f69c7af7 100644
--- a/components/spi_flash/esp_flash_api.c
+++ b/components/spi_flash/esp_flash_api.c
@@ -218,6 +218,16 @@ esp_err_t IRAM_ATTR esp_flash_init(esp_flash_t *chip)
         return err;
     }
 
+    if (chip->chip_drv->get_chip_caps == NULL) {
+        // chip caps get failed, pass the flash capability check.
+        ESP_EARLY_LOGW(TAG, "get_chip_caps function pointer hasn't been initialized");
+    } else {
+        if (((chip->chip_drv->get_chip_caps(chip) & SPI_FLASH_CHIP_CAP_32MB_SUPPORT) == 0) && (size > (16 *1024 * 1024))) {
+            ESP_EARLY_LOGW(TAG, "Detected flash size > 16 MB, but access beyond 16 MB is not supported for this flash model yet.");
+            size = (16 * 1024 * 1024);
+        }
+    }
+
     ESP_LOGI(TAG, "flash io: %s", io_mode_str[chip->read_mode]);
     err = rom_spiflash_api_funcs->start(chip);
     if (err != ESP_OK) {
@@ -307,6 +317,16 @@ esp_err_t esp_flash_read_unique_chip_id(esp_flash_t *chip, uint64_t* out_uid)
     if (err != ESP_OK) {
         return err;
     }
+    if (chip->chip_drv->get_chip_caps == NULL) {
+        // chip caps get failed, pass the flash capability check.
+        ESP_EARLY_LOGW(TAG, "get_chip_caps function pointer hasn't been initialized");
+    } else {
+        if ((chip->chip_drv->get_chip_caps(chip) & SPI_FLASH_CHIP_CAP_UNIQUE_ID) == 0) {
+            ESP_EARLY_LOGE(TAG, "chip %s doesn't support reading unique id", chip->chip_drv->name);
+            return ESP_ERR_NOT_SUPPORTED;
+        }
+    }
+
     if (out_uid == NULL) {
         return ESP_ERR_INVALID_ARG;
     };
@@ -386,6 +406,7 @@ esp_err_t IRAM_ATTR esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size)
     err = chip->chip_drv->detect_size(chip, &detect_size);
     if (err == ESP_OK) {
         chip->size = detect_size;
+        *out_size = chip->size;
     }
     return rom_spiflash_api_funcs->end(chip, err);
 }
@@ -969,6 +990,14 @@ IRAM_ATTR esp_err_t esp_flash_set_io_mode(esp_flash_t* chip, bool qe)
 esp_err_t esp_flash_suspend_cmd_init(esp_flash_t* chip)
 {
     ESP_EARLY_LOGW(TAG, "Flash suspend feature is enabled");
+    if (chip->chip_drv->get_chip_caps == NULL) {
+        // chip caps get failed, pass the flash capability check.
+        ESP_EARLY_LOGW(TAG, "get_chip_caps function pointer hasn't been initialized");
+    } else {
+        if ((chip->chip_drv->get_chip_caps(chip) & SPI_FLASH_CHIP_CAP_SUSPEND) == 0) {
+            ESP_EARLY_LOGW(TAG, "Suspend and resume may not supported for this flash model yet.");
+        }
+    }
     return chip->chip_drv->sus_setup(chip);
 }
 
diff --git a/components/spi_flash/include/spi_flash_chip_driver.h b/components/spi_flash/include/spi_flash_chip_driver.h
index 6356291b78..9a143d84d2 100644
--- a/components/spi_flash/include/spi_flash_chip_driver.h
+++ b/components/spi_flash/include/spi_flash_chip_driver.h
@@ -14,6 +14,7 @@
 
 #pragma once
 #include "esp_flash.h"
+#include "esp_attr.h"
 
 struct esp_flash_t;
 typedef struct esp_flash_t esp_flash_t;
@@ -33,6 +34,13 @@ typedef enum {
     SPI_FLASH_REG_STATUS = 1,
 } spi_flash_register_t;
 
+typedef enum {
+   SPI_FLASH_CHIP_CAP_SUSPEND = BIT(0),            ///< Flash chip support suspend feature.
+   SPI_FLASH_CHIP_CAP_32MB_SUPPORT = BIT(1),       ///< Flash chip driver support flash size larger than 32M Bytes.
+   SPI_FLASH_CHIP_CAP_UNIQUE_ID = BIT(2),          ///< Flash chip driver support read the flash unique id.
+} spi_flash_caps_t;
+FLAG_ATTR(spi_flash_caps_t)
+
 /** @brief SPI flash chip driver definition structure.
  *
  * The chip driver structure contains chip-specific pointers to functions to perform SPI flash operations, and some
@@ -193,6 +201,11 @@ struct spi_flash_chip_t {
      * Read the chip unique ID.
      */
     esp_err_t (*read_unique_id)(esp_flash_t *chip, uint64_t* flash_unique_id);
+
+    /**
+     * Get the capabilities of the flash chip. See SPI_FLASH_CHIP_CAP_* macros as reference.
+     */
+    spi_flash_caps_t (*get_chip_caps)(esp_flash_t *chip);
 };
 
 /* Pointer to an array of pointers to all known drivers for flash chips. This array is used
diff --git a/components/spi_flash/include/spi_flash_chip_generic.h b/components/spi_flash/include/spi_flash_chip_generic.h
index 90bfcf7deb..9e99f73e44 100644
--- a/components/spi_flash/include/spi_flash_chip_generic.h
+++ b/components/spi_flash/include/spi_flash_chip_generic.h
@@ -370,7 +370,7 @@ esp_err_t spi_flash_common_set_io_mode(esp_flash_t *chip, esp_flash_wrsr_func_t
  * transactions. Also prepare the command to be sent in read functions.
  *
  * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
- * @param addr_32bit Whether 32 bit commands will be used (Currently only W25Q256 is supported)
+ * @param addr_32bit Whether 32 bit commands will be used (Currently only W25Q256 and GD25Q256 are supported)
  *
  * @return
  *      - ESP_OK if success
diff --git a/components/spi_flash/spi_flash_chip_boya.c b/components/spi_flash/spi_flash_chip_boya.c
index 3a496d61c7..f87c337585 100644
--- a/components/spi_flash/spi_flash_chip_boya.c
+++ b/components/spi_flash/spi_flash_chip_boya.c
@@ -34,6 +34,16 @@ esp_err_t spi_flash_chip_boya_probe(esp_flash_t *chip, uint32_t flash_id)
     return ESP_OK;
 }
 
+spi_flash_caps_t spi_flash_chip_boya_get_caps(esp_flash_t *chip)
+{
+    spi_flash_caps_t caps_flags = 0;
+    // 32-bit-address flash is not supported
+    // flash-suspend is not supported
+    // flash read unique id.
+    caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID;
+    return caps_flags;
+}
+
 static const char chip_name[] = "boya";
 
 // The BOYA chip can use the functions for generic chips except from set read mode and probe,
@@ -72,4 +82,5 @@ const spi_flash_chip_t esp_flash_chip_boya = {
     .yield = spi_flash_chip_generic_yield,
     .sus_setup = spi_flash_chip_generic_suspend_cmd_conf,
     .read_unique_id = spi_flash_chip_generic_read_unique_id,
+    .get_chip_caps = spi_flash_chip_boya_get_caps,
 };
diff --git a/components/spi_flash/spi_flash_chip_gd.c b/components/spi_flash/spi_flash_chip_gd.c
index 936de0412e..509e008f55 100644
--- a/components/spi_flash/spi_flash_chip_gd.c
+++ b/components/spi_flash/spi_flash_chip_gd.c
@@ -13,10 +13,40 @@
 // limitations under the License.
 
 #include <stdlib.h>
+#include <string.h>
+#include <sys/param.h> // For MIN/MAX
+#include "esp_log.h"
 #include "spi_flash_chip_generic.h"
 #include "spi_flash_chip_gd.h"
 #include "spi_flash_defs.h"
 
+#define ADDR_32BIT(addr)            (addr >= (1<<24))
+
+#define REGION_32BIT(start, len)    ((start) + (len) > (1<<24))
+
+extern esp_err_t spi_flash_chip_winbond_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length);
+extern esp_err_t spi_flash_chip_winbond_page_program(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
+extern esp_err_t spi_flash_chip_winbond_erase_sector(esp_flash_t *chip, uint32_t start_address);
+extern esp_err_t spi_flash_chip_winbond_erase_block(esp_flash_t *chip, uint32_t start_address);
+
+#define spi_flash_chip_gd_read spi_flash_chip_winbond_read
+#define spi_flash_chip_gd_page_program spi_flash_chip_winbond_page_program
+#define spi_flash_chip_gd_erase_sector spi_flash_chip_winbond_erase_sector
+#define spi_flash_chip_gd_erase_block spi_flash_chip_winbond_erase_block
+
+spi_flash_caps_t spi_flash_chip_gd_get_caps(esp_flash_t *chip)
+{
+    spi_flash_caps_t caps_flags = 0;
+    // 32M-bits address support
+    if ((chip->chip_id & 0xFF) >= 0x19) {
+        caps_flags |= SPI_FLASH_CHIP_CAP_32MB_SUPPORT;
+    }
+    // flash-suspend is not supported
+    // flash read unique id.
+    caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID;
+    return caps_flags;
+}
+
 #ifndef CONFIG_SPI_FLASH_ROM_IMPL
 
 #define FLASH_ID_MASK       0xFF00
@@ -86,8 +116,8 @@ const spi_flash_chip_t esp_flash_chip_gd = {
     .reset = spi_flash_chip_generic_reset,
     .detect_size = spi_flash_chip_generic_detect_size,
     .erase_chip = spi_flash_chip_generic_erase_chip,
-    .erase_sector = spi_flash_chip_generic_erase_sector,
-    .erase_block = spi_flash_chip_generic_erase_block,
+    .erase_sector = spi_flash_chip_gd_erase_sector,
+    .erase_block = spi_flash_chip_gd_erase_block,
     .sector_size = 4 * 1024,
     .block_erase_size = 64 * 1024,
 
@@ -99,9 +129,9 @@ const spi_flash_chip_t esp_flash_chip_gd = {
     .get_protected_regions = NULL,
     .set_protected_regions = NULL,
 
-    .read = spi_flash_chip_generic_read,
+    .read = spi_flash_chip_gd_read,
     .write = spi_flash_chip_generic_write,
-    .program_page = spi_flash_chip_generic_page_program,
+    .program_page = spi_flash_chip_gd_page_program,
     .page_size = 256,
     .write_encrypted = spi_flash_chip_generic_write_encrypted,
 
@@ -113,4 +143,5 @@ const spi_flash_chip_t esp_flash_chip_gd = {
     .yield = spi_flash_chip_generic_yield,
     .sus_setup = spi_flash_chip_generic_suspend_cmd_conf,
     .read_unique_id = spi_flash_chip_generic_read_unique_id,
+    .get_chip_caps = spi_flash_chip_gd_get_caps,
 };
diff --git a/components/spi_flash/spi_flash_chip_generic.c b/components/spi_flash/spi_flash_chip_generic.c
index 4483a35af9..0dc3062fd5 100644
--- a/components/spi_flash/spi_flash_chip_generic.c
+++ b/components/spi_flash/spi_flash_chip_generic.c
@@ -553,6 +553,22 @@ esp_err_t spi_flash_chip_generic_read_unique_id(esp_flash_t *chip, uint64_t* fla
     return err;
 }
 
+spi_flash_caps_t spi_flash_chip_generic_get_caps(esp_flash_t *chip)
+{
+    // For generic part flash capability, take the XMC chip as reference.
+    spi_flash_caps_t caps_flags = 0;
+    // 32M-bits address support
+
+    // flash suspend support
+    // Only `XMC` support suspend for now.
+    if (chip->chip_id >> 16 == 0x20) {
+        caps_flags |= SPI_FLASH_CHIP_CAP_SUSPEND;
+    }
+    // flash read unique id.
+    caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID;
+    return caps_flags;
+}
+
 static const char chip_name[] = "generic";
 
 const spi_flash_chip_t esp_flash_chip_generic = {
@@ -592,6 +608,7 @@ const spi_flash_chip_t esp_flash_chip_generic = {
     .yield = spi_flash_chip_generic_yield,
     .sus_setup = spi_flash_chip_generic_suspend_cmd_conf,
     .read_unique_id = spi_flash_chip_generic_read_unique_id,
+    .get_chip_caps = spi_flash_chip_generic_get_caps,
 };
 
 #ifndef CONFIG_SPI_FLASH_ROM_IMPL
diff --git a/components/spi_flash/spi_flash_chip_issi.c b/components/spi_flash/spi_flash_chip_issi.c
index 5d9bdcaa3a..e8ae39fcff 100644
--- a/components/spi_flash/spi_flash_chip_issi.c
+++ b/components/spi_flash/spi_flash_chip_issi.c
@@ -58,6 +58,16 @@ esp_err_t spi_flash_chip_issi_get_io_mode(esp_flash_t *chip, esp_flash_io_mode_t
     return ret;
 }
 
+spi_flash_caps_t spi_flash_chip_issi_get_caps(esp_flash_t *chip)
+{
+    spi_flash_caps_t caps_flags = 0;
+    // 32-bit-address flash is not supported
+    // flash-suspend is not supported
+    // flash read unique id.
+    caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID;
+    return caps_flags;
+}
+
 static const char chip_name[] = "issi";
 
 // The issi chip can use the functions for generic chips except from set read mode and probe,
@@ -96,4 +106,5 @@ const spi_flash_chip_t esp_flash_chip_issi = {
     .yield = spi_flash_chip_generic_yield,
     .sus_setup = spi_flash_chip_generic_suspend_cmd_conf,
     .read_unique_id = spi_flash_chip_generic_read_unique_id,
+    .get_chip_caps = spi_flash_chip_issi_get_caps,
 };
diff --git a/components/spi_flash/spi_flash_chip_mxic.c b/components/spi_flash/spi_flash_chip_mxic.c
index 73a1e573be..f88486dfd4 100644
--- a/components/spi_flash/spi_flash_chip_mxic.c
+++ b/components/spi_flash/spi_flash_chip_mxic.c
@@ -47,6 +47,15 @@ esp_err_t spi_flash_chip_mxic_read_unique_id(esp_flash_t *chip, uint64_t* flash_
     return ESP_ERR_NOT_SUPPORTED;
 }
 
+spi_flash_caps_t spi_flash_chip_mxic_get_caps(esp_flash_t *chip)
+{
+    spi_flash_caps_t caps_flags = 0;
+    // 32-bit-address flash is not supported
+    // flash-suspend is not supported
+    // reading unique id is not supported.
+    return caps_flags;
+}
+
 // The mxic chip can use the functions for generic chips except from set read mode and probe,
 // So we only replace these two functions.
 const spi_flash_chip_t esp_flash_chip_mxic = {
@@ -83,4 +92,5 @@ const spi_flash_chip_t esp_flash_chip_mxic = {
     .yield = spi_flash_chip_generic_yield,
     .sus_setup = spi_flash_chip_generic_suspend_cmd_conf,
     .read_unique_id = spi_flash_chip_mxic_read_unique_id,
+    .get_chip_caps = spi_flash_chip_mxic_get_caps,
 };
diff --git a/components/spi_flash/spi_flash_chip_winbond.c b/components/spi_flash/spi_flash_chip_winbond.c
index f7da73b4c6..98e94ae01a 100644
--- a/components/spi_flash/spi_flash_chip_winbond.c
+++ b/components/spi_flash/spi_flash_chip_winbond.c
@@ -140,6 +140,19 @@ esp_err_t spi_flash_chip_winbond_erase_block(esp_flash_t *chip, uint32_t start_a
     return err;
 }
 
+spi_flash_caps_t spi_flash_chip_winbond_get_caps(esp_flash_t *chip)
+{
+    spi_flash_caps_t caps_flags = 0;
+    // 32M-bits address support
+    if ((chip->chip_id & 0xFF) >= 0x19) {
+        caps_flags |= SPI_FLASH_CHIP_CAP_32MB_SUPPORT;
+    }
+    // flash-suspend is not supported
+    // flash read unique id.
+    caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID;
+    return caps_flags;
+}
+
 static const char chip_name[] = "winbond";
 
 // The issi chip can use the functions for generic chips except from set read mode and probe,
@@ -178,6 +191,7 @@ const spi_flash_chip_t esp_flash_chip_winbond = {
     .yield = spi_flash_chip_generic_yield,
     .sus_setup = spi_flash_chip_generic_suspend_cmd_conf,
     .read_unique_id = spi_flash_chip_generic_read_unique_id,
+    .get_chip_caps = spi_flash_chip_winbond_get_caps,
 };
 
 
diff --git a/docs/en/api-reference/storage/spi_flash.rst b/docs/en/api-reference/storage/spi_flash.rst
index 9253dd6903..fbe4baf979 100644
--- a/docs/en/api-reference/storage/spi_flash.rst
+++ b/docs/en/api-reference/storage/spi_flash.rst
@@ -42,6 +42,7 @@ The Quad mode (QIO/QOUT) the following chip types are supported:
 The 32-bit address range of following chip type is supported:
 
 1. W25Q256
+2. GD25Q256
 
 Users can also customize their own flash chip driver, see :doc:`spi_flash_override_driver` for more details.
 
diff --git a/docs/en/api-reference/storage/spi_flash_override_driver.rst b/docs/en/api-reference/storage/spi_flash_override_driver.rst
index f3fd6cf679..8f3e7a84b2 100644
--- a/docs/en/api-reference/storage/spi_flash_override_driver.rst
+++ b/docs/en/api-reference/storage/spi_flash_override_driver.rst
@@ -27,6 +27,35 @@ Steps For Creating Custom Chip Drivers and Overriding the IDF Default Driver Lis
 
    Modify the files above properly.
 
+.. note::
+   - When writing your own flash chip driver, you can set your flash chip capabilities through `spi_flash_chip_***(vendor)_get_caps` and points the function pointer `get_chip_caps` for protection to the `spi_flash_chip_***_get_caps` function. The steps are as follows.
+      
+      1. Please check whether your flash chip have the capabilities listed in `spi_flash_caps_t` by checking the flash datasheet.
+      2. Write a function named `spi_flash_chip_***(vendor)_get_caps`. Take the example below as a reference. (if the flash support `suspend` and `read unique id`).
+      3. Points the the pointer `get_chip_caps` (in `spi_flash_chip_t`) to the function mentioned above.
+
+      .. code-block:: c
+
+         spi_flash_caps_t spi_flash_chip_***(vendor)_get_caps(esp_flash_t *chip)
+         {
+            spi_flash_caps_t caps_flags = 0;
+            // 32-bit-address flash is not supported
+            flash-suspend is supported
+            caps_flags |= SPI_FLAHS_CHIP_CAP_SUSPEND;
+            // flash read unique id.
+            caps_flags |= SPI_FLASH_CHIP_CAP_UNIQUE_ID;
+            return caps_flags;
+         }
+
+      .. code-block:: c
+
+         const spi_flash_chip_t esp_flash_chip_eon = {
+            // Other function pointers
+            .get_chip_caps = spi_flash_chip_eon_get_caps,
+         };
+
+   - You also can see how to implement this in the example :example:`storage/custom_flash_driver`.
+
 4. Add linking dependency from `spi_flash` component to the new `custom_chip_driver` component, by adding the following lines after the `idf_component_register`, in the `CMakeLists.txt` file of the `custom_chip_driver` component:
 
       idf_component_get_property(spi_flash_lib spi_flash COMPONENT_LIB)
diff --git a/docs/zh_CN/api-reference/storage/spi_flash.rst b/docs/zh_CN/api-reference/storage/spi_flash.rst
index 1cdbecaa8d..41dedc34d7 100644
--- a/docs/zh_CN/api-reference/storage/spi_flash.rst
+++ b/docs/zh_CN/api-reference/storage/spi_flash.rst
@@ -41,6 +41,7 @@ Flash 特性支持情况
 当前驱动支持以下厂家/型号的 Flash 的 32 位地址范围的访问：
 
 1. W25Q256
+2. GD25Q256
 
 如果有需要，也可以自定义 Flash 芯片驱动，参见 :doc:`spi_flash_override_driver` 。但此功能仅供专业用户使用。
 
diff --git a/examples/storage/custom_flash_driver/components/custom_chip_driver/spi_flash_chip_eon.c b/examples/storage/custom_flash_driver/components/custom_chip_driver/spi_flash_chip_eon.c
index 28d6711c79..dd2bf25486 100644
--- a/examples/storage/custom_flash_driver/components/custom_chip_driver/spi_flash_chip_eon.c
+++ b/examples/storage/custom_flash_driver/components/custom_chip_driver/spi_flash_chip_eon.c
@@ -108,6 +108,15 @@ esp_err_t spi_flash_chip_eon_suspend_cmd_conf(esp_flash_t *chip)
     return ESP_ERR_NOT_SUPPORTED;
 }
 
+spi_flash_caps_t spi_flash_chip_eon_get_caps(esp_flash_t *chip)
+{
+    spi_flash_caps_t caps_flags = 0;
+    // 32-bit-address flash is not supported
+    // flash-suspend is not supported
+    // flash read unique id is not supported.
+    return caps_flags;
+}
+
 // The issi chip can use the functions for generic chips except from set read mode and probe,
 // So we only replace these two functions.
 const spi_flash_chip_t esp_flash_chip_eon = {
@@ -143,4 +152,5 @@ const spi_flash_chip_t esp_flash_chip_eon = {
     .read_reg = spi_flash_chip_generic_read_reg,
     .yield = spi_flash_chip_generic_yield,
     .sus_setup = spi_flash_chip_eon_suspend_cmd_conf,
+    .get_chip_caps = spi_flash_chip_eon_get_caps,
 };