Merge branch 'docs/update_format_for_kconfig_and_external-ram.rst' into 'master'

docs: Update Chinese translation for external-ram.rst and kconfig.rst

See merge request espressif/esp-idf!26517

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

@@ -4,7 +4,7 @@ Support for External RAM
 :link_to_translation:`zh_CN:[中文]`
 
 .. toctree::
-   :maxdepth: 1
+    :maxdepth: 1
 
 Introduction
 ============
@@ -168,15 +168,15 @@ External RAM use has the following restrictions:
 
     - When flash cache is disabled (for example, if the flash is being written to), the external RAM also becomes inaccessible. Any read operations from or write operations to it will lead to an illegal cache access exception. This is also the reason why ESP-IDF does not by default allocate any task stacks in external RAM (see below).
 
-    :esp32s2: - 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. Therefore when External RAM is enabled, any buffer that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` and can be freed using a standard ``free()`` call. Note, although {IDF_TARGET_NAME} has hardware support for DMA to or from external RAM, this is not yet supported in ESP-IDF.
+    :esp32s2: - 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. Therefore when External RAM is enabled, any buffer that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` and can be freed using a standard ``free()`` call. Note that although {IDF_TARGET_NAME} has hardware support for DMA to or from external RAM, this is not yet supported in ESP-IDF.
 
     :esp32s3: - Although {IDF_TARGET_NAME} has hardware support for DMA to or from external RAM, there are still limitations:
 
         :esp32s3: - DMA transaction descriptors cannot be placed in PSRAM.
-        :esp32s3: - The bandwidth that DMA accesses external RAM is very limited, especially when CPU is trying to access the external RAM at the same time.
+        :esp32s3: - The bandwidth that DMA accesses external RAM is very limited, especially when the core is trying to access the external RAM at the same time.
         :esp32s3: - You can configure :ref:`CONFIG_SPIRAM_SPEED` as 120 MHz for an octal PSRAM. The bandwidth will be improved. However there are still restrictions for this option. See :ref:`All Supported PSRAM Modes and Speeds <flash-psram-combination>` for more details.
 
-    - 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 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.
 
     - In general, external RAM will not be used as task stack memory. :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs.
 
@@ -186,9 +186,9 @@ The option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` can be used to allow
 Failure to Initialize
 =====================
 
- 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`.
+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 or esp32s2
+.. only:: esp32 or esp32s2
 
     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.
 

docs/en/api-reference/kconfig.rst

@@ -45,9 +45,9 @@ Format Checker
 
 ``kconfcheck`` tool in esp-idf-kconfig_ package is provided for checking Kconfig files against the above format rules. The checker checks all Kconfig and ``Kconfig.projbuild`` files given as arguments, and generates a new file with suffix ``.new`` with some suggestions about how to fix issues (if there are any). Please note that the checker cannot correct all format issues and the responsibility of the developer is to final check and make corrections in order to pass the tests. For example, indentations will be corrected if there is not any misleading formatting, but it cannot come up with a common prefix for options inside a menu.
 
+The ``esp-idf-kconfig`` package is available in ESP-IDF environments, where the checker tool can be invoked by running command ``python -m kconfcheck <path_to_kconfig_file>``.
 
-The ``esp-idf-kconfig`` package is available in ESP-IDF environments, where the checker tool can be invoked by running command: ``python -m kconfcheck <path_to_kconfig_file>``
+For more information, please refer to `esp-idf-kconfig package documentation <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`__.
-For more information, see `esp-idf-kconfig package documentation <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`_
 
 .. _configuration-options-compatibility:
 

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

@@ -1,10 +1,10 @@
 片外 RAM
-************************
+*************
 
 :link_to_translation:`en:[English]`
 
 .. toctree::
-   :maxdepth: 1
+    :maxdepth: 1
 
 简介
 ============
@@ -164,24 +164,23 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该
 
 使用片外 RAM 有下面一些限制：
 
- * flash cache 禁用时（比如，正在写入 flash），片外 RAM 将无法访问；同样，对片外 RAM 的读写操作也将导致 cache 访问异常。出于这个原因，ESP-IDF 不会在片外 RAM 中分配任务堆栈（详见下文）。
+.. list::
 
-.. only:: SOC_PSRAM_DMA_CAPABLE and not esp32s3
+    - flash cache 禁用时（比如，正在写入 flash），片外 RAM 将无法访问；同样，对片外 RAM 的读写操作也将导致 cache 访问异常。因此，ESP-IDF 不会在片外 RAM 中分配任务堆栈（详见下文）。
 
-    * 片外 RAM 不能用于储存 DMA 事务描述符，也不能用作 DMA 读写操作的缓冲区 (Buffer)。因此，当片外 RAM 启用时，与 DMA 搭配使用的 Buffer 必须先使用 ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` 进行分配，之后可以调用标准 ``free()`` 回调释放 Buffer。注意，尽管 {IDF_TARGET_NAME} 中已有硬件支持 DMA 与片外 RAM，但在 ESP-IDF 中，尚未提供软件支持。
+    :esp32s2: - 片外 RAM 不能用于存储 DMA 事务描述符，也不能用作 DMA 传输读写信息的 buffer。因此，当启用片外 RAM 时，任何与 DMA 结合使用的 buffer 必须使用 ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` 进行分配，之后调用标准的 ``free()`` 来释放。注意，尽管 {IDF_TARGET_NAME} 具有与外部 RAM 进行 DMA 传输的硬件支持，但在 ESP-IDF 中，尚未提供软件支持。
 
