Merge pull request #137 from rust-embedded-community/release/v0.8.0

Release/v0.8.0

Author: thejpster

CHANGELOG.md

@@ -6,11 +6,39 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 
 ## [Unreleased]
 
-* None
+### Changed
+
+- None
+
+### Added
+
+- None
+
+### Removed
+
+- None
+
+## [Version 0.8.0] - 2024-07-12
+
+### Changed
+
+- Fixed a bug when seeking backwards through files.
+- Updated to `heapless-0.8` and `embedded-hal-bus-0.2`.
+- No longer panics if the close fails when a `Volume` is dropped - the failure is instead ignored.
+
+### Added
+
+- `File` now has a `flush()` method.
+- `File` now has a `close()` method.
+
+### Removed
+
+- __Breaking Change__: Removed `CS` type-param on `SdCard` - now we use the `SpiDevice` chip-select (closing [#126])
+- __Breaking Change__: Removed the 74 clock cycle 'init' sequence - now applications must do this
 
 ## [Version 0.7.0] - 2024-02-04
 
-## Changed
+### Changed
 
 - __Breaking Change__: `Volume`, `Directory` and `File` are now smart! They hold references to the thing they were made from, and will clean themselves up when dropped. The trade-off is you can can't open multiple volumes, directories or files at the same time.
 - __Breaking Change__: Renamed the old types to `RawVolume`, `RawDirectory` and `RawFile`
@@ -19,18 +47,19 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 - You can now open directories multiple times without error
 - Updated to [embedded-hal] 1.0
 
-## Added
+### Added
 
 - `RawVolume`, `RawDirectory` and `RawFile` types (like the old `Volume`, `Directory` and `File` types)
 - New method `make_dir_in_dir`
 - Empty strings and `"."` convert to `ShortFileName::this_dir()`
 - New API `change_dir` which changes a directory to point to some child directory (or the parent) without opening a new directory.
 - Updated 'shell' example to support `mkdir`, `tree` and relative/absolute paths
 
-## Removed
+### Removed
 
-* None
+- None
 
+[#126]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/126
 [#74]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/74
 [embedded-hal]: https://crates.io/crates/embedded-hal
 
@@ -126,7 +155,7 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 
 - Reduce delay waiting for response. Big speed improvements.
 
-## [Version 0.1.0] - 2018-12-23
+## [Version 0.1.1] - 2018-12-23
 
 ### Changed
 
@@ -137,7 +166,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.7.0...develop
+[Unreleased]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.8.0...develop
+[Version 0.8.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.8.0...v0.7.0
 [Version 0.7.0]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.7.0...v0.6.0
 [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

Cargo.toml

@@ -8,18 +8,18 @@ license = "MIT OR Apache-2.0"
 name = "embedded-sdmmc"
 readme = "README.md"
 repository = "https://github.com/rust-embedded-community/embedded-sdmmc-rs"
-version = "0.7.0"
+version = "0.8.0"
 
 [dependencies]
 byteorder = {version = "1", default-features = false}
 defmt = {version = "0.3", optional = true}
 embedded-hal = "1.0.0"
-heapless = "0.7"
+heapless = "^0.8"
 log = {version = "0.4", default-features = false, optional = true}
 
 [dev-dependencies]
 chrono = "0.4"
-embedded-hal-bus = "0.1.0"
+embedded-hal-bus = "0.2.0"
 env_logger = "0.10.0"
 flate2 = "1.0"
 hex-literal = "0.4.1"

LICENSE-MIT

@@ -1,4 +1,5 @@
-Copyright (c) 2018-2023 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers
+Copyright (c) 2018-2024 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers
+Copyright (c) 2011-2018 Bill Greiman
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

NOTICE

@@ -0,0 +1,6 @@
+# Copyright Notices
+
+This is a copyright notices file, as described by the Apache-2.0 license.
+
+Copyright (c) 2018-2024 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers
+Copyright (c) 2011-2018 Bill Greiman

README.md

@@ -12,7 +12,7 @@ You will need something that implements the `BlockDevice` trait, which can read
 
 ```rust
 // 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, sdmmc_cs, delay);
+let sdcard = embedded_sdmmc::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.
@@ -27,7 +27,7 @@ let mut 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)?;
-// Print the contents of the file
+// Print the contents of the file, assuming it's in ISO-8859-1 encoding
 while !my_file.is_eof() {
     let mut buffer = [0u8; 32];
     let num_read = my_file.read(&mut buffer)?;
@@ -59,10 +59,12 @@ let mut cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(blo
 * Log over defmt or the common log interface (feature flags).
 
 ## No-std usage
+
 This repository houses no examples for no-std usage, however you can check out the following examples:
-- [Pi Pico](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/rp-pico/examples/pico_spi_sd_card.rs)
-- [STM32H7XX](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sdmmc_fat.rs)
-- [atsamd(pygamer)](https://github.com/atsamd-rs/atsamd/blob/master/boards/pygamer/examples/sd_card.rs)
+
+* [Pi Pico](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/rp-pico/examples/pico_spi_sd_card.rs)
+* [STM32H7XX](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sdmmc_fat.rs)
+* [atsamd(pygamer)](https://github.com/atsamd-rs/atsamd/blob/master/boards/pygamer/examples/sd_card.rs)
 
 ## Todo List (PRs welcome!)
 
@@ -79,12 +81,14 @@ The changelog has moved to [CHANGELOG.md](/CHANGELOG.md)
 Licensed under either of
 
 - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
-  http://www.apache.org/licenses/LICENSE-2.0)
+  <http://www.apache.org/licenses/LICENSE-2.0>)
 
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
 
 at your option.
 
+Copyright notices are stored in the [NOTICE](./NOTICE) file.
+
 ## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally

examples/readme_test.rs

@@ -3,9 +3,27 @@
 //! We add enough stuff to make it compile, but it won't run because our fake
 //! SPI doesn't do any replies.
 
+#![allow(dead_code)]
+
 use core::cell::RefCell;
 
-use embedded_sdmmc::sdcard::DummyCsPin;
+pub struct DummyCsPin;
+
+impl embedded_hal::digital::ErrorType for DummyCsPin {
+    type Error = core::convert::Infallible;
+}
+
+impl embedded_hal::digital::OutputPin for DummyCsPin {
+    #[inline(always)]
+    fn set_low(&mut self) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    #[inline(always)]
+    fn set_high(&mut self) -> Result<(), Self::Error> {
+        Ok(())
+    }
+}
 
 struct FakeSpiBus();
 
@@ -97,13 +115,12 @@ fn main() -> Result<(), Error> {
     // BEGIN Fake stuff that will be replaced with real peripherals
     let spi_bus = RefCell::new(FakeSpiBus());
     let delay = FakeDelayer();
-    let sdmmc_spi = embedded_hal_bus::spi::RefCellDevice::new(&spi_bus, DummyCsPin, delay);
-    let sdmmc_cs = FakeCs();
+    let sdmmc_spi = embedded_hal_bus::spi::RefCellDevice::new(&spi_bus, DummyCsPin, delay).unwrap();
     let time_source = FakeTimesource();
     // END Fake stuff that will be replaced with real peripherals
 
     // 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, sdmmc_cs, delay);
+    let sdcard = embedded_sdmmc::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.
@@ -118,7 +135,7 @@ fn main() -> Result<(), Error> {
     // 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)?;
-    // Print the contents of the file
+    // Print the contents of the file, assuming it's in ISO-8859-1 encoding
     while !my_file.is_eof() {
         let mut buffer = [0u8; 32];
         let num_read = my_file.read(&mut buffer)?;

src/blockdevice.rs

@@ -1,11 +1,12 @@
-//! Block Device support
+//! Traits and types for working with Block Devices.
 //!
 //! Generic code for handling block devices, such as types for identifying
 //! a particular block on a block device by its index.
 
-/// Represents a standard 512 byte block (also known as a sector). IBM PC
-/// formatted 5.25" and 3.5" floppy disks, SD/MMC cards up to 1 GiB in size
-/// and IDE/SATA Hard Drives up to about 2 TiB all have 512 byte blocks.
+/// A standard 512 byte block (also known as a sector).
+///
+/// IBM PC formatted 5.25" and 3.5" floppy disks, IDE/SATA Hard Drives up to
+/// about 2 TiB, and almost all SD/MMC cards have 512 byte blocks.
 ///
 /// This library does not support devices with a block size other than 512
 /// bytes.
@@ -15,15 +16,17 @@ pub struct Block {
     pub contents: [u8; Block::LEN],
 }
 
-/// Represents the linear numeric address of a block (or sector). The first
-/// block on a disk gets `BlockIdx(0)` (which usually contains the Master Boot
-/// Record).
+/// The linear numeric address of a block (or sector).
+///
+/// The first block on a disk gets `BlockIdx(0)` (which usually contains the
+/// Master Boot Record).
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct BlockIdx(pub u32);
 
-/// Represents the a number of blocks (or sectors). Add this to a `BlockIdx`
-/// to get an actual address on disk.
+/// The a number of blocks (or sectors).
+///
+/// Add this to a `BlockIdx` to get an actual address on disk.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct BlockCount(pub u32);
@@ -34,7 +37,7 @@ pub struct BlockIter {
     current: BlockIdx,
 }
 
-/// Represents a block device - a device which can read and write blocks (or
+/// A block device - a device which can read and write blocks (or
 /// sectors). Only supports devices which are <= 2 TiB in size.
 pub trait BlockDevice {
     /// The errors that the `BlockDevice` can return. Must be debug formattable.

src/fat/bpb.rs

@@ -6,9 +6,10 @@ use crate::{
 };
 use byteorder::{ByteOrder, LittleEndian};
 
-/// Represents a Boot Parameter Block. This is the first sector of a FAT
-/// formatted partition, and it describes various properties of the FAT
-/// filesystem.
+/// A Boot Parameter Block.
+///
+/// This is the first sector of a FAT formatted partition, and it describes
+/// various properties of the FAT filesystem.
 pub struct Bpb<'a> {
     data: &'a [u8; 512],
     pub(crate) fat_type: FatType,

src/fat/ondiskdirentry.rs

@@ -3,7 +3,10 @@
 use crate::{fat::FatType, Attributes, BlockIdx, ClusterId, DirEntry, ShortFileName, Timestamp};
 use byteorder::{ByteOrder, LittleEndian};
 
-/// Represents a 32-byte directory entry as stored on-disk in a directory file.
+/// A 32-byte directory entry as stored on-disk in a directory file.
+///
+/// This is the same for FAT16 and FAT32 (except FAT16 doesn't use
+/// first_cluster_hi).
 pub struct OnDiskDirEntry<'a> {
     data: &'a [u8],
 }
@@ -38,8 +41,6 @@ impl<'a> core::fmt::Debug for OnDiskDirEntry<'a> {
     }
 }
 
-/// Represents the 32 byte directory entry. This is the same for FAT16 and
-/// FAT32 (except FAT16 doesn't use first_cluster_hi).
 impl<'a> OnDiskDirEntry<'a> {
     pub(crate) const LEN: usize = 32;
     pub(crate) const LEN_U32: u32 = 32;