Struct spi_flash::Flash

pub struct Flash<'a, A: FlashAccess> { /* private fields */ }

SPI Flash.

This struct provides methods for interacting with common SPI flashes.

Implementations

impl<'a, A: FlashAccess> Flash<'a, A> where
    Error: From<<A as FlashAccess>::Error>, 

pub fn new(access: &'a mut A) -> Self

Create a new Flash instance using the given FlashAccess provider.

pub fn address_bytes(&self) -> u8

Get the number of address bytes which will be used in read and write commands.

pub fn set_address_bytes(&mut self, n: u8)

Set the number of address bytes to use with read and write commands. By default this is set to 3, and can also be autodiscovered using SFDP.

Panics if n is less than 1 or greater than 4.

pub fn capacity(&self) -> Option<usize>

Get the total memory capacity in bytes, if known.

pub fn set_capacity(&mut self, n: usize)

Set the total memory capacity in bytes.

If set, or discovered using SFDP, reads and writes are prevented from going beyond the memory capacity.

pub fn page_size(&self) -> Option<usize>

Get the page program size in bytes.

pub fn set_page_size(&mut self, n: usize)

Set the page program size in bytes.

This must be known before page program operations can be performed.

pub fn erase_size(&self) -> Option<usize>

Get the sector erase size in bytes, if known.

pub fn set_erase_size(&mut self, n: usize)

Set the sector erase size in bytes.

This must be known before sector erase operations can be performed.

pub fn erase_opcode(&self) -> u8

Get the opcode used for the Erase Sector instruction.

pub fn set_erase_opcode(&mut self, opcode: u8)

Set the opcode used for the Erase Sector instruction.

This is 0x20 by default.

pub fn get_id(&self) -> Option<FlashID>

Get the flash ID, if it has already been read.

Call read_id() to read the ID from the flash.

pub fn get_params(&self) -> Option<FlashParams>

Get the flash parameters, if they have already been read.

Call read_params() to read the params from the flash.

pub fn read_id(&mut self) -> Result<FlashID>

Read the device’s manufacturer ID and device IDs.

This method additionally brings the flash out of powerdown and resets it.

self.id is updated with the new ID; use get_id() to retrieve it without re-reading the ID from the flash.

pub fn read_params(&mut self) -> Result<Option<FlashParams>>

Read SFDP JEDEC Basic Flash Parameter table from flash.

Access errors are returned as usual, but if SFDP is not supported (no SFDP signature is detected in the first SFDP DWORD) then Ok(None) is returned instead.

Depending on the version of SFDP supported, some fields may not be available.

Once read, the parameters are available using get_params(), and the parameter values are automatically used for the configuration of address bytes, capacity, page size, sector size, and erase sector opcode. Additionally, larger erase commands described by the SFDP parameters will be used when appropriate.

pub fn read(&mut self, address: u32, length: usize) -> Result<Vec<u8>>

Read length bytes of data from the attached flash, starting at address.

This method uses the FastRead instruction; if it is not supported try using legacy_read() instead.

pub fn legacy_read(&mut self, address: u32, length: usize) -> Result<Vec<u8>>

Read length bytes of data from the attached flash, starting at address.

This method uses the legacy ReadData instruction, which often has a low maximum clock speed compared to other operations, but is more widely supported and may be faster for very short reads as it does not require a dummy byte.

pub fn read_cb<F: Fn(usize)>(
    &mut self,
    address: u32,
    length: usize,
    cb: F
) -> Result<Vec<u8>>

Read length bytes of data from the attached flash, starting at address.

This method is similar to the read() method, except it calls the provided callback function at regular intervals with the number of bytes read so far.

While read() performs a single long SPI exchange, this method performs up to 128 separate SPI exchanges to allow progress to be reported.

pub fn read_progress(&mut self, address: u32, length: usize) -> Result<Vec<u8>>

Read length bytes of data from the attached flash, starting at address.

This method is similar to the read() method, except it renders a progress bar to the terminal during the read.

While read() performs a single long SPI exchange, this method performs up to 128 separate SPI exchanges to allow progress to be reported.

pub fn erase(&mut self) -> Result<()>

Erase entire flash chip.

This method uses the ChipErase instruction, so no progress information is available, but the typical and maximum times taken may be available from the SFDP parameters.

Returns only after erase operation is complete.

pub fn erase_progress(&mut self) -> Result<()>

Erase entire flash chip.

This method is identical to erase(), except it draws a progress bar to the terminal during the erase operation.

If SFDP data indicates a typical chip erase time, that value is used, otherwise the progress bar is drawn as a spinner.

pub fn program(&mut self, address: u32, data: &[u8], verify: bool) -> Result<()>

Program the attached flash with data starting at address.

Sectors and blocks are erased as required for the new data, and existing data outside the new data to write is written back if it has to be erased.

If verify is true, the programmed data is read back, and a ReadbackError will be returned if it did not match what was written.

When available, SFDP parameters are used to generate an efficient sequence of erase instructions. If unavailable, the single erase instruction in erase_opcode is used, and its size of effect must be given in erase_size. If these are not set, a NoEraseInstruction is returned.

The programming page size is set by page_size, which is automatically set when SFDP parameters are read.

pub fn program_progress(
    &mut self,
    address: u32,
    data: &[u8],
    verify: bool
) -> Result<()>

Program the attached flash with data starting at address.

This is identical to program(), except it also draws progress bars to the terminal.

pub fn reset(&mut self) -> Result<()>

Reset the attached flash.

The instruction sequence EnableReset 0x66 followed by Reset 0x99 is sent by default, but if the SFDP parameters indicate that only the 0xF0 instruction is supported for reset, that is sent instead.

pub fn is_protected(&mut self) -> Result<bool>

Check if any block protect bits are set in status register 1.

pub fn protect(&mut self, bp0: bool, bp1: bool, bp2: bool) -> Result<()>

Set block protection bits.

This sets the block protect bits in status register 1, using the non-volatile commands if supported. If available, the SFDP parameters are used to determine the correct non-volatile instruction.

pub fn unprotect(&mut self) -> Result<()>

Clear any protection bits that are set.

This checks and clears the block protect bits in status register 1, using the non-volatile commands if supported. If available, the SFDP parameters are used to determine the correct non-volatile instruction.

pub fn unprotect_wps(&mut self) -> Result<()>

Clear the write-protect-selection bit in status register 3, if set.

This status bit configures the fine-granularity write protection which is a vendor-specific extension that is disabled by default.

Unfortunately it is not possible to determine automatically if a flash chip supports the WPS feature or even has a status register 3, so this command is not called automatically.

pub fn power_down(&mut self) -> Result<()>

Power down the flash.

pub fn release_power_down(&mut self) -> Result<u8>

Power up the flash.

Returns the legacy device ID.

pub fn program_data(&mut self, address: u32, data: &[u8]) -> Result<()>

Program data to address, automatically split into multiple page program operations.

Note that this does not erase the flash beforehand; use program() for a higher-level erase-program-verify interface.

pub fn program_data_progress(&mut self, address: u32, data: &[u8]) -> Result<()>

Program data to address, automatically split into multiple page program operations, and draws a progress bar to the terminal.

Note that this does not erase the flash beforehand; use program() for a higher-level erase-program-verify interface.

pub fn program_data_cb<F: Fn(usize)>(
    &mut self,
    address: u32,
    data: &[u8],
    cb: F
) -> Result<()>

Program data to address, automatically split into multiple page program operations.

Note that this does not erase the flash beforehand; use program() for a higher-level erase-program-verify interface.

Calls cb with the number of bytes programmed so far after each page programming operation.

pub fn write_enable(&mut self) -> Result<()>

Send the WriteEnable command, setting the WEL in the status register.

pub fn page_program(&mut self, address: u32, data: &[u8]) -> Result<()>

Program up to one page of data.

This method sets the write-enable latch and then waits for programming to complete, including sleeping half the typical page program time if known before polling.

Note that this does not erase the flash beforehand; use program() for a higher-level erase-program-verify interface.

pub fn read_jedec_id(&mut self) -> Result<(u8, u8, u16)>

Reads the JEDEC manufacturer and long (16-bit) device IDs.

The manufacturer ID may be prefixed with up to 13 of the continuation code 0x7F; the number of continuation codes is returned as the bank number.

Returns (bank, manufacturer ID, device ID).

pub fn read_device_id(&mut self) -> Result<(u8, u8, u8)>

Reads the JEDEC manufacturer and short (8-bit) device IDs.

The manufacturer ID may be prefixed with up to 13 of the continuation code 0x7F; the number of continuation codes is returned as the bank number.

Returns (bank, manufacturer ID, device ID).

pub fn read_unique_id(&mut self) -> Result<u64>

Read the device’s 64-bit unique ID, if present.

pub fn read_status1(&mut self) -> Result<StatusRegister1>

Read status register 1.

pub fn read_status2(&mut self) -> Result<StatusRegister2>

Read status register 2.

This status register is less widely supported and SFDP does not indicate whether or not it is present.

pub fn read_status3(&mut self) -> Result<StatusRegister3>

Read status register 3.

This status register is less widely supported and SFDP does not indicate whether or not it is present.

pub fn write_status2(&mut self, status2: StatusRegister2) -> Result<()>

Write status register 2.

pub fn write_status3(&mut self, status3: StatusRegister3) -> Result<()>

Write status register 3.

pub fn is_busy(&mut self) -> Result<bool>

Check if the device is currently busy performing an operation.

If the flash parameters indicate support for the Flag Status Register instruction (0x70), it is used, otherwise legacy polling of status register 1 is used.

pub fn wait_while_busy(&mut self) -> Result<()>

Wait until the device stops being busy.

This polls using is_busy(), which uses the flag status register if available or otherwise uses status register 1.

pub fn read_sfdp(&mut self, addr: u32, len: usize) -> Result<Vec<u8>>

Read SFDP register data.

addr is always sent as a 24-bit address, regardless of the address_bytes setting.

pub fn exchange<C: Into<u8>>(
    &mut self,
    command: C,
    data: &[u8],
    nbytes: usize
) -> Result<Vec<u8>>

Writes command and data to the flash memory, then returns nbytes of response.

pub fn write<C: Into<u8>>(&mut self, command: C, data: &[u8]) -> Result<()>

Writes command and data to the flash memory, without reading the response.

pub fn command<C: Into<u8>>(&mut self, command: C) -> Result<()>

Convenience method for issuing a single command and not caring about the returned data