Merge pull request #192 from rust-embedded-community/release-v0.9.0

Release v0.9.0

Author: thejpster

.github/workflows/rust.yml

@@ -6,18 +6,28 @@ jobs:
   formatting:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt
     - name: Check formatting
       run: cargo fmt -- --check
 
   build-test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
+        # Always run MSRV too!
+        rust: ["stable", "1.76"]
         features: ['log', 'defmt-log', '""']
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: ${{ matrix.rust }}
     - name: Build
       run: cargo build --no-default-features --features ${{matrix.features}} --verbose
+      env:
+        DEFMT_LOG: debug
     - name: Run Tests
       run: cargo test --no-default-features --features ${{matrix.features}} --verbose

CHANGELOG.md

@@ -6,17 +6,26 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 
 ## [Unreleased]
 
+## [Version 0.9.0] - 2025-06-08
+
 ### Changed
 
-- None
+- __Breaking Change__: `VolumeManager` now uses interior-mutability (with a `RefCell`) and so most methods are now `&self`. This also makes it easier to open multiple `File`, `Directory` or `Volume` objects at once.
+- __Breaking Change__: The `VolumeManager`, `File`, `Directory` and `Volume` no longer implement `Send` or `Sync`.
+- `VolumeManager` uses an interior block cache of 512 bytes, increasing its size by about 520 bytes but hugely reducing stack space required at run-time.
+- __Breaking Change__: The `VolumeManager::device` method now takes a callback rather than giving you a reference to the underlying `BlockDevice`
+- __Breaking Change__: `Error:LockError` variant added.
+- __Breaking Change__: `SearchId` was renamed to `Handle`
+- Fixed writing at block start mid-file (previously overwrote subsequent file data with zeros up to the end of the block)
 
 ### Added
 
-- None
+- `File` now implements the `embedded-io` `Read`, `Write` and `Seek` traits.
+- New `iterate_dir_lfn` method on `VolumeManager` and `Directory` - provides decoded Long File Names as `Option<&str>`
 
 ### Removed
 
-- None
+- __Breaking Change__: Removed the `reason: &str` argument from `BlockDevice`
 
 ## [Version 0.8.2] - 2025-06-07
 
@@ -180,7 +189,8 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 
 [Keep a Changelog]: http://keepachangelog.com/en/1.0.0/
 [Semantic Versioning]: http://semver.org/spec/v2.0.0.html
