high-level fs abstraction

Author: phip1611

src/fs/dir_entry_iter.rs

@@ -0,0 +1,35 @@
+use crate::fs::file_info::{BoxedUefiFileInfo, UEFI_FILE_INFO_MAX_SIZE};
+use super::*;
+use alloc_api::vec::Vec;
+
+/// Iterator over the low-level entries of a UEFI directory handle.
+/// Returns owning [BoxedUefiFileInfo].
+pub struct UefiDirectoryEntryIterator {
+    handle: UefiDirectoryHandle,
+    buffer: Vec<u8>,
+}
+
+impl UefiDirectoryEntryIterator {
+    pub fn new(handle: UefiDirectoryHandle) -> Self {
+        // May contain 256 characters with an fixed size UTF-16 format. Null-byte included.
+        let mut buffer = Vec::with_capacity(UEFI_FILE_INFO_MAX_SIZE);
+        (0..buffer.capacity()).for_each(|_| buffer.push(0));
+        Self { handle, buffer }
+    }
+}
+
+impl Iterator for UefiDirectoryEntryIterator {
+    type Item = BoxedUefiFileInfo;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        // reset as the buffer gets used multiple times
+        self.buffer.fill(0);
+
+        self.handle
+            .read_entry(&mut self.buffer)
+            // it is extremly ugly to marry the results from uefi with the option from the iterator..
+            //  thus, just panic =(
+            .expect("Uefi Error")
+            .map(|fileinfo| BoxedUefiFileInfo::new(fileinfo))
+    }
+}

src/fs/file_info.rs

