mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'fix/move_xip_doc_out_from_non_updated_list_v5.3' into 'release/v5.3'
doc(psram): move xip psram doc out from non updated list (v5.3) See merge request espressif/esp-idf!32841
This commit is contained in:
Marius Vikhammer
commit
8679f14d1d
@ -1319,6 +1319,10 @@ config SOC_MEMSPI_SRC_FREQ_20M_SUPPORTED
|
||||
bool
|
||||
default y
|
||||
|
||||
config SOC_SPIRAM_XIP_SUPPORTED
|
||||
bool
|
||||
default y
|
||||
|
||||
config SOC_SYSTIMER_COUNTER_NUM
|
||||
int
|
||||
default 2
|
||||
|
||||
@ -522,6 +522,9 @@
|
||||
#define SOC_MEMSPI_SRC_FREQ_40M_SUPPORTED 1
|
||||
#define SOC_MEMSPI_SRC_FREQ_20M_SUPPORTED 1
|
||||
|
||||
/*-------------------------- SPIRAM CAPS ----------------------------------------*/
|
||||
#define SOC_SPIRAM_XIP_SUPPORTED 1
|
||||
|
||||
/*-------------------------- SYSTIMER CAPS ----------------------------------*/
|
||||
#define SOC_SYSTIMER_COUNTER_NUM 2 // Number of counter units
|
||||
#define SOC_SYSTIMER_ALARM_NUM 3 // Number of alarm units
|
||||
|
||||
@ -33,7 +33,6 @@ api-guides/deep-sleep-stub.rst
|
||||
api-guides/blufi.rst
|
||||
api-guides/lwip.rst
|
||||
api-guides/coexist.rst
|
||||
api-guides/flash_psram_config.rst
|
||||
api-guides/usb-serial-jtag-console.rst
|
||||
api-guides/wifi.rst
|
||||
api-guides/usb-otg-console.rst
|
||||
|
||||
@ -2,7 +2,6 @@ api-guides/partition-tables.rst
|
||||
api-guides/RF_calibration.rst
|
||||
api-guides/deep-sleep-stub.rst
|
||||
api-guides/coexist.rst
|
||||
api-guides/flash_psram_config.rst
|
||||
api-guides/wifi.rst
|
||||
api-guides/usb-otg-console.rst
|
||||
api-guides/esp-wifi-mesh.rst
|
||||
@ -19,7 +18,6 @@ api-reference/peripherals/usb_host/usb_host_notes_design.rst
|
||||
api-reference/peripherals/usb_host/usb_host_notes_usbh.rst
|
||||
api-reference/peripherals/usb_device.rst
|
||||
api-reference/peripherals/touch_element.rst
|
||||
api-reference/peripherals/spi_flash/xip_from_psram.inc
|
||||
api-reference/peripherals/touch_pad.rst
|
||||
api-reference/peripherals/adc_calibration.rst
|
||||
api-reference/peripherals/parlio.rst
|
||||
|
||||
@ -26,7 +26,7 @@ Hardware
|
||||
|
||||
.. only:: esp32 or esp32s2 or esp32s3
|
||||
|
||||
Some PSRAM chips are 1.8 V devices and some are 3.3 V. The working voltage of the PSRAM chip must match the working voltage of the flash component. Consult the datasheet for your PSRAM chip and {IDF_TARGET_NAME} device to find out the working voltages. For a 1.8 V PSRAM chip, make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.
|
||||
Some PSRAM chips are 1.8 V devices and some are 3.3 V. The working voltage of the PSRAM chip must match the working voltage of the flash component. Consult the datasheet for your PSRAM chip and {IDF_TARGET_NAME} device to find out the working voltages. For a 1.8 V PSRAM chip, make sure to either set the MTDI pin to a high signal level on boot-up, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.
|
||||
|
||||
.. only:: esp32p4
|
||||
|
||||
@ -55,8 +55,7 @@ ESP-IDF fully supports the use of external RAM in applications. Once the externa
|
||||
* :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:
|
||||
|
||||
@ -139,8 +138,6 @@ Remaining external RAM can also be added to the capability heap allocator using
|
||||
|
||||
.. only:: esp32s2 or esp32s3
|
||||
|
||||
.. _external_ram_config_instructions:
|
||||
|
||||
Move Instructions in Flash to PSRAM
|
||||
-----------------------------------
|
||||
|
||||
@ -152,8 +149,6 @@ 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.
|
||||
|
||||
.. _external_ram_config_rodata:
|
||||
|
||||
Move Read-Only Data in Flash to PSRAM
|
||||
---------------------------------------
|
||||
|
||||
@ -165,6 +160,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.
|
||||
|
||||
.. _external_ram_config_xip:
|
||||
|
||||
Execute In Place (XiP) from PSRAM
|
||||
------------------------------------
|
||||
@ -179,10 +175,12 @@ Remaining external RAM can also be added to the capability heap allocator using
|
||||
|
||||
.. only:: esp32p4
|
||||
|
||||
.. _external_ram_config_xip:
|
||||
|
||||
Execute In Place (XiP) from PSRAM
|
||||
------------------------------------
|
||||
|
||||
The :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` option enables the executable in place (XiP) from PSRAM feature. With this option sections that are normally placed in flash ,``.text`` (for instructions) and ``.rodata`` (for read only data), will be loaded in PSRAM.
|
||||
The :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` option enables the executable in place (XiP) from PSRAM feature. With this option sections that are normally placed in flash, ``.text`` (for instructions) and ``.rodata`` (for read only data), will be loaded in PSRAM.
|
||||
|
||||
With this option enabled, the cache will not be disabled during an SPI1 flash operation, so code that requires executing during an SPI1 flash operation does not have to be placed in internal RAM. Because P4 flash and PSRAM are using two separate SPI buses, moving flash content to PSRAM will actually increase the load of the PSRAM MSPI bus, so the exact impact on performance will be dependent on your app usage of PSRAM. For example, as the PSRAM bus speed could be much faster than flash bus speed, if the instructions and data that are used to be in flash are not accessed very frequently, you might get better performance with this option enabled. We suggest doing performance profiling to determine if enabling this option.
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@ The SPI0/1 bus is shared between the instruction & data cache (for firmware exec
|
||||
|
||||
.. only:: SOC_SPIRAM_XIP_SUPPORTED
|
||||
|
||||
On {IDF_TARGET_NAME}, the config options :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` (disabled by default) and :ref:`CONFIG_SPIRAM_RODATA` (disabled by default) allow the cache to read/write PSRAM concurrently with SPI1 operations. See :ref:`xip_from_psram` for more details.
|
||||
On {IDF_TARGET_NAME}, the config options :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` (disabled by default) allows the cache to read/write PSRAM concurrently with SPI1 operations. See :ref:`xip_from_psram` for more details.
|
||||
|
||||
If these options are disabled, the caches must be disabled while reading/writing/erasing operations. There are some constraints using driver on the SPI1 bus, see :ref:`impact_disabled_cache`. These constraints will cause more IRAM/DRAM usages.
|
||||
|
||||
@ -40,7 +40,7 @@ Under this condition, all CPUs should always execute code and access data from i
|
||||
|
||||
.. note::
|
||||
|
||||
When :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA` are both enabled, these APIs will not disable the caches.
|
||||
When :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` is enabled, these APIs will not disable the caches.
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
|
||||
@ -3,10 +3,8 @@
|
||||
XIP from PSRAM Feature
|
||||
----------------------
|
||||
|
||||
If :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` is enabled, the flash ``.text`` sections (used for instructions) will be placed in PSRAM.
|
||||
If :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` is enabled, the flash ``.text`` sections (used for instructions) and the flash ``.rodata`` sections (used for read only data) will be placed in PSRAM.
|
||||
|
||||
If :ref:`CONFIG_SPIRAM_RODATA` is enabled, the flash ``.rodata`` sections (used for read only data) will be placed in PSRAM.
|
||||
|
||||
The corresponding virtual memory range will be re-mapped to PSRAM.
|
||||
The corresponding virtual memory range will be mapped to PSRAM.
|
||||
|
||||
If both of the above options are 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.
|
||||
|
||||
@ -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 中。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user