Merge branch 'docs/update_trans_for_19147' into 'master'

docs: updated trans for ulp-risc-v,fatfs and sleep_modes

Closes DOC-3457

See merge request espressif/esp-idf!19395

docs/en/api-reference/system/ulp-risc-v.rst

@@ -35,7 +35,7 @@ To compile the ULP RISC-V code as part of the component, the following steps mus
 
  The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used by other generated artifacts such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP source files.  Finally, the third argument specifies the list of component source files which include the header file to be generated. This list is needed to build the dependencies correctly and ensure that the generated header file will be created before any of these files are compiled. See the section below for the concept of generated header files for ULP applications.
 
-3. Build the application as usual (e.g. `idf.py app`).
+3. Build the application as usual (e.g., `idf.py app`).
 
    Inside, the build system will take the following steps to build ULP program:
 
@@ -142,21 +142,22 @@ To disable the timer (effectively preventing the ULP program from running again)
 Debugging Your ULP RISC-V Program
 ----------------------------------
 
-When programming the ULP RISC-V it can sometimes be challenging to figure out why the program is not behaving as expected. Due to the simplicity of the core many of the standard methods of debugging, e.g. JTAG or ``printf``, are simply not available.
+When programming the ULP RISC-V, it can sometimes be challenging to figure out why the program is not behaving as expected. Due to the simplicity of the core, many of the standard methods of debugging, e.g., JTAG or ``printf``, are simply not available.
 
 Keeping this in mind, here are some ways that may help you debug you ULP RISC-V program:
 
  * Share program state through shared variables: as described in :ref:`ulp-riscv-access-variables`, both the main CPU and the ULP core can easily access global variables in RTC memory. Writing state information to such a variable from the ULP and reading it from the main CPU can help you discern what is happening on the ULP core. The downside of this approach is that it requires the main CPU to be awake, which will not always be the case. Keeping the main CPU awake might even, in some cases, mask problems, as some issues may only occur when certain power domains are powered down.
- * Printing using the bit-banged UART driver: the ULP RISC-V component comes with a low-speed bit-banged UART TX driver that can be used for printing information independently of the main CPU state. See :example:`system/ulp_riscv/uart_print` for an example of how to use this driver.
- * Trap signal: the ULP RISC-V has a hardware trap that will trigger under certain conditions, e.g. illegal instruction. This will cause the main CPU to be woken up with the wake-up cause :cpp:enumerator:`ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG`.
 
+ * Use the bit-banged UART driver to print: the ULP RISC-V component comes with a low-speed bit-banged UART TX driver that can be used for printing information independently of the main CPU state. See :example:`system/ulp_riscv/uart_print` for an example of how to use this driver.
+
+ * Trap signal: the ULP RISC-V has a hardware trap that will trigger under certain conditions, e.g., illegal instruction. This will cause the main CPU to be woken up with the wake-up cause :cpp:enumerator:`ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG`.
 
 
 Application Examples
 --------------------
 
 * ULP RISC-V Coprocessor polls GPIO while main CPU is in deep sleep: :example:`system/ulp_riscv/gpio`.
-* ULP RISC-V Coprocessor uses bit-banged UART tx to print: :example:`system/ulp_riscv/uart_print`.
+* ULP RISC-V Coprocessor uses bit-banged UART driver to print: :example:`system/ulp_riscv/uart_print`.
 * ULP RISC-V Coprocessor reads external temperature sensor while main CPU is in deep sleep: :example:`system/ulp_riscv/ds18b20_onewire`.
 
 API Reference

docs/zh_CN/api-reference/storage/fatfs.rst

@@ -121,7 +121,10 @@ FatFs 分区生成器
 
 2. base_dir - 目录名称，该目录会被编码为 FatFs 分区，也可以选择将其被烧录进设备。但注意必须在分区表中指定合适的分区大小。
 
-3. ``FLASH_IN_PROJECT`` 标志 - 用户可以通过指定 ``FLASH_IN_PROJECT``，选择在执行 ``idf.py flash -p <PORT>`` 时让分区镜像自动与应用程序二进制文件、分区表等一同烧录进设备。
+3. ``FLASH_IN_PROJECT`` 标志 - 可选参数，用户可以通过指定 ``FLASH_IN_PROJECT``，选择在执行 ``idf.py flash -p <PORT>`` 时让分区镜像自动与应用程序二进制文件、分区表等一同烧录进设备。
+
+4. ``PRESERVE_TIME`` 标志 - 可选参数，用户可强制让目标镜像保留源文件夹的时间戳。如果不保留，每个目标镜像的时间戳都将设置为 FATFS 默认初始时间（1980 年 1 月 1 日）。
+
 
 例如::
 

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

@@ -171,7 +171,9 @@ RTC 外设和内存断电
 Flash 断电
 ----------
 
