Merge pull request #104 from rust-embedded-community/release/v0.6.0

Release/v0.6.0

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

@@ -2,26 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning].
 
-## [Unreleased](https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.5.0...develop)
+## [Unreleased]
+
+* None
+
+## [Version 0.6.0] - 2023-10-20
 
 ### 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`, `shell`
+- 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
+## [Version 0.5.0] - 2023-05-20
 
-### Changes
+### Changed
 
 - __Breaking Change__: Renamed `Controller` to `VolumeManager`, to better describe what it does.
 - __Breaking Change__: Renamed `SdMmcSpi` to `SdCard`
@@ -39,13 +58,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.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
+## [Version 0.4.0] - 2023-01-18
+
+### Changed
 
-### Changes
-- Optionally use [defmt](https://github.com/knurling-rs/defmt) for logging.
+- Optionally use [defmt] s/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.
@@ -56,35 +76,46 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Add new constructor method `Controller::new_with_limits(block_device: D, timesource: T) -> Controller<D, T, MAX_DIRS, MAX_FILES>`
   to create a `Controller` with custom limits.
 
-## [Version 0.3.0](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.3.0) - 2019-12-16
+## [Version 0.3.0] - 2019-12-16
 
-### Changes
+### Changed
 
-* 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
+## [Version 0.2.1] - 2019-02-19
 
-### Changes
+### Changed
 
-* 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
+## [Version 0.2.0] - 2019-01-24
 
-### Changes
+### Changed
 
-* 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
+## [Version 0.1.0] - 2018-12-23
 
-### Changes
+### Changed
 
-* 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.
+
+[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.6.0...develop
+[Version 0.6.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.6.0...v0.5.0
+[Version 0.5.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.5.0...v0.4.0
+[Version 0.4.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.4.0...v0.3.0
+[Version 0.3.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.3.0...v0.2.1
+[Version 0.2.1]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.2.1...v0.2.0
+[Version 0.2.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.2.0...v0.1.1
+[Version 0.1.1]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.1.1

Cargo.toml

@@ -8,17 +8,21 @@ license = "MIT OR Apache-2.0"
 name = "embedded-sdmmc"
 readme = "README.md"
 repository = "https://github.com/rust-embedded-community/embedded-sdmmc-rs"
-version = "0.5.0"
+version = "0.6.0"
 
 [dependencies]
 byteorder = {version = "1", default-features = false}
 defmt = {version = "0.3", optional = true}
 embedded-hal = "0.2.3"
+heapless = "0.7"
 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
+//
+// ****************************************************************************