API referencestd/embedded

std/embedded/flash/spi_nor

Public declarations, types, methods, and source contracts for std/embedded/flash/spi_nor.

On this page

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 probe or set_capacity. Most programs call new instead.

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_id reports 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.len bytes of the chip’s SFDP data from address into buffer, 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 bytes as 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 polls status 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)

Search every guide, reference page, and API declaration.