Document filesystem support. This is related to

issue #74 Document COCONUT-SVSM.

Signed-off-by: Vasant Karasulli <[email protected]>

src/fs/api.rs

@@ -18,6 +18,8 @@ use packit::PackItError;
 const MAX_FILENAME_LENGTH: usize = 64;
 pub type FileName = FixedString<MAX_FILENAME_LENGTH>;
 
+/// Represents the type of error occured
+/// while doing SVSM filesystem operations.
 #[derive(Copy, Clone, Debug, Default)]
 pub enum FsError {
     #[default]
@@ -45,6 +47,7 @@ impl From<PackItError> for SvsmError {
     }
 }
 
+/// Used to define methods of [`FsError`].
 macro_rules! impl_fs_err {
     ($name:ident, $v:ident) => {
         pub fn $name() -> Self {
@@ -59,32 +62,140 @@ impl FsError {
     impl_fs_err!(file_not_found, FileNotFound);
 }
 
+/// Represents file operations
 pub trait File: Debug + Send + Sync {
+    /// Used to read contents of a file
+    ///
+    /// # Arguments
+    ///
+    /// - `buf`: buffer to read the file contents into.
+    /// - `offset`: file offset to read from.
+    ///
+    /// # Returns
+    ///
+    /// [`Result<usize, SvsmError>`]: A [`Result`] containing the number of
+    /// bytes read if successful, or an [`SvsmError`] if there was a problem
+    /// during the read operation.
     fn read(&self, buf: &mut [u8], offset: usize) -> Result<usize, SvsmError>;
+
+    /// Used to write contents to a file
+    ///
+    /// # Arguments
+    ///
+    /// - `buf`: buffer which holds the contents to be written to the file.
+    /// - `offset`: file offset to write to.
+    ///
+    /// # Returns
+    ///
+    /// [`Result<usize, SvsmError>`]: A [`Result`] containing the number of
+    /// bytes written if successful, or an [`SvsmError`] if there was a problem
+    /// during the write operation.
     fn write(&self, buf: &[u8], offset: usize) -> Result<usize, SvsmError>;
+
+    /// Used to truncate the file to the specified size.
+    ///
+    ///  # Arguments
+    ///
+    ///  - `size`: specifies the size in bytes to which the file
+    ///  is to be truncated.
+    ///
+    ///  # Returns
+    ///
+    /// [`Result<usize, SvsmError>`]: A [`Result`] containing the size of the
+    /// file after truncation if successful, or an [`SvsmError`] if there was
+    /// a problem during the truncate operation.
     fn truncate(&self, size: usize) -> Result<usize, SvsmError>;
+
+    /// Used to get the size of the file.
+    ///
+    /// # Returns
+    ///
+    /// size of the file in bytes.
     fn size(&self) -> usize;
 }
 
+/// Represents directory operations
 pub trait Directory: Debug + Send + Sync {
+    /// Used to get the list of entries in the directory.
+    ///
+    /// # Returns
+    ///
+    /// A [`Vec<FileName>`] containing all the entries in the directory.
     fn list(&self) -> Vec<FileName>;
+
+    /// Used to lookup for an entry in the directory.
+    ///
+    /// # Arguments
+    ///
+    /// - `name`: name of the entry to be looked up in the directory.
+    ///
+    /// # Returns
+    ///
+    /// [`Result<DirEntry, SvsmError>`]: A [`Result`] containing the [`DirEntry`]
+    /// corresponding to the entry being looked up in the directory if present, or
+    /// an [`SvsmError`] if not present.
     fn lookup_entry(&self, name: FileName) -> Result<DirEntry, SvsmError>;
+
+    /// Used to create a new file in the directory.
+    ///
+    /// # Arguments
+    ///
+    /// - `name`: name of the file to be created.
+    ///
+    /// # Returns
+    ///
+    /// [`Result<DirEntry, SvsmError>`]: A [`Result`] containing the [`DirEntry`]
+    /// of the new file created on success, or an [`SvsmError`] on failure
     fn create_file(&self, name: FileName) -> Result<Arc<dyn File>, SvsmError>;
+
+    /// Used to create a subdirectory in the directory.
+    ///
+    /// # Arguments
+    ///
+    /// - `name`: name of the subdirectory to be created.
+    ///
+    /// # Returns
+    ///
+    /// [`Result<DirEntry, SvsmError>`]: A [`Result`] containing the [`DirEntry`]
+    /// of the subdirectory created on success, or an [`SvsmError`] on failure
     fn create_directory(&self, name: FileName) -> Result<Arc<dyn Directory>, SvsmError>;
+
+    /// Used to remove an entry from the directory.
+    ///
+    /// # Arguments
+    ///
+    /// - `name`: name of the entry to be removed from the directory.
+    ///
+    /// # Returns
+    ///
+    /// [`Result<(), SvsmError>`]: A [`Result`] containing the empty
+    /// value on success, or an [`SvsmError`] on failure
     fn unlink(&self, name: FileName) -> Result<(), SvsmError>;
 }
 
+/// Represents a directory entry which could
+/// either be a file or a subdirectory.
 #[derive(Debug)]
 pub enum DirEntry {
     File(Arc<dyn File>),
     Directory(Arc<dyn Directory>),
 }
 
 impl DirEntry {
+    /// Used to check if a [`DirEntry`] variable is a file.
+    ///
+    /// # Returns
+    ///
+    /// ['true'] if [`DirEntry`] is a file, ['false'] otherwise.
     pub fn is_file(&self) -> bool {
         matches!(self, Self::File(_))
     }
 
+    /// Used to check if a [`DirEntry`] variable is a directory.
+    ///
+    /// # Returns
+    ///
+    /// ['true'] if [`DirEntry`] is a directory, ['false'] otherwise.
     pub fn is_dir(&self) -> bool {
         matches!(self, Self::Directory(_))
     }
@@ -99,13 +210,24 @@ impl Clone for DirEntry {
     }
 }
 
+/// Directory entries including their names.
 #[derive(Debug)]
 pub struct DirectoryEntry {
     pub name: FileName,
     pub entry: DirEntry,
 }
 
 impl DirectoryEntry {
+    /// Create a new [`DirectoryEntry`] instance.
+    ///
+    /// # Arguments
+    ///
+    /// - `name`: name for the entry to be created.
+    /// - `entry`: [`DirEntry`] containing the file or directory details.
+    ///
+    /// # Returns
+    ///
+    /// A new [`DirectoryEntry`] instance.
     pub fn new(name: FileName, entry: DirEntry) -> Self {
         DirectoryEntry { name, entry }
     }