Internal API revisions to sleep

[hierophect]

This PR suggests some changes to the internal structure of the Alarm module to fix some bugs with light sleep and hopefully make the sleep program flow easier to follow. Starting as draft so it isn't accidentally merged.

• Changed shared_alarm_save_wake_alarm to take an alarm parameter. This means it can be called directly in Light Sleep to set the current alarm without an intermediary static variable, and it doesn't impact deep sleep in main.c since common_hal_alarm_get_wake_alarm/common_hal_alarm_create_wake_alarm (see below) can be called as the parameter. Setting the global variable to an alarm out of the current VM memory is now contained entirely within the light sleep function.
• As per the above, common_hal_alarm_get_wake_alarm is renamed common_hal_alarm_create_wake_alarm. Now that light sleep "real" alarm management is entirely self contained, this function can be upfront about only returning generated "copy" alarms for deep sleep.
• All x_woke_us_up functions are renamed x_woke_this_cycle, making it clear they apply only to wakeup detection within the current RAM cycle, and won't work for deep sleep.
• _get_wake_alarm has been completely merged into common_hal_alarm_create_wake_alarm, and now has no parameters, since all current VM alarm objects are handled by light sleep. The internal functions used are of x_create_wakeup_alarm type, see below.
• All x_get_wakeup_alarm functions have been separated into two: x_create_wakeup_alarm and x_find_triggered_alarm. The creation of alarms is used for deep sleep (real and fake), whereas finding triggered alarms is for light sleep.
• common_hal_alarm_light_sleep_until_alarms now detects the wakeup cause itself, searches through the alarm list itself, and saves the real alarm object directly to the global array using the shared_alarm_save_wake_alarm, rather than saving an incorrect fake alarm to the global array (old ESP case) or using a static variable to hack around the existing system (old STM case). The alarm in the global array now matches the alarm returned by the function.
• _idle_until_alarm has been factored into light sleep as it was not used anywhere else.
• Various comments added describing program flow.

Considered but unchanged:

• _get_wakeup_cause still handles both light and deep sleep, as deep sleep calls to common_hal_alarm_create_wake_alarm may need either fake or true deep sleep wakeup detection.
• _setup_sleep_alarms still handles all kinds of sleep, since platforms like the STM32 have overlap in light/deep sleep setup, especially for the RTC.

[hierophect]

Old structure:

New structure:

[dhalbert]

These changes clairfy the flow nicely - thanks! I did not test but you did. The build failures are due to GitHub cache failures. You could merge from upstream and re-run, because the cache key has already been changed.

[hierophect]

@dhalbert Thanks for the review! But let's get STM32 sleep merged in first. That way I can merge the API changes to all existing Alarm modules at once, plus the STM32 port has a minor API adjustment (makes PinAlarms use const for pin objects, like other pin-related modules) that is better to put in before this.

[hierophect]

NRF isn't returning the correct global object in testing, will resolve tomorrow morning.

[hierophect]

@dhalbert nevermind, object problems were just a testing mistake. I've tested this and it works across all 4 possible sleep modes on all platforms, NRF/STM/ESP. Should be good to go.

[dhalbert]

Thanks for taking this on!