Merge branch 'docs/update_CN_trans_api-guides' into 'master'

docs: updated CN trans for linker-script-generation and external-ram

Closes DOC-2803

See merge request espressif/esp-idf!17510

docs/en/api-guides/linker-script-generation.rst

@@ -5,7 +5,7 @@ Linker Script Generation
 Overview
 --------
 
-There are several :ref:`memory regions<memory-layout>` where code and data can be placed. Code and read-only data are placed by default in flash, writable data in RAM, etc. However, it is sometimes necessary to change these default placements. 
+There are several :ref:`memory regions<memory-layout>` where code and data can be placed. Code and read-only data are placed by default in flash, writable data in RAM, etc. However, it is sometimes necessary to change these default placements.
 
 .. only:: SOC_ULP_SUPPORTED
 
@@ -71,6 +71,7 @@ Placing object files
 """"""""""""""""""""
 
 Suppose the entirety of ``my_src1.o`` is performance-critical, so it is desirable to place it in RAM. On the other hand, the entirety of ``my_src2.o`` contains symbols needed coming out of deep sleep, so it needs to be put under RTC memory.
+
 In the linker fragment file, we can write:
 
 .. code-block:: none
@@ -227,7 +228,7 @@ The three fragment types share a common grammar:
 - type: Corresponds to the fragment type, can either be ``sections``, ``scheme`` or ``mapping``.
 - name: The name of the fragment, should be unique for the specified fragment type.
 - key, value: Contents of the fragment; each fragment type may support different keys and different grammars for the key values.
-   
+
     - For :ref:`sections<ldgen-sections-fragment>` and :ref:`scheme<ldgen-scheme-fragment>`, the only supported key is ``entries``
     - For :ref:`mappings<ldgen-mapping-fragment>`, both ``archive`` and ``entries`` are supported.
 
@@ -431,7 +432,7 @@ Example:
     entries:
         * (noflash)
 
-Aside from the entity and scheme, flags can also be specified in an entry. The following flags are supported (note: <> = argument name, [] = optional): 
+Aside from the entity and scheme, flags can also be specified in an entry. The following flags are supported (note: <> = argument name, [] = optional):
 
 1. ALIGN(<alignment>[, pre, post])
 
@@ -446,7 +447,7 @@ Aside from the entity and scheme, flags can also be specified in an entry. The f
 2. SORT([<sort_by_first>, <sort_by_second>])
 
     Emits ``SORT_BY_NAME``, ``SORT_BY_ALIGNMENT``, ``SORT_BY_INIT_PRIORITY`` or ``SORT`` in the input section description.
-    
+
     Possible values for ``sort_by_first`` and ``sort_by_second`` are: ``name``, ``alignment``, ``init_priority``.
 
     If both ``sort_by_first`` and ``sort_by_second`` are not specified, the input sections are sorted by name. If both are specified, then the nested sorting follows the same rules discussed in https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards.html.
@@ -474,8 +475,8 @@ When adding flags, the specific ``section -> target`` in the scheme needs to be
     # Notes:
     # A. semicolon after entity-scheme
     # B. comma before section2 -> target2
-    # C. section1 -> target1 and section2 -> target2 should be defined in entries of scheme1 
+    # C. section1 -> target1 and section2 -> target2 should be defined in entries of scheme1
-    entity1 (scheme1); 
+    entity1 (scheme1);
         section1 -> target1 KEEP() ALIGN(4, pre, post),
         section2 -> target2 SURROUND(sym) ALIGN(4, post) SORT()
 
@@ -512,7 +513,7 @@ Note that ALIGN and SURROUND, as mentioned in the flag descriptions, are order s
 On Symbol-Granularity Placements
 """"""""""""""""""""""""""""""""
 
-Symbol granularity placements is possible due to compiler flags ``-ffunction-sections`` and ``-ffdata-sections``. ESP-IDF compiles with these flags by default. 
+Symbol granularity placements is possible due to compiler flags ``-ffunction-sections`` and ``-ffdata-sections``. ESP-IDF compiles with these flags by default.
 If the user opts to remove these flags, then the symbol-granularity placements will not work. Furthermore, even with the presence of these flags, there are still other limitations to keep in mind due to the dependence on the compiler's emitted output sections.
 
 For example, with ``-ffunction-sections``, separate sections are emitted for each function; with section names predictably constructed i.e. ``.text.{func_name}`` and ``.literal.{func_name}``. This is not the case for string literals within the function, as they go to pooled or generated section names.

