Merge branch 'develop' into update-embedded-hal

Author: AnyTimeTraveler

CHANGELOG.md

@@ -8,6 +8,11 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 
 * `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.
 * Renamed the old types to `RawVolume`, `RawDirectory` and `RawFile`
+* New method `make_dir_in_dir`
+* Fixed long-standing bug that caused an integer overflow when a FAT32 directory
+  was longer than one cluster ([#74])
+
+[#74]: https://github.com/rust-embedded-community/embedded-sdmmc-rs/issues/74
 
 ## [Version 0.6.0] - 2023-10-20
 

README.md

@@ -58,6 +58,12 @@ let mut cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(blo
 * Iterate sub-directories
 * 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)
+
 ## Todo List (PRs welcome!)
 
 * Create new dirs

examples/big_dir.rs

@@ -0,0 +1,39 @@
+extern crate embedded_sdmmc;
+
+mod linux;
+use linux::*;
+
+use embedded_sdmmc::{Error, 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 mut volume = volume_mgr
+        .open_volume(embedded_sdmmc::VolumeIdx(1))
+        .unwrap();
+    println!("Volume: {:?}", volume);
+    let mut root_dir = volume.open_root_dir().unwrap();
+
+    let mut file_num = 0;
+    loop {
+        file_num += 1;
+        let file_name = format!("{}.da", file_num);
+        println!("opening file {file_name} for writing");
+        let mut file = root_dir
+            .open_file_in_dir(
+                file_name.as_str(),
+                embedded_sdmmc::Mode::ReadWriteCreateOrTruncate,
+            )
+            .unwrap();
+        let buf = b"hello world, from rust";
+        println!("writing to file");
+        file.write(&buf[..]).unwrap();
+        println!("closing file");
+        drop(file);
+    }
+}

examples/list_dir.rs

@@ -76,12 +76,11 @@ fn list_dir(
                 ""
             }
         );
-        if entry.attributes.is_directory() {
-            if entry.name != embedded_sdmmc::ShortFileName::parent_dir()
-                && entry.name != embedded_sdmmc::ShortFileName::this_dir()
-            {
-                children.push(entry.name.clone());
-            }
+        if entry.attributes.is_directory()
+            && entry.name != embedded_sdmmc::ShortFileName::parent_dir()
+            && entry.name != embedded_sdmmc::ShortFileName::this_dir()
+        {
+            children.push(entry.name.clone());
         }
     })?;
     for child_name in children {

examples/shell.rs

@@ -41,6 +41,7 @@ impl Context {
             println!("\thexdump <file>      -> print a binary file");
             println!("\tcd ..               -> go up a level");
             println!("\tcd <dir>            -> change into <dir>");
+            println!("\tmkdir <dir>         -> create a directory called <dir>");
             println!("\tquit                -> exits the program");
         } else if line == "0:" {
             self.current_volume = 0;
@@ -59,11 +60,17 @@ impl Context {
             };
             self.volume_mgr.iterate_dir(s.directory, |entry| {
                 println!(
-                    "{:12} {:9} {} {:?}",
-                    entry.name, entry.size, entry.mtime, entry.attributes
+                    "{:12} {:9} {} {} {:X?} {:?}",
+                    entry.name,
+                    entry.size,
+                    entry.ctime,
+                    entry.mtime,
+                    entry.cluster,
+                    entry.attributes
                 );
             })?;
         } else if let Some(arg) = line.strip_prefix("cd ") {
+            let arg = arg.trim();
             let Some(s) = &mut self.volumes[self.current_volume] else {
                 println!("This volume isn't available");
                 return Ok(());
@@ -77,6 +84,7 @@ impl Context {
                 s.path.push(arg.to_owned());
             }
         } else if let Some(arg) = line.strip_prefix("cat ") {
+            let arg = arg.trim();
             let Some(s) = &mut self.volumes[self.current_volume] else {
                 println!("This volume isn't available");
                 return Ok(());
@@ -99,6 +107,7 @@ impl Context {
                 println!("I'm afraid that file isn't UTF-8 encoded");
             }
         } else if let Some(arg) = line.strip_prefix("hexdump ") {
+            let arg = arg.trim();
             let Some(s) = &mut self.volumes[self.current_volume] else {
                 println!("This volume isn't available");
                 return Ok(());
@@ -136,6 +145,14 @@ impl Context {
                 }
                 println!();
             }
+        } else if let Some(arg) = line.strip_prefix("mkdir ") {
+            let arg = arg.trim();
+            let Some(s) = &mut self.volumes[self.current_volume] else {
+                println!("This volume isn't available");
+                return Ok(());
+            };
+            // make the dir
+            self.volume_mgr.make_dir_in_dir(s.directory, arg)?;
         } else {
             println!("Unknown command {line:?} - try 'help' for help");
         }

src/fat/volume.rs

@@ -179,6 +179,9 @@ impl FatVolume {
     where
         D: BlockDevice,
     {
+        if cluster.0 > (u32::MAX / 4) {
+            panic!("next_cluster called on invalid cluster {:x?}", cluster);
+        }
         match &self.fat_specific_info {
             FatSpecificInfo::Fat16(_fat16_info) => {
                 let fat_offset = cluster.0 * 2;
@@ -275,7 +278,7 @@ impl FatVolume {
         &mut self,
         block_device: &D,
         time_source: &T,
-        dir: &DirectoryInfo,
+        dir_cluster: ClusterId,
         name: ShortFileName,
         attributes: Attributes,
     ) -> Result<DirEntry, Error<D::Error>>
@@ -289,12 +292,12 @@ impl FatVolume {
                 // a specially reserved space on disk (see
                 // `first_root_dir_block`). Other directories can have any size
                 // as they are made of regular clusters.
-                let mut current_cluster = Some(dir.cluster);
-                let mut first_dir_block_num = match dir.cluster {
+                let mut current_cluster = Some(dir_cluster);
+                let mut first_dir_block_num = match dir_cluster {
                     ClusterId::ROOT_DIR => self.lba_start + fat16_info.first_root_dir_block,
-                    _ => self.cluster_to_block(dir.cluster),
+                    _ => self.cluster_to_block(dir_cluster),
                 };
-                let dir_size = match dir.cluster {
+                let dir_size = match dir_cluster {
                     ClusterId::ROOT_DIR => {
                         let len_bytes =
                             u32::from(fat16_info.root_entries_count) * OnDiskDirEntry::LEN_U32;
@@ -360,19 +363,24 @@ impl FatVolume {
             FatSpecificInfo::Fat32(fat32_info) => {
                 // All directories on FAT32 have a cluster chain but the root
                 // dir starts in a specified cluster.
-                let mut first_dir_block_num = match dir.cluster {
-                    ClusterId::ROOT_DIR => self.cluster_to_block(fat32_info.first_root_dir_cluster),
-                    _ => self.cluster_to_block(dir.cluster),
+                let mut current_cluster = match dir_cluster {
+                    ClusterId::ROOT_DIR => Some(fat32_info.first_root_dir_cluster),
+                    _ => Some(dir_cluster),
                 };
-                let mut current_cluster = Some(dir.cluster);
+                let mut first_dir_block_num = self.cluster_to_block(dir_cluster);
                 let mut blocks = [Block::new()];
 
                 let dir_size = BlockCount(u32::from(self.blocks_per_cluster));
+                // Walk the cluster chain until we run out of clusters
                 while let Some(cluster) = current_cluster {
+                    // Loop through the blocks in the cluster
                     for block in first_dir_block_num.range(dir_size) {
+                        // Read a block of directory entries
                         block_device
                             .read(&mut blocks, block, "read_dir")
                             .map_err(Error::DeviceError)?;
+                        // Are any entries in the block we just loaded blank? If so
+                        // we can use them.
                         for entry in 0..Block::LEN / OnDiskDirEntry::LEN {
                             let start = entry * OnDiskDirEntry::LEN;
                             let end = (entry + 1) * OnDiskDirEntry::LEN;
@@ -397,6 +405,8 @@ impl FatVolume {
                             }
                         }
                     }
+                    // Well none of the blocks in that cluster had any space in
+                    // them, let's fetch another one.
                     let mut block_cache = BlockCache::empty();
                     current_cluster =
                         match self.next_cluster(block_device, cluster, &mut block_cache) {
@@ -412,6 +422,8 @@ impl FatVolume {
                             _ => None,
                         };
                 }
+                // We ran out of clusters in the chain, and apparently we weren't
+                // able to make the chain longer, so the disk must be full.
                 Err(Error::NotEnoughSpace)
             }
         }
@@ -994,6 +1006,34 @@ impl FatVolume {
         }
         Ok(())
     }
+
+    /// Writes a Directory Entry to the disk
+    pub(crate) fn write_entry_to_disk<D>(
+        &self,
+        block_device: &D,
+        entry: &DirEntry,
+    ) -> Result<(), Error<D::Error>>
+    where
+        D: BlockDevice,
+    {
+        let fat_type = match self.fat_specific_info {
+            FatSpecificInfo::Fat16(_) => FatType::Fat16,
+            FatSpecificInfo::Fat32(_) => FatType::Fat32,
+        };
+        let mut blocks = [Block::new()];
+        block_device
+            .read(&mut blocks, entry.entry_block, "read")
+            .map_err(Error::DeviceError)?;
+        let block = &mut blocks[0];
+
+        let start = usize::try_from(entry.entry_offset).map_err(|_| Error::ConversionError)?;
+        block[start..start + 32].copy_from_slice(&entry.serialize(fat_type)[..]);
+
+        block_device
+            .write(&blocks, entry.entry_block)
+            .map_err(Error::DeviceError)?;
+        Ok(())
+    }
 }
 
 /// Load the boot parameter block from the start of the given partition and

src/filesystem/directory.rs

@@ -51,7 +51,7 @@ pub struct DirEntry {
 pub struct RawDirectory(pub(crate) SearchId);
 
 impl RawDirectory {
-    /// Convert a raw file into a droppable [`File`]
+    /// Convert a raw directory into a droppable [`Directory`]
     pub fn to_directory<
         D,
         T,

src/lib.rs

@@ -231,6 +231,8 @@ where
     InvalidOffset,
     /// Disk is full
     DiskFull,
+    /// A directory with that name already exists
+    DirAlreadyExists,
 }
 
 impl<E> From<E> for Error<E>