this is "generic" in that it doesn't require the user to set up anything
specific to go to dormant sleep, unlike the C sdk which requires clock
sources to be configured explicitly and doesn't much care about PLLs. we
will instead take a snapshot of the current clock configuration, switch
to a known clock source (very slow rosc, in this case), go to sleep, and
on wakeup undo everything we've done (ensuring stability of PLLs and
such).
tested locally, but adding tests to HIL seems infeasible. we'd need at
least another pico or extensive modifications to teleprobe since
dormant-sleep breaks SWD (except to rescue-dp), neither of which is
feasible at this point. if we *did* want to add tests we should check
for both rtc wakeups (with an external rtc clock source) and gpio wakeups.
we'll need access to the pin io bank registers for an upcoming fix, and
having both `io` and `io_bank` or similar can get confusing quickly.
rename `io` to `gpio` to avoid this, and also match the type while there.
gpin clock sources aren't going to be very useful during cold boot and
thus require runtime clock reconfig. once we get there we can use this
for reference. or maybe we can't, only time will tell.
we'll take static ownership of an entire pin (not just a limited
reference), otherwise we cannot at all guarantee that the pin will not
be reused for something else while still in use. in theory we could
limit the liftime of this use, but that would require attaching
lifetimes to ClockConfig (and subsequently the main config), passing
those through init(), and returning an object that undoes the gpin
configuration on drop. that's a lot unnecessary support code while we
don't have runtime clock reconfig.
don't recalculate clock frequencies every time they are asked for. while
this is not very often in practice it does consume a bunch of flash
space that cannot be optimized away, and was pulled in unconditionally
previously. while we technically only need the configured rosc, xosc and
gpin frequencies it is easier to store all frequencies (and much cheaper
at runtime too).
if rosc really does run at 140MHz in high at div=1 then these values
were not correct and would've exceeded the chip spec. the HIL test
device seems to run fast (150MHz) so they're still not quite correct,
but rosc has high variance anyway so it's probably fine.
