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

5 files changed, 74 insertions, 25 deletions

diff --git a/supervisor/board.h b/supervisor/board.h
new file mode 100644
index 000000000..939ee1c19
--- /dev/null
+++ b/supervisor/board.h
@@ -0,0 +1,53 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_SUPERVISOR_BOARD_H
+#define MICROPY_INCLUDED_SUPERVISOR_BOARD_H
+
+#include <stdbool.h>
+
+#include "supervisor/shared/safe_mode.h"
+
+// Returns true if the user initiates safe mode in a board specific way.
+// Also add BOARD_USER_SAFE_MODE in mpconfigboard.h to explain the board specific
+// way.
+bool board_requests_safe_mode(void);
+
+// Initializes board related state once on start up.
+void board_init(void);
+
+// Reset the state of off MCU components such as neopixels.
+void reset_board(void);
+
+#if CIRCUITPY_ALARM
+// Deinit the board. This should put the board in deep sleep durable, low power
+// state. It should not prevent the user access method from working (such as
+// disabling USB, BLE or flash) because CircuitPython may continue to run.
+void board_deinit(void);
+#endif
+
+
+#endif  // MICROPY_INCLUDED_SUPERVISOR_BOARD_H
diff --git a/supervisor/port.h b/supervisor/port.h
index 5bc06bc4e..862400986 100644
--- a/supervisor/port.h
+++ b/supervisor/port.h
@@ -49,9 +49,6 @@ void reset_cpu(void) NORETURN;
 // Reset the microcontroller state.
 void reset_port(void);
 
-// Reset the rest of the board.
-void reset_board(void);
-
 // Reset to the bootloader
 void reset_to_bootloader(void) NORETURN;
 
@@ -89,8 +86,9 @@ void port_disable_tick(void);
 // Only the common sleep routine should use it.
 void port_interrupt_after_ticks(uint32_t ticks);
 
-// Sleep the CPU until an interrupt is received.
-void port_sleep_until_interrupt(void);
+// Sleep the CPU until an interrupt is received. We call this idle because it
+// may not be a system level sleep.
+void port_idle_until_interrupt(void);
 
 // Execute port specific actions during background tasks.
 void port_background_task(void);
@@ -100,4 +98,5 @@ void port_background_task(void);
 // work" should be done in port_background_task() instead.
 void port_start_background_task(void);
 void port_finish_background_task(void);
+
 #endif  // MICROPY_INCLUDED_SUPERVISOR_PORT_H
diff --git a/supervisor/shared/board.c b/supervisor/shared/board.c
index e3eb8fd0d..111aa0e3c 100644
--- a/supervisor/shared/board.c
+++ b/supervisor/shared/board.c
@@ -26,23 +26,22 @@
 
 #include "supervisor/shared/board.h"
 
-#include "shared-bindings/digitalio/DigitalInOut.h"
-#include "shared-bindings/neopixel_write/__init__.h"
+#if CIRCUITPY_DIGITALIO && CIRCUITPY_NEOPIXEL_WRITE
 
-#ifdef USER_NEOPIXELS_PIN
+#include <string.h>
 
-// The maximum number of user neopixels right now is 10, on Circuit Playgrounds.
-// PyBadge and PyGamer have max 5
-#define USER_NEOPIXELS_MAX_COUNT 10
+#include "shared-bindings/digitalio/DigitalInOut.h"
+#include "shared-bindings/neopixel_write/__init__.h"
 
-void board_reset_user_neopixels(void) {
+void board_reset_user_neopixels(mcu_pin_obj_t* pin, size_t count) {
     // Turn off on-board NeoPixel string
-    uint8_t empty[USER_NEOPIXELS_MAX_COUNT * 3] = { 0 };
+    uint8_t empty[count * 3];
+    memset(empty, 0, count);
     digitalio_digitalinout_obj_t neopixel_pin;
-    common_hal_digitalio_digitalinout_construct(&neopixel_pin, USER_NEOPIXELS_PIN);
+    common_hal_digitalio_digitalinout_construct(&neopixel_pin, pin);
     common_hal_digitalio_digitalinout_switch_to_output(&neopixel_pin, false,
         DRIVE_MODE_PUSH_PULL);
-    common_hal_neopixel_write(&neopixel_pin, empty, USER_NEOPIXELS_MAX_COUNT * 3);
+    common_hal_neopixel_write(&neopixel_pin, empty, count * 3);
     common_hal_digitalio_digitalinout_deinit(&neopixel_pin);
 }
 
diff --git a/supervisor/shared/board.h b/supervisor/shared/board.h
index 0e4d73455..cdeefbf22 100644
--- a/supervisor/shared/board.h
+++ b/supervisor/shared/board.h
@@ -24,15 +24,13 @@
  * THE SOFTWARE.
  */
 
-#ifndef MICROPY_INCLUDED_SUPERVISOR_BOARD_H
-#define MICROPY_INCLUDED_SUPERVISOR_BOARD_H
+#ifndef MICROPY_INCLUDED_SUPERVISOR_SHARED_BOARD_H
+#define MICROPY_INCLUDED_SUPERVISOR_SHARED_BOARD_H
 
-#include "py/mpconfig.h"
+#include <stddef.h>
 
-#ifdef USER_NEOPIXELS_PIN
+#include "shared-bindings/microcontroller/Pin.h"
 
-void board_reset_user_neopixels(void);
+void board_reset_user_neopixels(mcu_pin_obj_t* pin, size_t count);
 
-#endif
-
-#endif  // MICROPY_INCLUDED_SUPERVISOR_BOARD_H
+#endif  // MICROPY_INCLUDED_SUPERVISOR_SHARED_BOARD_H
diff --git a/supervisor/shared/tick.c b/supervisor/shared/tick.c
index a2855a570..d37a585eb 100644
--- a/supervisor/shared/tick.c
+++ b/supervisor/shared/tick.c
@@ -156,8 +156,8 @@ void mp_hal_delay_ms(mp_uint_t delay) {
             break;
         }
         port_interrupt_after_ticks(remaining);
-        // Sleep until an interrupt happens.
-        port_sleep_until_interrupt();
+        // Idle until an interrupt happens.
+        port_idle_until_interrupt();
         remaining = end_tick - port_get_raw_ticks(NULL);
     }
 }