-[Unreleased]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.8.2...develop
+[Unreleased]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.9.0...develop
+[Version 0.9.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.8.2...v0.9.0
 [Version 0.8.2]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.8.1...v0.8.2
 [Version 0.8.1]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.8.0...v0.8.1
 [Version 0.8.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.7.0...v0.8.0

Cargo.toml

@@ -8,12 +8,16 @@ license = "MIT OR Apache-2.0"
 name = "embedded-sdmmc"
 readme = "README.md"
 repository = "https://github.com/rust-embedded-community/embedded-sdmmc-rs"
-version = "0.8.2"
+version = "0.9.0"
+
+# Make sure to update the CI too!
+rust-version = "1.76"
 
 [dependencies]
 byteorder = {version = "1", default-features = false}
 defmt = {version = "0.3", optional = true}
 embedded-hal = "1.0.0"
+embedded-io = "0.6.1"
 heapless = "^0.8"
 log = {version = "0.4", default-features = false, optional = true}
 

README.md

@@ -11,22 +11,23 @@ designed for readability and simplicity over performance.
 You will need something that implements the `BlockDevice` trait, which can read and write the 512-byte blocks (or sectors) from your card. If you were to implement this over USB Mass Storage, there's no reason this crate couldn't work with a USB Thumb Drive, but we only supply a `BlockDevice` suitable for reading SD and SDHC cards over SPI.
 
 ```rust
+use embedded_sdmmc::{SdCard, VolumeManager, Mode, VolumeIdx};
 // Build an SD Card interface out of an SPI device, a chip-select pin and the delay object
-let sdcard = embedded_sdmmc::SdCard::new(sdmmc_spi, delay);
+let sdcard = SdCard::new(sdmmc_spi, delay);
 // Get the card size (this also triggers card initialisation because it's not been done yet)
 println!("Card size is {} bytes", sdcard.num_bytes()?);
 // Now let's look for volumes (also known as partitions) on our block device.
 // To do this we need a Volume Manager. It will take ownership of the block device.
-let mut volume_mgr = embedded_sdmmc::VolumeManager::new(sdcard, time_source);
+let volume_mgr = VolumeManager::new(sdcard, time_source);
 // Try and access Volume 0 (i.e. the first partition).
 // The volume object holds information about the filesystem on that volume.
-let mut volume0 = volume_mgr.open_volume(embedded_sdmmc::VolumeIdx(0))?;
+let volume0 = volume_mgr.open_volume(VolumeIdx(0))?;
 println!("Volume 0: {:?}", volume0);
 // Open the root directory (mutably borrows from the volume).
-let mut root_dir = volume0.open_root_dir()?;
+let root_dir = volume0.open_root_dir()?;
 // Open a file called "MY_FILE.TXT" in the root directory
 // This mutably borrows the directory.
-let mut my_file = root_dir.open_file_in_dir("MY_FILE.TXT", embedded_sdmmc::Mode::ReadOnly)?;
+let my_file = root_dir.open_file_in_dir("MY_FILE.TXT", Mode::ReadOnly)?;
 // Print the contents of the file, assuming it's in ISO-8859-1 encoding
 while !my_file.is_eof() {
     let mut buffer = [0u8; 32];
@@ -37,13 +38,26 @@ while !my_file.is_eof() {
 }
 ```
 
+For writing files:
+
+```rust
+let my_other_file = root_dir.open_file_in_dir("MY_DATA.CSV", embedded_sdmmc::Mode::ReadWriteCreateOrAppend)?;
+my_other_file.write(b"Timestamp,Signal,Value\n")?;
+my_other_file.write(b"2025-01-01T00:00:00Z,TEMP,25.0\n")?;
+my_other_file.write(b"2025-01-01T00:00:01Z,TEMP,25.1\n")?;
+my_other_file.write(b"2025-01-01T00:00:02Z,TEMP,25.2\n")?;
+
+// Don't forget to flush the file so that the directory entry is updated
+my_other_file.flush()?;
+```
+
 ### Open directories and files
 
 By default the `VolumeManager` will initialize with a maximum number of `4` open directories, files and volumes. This can be customized by specifying the `MAX_DIR`, `MAX_FILES` and `MAX_VOLUMES` generic consts of the `VolumeManager`:
 
 ```rust
 // Create a volume manager with a maximum of 6 open directories, 12 open files, and 4 volumes (or partitions)
-let mut cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(block, time_source);
+let cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(block, time_source);
 ```
 
 ## Supported features

examples/append_file.rs

@@ -5,37 +5,35 @@
 //! $ cargo run --example append_file -- /dev/mmcblk0
 //! ```
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
 //! $ cargo run --example append_file -- ./disk.img
 //! ```
 
-extern crate embedded_sdmmc;
-
 mod linux;
 use linux::*;
 
 const FILE_TO_APPEND: &str = "README.TXT";
 
-use embedded_sdmmc::{Error, Mode, VolumeIdx, VolumeManager};
+use embedded_sdmmc::{Error, Mode, VolumeIdx};
+
+type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
-fn main() -> Result<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());
     let print_blocks = args.find(|x| x == "-v").map(|_| true).unwrap_or(false);
     let lbd = LinuxBlockDevice::new(filename, print_blocks).map_err(Error::DeviceError)?;
-    let mut volume_mgr: VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4> =
-        VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
-    let mut volume = volume_mgr.open_volume(VolumeIdx(0))?;
-    let mut root_dir = volume.open_root_dir()?;
+    let volume_mgr: VolumeManager = VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
+    let volume = volume_mgr.open_volume(VolumeIdx(0))?;
+    let root_dir = volume.open_root_dir()?;
     println!("\nCreating file {}...", FILE_TO_APPEND);
-    let mut f = root_dir.open_file_in_dir(FILE_TO_APPEND, Mode::ReadWriteAppend)?;
+    let f = root_dir.open_file_in_dir(FILE_TO_APPEND, Mode::ReadWriteAppend)?;
     f.write(b"\r\n\r\nThis has been added to your file.\r\n")?;
     Ok(())
 }

examples/big_dir.rs

@@ -1,34 +1,48 @@
-extern crate embedded_sdmmc;
+//! Big Directory Example.
+//!
+//! Attempts to create an infinite number of files in the root directory of the
+//! first volume of the given block device. This is basically to see what
+//! happens when the root directory runs out of space.
+//!
+//! ```bash
+//! $ cargo run --example big_dir -- ./disk.img
+//! $ cargo run --example big_dir -- /dev/mmcblk0
+//! ```
+//!
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
+//!
+//! ```bash
+//! zcat ./tests/disk.img.gz > ./disk.img
+//! $ cargo run --example big_dir -- ./disk.img
+//! ```
 
 mod linux;
 use linux::*;
 
-use embedded_sdmmc::{Error, VolumeManager};
+use embedded_sdmmc::{Error, Mode, VolumeIdx};
 
-fn main() -> Result<(), embedded_sdmmc::Error<std::io::Error>> {
+type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
+
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());
     let print_blocks = args.find(|x| x == "-v").map(|_| true).unwrap_or(false);
     let lbd = LinuxBlockDevice::new(filename, print_blocks).map_err(Error::DeviceError)?;
-    let mut volume_mgr: VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4> =
-        VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
-    let mut volume = volume_mgr
-        .open_volume(embedded_sdmmc::VolumeIdx(1))
-        .unwrap();
+    let volume_mgr: VolumeManager = VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
+    let volume = volume_mgr.open_volume(VolumeIdx(0)).unwrap();
     println!("Volume: {:?}", volume);
