Add `board_deinit` for use with sleep

This changes lots of files to unify `board.h` across ports. It adds
`board_deinit` when CIRCUITPY_ALARM is set. `main.c` uses it to
deinit the board before deep sleeping (even when pretending.)

Deep sleep is now a two step process for the port. First, the
port should prepare to deep sleep based on the given alarms. It
should set alarms for both deep and pretend sleep. In particular,
the pretend versions should be set immediately so that we don't
miss an alarm as we shutdown. These alarms should also wake from
`port_idle_until_interrupt` which is used when pretending to deep
sleep.

Second, when real deep sleeping, `alarm_enter_deep_sleep` is called.
The port should set any alarms it didn't during prepare based on
data it saved internally during prepare.

ESP32-S2 sleep is a bit reorganized to locate more logic with
TimeAlarm. This will help it scale to more alarm types.

Fixes #3786

2 files changed, 23 insertions, 38 deletions

diff --git a/shared-bindings/alarm/__init__.c b/shared-bindings/alarm/__init__.c
index a1f1a2f8c..5420b8404 100644
--- a/shared-bindings/alarm/__init__.c
+++ b/shared-bindings/alarm/__init__.c
@@ -36,9 +36,6 @@
 #include "supervisor/shared/autoreload.h"
 #include "supervisor/shared/workflow.h"
 
-// Wait this long imediately after startup to see if we are connected to USB.
-#define CIRCUITPY_USB_CONNECTED_SLEEP_DELAY 5
-
 //| """Alarms and sleep
 //|
 //| Provides alarms that trigger based on time intervals or on external events, such as pin
@@ -93,21 +90,13 @@ void validate_objs_are_alarms(size_t n_args, const mp_obj_t *objs) {
 //|     ...
 //|
 STATIC mp_obj_t alarm_light_sleep_until_alarms(size_t n_args, const mp_obj_t *args) {
-    validate_objs_are_alarms(n_args, args);
-
-    // See if we are connected to a host.
-    // Make sure we have been awake long enough for USB to connect (enumeration delay).
-    int64_t connecting_delay_msec = CIRCUITPY_USB_CONNECTED_SLEEP_DELAY * 1024 - supervisor_ticks_ms64();
-    if (connecting_delay_msec > 0) {
-        common_hal_time_delay_ms(connecting_delay_msec * 1000 / 1024);
+    if (n_args == 0) {
+        return mp_const_none;
     }
 
-    if (supervisor_workflow_active()) {
-        common_hal_alarm_wait_until_alarms(n_args, args);
-    } else {
-        common_hal_alarm_light_sleep_until_alarms(n_args, args);
-    }
-    return mp_const_none;
+    validate_objs_are_alarms(n_args, args);
+
+    return common_hal_alarm_light_sleep_until_alarms(n_args, args);
 }
 MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(alarm_light_sleep_until_alarms_obj, 1, MP_OBJ_FUN_ARGS_MAX, alarm_light_sleep_until_alarms);
 
@@ -151,26 +140,13 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(alarm_light_sleep_until_alarms_obj, 1, MP_OB
 STATIC mp_obj_t alarm_exit_and_deep_sleep_until_alarms(size_t n_args, const mp_obj_t *args) {
     validate_objs_are_alarms(n_args, args);
 
-    // Shut down WiFi, etc.
-    common_hal_alarm_prepare_for_deep_sleep();
+    // Validate the alarms and set them.
+    common_hal_alarm_set_deep_sleep_alarms(n_args, args);
 
-    // See if we are connected to a host.
-    // Make sure we have been awake long enough for USB to connect (enumeration delay).
-    int64_t connecting_delay_msec = CIRCUITPY_USB_CONNECTED_SLEEP_DELAY * 1024 - supervisor_ticks_ms64();
-    if (connecting_delay_msec > 0) {
-        common_hal_time_delay_ms(connecting_delay_msec * 1000 / 1024);
-    }
+    // Raise an exception, which will be processed in main.c.
+    mp_raise_arg1(&mp_type_DeepSleepRequest, NULL);
 
-    if (supervisor_workflow_active()) {
-        // Simulate deep sleep by waiting for an alarm and then restarting when done.
-        common_hal_alarm_wait_until_alarms(n_args, args);
-        reload_requested = true;
-        supervisor_set_run_reason(RUN_REASON_STARTUP);
-        mp_raise_reload_exception();
-    } else {
-        common_hal_alarm_exit_and_deep_sleep_until_alarms(n_args, args);
-        // Does not return.
-    }
+    // Doesn't get here.
     return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(alarm_exit_and_deep_sleep_until_alarms_obj, 1, MP_OBJ_FUN_ARGS_MAX, alarm_exit_and_deep_sleep_until_alarms);
diff --git a/shared-bindings/alarm/__init__.h b/shared-bindings/alarm/__init__.h
index 380c65ea8..5a8c613d9 100644
--- a/shared-bindings/alarm/__init__.h
+++ b/shared-bindings/alarm/__init__.h
@@ -31,13 +31,22 @@
 
 #include "common-hal/alarm/__init__.h"
 
-extern mp_obj_t common_hal_alarm_wait_until_alarms(size_t n_alarms, const mp_obj_t *alarms);
 extern mp_obj_t common_hal_alarm_light_sleep_until_alarms(size_t n_alarms, const mp_obj_t *alarms);
-extern void common_hal_alarm_exit_and_deep_sleep_until_alarms(size_t n_alarms, const mp_obj_t *alarms);
-extern void common_hal_alarm_prepare_for_deep_sleep(void);
-extern NORETURN void common_hal_alarm_enter_deep_sleep(void);
+
+// Deep sleep is a two step process. Alarms are set when the VM is valid but
+// everything is reset before entering deep sleep. Furthermore, deep sleep may
+// not actually happen if the user is connected to the device. In this case, the
+// supervisor will idle using `port_wait_for_interrupt`. After each call, it will
+// call alarm_woken_from_sleep to see if we've been woken by an alarm and if so,
+// it will exit idle as if deep sleep was exited.
+extern void common_hal_alarm_set_deep_sleep_alarms(size_t n_alarms, const mp_obj_t *alarms);
+// Deep sleep is entered outside of the VM so we omit the `common_hal_` prefix.
+extern NORETURN void alarm_enter_deep_sleep(void);
 
 // Used by wake-up code.
 extern void common_hal_alarm_set_wake_alarm(mp_obj_t alarm);
 
+// True if an alarm is alerting. This is most useful for pretend deep sleep.
+extern bool alarm_woken_from_sleep(void);
+
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_ALARM___INIT___H