Struct FlashStorage 

pub struct FlashStorage<'d> { /* private fields */ }

Flash storage abstraction.

This type can read and write any location on the SPI flash chip. For application data, it is recommended to reserve a dedicated partition instead of writing to arbitrary addresses. For partition-table helpers, see esp-bootloader-esp-idf.

Use FlashStorage::write_nor and FlashStorage::erase for low-level NOR flash semantics, or FlashStorage::write for read-modify-write with automatic sector erasure.

See the crate-level documentation for stack usage.

Implementations

impl<'d> FlashStorage<'d>

pub const WORD_SIZE: u32 = 4

Flash word size in bytes.

pub const SECTOR_SIZE: u32 = 4096

Flash sector size in bytes.

pub const BLOCK_SIZE: u32 = 65536

Flash block size in bytes.

pub fn new(flash: Flash<'d>) -> Self

Create a new flash storage instance.

Panics

Panics if called more than once.

impl<'d> FlashStorage<'d>

pub fn multicore_auto_park(self) -> FlashStorage<'d>

Enable auto parking of the second core before writing to flash. The other core will be automatically un-parked when the write is complete.

pub unsafe fn multicore_ignore(self) -> FlashStorage<'d>

Do not check if the second core is active before writing to flash.

Safety

Only enable this if you are sure that the second core is not fetching instructions from the flash during the write.

impl FlashStorage<'_>

pub const READ_SIZE: usize

Minimum read size in bytes for FlashStorage::read_nor.

pub const WRITE_SIZE: usize

Minimum write size in bytes for FlashStorage::write_nor.

pub const ERASE_SIZE: usize

Minimum erase size in bytes for FlashStorage::erase.

pub fn read_nor( &mut self, offset: u32, bytes: &mut [u8], ) -> Result<(), FlashStorageError>

Read bytes from flash using NOR flash semantics.

offset and bytes.len() must be aligned to Self::READ_SIZE.

Note

If bytes is not word-aligned (4-byte), this function allocates a Self::SECTOR_SIZE-byte buffer on the stack and copies through it. See the crate-level documentation.

Errors

Returns FlashStorageError::NotAligned if offset or bytes.len() is not aligned to Self::READ_SIZE.

Returns FlashStorageError::OutOfBounds if the read would extend past the end of the flash.

pub fn write_nor( &mut self, offset: u32, bytes: &[u8], ) -> Result<(), FlashStorageError>

Write bytes to flash using NOR flash semantics.

NOR flash can only change bits from 1 to 0. Setting a bit from 0 to 1 requires erasing the containing sector first (see Self::erase). Each byte is updated by ANDing it with the data being written; if the target still contains 0 bits where you need 1s, the stored value will not match what you passed in even though the operation succeeds.

offset and bytes.len() must be aligned to Self::WRITE_SIZE.

Note

If bytes is not word-aligned (4-byte), this function allocates a Self::SECTOR_SIZE-byte buffer on the stack and copies through it. See the crate-level documentation.

Errors

Returns FlashStorageError::NotAligned if offset or bytes.len() is not aligned to Self::WRITE_SIZE.

Returns FlashStorageError::OutOfBounds if the write would extend past the end of the flash.

pub fn erase(&mut self, from: u32, to: u32) -> Result<(), FlashStorageError>

Erase flash from from up to but not including to.

Erased bytes are set to 0xFF. Both addresses must be aligned to Self::ERASE_SIZE, and to - from must be a multiple of Self::ERASE_SIZE.

Errors

Returns FlashStorageError::NotAligned if from or to - from is not aligned to Self::ERASE_SIZE.

Returns FlashStorageError::OutOfBounds if the range would extend past the end of the flash, or if to is less than from.

impl FlashStorage<'_>

pub fn read( &mut self, offset: u32, bytes: &mut [u8], ) -> Result<(), FlashStorageError>

Read bytes from flash.

Unaligned offsets and lengths are supported.

Note

This function always allocates a Self::SECTOR_SIZE-byte buffer on the stack. See the crate-level documentation.

Errors

Returns FlashStorageError::OutOfBounds if the read would extend past the end of the flash.

pub fn capacity(&self) -> usize

The SPI flash size is configured by writing a field in the software bootloader image header. This is done during flashing in espflash / esptool.

pub fn write( &mut self, offset: u32, bytes: &[u8], ) -> Result<(), FlashStorageError>

Write bytes to flash.

Performs read-modify-write on affected sectors and erases each sector before writing. Unlike FlashStorage::write_nor, alignment is not required and erasure is handled automatically.

Note

This function always allocates a Self::SECTOR_SIZE-byte buffer on the stack. See the crate-level documentation.

Errors

Returns FlashStorageError::OutOfBounds if the write would extend past the end of the flash.

impl FlashStorage<'_>

pub fn read_encrypted( &mut self, offset: u32, bytes: &mut [u8], ) -> Result<(), FlashStorageError>

Read bytes from encrypted flash.

Uses the MMU to map flash pages and reads decrypted data through the cache. Unaligned offsets and lengths are supported.

If flash encryption is not enabled this will just read plaintext.

Note

This function always allocates a Self::SECTOR_SIZE-byte buffer on the stack. See the crate-level documentation.

Errors

Returns FlashStorageError::OutOfBounds if the read would extend past the end of the flash. Returns FlashStorageError::OtherCoreRunning if the other core is active, because this function changes the flash MMU and the cache.

pub fn write_encrypted( &mut self, offset: u32, bytes: &[u8], ) -> Result<(), FlashStorageError>

Write bytes to encrypted flash.

Performs read-modify-write on affected sectors: reads the current encrypted content, merges the new bytes, erases the sector, then writes it back encrypted.

Note

This function always allocates a Self::SECTOR_SIZE-byte buffer on the stack. See the crate-level documentation.

Errors

Returns FlashStorageError::NotSupported if flash encryption is not enabled.

Returns FlashStorageError::OutOfBounds if the write would extend past the end of the flash. Returns FlashStorageError::OtherCoreRunning if the other core is active, because this function changes the flash MMU and the cache.

Trait Implementations

impl<'d> Debug for FlashStorage<'d>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.