From f0f91578cddae31977ca03bc36e2c318ea5388d4 Mon Sep 17 00:00:00 2001 From: wuzhenghui Date: Mon, 7 Sep 2026 10:56:27 +0800 Subject: [PATCH] fix(doc): fix uart output handling doc format --- docs/en/api-reference/system/sleep_modes.rst | 18 +++++++++--------- .../zh_CN/api-reference/system/sleep_modes.rst | 14 +++++++------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index d563002cf3a..c6d89880a51 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -664,26 +664,26 @@ If you do not call :cpp:func:`esp_sleep_set_console_uart_handling_mode`, the fol You can override the default by calling :cpp:func:`esp_sleep_set_console_uart_handling_mode` and choosing one of the following modes (see :cpp:enum:`esp_sleep_uart_handling_mode_t`): - :cpp:enumerator:`ESP_SLEEP_AUTO_FLUSH_SUSPEND_UART` (default): Automatically choose flush or suspend based on sleep type and power domain, as described above. -- :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART` : Always wait until all data in the console UART TX FIFO has been transmitted before entering sleep. Use when you must guarantee that all debug output is visible; sleep entry will take longer and the chip will stay in Active state longer, increasing power consumption. -- :cpp:enumerator:`ESP_SLEEP_ALWAYS_SUSPEND_UART` : Wait for the current UART frame to complete, then suspend the UART. If the UART stays powered during Light-sleep, transmission continues after wake. If the UART power domain is powered down, unsent data will be lost. -- :cpp:enumerator:`ESP_SLEEP_ALWAYS_DISCARD_UART` : Discard all unsent data in the console UART FIFO and enter sleep immediately. Use for the fastest sleep entry and lowest power when debug output can be discarded. -- :cpp:enumerator:`ESP_SLEEP_NO_HANDLING` : Do not perform any handling on the console UART before sleep. Use only when the UART state is known to be safe (e.g. no pending output or the console UART is disabled). +- :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART`: Always wait until all data in the console UART TX FIFO has been transmitted before entering sleep. Use when you must guarantee that all debug output is visible; sleep entry will take longer and the chip will stay in Active state longer, increasing power consumption. +- :cpp:enumerator:`ESP_SLEEP_ALWAYS_SUSPEND_UART`: Wait for the current UART frame to complete, then suspend the UART. If the UART stays powered during Light-sleep, transmission continues after wake. If the UART power domain is powered down, unsent data will be lost. +- :cpp:enumerator:`ESP_SLEEP_ALWAYS_DISCARD_UART`: Discard all unsent data in the console UART FIFO and enter sleep immediately. Use for the fastest sleep entry and lowest power when debug output can be discarded. +- :cpp:enumerator:`ESP_SLEEP_NO_HANDLING`: Do not perform any handling on the console UART before sleep. Use only when the UART state is known to be safe (e.g. no pending output or the console UART is disabled). .. note:: - The sleep flow runs in a critical section. When using a mode that flushes the console UART (e.g. :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART` , or the default behavior for Light-sleep/Deep-sleep when the HP peripheral domain is powered down), set :menuitem:`CONFIG_ESP_INT_WDT_TIMEOUT_MS` to be **greater than** ``SOC_UART_FIFO_LEN`` × (time to send one character at the current baud rate). Otherwise, if too much data is queued in the TX FIFO, the flush may take longer than the interrupt watchdog timeout and trigger a watchdog reset during sleep entry. + The sleep flow runs in a critical section. When using a mode that flushes the console UART (e.g. :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART`, or the default behavior for Light-sleep/Deep-sleep when the HP peripheral domain is powered down), set :menuitem:`CONFIG_ESP_INT_WDT_TIMEOUT_MS` to be **greater than** ``SOC_UART_FIFO_LEN`` × (time to send one character at the current baud rate). Otherwise, if too much data is queued in the TX FIFO, the flush may take longer than the interrupt watchdog timeout and trigger a watchdog reset during sleep entry. -Example: ensure all debug output is sent before every sleep:: +Example: ensure all debug output is sent before every sleep: -.. code-block:: C +.. code-block:: c fflush(stdout); esp_sleep_set_console_uart_handling_mode(ESP_SLEEP_ALWAYS_FLUSH_UART); esp_light_sleep_start(); -Example: minimize sleep entry time and allow discarding console output:: +Example: minimize sleep entry time and allow discarding console output: -.. code-block:: C +.. code-block:: c esp_sleep_set_console_uart_handling_mode(ESP_SLEEP_ALWAYS_DISCARD_UART); esp_deep_sleep_start(); diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index 5db6827708d..2e82185ca48 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -664,16 +664,16 @@ UART 输出处理 可通过调用 :cpp:func:`esp_sleep_set_console_uart_handling_mode` 覆盖默认行为，并选择下列模式之一（参见 :cpp:enum:`esp_sleep_uart_handling_mode_t`）： - :cpp:enumerator:`ESP_SLEEP_AUTO_FLUSH_SUSPEND_UART` （默认）：根据睡眠类型和电源域自动选择冲刷或挂起，如上所述。 -- :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART` ：进入睡眠前始终等待控制台 UART TX FIFO 中的数据全部发送完毕。适用于必须保证所有调试输出可见的场景；进入睡眠时间会更长，芯片处于 Active 状态的时间变长进而增加功耗。 -- :cpp:enumerator:`ESP_SLEEP_ALWAYS_SUSPEND_UART` ：等待当前 UART 帧发完后挂起 UART。若 Light-sleep 期间 UART 保持供电，唤醒后会继续发送；若 UART 电源域掉电，未发送的数据将丢失。 -- :cpp:enumerator:`ESP_SLEEP_ALWAYS_DISCARD_UART` ：丢弃控制台 UART FIFO 中所有未发送数据并立即进入睡眠。适用于追求最快进入睡眠和最低功耗、且可接受丢弃调试输出的场景。 -- :cpp:enumerator:`ESP_SLEEP_NO_HANDLING` ：进入睡眠前不对控制台 UART 做任何处理。仅在确认 UART 状态安全时使用（例如无待发数据或已禁用控制台 UART）。 +- :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART`：进入睡眠前始终等待控制台 UART TX FIFO 中的数据全部发送完毕。适用于必须保证所有调试输出可见的场景；进入睡眠时间会更长，芯片处于 Active 状态的时间变长进而增加功耗。 +- :cpp:enumerator:`ESP_SLEEP_ALWAYS_SUSPEND_UART`：等待当前 UART 帧发完后挂起 UART。若 Light-sleep 期间 UART 保持供电，唤醒后会继续发送；若 UART 电源域掉电，未发送的数据将丢失。 +- :cpp:enumerator:`ESP_SLEEP_ALWAYS_DISCARD_UART`：丢弃控制台 UART FIFO 中所有未发送数据并立即进入睡眠。适用于追求最快进入睡眠和最低功耗、且可接受丢弃调试输出的场景。 +- :cpp:enumerator:`ESP_SLEEP_NO_HANDLING`：进入睡眠前不对控制台 UART 做任何处理。仅在确认 UART 状态安全时使用（例如无待发数据或已禁用控制台 UART）。 .. note:: - 睡眠流程在临界区中执行，当使用会冲刷控制台 UART 的模式（如 :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART` ，或 HP 外设域掉电时的 Light-sleep/Deep-sleep 默认行为）时，请将 :menuitem:`CONFIG_ESP_INT_WDT_TIMEOUT_MS` 配置为**大于** ``SOC_UART_FIFO_LEN`` ×（当前波特率下发送一个字符所需时间）。否则若 TX FIFO 中积压数据过多，冲刷时间可能超过中断看门狗超时，会在进入睡眠过程中触发看门狗复位。 + 睡眠流程在临界区中执行，当使用会冲刷控制台 UART 的模式（如 :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART`，或 HP 外设域掉电时的 Light-sleep/Deep-sleep 默认行为）时，请将 :menuitem:`CONFIG_ESP_INT_WDT_TIMEOUT_MS` 配置为**大于** ``SOC_UART_FIFO_LEN`` ×（当前波特率下发送一个字符所需时间）。否则若 TX FIFO 中积压数据过多，冲刷时间可能超过中断看门狗超时，会在进入睡眠过程中触发看门狗复位。 -示例：在每次睡眠前确保所有调试输出已发出：: +示例：在每次睡眠前确保所有调试输出已发出： .. code-block:: c @@ -681,7 +681,7 @@ UART 输出处理 esp_sleep_set_console_uart_handling_mode(ESP_SLEEP_ALWAYS_FLUSH_UART); esp_light_sleep_start(); -示例：尽量缩短进入睡眠时间并允许丢弃控制台输出：: +示例：尽量缩短进入睡眠时间并允许丢弃控制台输出： .. code-block:: c