Merge branch 'docs/update_external_ram' into 'master'

docs: update translation for external-ram

Closes DOC-3918

See merge request espressif/esp-idf!20761

docs/en/api-guides/external-ram.rst

@@ -138,7 +138,7 @@ Remaining external RAM can also be added to the capability heap allocator using
 
     - The corresponding virtual memory range of those instructions will also be re-mapped to PSRAM.
 
-    If :ref:`CONFIG_SPIRAM_RODATA` is also enabled, the Cache won't be disabled during an SPI1 Flash operation. You don't need to make sure ISRs, ISR callbacks and involved data are placed in internal RAM, thus internal RAM usage can be optimized.
+    If :ref:`CONFIG_SPIRAM_RODATA` is also enabled, the cache won't be disabled during an SPI1 flash operation. You don't need to make sure ISRs, ISR callbacks and involved data are placed in internal RAM, thus internal RAM usage can be optimized.
 
     .. _external_ram_config_rodata:
 
@@ -153,7 +153,7 @@ Remaining external RAM can also be added to the capability heap allocator using
 
     - The corresponding virtual memory range of those rodata will also be re-mapped to PSRAM.
 
-    If :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` is also enabled, the Cache won't be disabled during an SPI1 Flash operation. You don't need to make sure ISRs, ISR callbacks and involved data are placed in internal RAM, thus internal RAM usage can be optimized.
+    If :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` is also enabled, the cache won't be disabled during an SPI1 flash operation. You don't need to make sure ISRs, ISR callbacks and involved data are placed in internal RAM, thus internal RAM usage can be optimized.
 
 Restrictions
 ============

docs/zh_CN/api-guides/external-ram.rst

@@ -16,7 +16,7 @@
 硬件
 ========
 
-{IDF_TARGET_NAME} 支持与 SPI Flash 芯片并联的 SPI PSRAM（伪静态随机存储器）。虽然 {IDF_TARGET_NAME} 支持多种类型的 RAM 芯片，但 ESP-IDF 当前仅支持乐鑫品牌的 PSRAM 芯片，如 ESP-PSRAM32、ESP-PSRAM64 等。
+{IDF_TARGET_NAME} 支持与 SPI flash 芯片并联的 SPI PSRAM（伪静态随机存储器）。虽然 {IDF_TARGET_NAME} 支持多种类型的 RAM 芯片，但 ESP-IDF 当前仅支持乐鑫品牌的 PSRAM 芯片，如 ESP-PSRAM32、ESP-PSRAM64 等。
 
 .. note::
 
@@ -41,13 +41,17 @@ ESP-IDF 完全支持将片外 RAM 集成到您的应用程序中。在启动并
     * :ref:`external_ram_config_memory_map`
     * :ref:`external_ram_config_capability_allocator`
     * :ref:`external_ram_config_malloc` (default)
-    :esp32 or esp32s2: * :ref:`external_ram_config_bss`
+    * :ref:`external_ram_config_bss`
     :esp32: * :ref:`external_ram_config_noinit`
+    :esp32s2 or esp32s3: * :ref:`external_ram_config_instructions`
+    :esp32s2 or esp32s3: * :ref:`external_ram_config_rodata`
 
 .. _external_ram_config_memory_map:
 
+
 集成片外 RAM 到 {IDF_TARGET_NAME} 内存映射
 -------------------------------------------
+
 {IDF_TARGET_PSRAM_ADDR_START:default="Value not updated", esp32="0x3F800000", esp32s2="0x3F500000", esp32s3="0x3D000000"}
 
 在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Integrate RAM into memory map（集成片外 RAM 到 {IDF_TARGET_NAME} 内存映射）" 选项。
@@ -91,25 +95,22 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 {IDF_TARGET_PSRAM_ADDR_STAR
 
 由于有些内存缓冲器仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 定义一个内部内存池，仅限显式的内部存储器分配使用（例如用于 DMA 的存储器）。常规 ``malloc()`` 将不会从该池中分配，但可以使用 :ref:`MALLOC_CAP_DMA <dma-capable-memory>` 和 ``MALLOC_CAP_INTERNAL`` 标志从该池中分配存储器。
 
-.. only:: SOC_SPIRAM_SUPPORTED
-
-    .. _external_ram_config_bss:
+.. _external_ram_config_bss:
 
-    允许 .bss 段放入片外存储器
-    -----------------------------------
-
-    通过勾选 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` 启用该选项，此选项配置与其它三个选项互不影响。
+允许 .bss 段放入片外存储器
+-----------------------------------
 
-    启用该选项后，从 {IDF_TARGET_PSRAM_ADDR_START} 起始的地址空间将用于存储来自 lwip、net80211、libpp 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。
+通过勾选 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` 启用该选项。
 
-    ``EXT_RAM_BSS_ATTR`` 宏应用于任何静态声明（未初始化为非零值）之后，可以将附加数据从内部 BSS 段移到片外 RAM。
+启用该选项后，从 {IDF_TARGET_PSRAM_ADDR_START} 起始的地址空间将用于存储来自 lwip、net80211、libpp 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。
 
-    也可以使用链接器片段方案 ``extram_bss`` 将组件或库的 BSS 段放到片外 RAM 中。
+通过将宏 ``EXT_RAM_BSS_ATTR`` 应用于任何静态声明（未初始化为非零值），可以将附加数据从内部 BSS 段移到片外 RAM。
 
-    启用此选项可以减少 BSS 段占用的内部静态存储。
+也可以使用链接器片段方案 ``extram_bss`` 将组件或库的 BSS 段放到片外 RAM 中。
 
-    剩余的片外 RAM 也可以通过上述方法添加到堆分配器中。
+启用此选项可以减少 BSS 段占用的内部静态存储。
 
+剩余的片外 RAM 也可以通过上述方法添加到堆分配器中。
 
 .. only:: esp32
 
@@ -122,12 +123,44 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 {IDF_TARGET_PSRAM_ADDR_STAR
 
     通过应用 ``EXT_RAM_NOINIT_ATTR`` 宏，可以将数据从内部 NOINIT 段移到片外 RAM。剩余的片外 RAM 也可以通过上述方法添加到堆分配器中，具体请参考 :ref:`external_ram_config_capability_allocator`。
 
+.. only:: SOC_SPIRAM_XIP_SUPPORTED
+
+    .. _external_ram_config_instructions:
+
+    将 flash 中的指令移至 PSRAM
+    -----------------------------------
+
+    启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后，flash 中 ``.text`` 部分的数据（用于指令）将被放入 PSRAM。
+
+    启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后：
+
+    - flash ``.text`` 部分中的指令将在系统启动时移至 PSRAM。
+
+    - 上述指令对应的虚拟内存范围也将重新映射至 PSRAM。
+
+    如果同时启用 :ref:`CONFIG_SPIRAM_RODATA`，SPI1 flash 操作期间不会禁用 cache。ISR、ISR 回调和相关数据无需放在内部 RAM 中，因此可以优化内部 RAM 的使用。
+
+    .. _external_ram_config_rodata:
+
+    将 flash 中的只读数据移至 PSRAM
+    ---------------------------------------
+
+    启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后，flash 中 ``.rodata`` 部分的数据（用于只读数据）将被放入 PSRAM。
+
+    启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后：
+
+    - flash ``.rodata`` 部分中的指令将在系统启动时移至 PSRAM。
+
+    - 上述只读数据对应的虚拟内存范围也将重新映射至 PSRAM。
+
+    如果同时启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS`，SPI1 flash 操作期间不会禁用 cache。ISR、ISR 回调和相关数据无需放在内部 RAM 中，因此可以优化内部 RAM 的使用。
+
 片外 RAM 使用限制
 ===================
 
 使用片外 RAM 有下面一些限制：
 
- * Flash cache 禁用时（比如，正在写入 flash），片外 RAM 将无法访问；同样，对片外 RAM 的读写操作也将导致 cache 访问异常。出于这个原因，ESP-IDF 不会在片外 RAM 中分配任务堆栈（详见下文）。
+ * flash cache 禁用时（比如，正在写入 flash），片外 RAM 将无法访问；同样，对片外 RAM 的读写操作也将导致 cache 访问异常。出于这个原因，ESP-IDF 不会在片外 RAM 中分配任务堆栈（详见下文）。
 
  * 片外 RAM 不能用于储存 DMA 事务描述符，也不能用作 DMA 读写操作的缓冲区 (Buffer)。因此，当片外 RAM 启用时，与 DMA 搭配使用的 Buffer 必须先使用 ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` 进行分配，之后可以调用标准 ``free()`` 回调释放 Buffer。