Struct FlashStorage

Source

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

Expand description

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§

Source §

impl<'d> FlashStorage<'d>

Source

pub const WORD_SIZE: u32 = 4

Flash word size in bytes.

Source

pub const SECTOR_SIZE: u32 = 4096

Flash sector size in bytes.

Source

pub const BLOCK_SIZE: u32 = 65536

Flash block size in bytes.

Source

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

Create a new flash storage instance.

§Panics

Panics if called more than once.

Source §

impl FlashStorage<'_>

Source

pub const READ_SIZE: usize

Minimum read size in bytes for FlashStorage::read_nor.

Source

pub const WRITE_SIZE: usize

Minimum write size in bytes for FlashStorage::write_nor.

Source

pub const ERASE_SIZE: usize

Minimum erase size in bytes for FlashStorage::erase.

Source

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.

Source

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.

Source

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.

Source §

impl FlashStorage<'_>

Source

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.

Source

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.

Source

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.

Source §

impl FlashStorage<'_>

Source

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.

Source

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.