docs/zh_CN/api-guides/external-ram.rst

@@ -137,12 +137,18 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 {IDF_TARGET_PSRAM_ADDR_STAR
 
 * 片外 RAM 与片外 flash 使用相同的 cache 区域，这意味着频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将回落到片外 RAM 访问速度。此外，访问大块数据会挤出 flash cache，可能降低代码执行速度。
 
- * 一般来说，片外 RAM 不可用作任务堆栈存储器。因此 :cpp:func:`xTaskCreate` 及类似函数将始终为堆栈和任务 TCB 分配片上储存器，而 :cpp:func:`xTaskCreateStatic` 类型的函数将检查传递的 Buffer 是否属于片上存储器。
+ * 一般来说，片外 RAM 不会用作任务堆栈存储器。:cpp:func:`xTaskCreate` 及类似函数始终会为堆栈和任务 TCB 分配片上储存器。
 
 .. only:: esp32
 
     可以使用 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 选项将任务堆栈放入片外存储器。这时，必须使用 :cpp:func:`xTaskCreateStatic` 指定从片外存储器分配的任务堆栈缓冲区，否则任务堆栈将会从片上存储器分配。
 
+
+.. only:: not esp32
+
+    可以使用 :cpp:func:`xTaskCreateStatic` 显式地将任务堆栈放入片外存储器。
+
+
 初始化失败
 =====================
 

docs/zh_CN/api-guides/linker-script-generation.rst

@@ -71,6 +71,7 @@
 """"""""""""
 
 假设整个 ``my_src1.o`` 目标文件对性能至关重要，所以最好把该文件放在 RAM 中。另外，``my_src2.o`` 目标文件包含从深度睡眠唤醒所需的符号，因此需要将其存放到 RTC 存储器中。
+
 在链接器片段文件中可以写入以下内容：
 
 .. code-block:: none
@@ -125,6 +126,7 @@
     entries:
         * (rtc)
 
+
 .. _ldgen-conditional-placements :
 
 根据具体配置存放
@@ -227,8 +229,8 @@
 - 名称：片段名称，指定片段类型的片段名称应唯一。
 - 键值：片段内容。每个片段类型可支持不同的键值和不同的键值语法。
 
-    - 在 ``段`` 和 ``协议`` 中，仅支持 ``entries`` 键。
+    - 在 :ref:`段 <ldgen-sections-fragment>` 和 :ref:`协议 <ldgen-scheme-fragment>` 中，仅支持 ``entries`` 键。
-    - 在 ``映射`` 中，键支持 ``archive`` 和 ``entries``。
+    - 在 :ref:`映射 <ldgen-mapping-fragment>` 中，支持 ``archive`` 和 ``entries`` 键。
 
 .. note::
 
@@ -445,7 +447,7 @@
 2. SORT([<sort_by_first>, <sort_by_second>])
 
     在输入段描述中输出 ``SORT_BY_NAME``, ``SORT_BY_ALIGNMENT``, ``SORT_BY_INIT_PRIORITY`` 或 ``SORT``。
-    
+
    ``sort_by_first`` 和 ``sort_by_second`` 的值可以是：``name``、``alignment``、``init_priority``。
 
     如果既没指定 ``sort_by_first`` 也没指定 ``sort_by_second``，则输入段会按照名称排序，如果两者都指定了，那么嵌套排序会遵循 https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards.html 中的规则。
@@ -473,8 +475,8 @@
     # 注意
     # A. entity-scheme 后使用分号
     # B. section2 -> target2 前使用逗号
-    # C. 在 scheme1 条目中 定义 section1 -> target1 和 section2 -> target2 
+    # C. 在 scheme1 条目中定义 section1 -> target1 和 section2 -> target2
-    entity1 (scheme1); 
+    entity1 (scheme1);
         section1 -> target1 KEEP() ALIGN(4, pre, post),
         section2 -> target2 SURROUND(sym) ALIGN(4, post) SORT()