fs: add method read_entry_boxed to Directory + test

Author: phip1611

src/proto/media/file/dir.rs

@@ -3,6 +3,19 @@ use crate::data_types::Align;
 use crate::Result;
 use core::ffi::c_void;
 
+#[cfg(feature = "alloc")]
+use crate::{ResultExt, Status};
+#[cfg(feature = "alloc")]
+use alloc_api::alloc;
+#[cfg(feature = "alloc")]
+use alloc_api::boxed::Box;
+#[cfg(feature = "alloc")]
+use core::alloc::Layout;
+#[cfg(feature = "alloc")]
+use core::ptr::NonNull;
+#[cfg(feature = "alloc")]
+use core::slice;
+
 /// A `FileHandle` that is also a directory.
 ///
 /// Use `File::into_type` or `Directory::new` to create a `Directory`. In
@@ -20,7 +33,7 @@ impl Directory {
         Self(RegularFile::new(handle))
     }
 
-    /// Read the next directory entry
+    /// Read the next directory entry.
     ///
     /// Try to read the next directory entry into `buffer`. If the buffer is too small, report the
     /// required buffer size as part of the error. If there are no more directory entries, return
@@ -56,6 +69,64 @@ impl Directory {
         })
     }
 
+    /// Wrapper around [`Self::read_entry`] that returns an owned copy of the data. It has the same
+    /// implications and requirements. On failure, the payload of `Err` is `()´.
+    #[cfg(feature = "alloc")]
+    pub fn read_entry_boxed(&mut self) -> Result<Option<Box<FileInfo>>> {
+        let read_entry_res = self.read_entry(&mut []);
+
+        // If no more entries are available, return early.
+        if let Ok(None) = read_entry_res {
+            return Ok(None);
+        }
+
+        let required_size = match read_entry_res
+            .expect_err("zero sized read unexpectedly succeeded")
+            .split()
+        {
+            // Early return if something has failed.
+            (s, None) => return Err(s.into()),
+            (_, Some(required_size)) => required_size,
+        };
+
+        // We add trailing padding because the size of a rust structure must
+        // always be a multiple of alignment.
+        let layout = Layout::from_size_align(required_size, FileInfo::alignment())
+            .unwrap()
+            .pad_to_align();
+
+        // Allocate the buffer.
+        let heap_buf: NonNull<u8> = unsafe {
+            let ptr = alloc::alloc(layout);
+            match NonNull::new(ptr) {
+                None => return Err(Status::OUT_OF_RESOURCES.into()),
+                Some(ptr) => ptr,
+            }
+        };
+
+        // Get the file info using the allocated buffer for storage.
+        let info = {
+            let buffer = unsafe { slice::from_raw_parts_mut(heap_buf.as_ptr(), layout.size()) };
+            self.read_entry(buffer).discard_errdata()
+        };
+
+        // If an error occurred, deallocate the memory before returning.
+        let info = match info {
+            Ok(info) => info,
+            Err(err) => {
+                unsafe { alloc::dealloc(heap_buf.as_ptr(), layout) };
+                return Err(err);
+            }
+        };
+
+        // Wrap the file info in a box so that it will be deallocated on
+        // drop. This is valid because the memory was allocated with the
+        // global allocator.
+        let info = info.map(|info| unsafe { Box::from_raw(info) });
+
+        Ok(info)
+    }
+
     /// Start over the process of enumerating directory entries
     pub fn reset_entry_readout(&mut self) -> Result {
         self.0.set_position(0)

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

@@ -1,4 +1,5 @@
 use alloc::string::ToString;
+use core::cell::RefCell;
 use core::ptr::NonNull;
 use uefi::prelude::*;
 use uefi::proto::media::block::BlockIO;
@@ -21,20 +22,61 @@ fn test_existing_dir(directory: &mut Directory) {
 
     assert!(dir.is_directory().unwrap());
 
-    let mut dir = dir.into_directory().expect("not a directory");
-
-    // Collect and validate the directory entries.
-    let mut entry_names = vec![];
-    let mut buf = vec![0; 200];
-    loop {
-        let entry = dir.read_entry(&mut buf).expect("failed to read directory");
-        if let Some(entry) = entry {
-            entry_names.push(entry.file_name().to_string());
-        } else {
-            break;
+    let dir = dir.into_directory().expect("Should be a directory");
+
+    let dir = RefCell::new(dir);
+
+    // Backing memory to read the file info data into.
+    let mut stack_buf = [0; 200];
+
+    // The file names that the test read from the directory.
+    let entry_names = RefCell::new(vec![]);
+
+    // Expected file names in the directory.
+    const EXPECTED: &[&str] = &[".", "..", "test_input.txt"];
+
+    // Reads the whole directory with provided backing memory.
+    let mut test_read_dir_stack_mem = || {
+        let mut dir = dir.borrow_mut();
+        let mut entry_names = entry_names.borrow_mut();
+        loop {
+            let entry = dir
+                .read_entry(&mut stack_buf)
+                .expect("failed to read directory");
+            if let Some(entry) = entry {
+                entry_names.push(entry.file_name().to_string());
+            } else {
+                break;
+            }
         }
+        assert_eq!(&*entry_names, EXPECTED);
+    };
+
+    // Reads the whole directory but returns owned memory on the heap.
+    let test_read_dir_heap_mem = || {
+        let mut dir = dir.borrow_mut();
+        let mut entry_names = entry_names.borrow_mut();
+        loop {
+            let entry = dir.read_entry_boxed().expect("failed to read directory");
+            if let Some(entry) = entry {
+                entry_names.push(entry.file_name().to_string());
+            } else {
+                break;
+            }
+        }
+        assert_eq!(&*entry_names, EXPECTED);
+    };
+
+    // Tests all read dir test functions three times.
+    for _ in 0..3 {
+        entry_names.borrow_mut().clear();
+        dir.borrow_mut().reset_entry_readout().unwrap();
+        test_read_dir_stack_mem();
+
+        entry_names.borrow_mut().clear();
+        dir.borrow_mut().reset_entry_readout().unwrap();
+        test_read_dir_heap_mem();
     }
-    assert_eq!(entry_names, [".", "..", "test_input.txt"]);
 }
 
 /// Test that deleting a file opened in read-only mode fails with a