spi_memory/
lib.rs

1//! An `embedded-hal`-based SPI-Flash chip driver.
2//!
3//! This crate aims to be compatible with common families of SPI flash chips.
4//! Currently, reading 25-series chips is supported, and support for writing and
5//! erasing as well as other chip families (eg. 24-series chips) is planned.
6//! Contributions are always welcome!
7
8#![doc(html_root_url = "https://docs.rs/spi-memory/0.2.0")]
9#![warn(missing_debug_implementations, rust_2018_idioms)]
10#![cfg_attr(not(test), no_std)]
11
12#[macro_use]
13mod log;
14pub mod prelude;
15pub mod series25;
16mod utils;
17
18use core::fmt::{self, Debug};
19use embedded_hal::blocking::spi::Transfer;
20use embedded_hal::digital::v2::OutputPin;
21
22mod private {
23    #[derive(Debug)]
24    pub enum Private {}
25}
26
27/// The error type used by this library.
28///
29/// This can encapsulate an SPI or GPIO error, and adds its own protocol errors
30/// on top of that.
31pub enum Error<SPI: Transfer<u8>, GPIO: OutputPin> {
32    /// An SPI transfer failed.
33    Spi(SPI::Error),
34
35    /// A GPIO could not be set.
36    Gpio(GPIO::Error),
37
38    /// Status register contained unexpected flags.
39    ///
40    /// This can happen when the chip is faulty, incorrectly connected, or the
41    /// driver wasn't constructed or destructed properly (eg. while there is
42    /// still a write in progress).
43    UnexpectedStatus,
44
45    #[doc(hidden)]
46    __NonExhaustive(private::Private),
47}
48
49impl<SPI: Transfer<u8>, GPIO: OutputPin> Debug for Error<SPI, GPIO>
50where
51    SPI::Error: Debug,
52    GPIO::Error: Debug,
53{
54    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
55        match self {
56            Error::Spi(spi) => write!(f, "Error::Spi({:?})", spi),
57            Error::Gpio(gpio) => write!(f, "Error::Gpio({:?})", gpio),
58            Error::UnexpectedStatus => f.write_str("Error::UnexpectedStatus"),
59            Error::__NonExhaustive(_) => unreachable!(),
60        }
61    }
62}
63
64/// A trait for reading operations from a memory chip.
65pub trait Read<Addr, SPI: Transfer<u8>, CS: OutputPin> {
66    /// Reads bytes from a memory chip.
67    ///
68    /// # Parameters
69    /// * `addr`: The address to start reading at.
70    /// * `buf`: The buffer to read `buf.len()` bytes into.
71    fn read(&mut self, addr: Addr, buf: &mut [u8]) -> Result<(), Error<SPI, CS>>;
72}
73
74/// A trait for writing and erasing operations on a memory chip.
75pub trait BlockDevice<Addr, SPI: Transfer<u8>, CS: OutputPin> {
76    /// Erases sectors from the memory chip.
77    ///
78    /// # Parameters
79    /// * `addr`: The address to start erasing at. If the address is not on a sector boundary,
80    ///   the lower bits can be ignored in order to make it fit.
81    fn erase_sectors(&mut self, addr: Addr, amount: usize) -> Result<(), Error<SPI, CS>>;
82
83    /// Erases the memory chip fully.
84    ///
85    /// Warning: Full erase operations can take a significant amount of time.
86    /// Check your device's datasheet for precise numbers.
87    fn erase_all(&mut self) -> Result<(), Error<SPI, CS>>;
88    /// Writes bytes onto the memory chip. This method is supposed to assume that the sectors
89    /// it is writing to have already been erased and should not do any erasing themselves.
90    ///
91    /// # Parameters
92    /// * `addr`: The address to write to.
93    /// * `data`: The bytes to write to `addr`.
94    fn write_bytes(&mut self, addr: Addr, data: &mut [u8]) -> Result<(), Error<SPI, CS>>;
95}
spi_memory/lib.rs

spi_memory/
lib.rs
