fix(xip): move rest xip_psram doc out from non updated list

2026-10-02 03:00:34 +03:00 · 2024-08-14 14:57:44 +08:00
parent fe48cfd6e5
commit eca7b3b1f1
8 changed files with 54 additions and 45 deletions
@@ -55,8 +55,7 @@ ESP-IDF 完全支持将片外 RAM 集成到你的应用程序中。在启动并
    * :ref:`external_ram_config_malloc` (default)
    * :ref:`external_ram_config_bss`
    :esp32: * :ref:`external_ram_config_noinit`
-    :SOC_SPIRAM_XIP_SUPPORTED: * :ref:`external_ram_config_instructions`
-    :SOC_SPIRAM_XIP_SUPPORTED: * :ref:`external_ram_config_rodata`
+    :SOC_SPIRAM_XIP_SUPPORTED: * :ref:`external_ram_config_xip`

 .. _external_ram_config_memory_map:

@@ -82,7 +81,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该

 在 :ref:`CONFIG_SPIRAM_USE` 中选择 ``Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)`` 选项。

-启用上述选项后，片外 RAM 被映射到数据虚拟地址空间，并将这个区域添加到携带 ``MALLOC_CAP_SPIRAM`` 标志的 :doc:`堆内存分配器 </api-reference/system/mem_alloc>` 。
+启用上述选项后，片外 RAM 被映射到数据虚拟地址空间，并将这个区域添加到携带 ``MALLOC_CAP_SPIRAM`` 标志的 :doc:`堆内存分配器 </api-reference/system/mem_alloc>`。

 程序如果想从片外存储器分配存储空间，则需要调用 ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``，之后可以调用 ``free()`` 函数释放这部分存储空间。

@@ -114,7 +113,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该

 通过勾选 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` 启用该选项。

-启用该选项后，PSRAM 被映射到的数据虚拟地址空间将用于存储来自 lwip、net80211、libpp, wpa_supplicant 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。
+启用该选项后，PSRAM 被映射到的数据虚拟地址空间将用于存储来自 lwip、net80211、libpp、wpa_supplicant 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。

 通过将宏 ``EXT_RAM_BSS_ATTR`` 应用于任何静态声明（未初始化为非零值），可以将附加数据从内部 BSS 段移到片外 RAM。

@@ -137,35 +136,54 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该

 .. only:: SOC_SPIRAM_XIP_SUPPORTED

-    .. _external_ram_config_instructions:
+    .. only:: esp32s2 or esp32s3

-    将 flash 中的指令移至 PSRAM
-    -----------------------------------
+        将 flash 中的指令移至 PSRAM
+        -----------------------------------

-    启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后，flash 中 ``.text`` 部分的数据（用于指令）将被放入 PSRAM。
+        启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后，flash 中 ``.text`` 部分的数据（用于指令）将被放入 PSRAM。

-    启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后：
+        启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后：

-    - flash ``.text`` 部分中的指令将在系统启动时移至 PSRAM。
+        - flash ``.text`` 部分中的指令将在系统启动时移至 PSRAM。

-    - 上述指令对应的虚拟内存范围也将重新映射至 PSRAM。
+        - 上述指令对应的虚拟内存范围也将重新映射至 PSRAM。

-    如果同时启用 :ref:`CONFIG_SPIRAM_RODATA`，SPI1 flash 操作期间不会禁用 cache。ISR、ISR 回调和相关数据无需放在内部 RAM 中，因此可以优化内部 RAM 的使用。
+        将 flash 中的只读数据移至 PSRAM
+        ---------------------------------------

-    .. _external_ram_config_rodata:
+        启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后，flash 中 ``.rodata`` 部分的数据（用于只读数据）将被放入 PSRAM。

-    将 flash 中的只读数据移至 PSRAM
-    ---------------------------------------
+        启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后：

-    启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后，flash 中 ``.rodata`` 部分的数据（用于只读数据）将被放入 PSRAM。
+        - flash ``.rodata`` 部分中的指令将在系统启动时移至 PSRAM。

-    启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后：
+        - 上述只读数据对应的虚拟内存范围也将重新映射至 PSRAM。

-    - flash ``.rodata`` 部分中的指令将在系统启动时移至 PSRAM。
+        .. _external_ram_config_xip:

-    - 上述只读数据对应的虚拟内存范围也将重新映射至 PSRAM。
+        在 PSRAM 中直接执行代码
+        ------------------------------------
+
+        启用 :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` 选项后，可同时指定 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 和 :ref:`CONFIG_SPIRAM_RODATA` 选项。
+
+        在 PSRAM 中直接执行代码的好处包括：
+
+        - PSRAM 访问速度快于 flash，因此性能更好。
+
+        - 在进行 SPI1 flash 操作期间，cache 仍然保持启用状态，这样可以优化代码执行性能。由于无需把中断服务程序 (ISR)、ISR 回调和在此期间可能被访问的数据放置在片上 RAM 中，片上 RAM 可用于其他用途，从而提高了使用效率。这个特性适用于需要处理大量数据的高吞吐量外设应用，能显著提高 SPI1 flash 操作期间的性能。
+
+    .. only:: esp32p4
+
+        .. _external_ram_config_xip:
+
+        在 PSRAM 中直接执行代码
+        ------------------------------------
+
+        启用 :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` 选项后能在 PSRAM 中直接执行代码。通常放置在 flash 中的段，如 ``.text`` 部分的数据（用于指令）和 ``.rodata`` 部分的数据（用于只读数据），将被加载到 PSRAM 中。
+
+        启用此选项后，SPI1 flash 操作期间 cache 保持启用状态，因此需要执行的代码在此期间不必放置在内部 RAM 中。由于 ESP32-P4 flash 和 PSRAM 使用两个独立的 SPI 总线，将 flash 内容移动到 PSRAM 实际上增加了 PSRAM MSPI 总线的负载，因此整体性能将取决于应用程序对 PSRAM 的使用。例如，因为 PSRAM 的总线速度可能远大于 flash 总线速度，如果那些之前存放在 flash 中的指令和只读数据（现在存放于 PSRAM 中）不被经常访问，那么整体性能将有可能更好。因此，建议先进行性能分析以确定启用此选项是否会显著影响应用程序性能。

-    如果同时启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS`，SPI1 flash 操作期间不会禁用 cache。ISR、ISR 回调和相关数据无需放在内部 RAM 中，因此可以优化内部 RAM 的使用。

 片外 RAM 使用限制
 ===================
