Skip to main content

Crate esp_storage

Crate esp_storage 

Source
Expand description

esp-storage contains API functions related to reading, writing and erasing memory for data in the external flash.

For higher-level functionality which works with partitions defined in the partition table, see esp-bootloader-esp-idf.

Encrypted flash read/write is available on chips with hardware flash encryption support when flash encryption is enabled in eFuses. See FlashStorage::read_encrypted and FlashStorage::write_encrypted.

The embedded-storage feature flag only implements traits from embedded_storage and always assumes access to non-encrypted flash.

If you need to use this struct where traits from embedded_storage_async are needed, you can use embassy_embedded_hal::adapter::BlockingAsync or embassy_embedded_hal::adapter::YieldingAsync wrappers.

§Buffer alignment and stack usage

The ESP flash ROM read/write path requires word-aligned (4-byte) buffers. Several methods accept any &[u8] / &mut [u8] and, when needed, copy through a temporary sector-sized buffer on the stack. That cost is not visible from the slice type and can surprise users in stack-constrained contexts (for example Embassy tasks with small stacks).

FlashStorage::read_nor and FlashStorage::write_nor only allocate this fallback when the caller’s slice pointer is not word-aligned. Each fallback is FlashStorage::SECTOR_SIZE bytes.

FlashStorage::read, FlashStorage::write, and the encrypted variants always allocate a sector buffer on the stack for each call.

§Feature Flags

  • critical-section (enabled by default) — Place the flash operations in a critical section
  • bytewise-read — Bytewise read emulation
  • embedded-storage — Implement traits from embedded-storage for FlashStorage.
  • defmt — Implement defmt::Format on certain types.

§Chip selection

One of the following features must be enabled to select the target chip:

  • esp32c2
  • esp32c3
  • esp32c5
  • esp32c6
  • esp32c61
  • esp32h2
  • esp32p4
  • esp32
  • esp32s2
  • esp32s3
  • esp32s31
  • emulation — Used for testing on a host.

Modules§

ll
Low-level API

Structs§

Flash
FLASH peripheral singleton
FlashStorage
Flash storage abstraction.

Enums§

FlashStorageError
Flash storage error.

Functions§

flash_encryption
Whether flash encryption is enabled or not.