From 7edf5090ab859b11fca88a390126e92333cbaf8a Mon Sep 17 00:00:00 2001 From: Mo Fei Fei Date: Wed, 14 Sep 2022 21:33:50 +0800 Subject: [PATCH] Docs: Update cn trans for migration-guides/system.rst and api-reference/system/ulp-risc-v.rst --- docs/en/api-reference/system/ulp-risc-v.rst | 4 ++-- docs/en/migration-guides/release-5.x/system.rst | 2 +- docs/zh_CN/api-reference/system/ulp-risc-v.rst | 15 ++++++++++++++- .../zh_CN/migration-guides/release-5.x/system.rst | 12 ++++++++++++ 4 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/en/api-reference/system/ulp-risc-v.rst b/docs/en/api-reference/system/ulp-risc-v.rst index 8978383baf..124e530e0e 100644 --- a/docs/en/api-reference/system/ulp-risc-v.rst +++ b/docs/en/api-reference/system/ulp-risc-v.rst @@ -101,12 +101,12 @@ To access the ULP RISC-V program variables from the main program, the generated Mutual Exclusion ^^^^^^^^^^^^^^^^ -If mutual exclusion is needed when accessing a variable shared between the main program and ULP then this can be achieved by using the ULP RISC-V lock API: +If mutual exclusion is needed when accessing a variable shared between the main program and ULP, then this can be achieved by using the ULP RISC-V lock API: * :cpp:func:`ulp_riscv_lock_acquire` * :cpp:func:`ulp_riscv_lock_release` -The ULP does not have any hardware instructions to facilitate mutual exclusion so the lock API achieves this through a software algorithm (`Peterson's algorithm `_). +The ULP does not have any hardware instructions to facilitate mutual exclusion, so the lock API achieves this through a software algorithm (`Peterson's algorithm `_). The locks are intended to only be called from a single thread in the main program, and will not provide mutual exclusion if used simultaneously from multiple threads. diff --git a/docs/en/migration-guides/release-5.x/system.rst b/docs/en/migration-guides/release-5.x/system.rst index 81534abbc8..9c075ee0f3 100644 --- a/docs/en/migration-guides/release-5.x/system.rst +++ b/docs/en/migration-guides/release-5.x/system.rst @@ -153,7 +153,7 @@ The file ``portmacro_deprecated.h`` which was added to maintain backward compati App Update ---------- -- The functions :cpp:func:`esp_ota_get_app_description` and :cpp:func:`esp_ota_get_app_elf_sha256` have been termed as deprecated. Please use the alternative functions :cpp:func:`esp_app_get_description` and :cpp:func:`esp_app_get_elf_sha256` respectively. These functions have now been moved to a new component :component:`esp_app_format`. (Refer header file :component_file:`esp_app_desc.h `) +- The functions :cpp:func:`esp_ota_get_app_description` and :cpp:func:`esp_ota_get_app_elf_sha256` have been termed as deprecated. Please use the alternative functions :cpp:func:`esp_app_get_description` and :cpp:func:`esp_app_get_elf_sha256` respectively. These functions have now been moved to a new component :component:`esp_app_format`. Please refer to the header file :component_file:`esp_app_desc.h `. Bootloader Support ------------------ diff --git a/docs/zh_CN/api-reference/system/ulp-risc-v.rst b/docs/zh_CN/api-reference/system/ulp-risc-v.rst index 5c9156e243..da720f2b84 100644 --- a/docs/zh_CN/api-reference/system/ulp-risc-v.rst +++ b/docs/zh_CN/api-reference/system/ulp-risc-v.rst @@ -98,6 +98,18 @@ ULP RISC-V 协处理器代码以 C 语言（或汇编语言）编写，使用基 ulp_measurement_count = 64; } +互斥 +^^^^^^^ + +如果想要互斥地访问被主程序和 ULP 程序共享的变量，则可以通过 ULP RISC-V Lock API 来实现： + + * :cpp:func:`ulp_riscv_lock_acquire` + * :cpp:func:`ulp_riscv_lock_release` + +ULP 中的所有硬件指令都不支持互斥，所以 Lock API 需通过一种软件算法（`Peterson 算法 `_ ）来实现互斥。 + +注意，只能从主程序的单个线程中调用这些锁，如果多个线程同时调用，将无法启用互斥功能。 + 启动 ULP RISC-V 程序 ------------------------------- @@ -152,7 +164,6 @@ ULP RISC-V 协处理器由定时器启动，调用 :cpp:func:`ulp_riscv_run` 即 * 陷阱信号：ULP RISC-V 有一个硬件陷阱，将在特定条件下触发，例如非法指令。这将导致主 CPU 被 :cpp:enumerator:`ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG` 唤醒。 - 应用示例 -------------------- @@ -164,3 +175,5 @@ API 参考 ------------- .. include-build-file:: inc/ulp_riscv.inc +.. include-build-file:: inc/ulp_riscv_lock_shared.inc +.. include-build-file:: inc/ulp_riscv_lock.inc diff --git a/docs/zh_CN/migration-guides/release-5.x/system.rst b/docs/zh_CN/migration-guides/release-5.x/system.rst index 9fa7bb5903..342052b249 100644 --- a/docs/zh_CN/migration-guides/release-5.x/system.rst +++ b/docs/zh_CN/migration-guides/release-5.x/system.rst @@ -149,3 +149,15 @@ FreeRTOS 移植相关的宏 - ``vPortCPUAcquireMutex()`` 已被移除，请使用 ``spinlock_acquire()`` 函数。 - ``vPortCPUAcquireMutexTimeout()`` 已被移除，请使用 ``spinlock_acquire()`` 函数。 - ``vPortCPUReleaseMutex()`` 已被移除，请使用 ``spinlock_release()`` 函数。 + +应用程序更新 +------------ + +- 函数 :cpp:func:`esp_ota_get_app_description` 和 :cpp:func:`esp_ota_get_app_elf_sha256` 已被弃用，请分别使用 :cpp:func:`esp_app_get_description` 和 :cpp:func:`esp_app_get_elf_sha256` 函数来代替。这些函数已被移至新组件 :component:`esp_app_format`。请参考头文件 :component_file:`esp_app_desc.h `。 + +引导加载程序支持 +---------------- + +- :cpp:type:`esp_app_desc_t` 结构体此前在 :component_file:`esp_app_format.h ` 中声明，现在在 :component_file:`esp_app_desc.h ` 中声明。 + +- 函数 :cpp:func:`bootloader_common_get_partition_description` 已更新为私有函数，请使用代替函数 :cpp:func:`esp_ota_get_partition_description`。注意，此函数的第一个参数为 :cpp:type:`esp_partition_t`，而非 :cpp:type:`esp_partition_pos_t`。