@@ -192,7 +210,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该


 初始化失败
-=====================
+====================

 默认情况下，片外 RAM 初始化失败将终止 ESP-IDF 启动。如果想禁用此功能，可启用 :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 配置选项。

@@ -206,7 +224,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该
    加密
    ==========

-    可以为存储在外部 RAM 中的数据启用自动加密功能。启用该功能后，通过缓存读写的任何数据将被外部存储器加密硬件自动加密/解密。
+    可以为存储在外部 RAM 中的数据启用自动加密功能。启用该功能后，通过缓存读写的任何数据将被外部存储器加密硬件自动加密、解密。

    只要启用了 flash 加密功能，就会启用这个功能。关于如何启用 flash 加密以及其工作原理，请参考 :doc:`/security/flash-encryption`。

@@ -19,7 +19,7 @@ SPI1 flash 并发约束

 .. only:: SOC_SPIRAM_XIP_SUPPORTED

-    在 {IDF_TARGET_NAME} 上，启用配置选项 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` （默认禁用）和 :ref:`CONFIG_SPIRAM_RODATA` （默认禁用）后将允许 flash/PSRAM 的 cache 访问和 SPI1 的操作并发执行。请参阅 :ref:`xip_from_psram`，查看详细信息。
+    在 {IDF_TARGET_NAME} 上，启用配置选项 :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` （默认禁用）后将允许 flash/PSRAM 的 cache 访问和 SPI1 的操作并发执行。请参阅 :ref:`xip_from_psram`，查看详细信息。

    禁用该选项时，在读取/写入/擦除 flash 期间，必须禁用 cache。使用驱动访问 SPI1 的相关约束参见 :ref:`impact_disabled_cache`。这些约束会带来更多的 IRAM/DRAM 消耗。

@@ -40,7 +40,7 @@ SPI1 flash 并发约束

    .. note::

-        同时启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 和 :ref:`CONFIG_SPIRAM_RODATA` 选项后，不会禁用 cache。
+        启用 :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` 选项后，不会禁用 cache。

 .. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES

@@ -3,10 +3,8 @@
 在 PSRAM 中执行代码
 ----------------------

-启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 选项后，flash 中 ``.text`` 部分的数据（用于指令）将被放入 PSRAM。
+启用 :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` 选项后，flash 中 ``.text`` 部分的数据（用于指令）和 flash 中 ``.rodata`` 部分的数据（用于只读数据）将被放入 PSRAM。

-启用 :ref:`CONFIG_SPIRAM_RODATA` 选项后，flash 中 ``.rodata`` 部分的数据（用于只读数据）将被放入 PSRAM。
-
-相应的虚拟内存地址将被重新映射到 PSRAM。
+相应的虚拟内存地址将被映射到 PSRAM。

 如果同时启用以上两个选项，则在 SPI1 flash 操作期间 cache 不会被禁用，无需确保 ISR、ISR 回调及相关数据放置在内部 RAM 中。