Skip to main content

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}