Merge branch 'feature/deepsleep_stub_linker' into 'master'

Deep sleep: Any source named rtc_wake_stub* is linked as RTC wake stub code

Also move esp_deepsleep.h documentation out to docs/deep-sleep-stub.rst

See merge request !142

components/esp32/cpu_start.c

@@ -19,6 +19,7 @@
 
 #include "rom/ets_sys.h"
 #include "rom/uart.h"
+#include "rom/rtc.h"
 
 #include "soc/cpu.h"
 #include "soc/dport_reg.h"
@@ -65,6 +66,8 @@ extern void app_main(void);
 
 extern int _bss_start;
 extern int _bss_end;
+extern int _rtc_bss_start;
+extern int _rtc_bss_end;
 extern int _init_start;
 extern void (*__init_array_start)(void);
 extern void (*__init_array_end)(void);
@@ -95,6 +98,11 @@ void IRAM_ATTR call_start_cpu0()
 
     memset(&_bss_start, 0, (&_bss_end - &_bss_start) * sizeof(_bss_start));
 
+    /* Unless waking from deep sleep (implying RTC memory is intact), clear RTC bss */
+    if (rtc_get_reset_reason(0) != DEEPSLEEP_RESET) {
+        memset(&_rtc_bss_start, 0, (&_rtc_bss_end - &_rtc_bss_start) * sizeof(_rtc_bss_start));
+    }
+
     // Initialize heap allocator
     heap_alloc_caps_init();
 

components/esp32/deepsleep.c

@@ -40,8 +40,7 @@ void esp_set_deep_sleep_wake_stub(esp_deep_sleep_wake_stub_fn_t new_stub)
 }
 
 void RTC_IRAM_ATTR esp_default_wake_deep_sleep(void) {
-    //
-    //mmu_init(0);
+    /* Clear MMU for CPU 0 */
     REG_SET_BIT(DPORT_PRO_CACHE_CTRL1_REG, DPORT_PRO_CACHE_MMU_IA_CLR);
     REG_CLR_BIT(DPORT_PRO_CACHE_CTRL1_REG, DPORT_PRO_CACHE_MMU_IA_CLR);
 }

components/esp32/include/esp_attr.h

@@ -20,22 +20,21 @@
 //and all variables in shared RAM. These macros can be used to redirect
 //particular functions/variables to other memory regions.
 
-// Forces code into IRAM instead of flash
+// Forces code into IRAM instead of flash.
 #define IRAM_ATTR __attribute__((section(".iram1")))
 
 // Forces data into DRAM instead of flash
 #define DRAM_ATTR __attribute__((section(".dram1")))
 
-// Forces code into RTC fast memory
+// Forces code into RTC fast memory. See "docs/deep-sleep-stub.rst"
 #define RTC_IRAM_ATTR __attribute__((section(".rtc.text")))
 
-// Forces data into RTC slow memory
+// Forces data into RTC slow memory. See "docs/deep-sleep-stub.rst"
 // Any variable marked with this attribute will keep its value
 // during a deep sleep / wake cycle.
 #define RTC_DATA_ATTR __attribute__((section(".rtc.data")))
 
-// Forces read-only data into RTC slow memory
-// Makes constant data available to RTC wake stubs (see esp_deepsleep.h)
+// Forces read-only data into RTC slow memory. See "docs/deep-sleep-stub.rst"
 #define RTC_RODATA_ATTR __attribute__((section(".rtc.rodata")))
 
 #endif /* __ESP_ATTR_H__ */

components/esp32/include/esp_deepsleep.h

@@ -54,37 +54,7 @@ void system_deep_sleep(uint64_t time_in_us);
  * to run code immediately when the chip wakes from
  * sleep.
  *
