[RFC PATCH 10/19] rust: fs: introduce `FileSystem::read_folio`

[Wedson Almeida Filho <wedsonaf@gmail.com>]

From: Wedson Almeida Filho <walmeida@microsoft.com>

Allow Rust file systems to create regular file inodes backed by the page
cache. The contents of such files are read into folios via `read_folio`.

Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com>
---
 rust/kernel/folio.rs      |  1 -
 rust/kernel/fs.rs         | 75 +++++++++++++++++++++++++++++++++++++--
 samples/rust/rust_rofs.rs | 69 ++++++++++++++++++++++++-----------
 3 files changed, 122 insertions(+), 23 deletions(-)

diff --git a/rust/kernel/folio.rs b/rust/kernel/folio.rs
index ef8a08b97962..b7f80291b0e1 100644
--- a/rust/kernel/folio.rs
+++ b/rust/kernel/folio.rs
@@ -123,7 +123,6 @@ impl LockedFolio<'_> {
     /// Callers must ensure that the folio is valid and locked. Additionally, that the
     /// responsibility of unlocking is transferred to the new instance of [`LockedFolio`]. Lastly,
     /// that the returned [`LockedFolio`] doesn't outlive the refcount that keeps it alive.
-    #[allow(dead_code)]
     pub(crate) unsafe fn from_raw(folio: *const bindings::folio) -> Self {
         let ptr = folio.cast();
         // SAFETY: The safety requirements ensure that `folio` (from which `ptr` is derived) is
diff --git a/rust/kernel/fs.rs b/rust/kernel/fs.rs
index 681fef8e3af1..ee3dce87032b 100644
--- a/rust/kernel/fs.rs
+++ b/rust/kernel/fs.rs
@@ -8,7 +8,10 @@
 
 use crate::error::{code::*, from_result, to_result, Error, Result};
 use crate::types::{ARef, AlwaysRefCounted, Either, Opaque};
-use crate::{bindings, init::PinInit, str::CStr, time::Timespec, try_pin_init, ThisModule};
+use crate::{
+    bindings, folio::LockedFolio, init::PinInit, str::CStr, time::Timespec, try_pin_init,
+    ThisModule,
+};
 use core::{marker::PhantomData, marker::PhantomPinned, mem::ManuallyDrop, pin::Pin, ptr};
 use macros::{pin_data, pinned_drop};
 
@@ -36,6 +39,9 @@ pub trait FileSystem {
 
     /// Returns the inode corresponding to the directory entry with the given name.
     fn lookup(parent: &INode<Self>, name: &[u8]) -> Result<ARef<INode<Self>>>;
+
+    /// Reads the contents of the inode into the given folio.
+    fn read_folio(inode: &INode<Self>, folio: LockedFolio<'_>) -> Result;
 }
 
 /// The types of directory entries reported by [`FileSystem::read_dir`].
@@ -74,6 +80,7 @@ impl From<INodeType> for DirEntryType {
     fn from(value: INodeType) -> Self {
         match value {
             INodeType::Dir => DirEntryType::Dir,
+            INodeType::Reg => DirEntryType::Reg,
         }
     }
 }
@@ -232,6 +239,15 @@ pub fn init(self, params: INodeParams) -> Result<ARef<INode<T>>> {
                 inode.i_op = &Tables::<T>::DIR_INODE_OPERATIONS;
                 bindings::S_IFDIR
             }
+            INodeType::Reg => {
+                // SAFETY: `generic_ro_fops` never changes, it's safe to reference it.
+                inode.__bindgen_anon_3.i_fop = unsafe { &bindings::generic_ro_fops };
+                inode.i_data.a_ops = &Tables::<T>::FILE_ADDRESS_SPACE_OPERATIONS;
+
+                // SAFETY: The `i_mapping` pointer doesn't change and is valid.
+                unsafe { bindings::mapping_set_large_folios(inode.i_mapping) };
+                bindings::S_IFREG
+            }
         };
 
         inode.i_mode = (params.mode & 0o777) | u16::try_from(mode)?;
@@ -268,6 +284,9 @@ fn drop(&mut self) {
 pub enum INodeType {
     /// Directory type.
     Dir,
+
+    /// Regular file type.
+    Reg,
 }
 
 /// Required inode parameters.
@@ -588,6 +607,55 @@ extern "C" fn lookup_callback(
             },
         }
     }
+
+    const FILE_ADDRESS_SPACE_OPERATIONS: bindings::address_space_operations =
+        bindings::address_space_operations {
+            writepage: None,
+            read_folio: Some(Self::read_folio_callback),
+            writepages: None,
+            dirty_folio: None,
+            readahead: None,
+            write_begin: None,
+            write_end: None,
+            bmap: None,
+            invalidate_folio: None,
+            release_folio: None,
+            free_folio: None,
+            direct_IO: None,
+            migrate_folio: None,
+            launder_folio: None,
+            is_partially_uptodate: None,
+            is_dirty_writeback: None,
+            error_remove_page: None,
+            swap_activate: None,
+            swap_deactivate: None,
+            swap_rw: None,
+        };
+
+    extern "C" fn read_folio_callback(
+        _file: *mut bindings::file,
+        folio: *mut bindings::folio,
+    ) -> i32 {
+        from_result(|| {
+            // SAFETY: All pointers are valid and stable.
+            let inode = unsafe {
+                &*(*(*folio)
+                    .__bindgen_anon_1
+                    .page
+                    .__bindgen_anon_1
+                    .__bindgen_anon_1
+                    .mapping)
+                    .host
+                    .cast::<INode<T>>()
+            };
+
+            // SAFETY: The C contract guarantees that the folio is valid and locked, with ownership
+            // of the lock transferred to the callee (this function). The folio is also guaranteed
+            // not to outlive this function.
+            T::read_folio(inode, unsafe { LockedFolio::from_raw(folio) })?;
+            Ok(0)
+        })
+    }
 }
 
 /// Directory entry emitter.
