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

@@ -12,7 +12,7 @@ pub const MAX_LFS_FILESIZE: i64 = bindings::MAX_LFS_FILESIZE;
 /// Read-only file systems.
 pub mod ro {
     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::Time, try_pin_init,
         ThisModule,
@@ -22,6 +22,9 @@ pub mod ro {
 
     /// A read-only file system type.
     pub trait Type {
+        /// 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;
 
@@ -178,7 +181,7 @@ pub mod ro {
                     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
@@ -199,10 +202,22 @@ pub mod ro {
             })
         }
 
-        unsafe extern "C" fn kill_sb_callback(sb_ptr: *mut bindings::super_block) {
+        unsafe extern "C" fn kill_sb_callback<T: Type + ?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) };
+            }
         }
     }
 
@@ -429,6 +444,15 @@ pub mod ro {
     pub struct SuperBlock<T: Type + ?Sized>(Opaque<bindings::super_block>, PhantomData<T>);
 
     impl<T: Type + ?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: u64) -> Result<Either<ARef<INode<T>>, NewINode<T>>> {
             // SAFETY: The only initialisation missing from the superblock is the root, and this
@@ -456,6 +480,14 @@ pub mod ro {
         }
     }
 
+    /// 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`].
@@ -477,17 +509,19 @@ pub mod ro {
 
     /// 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: Type + ?Sized> {
+    pub struct NewSuperBlock<'a, T: Type + ?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: Type + ?Sized> NewSuperBlock<'a, T> {
+    impl<'a, T: Type + ?Sized> NewSuperBlock<'a, T, NeedsInit> {
         /// Creates a new instance of [`NewSuperBlock`].
         ///
         /// # Safety
@@ -504,7 +538,11 @@ pub mod ro {
         }
 
         /// 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() };
 
@@ -521,27 +559,41 @@ pub mod ro {
             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: Type + ?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: Type + ?Sized> core::ops::Deref for NewSuperBlock<'_, T> {
+    impl<T: Type + ?Sized> core::ops::Deref for NewSuperBlock<'_, T, NeedsRoot> {
         type Target = SuperBlock<T>;
 
         fn deref(&self) -> &Self::Target {
@@ -909,6 +961,7 @@ pub mod ro {
     /// struct MyFs;
     /// impl fs::ro::Type for MyFs {
     ///     // ...
+    /// #    type Data = ();
     /// #    const NAME: &'static CStr = c_str!("myfs");
     /// #    fn fill_super(
     /// #        _: fs::ro::NewSuperBlock<'_, Self>

samples/rust/rust_rofs.rs

@@ -52,9 +52,19 @@ const ENTRIES: [Entry; 4] = [
 
 struct RoFs;
 impl fs::ro::Type 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::ro::Type 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(