Add support for opening existing files using LFNs.

thejpster · thejpster · commit d62effb16f3d · 2025-12-22T22:58:03.000Z
Opening existing directories can be added later.

Notably this does not require holding the entire LFN on the stack at
once - we match the UTF-8 string slice we're given against the USC-2
words we pull off the disk, in reverse order.

The shell example now lets you `cat` and `hexdump` files with long
names.
diff --git a/examples/shell.rs b/examples/shell.rs
@@ -340,7 +340,7 @@ impl Context {
     /// print a text file
     fn cat(&self, filename: &Path) -> Result<(), Error> {
         let (dir, filename) = self.resolve_filename(filename)?;
-        let f = dir.open_file_in_dir(filename, Mode::ReadOnly)?;
+        let f = dir.open_long_name_file_in_dir(filename, Mode::ReadOnly)?;
         let mut data = Vec::new();
         while !f.is_eof() {
             let mut buffer = vec![0u8; 65536];
@@ -360,7 +360,7 @@ impl Context {
     /// print a binary file
     fn hexdump(&self, filename: &Path) -> Result<(), Error> {
         let (dir, filename) = self.resolve_filename(filename)?;
-        let f = dir.open_file_in_dir(filename, Mode::ReadOnly)?;
+        let f = dir.open_long_name_file_in_dir(filename, Mode::ReadOnly)?;
         let mut data = Vec::new();
         while !f.is_eof() {
             let mut buffer = vec![0u8; 65536];
diff --git a/src/fat/volume.rs b/src/fat/volume.rs
@@ -797,6 +797,146 @@ impl FatVolume {
         result
     }
 
+    /// Get an entry from the given directory
+    pub(crate) fn find_directory_entry_by_lfn<D>(
+        &self,
+        block_cache: &mut BlockCache<D>,
+        dir_info: &DirectoryInfo,
+        match_name: &str,
+    ) -> Result<DirEntry, Error<D::Error>>
+    where
+        D: BlockDevice,
+    {
+        let mut result = Err(Error::NotFound);
+        enum SeqState<'a> {
+            /// Looking for the first entry in an LFN sequence
+            Waiting,
+            /// Scanning through an LFN sequence
+            Scanning {
+                remaining: &'a str,
+                sequence: u8,
+                csum: u8,
+            },
+            /// Found an entry we like
+            Found { csum: u8 },
+        }
+
+        let mut state = SeqState::Waiting;
+        self.iterate_dir_internal(block_cache, dir_info, |de, odde| {
+            match state {
+                SeqState::Waiting => {
+                    debug!("Am waiting for LFN start");
+                    let mut remaining = match_name;
+                    if let Some((true, sequence, csum, buffer)) = odde.lfn_contents() {
+                        debug!("{:02x} {:02x} {:04x?}", sequence, csum, buffer);
+                        // trim padding and NUL words off the end of the file name (which is the part that comes first)
+                        for word in buffer
+                            .iter()
+                            .rev()
+                            .skip_while(|b| **b == 0xFFFF)
+                            .skip_while(|b| **b == 0x0000)
+                        {
+                            debug!("Looking at word {:04x}", *word);
+                            // UCS-2 16-bit values are valid Unicode code points - we do not expect surrogate pairs but if we find then, we give up.
+                            let Some(c) = char::from_u32(*word as u32) else {
+                                return Continue::Yes;
+                            };
+                            debug!("Looking at char '{}'", c);
+                            let Some(r) = remaining.strip_suffix(c) else {
+                                debug!("No, didn't want that");
+                                return Continue::Yes;
+                            };
+                            debug!("Liked it! {:?} is left", r);
+                            remaining = r;
+                        }
+                        if sequence == 1 {
+                            // last piece
+                            if remaining.is_empty() {
+                                // found it
+                                state = SeqState::Found { csum }
+                            } else {
+                                // no, we have characters left over
+                                state = SeqState::Waiting
+                            }
+                        } else {
+                            // keep looking
+                            state = SeqState::Scanning {
+                                remaining,
+                                sequence: sequence - 1,
+                                csum,
+                            };
+                        }
+                    }
+                }
+                SeqState::Scanning {
+                    remaining,
+                    sequence,
+                    csum,
+                } => {
+                    debug!(
+                        "Am waiting for more LFN sequence={:02x}, csum={:02x}",
+                        sequence, csum
+                    );
+                    let mut remaining = remaining;
+                    if let Some((false, this_sequence, this_csum, buffer)) = odde.lfn_contents() {
+                        debug!("{:02x} {:02x} {:04x?}", sequence, csum, buffer);
+                        if (this_sequence != sequence) || (this_csum != csum) {
+                            // not what we wanted
+                            debug!(
+                                "No! Got sequence={:02x}, csum={:02x}",
+                                this_sequence, this_csum
+                            );
+                            state = SeqState::Waiting;
+                            return Continue::Yes;
+                        }
+                        for word in buffer.iter().rev() {
+                            // UCS-2 16-bit values are valid Unicode code points - we do not expect surrogate pairs but if we find then, we give up.
+                            debug!("Looking at word {:04x}", *word);
+                            let Some(c) = char::from_u32(*word as u32) else {
+                                return Continue::Yes;
+                            };
+                            debug!("Looking at char '{}'", c);
+                            let Some(r) = remaining.strip_suffix(c) else {
+                                debug!("No, didn't want that");
+                                return Continue::Yes;
+                            };
+                            debug!("Liked it! {:?} is left", r);
+                            remaining = r;
+                        }
+                        if sequence == 1 {
+                            // last piece
+                            if remaining.is_empty() {
+                                // found it
+                                state = SeqState::Found { csum }
+                            } else {
+                                // no, we have characters left over
+                                state = SeqState::Waiting
+                            }
+                        } else {
+                            // keep looking
+                            state = SeqState::Scanning {
+                                remaining,
+                                sequence: sequence - 1,
+                                csum,
+                            };
+                        }
+                    }
+                }
+                SeqState::Found { csum } => {
+                    let calc_csum = de.name.csum();
+                    if calc_csum == csum {
+                        result = Ok(de.clone());
+                        return Continue::No;
+                    } else {
+                        debug!("Bad csum {:02x} != {:02x}", calc_csum, csum)
+                    }
+                }
+            }
+            Continue::Yes
+        })?;
+        result
+    }
+
     /// Delete an entry from the given directory
     pub(crate) fn delete_directory_entry<D>(
         &self,
diff --git a/src/filesystem/directory.rs b/src/filesystem/directory.rs
@@ -197,6 +197,22 @@ where
         Ok(f.to_file(self.volume_mgr))
     }
 
+    /// Open a file.
+    ///
+    /// See [`VolumeManager::open_long_name_file_in_dir`] for details, except the
+    /// directory given is this directory.
+    pub fn open_long_name_file_in_dir(
+        &self,
+        name: &str,
+        mode: crate::Mode,
+    ) -> Result<crate::File<'_, D, T, MAX_DIRS, MAX_FILES, MAX_VOLUMES>, crate::Error<D::Error>>
+    {
+        let f = self
+            .volume_mgr
+            .open_long_name_file_in_dir(self.raw_directory, name, mode)?;
+        Ok(f.to_file(self.volume_mgr))
+    }
+
     /// Delete a file/directory.
     ///
     /// See [`VolumeManager::delete_entry_in_dir`] for details, except the
diff --git a/src/volume_mgr.rs b/src/volume_mgr.rs
@@ -731,6 +731,158 @@ where
         }
     }
 
+    /// Open a file with the given Unicode long file name, in the given directory.
+    ///
+    /// You can only open existing long-file-name files - you cannot create them.
+    ///
+    /// <div class="warning">
+    ///
+    /// This function gives you a [`RawFile`] and when you are finished with
+    /// it, you **must** close the file by calling
+    /// [`VolumeManager::close_file`] otherwise you will leak internal
+    /// resources and/or suffer file-system corruption and data loss.
+    ///
+    /// </div>
+    ///
+    /// If you want a file handle that closes itself on drop, see
+    /// [`File`](crate::File).
+    pub fn open_long_name_file_in_dir(
+        &self,
+        directory: RawDirectory,
+        name: &str,
+        mode: Mode,
+    ) -> Result<RawFile, Error<D::Error>> {
+        let mut data = self.data.try_borrow_mut().map_err(|_| Error::LockError)?;
+        let data = data.deref_mut();
+
+        // This check is load-bearing - we do an unchecked push later.
+        if data.open_files.is_full() {
+            return Err(Error::TooManyOpenFiles);
+        }
+
+        let directory_idx = data.get_dir_by_id(directory)?;
+        let volume_id = data.open_dirs[directory_idx].raw_volume;
+        let volume_idx = data.get_volume_by_id(volume_id)?;
+        let volume_info = &data.open_volumes[volume_idx];
+
+        let dir_entry = match &volume_info.volume_type {
+            VolumeType::Fat(fat) => fat.find_directory_entry_by_lfn(
+                &mut data.block_cache,
+                &data.open_dirs[directory_idx],
+                name,
+            ),
+        };
+
+        let dir_entry = match dir_entry {
+            Ok(entry) => {
+                // we are opening an existing file
+                entry
+            }
+            Err(_)
+                if (mode == Mode::ReadWriteCreate)
+                    | (mode == Mode::ReadWriteCreateOrTruncate)
+                    | (mode == Mode::ReadWriteCreateOrAppend) =>
+            {
+                // We are opening a non-existant file and we cannot do that with LFNs
+                return Err(Error::NotFound);
+            }
+            _ => {
+                // We are opening a non-existant file, and that's not OK.
+                return Err(Error::NotFound);
+            }
+        };
+
+        // Check if it's open already
+        if data.file_is_open(volume_info.raw_volume, &dir_entry) {
+            return Err(Error::FileAlreadyOpen);
+        }
+
+        let mode = solve_mode_variant(mode, true);
+
+        match mode {
+            Mode::ReadWriteCreate => {
+                return Err(Error::FileAlreadyExists);
+            }
+            _ => {
+                if dir_entry.attributes.is_read_only() && mode != Mode::ReadOnly {
+                    return Err(Error::ReadOnly);
+                }
+
+                if dir_entry.attributes.is_directory() {
+                    return Err(Error::OpenedDirAsFile);
+                }
+
+                // Check it's not already open
+                if data.file_is_open(volume_id, &dir_entry) {
+                    return Err(Error::FileAlreadyOpen);
+                }
+
+                let mode = solve_mode_variant(mode, true);
+                let raw_file = RawFile(data.id_generator.generate());
+
+                let file = match mode {
+                    Mode::ReadOnly => FileInfo {
+                        raw_file,
+                        raw_volume: volume_id,
+                        current_cluster: (0, dir_entry.cluster),
+                        current_offset: 0,
+                        mode,
+                        entry: dir_entry,
+                        dirty: false,
+                    },
+                    Mode::ReadWriteAppend => {
+                        let mut file = FileInfo {
+                            raw_file,
+                            raw_volume: volume_id,
+                            current_cluster: (0, dir_entry.cluster),
+                            current_offset: 0,
+                            mode,
+                            entry: dir_entry,
+                            dirty: false,
+                        };
+                        // seek_from_end with 0 can't fail
+                        file.seek_from_end(0).ok();
+                        file
+                    }
+                    Mode::ReadWriteTruncate => {
+                        let mut file = FileInfo {
+                            raw_file,
+                            raw_volume: volume_id,
+                            current_cluster: (0, dir_entry.cluster),
+                            current_offset: 0,
+                            mode,
+                            entry: dir_entry,
+                            dirty: false,
+                        };
+                        match &mut data.open_volumes[volume_idx].volume_type {
+                            VolumeType::Fat(fat) => fat.truncate_cluster_chain(
+                                &mut data.block_cache,
+                                file.entry.cluster,
+                            )?,
+                        };
+                        file.update_length(0);
+                        match &data.open_volumes[volume_idx].volume_type {
+                            VolumeType::Fat(fat) => {
+                                file.entry.mtime = self.time_source.get_timestamp();
+                                fat.write_entry_to_disk(&mut data.block_cache, &file.entry)?;
+                            }
+                        };
+
+                        file
+                    }
+                    _ => return Err(Error::Unsupported),
+                };
+
+                // Remember this open file - can't be full as we checked already
+                unsafe {
+                    data.open_files.push_unchecked(file);
+                }
+
+                Ok(raw_file)
+            }
+        }
+    }
+
     /// Delete a closed file or empty directory with the given filename, if it exists.
     pub fn delete_entry_in_dir<N>(
         &self,
diff --git a/tests/open_files.rs b/tests/open_files.rs
@@ -91,6 +91,40 @@ fn open_files() {
     volume_mgr.close_volume(volume).expect("close volume");
 }
 
+#[test]
+fn open_lfn() {
+    let time_source = utils::make_time_source();
+    let disk = utils::make_block_device(utils::DISK_SOURCE).unwrap();
+    let volume_mgr: VolumeManager<utils::RamDisk<Vec<u8>>, utils::TestTimeSource, 4, 2, 1> =
+        VolumeManager::new_with_limits(disk, time_source, 0xAA00_0000);
+    let volume = volume_mgr.open_volume(VolumeIdx(1)).expect("open volume");
+    let root_dir = volume.open_root_dir().expect("open root dir");
+    let _f = root_dir
+        .open_long_name_file_in_dir("Copy of Readme.txt", Mode::ReadOnly)
+        .expect("open file");
+
+    assert!(matches!(
+        root_dir.open_long_name_file_in_dir("Copy of Readme.tx", Mode::ReadOnly),
+        Err(embedded_sdmmc::Error::NotFound)
+    ));
+    assert!(matches!(
+        root_dir.open_long_name_file_in_dir("opy of Readme.txt", Mode::ReadOnly),
+        Err(embedded_sdmmc::Error::NotFound)
+    ));
+    assert!(matches!(
+        root_dir.open_long_name_file_in_dir("Copyof Readme.txt", Mode::ReadOnly),
+        Err(embedded_sdmmc::Error::NotFound)
+    ));
+    assert!(matches!(
+        root_dir.open_long_name_file_in_dir("Copy_of Readme.txt", Mode::ReadOnly),
+        Err(embedded_sdmmc::Error::NotFound)
+    ));
+    assert!(matches!(
+        root_dir.open_long_name_file_in_dir("Nonsense", Mode::ReadOnly),
+        Err(embedded_sdmmc::Error::NotFound)
+    ));
+}
+
 #[test]
 fn open_non_raw() {
     let time_source = utils::make_time_source();