@@ -673,7 +741,7 @@ fn init(module: &'static ThisModule) -> impl PinInit<Self, Error> {
 /// # mod module_fs_sample {
 /// use kernel::fs::{DirEmitter, INode, NewSuperBlock, SuperBlock, SuperParams};
 /// use kernel::prelude::*;
-/// use kernel::{c_str, fs, types::ARef};
+/// use kernel::{c_str, folio::LockedFolio, fs, types::ARef};
 ///
 /// kernel::module_fs! {
 ///     type: MyFs,
@@ -698,6 +766,9 @@ fn init(module: &'static ThisModule) -> impl PinInit<Self, Error> {
 ///     fn lookup(_: &INode<Self>, _: &[u8]) -> Result<ARef<INode<Self>>> {
 ///         todo!()
 ///     }
+///     fn read_folio(_: &INode<Self>, _: LockedFolio<'_>) -> Result {
+///         todo!()
+///     }
 /// }
 /// # }
 /// ```
diff --git a/samples/rust/rust_rofs.rs b/samples/rust/rust_rofs.rs
index 4cc8525884a9..ef651ad38185 100644
--- a/samples/rust/rust_rofs.rs
+++ b/samples/rust/rust_rofs.rs
@@ -6,7 +6,7 @@
     DirEmitter, INode, INodeParams, INodeType, NewSuperBlock, SuperBlock, SuperParams,
 };
 use kernel::prelude::*;
-use kernel::{c_str, fs, time::UNIX_EPOCH, types::ARef, types::Either};
+use kernel::{c_str, folio::LockedFolio, fs, time::UNIX_EPOCH, types::ARef, types::Either};
 
 kernel::module_fs! {
     type: RoFs,
@@ -20,6 +20,7 @@ struct Entry {
     name: &'static [u8],
     ino: u64,
     etype: INodeType,
+    contents: &'static [u8],
 }
 
 const ENTRIES: [Entry; 3] = [
@@ -27,16 +28,19 @@ struct Entry {
         name: b".",
         ino: 1,
         etype: INodeType::Dir,
+        contents: b"",
     },
     Entry {
         name: b"..",
         ino: 1,
         etype: INodeType::Dir,
+        contents: b"",
     },
     Entry {
-        name: b"subdir",
+        name: b"test.txt",
         ino: 2,
-        etype: INodeType::Dir,
+        etype: INodeType::Reg,
+        contents: b"hello\n",
     },
 ];
 
@@ -95,23 +99,48 @@ fn lookup(parent: &INode<Self>, name: &[u8]) -> Result<ARef<INode<Self>>> {
             return Err(ENOENT);
         }
 
-        match name {
-            b"subdir" => match parent.super_block().get_or_create_inode(2)? {
-                Either::Left(existing) => Ok(existing),
-                Either::Right(new) => new.init(INodeParams {
-                    typ: INodeType::Dir,
-                    mode: 0o555,
-                    size: 0,
-                    blocks: 1,
-                    nlink: 2,
-                    uid: 0,
-                    gid: 0,
-                    atime: UNIX_EPOCH,
-                    ctime: UNIX_EPOCH,
-                    mtime: UNIX_EPOCH,
-                }),
-            },
-            _ => Err(ENOENT),
+        for e in &ENTRIES {
+            if name == e.name {
+                return match parent.super_block().get_or_create_inode(e.ino)? {
+                    Either::Left(existing) => Ok(existing),
+                    Either::Right(new) => new.init(INodeParams {
+                        typ: e.etype,
+                        mode: 0o444,
+                        size: e.contents.len().try_into()?,
+                        blocks: 1,
+                        nlink: 1,
+                        uid: 0,
+                        gid: 0,
+                        atime: UNIX_EPOCH,
+                        ctime: UNIX_EPOCH,
+                        mtime: UNIX_EPOCH,
+                    }),
+                };
+            }
         }
+
+        Err(ENOENT)
+    }
+
+    fn read_folio(inode: &INode<Self>, mut folio: LockedFolio<'_>) -> Result {
+        let data = match inode.ino() {
+            2 => ENTRIES[2].contents,
+            _ => return Err(EINVAL),
+        };
+
+        let pos = usize::try_from(folio.pos()).unwrap_or(usize::MAX);
+        let copied = if pos >= data.len() {
+            0
+        } else {
+            let to_copy = core::cmp::min(data.len() - pos, folio.size());
+            folio.write(0, &data[pos..][..to_copy])?;
+            to_copy
+        };
+
+        folio.zero_out(copied, folio.size() - copied)?;
+        folio.mark_uptodate();
+        folio.flush_dcache();
+
+        Ok(())
     }
 }
-- 
2.34.1