Skip to main content

m5stack_core/
mem.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2//! Global heap ownership + external PSRAM integration.
3//!
4//! The BSP owns the global heap so a binary never spells out
5//! `esp_alloc::heap_allocator!` or the per-board region sizes itself:
6//! [`init_heap`] declares the esp-alloc DRAM regions for a [`HeapProfile`] and,
7//! optionally, registers external PSRAM. esp-alloc's global heap holds at most
8//! three regions, so each profile registers the reclaimed-ROM region, the
9//! plain-DRAM region, and (when PSRAM is supplied) the external region — never a
10//! fourth (a 4th `add_region` panics silently). The sizes are the HIL-proven
11//! per-board values previously copied into every binary.
12//!
13//! ```ignore
14//! use m5stack_core::mem::{self, HeapProfile};
15//!
16//! // After board init, before the first allocation:
17//! mem::init_heap(HeapProfile::Default); // DRAM regions only — never touches PSRAM
18//! mem::init_heap(HeapProfile::Lvgl);
19//! ```
20//!
21//! `init_heap` never touches PSRAM — it owns only the DRAM region sizes for a
22//! [`HeapProfile`]. PSRAM is a separate, deliberate decision: see
23//! [`psram_map`] / [`psram_split`] below. The PSRAM-specific surface (those two,
24//! the checked [`psram_box`] / [`psram_vec`], [`PsramSafe`]) needs the `psram`
25//! feature; the heap regions and [`dma_buffer`] need only `heap`.
26//!
27//! Both boards carry SPI PSRAM (Fire27: ~4 MB, CoreS3: ~8 MB). `esp-alloc`
28//! exposes a single global heap that can be backed by several regions. Getting
29//! PSRAM into one of those regions is opt-in and explicit — there is no
30//! function that puts PSRAM behind the global allocator as a side effect of
31//! anything else, because once a region carries external capability, *every*
32//! plain `alloc::vec!` / `Box` / `String` in the whole crate graph — not just
33//! your own code — becomes eligible to silently spill into it once internal
34//! DRAM is exhausted (esp-alloc has no "external, but not for capability-less
35//! requests" region flag).
36//!
37//! 1. **[`psram_map`] — the default.** Maps PSRAM and hands back the whole
38//!    region as a private slice. Nothing is registered with the global heap;
39//!    nothing here is ever reachable by a plain allocation. Hand the slice to
40//!    a foreign allocator (e.g. LVGL's TLSF) or use it directly.
41//! 2. **[`psram_split`] — deliberate global exposure.** Carves a private
42//!    region off the base (as above) *and* registers the remainder with the
43//!    global heap, for the checked [`psram_box`] / [`psram_vec`] helpers
44//!    (which reject atomic-bearing types at compile time — see [`PsramSafe`]).
45//!    Reach for this only when you've decided part (or with `reserve: 0`, all)
46//!    of PSRAM should be globally exposed, and accept what that costs.
47//!
48//! ```ignore
49//! use m5stack_core::mem;
50//!
51//! // Never touches the global allocator:
52//! let psram = mem::psram_map(peripherals.PSRAM);
53//!
54//! // Deliberately expose part of PSRAM globally:
55//! let split = mem::psram_split(peripherals.PSRAM, 2 * 1024 * 1024)?;
56//! let mut big = mem::psram_vec::<u8>(512 * 1024);   // in PSRAM, atomics rejected
57//! let scratch = mem::psram_box([0u32; 1024]);       // in PSRAM
58//! let dma = mem::dma_buffer(4 * 1024);              // in internal DRAM, DMA-safe
59//! ```
60//!
61//! The raw marker allocators ([`ExternalMemory`] / [`InternalMemory`]) are also
62//! re-exported as an escape hatch for `allocator_api2` containers, but they do
63//! **not** perform the atomic check — reach for them only when you know what
64//! you are placing in PSRAM.
65//!
66//! ## Enforced vs. documented caveats
67//!
68//! - **Atomics must not live in PSRAM.** *Enforced* on the checked path:
69//!   [`psram_box`] / [`psram_vec`] bound `T: PsramSafe`, so anything holding an
70//!   `Atomic*` (directly or transitively) fails to compile.
71//! - **DMA from PSRAM:** the original ESP32 (Fire27) cannot DMA out of PSRAM.
72//!   *Guarded* by [`assert_dma_capable`] (a `debug_assert` on Fire27, a no-op on
73//!   CoreS3, which can DMA from PSRAM); use [`dma_buffer`] to get an
74//!   internal-DRAM buffer in the first place.
75//! - **opt-level > 0:** *Enforced* at build time — enabling the `psram` feature
76//!   with `opt-level = 0` fails the build (see `build.rs`). PSRAM timing
77//!   calibration is unreliable unoptimized.
78
79use allocator_api2::vec::Vec;
80pub use esp_alloc::{AnyMemory, ExternalMemory, InternalMemory};
81#[cfg(feature = "psram")]
82use esp_hal::peripherals::PSRAM;
83
84#[cfg(feature = "psram")]
85use allocator_api2::boxed::Box;
86#[cfg(feature = "psram")]
87use core::mem::MaybeUninit;
88
89/// Heap size profile — selects the HIL-proven per-board DRAM region sizes for a
90/// workload. The BSP owns the sizes so every binary gets the validated values;
91/// pass the matching profile to [`init_heap`].
92#[derive(Clone, Copy, Debug, PartialEq, Eq)]
93pub enum HeapProfile {
94    /// Display / I2C / WiFi-STA workloads: reclaimed-ROM + plain DRAM (+ PSRAM).
95    Default,
96    /// LVGL UI: the reclaimed-ROM region only (LVGL object/style pool); no PSRAM.
97    Lvgl,
98    /// WiFi + BLE coexistence: more controller heap (+ PSRAM). Fire27 favours the
99    /// reclaimed region; CoreS3 favours plain DRAM.
100    Coex,
101}
102
103/// Register the global heap's DRAM regions for `profile`, using the
104/// HIL-proven per-board sizes. Call once, right after [`crate::board::init`] /
105/// `Board::split` and before any allocation.
106///
107/// This is the single place a binary sets up the DRAM heap — it never calls
108/// `esp_alloc::heap_allocator!` itself. This never touches PSRAM: see
109/// [`psram_map`] / [`psram_split`] for that, called separately (and
110/// optionally) afterward. esp-alloc's global heap holds at most three
111/// regions; each profile registers at most the reclaimed-ROM region and the
112/// plain-DRAM region, leaving room for [`psram_split`]'s external region — a
113/// 4th `add_region` panics silently.
114pub fn init_heap(profile: HeapProfile) {
115    match profile {
116        HeapProfile::Default => crate::init_heap_sized!(reclaimed: 50 * 1024, dram: 64 * 1024),
117        HeapProfile::Lvgl => crate::init_heap_sized!(reclaimed: 50 * 1024),
118        HeapProfile::Coex => {
119            #[cfg(feature = "fire27")]
120            crate::init_heap_sized!(reclaimed: 96 * 1024, dram: 24 * 1024);
121            #[cfg(feature = "cores3")]
122            crate::init_heap_sized!(reclaimed: 50 * 1024, dram: 96 * 1024);
123        }
124    }
125}
126
127/// Register the global heap's DRAM regions at explicit sizes. Use when no
128/// [`HeapProfile`] fits — a binary whose sizes are tuned against its own
129/// workload rather than a shared one.
130///
131/// ```rust, no_run
132/// m5stack_core::init_heap_sized!(reclaimed: 56 * 1024);
133/// m5stack_core::init_heap_sized!(reclaimed: 96 * 1024, dram: 24 * 1024);
134/// ```
135///
136/// A macro, not a function: `heap_allocator!` sizes a `static`, and a `static`
137/// cannot read a const generic of the function containing it. The size has to
138/// arrive as a literal at the expansion site.
139///
140/// Prefer [`init_heap`]: a profile is HIL-proven and shared, and a binary that
141/// picks its own number owns the consequences of getting it wrong. This is for
142/// the case where that number IS the validated result — e.g. an LVGL workload
143/// that OOMs mid-render at the `Lvgl` profile's 50 K.
144///
145/// Same region budget as [`init_heap`]: esp-alloc holds at most three regions
146/// and [`psram_split`] wants one.
147#[macro_export]
148macro_rules! init_heap_sized {
149    (reclaimed: $reclaimed:expr, dram: $dram:expr) => {{
150        $crate::esp_alloc::heap_allocator!(#[$crate::esp_hal::ram(reclaimed)] size: $reclaimed);
151        $crate::esp_alloc::heap_allocator!(size: $dram);
152    }};
153    (reclaimed: $reclaimed:expr) => {{
154        $crate::esp_alloc::heap_allocator!(#[$crate::esp_hal::ram(reclaimed)] size: $reclaimed);
155    }};
156    (dram: $dram:expr) => {{
157        $crate::esp_alloc::heap_allocator!(size: $dram);
158    }};
159}
160
161/// Map the board's external PSRAM and return the whole region as a private
162/// slice. Nothing is registered with the global heap — nothing returned here
163/// is ever reachable by a plain `alloc::vec!` / `Box` / `String`.
164///
165/// The default way to get at PSRAM. Hand the slice to a foreign allocator
166/// (e.g. LVGL's built-in TLSF via `lv_mem_add_pool`) or use it directly. For
167/// deliberate global exposure (so [`psram_box`] / [`psram_vec`] can reach
168/// part of PSRAM), use [`psram_split`] instead.
169///
170/// The size is auto-detected. Call once, after [`esp_hal::init`]. Calling
171/// this (or [`psram_split`]) more than once is unsound — the PSRAM controller
172/// must only be initialized a single time.
173#[cfg(feature = "psram")]
174pub fn psram_map(psram: PSRAM<'static>) -> &'static mut [MaybeUninit<u8>] {
175    // SAFETY: see `psram_split`, which this mirrors with `reserve == total`
176    // (the whole region private, nothing registered globally).
177    let psram = esp_hal::psram::Psram::new(psram, Default::default());
178    let (base, total) = psram.raw_parts();
179    info!("PSRAM mapped: {} KiB private", total / 1024);
180    unsafe { core::slice::from_raw_parts_mut(base as *mut MaybeUninit<u8>, total) }
181}
182
183/// A private PSRAM region carved off the global heap, plus the external bytes
184/// registered with the global heap. Returned by [`psram_split`].
185#[cfg(feature = "psram")]
186pub struct PsramSplit {
187    /// A private, exclusive, contiguous PSRAM region for a *foreign* allocator
188    /// (e.g. LVGL's built-in TLSF via `lv_mem_add_pool`). It is **not** part of
189    /// the global heap, so the global allocator never hands it to `Box` / `Vec`
190    /// / DMA. Its base is the PSRAM mapping base, so it is large-aligned (≥ any
191    /// reasonable `ALIGN_SIZE`) — the caller needs no alignment math and no
192    /// `unsafe`.
193    ///
194    /// `'static` is sound because esp-hal's `Psram` has no `Drop`: the mapping is
195    /// a hardware side effect recorded in esp-hal's range statics and is *not*
196    /// undone when the `Psram` value drops.
197    pub private: &'static mut [MaybeUninit<u8>],
198    /// External (PSRAM) heap free immediately after registering the remainder
199    /// with the global heap, in bytes. `0` when `reserve` was `None` (all
200    /// private, nothing registered).
201    pub global_free: usize,
202}
203
204// `private` is a `&'static mut` to uninit memory, so `PsramSplit` cannot derive
205// `Debug`; a manual impl prints the base/len/free a consumer wants when bringing
206// this up on a new board (`log::info!("{:?}", split)`).
207#[cfg(feature = "psram")]
208impl core::fmt::Debug for PsramSplit {
209    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
210        f.debug_struct("PsramSplit")
211            .field("private_base", &self.private.as_ptr())
212            .field("private_len", &self.private.len())
213            .field("global_free", &self.global_free)
214            .finish()
215    }
216}
217
218/// Why [`psram_split`] could not satisfy the request.
219#[cfg(feature = "psram")]
220#[derive(Debug, Clone, Copy, PartialEq, Eq)]
221pub enum PsramSplitError {
222    /// PSRAM did not map — `esp_hal::psram::init_psram` failed, or the board has
223    /// none. Nothing was registered with the global heap.
224    NotMapped,
225    /// PSRAM mapped, but smaller than the requested `reserve`. `available` is the
226    /// total mapped size, so the caller can retry with a smaller pool without
227    /// re-querying — the `PSRAM` peripheral was consumed by value.
228    TooSmall { available: usize },
229}
230
231/// Map the board's external PSRAM, carve a **private** region off the base, and
232/// register the remainder with the global heap.
233///
234/// The deliberate-global-exposure counterpart of [`psram_map`] (which makes
235/// the whole region private and touches the global heap not at all). Reach for
236/// `psram_split` only once you've decided that some of PSRAM should be
237/// reachable by the checked [`psram_box`] / [`psram_vec`] helpers — that
238/// decision then applies to the *whole* crate graph's plain allocations, not
239/// just yours, once internal DRAM runs out (see the module docs).
240///
241/// - `reserve` carves that many bytes private from the base and registers the
242///   remainder globally. `reserve == 0` is the maximal-exposure case: an empty
243///   [`PsramSplit::private`] slice and *all* PSRAM registered globally. Sound (a
244///   zero-length slice grants access to nothing) but rarely what you want —
245///   prefer [`psram_map`] if you don't need any global exposure at all.
246/// - The private region is carved **from the base**, so [`PsramSplit::private`]
247///   starts at the (large-aligned) PSRAM mapping base — aligned for LVGL's TLSF
248///   with no math; esp-alloc aligns the remainder's base internally.
249/// - This primitive controls *placement* (the private/global split). The PSRAM
250///   **hardware** mapping uses the default [`esp_hal::psram`] config, which
251///   auto-detects size — the board-correct choice for both boards. A
252///   `psram_split_with(config)` variant is a non-breaking addition if a consumer
253///   ever needs a custom `PsramConfig` (a fixed `PsramSize`, say); no current
254///   one does.
255///
256/// Call once, after [`esp_hal::init`], **instead of** [`psram_map`]: taking
257/// `PSRAM<'static>` by value makes the once-only mapping a type-level
258/// guarantee, so the two cannot both run.
259///
260/// # Caveats handed back to the caller
261/// - **No atomics in the private region.** The checked [`psram_box`] /
262///   [`psram_vec`] cannot guard a foreign allocator, so keeping `Atomic*` out of
263///   whatever is placed here is the caller's responsibility (holds for LVGL while
264///   `LV_USE_OS` is `LV_OS_NONE`). See [`PsramSafe`].
265/// - **DMA.** The ESP32 (Fire27) cannot DMA to/from PSRAM at all; the ESP32-S3
266///   can but slowly. A foreign allocator must not place DMA'd buffers here. See
267///   [`assert_dma_capable`] / [`dma_buffer`].
268///
269/// # Errors
270/// [`PsramSplitError::NotMapped`] if PSRAM does not map; [`PsramSplitError::TooSmall`]
271/// if it maps smaller than `reserve`.
272#[cfg(feature = "psram")]
273pub fn psram_split(psram: PSRAM<'static>, reserve: usize) -> Result<PsramSplit, PsramSplitError> {
274    // `Psram` has no `Drop`: the mapping is recorded in esp-hal's range statics
275    // and survives the value dropping (see `PsramSplit::private`), so a local is
276    // fine — nothing unmaps at the end of this block.
277    let psram = esp_hal::psram::Psram::new(psram, Default::default());
278    let (base, total) = psram.raw_parts();
279
280    // `Psram::new` maps only if `init_psram` succeeded; on failure the range
281    // statics stay unset and `raw_parts` reports a zero-size region.
282    if total == 0 {
283        return Err(PsramSplitError::NotMapped);
284    }
285
286    if reserve > total {
287        return Err(PsramSplitError::TooSmall { available: total });
288    }
289
290    // Carve `[base, base + reserve)` private.
291    // SAFETY: `base` is the exclusively-owned, `'static` PSRAM mapping (once-only,
292    // guaranteed by consuming `PSRAM<'static>` by value). This sub-range is handed
293    // out privately and is never registered with the global heap, so no aliasing.
294    // `MaybeUninit<u8>` has align 1, and `reserve <= total <= isize::MAX`. When
295    // `reserve == 0` the slice is empty: its base pointer lies inside the region
296    // that *is* registered globally below, but a zero-length slice dereferences
297    // nothing, so it still aliases nothing.
298    let private = unsafe { core::slice::from_raw_parts_mut(base as *mut MaybeUninit<u8>, reserve) };
299
300    // Register the remainder `[base + reserve, base + total)` with the global heap.
301    let global_free = if reserve < total {
302        // SAFETY: disjoint from `private`, `'static`, exclusively the heap's, and
303        // `total - reserve > 0` here (so esp-alloc's `size > 0` precondition holds).
304        unsafe {
305            esp_alloc::HEAP.add_region(esp_alloc::HeapRegion::new(
306                base.add(reserve),
307                total - reserve,
308                esp_alloc::MemoryCapability::External.into(),
309            ));
310        }
311        esp_alloc::HEAP.free_caps(esp_alloc::MemoryCapability::External.into())
312    } else {
313        0
314    };
315
316    info!(
317        "PSRAM split: {} KiB private, {} KiB external free (global)",
318        reserve / 1024,
319        global_free / 1024
320    );
321    Ok(PsramSplit {
322        private,
323        global_free,
324    })
325}
326
327/// Marker for types safe to store in PSRAM: nothing holding an *inline* atomic.
328///
329/// Atomic read-modify-write instructions misbehave against PSRAM-backed
330/// addresses on ESP32 / ESP32-S3, so the checked allocators [`psram_box`] /
331/// [`psram_vec`] only accept `T: PsramSafe`. Like `Send` / `Sync` this is an
332/// auto trait: a struct is `PsramSafe` iff every field is, so a type that
333/// embeds an `Atomic*` (directly or transitively — e.g. via `Arc`, many lock
334/// types) is rejected at compile time.
335///
336/// A *pointer or reference* to an atomic living elsewhere is fine — the atomic
337/// itself is not in PSRAM — so `&T`, `&mut T`, `*const T` and `*mut T` are
338/// always `PsramSafe`.
339///
340/// # Safety
341/// Only implement (or negative-impl) this to reflect the atomic-in-PSRAM
342/// hazard; the checked allocators rely on it to keep atomics out of PSRAM.
343#[cfg(feature = "psram")]
344pub unsafe auto trait PsramSafe {}
345
346#[cfg(feature = "psram")]
347mod psram_safe_impls {
348    use super::PsramSafe;
349    use core::sync::atomic::Atomic;
350
351    // Every atomic aliases `Atomic<T>`. Enumerating the aliases instead is
352    // incomplete, and illegal since each names a concrete `Atomic<..>` — a
353    // negative impl may not specialize (E0366).
354    impl<T> !PsramSafe for Atomic<T> {}
355
356    // A pointer/reference to an atomic is fine — the atomic lives elsewhere.
357    // (Mirrors `unsafe impl<T: ?Sized> Send for &T` in std.)
358    unsafe impl<T: ?Sized> PsramSafe for &T {}
359    unsafe impl<T: ?Sized> PsramSafe for &mut T {}
360    unsafe impl<T: ?Sized> PsramSafe for *const T {}
361    unsafe impl<T: ?Sized> PsramSafe for *mut T {}
362}
363
364/// Allocate `value` in external PSRAM. Atomic-bearing `T` is rejected at
365/// compile time via [`PsramSafe`].
366#[cfg(feature = "psram")]
367pub fn psram_box<T: PsramSafe>(value: T) -> Box<T, ExternalMemory> {
368    Box::new_in(value, ExternalMemory)
369}
370
371/// A `Vec<T>` with room for `capacity` elements reserved in external PSRAM.
372/// Atomic-bearing `T` is rejected at compile time via [`PsramSafe`].
373#[cfg(feature = "psram")]
374pub fn psram_vec<T: PsramSafe>(capacity: usize) -> Vec<T, ExternalMemory> {
375    Vec::with_capacity_in(capacity, ExternalMemory)
376}
377
378/// The most internal-region bytes seen in use by [`sample`].
379///
380/// `esp-alloc`'s own `max_usage` sums every region, PSRAM included, so it
381/// cannot say how full internal RAM got, which is the scarce one.
382static INTERNAL_MAX: core::sync::atomic::AtomicUsize = core::sync::atomic::AtomicUsize::new(0);
383
384/// Record the internal regions' current use, keeping the largest seen.
385///
386/// A high-water mark is only as good as the moments it is taken: call it where
387/// the peak plausibly is, such as after the radio is up and at each session end.
388pub fn sample() {
389    let stats = esp_alloc::HEAP.stats();
390    let internal: usize = stats
391        .region_stats
392        .iter()
393        .flatten()
394        .filter(|r| {
395            !r.capabilities
396                .contains(esp_alloc::MemoryCapability::External)
397        })
398        .map(|r| r.used)
399        .sum();
400    INTERNAL_MAX.fetch_max(internal, core::sync::atomic::Ordering::Relaxed);
401}
402
403/// The internal regions' high-water mark over every [`sample`] so far.
404#[must_use]
405pub fn internal_high_water() -> usize {
406    INTERNAL_MAX.load(core::sync::atomic::Ordering::Relaxed)
407}
408
409/// Free bytes in the global heap's **internal** DRAM regions (reclaimed-ROM +
410/// plain-DRAM), right now. The tight resource on both boards; use it to compare
411/// totals (e.g. before/after moving a subsystem's heap to PSRAM).
412///
413/// **A sum, not headroom.** It cannot answer "will a block of N bytes
414/// allocate": the regions are separate and each fragments independently, so a
415/// large total can hold no large block. Measured on fire27 — 39,172 B free and
416/// a 23,760 B request refused, with the caller retrying 73,679 times. A gate
417/// built on this number passes exactly the case that fails. To know whether an
418/// allocation will succeed, attempt it and free it.
419pub fn internal_free() -> usize {
420    esp_alloc::HEAP.free_caps(esp_alloc::MemoryCapability::Internal.into())
421}
422
423/// Free bytes in the global heap's **external** (PSRAM) region, right now — `0`
424/// unless [`psram_split`] registered a non-empty remainder globally (a private
425/// [`psram_map`] / [`psram_split`] region is *not* counted here).
426///
427/// A sum, with the same caveat as [`internal_free`].
428pub fn external_free() -> usize {
429    esp_alloc::HEAP.free_caps(esp_alloc::MemoryCapability::External.into())
430}
431
432/// A zeroed byte buffer in internal DRAM, suitable as a DMA buffer.
433///
434/// Convenience for the common "I need a DMA-capable scratch buffer" case so the
435/// allocator does not have to be spelled out. The result is DMA-reachable on
436/// both chips; pair it with [`assert_dma_capable`] if a buffer's origin is ever
437/// in doubt.
438pub fn dma_buffer(len: usize) -> Vec<u8, InternalMemory> {
439    let mut v = Vec::with_capacity_in(len, InternalMemory);
440    v.resize(len, 0);
441    v
442}
443
444/// Debug-assert that `buf` is DMA-reachable on this chip.
445///
446/// On the ESP32 (Fire27) the DMA engine cannot reach the PSRAM-mapped data
447/// window, so a PSRAM-backed buffer handed to SPI/I2S DMA silently corrupts.
448/// This catches that on first use under `debug_assertions`. It is a no-op
449/// (compiled away) on the ESP32-S3, which *can* DMA from PSRAM.
450#[cfg(feature = "fire27")]
451#[inline]
452pub fn assert_dma_capable(buf: &[u8]) {
453    // ESP32 external RAM (PSRAM) is cache-mapped into this data window; internal
454    // DRAM lives above it. Constant per the ESP32 TRM external-memory map.
455    const PSRAM_DATA_WINDOW: core::ops::Range<usize> = 0x3F80_0000..0x3FC0_0000;
456    let p = buf.as_ptr() as usize;
457    debug_assert!(
458        !PSRAM_DATA_WINDOW.contains(&p),
459        "DMA buffer at {p:#x} lives in PSRAM; the ESP32 cannot DMA to/from PSRAM \
460         — allocate it in InternalMemory (see mem::dma_buffer)"
461    );
462}
463
464/// No-op on every target except the ESP32 (Fire27); see the Fire27 variant.
465#[cfg(not(feature = "fire27"))]
466#[inline]
467pub fn assert_dma_capable(_buf: &[u8]) {}