Skip to main content

esp_hal/rtc_cntl/sleep/
mod.rs

1//! # RTC Control Sleep Module
2//!
3//! ## Overview
4//! The `sleep` module allows configuring various wakeup sources and setting up
5//! the sleep behavior based on those sources. The supported wakeup sources
6//! include:
7//!    * `GPIO` pins - light sleep only
8//!    * timers
9//!    * `SDIO (Secure Digital Input/Output) - light sleep only`
10//!    * `MAC (Media Access Control)` wake - light sleep only
11//!    * `UART0` - light sleep only
12//!    * `UART1` - light sleep only
13//!    * `touch`
14//!    * `ULP (Ultra-Low Power)` wake
15//!    * `BT (Bluetooth) wake` - light sleep only
16
17use esp_sync::raw::{RawLock, SingleCoreInterruptLock};
18
19#[cfg(sleep_deep_sleep)]
20use crate::rtc_cntl::WakeupSource;
21use crate::{gpio, peripherals::LPWR, rtc_cntl::Rtc};
22
23/// The CPU clock that [`SleepCpuClock::switch_to_xtal`] replaced for the length of the sleep.
24///
25/// The PLL is powered down across the sleep.
26#[cfg(not(soc_has_pmu))]
27#[must_use]
28struct SleepCpuClock {
29    cpu_clk: Option<crate::soc::clocks::CpuClkConfig>,
30}
31
32#[cfg(not(soc_has_pmu))]
33impl SleepCpuClock {
34    /// Runs the CPU from the crystal until [`Self::restore`].
35    fn switch_to_xtal() -> Self {
36        use crate::soc::clocks::{self, ClockTree, CpuClkConfig};
37
38        ClockTree::with(|clocks| {
39            let cpu_clk = clocks.cpu_clk();
40            clocks::configure_cpu_clk(clocks, CpuClkConfig::Xtal);
41            Self { cpu_clk }
42        })
43    }
44
45    /// Configures the PLL again and restores the CPU clock.
46    fn restore(self) {
47        use crate::soc::clocks::{self, ClockTree};
48
49        ClockTree::with(|clocks| {
50            // If another consumer kept `PLL_CLK` requested while the CPU ran from `XTAL`,
51            // restoring `CPU_CLK` below will not re-enable the PLL. `PLL_CLK` on esp32c2 and
52            // esp32c3 has no other consumer, so restoring `CPU_CLK` configures it again.
53            #[cfg(not(any(esp32c2, esp32c3)))]
54            clocks::reconfigure_pll(clocks);
55            if let Some(cpu_clk) = self.cpu_clk {
56                clocks::configure_cpu_clk(clocks, cpu_clk);
57            }
58        });
59    }
60}
61
62#[cfg(soc_has_pmu)]
63pub(crate) mod pmu_common;
64
65#[cfg_attr(esp32, path = "esp32.rs")]
66#[cfg_attr(esp32s2, path = "esp32s2.rs")]
67#[cfg_attr(esp32s3, path = "esp32s3.rs")]
68#[cfg_attr(esp32c3, path = "esp32c3.rs")]
69#[cfg_attr(esp32c5, path = "esp32c5.rs")]
70#[cfg_attr(esp32c61, path = "esp32c61.rs")]
71#[cfg_attr(esp32c6, path = "esp32c6.rs")]
72#[cfg_attr(esp32c2, path = "esp32c2.rs")]
73#[cfg_attr(esp32h2, path = "esp32h2.rs")]
74#[cfg_attr(esp32h4, path = "esp32h4.rs")]
75#[cfg_attr(esp32p4, path = "esp32p4.rs")]
76#[cfg_attr(esp32s31, path = "esp32s31.rs")]
77mod sleep_impl;
78pub use sleep_impl::*;
79
80#[cfg(sleep_has_wakeup_source_timer)]
81mod timer;
82
83mod wakeup;
84pub(crate) use wakeup::*;
85#[instability::unstable]
86pub use wakeup::{SleepEntryHook, SleepExitHook, WrappedSleepConfig};
87
88/// The result of a light sleep.
89#[cfg(sleep_light_sleep)]
90#[derive(Debug, Clone, Copy, PartialEq, Eq)]
91#[cfg_attr(feature = "defmt", derive(defmt::Format))]
92#[instability::unstable]
93pub enum LightSleep {
94    /// The call returned from the sleep.
95    ///
96    /// The sleep may also never have started, because no wakeup source was enabled, because the
97    /// hardware rejected the request, or because a sleep limit was too short for the transition to
98    /// catch. This result does not tell those apart from a sleep that a wakeup source ended.
99    Ended,
100
101    /// A wakeup source refused the sleep, so the chip stayed awake.
102    ///
103    /// The refusal holds until the state that caused it changes, so a second call refuses too.
104    /// Wait for an interrupt instead.
105    Refused,
106}
107
108#[cfg(supports_cpu_power_down)]
109use crate::rtc_cntl::cpu_retention;
110
111/// The handler that answers whether this core still agrees to a light sleep, or null.
112///
113/// Only the rendezvous of the software retention path reads this, which is why the read lives
114/// there.
115#[cfg(all(multi_core, sleep_driver_supported))]
116pub(crate) static CAN_SLEEP_HANDLER: portable_atomic::AtomicPtr<()> =
117    portable_atomic::AtomicPtr::new(core::ptr::null_mut());
118
119/// The parts of the sleep path that an RTOS fills in.
120#[cfg(all(multi_core, sleep_driver_supported))]
121#[doc(hidden)]
122#[instability::unstable]
123pub mod __rtos_implementation {
124    use portable_atomic::Ordering;
125
126    /// Registers the function that answers whether the core that runs it agrees to a light sleep.
127    ///
128    /// A light sleep that powers the CPU domain down needs every running core to save itself, so
129    /// the core that calls the sleep function asks the other core to join it. The core that calls
130    /// decides for itself. The other core answers this function, and a `false` answer stops the
131    /// sleep. Either core can be the one that answers.
132    ///
133    /// The answer holds for the whole sleep. The core that gives it has its interrupts disabled
134    /// already, so nothing can give that core work while the sleep runs.
135    ///
136    /// # Safety
137    ///
138    /// The handler runs in an interrupt handler, with interrupts disabled and with the caches of
139    /// the sleep path. It must return, it must take no lock that a core can hold across a sleep,
140    /// and it must stay callable for the life of the program.
141    pub unsafe fn set_can_sleep_handler(handler: fn() -> bool) {
142        super::CAN_SLEEP_HANDLER.store(handler as *mut (), Ordering::Release);
143    }
144}
145
146/// Prepares the sleep hardware, and clears the wakeup sources of the previous run.
147///
148/// The wakeup-enable mask survives a deep-sleep wake, so here it still holds the request of the run
149/// that went to sleep. Two steps need the mask, in this order. First, the code releases the pads
150/// that the previous run armed. Then it clears the mask, because a program starts with no wakeup
151/// sources, and the drivers of the new run build the mask again.
152pub(crate) fn init(rtc: &Rtc<'_>) {
153    // First, because the pads that ended a deep sleep are readable only until the code below
154    // changes a path.
155    gpio::wakeup::record_wakeup();
156
157    // Release the pads after a deep-sleep wake only, and only if the previous
158    // run armed an IO wake source.
159    if super::reset_reason(crate::system::Cpu::ProCpu) == Some(super::SocResetReason::CoreDeepSleep)
160        && gpio::wakeup::wake_enabled()
161    {
162        gpio::wakeup::wake_io_reset();
163    }
164
165    RtcSleepConfig::base_settings(rtc);
166
167    set_mask(0);
168}
169
170/// Low-power management.
171///
172/// The sleep calls do not take the wakeup sources that end the sleep. Each driver enables the
173/// source that it owns, and the hardware wakeup-enable mask keeps that request until the driver
174/// clears it. The mask keeps it through a light sleep, and through a deep-sleep wake. A sleep call
175/// reads the mask back, and calculates the rest of the configuration from it.
176#[instability::unstable]
177pub struct LowPower<'d> {
178    _inner: LPWR<'d>,
179}
180
181impl<'d> LowPower<'d> {
182    /// Creates a new `LowPower` driver.
183    pub fn new(lpwr: LPWR<'d>) -> Self {
184        Self { _inner: lpwr }
185    }
186
187    /// Arms the sleep alarm for `deadline`, and enables the timer wakeup source.
188    ///
189    /// The deadline is absolute, so the time between this call and the sleep does not make the
190    /// sleep shorter. The deadline is a standing request. The wake that it causes does not
191    /// disarm it, a later call replaces it, and [`Self::clear_wakeup_deadline`] removes it.
192    ///
193    /// A deadline in the past ends a light sleep immediately, and makes [`Self::sleep_deep`] panic.
194    ///
195    /// A wakeup source can limit one sleep to an earlier wake. The limit does not replace this
196    /// deadline. The deadline stays armed for the next sleep.
197    #[cfg(sleep_has_wakeup_source_timer)]
198    pub fn set_wakeup_deadline(&mut self, deadline: crate::time::Instant) {
199        timer::set_deadline(deadline);
200    }
201
202    /// Disarms the sleep alarm, and disables the timer wakeup source.
203    #[cfg(sleep_has_wakeup_source_timer)]
204    pub fn clear_wakeup_deadline(&mut self) {
205        timer::clear_deadline();
206    }
207
208    /// Enters deep sleep, and does not return.
209    ///
210    /// In deep sleep the CPUs, most of the RAM, and all digital peripherals that are clocked from
211    /// APB_CLK are powered off. The wake resets the chip, so use the
212    /// [`#[esp_hal::ram(persistent)]`][procmacros::ram] attribute to keep a variable through the
213    /// sleep.
214    ///
215    /// The hardware cannot reject this sleep, because the function cannot return to report the
216    /// rejection. Use [`Self::sleep_deep_with_rejection`] for that.
217    ///
218    /// A wakeup source cannot refuse this sleep. The wake resets the chip, so the call cannot
219    /// return a refusal. [`Self::sleep_light`] reports a refusal.
220    #[cfg_attr(
221        cpu_retention = "software",
222        doc = "\n\nDeep sleep shares the entry code of light sleep. See [Optimization \
223               level](crate#optimization-level) for the build requirement.\n"
224    )]
225    /// # Panics
226    ///
227    /// Panics if no wakeup source is enabled, because then nothing can end the sleep. Panics also
228    /// if the armed wakeup deadline is too near for the sleep transition to catch it, or if a
229    /// wakeup source limits the sleep to less time than the transition can catch. In these cases
230    /// the chip never wakes again, and it gives no report of the cause.
231    #[cfg(sleep_deep_sleep)]
232    #[cfg(feature = "rt")]
233    pub fn sleep_deep(&mut self, config: RtcSleepConfig) -> ! {
234        #[cfg(sleep_has_wakeup_source_timer)]
235        if enabled_sources().contains(WakeupSource::Timer) {
236            assert!(
237                !timer::deadline_missed(),
238                "the wakeup deadline is too near to be caught by the sleep transition"
239            );
240        }
241
242        self.sleep(config, SleepKind::Deep, false);
243
244        unreachable!("deep sleep without rejection cannot return")
245    }
246
247    /// Enters deep sleep, and returns only if the hardware rejects the request.
248    ///
249    /// The hardware rejects a sleep if one of its wakeup sources is already asserted. Without the
250    /// rejection, the chip sleeps through the event that the caller wants to wake on. The return of
251    /// this function is the complete report, so it gives no other result.
252    ///
253    /// A wakeup source cannot refuse this sleep. A wakeup source can limit it. The function also
254    /// returns when that limit is too short for the sleep transition to catch. The chip stays
255    /// awake. The return does not say which case it was.
256    ///
257    /// A rejected request returns the wake pads to their drivers, but it cannot return every pad.
258    /// Sleep entry disconnects the pads that no hold keeps, on the chips that need that step to
259    /// reach the deep-sleep current, and it cannot know their earlier configuration. Configure
260    /// those pads again if this function returns. ESP-IDF has the same limit in
261    /// `esp_deep_sleep_try_to_start`.
262    #[cfg_attr(
263        cpu_retention = "software",
264        doc = "\n\nDeep sleep shares the entry code of light sleep. See [Optimization \
265               level](crate#optimization-level) for the build requirement.\n"
266    )]
267    /// # Panics
268    ///
269    /// Panics if no wakeup source is enabled.
270    #[cfg(sleep_deep_sleep)]
271    #[cfg(feature = "rt")]
272    pub fn sleep_deep_with_rejection(&mut self, config: RtcSleepConfig) {
273        self.sleep(config, SleepKind::Deep, true);
274    }
275
276    /// Enters light sleep, and returns when a wakeup source ends it.
277    ///
278    /// Light sleep keeps the state of the digital domain, so the program continues at the same
279    /// place.
280    ///
281    /// A wakeup source can refuse the sleep, which keeps the chip awake. A direct call and
282    /// automatic light sleep both honor a refusal. The return reports it, because the caller then
283    /// has to wait for the event itself.
284    ///
285    /// A wakeup source can also limit the length of the sleep. The chip wakes at the sooner of that
286    /// limit and the armed wakeup deadline. When the timer source is not enabled, the limit enables
287    /// it for this sleep and disables it again afterwards. The sleep does not start when that wake
288    /// is already due, or when the transition cannot catch it. The result is [`LightSleep::Ended`],
289    /// not [`LightSleep::Refused`].
290    ///
291    /// The function also returns without a sleep if no wakeup source is enabled, or if the
292    /// hardware rejects the request because a wakeup source is already asserted. It reports
293    /// neither case. For the caller, a rejected sleep and a very short sleep have the same
294    /// result.
295    #[cfg_attr(
296        cpu_retention = "software",
297        doc = "\n\nLight sleep suspends the caches. See [Optimization \
298               level](crate#optimization-level) for the build requirement."
299    )]
300    #[cfg(sleep_light_sleep)]
301    #[cfg(feature = "rt")]
302    pub fn sleep_light(&mut self, config: RtcSleepConfig) -> LightSleep {
303        if self.sleep(config, SleepKind::Light, true) {
304            LightSleep::Refused
305        } else {
306            LightSleep::Ended
307        }
308    }
309
310    /// Calculates the sleep configuration from the wakeup-enable mask, and enters the sleep.
311    ///
312    /// Returns whether a wakeup source refused a light sleep. A deep sleep ignores a refusal,
313    /// so this function does not return `true` for a deep sleep.
314    ///
315    /// A sleep limit can end the call before the sleep starts. That result is `false`. It is not a
316    /// refusal. A deep sleep whose limit the transition cannot catch panics when the caller cannot
317    /// accept a rejection.
318    #[cfg(sleep_driver_supported)]
319    #[crate::ram]
320    #[cfg(feature = "rt")]
321    pub(crate) fn sleep(
322        &mut self,
323        config: RtcSleepConfig,
324        kind: SleepKind,
325        allow_reject: bool,
326    ) -> bool {
327        // ESP-IDF runs `esp_light_sleep_start` inside `portENTER_CRITICAL(&light_sleep_lock)`.
328        // A sleep ends when `wait_for_sleep_result` sees a wakeup or reject bit, so nothing in
329        // this path needs interrupts.
330        let irq_token = unsafe { SingleCoreInterruptLock.enter() };
331        let refused = cfg_select! {
332            all(cpu_retention = "software", multi_core) => {
333                // The PRO CPU requests every light sleep, because the wake releases the APP CPU
334                // from the PRO CPU.
335                match (kind, crate::system::Cpu::current()) {
336                    (SleepKind::Light, crate::system::Cpu::ProCpu) => {
337                        cpu_retention::rendezvous::take_request();
338                        let refused =
339                            self.sleep_with_interrupts_disabled(config, kind, allow_reject);
340                        cpu_retention::rendezvous::release_app_cpu();
341                        refused
342                    }
343                    // The APP CPU does not learn whether a wakeup source refused the sleep.
344                    (SleepKind::Light, _) => {
345                        cpu_retention::rendezvous::sleep_from_app_cpu(config);
346                        false
347                    }
348                    _ => self.sleep_with_interrupts_disabled(config, kind, allow_reject),
349                }
350            }
351            _ => self.sleep_with_interrupts_disabled(config, kind, allow_reject),
352        };
353        unsafe { SingleCoreInterruptLock.exit(irq_token) };
354        refused
355    }
356
357    #[cfg(sleep_driver_supported)]
358    #[crate::ram]
359    #[cfg(feature = "rt")]
360    fn sleep_with_interrupts_disabled(
361        &mut self,
362        config: RtcSleepConfig,
363        kind: SleepKind,
364        allow_reject: bool,
365    ) -> bool {
366        let rtc = Rtc::new(unsafe { crate::peripherals::RTC_TIMER::steal() });
367
368        let mut config = config;
369        config.set_sleep_kind(kind);
370
371        // Retention serves light sleep only. Deep sleep resets the chip, so it has no CPU state to
372        // bring back, and an armed descriptor would outlive the sleep in the RTC domain. esp-idf
373        // arms retention from its light sleep path alone.
374        //
375        // The buffer is read once, because the rendezvous and the power-down must agree on it. A
376        // buffer that another core installs during this sleep serves the next one.
377        #[cfg(supports_cpu_power_down)]
378        let retention_buffer = match kind {
379            SleepKind::Light => crate::rtc_cntl::installed_buffer_ptr(),
380            SleepKind::Deep => None,
381        };
382
383        // A chip that retains the CPU in software needs every running core to save itself, so the
384        // rendezvous comes first, before any step that a refusal would have to undo. A return
385        // after it must call `rendezvous::finish`.
386        #[cfg(all(cpu_retention = "software", multi_core))]
387        if retention_buffer.is_some() && !cpu_retention::rendezvous::engage() {
388            return false;
389        }
390
391        // The hooks run before `apply`, so that a request to keep a power domain powered reaches
392        // the hardware. They also run before the last read of the mask, because a hook can
393        // enable another source. The GPIO hook does this while it allocates its pins to the
394        // paths.
395        let entry = run_entry_hooks(&mut config);
396
397        // Stop before `apply` when a hook refused a light sleep. `apply` writes the sleep
398        // configuration, and the chip must stay awake with that configuration unchanged.
399        // Entry hooks can already have moved a pad. The exit hooks put the pad back.
400        // A deep sleep ignores the refusal. The wake resets the chip, so there is no caller.
401        if kind == SleepKind::Light && entry.refused {
402            #[cfg(sleep_has_wakeup_source_timer)]
403            if let Some(clamp) = entry.clamp {
404                timer::restore_after_limit(clamp);
405            }
406            run_exit_hooks();
407            #[cfg(all(cpu_retention = "software", multi_core))]
408            cpu_retention::rendezvous::finish();
409            return true;
410        }
411
412        // A limit inside the transition window cannot wake the chip. esp32 cannot reject on the
413        // timer, so the hardware does not report the miss. Stay awake. The exit hooks undo pad
414        // changes from the entry hooks. The comparator was not written.
415        #[cfg(sleep_has_wakeup_source_timer)]
416        if matches!(&entry.clamp, Some(timer::LimitClamp::TooShort)) {
417            run_exit_hooks();
418            #[cfg(all(cpu_retention = "software", multi_core))]
419            cpu_retention::rendezvous::finish();
420            if kind == SleepKind::Deep && !allow_reject {
421                panic!("the wakeup deadline is too near to be caught by the sleep transition");
422            }
423            return false;
424        }
425
426        // A deep sleep keeps what `RtcSleepConfig::deep` asked for, because the wake resets the
427        // chip and keeps no CPU state to lose.
428        #[cfg(supports_cpu_power_down)]
429        if kind == SleepKind::Light {
430            cpu_retention::configure_cpu_retention(&mut config, retention_buffer);
431        }
432
433        // The PMU chips write the configuration when the sleep starts.
434        #[cfg(not(soc_has_pmu))]
435        config.apply();
436
437        // A sleep with no wakeup source never ends. No counter overflow ends it either.
438        let wakeup_mask = mask();
439        if wakeup_mask == 0 {
440            // No sleep starts, so a clamp must not keep the comparator.
441            #[cfg(sleep_has_wakeup_source_timer)]
442            if let Some(clamp) = entry.clamp {
443                timer::restore_after_limit(clamp);
444            }
445            #[cfg(all(cpu_retention = "software", multi_core))]
446            cpu_retention::rendezvous::finish();
447
448            match kind {
449                // Not a software refusal. Light sleep does not report a missing wakeup source.
450                SleepKind::Light => return false,
451                SleepKind::Deep => {
452                    panic!("no wakeup source is enabled, so nothing could end the sleep")
453                }
454            }
455        }
456
457        let reject_mask = if allow_reject { reject_mask() } else { 0 };
458
459        sleep_uart_prepare();
460
461        // Latch the systimer value *before* sleeping. The systimer keeps running during
462        // the sleep enter/exit sequences, so we must not advance from the post-wake
463        // value (that would count the enter/exit time twice). Instead we set an absolute
464        // target of `before + slept`, measured by the always-running LP timer.
465        let before_ticks = crate::time::implem::raw_counter();
466        let before = rtc.time_since_boot_raw();
467
468        let _uart0_sclk_guard = crate::system::ensure_uart0_sclk_enabled();
469
470        #[cfg(multi_core)]
471        let parked = match kind {
472            SleepKind::Light => park_other_cores(),
473            // A deep sleep resets the chip, so the other core needs no stall, and nothing thaws
474            // it afterwards.
475            SleepKind::Deep => 0,
476        };
477
478        // After the light-sleep stall, so that the other core cannot force the SAR on again.
479        let sar_power = SarPower::for_sleep(kind).replace();
480
481        let rejected = {
482            // ESP-IDF arms RTC_CNTL retention in `misc_modules_sleep_prepare`, before it arms the
483            // wakeup sources.
484
485            #[cfg(cpu_retention = "rtc_cntl")]
486            cpu_retention::prepare_cpu_retention(retention_buffer);
487
488            let saved = config.start_sleep(wakeup_mask, reject_mask);
489
490            // Last, because this step takes the pads away from the peripherals that drove them. The
491            // wakeup sources have their holds now, and no later step needs a pad.
492            #[cfg(any(
493                sleep_deep_sleep_needs_gpio_isolation,
494                gpio_need_soft_isolate_during_pd
495            ))]
496            if kind == SleepKind::Deep {
497                gpio::wakeup::isolate_pads_for_deep_sleep();
498            }
499
500            // A CPU power-down loses the dirty cache lines, and with them the writes to PSRAM.
501            // See <https://github.com/espressif/esp-idf/blob/383dda6c182/components/esp_hw_support/sleep_cache.c#L55-L72>.
502            #[cfg(soc_cpu_powers_down_cache)]
503            if retention_buffer.is_some()
504                && config.pd_flags.pd_cpu()
505                && !crate::psram::psram_range().is_empty()
506            {
507                crate::soc::cache_writeback_all();
508            }
509
510            let rejected = cfg_select! {
511                cpu_retention = "software" => {
512                    // The software chips save the CPU inside the request, so the request belongs to
513                    // them. ESP-IDF wraps `pmu_sleep_start` the same way (`sleep_modes.c:963-964`).
514                    cpu_retention::enter_sleep_with_retention(&config, retention_buffer)
515                }
516                _ => config.enter_sleep(),
517            };
518
519            if config.is_deep_sleep() && !rejected {
520                // The chip is entering deep sleep, and the wake resets it. Because RTC is in a
521                // slower clock domain than the CPU, the power-down can take several CPU cycles.
522                loop {
523                    core::hint::spin_loop();
524                }
525            }
526
527            config.finish_sleep();
528            saved.restore();
529
530            rejected
531        };
532
533        #[cfg(supports_cpu_power_down)]
534        if kind == SleepKind::Light && retention_buffer.is_some() {
535            // First, because the other core comes back through the wake stub that the next call
536            // disarms.
537            #[cfg(all(cpu_retention = "software", multi_core))]
538            cpu_retention::rendezvous::finish();
539
540            cpu_retention::finish_cpu_retention(rejected);
541        }
542
543        sar_power.replace();
544
545        #[cfg(multi_core)]
546        unpark_cores(parked);
547
548        let after = rtc.time_since_boot_raw();
549
550        let slept_us = crate::clock::rtc_ticks_to_us(after.wrapping_sub(before));
551        let slept_ticks = crate::time::implem::us_to_ticks(slept_us);
552
553        unsafe { crate::time::implem::update_counter(before_ticks + slept_ticks) };
554        sleep_uart_resume();
555
556        run_exit_hooks();
557
558        // Unlike deep sleep, light sleep does not reset the chip, so `wakeup_cause` cannot rely on
559        // the reset reason to tell whether a wakeup occurred. A rejected request is not a wakeup,
560        // and it must not name a wakeup source.
561        // https://github.com/espressif/esp-idf/blob/a45d713b03fd96d8805d1cc116f02a4415b360c7/components/esp_hw_support/sleep_modes.c#L2158
562        if !config.is_deep_sleep() && !rejected {
563            super::LIGHT_SLEEP_WAKEUP.store(true, portable_atomic::Ordering::Relaxed);
564        }
565
566        // Last, because this call reads the wakeup cause, and after a light sleep the cause is
567        // available only after the line above.
568        gpio::wakeup::record_wakeup();
569
570        // After the cause is recorded. A limit must not keep the comparator, or the next sleep
571        // inherits a deadline that no hook requested.
572        #[cfg(sleep_has_wakeup_source_timer)]
573        if let Some(clamp) = entry.clamp {
574            timer::restore_after_limit(clamp);
575        }
576
577        false
578    }
579}
580
581/// Hardware-stalls the other running cores for the length of a light sleep, or thaws them.
582///
583/// A stall is enough where the retention DMA saves the CPU domain, because the domain holds every
584/// core and the hardware brings the stalled core back with this one. esp-idf stalls the other core
585/// the same way and adds nothing more (`sleep_modes.c`, where the SMP retention work is gated on
586/// `SOC_PM_CPU_RETENTION_BY_SW`).
587///
588/// FIXME: a stall freezes the other core wherever it stands, which can be inside an interrupt
589/// handler that holds a cross-core lock, such as the clock tree, the peripheral reference counts,
590/// or the UART locks that this path takes. This core then spins for that lock for ever, because the
591/// frozen core cannot release it.
592///
593/// A chip that retains the CPU in software needs more than a stall, because each core saves
594/// itself, and a frozen core saves nothing. The rendezvous of that path keeps the other core
595/// running, so this function stalls nothing while that core waits in the rendezvous.
596///
597/// Returns the cores that it stalled, as a bit for each [`Cpu`], for [`unpark_cores`]. A core that
598/// the program stalled before the sleep stays stalled after it.
599#[cfg(all(multi_core, sleep_driver_supported))]
600#[crate::ram]
601fn park_other_cores() -> u8 {
602    // A core that saves itself in the rendezvous must keep running, because a stalled core saves
603    // nothing.
604    #[cfg(all(cpu_retention = "software", multi_core, feature = "rt"))]
605    if cpu_retention::rendezvous::helper_saved() {
606        return 0;
607    }
608
609    let mut parked = 0;
610    for cpu in crate::system::Cpu::other() {
611        if crate::soc::cpu_control::is_running(cpu) {
612            // SAFETY: [`unpark_cores`] runs before this function returns to its caller.
613            unsafe { crate::soc::cpu_control::internal_park_core(cpu, true) };
614            parked |= 1 << cpu as u8;
615        }
616    }
617    parked
618}
619
620/// Thaws the cores that [`park_other_cores`] stalled.
621#[cfg(all(multi_core, sleep_driver_supported))]
622#[crate::ram]
623fn unpark_cores(parked: u8) {
624    for cpu in crate::system::Cpu::other() {
625        if parked & (1 << cpu as u8) != 0 {
626            // SAFETY: this core stalled that core for the sleep, and the sleep is over.
627            unsafe { crate::soc::cpu_control::internal_park_core(cpu, false) };
628        }
629    }
630}
631
632/// Waits for the hardware to report the result of the sleep request, and returns whether the
633/// hardware rejected the request.
634///
635/// A deep sleep powers the CPU down inside this loop, and a light sleep stops the CPU here until a
636/// wakeup source ends the sleep. A rejected request does neither, so the reject interrupt is the
637/// only report of that case. ESP-IDF waits in the same place, in `rtc_sleep_start` and in
638/// `pmu_sleep_start`.
639#[cfg(sleep_driver_supported)]
640#[inline(always)]
641pub(crate) fn wait_for_sleep_result() -> bool {
642    loop {
643        cfg_select! {
644            soc_has_pmu => {
645                let int_raw = crate::peripherals::PMU::regs().int_raw().read();
646                let rejected = int_raw.soc_sleep_reject().bit_is_set();
647                let wakeup = int_raw.soc_wakeup().bit_is_set();
648            }
649            _ => {
650                let int_raw = LPWR::regs().int_raw().read();
651                let rejected = int_raw.slp_reject().bit_is_set();
652                let wakeup = int_raw.slp_wakeup().bit_is_set();
653            }
654        }
655
656        if wakeup || rejected {
657            return rejected;
658        }
659    }
660}
661
662#[cfg(sleep_driver_supported)]
663fn sleep_uart_prepare() {
664    use crate::uart::Instance;
665    for_each_uart! {
666        ($id:literal, $inst:ident, $peri:ident, $rxd:ident, $txd:ident, $cts:ident, $rts:ident, wakeup_source = $_:literal) => {
667            unsafe {
668                crate::peripherals::$inst::steal().info().suspend_for_sleep();
669            }
670        };
671    }
672}
673
674/// The SAR ADC power override, as one 2-bit `force_xpd_sar` mode per SAR unit.
675///
676/// The ADC drivers and the TRNG force the SAR on. The override survives a light sleep, and also a
677/// deep sleep where it lives in the RTC or LP domain.
678#[cfg(sleep_driver_supported)]
679#[derive(Clone, Copy)]
680struct SarPower {
681    sar1: u8,
682    #[cfg(any(esp32p4, esp32s31))]
683    sar2: u8,
684    /// The drive of the radio power detector, which shares the SAR.
685    #[cfg(adc_sar_power_override)]
686    pwdet_drv: bool,
687}
688
689#[cfg(sleep_driver_supported)]
690impl SarPower {
691    const FSM: u8 = 0;
692    const OFF: u8 = 0b10;
693
694    /// Returns the override for a sleep.
695    ///
696    /// The FSM setting powers the SAR down when nothing samples, and leaves it to a ULP program.
697    /// On the ESP32-C2, ESP32-C3 and ESP32-P4 it hands the SAR to the digital controller, which the
698    /// ADC driver or the TRNG forces on, so a light sleep forces the SAR off. A deep sleep keeps
699    /// the FSM setting, because the override survives the wake and not every driver that uses the
700    /// SAR writes it.
701    fn for_sleep(kind: SleepKind) -> Self {
702        let mode = match kind {
703            SleepKind::Light if cfg!(any(esp32c2, esp32c3, esp32p4)) => Self::OFF,
704            _ => Self::FSM,
705        };
706
707        Self {
708            sar1: mode,
709            #[cfg(any(esp32p4, esp32s31))]
710            sar2: mode,
711            #[cfg(adc_sar_power_override)]
712            pwdet_drv: false,
713        }
714    }
715
716    /// Writes the override, and returns the previous one.
717    fn replace(self) -> Self {
718        cfg_select! {
719            adc_sar_power_override => {
720                let mut previous = self;
721                // A dropped ADC driver leaves the override set and the bus clock gated, which drops
722                // this access. A peripheral guard would reset the peripheral.
723                let bus_clock = crate::peripherals::SYSTEM::regs().saradc_conf();
724                let clocked = bus_clock.read().saradc_reg_clk_en().bit();
725                bus_clock.modify(|_, w| w.saradc_reg_clk_en().set_bit());
726
727                crate::peripherals::APB_SARADC::regs()
728                    .ctrl()
729                    .modify(|r, w| {
730                        previous.sar1 = r.xpd_sar_force().bits();
731                        previous.pwdet_drv = r.saradc2_pwdet_drv().bit();
732                        unsafe { w.xpd_sar_force().bits(self.sar1) };
733                        w.saradc2_pwdet_drv().bit(self.pwdet_drv)
734                    });
735
736                bus_clock.modify(|_, w| w.saradc_reg_clk_en().bit(clocked));
737                previous
738            }
739            esp32s31 => {
740                let mut previous = self;
741                let regs = crate::peripherals::APB_SARADC::regs();
742                regs.ctrl0().modify(|r, w| {
743                    previous.sar1 = r.xpd_sar1_force().bits();
744                    unsafe { w.xpd_sar1_force().bits(self.sar1) }
745                });
746                regs.ctrl1().modify(|r, w| {
747                    previous.sar2 = r.xpd_sar2_force().bits();
748                    unsafe { w.xpd_sar2_force().bits(self.sar2) }
749                });
750                previous
751            }
752            esp32p4 => {
753                let mut previous = self;
754                crate::peripherals::LP_ADC::regs()
755                    .force_wpd_sar()
756                    .modify(|r, w| {
757                        previous.sar1 = r.force_xpd_sar1().bits();
758                        previous.sar2 = r.force_xpd_sar2().bits();
759                        unsafe {
760                            w.force_xpd_sar1().bits(self.sar1);
761                            w.force_xpd_sar2().bits(self.sar2)
762                        }
763                    });
764                previous
765            }
766            any(esp32, esp32s2, esp32s3, esp32c2, esp32c3) => {
767                let mut previous = self;
768                let reg = cfg_select! {
769                    esp32 => crate::peripherals::SENS::regs().sar_meas_wait2(),
770                    any(esp32s2, esp32s3) => crate::peripherals::SENS::regs().sar_power_xpd_sar(),
771                    esp32c2 => LPWR::regs().cntl_sensor_ctrl(),
772                    esp32c3 => LPWR::regs().sensor_ctrl(),
773                };
774                reg.modify(|r, w| {
775                    previous.sar1 = r.force_xpd_sar().bits();
776                    unsafe { w.force_xpd_sar().bits(self.sar1) }
777                });
778                previous
779            }
780            _ => {
781                // No driver forces the SAR on, so there is no override to write.
782                let _ = self.sar1;
783                self
784            }
785        }
786    }
787}
788
789#[cfg(sleep_driver_supported)]
790fn sleep_uart_resume() {
791    use crate::uart::Instance;
792    for_each_uart! {
793        ($id:literal, $inst:ident, $peri:ident, $rxd:ident, $txd:ident, $cts:ident, $rts:ident, wakeup_source = $_:literal) => {
794            unsafe {
795                crate::peripherals::$inst::steal().info().resume_from_sleep();
796            }
797        };
798    }
799}