spi_flash: added programming guide for ESP-IDF vs ESP-ROM flash driver

espressif · Mar 9, 2023 · 75629ee · 75629ee
1 parent d35b6dd
commit 75629ee
Show file tree

Hide file tree

Showing 6 changed files with 75 additions and 1 deletion.
diff --git a/docs/en/api-guides/performance/ram-usage.rst b/docs/en/api-guides/performance/ram-usage.rst
@@ -134,7 +134,7 @@ The following options will reduce IRAM usage of some ESP-IDF features:
     - Enable :ref:`CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH`. Provided these functions are not (incorrectly) used from ISRs, this option is safe to enable in all configurations.
     - Enable :ref:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`. This option is not safe to use if the ISR ringbuf functions are used from an IRAM interrupt context, e.g. if :ref:`CONFIG_UART_ISR_IN_IRAM` is enabled. For the IDF drivers where this is the case you will get an error at run-time when installing the driver in question.
     :SOC_WIFI_SUPPORTED: - Disable Wi-Fi options :ref:`CONFIG_ESP_WIFI_IRAM_OPT` and/or :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT`. Disabling these options will free available IRAM at the cost of Wi-Fi performance.
-    :esp32c3 or esp32s3: - :ref:`CONFIG_SPI_FLASH_ROM_IMPL` enabling this option will free some IRAM but will mean that esp_flash bugfixes and new flash chip support is not available.
+    :CONFIG_ESP_ROM_HAS_SPI_FLASH: - :ref:`CONFIG_SPI_FLASH_ROM_IMPL` enabling this option will free some IRAM but will mean that esp_flash bugfixes and new flash chip support is not available, see :doc:`/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom` for details.
     :esp32: - :ref:`CONFIG_SPI_FLASH_ROM_DRIVER_PATCH` disabling this option will free some IRAM but is only available in some flash configurations (see the configuration item help text).
     :esp32: - If the application uses PSRAM and is based on ESP32 rev. 3 (ECO3), setting :ref:`CONFIG_ESP32_REV_MIN` to ``3`` will disable PSRAM bug workarounds, saving ~10kB or more of IRAM.
     - Disabling :ref:`CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR` prevents posting ``esp_event`` events from :ref:`iram-safe-interrupt-handlers` but will save some IRAM.

diff --git a/docs/en/api-reference/peripherals/spi_flash/index.rst b/docs/en/api-reference/peripherals/spi_flash/index.rst
@@ -250,6 +250,20 @@ Additionally, all API functions are protected with a mutex (``s_flash_op_mutex``
 
 In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need to disable both caches, so that no inter-CPU communication can take place.
 
+
+.. toctree::
+    :hidden:
+
+    spi_flash_idf_vs_rom
+
+.. only:: CONFIG_ESP_ROM_HAS_SPI_FLASH
+
+    ESP-IDF vs Chip-ROM SPI Flash Driver
+    ------------------------------------
+
+    Refer to :doc:`spi_flash_idf_vs_rom`.
+
+
 API Reference - SPI Flash
 -------------------------
 

diff --git a/docs/en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst b/docs/en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst
@@ -0,0 +1,37 @@
+SPI Flash API ESP-IDF version vs Chip-ROM version
+=================================================
+
+.. toctree::
+   :maxdepth: 1
+
+There is a set of SPI Flash drivers in Chip-ROM which you can use by enabling  :ref:`CONFIG_SPI_FLASH_ROM_IMPL`. Most of the ESP-IDF SPI Flash driver code are in internal RAM, therefore enabling this option will free some internal RAM usage. Note if you enable this option, this means some SPI Flash driver features and bugfixes that are done in ESP-IDF might not be included in the Chip-ROM version.
+
+
+Feature Supported by ESP-IDF but not in Chip-ROM
+------------------------------------------------
+
+.. list::
+
+    - Octal Flash chip support. See :ref:`oct-flash-doc` for details.
+    - 32-bit-address support for GD25Q256. See :ref:`32-bit-flash-doc` for details.
+    - TH Flash chip support.
+    - Kconfig option :ref:`CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED`.
+    - :ref:`CONFIG_SPI_FLASH_VERIFY_WRITE`, enabling this option helps you detect bad writing.
+    - :ref:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`, enabling this option will print the bad writing.
+    - :ref:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`, enabling this option will check if you're writing zero to one.
+    :esp32h2 or esp32c6: - Flash MMAP driver isn't ready in Chip-ROM.
+
+
+Bugfixes Introduced in ESP-IDF but not in Chip-ROM
+--------------------------------------------------
+
+.. list::
+
+    - Detected Flash physical size correctly, for larger than 256MBit Flash chips. (Commit ID: b4964279d44f73cce7cfd5cf684567fbdfd6fd9e)
+    :esp32c3: - Improved SPI1 cs setup timing, otherwise issue may happen on ZB32Q128. (Commit ID: 08f1bbe0c75382f1702e40c941e93314285105d4)
+    :esp32s3: - Fixed issue that 4-line Flash encryption cannot work normally when 8-line PSRAM enabled. (Commit ID: 683d92bc884e0f2a7eebea40a551cf05f0c28256)
+    :esp32s2: - Fixed issue that only 4MB virtual address ranges can be mapped to read-only data on Flash.
+    :esp32s3: - Fixed issue that only 128KB virtual address ranges can be mapped to instructions on Flash.
+    :esp32s3: - Fixed issue that only 16MB virtual address ranges can be mapped to read-only data on Flash.
+    :esp32c3: - Fixed issue that only 128KB virtual address ranges can be mapped to instructions on Flash.
+    :esp32c2: - Fixed issue that only at most 128KB virtual address ranges can be mapped to instructions on Flash.
diff --git a/docs/en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst b/docs/en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst
@@ -59,6 +59,8 @@ Flash Chips List:
 6. XMC
 7. BOYA
 
+.. _hpm-doc:
+
 High performance mode
 ---------------------
 
@@ -83,6 +85,9 @@ Flash Chips (name & ID) List:
 
     It is hard to create several strategies to cover all situations, so all flash chips using HPM need to be supported explicitly. Therefore, if you try to use a flash not listed as supported under high performance mode, it might cause some error. So, when you try to use the flash chip beyond supported list, please test properly.
 
+
+.. _oct-flash-doc:
+
 OPI flash support
 -----------------
 
@@ -102,6 +107,9 @@ Flash Chips List:
 
 1. MX25UM25645G
 
+
+.. _32-bit-flash-doc:
+
 32-bit Address Flash Chips
 --------------------------
 

diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst
@@ -250,6 +250,20 @@ Flash 操作完成后，CPU A 上的函数将设置另一标志位，即 ``s_fla
 
 在单核环境中（启用 :ref:`CONFIG_FREERTOS_UNICORE`），您需要禁用上述两个 cache 以防发生 CPU 间通信。
 
+
+.. toctree::
+    :hidden:
+
+    spi_flash_idf_vs_rom
+
+.. only:: CONFIG_ESP_ROM_HAS_SPI_FLASH
+
+    ESP-IDF 和 Chip-ROM 版本 SPI Flash 驱动对比
+    -----------------------------------------------------------------
+
+    请参考 :doc:`spi_flash_idf_vs_rom`.
+
+
 SPI Flash API 参考
 -------------------------
 

diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst
@@ -0,0 +1 @@
+.. include:: /../en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst