Merge pull request #95 from rust-embedded-community/jgp-fixes

Cleaning up some comments, and fixing the close file bug.

Author: thejpster

.github/workflows/rust.yml

@@ -19,18 +19,5 @@ jobs:
     - uses: actions/checkout@v1
     - name: Build
       run: cargo build --no-default-features --features ${{matrix.features}} --verbose
-    - name: Unpack Disk
-      run: gunzip -fk disk.img.gz
-    - name: Run Test Mount example
-      run: cargo run --no-default-features --features ${{matrix.features}} --example test_mount ./disk.img
-    - name: Unpack Disk
-      run: gunzip -fk disk.img.gz
-    - name: Run Create Test example
-      run: cargo run --no-default-features --features ${{matrix.features}} --example create_test ./disk.img
-    - name: Unpack Disk
-      run: gunzip -fk disk.img.gz
-    - name: Run Write Test example
-      run: cargo run --no-default-features --features ${{matrix.features}} --example write_test ./disk.img
-    - name: Run Unit Tests
+    - name: Run Tests
       run: cargo test --no-default-features --features ${{matrix.features}} --verbose
-

CHANGELOG.md

@@ -9,19 +9,35 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Changed
 
-- None
+- Writing to a file no longer flushes file metadata to the Directory Entry.
+  Instead closing a file now flushes file metadata to the Directory Entry.
+  Requires mutable access to the Volume ([#94]).
+- Files now have the correct length when modified, not appended ([#72]).
+- Calling `SdCard::get_card_type` will now perform card initialisation ([#87] and [#90]).
+- Removed warning about unused arguments.
+- Types are now documented at the top level ([#86]).
+- Renamed `Cluster` to `ClusterId` and stopped you adding two together
+
+[#72]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/72
+[#86]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/86
+[#87]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/87
+[#90]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/90
+[#94]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/94
 
 ### Added
 
-- None
+- New examples, `append_file`, `create_file`, `delete_file`, `list_dir`
+- New test cases `tests/directories.rs`, `tests/read_file.rs`
 
 ### Removed
 
-- None
+- __Breaking Change__: `Controller` alias for `VolumeManager` removed.
+- __Breaking Change__: `VolumeManager::open_dir_entry` removed, as it was unsafe to the user to randomly pick a starting cluster.
+- Old examples `create_test`, `test_mount`, `write_test`, `delete_test`
 
 ## [Version 0.5.0](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.5.0) - 2023-05-20
 
-### Changes
+### Changes in v0.5.0
 
 - __Breaking Change__: Renamed `Controller` to `VolumeManager`, to better describe what it does.
 - __Breaking Change__: Renamed `SdMmcSpi` to `SdCard`
@@ -31,21 +47,22 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - More robust card intialisation procedure, with added retries
 - Supports building with neither `defmt` nor `log` logging
 
-### Added
+### Added in v0.5.0
 
 - Added `mark_card_as_init` method, if you know the card is initialised and want to skip the initialisation step
 
-### Removed
+### Removed in v0.5.0
 
 - __Breaking Change__: Removed `BlockSpi` type - card initialisation now handled as an internal state variable
 
 ## [Version 0.4.0](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.4.0) - 2023-01-18
 
-### Changes
+### Changes in v0.4.0
+
 - Optionally use [defmt](https://github.com/knurling-rs/defmt) for logging.
     Controlled by `defmt-log` feature flag.
 - __Breaking Change__: Use SPI blocking traits instead to ease SPI peripheral sharing.
-  See: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/28
+  See: <https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/28>
 - Added `Controller::has_open_handles` and `Controller::free` methods.
 - __Breaking Change__: Changed interface to enforce correct SD state at compile time.
 - __Breaking Change__: Added custom error type for `File` operations.
@@ -58,33 +75,33 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Version 0.3.0](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.3.0) - 2019-12-16
 
-### Changes
+### Changes in v0.3.0
 
-* Updated to `v2` embedded-hal traits.
-* Added open support for all modes.
-* Added write support for files.
-* Added `Info_Sector` tracking for FAT32.
-* Change directory iteration to look in all the directory's clusters.
-* Added `write_test` and `create_test`.
-* De-duplicated FAT16 and FAT32 code (https://github.com/thejpster/embedded-sdmmc-rs/issues/10)
+- Updated to `v2` embedded-hal traits.
+- Added open support for all modes.
+- Added write support for files.
+- Added `Info_Sector` tracking for FAT32.
+- Change directory iteration to look in all the directory's clusters.
+- Added `write_test` and `create_test`.
+- De-duplicated FAT16 and FAT32 code (<https://github.com/thejpster/embedded-sdmmc-rs/issues/10>)
 
 ## [Version 0.2.1](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.2.1) - 2019-02-19
 
-### Changes
+### Changes in v0.2.1
 
-* Added `readme=README.md` to `Cargo.toml`
+- Added `readme=README.md` to `Cargo.toml`
 
 ## [Version 0.2.0](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.2.0) - 2019-01-24
 
-### Changes
+### Changes in v0.2.0
 
-* Reduce delay waiting for response. Big speed improvements.
+- Reduce delay waiting for response. Big speed improvements.
 
 ## [Version 0.1.0](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.1.1) - 2018-12-23
 
-### Changes
+### Changes in v0.1.0
 
-* Can read blocks from an SD Card using an `embedded_hal::SPI` device and a
+- Can read blocks from an SD Card using an `embedded_hal::SPI` device and a
   `embedded_hal::OutputPin` for Chip Select.
-* Can read partition tables and open a FAT32 or FAT16 formatted partition.
-* Can open and iterate the root directory of a FAT16 formatted partition.
+- Can read partition tables and open a FAT32 or FAT16 formatted partition.
+- Can open and iterate the root directory of a FAT16 formatted partition.

Cargo.toml

@@ -20,6 +20,9 @@ log = {version = "0.4", default-features = false, optional = true}
 [dev-dependencies]
 env_logger = "0.9"
 hex-literal = "0.3"
+flate2 = "1.0"
+sha256 = "1.4"
+chrono = "0.4"
 
 [features]
 default = ["log"]

README.md

@@ -23,36 +23,35 @@ let mut volume_mgr = embedded_sdmmc::VolumeManager::new(sdcard, time_source);
 // It doesn't hold a reference to the Volume Manager and so must be passed back
 // to every Volume Manager API call. This makes it easier to handle multiple
 // volumes in parallel.
-let mut volume0 = volume_mgr.get_volume(embedded_sdmmc::VolumeIdx(0))?;
+let volume0 = volume_mgr.get_volume(embedded_sdmmc::VolumeIdx(0))?;
 println!("Volume 0: {:?}", volume0);
 // Open the root directory (passing in the volume we're using).
 let root_dir = volume_mgr.open_root_dir(&volume0)?;
 // Open a file called "MY_FILE.TXT" in the root directory
-let mut my_file = volume_mgr.open_file_in_dir(
-    &mut volume0,
-    &root_dir,
+let my_file = volume_mgr.open_file_in_dir(
+    root_dir,
     "MY_FILE.TXT",
     embedded_sdmmc::Mode::ReadOnly,
 )?;
 // Print the contents of the file
-while !my_file.eof() {
+while !volume_manager.file_eof(my_file).unwrap() {
     let mut buffer = [0u8; 32];
     let num_read = volume_mgr.read(&volume0, &mut my_file, &mut buffer)?;
     for b in &buffer[0..num_read] {
         print!("{}", *b as char);
     }
 }
-volume_mgr.close_file(&volume0, my_file)?;
-volume_mgr.close_dir(&volume0, root_dir);
+volume_mgr.close_file(my_file)?;
+volume_mgr.close_dir(root_dir)?;
 ```
 
 ### Open directories and files
 
-By default the `VolumeManager` will initialize with a maximum number of `4` open directories and files. This can be customized by specifying the `MAX_DIR` and `MAX_FILES` generic consts of the `VolumeManager`:
+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 and 12 open files
-let mut cont: VolumeManager<_, _, 6, 12> = VolumeManager::new_with_limits(block, time_source);
+// 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);
 ```
 
 ## Supported features

examples/append_file.rs

@@ -0,0 +1,49 @@
+//! Append File Example.
+//!
+//! ```bash
+//! $ cargo run --example append_file -- ./disk.img
+//! $ 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.
+//!
+//! ```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};
+
+fn main() -> Result<(), embedded_sdmmc::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 volume = volume_mgr.open_volume(VolumeIdx(0))?;
+    let root_dir = volume_mgr.open_root_dir(volume)?;
+    println!("\nCreating file {}...", FILE_TO_APPEND);
+    let f = volume_mgr.open_file_in_dir(root_dir, FILE_TO_APPEND, Mode::ReadWriteAppend)?;
+    volume_mgr.write(f, b"\r\n\r\nThis has been added to your file.\r\n")?;
+    volume_mgr.close_file(f)?;
+    volume_mgr.close_dir(root_dir)?;
+    Ok(())
+}
+
+// ****************************************************************************
+//
+// End Of File
+//
+// ****************************************************************************

examples/create_file.rs

@@ -0,0 +1,52 @@
+//! Create File Example.
+//!
+//! ```bash
+//! $ cargo run --example create_file -- ./disk.img
+//! $ 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.
+//!
+//! ```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};
+
+fn main() -> Result<(), embedded_sdmmc::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 volume = volume_mgr.open_volume(VolumeIdx(0))?;
+    let root_dir = volume_mgr.open_root_dir(volume)?;
+    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 f = volume_mgr.open_file_in_dir(root_dir, FILE_TO_CREATE, Mode::ReadWriteCreate)?;
+    volume_mgr.write(f, b"Hello, this is a new file on disk\r\n")?;
+    volume_mgr.close_file(f)?;
+    volume_mgr.close_dir(root_dir)?;
+    Ok(())
+}
+
+// ****************************************************************************
+//
+// End Of File
+//
+// ****************************************************************************