ulp: document the need to wait for RTC to be ready for wakeup

diff --git a/components/soc/esp32/include/soc/rtc_cntl_reg.h b/components/soc/esp32/include/soc/rtc_cntl_reg.h
index ffcbb3c0338294b4ffd074e2456238b7eaf120d9..d54a7dde7cf44c45ebd6a0b333086bf76f3c6efe 100644 (file)
--- a/components/soc/esp32/include/soc/rtc_cntl_reg.h
+++ b/components/soc/esp32/include/soc/rtc_cntl_reg.h
@@ -1830,7 +1830,16 @@
 #define RTC_CNTL_SCRATCH7_V  0xFFFFFFFF
 #define RTC_CNTL_SCRATCH7_S  0
 
-#define RTC_CNTL_DIAG0_REG          (DR_REG_RTCCNTL_BASE + 0xc0)
+#define RTC_CNTL_LOW_POWER_ST_REG          (DR_REG_RTCCNTL_BASE + 0xc0)
+/* RTC_CNTL_RDY_FOR_WAKEUP : R/0; bitpos:[19]; default: 0 */
+/*description: 1 if RTC controller is ready to execute WAKE instruction, 0 otherwise */
+#define RTC_CNTL_RDY_FOR_WAKEUP  (BIT(19))
+#define RTC_CNTL_RDY_FOR_WAKEUP_M  (BIT(19))
+#define RTC_CNTL_RDY_FOR_WAKEUP_V  0x1
+#define RTC_CNTL_RDY_FOR_WAKEUP_S  19
+
+/* Compatibility definition */
+#define RTC_CNTL_DIAG0_REG RTC_CNTL_LOW_POWER_ST_REG
 /* RTC_CNTL_LOW_POWER_DIAG0 : RO ;bitpos:[31:0] ;default: 0 ; */
 /*description: */
 #define RTC_CNTL_LOW_POWER_DIAG0  0xFFFFFFFF

diff --git a/docs/api-guides/ulp_instruction_set.rst b/docs/api-guides/ulp_instruction_set.rst
index c4d21947ccf7edc4f8c35c6241a47d9a825df66a..62cbe3bd5ab6c03d2b47dc5f5372a825933776d7 100755 (executable)
--- a/docs/api-guides/ulp_instruction_set.rst
+++ b/docs/api-guides/ulp_instruction_set.rst
@@ -573,11 +573,17 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
 \r
   - If the SoC is not in deep sleep mode, and ULP interrupt bit (RTC_CNTL_ULP_CP_INT_ENA) is set in RTC_CNTL_INT_ENA_REG register, RTC interrupt will be triggered.\r
 \r
+  Note that before using WAKE instruction, ULP program may needs to wait until RTC controller is ready to wake up the main CPU. This is indicated using RTC_CNTL_RDY_FOR_WAKEUP bit of RTC_CNTL_LOW_POWER_ST_REG register. If WAKE instruction is executed while RTC_CNTL_RDY_FOR_WAKEUP is zero, it has no effect (wake up does not occur).\r
+\r
 **Examples**::\r
 \r
-  1:        WAKE                      // Trigger wake up\r
-            REG_WR 0x006, 24, 24, 0   // Stop ULP timer (clear RTC_CNTL_ULP_CP_SLP_TIMER_EN)\r
-            HALT                      // Stop the ULP program\r
+  1: is_rdy_for_wakeup:                   // Read RTC_CNTL_RDY_FOR_WAKEUP bit\r
+            READ_RTC_FIELD(RTC_CNTL_LOW_POWER_ST_REG, RTC_CNTL_RDY_FOR_WAKEUP)\r
+            AND r0, r0, 1\r
+            JUMP is_rdy_for_wakeup, eq    // Retry until the bit is set\r
+            WAKE                          // Trigger wake up\r
+            REG_WR 0x006, 24, 24, 0       // Stop ULP timer (clear RTC_CNTL_ULP_CP_SLP_TIMER_EN)\r
+            HALT                          // Stop the ULP program\r
             // After these instructions, SoC will wake up,\r
             // and ULP will not run again until started by the main program.\r
 \r

diff --git a/examples/system/ulp/main/ulp/pulse_cnt.S b/examples/system/ulp/main/ulp/pulse_cnt.S
index ba7b453442ff9f8942f46875aba4fc6ce86bbc7c..e573e3244f3932d669b22207127856790dcc75aa 100644 (file)
--- a/examples/system/ulp/main/ulp/pulse_cnt.S
+++ b/examples/system/ulp/main/ulp/pulse_cnt.S
@@ -130,6 +130,11 @@ edge_detected:
 
        .global wake_up
 wake_up:
+       /* Check if the system can be woken up */
+       READ_RTC_FIELD(RTC_CNTL_LOW_POWER_ST_REG, RTC_CNTL_RDY_FOR_WAKEUP)
+       and r0, r0, 1
+       jump wake_up, eq
+
        /* Wake up the SoC, end program */
        wake
        halt

diff --git a/examples/system/ulp_adc/main/ulp/adc.S b/examples/system/ulp_adc/main/ulp/adc.S
index 1f0f6d5ac9eca9a2f02075b7d5a9e8643a5592b5..70d0439c819743b95976940c4fbe526d8eee6f92 100644 (file)
--- a/examples/system/ulp_adc/main/ulp/adc.S
+++ b/examples/system/ulp_adc/main/ulp/adc.S
@@ -105,7 +105,7 @@ exit:
        .global wake_up
 wake_up:
        /* Check if the system can be woken up */
-       READ_RTC_REG(RTC_CNTL_DIAG0_REG, 19, 1)
+       READ_RTC_FIELD(RTC_CNTL_LOW_POWER_ST_REG, RTC_CNTL_RDY_FOR_WAKEUP)
        and r0, r0, 1
        jump exit, eq