rust: fs: add per-superblock data

This allows file systems to associate [typed] data to super blocks when
they're created. Since we only have a pointer-sized field in which to
store the state, it must implement the `ForeignOwnable` trait.

Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com>

Author: wedsonaf

rust/kernel/fs.rs

@@ -7,7 +7,7 @@
 //! C headers: [`include/linux/fs.h`](../../include/linux/fs.h)
 
 use crate::error::{code::*, from_result, to_result, Error, Result};
-use crate::types::{ARef, AlwaysRefCounted, Either, Opaque};
+use crate::types::{ARef, AlwaysRefCounted, Either, ForeignOwnable, Opaque};
 use crate::{
     bindings, folio::LockedFolio, init::PinInit, str::CStr, time::Timespec, try_pin_init,
     ThisModule,
@@ -20,6 +20,9 @@ pub const MAX_LFS_FILESIZE: i64 = bindings::MAX_LFS_FILESIZE;
 
 /// A file system type.
 pub trait FileSystem {
+    /// Data associated with each file system instance (super-block).
+    type Data: ForeignOwnable + Send + Sync;
+
     /// The name of the file system type.
     const NAME: &'static CStr;
 
@@ -168,7 +171,7 @@ impl Registration {
                 fs.owner = module.0;
                 fs.name = T::NAME.as_char_ptr();
                 fs.init_fs_context = Some(Self::init_fs_context_callback::<T>);
-                fs.kill_sb = Some(Self::kill_sb_callback);
+                fs.kill_sb = Some(Self::kill_sb_callback::<T>);
                 fs.fs_flags = 0;
 
                 // SAFETY: Pointers stored in `fs` are static so will live for as long as the
@@ -189,10 +192,22 @@ impl Registration {
         })
     }
 
-    unsafe extern "C" fn kill_sb_callback(sb_ptr: *mut bindings::super_block) {
+    unsafe extern "C" fn kill_sb_callback<T: FileSystem + ?Sized>(
+        sb_ptr: *mut bindings::super_block,
+    ) {
         // SAFETY: In `get_tree_callback` we always call `get_tree_nodev`, so `kill_anon_super` is
         // the appropriate function to call for cleanup.
         unsafe { bindings::kill_anon_super(sb_ptr) };
+
+        // SAFETY: The C API contract guarantees that `sb_ptr` is valid for read.
+        let ptr = unsafe { (*sb_ptr).s_fs_info };
+        if !ptr.is_null() {
+            // SAFETY: The only place where `s_fs_info` is assigned is `NewSuperBlock::init`, where
+            // it's initialised with the result of an `into_foreign` call. We checked above that
+            // `ptr` is non-null because it would be null if we never reached the point where we
+            // init the field.
+            unsafe { T::Data::from_foreign(ptr) };
+        }
     }
 }
 
@@ -423,6 +438,14 @@ pub struct INodeParams {
 pub struct SuperBlock<T: FileSystem + ?Sized>(Opaque<bindings::super_block>, PhantomData<T>);
 
 impl<T: FileSystem + ?Sized> SuperBlock<T> {
+    /// Returns the data associated with the superblock.
+    pub fn data(&self) -> <T::Data as ForeignOwnable>::Borrowed<'_> {
+        // SAFETY: This method is only available after the `NeedsData` typestate, so `s_fs_info`
+        // has been initialised initialised with the result of a call to `T::into_foreign`.
+        let ptr = unsafe { (*self.0.get()).s_fs_info };
+        unsafe { T::Data::borrow(ptr) }
+    }
+
     /// Tries to get an existing inode or create a new one if it doesn't exist yet.
     pub fn get_or_create_inode(&self, ino: Ino) -> Result<Either<ARef<INode<T>>, NewINode<T>>> {
         // SAFETY: The only initialisation missing from the superblock is the root, and this
@@ -449,6 +472,14 @@ impl<T: FileSystem + ?Sized> SuperBlock<T> {
     }
 }
 
+/// State of [`NewSuperBlock`] that indicates that [`NewSuperBlock::init`] needs to be called
+/// eventually.
+pub struct NeedsInit;
+
+/// State of [`NewSuperBlock`] that indicates that [`NewSuperBlock::init_root`] needs to be called
+/// eventually.
+pub struct NeedsRoot;
+
 /// Required superblock parameters.
 ///
 /// This is used in [`NewSuperBlock::init`].
@@ -470,17 +501,19 @@ pub struct SuperParams {
 
 /// A superblock that is still being initialised.
 ///
+//// It uses type states to ensure that callers use the right sequence of calls.
+///
 /// # Invariants
 ///
 /// The superblock is a newly-created one and this is the only active pointer to it.
-pub struct NewSuperBlock<'a, T: FileSystem + ?Sized> {
+pub struct NewSuperBlock<'a, T: FileSystem + ?Sized, S = NeedsInit> {
     sb: &'a mut SuperBlock<T>,
 
     // This also forces `'a` to be invariant.
-    _p: PhantomData<&'a mut &'a ()>,
+    _p: PhantomData<&'a mut &'a S>,
 }
 
-impl<'a, T: FileSystem + ?Sized> NewSuperBlock<'a, T> {
+impl<'a, T: FileSystem + ?Sized> NewSuperBlock<'a, T, NeedsInit> {
     /// Creates a new instance of [`NewSuperBlock`].
     ///
     /// # Safety
@@ -496,7 +529,11 @@ impl<'a, T: FileSystem + ?Sized> NewSuperBlock<'a, T> {
     }
 
     /// Initialises the superblock.
-    pub fn init(self, params: &SuperParams, root: ARef<INode<T>>) -> Result<&'a SuperBlock<T>> {
+    pub fn init(
+        self,
+        params: &SuperParams,
+        data: T::Data,
+    ) -> Result<NewSuperBlock<'a, T, NeedsRoot>> {
         // SAFETY: Since this is a new super block, we hold the only reference to it.
         let sb = unsafe { &mut *self.sb.0.get() };
 
@@ -513,27 +550,42 @@ impl<'a, T: FileSystem + ?Sized> NewSuperBlock<'a, T> {
         sb.s_blocksize = 1 << sb.s_blocksize_bits;
         sb.s_flags |= bindings::SB_RDONLY;
 
+        // No failures are allowed beyond this point, otherwise we'll leak `data`.
+        sb.s_fs_info = data.into_foreign().cast_mut();
+
+        Ok(NewSuperBlock {
+            sb: self.sb,
+            _p: PhantomData,
+        })
+    }
+}
+
+impl<'a, T: FileSystem + ?Sized> NewSuperBlock<'a, T, NeedsRoot> {
+    /// Initialises the root of the superblock.
+    pub fn init_root(self, inode: ARef<INode<T>>) -> Result<&'a SuperBlock<T>> {
         // Reject root inode if it belongs to a different superblock.
-        if !ptr::eq(root.super_block(), self.sb) {
+        if !ptr::eq(inode.super_block(), self.sb) {
             return Err(EINVAL);
         }
 
         // SAFETY: `d_make_root` requires that `inode` be valid and referenced, which is the case
         // for this call.
         //
         // It takes over the inode, even on failure, so we don't need to clean it up.
-        let dentry = unsafe { bindings::d_make_root(ManuallyDrop::new(root).0.get()) };
+        let dentry = unsafe { bindings::d_make_root(ManuallyDrop::new(inode).0.get()) };
         if dentry.is_null() {
             return Err(ENOMEM);
         }
 
+        // SAFETY: Since this is a new superblock, we hold the only reference to it.
+        let sb = unsafe { &mut *self.sb.0.get() };
         sb.s_root = dentry;
 
         Ok(self.sb)
     }
 }
 
-impl<T: FileSystem + ?Sized> core::ops::Deref for NewSuperBlock<'_, T> {
+impl<T: FileSystem + ?Sized> core::ops::Deref for NewSuperBlock<'_, T, NeedsRoot> {
     type Target = SuperBlock<T>;
 
     fn deref(&self) -> &Self::Target {
@@ -956,6 +1008,7 @@ impl<T: FileSystem + ?Sized + Sync + Send> crate::InPlaceModule for Module<T> {
 ///
 /// struct MyFs;
 /// impl fs::FileSystem for MyFs {
+///     type Data = ();
 ///     const NAME: &'static CStr = c_str!("myfs");
 ///     fn fill_super(_: NewSuperBlock<'_, Self>) -> Result<&SuperBlock<Self>> {
 ///         todo!()

samples/rust/rust_rofs.rs

@@ -52,9 +52,19 @@ const ENTRIES: [Entry; 4] = [
 
 struct RoFs;
 impl fs::FileSystem for RoFs {
+    type Data = ();
     const NAME: &'static CStr = c_str!("rust-fs");
 
     fn fill_super(sb: NewSuperBlock<'_, Self>) -> Result<&SuperBlock<Self>> {
+        let sb = sb.init(
+            &SuperParams {
+                magic: 0x52555354,
+                blocksize_bits: 12,
+                maxbytes: fs::MAX_LFS_FILESIZE,
+                time_gran: 1,
+            },
+            (),
+        )?;
         let root = match sb.get_or_create_inode(1)? {
             Either::Left(existing) => existing,
             Either::Right(new) => new.init(INodeParams {
@@ -70,15 +80,7 @@ impl fs::FileSystem for RoFs {
                 mtime: UNIX_EPOCH,
             })?,
         };
-        sb.init(
-            &SuperParams {
-                magic: 0x52555354,
-                blocksize_bits: 12,
-                maxbytes: fs::MAX_LFS_FILESIZE,
-                time_gran: 1,
-            },
-            root,
-        )
+        sb.init_root(root)
     }
 
     fn read_dir(inode: &INode<Self>, emitter: &mut DirEmitter) -> Result {