fs_proto: improved doc of read function and better return type

Author: phip1611

src/proto/media/file/dir.rs

@@ -2,6 +2,7 @@ use super::{File, FileHandle, FileInfo, FromUefi, RegularFile};
 use crate::data_types::Align;
 use crate::Result;
 use core::ffi::c_void;
+use uefi::Status;
 
 /// A `FileHandle` that is also a directory.
 ///
@@ -20,35 +21,28 @@ 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
-    /// an empty optional.
-    ///
-    /// The input buffer must be correctly aligned for a `FileInfo`. You can query the required
-    /// alignment through the `Align` trait (`<FileInfo as Align>::alignment()`).
+    /// Under the hood, this wraps [`super::RegularFile::read`]. Please refer to it's documentation.
     ///
     /// # Arguments
     /// * `buffer`  The target buffer of the read operation
     ///
-    /// # Errors
-    /// * `uefi::Status::NO_MEDIA`           The device has no media
-    /// * `uefi::Status::DEVICE_ERROR`       The device reported an error, the file was deleted,
-    ///                                      or the end of the file was reached before the `read()`.
-    /// * `uefi::Status::VOLUME_CORRUPTED`   The filesystem structures are corrupted
-    /// * `uefi::Status::BUFFER_TOO_SMALL`   The buffer is too small to hold a directory entry,
-    ///                                      the required buffer size is provided into the error.
+    /// # Return Value
+    /// This either returns some file info or nothing (if the directory contains no more entries)
+    /// success case or a tuple of the UEFI status and the required buffer size, if the buffer was
+    /// too small.
     pub fn read_entry<'buf>(
         &mut self,
         buffer: &'buf mut [u8],
-    ) -> Result<Option<&'buf mut FileInfo>, Option<usize>> {
+    ) -> Result<Option<&'buf mut FileInfo>, (Status, Option<usize>)> {
         // Make sure that the storage is properly aligned
         FileInfo::assert_aligned(buffer);
 
         // Read the directory entry into the aligned storage
-        self.0.read(buffer).map(|size| {
-            if size != 0 {
+        self.0.read(buffer).map(|read_bytes| {
+            // 0 signalizes that the last directory entry was read
+            if read_bytes != 0 {
                 unsafe { Some(FileInfo::from_uefi(buffer.as_mut_ptr().cast::<c_void>())) }
             } else {
                 None

src/proto/media/file/regular.rs

@@ -21,31 +21,54 @@ impl RegularFile {
         Self(handle)
     }
 
-    /// Read data from file
+    /// Read data from a file, hence, a regular file or a directory.
     ///
-    /// Try to read as much as possible into `buffer`. Returns the number of bytes that were
-    /// actually read.
+    /// # Read from Regular Files
+    /// If `self` is not a directory, the function reads the requested number of bytes from the file
+    /// at the file’s current position and returns them in `buffer`. If the read goes beyond the end
+    /// of the file, the read length is truncated to the end of the file. The file’s current
+    /// position is increased by the number of bytes returned.
+    ///
+    /// # Read from Directory
+    /// If `self` is a directory, the function reads the directory entry at the file’s current
+    /// position and returns the entry in `buffer`. If the `buffer` is not large enough to hold the
+    /// current directory entry, then `EFI_BUFFER_TOO_SMALL` is returned and the current file
+    /// position is not updated. `buffer_size` is set to be the size of the buffer needed to read
+    /// the entry. On success, the current position is updated to the next directory entry. If there
+    /// are no more directory entries, the read returns a zero-length buffer. `EFI_FILE_INFO` is the
+    /// structure returned as the directory entry.
     ///
     /// # Arguments
     /// * `buffer`  The target buffer of the read operation
     ///
-    /// # Errors
+    /// # Return Value
+    /// This either returns the size of read bytes in the success case or a tuple of the UEFI
+    /// status and the required buffer size, if the buffer was too small. The status code can
+    /// signalize one of the following errors:
+    ///
+    /// ## Status Error Codes
     /// * `uefi::Status::NO_MEDIA`           The device has no media
     /// * `uefi::Status::DEVICE_ERROR`       The device reported an error, the file was deleted,
     ///                                      or the end of the file was reached before the `read()`.
     /// * `uefi::Status::VOLUME_CORRUPTED`   The filesystem structures are corrupted
     /// * `uefi::Status::BUFFER_TOO_SMALL`   The buffer is too small to hold a directory entry,
     ///                                      and the required buffer size is provided as output.
-    pub fn read(&mut self, buffer: &mut [u8]) -> Result<usize, Option<usize>> {
+    pub fn read(&mut self, buffer: &mut [u8]) -> Result<usize, (Status, Option<usize>)> {
         let mut buffer_size = buffer.len();
-        unsafe { (self.imp().read)(self.imp(), &mut buffer_size, buffer.as_mut_ptr()) }.into_with(
+        let status =
+            unsafe { (self.imp().read)(self.imp(), &mut buffer_size, buffer.as_mut_ptr()) };
+
+        // Now, buffer_size is updated. It either contains the number of read bytes or the number
+        // of required bytes to read the whole entry.
+        status.into_with(
             || buffer_size,
-            |s| {
-                if s == Status::BUFFER_TOO_SMALL {
+            |s: Status| {
+                let required_buffer_size = if s == Status::BUFFER_TOO_SMALL {
                     Some(buffer_size)
                 } else {
                     None
-                }
+                };
+                (status, required_buffer_size)
             },
         )
     }

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

@@ -45,7 +45,7 @@ pub fn test(bt: &BootServices) {
                 }
                 Err(error) => {
                     // Buffer is not big enough, allocate a bigger one and try again.
-                    let min_size = error.data().unwrap();
+                    let min_size = error.data().1.unwrap();
                     buffer.resize(min_size, 0);
                     continue;
                 }