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/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"