Introducing a high-level FS abstraction

CHANGELOG.md

@@ -2,13 +2,20 @@
 
 ## uefi - [Unreleased]
 
+### Added
+
+- There is a new `fs` module that provides a high-level API for file-system
+  access. The API is close to the `std::fs` module.
+
 ### Changed
 
 - The `global_allocator` module has been renamed to `allocator`, and is now
   available regardless of whether the `global_allocator` feature is enabled. The
   `global_allocator` feature now only controls whether `allocator::Allocator` is
   set as Rust's global allocator.
 - `Error::new` and `Error::from` now panic if the status is `SUCCESS`.
+- `Image::get_image_file_system` now returns a `fs::FileSystem` instead of the
+  protocol.
 
 ## uefi-macros - [Unreleased]
 

uefi-test-runner/src/fs/mod.rs

@@ -0,0 +1,57 @@
+//! Tests functionality from the `uefi::fs` module. See function [`test`].
+
+use alloc::string::{String, ToString};
+use alloc::vec::Vec;
+use uefi::fs::{FileSystem, FileSystemError};
+use uefi::proto::media::fs::SimpleFileSystem;
+use uefi::table::boot::ScopedProtocol;
+
+/// Tests functionality from the `uefi::fs` module. This test relies on a
+/// working File System Protocol, which is tested at a dedicated place.
+pub fn test(sfs: ScopedProtocol<SimpleFileSystem>) -> Result<(), FileSystemError> {
+    let mut fs = FileSystem::new(sfs);
+
+    fs.create_dir("test_file_system_abs")?;
+
+    // slash is transparently transformed to backslash
+    fs.write("test_file_system_abs/foo", "hello")?;
+    // absolute or relative paths are supported; ./ is ignored
+    fs.copy("\\test_file_system_abs/foo", "\\test_file_system_abs/./bar")?;
+    let read = fs.read("\\test_file_system_abs\\bar")?;
+    let read = String::from_utf8(read).expect("Should be valid utf8");
+    assert_eq!(read, "hello");
+
+    assert_eq!(
+        fs.try_exists("test_file_system_abs\\barfoo"),
+        Err(FileSystemError::OpenError(
+            "\\test_file_system_abs\\barfoo".to_string()
+        ))
+    );
+    fs.rename("test_file_system_abs\\bar", "test_file_system_abs\\barfoo")?;
+    assert!(fs.try_exists("test_file_system_abs\\barfoo").is_ok());
+
+    let entries = fs
+        .read_dir("test_file_system_abs")?
+        .map(|e| {
+            e.expect("Should return boxed file info")
+                .file_name()
+                .to_string()
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(&[".", "..", "foo", "barfoo"], entries.as_slice());
+
+    fs.create_dir("/deeply_nested_test")?;
+    fs.create_dir("/deeply_nested_test/1")?;
+    fs.create_dir("/deeply_nested_test/1/2")?;
+    fs.create_dir("/deeply_nested_test/1/2/3")?;
+    fs.create_dir("/deeply_nested_test/1/2/3/4")?;
+    fs.create_dir_all("/deeply_nested_test/1/2/3/4/5/6/7")?;
+    fs.try_exists("/deeply_nested_test/1/2/3/4/5/6/7")?;
+    // TODO
+    // fs.remove_dir_all("/deeply_nested_test/1/2/3/4/5/6/7")?;
+    fs.remove_dir("/deeply_nested_test/1/2/3/4/5/6/7")?;
+    let exists = matches!(fs.try_exists("/deeply_nested_test/1/2/3/4/5/6/7"), Ok(_));
+    assert!(!exists);
+
+    Ok(())
+}

uefi-test-runner/src/main.rs

@@ -13,6 +13,7 @@ use uefi::Result;
 use uefi_services::{print, println};
 
 mod boot;
+mod fs;
 mod proto;
 mod runtime;
 

uefi-test-runner/src/proto/media.rs

@@ -433,8 +433,12 @@ pub fn test(bt: &BootServices) {
         test_partition_info(bt, handle);
     }
 
-    // Close the `SimpleFileSystem` protocol so that the raw disk tests work.
-    drop(sfs);
+    // Invoke the fs test after the basic low-level file system protocol
+    // tests succeeded.
+
+    // This will also drop the `SimpleFileSystem` protocol so that the raw disk
+    // tests work.
+    crate::fs::test(sfs).unwrap();
 
     test_raw_disk_io(handle, bt);
     test_raw_disk_io2(handle, bt);

uefi/Cargo.toml

@@ -25,6 +25,7 @@ unstable = []
 
 [dependencies]
 bitflags = "1.3.1"
+derive_more = { version = "0.99.17", features = ["display"] }
 log = { version = "0.4.5", default-features = false }
 ptr_meta = { version = "0.2.0", default-features = false }
 ucs2 = "0.3.2"

uefi/src/fs/dir_entry_iter.rs

@@ -0,0 +1,31 @@
+//! Module for directory iteration. See [`UefiDirectoryIter`].
+
+use super::*;
+use alloc::boxed::Box;
+use uefi::Result;
+
+/// Iterates over the entries of an UEFI directory. It returns boxed values of
+/// type [`UefiFileInfo`].
+#[derive(Debug)]
+pub struct UefiDirectoryIter(UefiDirectoryHandle);
+
+impl UefiDirectoryIter {
+    /// Constructor.
+    pub fn new(handle: UefiDirectoryHandle) -> Self {
+        Self(handle)
+    }
+}
+
+impl Iterator for UefiDirectoryIter {
+    type Item = Result<Box<UefiFileInfo>, ()>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        let e = self.0.read_entry_boxed();
+        match e {
+            // no more entries
+            Ok(None) => None,
+            Ok(Some(e)) => Some(Ok(e)),
+            Err(e) => Some(Err(e)),
+        }
+    }
+}