Skip to content

Commit

Permalink
Merge pull request #104 from rust-embedded-community/release/v0.6.0
Browse files Browse the repository at this point in the history
Release/v0.6.0
  • Loading branch information
thejpster authored Oct 20, 2023
2 parents e08947f + 2d2c889 commit d362a6a
Show file tree
Hide file tree
Showing 41 changed files with 3,350 additions and 1,815 deletions.
15 changes: 1 addition & 14 deletions .github/workflows/rust.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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

95 changes: 63 additions & 32 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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.
Expand All @@ -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
6 changes: 5 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
19 changes: 9 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
49 changes: 49 additions & 0 deletions examples/append_file.rs
Original file line number Diff line number Diff line change
@@ -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
//
// ****************************************************************************
52 changes: 52 additions & 0 deletions examples/create_file.rs
Original file line number Diff line number Diff line change
@@ -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
//
// ****************************************************************************
Loading

0 comments on commit d362a6a

Please sign in to comment.