Merge branch 'docs/add_cn_trans_for_esp_http_ota_and_esp_function_wit…

…h_shared_stack.rst' into 'master'

docs: Provide Chinese translation for api-reference/system/esp_http_ota and esp_function_with_shared_stack.rst

See merge request espressif/esp-idf!26195

docs/en/api-reference/system/async_memcpy.rst

@@ -8,7 +8,7 @@ Overview
 
 {IDF_TARGET_NAME} has a DMA engine which can help to offload internal memory copy operations from the CPU in an asynchronous way.
 
-The async memcpy API wraps all DMA configurations and operations, the signature of :cpp:func:`esp_async_memcpy` is almost the same as the standard libc ``memcpy`` function.
+The async memcpy API wraps all DMA configurations and operations. The signature of :cpp:func:`esp_async_memcpy` is almost the same as the standard libc ``memcpy`` function.
 
 The DMA allows multiple memory copy requests to be queued up before the first one is completed, which allows overlap of computation and memory copy. Moreover, it is still possible to know the exact time when a memory copy request is completed by registering an event callback.
 
@@ -31,7 +31,7 @@ There are several ways to install the async memcpy driver, depending on the unde
     :SOC_CP_DMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_cpdma` is used to install the async memcpy driver based on the CP DMA engine.
     :SOC_AHB_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_gdma_ahb` is used to install the async memcpy driver based on the AHB GDMA engine.
     :SOC_AXI_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_gdma_axi` is used to install the async memcpy driver based on the AXI GDMA engine.
-    - :cpp:func:`esp_async_memcpy_install` is a generic API to install the async memcpy driver with a default DMA engine. If the SoC has the CP_DMA engine, the default DMA engine is CP_DMA. Otherwise, the default DMA engine is AHB_GDMA.
+    - :cpp:func:`esp_async_memcpy_install` is a generic API to install the async memcpy driver with a default DMA engine. If the SoC has the CP DMA engine, the default DMA engine is CP DMA. Otherwise, the default DMA engine is AHB GDMA.
 
 Driver configuration is described in :cpp:type:`async_memcpy_config_t`:
 

docs/en/api-reference/system/esp_function_with_shared_stack.rst

@@ -1,10 +1,13 @@
 Call Function with External Stack
 =================================
 
+:link_to_translation:`zh_CN:[中文]`
+
 Overview
 --------
 
-A given function can be executed with a user-allocated stack space which is independent of current task stack, this mechanism can be used to save stack space wasted by tasks which call a common function with intensive stack usage such as ``printf``. The given function can be called inside the shared stack space which is a callback function deferred by calling :cpp:func:`esp_execute_shared_stack_function`, passing that function as a parameter.
+A given function can be executed with a user-allocated stack space which is independent of current task stack. This mechanism can be used to save stack space wasted by tasks which call a common function with intensive stack usage such as ``printf``. The given function can be called inside the shared stack space, which is a callback function deferred by calling :cpp:func:`esp_execute_shared_stack_function`, passing that function as a parameter.
+
 
 Usage
 -----
@@ -49,11 +52,10 @@ The usage may look like the code below:
         free(shared_stack);
     }
 
+
 .. _esp-call-with-stack-basic_usage:
 
 API Reference
 -------------
 
 .. include-build-file:: inc/esp_expression_with_stack.inc
-
-

docs/en/api-reference/system/esp_https_ota.rst

@@ -1,18 +1,18 @@
 ESP HTTPS OTA
 =============
 
+:link_to_translation:`zh_CN:[中文]`
+
 Overview
 --------
 
-``esp_https_ota`` provides simplified APIs to perform firmware upgrades over HTTPS. It is an abstraction layer over existing OTA APIs.
+``esp_https_ota`` provides simplified APIs to perform firmware upgrades over HTTPS. It is an abstraction layer over the existing OTA APIs.
 
 Application Example
 -------------------
 
     .. code-block:: c
 
-    ::
-
         esp_err_t do_firmware_upgrade()
         {
             esp_http_client_config_t config = {
@@ -35,25 +35,27 @@ Application Example
 Server Verification
 -------------------
 
-Please refer to :ref:`ESP-TLS: TLS Server Verification <esp_tls_server_verification>` for more information on server verification. The root certificate (in PEM format) needs to be provided to the :cpp:member:`esp_http_client_config_t::cert_pem` member.
+Please refer to :ref:`ESP-TLS: TLS Server Verification <esp_tls_server_verification>` for more information on server verification. The root certificate in PEM format needs to be provided to the :cpp:member:`esp_http_client_config_t::cert_pem` member.
 
 .. note::
 
-    The server-endpoint **root** certificate should be used for verification instead of any intermediate ones from the certificate chain. The reason is that the root certificate has the maximum validity and usually remains the same for a long period of time. Users can also use the ``ESP x509 Certificate Bundle`` feature for verification, which covers most of the trusted root certificates (using the :cpp:member:`esp_http_client_config_t::crt_bundle_attach` member).
+    The server-endpoint **root** certificate should be used for verification instead of any intermediate ones from the certificate chain. The reason is that the root certificate has the maximum validity and usually remains the same for a long period of time. Users can also use the :cpp:member:`esp_http_client_config_t::crt_bundle_attach` member for verification by the ``ESP x509 Certificate Bundle`` feature, which covers most of the trusted root certificates.
 
 Partial Image Download over HTTPS
 ---------------------------------
 
-To use partial image download feature, enable ``partial_http_download`` configuration in ``esp_https_ota_config_t``. When this configuration is enabled, firmware image will be downloaded in multiple HTTP requests of specified size. Maximum content length of each request can be specified by setting ``max_http_request_size`` to required value.
+To use the partial image download feature, enable ``partial_http_download`` configuration in ``esp_https_ota_config_t``. When this configuration is enabled, firmware image will be downloaded in multiple HTTP requests of specified sizes. Maximum content length of each request can be specified by setting ``max_http_request_size`` to the required value.
+
+This option is useful while fetching image from a service like AWS S3, where mbedTLS Rx buffer size (:ref:`CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN`) can be set to a lower value which is not possible without enabling this configuration.
 
-This option is useful while fetching image from a service like AWS S3, where mbedTLS Rx buffer size (:ref:`CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN`) can be set to lower value which is not possible without enabling this configuration.
+Default value of mbedTLS Rx buffer size is set to 16 K. By using ``partial_http_download`` with ``max_http_request_size`` of 4 K, size of mbedTLS Rx buffer can be reduced to 4 K. With this configuration, memory saving of around 12 K is expected.
 
-Default value of mbedTLS Rx buffer size is set to 16K. By using partial_http_download with max_http_request_size of 4K, size of mbedTLS Rx buffer can be reduced to 4K. With this configuration, memory saving of around 12K is expected.
 
 Signature Verification
 ----------------------
 
-For additional security, signature of OTA firmware images can be verified. For that, refer :ref:`secure-ota-updates`
+For additional security, signature of OTA firmware images can be verified. For more information， please refer to :ref:`secure-ota-updates`.
+
 
 Advanced APIs
 -------------
@@ -68,23 +70,23 @@ Example that uses advanced ESP_HTTPS_OTA APIs: :example:`system/ota/advanced_htt
 OTA Upgrades with Pre-Encrypted Firmware
 ----------------------------------------
 
