feat(doc): add docs for sleep console UART handling strategies

2026-04-27 19:13:21 +00:00 · 2026-02-04 21:41:17 +08:00
parent de104628a0
commit cb0694e5dc
2 changed files with 76 additions and 4 deletions
@@ -462,9 +462,45 @@ It is also possible to enter sleep modes with no wakeup sources configured. In t
 UART Output Handling
 ^^^^^^^^^^^^^^^^^^^^

-Before entering sleep mode, :cpp:func:`esp_deep_sleep_start` will flush the contents of UART FIFOs.
+Before entering sleep, the sleep flow prepares the **console UART** (the UART used for debug output, selected by :ref:`CONFIG_ESP_CONSOLE_UART_NUM`) so that APB clock changes or power-down do not cause garbled output or undefined behavior. The strategy applied is configurable and affects data integrity, sleep entry time, and power consumption.

-When entering Light-sleep mode using :cpp:func:`esp_light_sleep_start`, UART FIFOs will not be flushed. Instead, UART output will be suspended, and remaining characters in the FIFO will be sent out after wakeup from Light-sleep.
+**Default behavior (auto mode)**
+
+If you do not call :cpp:func:`esp_sleep_set_console_uart_handling_mode`, the following default strategy is used:
+
+- **Deep-sleep**: Always wait until all data in the console UART FIFO has been transmitted before entering sleep, so that all debug output is sent and no data is lost.
+- **Light-sleep**: Behavior depends on whether the UART power domain is powered down:
+    - If the UART remains powered (e.g. HP peripheral domain not powered down): UART output is **suspended** after the current frame completes; after wakeup it is resumed and any remaining data in the UART TX FIFO before sleep continues to be sent.
+    - If the UART power domain is powered down: The sleep flow waits until all data in the console UART TX FIFO has been transmitted before entering sleep; data in other UARTs is discarded to enter sleep faster.
+
+**Configuring console UART handling**
+
+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).
+
+.. 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 :ref:`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::
+
+.. 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::
+
+.. code-block:: C
+
+    esp_sleep_set_console_uart_handling_mode(ESP_SLEEP_ALWAYS_DISCARD_UART);
+    esp_deep_sleep_start();

 .. _wakeup_cause:

@@ -462,9 +462,45 @@ flash 断电
 UART 输出处理
 ^^^^^^^^^^^^^^^^^^^^

-在进入睡眠模式之前，调用函数 :cpp:func:`esp_deep_sleep_start` 会冲刷掉 UART FIFO 缓存。
+进入睡眠前，睡眠流程会对**控制台 UART**（用于调试输出的 UART，由 :ref:`CONFIG_ESP_CONSOLE_UART_NUM` 选定）进行准备，以避免 APB 时钟变化或掉电导致输出乱码或未定义行为。所采用的策略可配置，会影响数据完整性、进入睡眠的时间以及功耗。

-当使用函数 :cpp:func:`esp_light_sleep_start` 进入 Light-sleep 模式时，UART FIFO 将不会被冲刷。与之相反，UART 输出将被暂停，FIFO 中的剩余字符将在 Light-sleep 唤醒后被发送。
+**默认行为（自动模式）**
+
+若不调用 :cpp:func:`esp_sleep_set_console_uart_handling_mode`，则采用以下默认策略：
+
+- **Deep-sleep**：始终等到控制台 UART FIFO 中的数据全部发完后再进入睡眠，确保所有调试输出被发送且不丢数据。
+- **Light-sleep**：行为取决于 UART 所在电源域是否掉电：
+    - 若 UART 保持供电（例如 HP 外设域未掉电）：在当前帧发完后挂起 UART 输出；唤醒后恢复发送，睡眠前 UART TX FIFO 中剩余数据会继续发出。
+    - 若 UART 电源域掉电：睡眠流程会等到控制台 UART TX FIFO 中的数据全部发完后再进入睡眠；其他 UART 中的数据会被丢弃以更快进入睡眠。
+
+**配置控制台 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）。
+
+.. note::
+
+   睡眠流程在临界区中执行，当使用会冲刷控制台 UART 的模式（如 :cpp:enumerator:`ESP_SLEEP_ALWAYS_FLUSH_UART` ，或 HP 外设域掉电时的 Light-sleep/Deep-sleep 默认行为）时，请将 :ref:`CONFIG_ESP_INT_WDT_TIMEOUT_MS` 配置为**大于** ``SOC_UART_FIFO_LEN`` ×（当前波特率下发送一个字符所需时间）。否则若 TX FIFO 中积压数据过多，冲刷时间可能超过中断看门狗超时，会在进入睡眠过程中触发看门狗复位。
+
+示例：在每次睡眠前确保所有调试输出已发出：:
+
+.. code-block:: c
+
+    fflush(stdout);
+    esp_sleep_set_console_uart_handling_mode(ESP_SLEEP_ALWAYS_FLUSH_UART);
+    esp_light_sleep_start();
+
+示例：尽量缩短进入睡眠时间并允许丢弃控制台输出：:
+
+.. code-block:: c
+
+    esp_sleep_set_console_uart_handling_mode(ESP_SLEEP_ALWAYS_DISCARD_UART);
+    esp_deep_sleep_start();

 .. _wakeup_cause: