mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 20:56:01 -04:00
Merge branch 'bugfix/ext_ram_docs_label' into 'master'
docs: fix broken ref in external-ram.rst See merge request espressif/esp-idf!12425
This commit is contained in:
Angus Gratton
commit
ec8419945a
@ -31,10 +31,12 @@ Configuring External RAM
|
||||
|
||||
ESP-IDF fully supports the use of external memory in applications. Once the external RAM is initialized at startup, ESP-IDF can be configured to handle it in several ways:
|
||||
|
||||
.. list::
|
||||
|
||||
* :ref:`external_ram_config_memory_map`
|
||||
* :ref:`external_ram_config_capability_allocator`
|
||||
* :ref:`external_ram_config_malloc` (default)
|
||||
* :ref:`external_ram_config_bss`
|
||||
:esp32: * :ref:`external_ram_config_bss`
|
||||
|
||||
.. _external_ram_config_memory_map:
|
||||
|
||||
@ -83,23 +85,24 @@ If a suitable block of preferred internal/external memory is not available, the
|
||||
|
||||
Because some buffers can only be allocated in internal memory, a second configuration item :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` defines a pool of internal memory which is reserved for *only* explicitly internal allocations (such as memory for DMA use). Regular ``malloc()`` will not allocate from this pool. The :ref:`MALLOC_CAP_DMA <dma-capable-memory>` and ``MALLOC_CAP_INTERNAL`` flags can be used to allocate memory from this pool.
|
||||
|
||||
.. _external_ram_config_bss:
|
||||
.. only:: esp32
|
||||
|
||||
.. _external_ram_config_bss:
|
||||
|
||||
Allow .bss segment placed in external memory
|
||||
--------------------------------------------
|
||||
Allow .bss segment placed in external memory
|
||||
--------------------------------------------
|
||||
|
||||
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`. This configuration setting is independent of the other three.
|
||||
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`. This configuration setting is independent of the other three.
|
||||
|
||||
If enabled, a region of the address space starting from 0x3F800000 will be used to store zero-initialized data (BSS segment) from the lwIP, net80211, libpp, and bluedroid ESP-IDF libraries.
|
||||
If enabled, a region of the address space starting from 0x3F800000 will be used to store zero-initialized data (BSS segment) from the lwIP, net80211, libpp, and bluedroid ESP-IDF libraries.
|
||||
|
||||
Additional data can be moved from the internal BSS segment to external RAM by applying the macro ``EXT_RAM_ATTR`` to any static declaration (which is not initialized to a non-zero value).
|
||||
Additional data can be moved from the internal BSS segment to external RAM by applying the macro ``EXT_RAM_ATTR`` to any static declaration (which is not initialized to a non-zero value).
|
||||
|
||||
It is also possible to place the BSS section of a component or a library to external RAM using linker fragment scheme ``extram_bss``.
|
||||
It is also possible to place the BSS section of a component or a library to external RAM using linker fragment scheme ``extram_bss``.
|
||||
|
||||
This option reduces the internal static memory used by the BSS segment.
|
||||
This option reduces the internal static memory used by the BSS segment.
|
||||
|
||||
Remaining external RAM can also be added to the capability heap allocator using the method shown above.
|
||||
Remaining external RAM can also be added to the capability heap allocator using the method shown above.
|
||||
|
||||
|
||||
Restrictions
|
||||
@ -111,7 +114,12 @@ External RAM use has the following restrictions:
|
||||
* External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Any buffers that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA)`` and can be freed using a standard ``free()`` call.
|
||||
* External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can "push out" cached flash, possibly making the execution of code slower afterwards.
|
||||
* External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal.
|
||||
* By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`. If :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time.
|
||||
|
||||
By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
If :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time.
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
@ -31,10 +31,12 @@
|
||||
|
||||
ESP-IDF 完全支持将外部存储器集成到您的应用程序中。在启动并完成片外 RAM 初始化后，可以将 ESP-IDF 配置为以多种方式处理片外 RAM：
|
||||
|
||||
.. list::
|
||||
|
||||
* :ref:`external_ram_config_memory_map`
|
||||
* :ref:`external_ram_config_capability_allocator`
|
||||
* :ref:`external_ram_config_malloc` （默认）
|
||||
* :ref:`external_ram_config_bss`
|
||||
* :ref:`external_ram_config_malloc` (default)
|
||||
:esp32: * :ref:`external_ram_config_bss`
|
||||
|
||||
.. _external_ram_config_memory_map:
|
||||
|
||||
@ -83,23 +85,25 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据
|
||||
|
||||
由于有些 Buffer 仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 定义一个内部存储池，仅限显式的内部存储器分配使用（例如用于 DMA 的存储器）。常规 ``malloc()`` 将不会从该池中分配，但可以使用 :ref:`MALLOC_CAP_DMA <dma-capable-memory>` 和 ``MALLOC_CAP_INTERNAL`` 旗标从该池中分配存储器。
|
||||
|
||||
.. _external_ram_config_bss:
|
||||
.. only:: esp32
|
||||
|
||||
.. _external_ram_config_bss:
|
||||
|
||||
允许 .bss 段放入片外存储器
|
||||
-----------------------------
|
||||
允许 .bss 段放入片外存储器
|
||||
-----------------------------
|
||||
|
||||
通过检查 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` 启用该选项，此选项配置与上面三个选项互不影响。
|
||||
通过检查 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` 启用该选项，此选项配置与上面三个选项互不影响。
|
||||
|
||||
启用该选项后，从 0x3F800000 起始的地址空间将用于存储来自 lwip、net80211、libpp 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。
|
||||
启用该选项后，从 0x3F800000 起始的地址空间将用于存储来自 lwip、net80211、libpp 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。
|
||||
|
||||
``EXT_RAM_ATTR`` 宏应用于任何静态声明（未初始化为非零值）之后，可以将附加数据从内部 BSS 段移到片外 RAM。
|
||||
``EXT_RAM_ATTR`` 宏应用于任何静态声明（未初始化为非零值）之后，可以将附加数据从内部 BSS 段移到片外 RAM。
|
||||
|
||||
也可以使用链接器片段方案 ``extram_bss`` 将组件或库的 BSS 段放到片外 RAM 中。
|
||||
也可以使用链接器片段方案 ``extram_bss`` 将组件或库的 BSS 段放到片外 RAM 中。
|
||||
|
||||
启用此选项可以减少 BSS 段占用的内部静态存储。
|
||||
启用此选项可以减少 BSS 段占用的内部静态存储。
|
||||
|
||||
剩余的片外 RAM 也可以通过上述方法添加到堆分配器中。
|
||||
|
||||
剩余的片外 RAM 也可以通过上述方法添加到堆分配器中。
|
||||
|
||||
片外 RAM 使用限制
|
||||
===================
|
||||
@ -114,7 +118,11 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据
|
||||
|
||||
* 片外 RAM 不可用作任务堆栈存储器。因此 :cpp:func:`xTaskCreate` 及类似函数将始终为堆栈和任务 TCB 分配片上储存器，而 :cpp:func:`xTaskCreateStatic` 类型的函数将检查传递的 Buffer 是否属于片上存储器。
|
||||
|
||||
* 默认情况下，片外 RAM 初始化失败将终止 ESP-IDF 启动。如果想禁用此功能，可启用 :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 配置选项。如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，:ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 选项将不能使用，这是因为在链接时，链接器已经向片外 RAM 分配符号。
|
||||
默认情况下，片外 RAM 初始化失败将终止 ESP-IDF 启动。如果想禁用此功能，可启用 :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 配置选项。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，:ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 选项将不能使用，这是因为在链接时，链接器已经向片外 RAM 分配符号。
|
||||
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
Loading…
Reference in New Issue
Block a user