-.. only:: esp32s3
+    :esp32s3: - 尽管 {IDF_TARGET_NAME} 具有与外部 RAM 进行 DMA 传输的硬件支持，但仍有以下限制：
 
-    注意，尽管 {IDF_TARGET_NAME} 中已有硬件支持 DMA 与片外 RAM，但仍有以下限制：
+        :esp32s3: - DMA 事务描述符不能放在 PSRAM 中。
+        :esp32s3: - DMA 访问片外 RAM 的带宽非常有限，尤其是当内核尝试同时访问片外 RAM 时。
+        :esp32s3: - 将八线 PSRAM 的 :ref:`CONFIG_SPIRAM_SPEED` 配置为 120 MHz 可提高带宽，但使用此选项仍有一定限制。更多信息请参见 :ref:`所有支持的 PSRAM 模式和速度 <flash-psram-combination>`。
 
-    - DMA 访问外部 RAM 的带宽十分有限，尤其是当 CPU 同时访问外部 RAM 时。
+    - 片外 RAM 与片外 flash 使用相同的 cache 区域，这意味着频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将降低到片外 RAM 的访问速度。此外，访问大块数据会挤出 flash cache，可能在之后降低代码的执行速度。
-    - 将八线 PSRAM 的 :ref:`CONFIG_SPIRAM_SPEED` 配置为 120 MHz 可提高带宽，但使用此选项仍有一定限制，更多信息请参见 :ref:`所有支持的 PSRAM 模式和速度 <flash-psram-combination>`。
 
-* 片外 RAM 与片外 flash 使用相同的 cache 区域，这意味着频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将回落到片外 RAM 访问速度。此外，访问大块数据会挤出 flash cache，可能降低代码执行速度。
+    - 一般来说，片外 RAM 不会用作任务堆栈存储器。:cpp:func:`xTaskCreate` 及类似函数始终会为堆栈和任务 TCB 分配片上储存器。
 
- * 一般来说，片外 RAM 不会用作任务堆栈存储器。:cpp:func:`xTaskCreate` 及类似函数始终会为堆栈和任务 TCB 分配片上储存器。
+可以使用 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 选项将任务堆栈放入片外存储器。这时，必须使用 :cpp:func:`xTaskCreateStatic` 指定从片外存储器分配的任务堆栈缓冲区，否则任务堆栈将仍从片上存储器分配。
-
-可以使用 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 选项将任务堆栈放入片外存储器。这时，必须使用 :cpp:func:`xTaskCreateStatic` 指定从片外存储器分配的任务堆栈缓冲区，否则任务堆栈将会从片上存储器分配。
 
 
 初始化失败
@@ -189,7 +188,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到数据虚拟地址空间，该
 
 默认情况下，片外 RAM 初始化失败将终止 ESP-IDF 启动。如果想禁用此功能，可启用 :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 配置选项。
 
- .. only:: esp32 or esp32s2
+.. only:: esp32 or esp32s2
 
     如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，忽略失败的选项将无法使用，这是因为在链接时，链接器已经向片外存储器分配标志符。
 

docs/zh_CN/api-reference/kconfig.rst

@@ -43,7 +43,11 @@ Kconfig 文件的格式规定如下：
 格式检查器
 --------------
 
-``tools/ci/check_kconfigs.py`` 可以检查 Kconfig 文件是否符合上述格式规定。检查器会检查 ESP-IDF 目录下的所有 Kconfig 和 ``Kconfig.projbuild`` 文件，如有格式错误，会生成后缀为 ``.new`` 的新文件以提供修改建议。请注意，检查器不能解决所有格式问题，开发人员仍需终审和修改文件使其通过测试。例如，在没有其他误导性格式的情况下，检查器能够更正缩进，但无法提供菜单内选项的常用前缀。
+esp-idf-kconfig_ 软件包中的 ``kconfcheck`` 工具可以检查 Kconfig 文件是否符合上述格式规定。检查器会检查作为参数给出的所有 Kconfig 和 ``Kconfig.projbuild`` 文件，并生成一个后缀为 ``.new`` 的新文件，如有格式错误，便会在此文件中提供修改建议。注意，检查器不能解决所有格式问题，开发人员仍需终审并修改文件，使其通过测试。例如，在没有其他误导性格式的情况下，检查器能够更正缩进，但无法为菜单内选项提供常用的前缀。
+
+``esp-idf-kconfig`` 软件包可以在 ESP-IDF 环境中使用。运行命令 ``python -m kconfcheck <path_to_kconfig_file>`` 即可调用检查工具。
+
+如需了解更多内容，请参考 `esp-idf-kconfig 相关文档 <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`__。
 
 .. _configuration-options-compatibility: