From a68ad0192d4f093a4ea89e5493763769eecd9643 Mon Sep 17 00:00:00 2001 From: renpeiying Date: Mon, 25 Sep 2023 16:49:33 +0800 Subject: [PATCH] docs: Provide Chinese translation for api-reference/system/esp_http_ota and esp_function_with_shared_stack.rst --- docs/en/api-reference/system/async_memcpy.rst | 4 +- .../system/esp_function_with_shared_stack.rst | 8 +- .../en/api-reference/system/esp_https_ota.rst | 32 ++-- .../api-reference/system/async_memcpy.rst | 4 +- .../system/esp_function_with_shared_stack.rst | 62 +++++++- .../api-reference/system/esp_https_ota.rst | 144 +++++++++++++++++- 6 files changed, 231 insertions(+), 23 deletions(-) diff --git a/docs/en/api-reference/system/async_memcpy.rst b/docs/en/api-reference/system/async_memcpy.rst index 37ef709aea..d2ff7f2030 100644 --- a/docs/en/api-reference/system/async_memcpy.rst +++ b/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`: diff --git a/docs/en/api-reference/system/esp_function_with_shared_stack.rst b/docs/en/api-reference/system/esp_function_with_shared_stack.rst index d50033094a..94446ee6ad 100644 --- a/docs/en/api-reference/system/esp_function_with_shared_stack.rst +++ b/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 - - diff --git a/docs/en/api-reference/system/esp_https_ota.rst b/docs/en/api-reference/system/esp_https_ota.rst index 6301e894fa..d46fe0d989 100644 --- a/docs/en/api-reference/system/esp_https_ota.rst +++ b/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 ` 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 ` 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 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 a 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,14 +70,16 @@ 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 @@ -83,8 +87,6 @@ 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 ------------- diff --git a/docs/zh_CN/api-reference/system/async_memcpy.rst b/docs/zh_CN/api-reference/system/async_memcpy.rst index bfba6be1da..fdd40d6bef 100644 --- a/docs/zh_CN/api-reference/system/async_memcpy.rst +++ b/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 diff --git a/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst b/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst index 22ff5f93e3..2f8b29bf0b 100644 --- a/docs/zh_CN/api-reference/system/esp_function_with_shared_stack.rst +++ b/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 \ No newline at end of file +使用外部堆栈调用函数 +================================= + +: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 diff --git a/docs/zh_CN/api-reference/system/esp_https_ota.rst b/docs/zh_CN/api-reference/system/esp_https_ota.rst index e831ef944b..9ecc862e6c 100644 --- a/docs/zh_CN/api-reference/system/esp_https_ota.rst +++ b/docs/zh_CN/api-reference/system/esp_https_ota.rst @@ -1 +1,143 @@ -.. include:: ../../../en/api-reference/system/esp_https_ota.rst +ESP HTTPS OTA 升级 +==================== + +:link_to_translation:`en:[English]` + +概述 +-------- + +``esp_https_ota`` 是现有 OTA（空中升级）API 的抽象层，其中提供了简化的 API，能够通过 HTTPS 升级固件。 + +应用示例 +------------------- + + .. code-block:: c + + esp_err_t do_firmware_upgrade() + { + esp_http_client_config_t config = { + .url = CONFIG_FIRMWARE_UPGRADE_URL, + .cert_pem = (char *)server_cert_pem_start, + }; + esp_https_ota_config_t ota_config = { + .http_config = &config, + }; + esp_err_t ret = esp_https_ota(&ota_config); + if (ret == ESP_OK) { + esp_restart(); + } else { + return ESP_FAIL; + } + return ESP_OK; + } + + +服务器验证 +------------------- + +验证服务器时，应将 PEM 格式的根证书提供给 :cpp:member:`esp_http_client_config_t::cert_pem` 成员。如需了解有关服务器验证的更多信息，请参阅 :ref:`esp_tls_server_verification`。 + +.. note:: + + 应使用服务器端点的 **根** 证书应用于验证，而不能使用证书链中的任何中间证书，因为根证书有效期最长，且通常长时间维持不变。用户还可以通过 :cpp:member:`esp_http_client_config_t::crt_bundle_attach` 成员使用 ``ESP x509 证书包`` 功能进行验证，其中涵盖了大多数受信任的根证书。 + +通过 HTTPS 下载部分镜像 +--------------------------------- + +要使用部分镜像下载功能，请启用 ``esp_https_ota_config_t`` 中的 ``partial_http_download`` 配置。启用此配置后，固件镜像将通过多个指定大小的 HTTP 请求进行下载。将 ``max_http_request_size`` 设置为所需值，即可指定每个请求的最大内容长度。 + +在从 AWS S3 等服务获取镜像时，这一选项非常有用。在启用该选项时， 可以将 mbedTLS Rx 的 buffer 大小（即 :ref:`CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN`）设置为较小的值。不启用此配置时，无法将其设置为较小值。 + +mbedTLS Rx buffer 的默认大小为 16 K，但如果将 ``partial_http_download`` 的 ``max_http_request_size`` 设置为 4 K，便能将 mbedTLS Rx 的 buffer 减小到 4 K。使用这一配置方式预计可以节省约 12 K 内存。 + + +签名验证 +---------------------- + +要进一步提升安全性，还可以验证 OTA 固件镜像的签名。更多内容请参考 :ref:`secure-ota-updates`。 + + +高级 API +------------- + +``esp_https_ota`` 还提供一些高级 API，用于查看 OTA 过程的更多信息并满足其他控制需求。 + +如需查看使用高级 ESP_HTTPS_OTA API 的示例，请前往 :example:`system/ota/advanced_https_ota`。 + + +.. _ota_updates_pre-encrypted-firmware: + +使用预加密固件进行 OTA 升级 +---------------------------------------- + +如需使用预加密的固件进行 OTA 升级，请在组件的菜单配置中启用 :ref:`CONFIG_ESP_HTTPS_OTA_DECRYPT_CB` 选项。 + +如需查看使用预加密固件进行 OTA 升级的示例，请前往 :example:`system/ota/pre_encrypted_ota`。 + + +OTA 系统事件 +----------------- + +ESP HTTPS OTA 过程中可能发生各种系统事件。当特定事件发生时，会由 :doc:`../system/esp_event` 触发处理程序。此处理程序必须使用 :cpp:func:`esp_event_handler_register` 注册。这有助于 ESP HTTPS OTA 进行事件处理。 + +:cpp:enum:`esp_https_ota_event_t` 中包含了使用 ESP HTTPS OTA 升级时可能发生的所有事件。 + +事件处理程序示例 +^^^^^^^^^^^^^^^^^^^^^ + + .. code-block:: c + + /* 用于捕获系统事件的事件处理程序 */ + static void event_handler(void* arg, esp_event_base_t event_base, + int32_t event_id, void* event_data) + { + if (event_base == ESP_HTTPS_OTA_EVENT) { + switch (event_id) { + case ESP_HTTPS_OTA_START: + ESP_LOGI(TAG, "OTA started"); + break; + case ESP_HTTPS_OTA_CONNECTED: + ESP_LOGI(TAG, "Connected to server"); + break; + case ESP_HTTPS_OTA_GET_IMG_DESC: + ESP_LOGI(TAG, "Reading Image Description"); + break; + case ESP_HTTPS_OTA_VERIFY_CHIP_ID: + ESP_LOGI(TAG, "Verifying chip id of new image: %d", *(esp_chip_id_t *)event_data); + break; + case ESP_HTTPS_OTA_DECRYPT_CB: + ESP_LOGI(TAG, "Callback to decrypt function"); + break; + case ESP_HTTPS_OTA_WRITE_FLASH: + ESP_LOGD(TAG, "Writing to flash: %d written", *(int *)event_data); + break; + case ESP_HTTPS_OTA_UPDATE_BOOT_PARTITION: + ESP_LOGI(TAG, "Boot partition updated. Next Partition: %d", *(esp_partition_subtype_t *)event_data); + break; + case ESP_HTTPS_OTA_FINISH: + ESP_LOGI(TAG, "OTA finish"); + break; + case ESP_HTTPS_OTA_ABORT: + ESP_LOGI(TAG, "OTA abort"); + break; + } + } + } + +系统事件循环中，不同 ESP HTTPS OTA 事件的预期数据类型如下所示： + + - ESP_HTTPS_OTA_START : ``NULL`` + - ESP_HTTPS_OTA_CONNECTED : ``NULL`` + - ESP_HTTPS_OTA_GET_IMG_DESC : ``NULL`` + - ESP_HTTPS_OTA_VERIFY_CHIP_ID : ``esp_chip_id_t`` + - ESP_HTTPS_OTA_DECRYPT_CB : ``NULL`` + - ESP_HTTPS_OTA_WRITE_FLASH : ``int`` + - ESP_HTTPS_OTA_UPDATE_BOOT_PARTITION : ``esp_partition_subtype_t`` + - ESP_HTTPS_OTA_FINISH : ``NULL`` + - ESP_HTTPS_OTA_ABORT : ``NULL`` + + +API 参考 +------------- + +.. include-build-file:: inc/esp_https_ota.inc