//! The hardware wakeup-enable mask, and the hooks that run around a sleep.

//!

//! The driver that owns the hardware enables a wakeup source. The caller of a sleep function does

//! not. The hardware wakeup-enable mask is the record of the request. It is a register in the

//! always-on domain, and it keeps its value while the chip is awake, through a light sleep, and

//! through a deep-sleep wake. Sleep entry reads the mask back, and calculates everything else from

//! it.

//!

//! A driver can also register hooks in the call that sets its mask bit. Use them to do work at

//! sleep entry, or to restore state after a light sleep.

use enumset::EnumSet;

use esp_sync::NonReentrantMutex;

use crate::{

    rtc_cntl::{WakeupSource, sleep::RtcSleepConfig},

    soc::clocks::ClockSource,

    time::Duration,

};

/// Which sleep the chip is entering.

pub(crate) enum SleepKind {

    /// The digital domain keeps its state, and the sleep returns to the caller.

    Light,

    /// The chip resets when it wakes.

    Deep,

}

/// A power domain that a wakeup source needs powered while the chip sleeps.

///

/// The names are the same for all chips. A request for a domain that the target chip does not

/// have, or that it cannot power down, does nothing.

///

/// A clock is not a domain. Ask for one with [`WrappedSleepConfig::keep_clock_running`].

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

// The names are the same for all chips, and each chip uses a different subset.

#[allow(dead_code, reason = "the names are the same for all chips")]

pub(crate) enum SleepResource {

    /// The low-power peripherals, including the RTC IO pads.

    LpPeripherals,

    /// The low-power memory, which holds the program and the data of a low-power core.

    LpMemory,

    /// The high-performance peripherals, including the digital GPIO pads.

    HpPeripherals,

}

/// The sleep configuration, as the entry hook of a wakeup source can see it.

///

/// A hook can only relax the sleep. It can keep a power domain powered, keep a clock running,

/// refuse a light sleep, or shorten the sleep. The caller of the sleep function selects how much

/// of the chip to power down, and it arms the wake timer. A wakeup source only adds the resources

/// that it needs, refuses the sleep, or sets a shorter limit. It cannot request a power-down, stop

/// a clock, cancel a refusal, or lengthen a limit.

///

/// Each request is idempotent. The order of the hooks cannot change the result. The source with

/// the strongest request wins. One refusal is enough. The shortest limit wins.

///

/// Keep this property. A method that requests a power-down, stops a clock, cancels a refusal, or

/// lengthens a limit removes it.

#[instability::unstable]

pub struct WrappedSleepConfig<'a> {

    config: &'a mut RtcSleepConfig,

    clocks: EnumSet<ClockSource>,

    refused: bool,

    limit: Option<Duration>,

}

impl<'a> WrappedSleepConfig<'a> {

