esp_hal/rtc_cntl/cpu_retention/memory.rs
1//! The CPU retention memory and its one-shot install API.
2
3use core::ptr::NonNull;
4
5use crate::rtc_cntl::{
6 RetentionMemory,
7 RetentionMemoryError,
8 RetentionSlot,
9 RetentionStorage,
10 sleep::LowPower,
11};
12
13cfg_select! {
14 cpu_retention = "software" => {
15 pub(crate) use super::software::BUFFER_SIZE;
16 }
17 _ => {
18 pub(crate) const BUFFER_SIZE: usize = property!("sleep.cpu_retention_mem_size");
19
20 /// `repr(align)` takes a literal, so the buffer takes the strictest alignment of every
21 /// chip. The alignment then needs no check at run time.
22 const _: () = ::core::assert!(property!("sleep.cpu_retention_mem_align") <= 16);
23 }
24}
25
26static INSTALLED: RetentionSlot<BUFFER_SIZE> = RetentionSlot::new();
27
28/// Storage for [`CpuRetentionMemory`].
29///
30/// This storage must be placed to `#[ram(reclaimed, unstable(zeroed))]`, then
31/// a static mutable reference to [`CpuRetentionMemory`] can be taken out of it.
32#[instability::unstable]
33pub type CpuRetentionStorage = RetentionStorage<BUFFER_SIZE>;
34
35/// Memory that light sleep uses to retain the CPU domain.
36///
37/// The sleep path writes this memory while the CPU domain has no power, so the buffer gives no way
38/// to read or write its contents through safe Rust.
39///
40/// Install the buffer with [`LowPower::install_cpu_retention_memory`]. The buffer must live in
41/// internal RAM that stays powered across light sleep. The [`#[ram(reclaimed)]`][crate::ram]
42/// attribute places a static inside the reachable range on chips that use the retention DMA.
43#[instability::unstable]
44pub type CpuRetentionMemory = RetentionMemory<BUFFER_SIZE>;
45
46/// The reason why [`LowPower::install_cpu_retention_memory`] refused a buffer.
47#[instability::unstable]
48pub type CpuRetentionMemoryError = RetentionMemoryError;
49
50impl LowPower<'_> {
51 #[procmacros::doc_replace]
52 /// Gives light sleep the memory that it uses to retain the CPU domain.
53 ///
54 /// Light sleep powers the CPU domain down only after it has this memory. The memory stays with
55 /// the driver for the life of the program, and a second call is an error, because the sleep
56 /// path can hold one buffer only.
57 ///
58 /// # Errors
59 ///
60 /// Returns [`CpuRetentionMemoryError`] if the driver holds a buffer already, or if the buffer
61 /// is not inside the range that retention needs. The
62 /// [`#[ram(reclaimed, unstable(zeroed))]`][crate::ram] attribute places a static inside that
63 /// range on DMA chips.
64 ///
65 /// # Examples
66 ///
67 /// ```rust, no_run
68 /// # {before_snippet}
69 /// use esp_hal::rtc_cntl::{CpuRetentionStorage, sleep::LowPower};
70 ///
71 /// // #[esp_hal::ram(reclaimed, unstable(zeroed))]
72 /// static RETENTION: CpuRetentionStorage = CpuRetentionStorage::new();
73 ///
74 /// let mut lpwr = LowPower::new(peripherals.LPWR);
75 /// lpwr.install_cpu_retention_memory(RETENTION.take())?;
76 /// # {after_snippet}
77 /// ```
78 #[instability::unstable]
79 pub fn install_cpu_retention_memory(
80 &mut self,
81 memory: &'static mut CpuRetentionMemory,
82 ) -> Result<(), CpuRetentionMemoryError> {
83 INSTALLED.install(memory)
84 }
85}
86
87pub(crate) fn installed_buffer_ptr() -> Option<NonNull<u8>> {
88 INSTALLED.get()
89}