Struct Flash 

pub struct Flash<'d, Dm: DriverMode> { /* private fields */ }

Available on crate feature unstable only.

Internal SPI flash driver.

Constructible only in Blocking mode.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Implementations

impl<'d> Flash<'d, Blocking>

pub const PAGE_SIZE: u32 = 256

Program page size in bytes.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub const SECTOR_SIZE: u32 = 4096

Erase sector size in bytes.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub const BLOCK_SIZE: u32 = 65536

Erase block size in bytes.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn new(flash: FLASH<'d>, config: Config) -> Result<Self, ConfigError>

Creates a new flash driver from the FLASH peripheral.

Capacity is determined from the JEDEC density in the ROM-cached device ID, not the image-header size or the ROM cached chip size used by read, write, and erase operations.

Errors

• ConfigError::UnknownFlashChip if the attached flash chip cannot be identified or its size is not recognized. On ESP32, this error also occurs when a second-stage bootloader has not identified the chip (including the ROM placeholder ID 0x001540EF).

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError>

Applies a new configuration.

Updates the multi-core strategy on dual-core chips. On single-core chips, this is a no-op. The return type is reserved for future configuration options.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn capacity(&self) -> usize

Returns the JEDEC-decoded flash capacity in bytes.

Driver bounds checks use this value. ROM read, write, and erase operations also check the ROM-cached chip size, which a bootloader can set from the application image header.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn chip_info(&self) -> ChipInfo

Returns chip identification and geometry.

chip_id contains the manufacturer ID in bits 23:16. capacity is the JEDEC density; see Self::capacity. Geometry is fixed, not probed from the chip.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

#[unsafe(link_section = ".rwtext")]

pub fn read(&mut self, offset: u32, data: &mut [u32]) -> Result<(), Error>

Reads words into data starting at byte address offset.

offset is a flash byte address and must be a multiple of 4. data must reside in DRAM, not in flash, IRAM, RTC memory, or PSRAM. An empty data slice only checks that offset is within Self::capacity.

Errors

• Error::NotAligned if data is non-empty and offset is not a multiple of 4.
• Error::OutOfBounds if the range exceeds Self::capacity.
• Error::NotSupported if data is not in DRAM.
• Error::IoError, Error::IoTimeout, or Error::Unknown if the ROM reports an I/O error.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

#[unsafe(link_section = ".rwtext")]

pub unsafe fn write(&mut self, offset: u32, data: &[u32]) -> Result<(), Error>

Writes data starting at byte address offset.

The target flash range must already be erased. offset is a flash byte address and must be a multiple of 4. data must reside in DRAM, not in flash, IRAM, RTC memory, or PSRAM. An empty data slice only checks that offset is within Self::capacity.

Errors

• Error::NotAligned if data is non-empty and offset is not a multiple of 4.
• Error::OutOfBounds if the range exceeds Self::capacity.
• Error::NotSupported if data is not in DRAM.
• Error::IoError, Error::IoTimeout, or Error::Unknown if the ROM reports an I/O error.

Safety

The programmed range must not be mapped for instruction fetch or as immutable data. Writing a mapped .text or .rodata page overwrites the running image or mutates data the compiler treats as immutable.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

#[unsafe(link_section = ".rwtext")]

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

Erases flash sectors in the range [from, to).

from and to must be multiples of Self::SECTOR_SIZE (4096 bytes); there is no byte-granular erase. to == capacity is allowed. When from == to, this function only checks that from is within Self::capacity.

Errors

• Error::NotAligned if from != to and from or to is not a multiple of 4096.
• Error::OutOfBounds if from > to or the range exceeds Self::capacity.
• Error::IoError, Error::IoTimeout, or Error::Unknown if the ROM reports an I/O error.

Safety

The erased range must not be mapped for instruction fetch or as immutable data. Erasing a mapped .text or .rodata page destroys the running image or mutates data the compiler treats as immutable.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn read_encrypted( &mut self, offset: u32, data: &mut [u32], ) -> Result<(), Error>

Reads decrypted words into data starting at byte address offset.

Uses a temporary MMU mapping to read decrypted data through the cache. If flash encryption is not enabled, this returns plaintext.

offset is a flash byte address and must be a multiple of 4. data must reside in DRAM, not in flash, IRAM, RTC memory, or PSRAM. An empty data slice only checks that offset is within Self::capacity.

Errors

• Error::NotAligned if data is non-empty and offset is not a multiple of 4.
• Error::OutOfBounds if the range exceeds Self::capacity.
• Error::NotSupported if data is not in DRAM or no MMU entry is available.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

#[unsafe(link_section = ".rwtext")]

pub unsafe fn write_encrypted( &mut self, offset: u32, data: &[u32], ) -> Result<(), Error>

Writes data with transparent flash encryption.

offset must be a multiple of 16, and data.len() must be a multiple of 4 words (16 bytes). The destination must already be erased, and bytes outside the requested range are not programmed. data must reside in DRAM, not in flash, IRAM, RTC memory, or PSRAM.

On ESP32, encrypted writes operate in 32-byte rows. If a boundary is not 32-byte aligned, the driver preserves the adjacent 16-byte block by re-encrypting its existing plaintext to the same ciphertext. The neighbor block therefore does not require prior erasing. An empty data slice only checks that offset is within Self::capacity.

Errors

• Error::NotSupported if flash encryption is disabled. The eFuse gate is checked before the arguments are.
• Error::NotAligned if data is non-empty and offset is not a multiple of 16, or data.len() is not a multiple of 4 words (16 bytes).
• Error::OutOfBounds if the range exceeds Self::capacity.
• Error::NotSupported if data is not in DRAM, or on ESP32 if reading a row neighbor fails because no MMU entry is available.
• Error::IoError, Error::IoTimeout, or Error::Unknown if the ROM reports an I/O error.

Safety

The programmed range must not be mapped for instruction fetch or as immutable data. Writing a mapped .text or .rodata page overwrites the running image, or mutates static or .rodata data the compiler treats as immutable.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl<'d, Dm: Debug + DriverMode> Debug for Flash<'d, Dm>

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

Formats the value using the given formatter.