Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/embedded/flash/spi_nor"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
| Alias | Package | Source file |
|---|---|---|
hal |
std/embedded/hal |
spi_nor.dodo |
STATUS_BUSY
Constant · Source
Status register 1: a program or erase is running (BUSY, also WIP), writes are enabled (WEL), and the block-protect bits (BP0 to BP3, or BP0 to BP2 and TB, depending on the family).
pub const STATUS_BUSY: u8 = 0x01
STATUS_WRITE_ENABLED
Constant · Source
pub const STATUS_WRITE_ENABLED: u8 = 0x02
STATUS_PROTECTION
Constant · Source
pub const STATUS_PROTECTION: u8 = 0x3C
PAGE_BYTES
Constant · Source
The program size: a page program writes within one page.
pub const PAGE_BYTES: u32 = 256
SECTOR_BYTES
Constant · Source
The usual smallest erase, and the block erase.
pub const SECTOR_BYTES: u32 = 4096
BLOCK_BYTES
Constant · Source
pub const BLOCK_BYTES: u32 = 65536
THREE_BYTE_LIMIT
Constant · Source
The largest part that 3-byte addresses reach.
pub const THREE_BYTE_LIMIT: u32 = 16 * 1024 * 1024
CHIP_ERASE_POLLS
Constant · Source
Status polls a chip erase waits before Timeout.
pub const CHIP_ERASE_POLLS: u32 = 0xFFFF_FFFF
WAKE_POLLS
Constant · Source
JEDEC ID reads a wake or reset waits for the chip to answer again before Timeout: release from deep power-down takes at most tens of microseconds, a reset during an erase some milliseconds.
pub const WAKE_POLLS: u32 = 100_000
RESET_POLLS
Constant · Source
pub const RESET_POLLS: u32 = 1_000_000
Flash
Struct · Source
One SPI NOR flash chip; see the package comment.
pub struct Flash<B: hal.Spi, P: hal.OutputPin>: hal.Flash {
// Private implementation fields omitted.
}
Flash.attach
Function · Source
Take the bus and the chip-select pin, and deselect the chip, without talking to it: capacity() is 0, and every read, erase, or write is InvalidInput, until
probeorset_capacity. Most programs callnewinstead.
pub fn attach(bus: B, select: P) -> Flash<B, P> from(bus, select)
Flash.new
Function · Source
Attach to the chip and probe it; see
probe. The bus and pin are dropped with an error; use attach and probe to keep them.
pub fn new(bus: B, select: P) -> Flash<B, P>!hal.Error from(bus, select)
Flash.probe
Function · Source
Wake the chip, read its JEDEC ID, wait until it is idle, and learn its size, erase commands, and addressing from SFDP or the ID; see “Probing”. NoAcknowledge if no chip answers, Unsupported for a size it cannot tell or a part it cannot address, Timeout if it stays busy.
pub fn probe(&mut self) -> void!hal.Error
Flash.jedec_id
Function · Source
The JEDEC ID read by
probe: the manufacturer (EFh Winbond, C8h GigaDevice, C2h Macronix, 9Dh ISSI, 20h Micron) in bits 23-16, the memory type in bits 15-8, and the capacity code in bits 7-0. 0 before probing.
pub fn jedec_id(&self) -> u32
Flash.manufacturer
Function · Source
The manufacturer byte of the JEDEC ID.
pub fn manufacturer(&self) -> u8
Flash.read_jedec_id
Function · Source
Read the JEDEC ID from the chip now, as
jedec_idreports it. A sleeping chip answers garbage; this does not wake it.
pub fn read_jedec_id(&mut self) -> u32!hal.Error
Flash.read_sfdp
Function · Source
Copy
buffer.lenbytes of the chip’s SFDP data fromaddressintobuffer, for parameters this driver does not use.
pub fn read_sfdp(&mut self, address: u32, buffer: &mut[u8]) -> void!hal.Error
Flash.set_capacity
Function · Source
Take
bytesas the chip’s size, a nonzero multiple of erase_size(), for a chip whose size neither SFDP nor its ID tells, or to use only its start. Parts above THREE_BYTE_LIMIT need probing first, so that 4-byte addressing is chosen.
pub fn set_capacity(&mut self, bytes: u32) -> void!hal.Error
Flash.set_fast_read
Function · Source
Read with the plain read command (03h) instead of fast read (0Bh): only for the rare part without fast read, as plain reads are limited to lower clock rates.
pub fn set_fast_read(&mut self, fast: bool)
Flash.set_poll_limit
Function · Source
Give up waiting for a program or erase after
pollsstatus reads; hal.NO_POLL_LIMIT waits as long as it takes. A chip erase waits up to CHIP_ERASE_POLLS whatever the limit, unless it is NO_POLL_LIMIT.
pub fn set_poll_limit(&mut self, polls: u32)
Flash.uses_four_byte_addresses
Function · Source
True if the chip takes 4-byte addresses: parts above 16 MiB.
pub fn uses_four_byte_addresses(&self) -> bool
Flash.block_size
Function · Source
The size of a block erase, used where an erase covers whole blocks, or 0 if the chip has none beyond erase_size().
pub fn block_size(&self) -> u32
Flash.capacity
Function · Source
pub fn capacity(&self) -> u32
Flash.erase_size
Function · Source
pub fn erase_size(&self) -> u32
Flash.write_size
Function · Source
1: any byte can be written; writes split at page boundaries.
pub fn write_size(&self) -> u32
Flash.read
Function · Source
pub fn read(&mut self, offset: u32, buffer: &mut[u8]) -> void!hal.Error
Flash.erase
Function · Source
Erase whole blocks where the range covers them and erase_size() units elsewhere.
pub fn erase(&mut self, offset: u32, length: u32) -> void!hal.Error
Flash.write
Function · Source
pub fn write(&mut self, offset: u32, bytes: &[u8]) -> void!hal.Error
Flash.erase_chip
Function · Source
Erase the whole chip (C7h), which takes from seconds to minutes; see “Waiting”. A chip with any block protected refuses it.
pub fn erase_chip(&mut self) -> void!hal.Error
Flash.status
Function · Source
Status register 1; see the STATUS_ bits.
pub fn status(&mut self) -> u8!hal.Error
Flash.is_busy
Function · Source
True while a program or erase runs.
pub fn is_busy(&mut self) -> bool!hal.Error
Flash.is_protected
Function · Source
True if any block-protect bit is set, so that the chip may ignore programs and erases of some blocks.
pub fn is_protected(&mut self) -> bool!hal.Error
Flash.unprotect
Function · Source
Clear the block-protect bits in status register 1, keeping its other bits, so every block can be programmed and erased. Bus if the chip keeps them, as when its status register is locked by the WP# pin.
pub fn unprotect(&mut self) -> void!hal.Error
Flash.power_down
Function · Source
Send the chip to deep power-down, once a running program or erase has finished; any operation wakes it again.
pub fn power_down(&mut self) -> void!hal.Error
Flash.is_powered_down
Function · Source
True between power_down and the next operation or wake.
pub fn is_powered_down(&self) -> bool
Flash.wake
Function · Source
Release the chip from deep power-down and wait until it answers with its JEDEC ID again, at most WAKE_POLLS reads. NoAcknowledge if it never answers with a valid ID (before probing) or Timeout if it never answers with the probed one.
pub fn wake(&mut self) -> void!hal.Error
Flash.reset
Function · Source
Restart the chip with the software reset (66h then 99h) and wait until it answers with its JEDEC ID again, at most RESET_POLLS reads. A program or erase in progress stops, leaving its range undefined. The chip also leaves deep power-down; parts that power up protected are protected again.
pub fn reset(&mut self) -> void!hal.Error
Flash.bus
Function · Source
The bus, for other devices on it between operations.
pub fn bus(&mut self) -> &mut B from(self)
Flash.release
Function · Source
Give back the bus and the chip-select pin.
pub fn release(self) -> (B, P)