    pub(crate) fn new(config: &'a mut RtcSleepConfig) -> Self {

            config,

            clocks: EnumSet::empty(),

            refused: false,

            limit: None,

        }

    }

    /// Returns whether the chip is entering deep sleep, which resets it when it wakes.

    #[instability::unstable]

    /// Keeps `resource` powered during the sleep.

    pub(crate) fn keep_alive(&mut self, resource: SleepResource) {

        // One function for all chips. It keeps the code of one resource together for all chips, so

        // that a reader can compare the chips, and a new resource needs one change only.

        let _config = &mut self.config;

        match resource {

            SleepResource::LpPeripherals => {

                cfg_select! {

                    // esp32h2 powers its low-power peripherals from the top domain, so it has no

                    // separate flag to clear.

                    esp32h2 => {}

                    soc_has_pmu => _config.pd_flags.set_pd_lp_periph(false),

                    _ => _config.set_rtc_peri_pd_en(false),

                }

            }

            SleepResource::LpMemory => {

                cfg_select! {

                    // The PMU chips keep the contents of the low-power memory through a sleep in

                    // retention mode, so there is no power-down to prevent.

                    any(esp32, esp32s2, esp32s3) => _config.set_rtc_slowmem_pd_en(false),

                    _ => {}

                }

            }

            SleepResource::HpPeripherals => {

                cfg_select! {

                    // esp32, esp32s2 and esp32h2 cannot power down the high-performance peripherals

                    // separately, so there is nothing to prevent.

                    any(esp32, esp32s2, esp32h2) => {}

                    soc_has_pmu => _config.pd_flags.set_pd_hp_periph(false),

                    _ => _config.set_dig_peri_pd_en(false),

                }

            }

        }

    }

    /// Keeps `source` running during the sleep.

    ///

    /// Ask a clock tree node which source it runs on, and name the answer. A source that the chip

    /// keeps running anyway, or that it cannot power down, needs nothing.

    #[instability::unstable]

    pub fn keep_clock_running(&mut self, source: ClockSource) {

        self.clocks.insert(source);

    }

    /// Refuses a light sleep.

    ///

    /// Call this when software state makes the sleep unsafe and the hardware cannot see that

    /// state. One call is enough. A later hook cannot cancel it.

    ///

    /// A deep sleep ignores the call. The wake resets the chip, so there is no caller to report

    /// the refusal to. Read [`Self::is_deep_sleep`] when other work in the hook depends on the

    /// kind of sleep.

    ///

    /// The hardware also rejects a sleep when an enabled source is already asserted at sleep

    /// entry. This call is the software refusal.

    #[instability::unstable]

    pub fn reject_sleep(&mut self) {

    }

    /// Limits this sleep to `duration`.

    ///

    /// The duration starts when the driver programs the wake timer, after every hook has run. The

    /// shortest request wins. A later hook cannot make it longer.

    ///

    /// The driver clamps the wake timer to the limit. When the timer wakeup source is not enabled,

    /// the limit enables it for this sleep. Nothing else wakes the chip at the limit. After a

    /// light sleep the driver restores the timer. A deadline the caller armed stays armed. A timer

    /// that only the limit enabled is disabled again.

    ///

    /// The limit applies to deep sleep as well. The wake resets the chip. Read

    /// [`Self::is_deep_sleep`] when the hook should bound only one kind of sleep.

    ///

    /// A duration that the sleep transition cannot catch does not start the sleep. A light sleep

    /// then returns as if it had ended. A deep sleep without rejection panics, because it cannot

    /// return and the chip does not wake. This is not a refusal. Use [`Self::reject_sleep`] to

    /// refuse a light sleep. A duration of zero is too short to sleep.

    #[instability::unstable]

    pub fn limit_sleep(&mut self, duration: Duration) {

        let already_shorter = match self.limit {

            Some(current) => current.as_micros() <= duration.as_micros(),

            None => false,

        };

        if !already_shorter {

            self.limit = Some(duration);

        }

    }

    /// Prevents the power-down of every clock source a hook asked for.

    ///

    /// The set is what makes the requests of the hooks independent of their order.

    fn apply_clock_requests(&mut self) {

        // One function for all chips, like `keep_alive`.

        let _config = &mut self.config;

            match source {

                ClockSource::XtalClk => {

                    cfg_select! {

                        soc_has_pmu => _config.pd_flags.set_pd_xtal(false),

                        // This flag has the opposite sense. It forces the crystal on.

                        _ => _config.set_xtal_fpu(true),

                    }

                }

                ClockSource::RcFastClk => {

                    cfg_select! {

                        soc_has_pmu => _config.pd_flags.set_pd_rc_fast(false),

                        _ => _config.set_int_8m_pd_en(false),

                    }

                }

                #[cfg(use_xtal32k)]

                ClockSource::Xtal32kClk => {

                    cfg_select! {

                        soc_has_pmu => _config.pd_flags.set_pd_xtal32k(false),

                        _ => {}

                    }

                }

                #[cfg(soc_has_clock_node_rc32k_clk)]

                ClockSource::Rc32kClk => {

                    cfg_select! {

                        // esp32h2 has no separate flag for the 32 kHz RC oscillator.

                        esp32h2 => {}

                        _ => _config.pd_flags.set_pd_rc32k(false),

                    }

                }

                // The slow RC oscillator runs in the always-on domain, and the external 32 kHz

                // oscillator arrives on a pad, so neither has a power-down to prevent.

                #[cfg(soc_has_clock_node_osc_slow_clk)]

                ClockSource::OscSlowClk => {}

                ClockSource::RcSlowClk => {}

            }

        }

    }

}

