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}