-    let mut root_dir = volume.open_root_dir().unwrap();
+    let root_dir = volume.open_root_dir().unwrap();
 
     let mut file_num = 0;
     loop {
         file_num += 1;
         let file_name = format!("{}.da", file_num);
         println!("opening file {file_name} for writing");
-        let mut file = root_dir
-            .open_file_in_dir(
-                file_name.as_str(),
-                embedded_sdmmc::Mode::ReadWriteCreateOrTruncate,
-            )
+        let file = root_dir
+            .open_file_in_dir(file_name.as_str(), Mode::ReadWriteCreateOrTruncate)
             .unwrap();
         let buf = b"hello world, from rust";
         println!("writing to file");

examples/create_file.rs

@@ -5,40 +5,38 @@
 //! $ cargo run --example create_file -- /dev/mmcblk0
 //! ```
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
 //! $ cargo run --example create_file -- ./disk.img
 //! ```
 
-extern crate embedded_sdmmc;
-
 mod linux;
 use linux::*;
 
 const FILE_TO_CREATE: &str = "CREATE.TXT";
 
-use embedded_sdmmc::{Error, Mode, VolumeIdx, VolumeManager};
+use embedded_sdmmc::{Error, Mode, VolumeIdx};
+
+type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
-fn main() -> Result<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());
     let print_blocks = args.find(|x| x == "-v").map(|_| true).unwrap_or(false);
     let lbd = LinuxBlockDevice::new(filename, print_blocks).map_err(Error::DeviceError)?;
-    let mut volume_mgr: VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4> =
-        VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
-    let mut volume = volume_mgr.open_volume(VolumeIdx(0))?;
-    let mut root_dir = volume.open_root_dir()?;
+    let volume_mgr: VolumeManager = VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
+    let volume = volume_mgr.open_volume(VolumeIdx(0))?;
+    let root_dir = volume.open_root_dir()?;
     println!("\nCreating file {}...", FILE_TO_CREATE);
     // This will panic if the file already exists: use ReadWriteCreateOrAppend
     // or ReadWriteCreateOrTruncate instead if you want to modify an existing
     // file.
-    let mut f = root_dir.open_file_in_dir(FILE_TO_CREATE, Mode::ReadWriteCreate)?;
+    let f = root_dir.open_file_in_dir(FILE_TO_CREATE, Mode::ReadWriteCreate)?;
     f.write(b"Hello, this is a new file on disk\r\n")?;
     Ok(())
 }

examples/delete_file.rs

@@ -8,35 +8,33 @@
 //! NOTE: THIS EXAMPLE DELETES A FILE CALLED README.TXT. IF YOU DO NOT WANT THAT
 //! FILE DELETED FROM YOUR DISK IMAGE, DO NOT RUN THIS EXAMPLE.
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
 //! $ cargo run --example delete_file -- ./disk.img
 //! ```
 
-extern crate embedded_sdmmc;
-
 mod linux;
 use linux::*;
 
 const FILE_TO_DELETE: &str = "README.TXT";
 
-use embedded_sdmmc::{Error, VolumeIdx, VolumeManager};
+use embedded_sdmmc::{Error, VolumeIdx};
+
+type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
-fn main() -> Result<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());
     let print_blocks = args.find(|x| x == "-v").map(|_| true).unwrap_or(false);
     let lbd = LinuxBlockDevice::new(filename, print_blocks).map_err(Error::DeviceError)?;
-    let mut volume_mgr: VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4> =
-        VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
-    let mut volume = volume_mgr.open_volume(VolumeIdx(0))?;
-    let mut root_dir = volume.open_root_dir()?;
+    let volume_mgr: VolumeManager = VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
+    let volume = volume_mgr.open_volume(VolumeIdx(0))?;
+    let root_dir = volume.open_root_dir()?;
     println!("Deleting file {}...", FILE_TO_DELETE);
     root_dir.delete_file_in_dir(FILE_TO_DELETE)?;
     println!("Deleted!");

examples/linux/mod.rs

@@ -34,22 +34,14 @@ impl LinuxBlockDevice {
 impl BlockDevice for LinuxBlockDevice {
     type Error = std::io::Error;
 
-    fn read(
-        &self,
-        blocks: &mut [Block],
-        start_block_idx: BlockIdx,
-        reason: &str,
-    ) -> Result<(), Self::Error> {
+    fn read(&self, blocks: &mut [Block], start_block_idx: BlockIdx) -> Result<(), Self::Error> {
         self.file
             .borrow_mut()
             .seek(SeekFrom::Start(start_block_idx.into_bytes()))?;
         for block in blocks.iter_mut() {
             self.file.borrow_mut().read_exact(&mut block.contents)?;
             if self.print_blocks {
-                println!(
-                    "Read block ({}) {:?}: {:?}",
-                    reason, start_block_idx, &block
-                );
+                println!("Read block {:?}: {:?}", start_block_idx, &block);
             }
         }
         Ok(())