feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

docs: add docs to .bss and .noinit segments on spiram

Browse Source
This commit is contained in:
Armando
2021-07-27 16:22:56 +08:00
parent 65aa737b15
commit e0acefbb78
3 changed files with 19 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/en/api-guides/external-ram.rst
View File

@@ -38,6 +38,7 @@ ESP-IDF fully supports the use of external memory in applications. Once the exte
* :ref:`external_ram_config_capability_allocator`
* :ref:`external_ram_config_malloc` (default)
:esp32: * :ref:`external_ram_config_bss`
:esp32: * :ref:`external_ram_config_noinit`
.. _external_ram_config_memory_map:
@@ -104,6 +105,14 @@ Because some buffers can only be allocated in internal memory, a second configur
Remaining external RAM can also be added to the capability heap allocator using the method shown above.
.. _external_ram_config_noinit:
Allow .noinit segment placed in external memory
-----------------------------------------------
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY`. If enabled, a region of the address space provided in external RAM will be used to store non-initialized data. The values placed in this segment will not be initialized or modified even during startup or restart.
By applying the macro ``EXT_RAM_NOINIT_ATTR``, data could be moved from the internal NOINIT segment to external RAM. Remaining external RAM can still be added to the capability heap allocator using the method shown above, :ref:`external_ram_config_capability_allocator`.
Restrictions
============

8
docs/en/api-guides/memory-types.rst
View File

@@ -16,6 +16,8 @@ Non-constant static data (.data) and zero-initialized data (.bss) is placed by t
.. only:: esp32
By applying the ``EXT_RAM_ATTR`` macro, zero-initialized data can also be placed into external RAM. To use this macro, the :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` needs to be enabled. See :ref:`external_ram_config_bss`.
The available size of the internal DRAM region is reduced by 64kB (by shifting start address to ``0x3FFC0000``) if Bluetooth stack is used. Length of this region is also reduced by 16 kB or 32kB if trace memory is used. Due to some memory fragmentation issues caused by ROM, it is also not possible to use all available DRAM for static allocations - however the remaining DRAM is still available as heap at runtime.
.. only:: not esp32
@@ -31,6 +33,10 @@ Constant data may also be placed into DRAM, for example if it is used in an non-
The macro ``__NOINIT_ATTR`` can be used as attribute to place data into ``.noinit`` section. The values placed into this section will not be initialized at startup and should keep its value after software restart.
.. only:: esp32
By applying the ``EXT_RAM_NOINIT_ATTR`` macro, Non-initialized value could also be placed in external RAM. To do this, the :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY` needs to be enabled. See :ref:`external_ram_config_noinit`. If the :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY` is not enabled, ``EXT_RAM_NOINIT_ATTR`` will behave just as ``__NOINIT_ATTR``, it will make data to be placed into ``.noinit`` segment in internal RAM.
Example::
__NOINIT_ATTR uint32_t noinit_data;
@@ -209,5 +215,3 @@ Placing DMA buffers in the stack is possible but discouraged. If doing so, pay a
spi_device_transmit(spi, &temp);
// other stuff
}

8
docs/zh_CN/api-guides/external-ram.rst
View File

@@ -121,7 +121,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据
.. only:: esp32
可以使用 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 选项将任务堆栈放入片外存储器。这时，必须使用 :cpp:func:`xTaskCreateStatic` 指定从片外存储器分配的任务堆栈缓冲区，否则任务堆栈将会从片上存储器分配。
初始化失败
=====================
@@ -129,12 +129,12 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据
.. only:: esp32
如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，忽略失败的选项将无法使用，这是因为在链接时，链接器已经向片外存储器分配符号。
如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，忽略失败的选项将无法使用，这是因为在链接时，链接器已经向片外存储器分配符号。
.. only:: esp32
.. include:: inc/external-ram-esp32-notes.rst
.. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_cn.pdf
.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__CN.pdf
.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__CN.pdf