mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/translate_spi_flash' into 'master'
Docs/translate spi flash & ulp_macros Closes DOC-7532 See merge request espressif/esp-idf!29897
This commit is contained in:
Shen Meng Jing
commit
554179609f
@ -1,10 +1,12 @@
|
||||
SPI Flash API ESP-IDF Version vs Chip-ROM Version
|
||||
===================================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. 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 frees 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.
|
||||
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 frees some internal RAM usage. Note that 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
|
||||
@ -12,27 +14,27 @@ 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. Note this feature is an optional feature, please do read :ref:`32-bit-flash-doc` for details.
|
||||
- TH Flash chip support.
|
||||
- Octal flash chip support. See :ref:`oct-flash-doc` for details.
|
||||
- 32-bit-address support for GD25Q256. Note that this feature is an optional feature, please do read :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 prints the bad writing.
|
||||
- :ref:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`, enabling this option checks if you are writing zero to one.
|
||||
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`, enabling this option checks for flash programming to certain protected regions like bootloader, partition table or application itself.
|
||||
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`, enabling this option to collect performance data for ESP-IDF SPI Flash driver APIs.
|
||||
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, enabling this option to automatically suspend / resume a long Flash operation when short Flash operation happens. Note this feature is an optional feature, please do read :ref:`auto-suspend-intro` for more limitations.
|
||||
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`, enabling this option to collect performance data for ESP-IDF SPI flash driver APIs.
|
||||
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, enabling this option to automatically suspend or resume a long flash operation when short flash operation happens. Note that this feature is an optional feature, please do read :ref:`auto-suspend-intro` for more limitations.
|
||||
|
||||
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.
|
||||
- Detected flash physical size correctly, for larger than 256 MBit 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 can not work normally when 8-line PSRAM enabled. (Commit ID: 683d92bc884e0f2a7eebea40a551cf05f0c28256)
|
||||
:esp32s2: - Fixed issue that only 4 MB virtual address ranges can be mapped to read-only data on flash.
|
||||
:esp32s3: - Fixed issue that only 128 KB virtual address ranges can be mapped to instructions on flash.
|
||||
:esp32s3: - Fixed issue that only 16 MB virtual address ranges can be mapped to read-only data on flash.
|
||||
:esp32c3: - Fixed issue that only 128 KB virtual address ranges can be mapped to instructions on flash.
|
||||
:esp32c2: - Fixed issue that only at most 128 KB virtual address ranges can be mapped to instructions on flash.
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
Programming ULP FSM Coprocessor Using C Macros (Legacy)
|
||||
=======================================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
In addition to the existing binutils port for the {IDF_TARGET_NAME} ULP coprocessor, it is possible to generate programs for the ULP FSM coprocessor by embedding assembly-like macros into an {IDF_TARGET_NAME} application. Here is an example how this can be done::
|
||||
|
||||
const ulp_insn_t program[] = {
|
||||
@ -25,7 +27,7 @@ The ``program`` array is an array of ``ulp_insn_t``, i.e., ULP coprocessor instr
|
||||
.. note::
|
||||
|
||||
Load, store and move instructions use **addresses expressed in 32-bit words**. Address 0 corresponds to the first word of ``RTC_SLOW_MEM``.
|
||||
This is different to how address arguments are handled in assembly code of the same instructions. See the section :ref:`ulp-fsm-addressing` for more details for reference.
|
||||
This is different from how address arguments are handled in assembly code of the same instructions. See the section :ref:`ulp-fsm-addressing` for more details for reference.
|
||||
|
||||
To generate branch instructions, special ``M_`` preprocessor defines are used. ``M_LABEL`` define can be used to define a branch target. Label identifier is a 16-bit integer. ``M_Bxxx`` defines can be used to generate branch instructions with target set to a particular label.
|
||||
|
||||
|
||||
@ -1 +1,40 @@
|
||||
.. include:: ../../../../en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst
|
||||
SPI Flash API ESP-IDF 版本与芯片 ROM 版本的对比
|
||||
===============================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
芯片 ROM 中有一组 SPI flash 驱动程序，可以通过启用 :ref:`CONFIG_SPI_FLASH_ROM_IMPL` 来使用。大多数 ESP-IDF SPI flash 驱动程序的代码都在内部 RAM 中，因此启用此选项可以释放一些内部 RAM 的占用量。请注意，如果启用此选项，一些 ESP-IDF 中的 SPI flash 驱动程序功能和错误修复可能不会体现在芯片 ROM 版本中。
|
||||
|
||||
|
||||
ESP-IDF 支持但不包含在芯片 ROM 中的功能
|
||||
---------------------------------------
|
||||
|
||||
.. list::
|
||||
|
||||
- 八线 flash 芯片。详情请参阅 :ref:`oct-flash-doc`。
|
||||
- GD25Q256 32 位地址。请注意，此功能为可选功能，详情请参阅 :ref:`32-bit-flash-doc`。
|
||||
- TH flash 芯片。
|
||||
- Kconfig 选项 :ref:`CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED`。
|
||||
- :ref:`CONFIG_SPI_FLASH_VERIFY_WRITE`，启用此选项可检测错误写入。
|
||||
- :ref:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`，启用此选项会打印错误写入。
|
||||
- :ref:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`，启用此选项会检查是否将 0 写入为 1。
|
||||
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`，启用此选项会检查是否对某些受保护的区域（如引导加载程序、分区表或应用程序本身）进行了 flash 编程。
|
||||
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`，启用此选项以收集 ESP-IDF SPI flash 驱动程序 API 的性能数据。
|
||||
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`，启用此选项可在 flash 短时操作时自动挂起或恢复 flash 长时操作。请注意，此功能为可选功能，详情请参阅 :ref:`auto-suspend-intro`。
|
||||
|
||||
在 ESP-IDF 中引入，但不包含在芯片 ROM 中的错误修复
|
||||
--------------------------------------------------
|
||||
|
||||
.. list::
|
||||
|
||||
- 正确检测到大于 256 MBit 的 flash 芯片的物理大小。（提交 ID: b4964279d44f73cce7cfd5cf684567fbdfd6fd9e）
|
||||
:esp32c3: - 改进了 SPI1 的 CS 建立时间，否则可能会在 ZB32Q128 上报错。（提交 ID: 08f1bbe0c75382f1702e40c941e93314285105d4）
|
||||
:esp32s3: - 修复了当启用 8 线 PSRAM 时 4 线 flash 加密无法正常运行的问题。（提交 ID: 683d92bc884e0f2a7eebea40a551cf05f0c28256）
|
||||
:esp32s2: - 修复了只能将 4 MB 虚拟地址范围映射到 flash 只读数据中的问题。
|
||||
:esp32s3: - 修复了只能将 128 KB 虚拟地址范围映射到 flash 指令中的问题。
|
||||
:esp32s3: - 修复了只能将 16 MB 虚拟地址范围映射到 flash 只读数据中的问题。
|
||||
:esp32c3: - 修复了只能将 128 KB 虚拟地址范围映射到 flash 指令中的问题。
|
||||
:esp32c2: - 修复了只能将最多 128 KB 虚拟地址范围映射到 flash 指令中的问题。
|
||||
|
||||
@ -1 +1,61 @@
|
||||
.. include:: ../../../en/api-reference/system/ulp_macros.rst
|
||||
使用 C 语言宏编程 ULP FSM 协处理器（遗留）
|
||||
===========================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
想要为 ULP FSM 协处理器生成程序，除了用 {IDF_TARGET_NAME} ULP 协处理器目前的 binutils 端口外，还可以将类似汇编的宏嵌入到 {IDF_TARGET_NAME} 应用程序中。以下是一个示例::
|
||||
|
||||
const ulp_insn_t program[] = {
|
||||
I_MOVI(R3, 16), // R3 <- 16
|
||||
I_LD(R0, R3, 0), // R0 <- RTC_SLOW_MEM[R3 + 0]
|
||||
I_LD(R1, R3, 1), // R1 <- RTC_SLOW_MEM[R3 + 1]
|
||||
I_ADDR(R2, R0, R1), // R2 <- R0 + R1
|
||||
I_ST(R2, R3, 2), // R2 -> RTC_SLOW_MEM[R2 + 2]
|
||||
I_HALT()
|
||||
};
|
||||
size_t load_addr = 0;
|
||||
size_t size = sizeof(program)/sizeof(ulp_insn_t);
|
||||
ulp_process_macros_and_load(load_addr, program, &size);
|
||||
ulp_run(load_addr);
|
||||
|
||||
``program`` 数组是一个 ``ulp_insn_t`` 数组，即 ULP 协处理器指令。每个 ``I_XXX`` 预处理宏都会转换为单个 32 位指令。这些预处理宏的参数可以是寄存器号 (``R0 — R3``) 和字面常量。有关指令及其参数的详细信息，请参阅本指南末尾的 API 参考部分。
|
||||
|
||||
.. note::
|
||||
|
||||
由于一些宏指令会展开为内联函数调用，将这样的数组定义为全局数组会导致编译器报错："initializer element is not constant"。要修复此错误，请定义指令数组为局部数组。
|
||||
|
||||
.. note::
|
||||
|
||||
加载指令 (LD)、存储指令 (ST) 和移动指令 (MOV) 均使用 **32 位字地址**。地址 0 对应 ``RTC_SLOW_MEM`` 的第一个字。
|
||||
这与汇编代码中相同指令的地址参数处理方式不同。详情请参阅 :ref:`ulp-fsm-addressing`。
|
||||
|
||||
要生成分支指令，使用特殊的 ``M_`` 预处理宏定义。 ``M_LABEL`` 宏定义可用于定义分支目标。标签标识符是一个 16 位整数。 ``M_Bxxx`` 宏定义可用于生成目标设置为特定标签的分支指令。
|
||||
|
||||
实现注意事项：这些 ``M_`` 预处理宏将被转换为两个 ulp_insn_t 值：一个是包含标签号的令牌值，另一个是实际指令。 ``ulp_process_macros_and_load`` 函数将标签号解析为地址，修改分支指令以使用正确的地址，并移除包含标签号的额外 ``ulp_insn_t`` 令牌。
|
||||
|
||||
以下是使用标签和分支的示例::
|
||||
|
||||
const ulp_insn_t program[] = {
|
||||
I_MOVI(R0, 34), // R0 <- 34
|
||||
M_LABEL(1), // label_1
|
||||
I_MOVI(R1, 32), // R1 <- 32
|
||||
I_LD(R1, R1, 0), // R1 <- RTC_SLOW_MEM[R1]
|
||||
I_MOVI(R2, 33), // R2 <- 33
|
||||
I_LD(R2, R2, 0), // R2 <- RTC_SLOW_MEM[R2]
|
||||
I_SUBR(R3, R1, R2), // R3 <- R1 - R2
|
||||
I_ST(R3, R0, 0), // R3 -> RTC_SLOW_MEM[R0 + 0]
|
||||
I_ADDI(R0, R0, 1), // R0++
|
||||
M_BL(1, 64), // if (R0 < 64) goto label_1
|
||||
I_HALT(),
|
||||
};
|
||||
RTC_SLOW_MEM[32] = 42;
|
||||
RTC_SLOW_MEM[33] = 18;
|
||||
size_t load_addr = 0;
|
||||
size_t size = sizeof(program)/sizeof(ulp_insn_t);
|
||||
ulp_process_macros_and_load(load_addr, program, &size);
|
||||
ulp_run(load_addr);
|
||||
|
||||
API 参考
|
||||
--------
|
||||
|
||||
.. include-build-file:: inc/ulp.inc
|
||||
|
||||
Loading…
Reference in New Issue
Block a user