Allow using `embedded_storage` implementors with littlefs2 by replacing `Storage` with `NorFlash`

[kleinesfilmroellchen]

embedded_storage seems to be a converging HAL for block/byte-level storage I/O. Just looking at the reverse dependencies gives a good idea of how many HALs and peripheral drives provide an implementation of embedded_storage.

Looking deeper into it, it seems like littlefs2’s storage API is practically identical to embedded_storage::NorFlash (block-sized reads and writes, erase support), which makes a lot of sense given that LittleFS is designed for flash. The only difference are:

• CACHE_SIZE and LOOKAHEAD_SIZE values, which are related to LittleFS itself, rather than the driver. It seems possible to split this out so that the user has to configure this on the LittleFS instance itself (filesystem, not driver). It may create const parameter hell though, I don’t know :)
• The error types are distinct. embedded_storage allows for arbitrary driver errors, while littlefs2 requires a predefined set. Most of the errors are for higher-level FS issues and unrelated to driver operations, so this doesn’t seem like a significant thing to change, given that the FS is already generic over the driver (and therefore theoretically over its error type too).
• On success, functions return the amount of data written/read/erased. embedded_storage forces drivers to always write as much data as requested, which also seems like a reasonable approach for littlefs2 and not like a hassle for driver implementations given that embedded_storage is doing just fine. (This might even reduce the size of that Result type depending on how large the error enum is.)
• capacity is a dynamic value, rather than a static constant (BLOCK_SIZE in combination with BLOCK_COUNT). Looking at the code that passes this to the C library config, it doesn’t seem like this actually needs to be a constant and making the capacity dynamic appears to be trivial. However, the concept of block sizes is still foreign to NorFlash (so probably many real devices), unfortunately. It seems like a reasonable approach to calculate the block size as LCM(READ_SIZE, WRITE_SIZE, ERASE_SIZE), after all, drivers can always choose to fake their sizes to be larger than required by hardware (and e.g. perform multiple data transfers).

Once I have time next week I’ll hack up an adapter struct for plugging any NorFlash implementation into littlefs2::Storage and report back if there’s any other issues. Otherwise, I’d like for Storage to be replaced, as it is simply unnecessarily cumbersome for users on common platforms that already have robust embedded_storage::NorFlash implementations.

[kleinesfilmroellchen]

Upon further inspection of the error type situation (especially error_code_from), it seems like
(a) the result value (usize) is always ignored (converted into the “OK” symbol for the C library), making it wholly superflous
(b) do we really want to allow a driver to return DIR_NOT_EMPTY if it has no knowledge of directories and the operation was not a directory delete? :) it seems like converting all driver errors into IO for the C library is just a better design than what currently exists.

[kleinesfilmroellchen]

So this is what the adapter looks like. Not a lot to do, and not hard to adjust to any NorFlash implementation once you know their read/write sizes.

#![allow(non_camel_case_types)]

use core::marker::PhantomData;

use embedded_storage::nor_flash::NorFlash;
use gcd::binary_usize;
use generic_array::ArrayLength;
use generic_array::typenum::consts;
use littlefs2::driver::Storage;

const fn lcm(a: usize, b: usize) -> usize {
	// lcm(a, b) = (a*b) / gcd(a, b) for all a, b > 0
	a * (b / binary_usize(a, b))
}

/// Bridge type between [`embedded_storage::nor_flash::NorFlash`] and [`littlefs2::driver::Storage`].
///
/// Requires two extra type parameters to make this hack possible:
/// - `SIZE`: size of the file system in bytes. In `NorFlash` this is dynamic, but `Storage` (needlessly) requires it to
///   be a constant. Just make sure to set this to something smaller (or equal) the capacity your flash will report.
/// - `CACHE_SIZE`: Desired cache size, as a [`generic_array::ArrayLength`]. This must be a multiple of all of
///   `READ_SIZE`, `WRITE_SIZE`, `BLOCK_SIZE`. If littlefs2 could use const generic, we could calculate this
///   automatically, but for now you have to choose it so that it matches this.
pub struct EmbeddedStorageDriver<FlashImpl: NorFlash, const SIZE: usize, CACHE_SIZE: ArrayLength<u8>>(
	FlashImpl,
	PhantomData<CACHE_SIZE>,
);

impl<FlashImpl: NorFlash, const SIZE: usize, CACHE_SIZE: ArrayLength<u8>>
	EmbeddedStorageDriver<FlashImpl, SIZE, CACHE_SIZE>
{
	pub fn new(inner: FlashImpl) -> Self {
		Self(inner, PhantomData)
	}
}

impl<FlashImpl: NorFlash, const SIZE: usize, CACHE_SIZE: ArrayLength<u8>> Storage
	for EmbeddedStorageDriver<FlashImpl, SIZE, CACHE_SIZE>
{
	type CACHE_SIZE = CACHE_SIZE;
	// FIXME: arbitrarily chosen, might need tuning
	type LOOKAHEAD_SIZE = consts::U64;

	const BLOCK_COUNT: usize = SIZE / Self::BLOCK_SIZE;
	const BLOCK_CYCLES: isize = 100;
	const BLOCK_SIZE: usize = lcm(lcm(FlashImpl::ERASE_SIZE, FlashImpl::READ_SIZE), FlashImpl::WRITE_SIZE);
	const READ_SIZE: usize = FlashImpl::READ_SIZE;
	const WRITE_SIZE: usize = lcm(FlashImpl::WRITE_SIZE, FlashImpl::ERASE_SIZE);

	fn read(&mut self, off: usize, buf: &mut [u8]) -> littlefs2::io::Result<usize> {
		self.0.read(off as u32, buf).map_or_else(|_| Err(littlefs2::io::Error::IO), |_| Ok(buf.len()))
	}

	fn write(&mut self, off: usize, data: &[u8]) -> littlefs2::io::Result<usize> {
		self.0.write(off as u32, data).map_or_else(|_| Err(littlefs2::io::Error::IO), |_| Ok(data.len()))
	}

	fn erase(&mut self, off: usize, len: usize) -> littlefs2::io::Result<usize> {
		let to = off + len;
		self.0.erase(off as u32, to as u32).map_or_else(|_| Err(littlefs2::io::Error::IO), |_| Ok(len))
	}
}