Module flash 

Available on crate feature unstable only.

Internal SPI Flash (FLASH)

Overview

Provides blocking access to the attached SPI flash memory. The driver owns the virtual FLASH peripheral.

Write and erase are NOR flash operations: bits change only from 1 to 0 without an erase. The driver does not perform read-modify-write. Flash::read and Flash::write take word slices (&[u32]) and a 4-byte-aligned byte offset. The buffer must reside in DRAM. Flash::erase operates on 4096-byte sectors.

Flash::read_encrypted and Flash::write_encrypted provide transparent flash encryption. Encrypted writes require a 16-byte-aligned address and a length that is a multiple of 16 bytes (4 words). The destination must already be erased, and bytes outside the requested range are not programmed. Encrypted reads return plaintext if flash encryption is disabled.

For more information, see the ESP-IDF documentation

Configuration

On a dual-core chip, Config selects the strategy for the other core.

Usage

Construct Flash from the virtual FLASH peripheral. offset is a flash byte address, not a word index. The driver does not implement traits from embedded-storage; higher layers provide partition management and storage trait implementations.

Examples

Read a word-aligned range

use esp_hal::flash::{Config, Flash};

let mut flash = Flash::new(peripherals.FLASH, Config::default())?;
let mut buf = [0u32; 8];
flash.read(0x10_020, &mut buf)?;

Implementation State

• On ESP32, a second-stage bootloader must identify the flash chip; the ROM does not. Flash::new fails with ConfigError::UnknownFlashChip if identification is missing (including the ROM placeholder ID 0x001540EF, a valid W25Q16 ID on other chips).
• Driver bounds checks use the JEDEC density from the ROM-cached device ID. ROM operations also check the ROM-cached chip size, which a bootloader can set from the application image header. An operation within Flash capacity can still fail in the ROM if the ROM-cached size is smaller.
• Operations do not check whether the target flash range is mapped. Writing or erasing a mapped section (such as .text or .rodata) can corrupt running code or immutable data.
• Each Flash::read or Flash::write call executes one ROM operation. The flash cache stays off for the whole transfer. Split a large transfer when latency matters.
• On a dual-core chip, the multi-core strategy controls the other core for every operation, including a read.

Structs

ChipInfo

Flash chip identification and geometry.

Config

Flash driver configuration.

Flash

Internal SPI flash driver.

Enums

ConfigError

Error constructing or configuring the flash driver.

Error

Flash operation error.

MultiCoreStrategy

Strategy for the other core during flash operations.

Functions

flash_mmu_drom_entries

Returns the flash MMU entries that map the data (DROM) window, in address order.

flash_mmu_entry_offset

Returns the flash offset that the DROM entry index maps.