- * For example:
- * @code
- * void RTC_IRAM_ATTR esp_wake_deep_sleep(void) {
- *    esp_default_wake_deep_sleep();
- *    // Add additional functionality here
- * }
- *
- * (Implementing this function is not required for normal operation,
- * in the usual case your app will start normally when waking from
- * deep sleep.)
- *
- * esp_wake_deep_sleep() functionality is limited:
- *
- * - Runs immediately on wake, so most of the SoC is freshly reset -
- *   flash is unmapped and hardware is otherwise uninitialised.
- *
- * - Can only call functions implemented in ROM, or marked RTC_IRAM_ATTR.
- *
- * - Static variables marked RTC_DATA_ATTR will have initial values on
- *   cold boot, and maintain these values between sleep/wake cycles.
- *
- * - Read-only data should be marked RTC_RODATA_ATTR. Strings must be
- *   declared as variables also using RTC_RODATA_ATTR, like this:
- *   RTC_RODATA_ATTR const char message[] = "Hello from very early boot!\n";
- *
- * - Any other static memory will not be initialised (either to zero,
- *   or to any predefined value).
- *
- *
- * - If you implement your own stub, the first call the stub makes
-     should be to esp_default_wake_deep_sleep().
+ * See docs/deep-sleep-stub.rst for details.
  */
 void esp_wake_deep_sleep(void);
 
@@ -115,9 +85,7 @@ esp_deep_sleep_wake_stub_fn_t esp_get_deep_sleep_wake_stub(void);
 
 /* The default esp-idf-provided esp_wake_deep_sleep() stub.
 
-   If you replace esp_wake_deep_sleep() in your program, or use
-   esp_set_deep_sleep_wake_stub(), then it is recommended you call
-   esp_default_wake_deep_sleep() as the first function in your stub.
+   See docs/deep-sleep-stub.rst for details.
 */
 void esp_default_wake_deep_sleep(void);
 

components/esp32/include/esp_system.h

@@ -16,6 +16,7 @@
 #define __ESP_SYSTEM_H__
 
 #include <stdint.h>
+#include <stdbool.h>
 
 #include "esp_err.h"
 #include "esp_deepsleep.h"

components/esp32/ld/esp32.common.ld

@@ -3,8 +3,38 @@ ENTRY(call_start_cpu0);
 
 SECTIONS
 {
+  /* RTC fast memory holds RTC wake stub code,
+     including from any source file named rtc_wake_stub*.c
+  */
+  .rtc.text :
+  {
+    . = ALIGN(4);
+    *(.rtc.literal .rtc.text)
+    *rtc_wake_stub*.o(.literal .text .literal.* .text.*)
+  } >rtc_iram_seg
+
+  /* RTC slow memory holds RTC wake stub
+     data/rodata, including from any source file
+     named rtc_wake_stub*.c
+  */
+  .rtc.data :
+  {
+    *(.rtc.data)
+    *(.rtc.rodata)
+    *rtc_wake_stub*.o(.data .rodata .data.* .rodata.* .bss .bss.*)
+  } > rtc_slow_seg
+
+  /* RTC bss, from any source file named rtc_wake_stub*.c */
+  .rtc.bss (NOLOAD) :
+  {
+    _rtc_bss_start = ABSOLUTE(.);
+    *rtc_wake_stub*.o(.bss .bss.*)
+    *rtc_wake_stub*.o(COMMON)
+    _rtc_bss_end = ABSOLUTE(.);
+  } > rtc_slow_seg
+
   /* Send .iram0 code to iram */
-  .iram0.vectors : 
+  .iram0.vectors :
   {
     /* Vectors go to IRAM */
     _init_start = ABSOLUTE(.);
@@ -155,16 +185,4 @@ SECTIONS
     _text_end = ABSOLUTE(.);
     _etext = .;
   } >iram0_2_seg
-
-  .rtc.text :
-  {
-    . = ALIGN(4);
-    *(.rtc.literal .rtc.text)
-  } >rtc_iram_seg
-
-  .rtc.data :
-  {
-    *(.rtc.data)
-    *(.rtc.rodata)
-  } > rtc_slow_seg
 }