-To perform OTA upgrades with Pre-Encrypted Firmware, please enable :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` in component menuconfig.
+To perform OTA upgrades with pre-encrypted firmware, please enable :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` in component menuconfig.
+
+Example that performs OTA upgrade with pre-encrypted firmware: :example:`system/ota/pre_encrypted_ota`.
 
-Example that performs OTA upgrade with Pre-Encrypted Firmware: :example:`system/ota/pre_encrypted_ota`.
 
 OTA System Events
 -----------------
 
-ESP HTTPS OTA has various events for which a handler can be triggered by :doc:`the Event Loop library <../system/esp_event>` when the particular event occurs. The handler has to be registered using :cpp:func:`esp_event_handler_register`. This helps in event handling for ESP HTTPS OTA.
+ESP HTTPS OTA has various events for which a handler can be triggered by the :doc:`../system/esp_event` when the particular event occurs. The handler has to be registered using :cpp:func:`esp_event_handler_register`. This helps the event handling for ESP HTTPS OTA.
+
 :cpp:enum:`esp_https_ota_event_t` has all the events which can happen when performing OTA upgrade using ESP HTTPS OTA.
 
 Event Handler Example
 ^^^^^^^^^^^^^^^^^^^^^
 
     .. code-block:: c
 
-    ::
-
         /* Event handler for catching system events */
         static void event_handler(void* arg, esp_event_base_t event_base,
                                 int32_t event_id, void* event_data)
@@ -123,6 +125,7 @@ Event Handler Example
         }
 
 Expected data type for different ESP HTTPS OTA events in the system event loop:
+
     - ESP_HTTPS_OTA_START                     : ``NULL``
     - ESP_HTTPS_OTA_CONNECTED                 : ``NULL``
     - ESP_HTTPS_OTA_GET_IMG_DESC              : ``NULL``
@@ -133,6 +136,7 @@ Expected data type for different ESP HTTPS OTA events in the system event loop:
     - ESP_HTTPS_OTA_FINISH                    : ``NULL``
     - ESP_HTTPS_OTA_ABORT                     : ``NULL``
 
+
 API Reference
 -------------
 

docs/zh_CN/api-reference/system/async_memcpy.rst

@@ -31,13 +31,13 @@ DMA 允许多个内存复制请求在首个请求完成之前排队，即允许
     :SOC_CP_DMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_cpdma` 用于安装基于 CP DMA 引擎的异步 memcpy 驱动。
     :SOC_AHB_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_gdma_ahb` 用于安装基于 AHB GDMA 引擎的异步 memcpy 驱动。
     :SOC_AXI_GDMA_SUPPORTED: - :cpp:func:`esp_async_memcpy_install_gdma_axi` 用于安装基于 AXI GDMA 引擎的异步 memcpy 驱动。
-    - :cpp:func:`esp_async_memcpy_install` 是一个通用 API，用于安装带有默认 DMA 引擎的异步 memcpy 驱动。如果 SoC 具有 CP_DMA 引擎，则默认 DMA 引擎为 CP_DMA，否则，默认 DMA 引擎为 AHB_GDMA。
+    - :cpp:func:`esp_async_memcpy_install` 是一个通用 API，用于安装带有默认 DMA 引擎的异步 memcpy 驱动。如果 SoC 具有 CP DMA 引擎，则默认 DMA 引擎为 CP DMA，否则，默认 DMA 引擎为 AHB GDMA。
 
 在 :cpp:type:`async_memcpy_config_t` 中设置驱动配置：
 
 * :cpp:member:`backlog`：此项用于配置首个请求完成前可以排队的最大内存复制事务数量。如果将此字段设置为零，会应用默认值 4。
 * :cpp:member:`sram_trans_align`：声明 SRAM 中数据地址和复制大小的对齐方式，如果数据没有对齐限制，则设置为零。如果设置为四的倍数值（即 4X），驱动程序将内部启用突发模式，这有利于某些和性能相关的应用程序。
-* :cpp:member:`psram_trans_align`：声明 PSRAM 中数据地址和复制大小声明对齐方式。如果 memcpy 的目标地址位于 PSRAM 中，用户必须给出有一个效值（只支持 16、32、64）。如果设置为零，会默认采用 16 位对齐。在内部，驱动程序会根据对齐方式来配置 DMA 访问 PSRAM 时所用的块大小。
+* :cpp:member:`psram_trans_align`：声明 PSRAM 中数据地址和复制大小的对齐方式。如果 memcpy 的目标地址位于 PSRAM 中，用户必须给出一个有效值（只支持 16、32、64）。如果设置为零，会默认采用 16 位对齐。在内部，驱动程序会根据对齐方式来配置 DMA 访问 PSRAM 时所用的块大小。
 * :cpp:member:`flags`：此项可以启用一些特殊的驱动功能。
 
 .. code-block:: c

docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst

@@ -1 +1,61 @@
-.. include:: ../../../en/api-reference/system/esp_function_with_shared_stack.rst
+使用外部堆栈调用函数
+=================================
+
+:link_to_translation:`en:[English]`
+
+概述
+--------
+
+执行某个给定函数时，可以使用用户分配的堆栈空间，且该堆栈空间独立于当前任务的堆栈。这一机制能够节省在调用常用函数时浪费大量堆栈空间，例如 ``printf`` 函数。具体而言，将给定函数作为参数传入 :cpp:func:`esp_execute_shared_stack_function` 中，给定函数便会在共享堆栈空间内作为回调函数延迟执行。
+
+
+使用方法
+--------
+
+:cpp:func:`esp_execute_shared_stack_function` 需要四个参数：
+
+- 由调用者分配的互斥锁，防止同一函数共享分配的堆栈
+- 指向分配的堆栈顶部的指针
+- 以字节为单位的堆栈的大小
+- 指向需要共享堆栈的函数的指针
+
+通过这一功能，用户指定的函数被作为回调函数延迟执行，并在用户分配的空间中调用，无需从当前任务堆栈中获取空间。
+
+该函数的使用方式如下所示：
+
+.. code-block:: c
+
+    void external_stack_function(void)
+    {
+        printf("Executing this printf from external stack! \n");
+    }
+
+    //假设要使用一个单独的堆栈空间来调用 printf 函数
+    //允许应用程序减小其堆栈大小
+    void app_main()
+    {
+        //从堆中或以静态方式分配一个堆栈 buffer：
+        StackType_t *shared_stack = malloc(8192 * sizeof(StackType_t));
+        assert(shared_stack != NULL);
+
+        //分配一个互斥锁：
+        SemaphoreHandle_t printf_lock = xSemaphoreCreateMutex();
+        assert(printf_lock != NULL);
+
+        //使用宏助手调用所需函数：
+        esp_execute_shared_stack_function(printf_lock,
+                                        shared_stack,
+                                        8192,
+                                        external_stack_function);
+
+        vSemaphoreDelete(printf_lock);
+        free(shared_stack);
+    }
+
+
+.. _esp-call-with-stack-basic_usage:
+
+API 参考
+-------------
+
+.. include-build-file:: inc/esp_expression_with_stack.inc