Merge branch 'docs/translate_spi_flash_optional_feature' into 'master'

Docs/Provide Chinese translation for spi-flash-optional-feature

Closes DOC-8198

See merge request espressif/esp-idf!31743
This commit is contained in:
Shen Meng Jing 2024-08-08 11:47:20 +08:00
commit 77c7ec97c6
2 changed files with 235 additions and 38 deletions

View File

@ -1,61 +1,63 @@
Optional Features for Flash
===========================
Some features are not supported on all ESP chips and Flash chips. You can check the list below for more information.
:link_to_translation:`zh_CN:[中文]`
- `Auto Suspend & Resume <#auto-suspend-&-resume>`__
Some features are not supported on all ESP chips and flash chips. You can check the list below for more information:
- `Flash unique ID <#flash-unique-id>`__
- :ref:`auto-suspend-intro`
- `High Performance Mode of QSPI Flash Chips <#high-performance-mode>`__
- :ref:`flash-unique-id`
- `32-bit Address Support of QSPI Flash Chips <#32-bit-address-flash-chips>`__
- :ref:`high-performance-mode`
- `OPI Flash Support <#opi-flash-support>`__
- :ref:`32-bit-flash-doc`
- :ref:`oct-flash-doc`
.. note::
When Flash optional features listed in this page are used, aside from the capability of ESP chips, and ESP-IDF version you are using, you will also need to make sure these features are supported by flash chips used.
When Flash optional features listed in this page are used, aside from the capability of ESP chips and ESP-IDF version you are using, you will also need to make sure these features are supported by flash chips used:
- If you are using an official Espressif modules/SiP. Some of the modules/SiPs always support the feature, in this case you can see these features listed in the datasheet. Otherwise please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_ to know if we can supply such products for you.
- If you are using an official Espressif modules/SiP, please make sure that they support the above features by referring to the `datasheet <https://www.espressif.com/en/support/download/documents/modules>`__. Otherwise, please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_ to know if we can supply such products for you.
- If you are making your own modules with your own bought flash chips, and you need features listed above. Please contact your vendor if they support the those features, and make sure that the chips can be supplied continuously.
- If you are making your own modules with your own bought flash chips and need features listed above, please contact your vendor to see if they support those features, and make sure that the chips can be supplied continuously.
.. attention::
This document only shows that ESP-IDF code has supported the features of those flash chips. It is not a list of stable flash chips certified by Espressif. If you build your own hardware from flash chips with your own brought flash chips (even with flash listed in this page), you need to validate the reliability of flash chips yourself.
This document only shows that ESP-IDF code has supported the features of those flash chips. It is not a list of stable flash chips certified by Espressif. If you build your own hardware with your own brought flash chips (even with features listed in this page), you need to validate the reliability of flash chips yourself.
.. _auto-suspend-intro:
Auto Suspend & Resume
---------------------
This feature is only supported on ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C6, ESP32-H2 for now.
This feature is only supported on ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C6, and ESP32-H2 for now.
The support for ESP32-P4 may be added in the future.
.. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND
List of Flash chips that support this feature:
List of flash chips that support this feature:
1. XM25QxxC series.
2. GD25QxxE series.
1. XM25QxxC series
2. GD25QxxE series
3. FM25Q32
.. attention::
There are multiple limitations about the auto-suspend feature, please do read :ref:`auto-suspend` for more information before you enable this feature.
.. _flash-unique-id:
Flash Unique ID
---------------
This feature is supported on all Espressif chips.
Unique ID is not flash id, which means flash has 64-Bit unique ID for each device. The instruction to read the unique ID (4Bh) accesses a factory-set read-only 64-bit number that is unique to each flash device. This ID number helps you to recognize each single device. Not all flash vendors support this feature. If you try to read the unique ID on a chip which does not have this feature, the behavior is not determined. The support list is as follows.
Unique ID is not flash id, which means flash has 64-bit unique ID for each device. The instruction to read the unique ID (4Bh) accesses a factory-set read-only 64-bit number that is unique to each flash device. This ID number helps you to recognize each device. Not all flash vendors support this feature. If you try to read the unique ID on a chip which does not have this feature, the behavior is not determined.
List of Flash chips that support this feature:
List of flash chips that support this feature:
1. ISSI
2. GD
@ -65,54 +67,54 @@ List of Flash chips that support this feature:
6. XMC
7. BOYA
.. _hpm-doc:
.. _high-performance-mode:
High Performance Mode of QSPI Flash Chips
-----------------------------------------
This featuer is only supported on ESP32-S3 for now.
This feature is only supported on ESP32-S3 for now.
The support for ESP32-S2, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4 may be added in the future.
The support for ESP32-S2, ESP32-C3, ESP32-C6, ESP32-H2, and ESP32-P4 may be added in the future.
.. note::
This section is provided for QSPI flash chips. Octal flash used on ESP-chips support High performance mode by default so far, please refer to the :ref:`oct-flash-doc` for the list of supported octal flash chips.
This section is provided for QSPI flash chips. Octal flash used on ESP-chips supports High Performance mode by default so far, please refer to :ref:`oct-flash-doc` for the list of supported octal flash chips.
.. only:: esp32s3
High performance mode (HPM) means that the SPI1 and flash chip works under high frequency. Usually, when the operating frequency of the flash is greater than 80 MHz, it is considered that the flash works under HPM.
High Performance mode (HPM) means that the SPI1 and flash chip works under high frequency. Usually, when the operating frequency of the flash is greater than 80 MHz, it is considered that the flash works under HPM.
As far as we acknowledged, there are more than three strategies for High Performance Mode (HPM) in typical SPI flash parts. For some flash chips, HPM is controlled by dummy cycle bit in the registers, while for other chips, it can be controlled by other bits (like HPM bit) in the register, or some special command. The difference in strategies requires the driver to explicitly add support for each chip.
As far as we acknowledged, there are more than three strategies for HPM in typical SPI flash parts. For some flash chips, HPM is controlled by dummy cycle (DC) bit in the registers, while for other chips, it can be controlled by other bits (like HPM bit) in the register, or some special command. The difference in strategies requires the driver to explicitly add support for each chip.
.. attention::
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 in :ref:`hpm_dc_support_list`, it might cause some error. So, when you try to use the flash chip beyond supported list, please test properly.
Moreover, when the `Dummy Cycle adjustment` strategy is adopted by the flash chip, the flash remains in a state in which DC is different from the default value after a software reset. The sub mode of HPM that adjusts the dummy cycle to run at higher frequency in the application is called `HPM-DC`. `HPM-DC` feature needs a feature `DC Aware` to be enabled in the bootloader. Otherwise different DC value will forbid the 2nd bootloader from being boot up after reset.
Moreover, when the `DC adjustment` strategy is adopted by the flash chip, the flash remains in a state in which DC is different from the default value after a software reset. The sub mode of HPM that adjusts the DC to run at higher frequency in the application is called `HPM-DC`. `HPM-DC` feature needs a feature `DC Aware` to be enabled in the bootloader. Otherwise different DC value will forbid the 2nd bootloader from being boot up after reset.
To enable High Performance Mode:
To enable High Performance mode:
1. De-select :ref:`CONFIG_ESPTOOLPY_OCT_FLASH` and :ref:`CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT`. HPM is not used for Octal flash, enabling related options may bypass HPM functions.
2. Enable ``CONFIG_SPI_FLASH_HPM_ENA`` option.
3. Switch Flash frequency to HPM ones. For example, ``CONFIG_ESPTOOLPY_FLASHFREQ_120M``.
3. Switch flash frequency to HPM ones. For example, ``CONFIG_ESPTOOLPY_FLASHFREQ_120M``.
4. Make sure the config option for `HPM-DC` feature (under ``CONFIG_SPI_FLASH_HPM_DC`` choices) is selected correctly according to whether the bootloader supports `DC Aware`.
- If bootloader supports `DC Aware`, select ``CONFIG_SPI_FLASH_HPM_DC_AUTO``. This allows the usage of flash chips that adopted `Dummy Cycle adjustment` strategy.
- If bootloader supports `DC Aware`, select ``CONFIG_SPI_FLASH_HPM_DC_AUTO``. This allows the usage of flash chips that adopted `DC adjustment` strategy.
- If bootloader doesn't support `DC Aware`, select ``CONFIG_SPI_FLASH_HPM_DC_DISABLE``. It avoid consequences caused by running HPM-DC with non-DC-aware bootloaders. But please avoid using flash chips that adopts `Dummy Cycle adjustment` strategy if ``CONFIG_SPI_FLASH_HPM_DC_DISABLE`` is selected. See list of flash models that adpot DC strategy below.
- If bootloader doesn't support `DC Aware`, select ``CONFIG_SPI_FLASH_HPM_DC_DISABLE``. It avoids consequences caused by running `HPM-DC` with non-DC-aware bootloaders. But please avoid using flash chips that adopts `DC adjustment` strategy if ``CONFIG_SPI_FLASH_HPM_DC_DISABLE`` is selected. See list of flash models that adpot DC strategy below.
Check whether the bootloader supports `DC Aware` in the following way:
- If you are starting a new project, it's suggested to enable `DC Aware` by selecting :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` option in the bootloader menu. Please note that, you won't be able to modify this option via OTA, because the support is in the bootloader.
- If you are working on an existing project and want to update `HPM-DC` config option in the app via OTA, check the sdkconfig file used to build your bootloader: (Upgrading ESP-IDF version may make this file different from the one used by bootloader to build.)
- If you are working on an existing project and want to update `HPM-DC` config option in the app via OTA, check the sdkconfig file used to build your bootloader (upgrading ESP-IDF version may make this file different from the one used by bootloader to build):
- For latest version (ESP-IDF v5.2 and above), if :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` is selected, the bootloader supports `DC Aware`.
- For versions in this range: (v4.4.4+, v5.0+, and v5.1+), if ``CONFIG_ESPTOOLPY_FLASHFREQ_120M`` is selected, the bootloader supports `DC Aware`. In this case, enable :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` to confirm this (though it will not affect bootloader in devices in the field).
- For other versions (v4.4.4+, v5.0+, and v5.1+), if ``CONFIG_ESPTOOLPY_FLASHFREQ_120M`` is selected, the bootloader supports `DC Aware`. In this case, enable :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` to confirm this (though it will not affect bootloader in devices in the field).
- For versions below v4.4.4, the bootloader doesn't support `DC Aware`.
@ -145,9 +147,9 @@ This feature is supported on all Espressif chips (see restrictions to applicatio
.. note::
This section is provided for QSPI flash chips. The 32-bit address support of Octal Flash chips are considered as part of the Octal flash support. Please refer to the :ref:`oct-flash-doc` for the list of supported octal flash chips.
This section is provided for QSPI flash chips. The 32-bit address support of Octal flash chips are considered as part of the Octal flash support. Please refer to :ref:`oct-flash-doc` for the list of supported octal flash chips.
Most NOR flash chips used by Espressif chips use 24-bits address, which can cover 16 MBytes memory. However, for larger memory (usually equal to or larger than 32 MBytes), flash uses a 32-bits address to address memory region higher than 16 MBytes. Unfortunately, 32-bits address chips have vendor-specific commands, so we need to support the chips one by one.
Most NOR flash chips used by Espressif chips use 24-bits address, which can cover 16 MB memory. However, for larger memory (usually equal to or larger than 32 MB), flash uses a 32-bits address to address memory region higher than 16 MB. Unfortunately, 32-bits address chips have vendor-specific commands, so we need to support the chips one by one.
List of Flash chips that support this feature:
@ -161,17 +163,17 @@ Restrictions
.. important::
Over 16 MBytes space on flash mentioned above can be only used for ``data saving``, like file system.
Over 16 MB space on flash mentioned above can be only used for ``data saving``, like file system.
Mapping data/instructions to 32-bit physical address space (so as to be accessed by the CPU) needs the support of MMU. However {IDF_TARGET_NAME} doesn't support this feature. Only ESP32-S3 and ESP32-P4 supports this up to now.
.. only:: SOC_SPI_MEM_SUPPORT_CACHE_32BIT_ADDR_MAP
By default, space over 16 MBytes on flash mentioned above can be used for ``data saving``, like file system.
By default, space over 16 MB on flash mentioned above can be used for ``data saving``, like file system.
Furthermore, to map data/instructions to 32-bit physical address space (so as to be accessed by the CPU), please enable the config ``IDF_EXPERIMENTAL_FEATURES`` and ``BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH``.
Please note that, this option is experimental, which means it can not be used on all flash chips stably. For more information, please contact Espressif Business Support.
Please note that, this option is experimental, which means that it can not be used on all flash chips stably. For more information, please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_.
.. _oct-flash-doc:
@ -186,9 +188,9 @@ OPI flash means that the flash chip supports octal peripheral interface, which h
.. note::
To know how to configure menuconfig for a board with different Flash and PSRAM, please refer to the :ref:`SPI Flash and External SPI RAM Configuration <flash-psram-configuration>`
To know how to configure menuconfig for a board with different flash and PSRAM, please refer to :ref:`flash-psram-configuration`.
List of Flash chips that support this feature:
List of flash chips that support this feature:
1. MX25UM25645G
2. MX25UM12345G

View File

@ -1 +1,196 @@
.. include:: ../../../../en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst
flash 的可选功能
================
:link_to_translation:`en:[English]`
有些功能并非所有的 ESP 芯片和 flash 芯片都支持,具体功能可参阅以下列表:
- :ref:`auto-suspend-intro`
- :ref:`flash-unique-id`
- :ref:`high-performance-mode`
- :ref:`32-bit-flash-doc`
- :ref:`oct-flash-doc`
.. note::
使用上述 flash 可选功能时,除了 ESP 芯片自身的功能以及所选的 ESP-IDF 版本,还需确保所用的 flash 芯片支持下列功能:
- 如果使用乐鑫官方的模组或 SiP请查阅 `技术规格书 <https://www.espressif.com/zh-hans/support/download/documents/modules>`__,确保其具备上述功能。也可以联系 `乐鑫商务部 <https://www.espressif.com/zh-hans/contact-us/sales-questions>`_,咨询具备此类功能的相关产品。
- 如果使用其他厂商的 flash 芯片来自行组装模组,并且需要应用上述功能,请联系供应商确认所用芯片支持上述功能,并确保厂商会持续量产所用的芯片。
.. attention::
本文档仅表明 ESP-IDF 代码支持 flash 芯片的部分功能,乐鑫官方并未对这些芯片进行全面的稳定性认证。如果使用其他厂商生产的 flash 芯片来组建硬件,即便这些芯片具备上述功能,也需要自行验证其可靠性。
.. _auto-suspend-intro:
自动挂起和恢复
--------------
目前仅有 ESP32-S3、ESP32-C2、ESP32-C3、ESP32-C6 及 ESP32-H2 支持此功能。
未来 ESP32-P4 可能会添加此功能。
.. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND
支持此功能的 flash 芯片列表:
1. XM25QxxC 系列
2. GD25QxxE 系列
3. FM25Q32
.. attention::
自动挂起功能有多重限制,在启用此功能前请务必先行阅读 :ref:`auto-suspend`
.. _flash-unique-id:
flash 的唯一 ID
---------------
所有乐鑫芯片均支持此功能。
flash 的唯一 ID 并不等同于 flash ID每个 flash 设备都有一个 64 位的唯一 ID。读取这个唯一 ID (4Bh) 的指令将访问出厂设置的 64 位只读数字,从而识别出每台设备。并非所有 flash 供应商都支持此功能,如果在没有此功能的芯片上读取该唯一 ID则可能导致不确定的后果。
支持此功能的 flash 芯片列表:
1. ISSI
2. GD
3. TH
4. FM
5. Winbond
6. XMC
7. BOYA
.. _high-performance-mode:
QSPI flash 芯片的高性能模式
---------------------------
目前仅有 ESP32-S3 支持此功能。
未来 ESP32-S2, ESP32-C3, ESP32-C6, ESP32-H2 及 ESP32-P4 可能会添加此功能。
.. note::
本节适用于 QSPI flash 芯片。ESP 芯片上使用的八线 flash 默认支持高性能模式。有关支持高性能模式的所有八线 flash 芯片,请参考 :ref:`oct-flash-doc`
.. only:: esp32s3
高性能模式 (HPM) 是指 SPI1 和 flash 芯片在高频率(通常是大于 80 MHz下工作。
一般来说SPI flash 芯片有超过三种方式可以实现高性能模式。第一,由寄存器中的 dummy 周期 (DC) 位控制;第二,由其他位(如 HPM 位)控制;第三,由某些特殊命令进行控制。由于实现高性能模式的策略不同,驱动程序需要针对每款芯片显式添加支持。
.. attention::
简单通过几种策略来涵盖所有情况并不现实,因此驱动程序需要为所有使用高性能模式的芯片显式添加支持。如果尝试使用未列在 :ref:`hpm_dc_support_list` 中的 flash 芯片,可能会导致一些错误。因此,尝试使用支持列表之外的 flash 芯片前,请先进行测试。
此外,若 flash 芯片采用 `DC 调整` 策略经软件复位后flash 芯片将保持在 DC 与默认值不同的状态。调整 DC 以在应用中以更高频率运行的高性能模式的子模式称为 `HPM-DC``HPM-DC` 功能需要在引导加载程序中启用 `DC Aware` 功能,否则,不同的 DC 值将导致二级引导加载程序在复位后无法启动。
启用高性能模式的方法:
1. 取消选择 :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`:ref:`CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT`。高性能模式不用于八线 flash启用相关选项可能会导致无法使用高性能模式。
2. 启用 ``CONFIG_SPI_FLASH_HPM_ENA`` 选项。
3. 将 flash 频率切换到高性能模式下的频率。例如,``CONFIG_ESPTOOLPY_FLASHFREQ_120M``
4. 检查引导加载程序是否支持 `DC Aware` 功能,选择正确的 `HPM-DC` 配置选项(在 ``CONFIG_SPI_FLASH_HPM_DC`` 选项下)。
- 如果引导加载程序支持 `DC Aware`,请选择 ``CONFIG_SPI_FLASH_HPM_DC_AUTO``,从而使用采用 `DC 调整` 策略的 flash 芯片。
- 如果引导加载程序不支持 `DC Aware`,请选择 ``CONFIG_SPI_FLASH_HPM_DC_DISABLE``,避免不支持 `DC Aware` 的引导加载程序运行 `HPM-DC` 模式造成不良后果。但如果选择了 ``CONFIG_SPI_FLASH_HPM_DC_DISABLE``,请避免使用采用 `DC 调整` 策略的 flash 芯片。请参阅以下列表,了解采用了 DC 策略的 flash 模组。
通过以下方式检查引导加载程序是否支持 `DC Aware`
- 如果启动了新项目,建议通过在引导加载程序菜单中选择 :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` 选项来启用 `DC Aware`。请注意,此选项无法通过 OTA 修改,因为支持代码在引导加载程序中。
- 如果想在现有项目中通过 OTA 来更新 `HPM-DC` 配置选项,请检查用于构建引导加载程序的 sdkconfig 文件(升级 ESP-IDF 版本可能会使此文件与用于构建引导加载程序的文件不同):
- 对于最新版本的 ESP-IDFv5.2 及以上),如果选择了 :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE`,则引导加载程序支持 `DC Aware`
- 对于某些范围内的 ESP-IDF 版本v4.4.4+、v5.0+ 和 v5.1+),如果选择了 ``CONFIG_ESPTOOLPY_FLASHFREQ_120M``,则引导加载程序支持 `DC Aware`。此时,可启用 :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` 进行确认(不会影响实际应用中的引导加载程序)。
- 对于低于 v4.4.4 的 ESP-IDF 版本,引导加载程序不支持 `DC Aware`
.. _hpm_dc_support_list:
支持高性能模式的四线 flash 列表
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
不需要 HPM-DC 的 flash 芯片:
1. GD25Q64C (ID: 0xC84017)
2. GD25Q32C (ID: 0xC84016)
3. ZB25VQ32B (ID: 0x5E4016)
4. GD25LQ255E (ID: 0xC86019)
以下 flash 芯片也具备高性能模式,但需要引导加载程序支持 `DC Aware`
1. GD25Q64E (ID: 0xC84017)
2. GD25Q128E (ID: 0xC84018)
3. XM25QH64C (ID: 0x204017)
4. XM25QH128C (ID: 0x204018)
.. _32-bit-flash-doc:
QSPI flash 芯片的 32 位地址支持
-------------------------------
所有乐鑫芯片均支持此功能(见下文的应用限制章节)。
.. note::
本节适用于 QSPI flash 芯片。八线 flash 芯片的 32 位地址支持属于八线 flash 支持的一部分。有关支持此功能的八线 flash 芯片列表,请参考 :ref:`oct-flash-doc`
乐鑫芯片所用的大多数 NOR flash 芯片使用 24 位地址,可以覆盖 16 MB 的内存。但对于更大的内存(通常大于或等于 32 MBflash 使用 32 位地址来访问超过 16 MB 内存的区域。但是32 位地址的芯片具有厂商特定的命令,因此需要逐一支持这些芯片。
支持此功能的 flash 芯片列表:
1. W25Q256
2. GD25Q256
限制
^^^^
.. only:: not SOC_SPI_MEM_SUPPORT_CACHE_32BIT_ADDR_MAP
.. important::
上述超过 16 MB 内存的 flash 区域只能用于 ``数据保存``,如文件系统。
将数据或指令映射到 32 位物理地址空间(以便由 CPU 访问)需要 MMU 的支持。但 {IDF_TARGET_NAME} 并不支持此功能。目前只有 ESP32-S3 和 ESP32-P4 支持此功能。
.. only:: SOC_SPI_MEM_SUPPORT_CACHE_32BIT_ADDR_MAP
默认情况下,上述超过 16 MB 内存的 flash 区域可用于 ``数据保存``,如文件系统。
此外,要将数据或指令映射到 32 位物理地址空间(以便由 CPU 访问),请启用配置 ``IDF_EXPERIMENTAL_FEATURES````BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH``
请注意,此选项为实验性选项,无法在所有 flash 芯片上稳定使用,详情请咨询 `乐鑫商务部 <https://www.espressif.com/zh-hans/contact-us/sales-questions>`_
.. _oct-flash-doc:
OPI flash 支持
--------------
目前仅有 ESP32-S3 支持此功能。
OPI flash 是指 flash 芯片支持八线外设接口,具有八个 I/O 管脚。不同的八线 flash 有不同的配置和命令,因此必须仔细检查支持列表。
.. only:: esp32s3
.. note::
若想为具有不同 flash 和 PSRAM 的开发板配置 menuconfig请参考 :ref:`flash-psram-configuration`
支持此功能的 flash 芯片列表:
1. MX25UM25645G
2. MX25UM12345G