-默认情况下，调用函数 :cpp:func:`esp_light_sleep_start` 后， **不会** 断电 flash。在 sleep 过程中断电 flash 存在风险。因为 flash 断电需要时间，但是在此期间，系统有可能被唤醒。此时 flash 重新被上电，断电尚未完成又重新上电的硬件行为有概率导致 flash 不能正常工作。如果用户为 flash 供电电路添加了滤波电容，断电所需时间可能会更长。此外，即使可以预知 flash 彻底断电所需的时间，有时也不能通过设置足够长的睡眠时间来确保 flash 断电的安全（比如，突发的异步唤醒源会使得实际的睡眠时间不可控）。
+默认情况下，调用函数 :cpp:func:`esp_light_sleep_start` 后， flash **不会** 断电，因为在 sleep 过程中断电 flash 存在风险。具体而言，flash 断电需要时间，但是在此期间，系统有可能被唤醒，导致 flash 重新被上电。此时，断电尚未完成又重新上电的硬件行为有可能导致 flash 无法正常工作。
+
+理论上讲，在 flash 完全断电后可以仅唤醒系统，然而现实情况是 flash 断电所需的时间很难预测。如果用户为 flash 供电电路添加了滤波电容，断电所需时间可能会更长。此外，即使可以预知 flash 彻底断电所需的时间，有时也不能通过设置足够长的睡眠时间来确保 flash 断电的安全（比如，突发的异步唤醒源会使得实际的睡眠时间不可控）。
 
 .. warning::
     如果在 flash 的供电电路上添加了滤波电容，那么应当尽一切可能避免 flash 断电。
@@ -193,7 +195,7 @@ Flash 断电
 
     .. list::
 
-        - Light sleep 时，ESP-IDF 并未提供保证 flash 一定会被断电的机制。
+        - Light sleep 时，ESP-IDF 没有提供保证 flash 一定会被断电的机制。
         - 不管用户的配置如何，函数 :cpp:func:`esp_deep_sleep_start` 都会强制断电 flash。
 
 进入 Light-sleep 模式

docs/zh_CN/api-reference/system/ulp-risc-v.rst

@@ -11,7 +11,7 @@ ULP RISC-V 协处理器代码以 C 语言（或汇编语言）编写，使用基
 
 如果您已依照 :doc:`快速入门指南 <../../../get-started/index>` 中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 ULP RISC-V 工具链已经被默认安装到了您的开发环境中。
 
-.. note: 在早期版本的ESP-IDF中，RISC-V工具链具有不同的名称：`riscv-none-embed-gcc`。
+.. note: 在早期版本的 ESP-IDF 中，RISC-V 工具链具有不同的名称：`riscv-none-embed-gcc`。
 
 编译 ULP RISC-V 代码
 -----------------------------
@@ -51,18 +51,20 @@ ULP RISC-V 协处理器代码以 C 语言（或汇编语言）编写，使用基
 
    6. **创建 LD 导出脚本和头文件** （``ulp_app_name.ld`` 和 ``ulp_app_name.h``），包含来自 ``ulp_app_name.sym`` 的符号。此步骤可借助 ``esp32ulp_mapgen.py`` 工具来完成。
 
-   7. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。** 
+   7. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。**
+
+.. _ulp-riscv-access-variables:
 
 访问 ULP RISC-V 程序变量
 ----------------------------
 
-在 ULP RISC-V 程序中定义的全局符号也可以在主程序中使用。 
+在 ULP RISC-V 程序中定义的全局符号也可以在主程序中使用。
 
 例如，ULP RISC-V 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数。
 
 .. code-block:: c
 
-    volatile int measurement_count; 
+    volatile int measurement_count;
 
     int some_function()
     {
@@ -136,10 +138,26 @@ ULP RISC-V 协处理器由定时器启动，调用 :cpp:func:`ulp_riscv_run` 即
 
 如需禁用定时器（有效防止 ULP 程序再次运行），请清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位，此项操作可在 ULP 代码或主程序中进行。
 
+
+调试 ULP RISC-V 程序
+----------------------------------
+
+在对 ULP RISC-V 进行编程时，若程序未按预期运行，有时很难找出的原因。因为其内核的简单性，许多标准的调试方法如 JTAG 或 ``printf`` 无法使用。
+
+以下方法可以帮助您调试 ULP RISC-V 程序：
+
+ * 通过共享变量查看程序状态：如 :ref:`ulp-riscv-access-variables` 中所述，主 CPU 以及 ULP 内核都可以轻松访问 RTC 内存中的全局变量。通过 ULP 向该变量中写入状态信息，然后通过主 CPU 读取状态信息，可帮助您了解 ULP 内核的状态。该方法的缺点在于它要求主 CPU 一直处于唤醒状态，但现实情况可能并非如此。有时，保持主 CPU 处于唤醒状态还可能会掩盖一些问题，因为某些问题可能仅在特定电源域断电时才会出现。
+
+ * 使用 bit-banged UART 驱动程序打印：ULP RISC-V 组件中有一个低速 bit-banged UART TX 驱动程序，可用于打印独立于主 CPU 状态的信息。有关如何使用此驱动程序的示例，请参阅 :example:`system/ulp_riscv/uart_print`。
+
+ * 陷阱信号：ULP RISC-V 有一个硬件陷阱，将在特定条件下触发，例如非法指令。这将导致主 CPU 被 :cpp:enumerator:`ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG` 唤醒。
+
+
 应用示例
 --------------------
 
 * 主处理器处于 Deep-sleep 状态时，ULP RISC-V 协处理器轮询 GPIO：:example:`system/ulp_riscv/gpio`。
+* ULP RISC-V 协处理器使用 bit-banged UART 驱动程序打印: :example:`system/ulp_riscv/uart_print`.
 * 主处理器处于 Deep-sleep 状态时，ULP RISC-V 协处理器读取外部温度传感器：:example:`system/ulp_riscv/ds18b20_onewire`。
 
 API 参考