/// Runs at sleep entry, before the sleep configuration reaches hardware.

///

/// The configuration already holds the kind of the sleep, so a hook that needs it asks

/// [`WrappedSleepConfig::is_deep_sleep`]. A hook keeps a clock running with

/// [`WrappedSleepConfig::keep_clock_running`]. A hook refuses a light sleep with

/// [`WrappedSleepConfig::reject_sleep`].

///

/// The hook can run with interrupts disabled, for example from automatic light sleep. Do not

/// allocate, take a blocking lock, or log in it.

#[instability::unstable]

pub type SleepEntryHook = fn(&mut WrappedSleepConfig<'_>);

/// Runs after a light sleep.

///

/// It also runs when a hook refuses a light sleep. An entry hook may already have changed a pad,

/// and the exit hook puts that pad back. A deep sleep resets the chip, which runs the

/// initialization again.

#[instability::unstable]

pub type SleepExitHook = fn();

for_each_wakeup_source! {

    (all $( ($variant:ident, $bit:literal) ),*) => {

        /// One slot for each bit of the mask, so that a source can use its bit as the index.

        const HOOK_SLOTS: usize = {

            let mut highest = 0;

            $(

                if $bit > highest {

                    highest = $bit;

                }

            )*

            highest + 1

        };

    };

}

struct Hooks {

    entry: [Option<SleepEntryHook>; HOOK_SLOTS],

    exit: [Option<SleepExitHook>; HOOK_SLOTS],

}

/// The same lock protects the hooks and the mask bits, so the two always agree.

static HOOKS: NonReentrantMutex<Hooks> = NonReentrantMutex::new(Hooks {

    entry: [None; HOOK_SLOTS],

    exit: [None; HOOK_SLOTS],

});

impl WakeupSource {

    /// Enables this source, so that it can end a sleep.

    ///

    /// The source stays enabled until [`Self::disable`] is called. It also stays enabled through a

    /// sleep and through a deep-sleep wake. While the chip is awake, an enabled source does

    /// nothing.

    // On a chip where all the implemented sources need hooks, nothing calls this function.

    #[allow(dead_code, reason = "not every chip has such a source yet")]

    pub(crate) fn enable(self) {

        self.enable_with_hooks(None, None)

    }

    /// Enables this source and registers the hooks that run around a sleep.

    ///

    /// A source has one slot for each kind of hook, so a second call replaces the hooks of the

    /// first call. One driver owns each source, so only that driver can replace its own hooks.

    /// A call for a source that is already enabled does this.

    ///

    /// Both hooks run with the flash accessible, so they need no [`ram`][crate::ram] attribute. The

    /// entry hook runs before esp-hal writes the sleep configuration to hardware, and the exit hook

    /// runs after the wake sequence restores it. Both hooks are part of sleep entry, so keep them

    /// short.

    ///

    /// Only the driver that owns the source calls this. esp-hal owns the sources of its own

    /// drivers, for example the timer source. A call for such a source replaces the hooks of that

    /// driver, and the driver then does not work through a sleep.

    #[instability::unstable]

        HOOKS.with(|hooks| {

            set_mask_bit(self, true);

        })

    /// Disables this source, and removes its hooks.

    ///

    /// Only the driver that owns the source calls this, as for [`Self::enable_with_hooks`].

    #[instability::unstable]

        HOOKS.with(|hooks| {

            set_mask_bit(self, false);

        })

}

/// Returns the enabled wakeup sources, as the hardware mask records them.

pub(crate) fn enabled_sources() -> enumset::EnumSet<WakeupSource> {

    enumset::EnumSet::from_u32_truncated(mask())

}

/// Returns the sources that reject the next sleep.

///

/// A source rejects a sleep if the source is already asserted when the sleep starts. Without the

/// rejection, the chip sleeps through the event that the caller wants to wake on. The reject

/// sources are the enabled wake sources that the chip can also reject on. A chip cannot reject on

/// every source that it can wake from. esp32 rejects on GPIO and SDIO only, and esp32c2, esp32c3,

/// esp32s2 and esp32s3 do not reject on a UART.

pub(crate) fn reject_mask() -> u32 {

    mask() & property!("sleep.rejectable_mask")

}

/// What the entry hooks asked for, other than power domains and clocks.

///

/// The clock requests reach the configuration before this value is returned, and so does the

/// wake timer. The refusal does not, because only the caller knows what to do with it.

pub(crate) struct SleepEntry {

    /// A hook called [`WrappedSleepConfig::reject_sleep`].

    pub(crate) refused: bool,

    /// How [`WrappedSleepConfig::limit_sleep`] changed the wake timer.

    ///

    /// `None` when no hook set a limit. The caller restores the timer on every path that does not

    /// sleep, and after a light sleep.

    #[cfg(sleep_has_wakeup_source_timer)]

    pub(crate) clamp: Option<super::timer::LimitClamp>,

}

/// Runs the sleep-entry hook of every enabled source.

///

/// One [`WrappedSleepConfig::reject_sleep`] is enough. The caller ignores the refusal for a deep

/// sleep. The wake resets the chip, so there is no caller to report the refusal to. The shortest

/// [`WrappedSleepConfig::limit_sleep`] wins.

///

/// The mask as read at sleep entry selects the hooks. A hook can enable another source. The GPIO

/// hook does this, because it selects between the `ext0`, `ext1` and per-pin paths. The caller

/// therefore reads the mask again after the hooks. It does not run the hooks again until the mask

/// stops to change.

///

/// The caller writes the kind of the sleep to the configuration before this call, so that the hooks

/// can read it.

pub(crate) fn run_entry_hooks(config: &mut RtcSleepConfig) -> SleepEntry {

    let mut wrapped = WrappedSleepConfig::new(config);

        }

    }

    // The clamp writes the comparator, so it runs after every hook has asked for its limit. A

    // source that the clamp enables has not run its entry hook. It runs here, where the requests

    // of a hook still reach the configuration.

    #[cfg(sleep_has_wakeup_source_timer)]

        let clamp = super::timer::clamp_to_limit(limit);

        clamp.apply_entry_hook(&mut wrapped);

        clamp

    });

    SleepEntry {

        #[cfg(sleep_has_wakeup_source_timer)]

        clamp,

    }

}

