Rename Controller to VolumeManager.

Better reflects what it actually does.

Author: jonathanpallant

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 [Unreleased]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/compare/v0.4.0...develop
 
+- Renamed `Controller` to `VolumeManager`, to better describe what it does.
+
 ## [Version 0.4.0](https://github.com/rust-embedded-community/embedded-sdmmc-rs/releases/tag/v0.4.0)
 
 ### Changes

README.md

@@ -11,11 +11,15 @@ 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
+// Build an SD Card interface out of an SPI device
 let mut spi_dev = embedded_sdmmc::SdMmcSpi::new(sdmmc_spi, sdmmc_cs);
+// Try and initialise the SD card
 write!(uart, "Init SD card...").unwrap();
 match spi_dev.acquire() {
     Ok(block) => {
-        let mut cont = embedded_sdmmc::Controller::new(block, time_source);
+        // The SD Card initialised, and we have a `BlockSpi` object representing
+        // the initialised card. Now let's 
+        let mut cont = embedded_sdmmc::VolumeManager::new(block, time_source);
         write!(uart, "OK!\nCard size...").unwrap();
         match cont.device().card_size_bytes() {
             Ok(size) => writeln!(uart, "{}", size).unwrap(),
@@ -33,16 +37,16 @@ match spi_dev.acquire() {
 
 ### Open directories and files
 
-By default the `Controller` 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 `Controller`:
+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`:
 
 ```rust
-// Create a controller with a maximum of 6 open directories and 12 open files
-let mut cont: Controller<
+// Create a volume manager with a maximum of 6 open directories and 12 open files
+let mut cont: VolumeManager<
     embedded_sdmmc::BlockSpi<DummySpi, DummyCsPin>,
     DummyTimeSource,
     6,
     12,
-> = Controller::new_with_limits(block, time_source);
+> = VolumeManager::new_with_limits(block, time_source);
 ```
 
 ## Supported features

examples/create_test.rs

@@ -19,8 +19,8 @@ extern crate embedded_sdmmc;
 const FILE_TO_CREATE: &'static str = "CREATE.TXT";
 
 use embedded_sdmmc::{
-    Block, BlockCount, BlockDevice, BlockIdx, Controller, Error, Mode, TimeSource, Timestamp,
-    VolumeIdx,
+    Block, BlockCount, BlockDevice, BlockIdx, Error, Mode, TimeSource, Timestamp, VolumeIdx,
+    VolumeManager,
 };
 use std::cell::RefCell;
 use std::fs::{File, OpenOptions};
@@ -118,22 +118,22 @@ fn main() {
         .map_err(Error::DeviceError)
         .unwrap();
     println!("lbd: {:?}", lbd);
-    let mut controller = Controller::new(lbd, Clock);
+    let mut volume_mgr = VolumeManager::new(lbd, Clock);
     for volume_idx in 0..=3 {
-        let volume = controller.get_volume(VolumeIdx(volume_idx));
+        let volume = volume_mgr.get_volume(VolumeIdx(volume_idx));
         println!("volume {}: {:#?}", volume_idx, volume);
         if let Ok(mut volume) = volume {
-            let root_dir = controller.open_root_dir(&volume).unwrap();
+            let root_dir = volume_mgr.open_root_dir(&volume).unwrap();
             println!("\tListing root directory:");
-            controller
+            volume_mgr
                 .iterate_dir(&volume, &root_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
                 .unwrap();
             println!("\nCreating file {}...", FILE_TO_CREATE);
             // This will panic if the file already exists, use ReadWriteCreateOrAppend or
             // ReadWriteCreateOrTruncate instead
-            let mut f = controller
+            let mut f = volume_mgr
                 .open_file_in_dir(
                     &mut volume,
                     &root_dir,
@@ -145,7 +145,7 @@ fn main() {
             println!("FILE STARTS:");
             while !f.eof() {
                 let mut buffer = [0u8; 32];
-                let num_read = controller.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     if *b == 10 {
                         print!("\\n");
@@ -164,12 +164,12 @@ fn main() {
                 buffer.push(b'\n');
             }
             println!("\nAppending to file");
-            let num_written1 = controller.write(&mut volume, &mut f, &buffer1[..]).unwrap();
-            let num_written = controller.write(&mut volume, &mut f, &buffer[..]).unwrap();
+            let num_written1 = volume_mgr.write(&mut volume, &mut f, &buffer1[..]).unwrap();
+            let num_written = volume_mgr.write(&mut volume, &mut f, &buffer[..]).unwrap();
             println!("Number of bytes written: {}\n", num_written + num_written1);
-            controller.close_file(&volume, f).unwrap();
+            volume_mgr.close_file(&volume, f).unwrap();
 
-            let mut f = controller
+            let mut f = volume_mgr
                 .open_file_in_dir(
                     &mut volume,
                     &root_dir,
@@ -183,13 +183,13 @@ fn main() {
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_CREATE,
-                controller.find_directory_entry(&volume, &root_dir, FILE_TO_CREATE)
+                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_CREATE)
             );
             println!("\nReading from file");
             println!("FILE STARTS:");
             while !f.eof() {
                 let mut buffer = [0u8; 32];
-                let num_read = controller.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     if *b == 10 {
                         print!("\\n");
@@ -198,7 +198,7 @@ fn main() {
                 }
             }
             println!("EOF");
-            controller.close_file(&volume, f).unwrap();
+            volume_mgr.close_file(&volume, f).unwrap();
         }
     }
 }

examples/delete_test.rs

@@ -19,8 +19,8 @@ extern crate embedded_sdmmc;
 const FILE_TO_DELETE: &'static str = "DELETE.TXT";
 
 use embedded_sdmmc::{
-    Block, BlockCount, BlockDevice, BlockIdx, Controller, Error, Mode, TimeSource, Timestamp,
-    VolumeIdx,
+    Block, BlockCount, BlockDevice, BlockIdx, Error, Mode, TimeSource, Timestamp, VolumeIdx,
+    VolumeManager,
 };
 use std::cell::RefCell;
 use std::fs::{File, OpenOptions};
@@ -118,22 +118,22 @@ fn main() {
         .map_err(Error::DeviceError)
         .unwrap();
     println!("lbd: {:?}", lbd);
-    let mut controller = Controller::new(lbd, Clock);
+    let mut volume_mgr = VolumeManager::new(lbd, Clock);
     for volume_idx in 0..=3 {
-        let volume = controller.get_volume(VolumeIdx(volume_idx));
+        let volume = volume_mgr.get_volume(VolumeIdx(volume_idx));
         println!("volume {}: {:#?}", volume_idx, volume);
         if let Ok(mut volume) = volume {
-            let root_dir = controller.open_root_dir(&volume).unwrap();
+            let root_dir = volume_mgr.open_root_dir(&volume).unwrap();
             println!("\tListing root directory:");
-            controller
+            volume_mgr
                 .iterate_dir(&volume, &root_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
                 .unwrap();
             println!("\nCreating file {}...", FILE_TO_DELETE);
             // This will panic if the file already exists, use ReadWriteCreateOrAppend or
             // ReadWriteCreateOrTruncate instead
-            let f = controller
+            let f = volume_mgr
                 .open_file_in_dir(
                     &mut volume,
                     &root_dir,
@@ -146,25 +146,25 @@ fn main() {
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_DELETE,
-                controller.find_directory_entry(&volume, &root_dir, FILE_TO_DELETE)
+                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_DELETE)
             );
 
-            match controller.delete_file_in_dir(&volume, &root_dir, FILE_TO_DELETE) {
+            match volume_mgr.delete_file_in_dir(&volume, &root_dir, FILE_TO_DELETE) {
                 Ok(()) => (),
                 Err(error) => println!("\tCannot delete file: {:?}", error),
             }
             println!("\tClosing {}...", FILE_TO_DELETE);
-            controller.close_file(&volume, f).unwrap();
+            volume_mgr.close_file(&volume, f).unwrap();
 
-            match controller.delete_file_in_dir(&volume, &root_dir, FILE_TO_DELETE) {
+            match volume_mgr.delete_file_in_dir(&volume, &root_dir, FILE_TO_DELETE) {
                 Ok(()) => println!("\tDeleted {}.", FILE_TO_DELETE),
                 Err(error) => println!("\tCannot delete {}: {:?}", FILE_TO_DELETE, error),
             }
             println!("\tFinding {}...", FILE_TO_DELETE);
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_DELETE,
-                controller.find_directory_entry(&volume, &root_dir, FILE_TO_DELETE)
+                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_DELETE)
             );
         }
     }

examples/test_mount.rs

@@ -27,8 +27,8 @@ const FILE_TO_PRINT: &'static str = "README.TXT";
 const FILE_TO_CHECKSUM: &'static str = "64MB.DAT";
 
 use embedded_sdmmc::{
-    Block, BlockCount, BlockDevice, BlockIdx, Controller, Error, Mode, TimeSource, Timestamp,
-    VolumeIdx,
+    Block, BlockCount, BlockDevice, BlockIdx, Error, Mode, TimeSource, Timestamp, VolumeIdx,
+    VolumeManager,
 };
 use std::cell::RefCell;
 use std::fs::File;
@@ -121,14 +121,14 @@ fn main() {
         .map_err(Error::DeviceError)
         .unwrap();
     println!("lbd: {:?}", lbd);
-    let mut controller = Controller::new(lbd, Clock);
+    let mut volume_mgr = VolumeManager::new(lbd, Clock);
     for i in 0..=3 {
-        let volume = controller.get_volume(VolumeIdx(i));
+        let volume = volume_mgr.get_volume(VolumeIdx(i));
         println!("volume {}: {:#?}", i, volume);
         if let Ok(mut volume) = volume {
-            let root_dir = controller.open_root_dir(&volume).unwrap();
+            let root_dir = volume_mgr.open_root_dir(&volume).unwrap();
             println!("\tListing root directory:");
-            controller
+            volume_mgr
                 .iterate_dir(&volume, &root_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
@@ -137,15 +137,15 @@ fn main() {
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_PRINT,
-                controller.find_directory_entry(&volume, &root_dir, FILE_TO_PRINT)
+                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_PRINT)
             );
-            let mut f = controller
+            let mut f = volume_mgr
                 .open_file_in_dir(&mut volume, &root_dir, FILE_TO_PRINT, Mode::ReadOnly)
                 .unwrap();
             println!("FILE STARTS:");
             while !f.eof() {
                 let mut buffer = [0u8; 32];
-                let num_read = controller.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     if *b == 10 {
                         print!("\\n");
@@ -155,43 +155,43 @@ fn main() {
             }
             println!("EOF");
             // Can't open file twice
-            assert!(controller
+            assert!(volume_mgr
                 .open_file_in_dir(&mut volume, &root_dir, FILE_TO_PRINT, Mode::ReadOnly)
                 .is_err());
-            controller.close_file(&volume, f).unwrap();
+            volume_mgr.close_file(&volume, f).unwrap();
 
-            let test_dir = controller.open_dir(&volume, &root_dir, "TEST").unwrap();
+            let test_dir = volume_mgr.open_dir(&volume, &root_dir, "TEST").unwrap();
             // Check we can't open it twice
-            assert!(controller.open_dir(&volume, &root_dir, "TEST").is_err());
+            assert!(volume_mgr.open_dir(&volume, &root_dir, "TEST").is_err());
             // Print the contents
             println!("\tListing TEST directory:");
-            controller
+            volume_mgr
                 .iterate_dir(&volume, &test_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
                 .unwrap();
-            controller.close_dir(&volume, test_dir);
+            volume_mgr.close_dir(&volume, test_dir);
 
             // Checksum example file. We just sum the bytes, as a quick and dirty checksum.
             // We also read in a weird block size, just to exercise the offset calculation code.
-            let mut f = controller
+            let mut f = volume_mgr
                 .open_file_in_dir(&mut volume, &root_dir, FILE_TO_CHECKSUM, Mode::ReadOnly)
                 .unwrap();
             println!("Checksuming {} bytes of {}", f.length(), FILE_TO_CHECKSUM);
             let mut csum = 0u32;
             while !f.eof() {
                 let mut buffer = [0u8; 2047];
-                let num_read = controller.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     csum += u32::from(*b);
                 }
             }
             println!("Checksum over {} bytes: {}", f.length(), csum);
-            controller.close_file(&volume, f).unwrap();
+            volume_mgr.close_file(&volume, f).unwrap();
 
-            assert!(controller.open_root_dir(&volume).is_err());
-            controller.close_dir(&volume, root_dir);
-            assert!(controller.open_root_dir(&volume).is_ok());
+            assert!(volume_mgr.open_root_dir(&volume).is_err());
+            volume_mgr.close_dir(&volume, root_dir);
+            assert!(volume_mgr.open_root_dir(&volume).is_ok());
         }
     }
 }