Merge branch 'feat/twai_sleep_retention' into 'master'

twai: sleep retention support

Closes IDF-8471, IDF-9772, and IDF-9743

See merge request espressif/esp-idf!34107

docs/en/api-reference/peripherals/twai.rst

@@ -599,6 +599,14 @@ Application Examples
 
 **Self-Test Example:** :example:`peripherals/twai/twai_self_test` demonstrates how a node can transmit TWAI messages to itself using the TWAI driver's "No Acknowledgement" mode and Self Reception Requests, testing the proper connection of a target to a working external transceiver.
 
+.. only:: SOC_TWAI_SUPPORT_SLEEP_RETENTION
+
+    Sleep Retention
+    ^^^^^^^^^^^^^^^
+
+    {IDF_TARGET_NAME} supports to retain the TWAI register context before entering **light sleep** and restore them after waking up. This means you don't have to re-init the TWAI driver after the light sleep.
+
+    This feature can be enabled by setting the flag :cpp:member:`twai_general_config_t::sleep_allow_pd`. It will allow the system to power down the TWAI in light sleep, meanwhile saving the register context. It can help save more power consumption with some extra cost of the memory.
 
 .. ---------------------------- API Reference ----------------------------------
 

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

@@ -157,6 +157,7 @@ The following peripheral drivers are not aware of DFS yet. Applications need to
             :SOC_I2S_SUPPORT_SLEEP_RETENTION: - I2S
             :SOC_UART_SUPPORT_SLEEP_RETENTION: - All UARTs
             :SOC_TEMPERATURE_SENSOR_SUPPORT_SLEEP_RETENTION: - Temperature Sensor
+            :SOC_TWAI_SUPPORT_SLEEP_RETENTION: - All TWAIs
 
         The following peripherals are not yet supported:
 
@@ -168,7 +169,6 @@ The following peripheral drivers are not aware of DFS yet. Applications need to
             - SPI2
             - PCNT
             - USB-Serial-JTAG
-            - TWAI
             - LEDC
             - MCPWM
             - SARADC