From e697c62cfdaf2cbb3f2cbc8f05466b5dcc0c718b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1niel=20Buga?= Date: Mon, 14 Apr 2025 11:33:00 +0200 Subject: [PATCH] Document that atomics in psram don't work (#3379) --- esp-alloc/src/macros.rs | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/esp-alloc/src/macros.rs b/esp-alloc/src/macros.rs index bea9c969c..fdd8c4506 100644 --- a/esp-alloc/src/macros.rs +++ b/esp-alloc/src/macros.rs @@ -28,14 +28,21 @@ macro_rules! heap_allocator { /// Initialize a global heap allocator backed by PSRAM /// -/// You need a SoC which supports PSRAM -/// and activate the feature to enable it. You need to pass the PSRAM peripheral -/// and the psram module path. +/// You need a SoC which supports PSRAM and activate the feature to enable +/// it. You need to pass the PSRAM peripheral and the psram module path. /// /// # Usage +/// /// ```rust, no_run /// esp_alloc::psram_allocator!(peripherals.PSRAM, hal::psram); /// ``` +/// +/// # ⚠️ Limitations +/// +/// On ESP32, ESP32-S2 and ESP32-S3 the atomic instructions do not work +/// correctly when the memory they access is located in PSRAM. This means that +/// the allocator must not be used to allocate `Atomic*` types - either directly +/// or indirectly. Be very careful when using PSRAM in your global allocator. #[macro_export] macro_rules! psram_allocator { ($peripheral:expr, $psram_module:path) => {{