From b5de3ec953ba31841d972c65db75cc0af61172ca Mon Sep 17 00:00:00 2001 From: Armando Date: Wed, 23 Mar 2022 20:22:54 +0800 Subject: [PATCH] esp_common: rename EXT_RAM_ATTR to EXT_RAM_BSS_ATTR to make it clearer EXT_RAM_ATTR is deprecated. To put .bss on PSRAM, use this new macro EXT_RAM_BSS_ATTR --- components/esp_common/include/esp_attr.h | 14 ++++++++++++-- components/esp_common/test/test_attr.c | 2 +- components/esp_hw_support/Kconfig.spiram.common | 4 ++-- components/esp_system/ld/esp32/sections.ld.in | 2 +- components/esp_system/ld/esp32s2/sections.ld.in | 2 +- docs/en/api-guides/external-ram.rst | 4 ++-- docs/en/api-guides/memory-types.rst | 4 ++-- docs/en/migration-guides/system.rst | 4 ++++ docs/zh_CN/api-guides/external-ram.rst | 4 ++-- docs/zh_CN/api-guides/memory-types.rst | 4 ++-- 10 files changed, 29 insertions(+), 15 deletions(-) diff --git a/components/esp_common/include/esp_attr.h b/components/esp_common/include/esp_attr.h index acd895c7be..91fe654014 100644 --- a/components/esp_common/include/esp_attr.h +++ b/components/esp_common/include/esp_attr.h @@ -66,9 +66,19 @@ extern "C" { #if CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY // Forces bss variable into external memory. " -#define EXT_RAM_ATTR _SECTION_ATTR_IMPL(".ext_ram.bss", __COUNTER__) +#define EXT_RAM_BSS_ATTR _SECTION_ATTR_IMPL(".ext_ram.bss", __COUNTER__) #else -#define EXT_RAM_ATTR +#define EXT_RAM_BSS_ATTR +#endif + +/** + * Deprecated Macro for putting .bss on PSRAM + */ +#if CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY +// Forces bss variable into external memory. " +#define EXT_RAM_ATTR _SECTION_ATTR_IMPL(".ext_ram.bss", __COUNTER__) _Pragma ("GCC warning \"'EXT_RAM_ATTR' macro is deprecated, please use `EXT_RAM_BSS_ATTR`\"") +#else +#define EXT_RAM_ATTR _Pragma ("GCC warning \"'EXT_RAM_ATTR' macro is deprecated, please use `EXT_RAM_BSS_ATTR`\"") #endif // Forces data into RTC slow memory. See "docs/deep-sleep-stub.rst" diff --git a/components/esp_common/test/test_attr.c b/components/esp_common/test/test_attr.c index abd771cf08..6e5378dda2 100644 --- a/components/esp_common/test/test_attr.c +++ b/components/esp_common/test/test_attr.c @@ -117,7 +117,7 @@ TEST_CASE_MULTIPLE_STAGES("Spiram test noinit memory", "[spiram]", write_spiram_ #if CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY #define TEST_BSS_NUM (256 * 1024) -static EXT_RAM_ATTR uint32_t s_bss_buffer[TEST_BSS_NUM]; +static EXT_RAM_BSS_ATTR uint32_t s_bss_buffer[TEST_BSS_NUM]; TEST_CASE("Test variables placed in external .bss segment", "[ld]") { diff --git a/components/esp_hw_support/Kconfig.spiram.common b/components/esp_hw_support/Kconfig.spiram.common index 4356b127cb..89b10e1397 100644 --- a/components/esp_hw_support/Kconfig.spiram.common +++ b/components/esp_hw_support/Kconfig.spiram.common @@ -95,12 +95,12 @@ config SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY depends on SPIRAM select ESP_ALLOW_BSS_SEG_EXTERNAL_MEMORY help - If enabled, variables with EXT_RAM_ATTR attribute will be placed in SPIRAM instead of internal DRAM. + If enabled, variables with EXT_RAM_BSS_ATTR attribute will be placed in SPIRAM instead of internal DRAM. BSS section of `lwip`, `net80211`, `pp`, `bt` libraries will be automatically placed in SPIRAM. BSS sections from other object files and libraries can also be placed in SPIRAM through linker fragment scheme `extram_bss`. - Note that the variables placed in SPIRAM using EXT_RAM_ATTR will be zero initialized. + Note that the variables placed in SPIRAM using EXT_RAM_BSS_ATTR will be zero initialized. config SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY bool "Allow .noinit segment placed in external memory" diff --git a/components/esp_system/ld/esp32/sections.ld.in b/components/esp_system/ld/esp32/sections.ld.in index c2a6c66c5b..db03190c95 100644 --- a/components/esp_system/ld/esp32/sections.ld.in +++ b/components/esp_system/ld/esp32/sections.ld.in @@ -223,7 +223,7 @@ SECTIONS _noinit_end = ABSOLUTE(.); } > dram0_0_seg - /* external memory bss, from any global variable with EXT_RAM_ATTR attribute*/ + /* external memory bss, from any global variable with EXT_RAM_BSS_ATTR attribute*/ .ext_ram.bss (NOLOAD) : { _ext_ram_bss_start = ABSOLUTE(.); diff --git a/components/esp_system/ld/esp32s2/sections.ld.in b/components/esp_system/ld/esp32s2/sections.ld.in index 270a6a94d8..c5580c4936 100644 --- a/components/esp_system/ld/esp32s2/sections.ld.in +++ b/components/esp_system/ld/esp32s2/sections.ld.in @@ -233,7 +233,7 @@ SECTIONS _noinit_end = ABSOLUTE(.); } > dram0_0_seg - /* external memory bss, from any global variable with EXT_RAM_ATTR attribute*/ + /* external memory bss, from any global variable with EXT_RAM_BSS_ATTR attribute*/ .ext_ram.bss (NOLOAD) : { _ext_ram_bss_start = ABSOLUTE(.); diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index b783c4592c..a94bb89c58 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -91,7 +91,7 @@ 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 ` and ``MALLOC_CAP_INTERNAL`` flags can be used to allocate memory from this pool. -.. only:: esp32 or esp32s2 +.. only:: SOC_SPIRAM_SUPPORTED .. _external_ram_config_bss: @@ -102,7 +102,7 @@ Because some buffers can only be allocated in internal memory, a second configur If enabled, a region of the address space starting from {IDF_TARGET_PSRAM_ADDR_START} 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_BSS_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``. diff --git a/docs/en/api-guides/memory-types.rst b/docs/en/api-guides/memory-types.rst index d50027cabb..5b351c8d75 100644 --- a/docs/en/api-guides/memory-types.rst +++ b/docs/en/api-guides/memory-types.rst @@ -16,9 +16,9 @@ DRAM (Data RAM) Non-constant static data (.data) and zero-initialized data (.bss) is placed by the linker into Internal SRAM as data memory. The remaining space in this region is used for the runtime heap. -.. only:: esp32 or esp32s2 +.. only:: SOC_SPIRAM_SUPPORTED - 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`. + By applying the ``EXT_RAM_BSS_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`. .. only:: esp32 diff --git a/docs/en/migration-guides/system.rst b/docs/en/migration-guides/system.rst index 5ae55c6ef6..0a4cf47886 100644 --- a/docs/en/migration-guides/system.rst +++ b/docs/en/migration-guides/system.rst @@ -51,6 +51,10 @@ PSRAM - `esp_spiram_get_chip_size` has been deleted. - `esp_spiram_get_size` has been moved to `esp_private/spiram_private.h` +ESP Common +---------- + +- `EXT_RAM_ATTR` is deprecated. Use this new macro `EXT_RAM_BSS_ATTR` to put .bss on PSRAM. ESP System ---------- diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index 4fc29f11ee..6d3ece3660 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -91,7 +91,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 {IDF_TARGET_PSRAM_ADDR_STAR 由于有些内存缓冲器仅可在内部存储器中分配，因此需要使用第二个配置项 :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` 定义一个内部内存池，仅限显式的内部存储器分配使用（例如用于 DMA 的存储器）。常规 ``malloc()`` 将不会从该池中分配，但可以使用 :ref:`MALLOC_CAP_DMA ` 和 ``MALLOC_CAP_INTERNAL`` 标志从该池中分配存储器。 -.. only:: esp32 or esp32s2 +.. only:: SOC_SPIRAM_SUPPORTED .. _external_ram_config_bss: @@ -102,7 +102,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 {IDF_TARGET_PSRAM_ADDR_STAR 启用该选项后，从 {IDF_TARGET_PSRAM_ADDR_START} 起始的地址空间将用于存储来自 lwip、net80211、libpp 和 bluedroid ESP-IDF 库中零初始化的数据（BSS 段）。 - ``EXT_RAM_ATTR`` 宏应用于任何静态声明（未初始化为非零值）之后，可以将附加数据从内部 BSS 段移到片外 RAM。 + ``EXT_RAM_BSS_ATTR`` 宏应用于任何静态声明（未初始化为非零值）之后，可以将附加数据从内部 BSS 段移到片外 RAM。 也可以使用链接器片段方案 ``extram_bss`` 将组件或库的 BSS 段放到片外 RAM 中。 diff --git a/docs/zh_CN/api-guides/memory-types.rst b/docs/zh_CN/api-guides/memory-types.rst index 782f4b2320..7d27bfff92 100644 --- a/docs/zh_CN/api-guides/memory-types.rst +++ b/docs/zh_CN/api-guides/memory-types.rst @@ -16,9 +16,9 @@ DRAM（数据 RAM） 非常量静态数据（.data 段）和零初始化数据（.bss 段）由链接器放入内部 SRAM 作为数据存储。此区域中的剩余空间可在程序运行时用作堆。 -.. only:: esp32 or esp32s2 +.. only:: SOC_SPIRAM_SUPPORTED - 通过应用 ``EXT_RAM_ATTR`` 宏，零初始化数据也可以放入外部 RAM。使用这个宏需要启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`。详情请见 :ref:`external_ram_config_bss`。 + 通过应用 ``EXT_RAM_BSS_ATTR`` 宏，零初始化数据也可以放入外部 RAM。使用这个宏需要启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`。详情请见 :ref:`external_ram_config_bss`。 .. only:: esp32