/// Runs the post-wake hook of every enabled source.

///

/// A light sleep calls this after the wake. A refused light sleep calls it too, so an entry hook

/// can undo a pad change. A sleep that a limit ends before it starts calls it for the same reason.

/// A deep sleep that resets the chip does not call this.

pub(crate) fn run_exit_hooks() {

        }

    }

}

/// Reads the wakeup-enable mask back from hardware.

pub(crate) fn mask() -> u32 {

    let reg = cfg_select! {

        soc_has_pmu => crate::peripherals::PMU::regs().slp_wakeup_cntl2(),

        _ => crate::peripherals::LPWR::regs().wakeup_state(),

    };

    reg.read().wakeup_ena().bits() as _

}

/// Writes the wakeup-enable mask.

///

/// The function writes the field and not the register, because on esp32 the mask shares its

/// register with `gpio_wakeup_filter` and with the read-only `wakeup_cause`.

pub(crate) fn set_mask(mask: u32) {

    let reg = cfg_select! {

        soc_has_pmu => crate::peripherals::PMU::regs().slp_wakeup_cntl2(),

        _ => crate::peripherals::LPWR::regs().wakeup_state(),

    };

    reg.modify(|_, w| unsafe { w.wakeup_ena().bits(mask as _) });

}

fn set_mask_bit(source: WakeupSource, enable: bool) {

    let current = mask();

        current | bit

    } else {

        current & !bit

    });

}