Merge branch 'bugfix/deep_sleep_flush_uart_v3.1' into 'release/v3.1'

sleep: fix flushing UARTs when entering deep sleep (backport v3.1)

See merge request idf/esp-idf!2816

components/esp32/sleep_modes.c

@@ -141,6 +141,13 @@ void esp_deep_sleep(uint64_t time_in_us)
     esp_deep_sleep_start();
 }
 
+static void IRAM_ATTR flush_uarts()
+{
+    for (int i = 0; i < 3; ++i) {
+        uart_tx_wait_idle(i);
+    }
+}
+
 static void IRAM_ATTR suspend_uarts()
 {
     for (int i = 0; i < 3; ++i) {
@@ -160,8 +167,14 @@ static void IRAM_ATTR resume_uarts()
 
 static uint32_t IRAM_ATTR esp_sleep_start(uint32_t pd_flags)
 {
-    // Stop UART output so that output is not lost due to APB frequency change
-    suspend_uarts();
+    // Stop UART output so that output is not lost due to APB frequency change.
+    // For light sleep, suspend UART output — it will resume after wakeup.
+    // For deep sleep, wait for the contents of UART FIFO to be sent.
+    if (pd_flags & RTC_SLEEP_PD_DIG) {
+        flush_uarts();
+    } else {
+        suspend_uarts();
+    }
 
     // Save current frequency and switch to XTAL
     rtc_cpu_freq_t cpu_freq = rtc_clk_cpu_freq_get();

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

@@ -136,6 +136,13 @@ Add the following code before :cpp:func:`esp_deep_sleep_start` to remove this ex
 rtc_gpio_isolate(GPIO_NUM_12);
 ```
 
+UART output handling
+--------------------
+
+Before entering sleep mode, :cpp:func:`esp_deep_sleep_start` will flush the contents of UART FIFOs.
+
+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.
+
 Checking sleep wakeup cause
 ---------------------------