Merge pull request #21 from ia0/error

Nest ReadNorFlash::Error in a new NorFlashError

Author: MathiasKoch

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+- Require Nor flashes error types to be convertible to generic errors.
+- Provide helper functions for Nor flashes to check for generic errors.
+
 ## [0.2.0] - 2021-09-15
 
 - Removed `try_` prefix from all trait methods.

src/nor_flash.rs

@@ -1,24 +1,83 @@
 use crate::{iter::IterableByOverlaps, ReadStorage, Region, Storage};
 
+/// NOR flash errors.
+///
+/// NOR flash implementations must use an error type implementing this trait. This permits generic
+/// code to extract a generic error kind.
+pub trait NorFlashError: core::fmt::Debug {
+	/// Convert a specific NOR flash error into a generic error kind.
+	fn kind(&self) -> NorFlashErrorKind;
+}
+
+impl NorFlashError for core::convert::Infallible {
+	fn kind(&self) -> NorFlashErrorKind {
+		match *self {}
+	}
+}
+
+/// NOR flash error kinds.
+///
+/// NOR flash implementations must map their error to those generic error kinds through the
+/// [`NorFlashError`] trait.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
+#[non_exhaustive]
+pub enum NorFlashErrorKind {
+	/// The arguments are not properly aligned.
+	NotAligned,
+
+	/// The arguments are out of bounds.
+	OutOfBounds,
+
+	/// Error specific to the implementation.
+	Other,
+}
+
+impl NorFlashError for NorFlashErrorKind {
+	fn kind(&self) -> NorFlashErrorKind {
+		*self
+	}
+}
+
+impl core::fmt::Display for NorFlashErrorKind {
+	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+		match self {
+			Self::NotAligned => write!(f, "Arguments are not properly aligned"),
+			Self::OutOfBounds => write!(f, "Arguments are out of bounds"),
+			Self::Other => write!(f, "An implementation specific error occurred"),
+		}
+	}
+}
+
 /// Read only NOR flash trait.
 pub trait ReadNorFlash {
-	/// An enumeration of storage errors
-	type Error;
+	/// Errors returned by this NOR flash.
+	type Error: NorFlashError;
 
 	/// The minumum number of bytes the storage peripheral can read
 	const READ_SIZE: usize;
 
 	/// Read a slice of data from the storage peripheral, starting the read
 	/// operation at the given address offset, and reading `bytes.len()` bytes.
 	///
-	/// This should throw an error in case `bytes.len()` will be larger than
-	/// the peripheral end address.
+	/// # Errors
+	///
+	/// Returns an error if the arguments are not aligned or out of bounds. The implementation
+	/// can use the [`check_read`] helper function.
 	fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error>;
 
 	/// The capacity of the peripheral in bytes.
 	fn capacity(&self) -> usize;
 }
 
+/// Return whether a read operation is within bounds.
+pub fn check_read<T: ReadNorFlash>(
+	flash: &T,
+	offset: u32,
+	length: usize,
+) -> Result<(), NorFlashErrorKind> {
+	check_slice(flash, T::READ_SIZE, offset, length)
+}
+
 /// NOR flash trait.
 pub trait NorFlash: ReadNorFlash {
 	/// The minumum number of bytes the storage peripheral can write
@@ -30,19 +89,63 @@ pub trait NorFlash: ReadNorFlash {
 	/// Erase the given storage range, clearing all data within `[from..to]`.
 	/// The given range will contain all 1s afterwards.
 	///
-	/// This should return an error if the range is not aligned to a proper
-	/// erase resolution
 	/// If power is lost during erase, contents of the page are undefined.
-	/// `from` and `to` must both be multiples of `ERASE_SIZE` and `from` <= `to`.
+	///
+	/// # Errors
+	///
+	/// Returns an error if the arguments are not aligned or out of bounds (the case where `to >
+	/// from` is considered out of bounds). The implementation can use the [`check_erase`]
+	/// helper function.
 	fn erase(&mut self, from: u32, to: u32) -> Result<(), Self::Error>;
 
 	/// If power is lost during write, the contents of the written words are undefined,
 	/// but the rest of the page is guaranteed to be unchanged.
 	/// It is not allowed to write to the same word twice.
-	/// `offset` and `bytes.len()` must both be multiples of `WRITE_SIZE`.
+	///
+	/// # Errors
+	///
+	/// Returns an error if the arguments are not aligned or out of bounds. The implementation
+	/// can use the [`check_write`] helper function.
 	fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error>;
 }
 
+/// Return whether an erase operation is aligned and within bounds.
+pub fn check_erase<T: NorFlash>(flash: &T, from: u32, to: u32) -> Result<(), NorFlashErrorKind> {
+	let (from, to) = (from as usize, to as usize);
+	if from > to || to > flash.capacity() {
+		return Err(NorFlashErrorKind::OutOfBounds);
+	}
+	if from % T::ERASE_SIZE != 0 || to % T::ERASE_SIZE != 0 {
+		return Err(NorFlashErrorKind::NotAligned);
+	}
+	Ok(())
+}
+
+/// Return whether a write operation is aligned and within bounds.
+pub fn check_write<T: NorFlash>(
+	flash: &T,
+	offset: u32,
+	length: usize,
+) -> Result<(), NorFlashErrorKind> {
+	check_slice(flash, T::WRITE_SIZE, offset, length)
+}
+
+fn check_slice<T: ReadNorFlash>(
+	flash: &T,
+	align: usize,
+	offset: u32,
+	length: usize,
+) -> Result<(), NorFlashErrorKind> {
+	let offset = offset as usize;
+	if length > flash.capacity() || offset > flash.capacity() - length {
+		return Err(NorFlashErrorKind::OutOfBounds);
+	}
+	if offset % align != 0 || length % align != 0 {
+		return Err(NorFlashErrorKind::NotAligned);
+	}
+	Ok(())
+}
+
 /// Marker trait for NorFlash relaxing the restrictions on `write`.
 ///
 /// Writes to the same word twice are now allowed. The result is the logical AND of the