#[ram]Expand description
Sets which segment of RAM to use for a function or static and how it should be initialized.
§Options
rtc_fast: Use RTC fast RAM.rtc_slow: Use RTC slow RAM. Note: not available on all targets.checked: Place a function in the RAM section for code that runs while flash cannot be read, for example while the caches are suspended. The link fails if the function refers to code or constants in flash, or to RAM code withoutchecked. GNU ld, the default linker for the ESP32, ESP32-S2, and ESP32-S3, finds only references to global symbols, for example#[no_mangle]functions.persistent: Persist the contents of thestaticacross resets. See the section below for details.zeroed: Initialize the memory of thestaticto zero. The initializer expression will be discarded. Types used must implementbytemuck::Zeroable.reclaimed: Memory reclaimed from the esp-idf bootloader.uncached: Use internal SRAM through the L1-bypass address range. The CPU does not cache this memory. Only available on ESP32-P4.
Using both rtc_fast and rtc_slow, or persistent and zeroed, together is an error.
checked on a static, or with rtc_fast or rtc_slow, is also an error.
§persistent
Initialize the memory to zero after the initial boot. Thereafter,
initialization is skipped to allow communication across software_reset(),
deep sleep, watchdog timeouts, etc.
Types used must implement bytemuck::AnyBitPattern.
§Warnings
- A system-level or lesser reset occurring before the ram has been zeroed could skip initialization and start the application with the static filled with random bytes.
- There is no way to keep some kinds of resets from happening while updating a persistent static—not even a critical section.
If these are issues for your application, consider adding a checksum alongside the data.
§Examples
ⓘ
#[ram(unstable(rtc_fast))]
static mut SOME_INITED_DATA: [u8; 2] = [0xaa, 0xbb];
#[ram(unstable(rtc_fast, persistent))]
static mut SOME_PERSISTENT_DATA: [u8; 2] = [0; 2];
#[ram(unstable(rtc_fast, zeroed))]
static mut SOME_ZEROED_DATA: [u8; 8] = [0; 8];
#[ram(unstable(uncached))]
static mut UNCACHE_DATA: [u8; 4] = [0x11, 0x22, 0x33, 0x44];
#[ram(unstable(uncached, zeroed))]
static mut UNCACHE_BSS: [u8; 8] = [0; 8];See the ram example in examples/qa of the esp-hal repository for a full usage example.