@@ -0,0 +1,67 @@
+use crate::fs::path::MAX_COMPONENT_LENGTH;
+use alloc_api::vec::Vec;
+use core::ops::Deref;
+use uefi::proto::media::file::FileInfo as UefiFileInfo;
+
+// Ugly but we can't use size_of() as the type isn't sized.
+// This is constant, as it is specified.
+/// Size of a [UefiFileInfo] without the filename and without a NULL byte.
+pub const UEFI_FILE_INFO_MAX_SIZE: usize = 80 + 2 * (1 + MAX_COMPONENT_LENGTH);
+
+/// A UEFI file info that lives on the heap. Owns the data.
+#[derive(Debug)]
+pub struct BoxedUefiFileInfo {
+    // owning buffer
+    buffer: Vec<u8>,
+}
+
+impl BoxedUefiFileInfo {
+    pub fn new(info: &UefiFileInfo) -> Self {
+        let mut buffer = Vec::<u8>::with_capacity(UEFI_FILE_INFO_MAX_SIZE);
+        (0..buffer.capacity()).for_each(|_| buffer.push(0));
+
+        unsafe {
+            let src_ptr = core::ptr::addr_of!(*info).cast::<u8>();
+            let dest_ptr = buffer.as_mut_ptr().cast::<u8>();
+            core::ptr::copy_nonoverlapping(src_ptr, dest_ptr, UEFI_FILE_INFO_MAX_SIZE);
+        }
+        Self { buffer }
+    }
+}
+
+impl Deref for BoxedUefiFileInfo {
+    type Target = UefiFileInfo;
+    fn deref(&self) -> &Self::Target {
+        unsafe {
+            let addr = self.buffer.as_ptr().cast::<()>();
+            let ptr: *const UefiFileInfo =
+            // todo metadata is here probably unused?!
+                core::ptr::from_raw_parts(addr, self.buffer.capacity());
+            ptr.as_ref().unwrap()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use uefi::proto::media::file::FromUefi;
+
+    #[test]
+    fn test_put_into_box() {
+        let mut buffer = [0_u8; UEFI_FILE_INFO_MAX_SIZE];
+
+        let boxed_fileinfo = unsafe {
+            let ptr = buffer.as_mut_ptr();
+
+            // set some values to the "file_size" property
+            *ptr.cast::<u64>().add(1) = 0x7733_0909_2345_1337;
+
+            let uefi_fileinfo = UefiFileInfo::from_uefi(ptr.cast());
+            assert_eq!(uefi_fileinfo.file_size(), 0x7733_0909_2345_1337);
+            BoxedUefiFileInfo::new(uefi_fileinfo)
+        };
+
+        assert_eq!(boxed_fileinfo.file_size(), 0x7733_0909_2345_1337);
+    }
+}

src/fs/file_system.rs

@@ -0,0 +1,289 @@
+//! Module for [FileSystem].
+
+use super::*;
+use crate::fs::dir_entry_iter::UefiDirectoryEntryIterator;
+use crate::fs::file_info::BoxedUefiFileInfo;
+use crate::fs::path::{Path, PathError};
+use alloc_api::string::{FromUtf8Error, String, ToString};
+use alloc_api::vec::Vec;
+use core::fmt;
+use core::fmt::{Debug, Formatter};
+use uefi::proto::media::file::FileType;
+use uefi::table::boot::ScopedProtocol;
+use uefi::{CString16};
+
+// #[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
+#[derive(Debug, Clone)]
+pub enum FileSystemError {
+    /// Can't open the root directory of the underlying volume.
+    CantOpenVolume,
+    /// The path is invalid because of the underlying [PathError].
+    IllegalPath(PathError),
+    /// The file or directory was not found in the underlying volume.
+    FileNotFound(String),
+    /// The path is existend but does not correspond to a directory when a directory was expected.
+    NotADirectory(String),
+    /// The path is existend but does not correspond to a file when a file was expected.
+    NotAFile(String),
+    /// Can't delete the file.
+    CantDeleteFile(String),
+    /// Error writing bytes.
+    WriteFailure,
+    /// Error flushing file.
+    FlushFailure,
+    /// Error reading file.
+    ReadFailure,
+    /// Can't parse file content as UTF-8.
+    Utf8Error(FromUtf8Error),
+    /// Could not open the given path.
+    OpenError(String),
+}
+
+impl From<PathError> for FileSystemError {
+    fn from(err: PathError) -> Self {
+        Self::IllegalPath(err)
+    }
+}
+
+/// Return type for public [FileSystem] operations.
+pub type FileSystemResult<T> = Result<T, FileSystemError>;
+
+/// Entry point into the file system abstraction described by the module description. Accessor to
+/// an UEFI volume. Available methods try to be close to the `fs` module of `libstd`.
+///
+/// # Technical Background
+/// Some random interesting information how this abstraction helps.
+/// - To get metadata about UEFI files, we need to iterate the parent directory. This abstraction
+///   hides this complexity.
+pub struct FileSystem<'name, 'boot_services> {
+    /// Name to identify this file system. For example "root" or "boot". Only a help for users.
+    name: &'name str,
+    /// Underlying UEFI
+    proto: ScopedProtocol<'boot_services, SimpleFileSystemProtocol>,
+}
+
+impl<'name, 'boot_services> FileSystem<'name, 'boot_services> {
+    /// Constructor. The name is only used to help you as a user to identify this file system.
+    /// This may be "root", "main", or "boot".
+    pub fn new(
+        name: &'name str,
+        proto: ScopedProtocol<'boot_services, SimpleFileSystemProtocol>,
+    ) -> Self {
+        Self { name, proto }
+    }
+
+    /// Tests if the underlying file exists. If this returns `Ok`, the file exists.
+    pub fn try_exists(&mut self, path: &str) -> FileSystemResult<()> {
+        self.metadata(&path).map(|_| ())
+    }
+
+    /// Copies the contents of one file to another. Creates the destination file if it doesn't
+    /// exist and overwrites any content, if it exists.
+    pub fn copy(&mut self, src_path: &str, dest_path: &str) -> FileSystemResult<()> {
+        let read = self.read(src_path)?;
+        self.write(dest_path, read)
+    }
+
+    /// Creates a new, empty directory at the provided path
+    pub fn create_dir(&mut self, path: &str) -> FileSystemResult<()> {
+        let _path = Path::new(path)?;
+        todo!()
+    }
+
+    /// Recursively create a directory and all of its parent components if they are missing.
+    pub fn create_dir_all(&mut self, path: &str) -> FileSystemResult<()> {
+        let _path = Path::new(path)?;
+        todo!()
+    }
+
+    /// Given a path, query the file system to get information about a file, directory, etc.
+    pub fn metadata(&mut self, path: &str) -> FileSystemResult<BoxedUefiFileInfo> {
+        let path = Path::new(path)?;
+        self.resolve_directory_entry_fileinfo(&path)
+    }
+
+    /// Read the entire contents of a file into a bytes vector.
+    pub fn read(&mut self, path: &str) -> FileSystemResult<Vec<u8>> {
+        let path = Path::new(path)?;
+
+        let mut file = self
+            .open_in_root(&path, UefiFileMode::Read)?
+            .into_regular_file()
+            .ok_or(FileSystemError::NotAFile(path.as_str().to_string()))?;
+        let info = self.resolve_directory_entry_fileinfo(&path).unwrap();
+
+        let mut vec = Vec::with_capacity(info.file_size() as usize);
+        vec.resize(vec.capacity(), 0);
+        let read_bytes = file.read(vec.as_mut_slice()).map_err(|e| {
+            log::error!("reading failed: {e:?}");
+            FileSystemError::ReadFailure
+        })?;
+
+        // we read the whole file at once!
+        if read_bytes != info.file_size() as usize {
+            log::error!("Did only read {}/{} bytes", info.file_size(), read_bytes);
+        }
+
+        Ok(vec)
+    }
+
+    /// Returns an iterator over the entries within a directory.
+    pub fn read_dir(&mut self, path: &str) -> FileSystemResult<UefiDirectoryEntryIterator> {
+        let path = Path::new(path)?;
+        let parent_dir = self.open_parent_dir_handle_of_path(&path, UefiFileMode::Read)?;
+        Ok(UefiDirectoryEntryIterator::new(parent_dir))
+    }
+
+    /// Read the entire contents of a file into a string.
+    pub fn read_to_string(&mut self, path: &str) -> FileSystemResult<String> {
+        String::from_utf8(self.read(path)?).map_err(|x| FileSystemError::Utf8Error(x))
+    }
+
+    /// Removes an empty directory.
+    pub fn remove_dir(&mut self, path: &str) -> FileSystemResult<()> {
+        let _path = Path::new(path)?;
+        todo!()
+    }
+
+    /// Removes a directory at this path, after removing all its contents. Use carefully!
+    pub fn remove_dir_all(&mut self, path: &str) -> FileSystemResult<()> {
+        let _path = Path::new(path)?;
+        todo!()
+    }
+
+    // Removes a file from the filesystem.
+    pub fn remove_file(&mut self, path: &str) -> FileSystemResult<()> {
+        let path = Path::new(path)?;
+
+        let file = self
+            .open_in_root(&path, UefiFileMode::ReadWrite)?
+            .into_type()
+            .unwrap();
+
+        match file {
+            FileType::Regular(file) => file.delete().map_err(|e| {
+                log::error!("error removing file: {e:?}");
+                FileSystemError::CantDeleteFile(path.as_str().to_string())
+            }),
+            FileType::Dir(_) => Err(FileSystemError::NotAFile(path.as_str().to_string())),
+        }
+    }
+
+    // Rename a file or directory to a new name, replacing the original file if it already exists.
+    pub fn rename(&mut self, src_path: &str, dest_path: &str) -> FileSystemResult<()> {
+        self.copy(src_path, dest_path)?;
+        self.remove_file(src_path)
+    }
+
+    /// Write a slice as the entire contents of a file. This function will create a file if it does
+    /// not exist, and will entirely replace its contents if it does.
+    pub fn write<C: AsRef<[u8]>>(&mut self, path: &str, content: C) -> FileSystemResult<()> {
+        let path = Path::new(path)?;
+
+        // since there is no .truncate() in UEFI, we delete the file first it it exists.
+        if self.try_exists(path.as_str()).is_ok() {
+            self.remove_file(path.as_str())?;
+        }
+
+        let mut handle = self
+            .open_in_root(&path, UefiFileMode::CreateReadWrite)?
+            .into_regular_file()
+            .unwrap();
+
+        handle.write(content.as_ref()).map_err(|e| {
+            log::error!("only wrote {e:?} bytes");
+            FileSystemError::WriteFailure
+        })?;
+        handle.flush().map_err(|e| {
+            log::error!("flush failure: {e:?}");
+            FileSystemError::FlushFailure
+        })?;
+        Ok(())
+    }
+
+    /// Resolves the [BoxedUefiFileInfo] of the final [Component].
+    /// For example, looks up fileinfo of "bar" in "/foo/bar". The returned fileinfo belongs to a
+    /// directory or a file.
+    ///
+    /// # Parameters
+    /// - `path`: whole user input for the path. Only required for error/debug information.
+    fn resolve_directory_entry_fileinfo(
+        &mut self,
+        path: &Path,
+    ) -> FileSystemResult<BoxedUefiFileInfo> {
+        let ucs2_filename = CString16::try_from(path.final_component().as_str()).unwrap();
+
+        let parent_dir = self.open_parent_dir_handle_of_path(path, UefiFileMode::Read)?;
+
+        // from my current knowledge, file info can only by obtained by iterating the parent dir
+        UefiDirectoryEntryIterator::new(parent_dir)
+            .find(|entry| entry.file_name() == ucs2_filename)
+            .ok_or(FileSystemError::FileNotFound(path.as_str().to_string()))
+    }
+
+    /// Opens a fresh handle to the root directory of the volume.
+    fn open_root(&mut self) -> FileSystemResult<UefiDirectoryHandle> {
+        let proto = unsafe { self.proto.interface.get().as_mut() }.unwrap();
+        proto.open_volume().map_err(|e| {
+            log::error!("Can't open root volume: {e:?}");
+            FileSystemError::CantOpenVolume
+        })
+    }
+
+    /// Wrapper around [Self::open_root] that opens the specified path. May create a file if
+    /// a corresonding [UefiFileMode] is set.
+    fn open_in_root(
+        &mut self,
+        path: &Path,
+        mode: UefiFileMode,
+    ) -> FileSystemResult<UefiFileHandle> {
+        let ucs2_path = CString16::try_from(path.as_str_without_root()).unwrap();
+
+        self.open_root()?
+            .open(&ucs2_path, mode, UefiFileAttribute::empty())
+            .map_err(|x| {
+                log::trace!("Can't open file {path}: {x:?}");
+                FileSystemError::OpenError(path.as_str().to_string())
+            })
+    }
+
+    /// Opens a handle to the parent directory of the final component provided by `path`.
+    fn open_parent_dir_handle_of_path(
+        &mut self,
+        path: &Path,
+        mode: UefiFileMode,
+    ) -> FileSystemResult<UefiDirectoryHandle> {
+        let mut parent_dir = self.open_root()?;
+        if let Some(path_to_parent_dir) = path.to_path_of_parent() {
+            // panic okay because the file must exist at that point (and thus, the parent dir)
+
+            let ucs2_path = CString16::try_from(path_to_parent_dir.as_str_without_root()).unwrap();
+            let filetype = parent_dir
+                .open(&ucs2_path, mode, UefiFileAttribute::empty())
+                .map_err(|e| {
+                    log::error!("Can't open directory: {e:?}");
+                    FileSystemError::OpenError(path.as_str().to_string())
+                })?
+                .into_type()
+                .expect("low level uefi error");
+            assert!(matches!(filetype, UefiFileType::Dir(_)));
+        }
+        Ok(parent_dir)
+    }
+}
+
+impl<'name, 'boot_services> Debug for FileSystem<'name, 'boot_services> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.debug_struct("FileSystem")
+            .field("name", &self.name)
+            .field("proto_ptr", &self.proto.interface.get())
+            .finish()
+    }
+}
+
+/* nothing to clean up manually
+impl<'name, 'boot_services> Drop for FileSystem<'name, 'boot_services> {
+    fn drop(&mut self) {
+        //
+    }
+}*/