Share context with file instances based on registration.

Author: wedsonaf

drivers/char/rust_example.rs

@@ -11,7 +11,7 @@ use core::pin::Pin;
 use kernel::prelude::*;
 use kernel::{
     chrdev, condvar_init, cstr,
-    file_operations::FileOperations,
+    file_operations::{FileOpener, FileOperations},
     miscdev, mutex_init, spinlock_init,
     sync::{CondVar, Mutex, SpinLock},
 };
@@ -53,15 +53,17 @@ module! {
 
 struct RustFile;
 
+impl FileOpener<()> for RustFile {
+    fn open(_ctx: &()) -> KernelResult<Self::Wrapper> {
+        println!("rust file was opened!");
+        Ok(Box::try_new(Self)?)
+    }
+}
+
 impl FileOperations for RustFile {
     type Wrapper = Box<Self>;
 
     kernel::declare_file_operations!();
-
-    fn open() -> KernelResult<Self::Wrapper> {
-        println!("rust file was opened!");
-        Ok(Box::try_new(Self)?)
-    }
 }
 
 struct RustExample {
@@ -150,7 +152,7 @@ impl KernelModule for RustExample {
 
         Ok(RustExample {
             message: "on the heap!".to_owned(),
-            _dev: miscdev::Registration::new_pinned::<RustFile>(cstr!("rust_miscdev"), None)?,
+            _dev: miscdev::Registration::new_pinned::<RustFile>(cstr!("rust_miscdev"), None, ())?,
             _chrdev: chrdev_reg,
         })
     }

rust/kernel/chrdev.rs

@@ -78,7 +78,7 @@ impl<const N: usize> Registration<{ N }> {
     /// Registers a character device.
     ///
     /// You may call this once per device type, up to `N` times.
-    pub fn register<T: file_operations::FileOperations>(self: Pin<&mut Self>) -> KernelResult {
+    pub fn register<T: file_operations::FileOpener<()>>(self: Pin<&mut Self>) -> KernelResult {
         // SAFETY: We must ensure that we never move out of `this`.
         let this = unsafe { self.get_unchecked_mut() };
         if this.inner.is_none() {
@@ -112,7 +112,10 @@ impl<const N: usize> Registration<{ N }> {
         // SAFETY: Calling unsafe functions and manipulating `MaybeUninit`
         // pointer.
         unsafe {
-            bindings::cdev_init(cdev, &file_operations::FileOperationsVtable::<T>::VTABLE);
+            bindings::cdev_init(
+                cdev,
+                &file_operations::FileOperationsVtable::<Self, T>::VTABLE,
+            );
             (*cdev).owner = this.this_module.0;
             let rc = bindings::cdev_add(cdev, inner.dev + inner.used as bindings::dev_t, 1);
             if rc != 0 {
@@ -124,6 +127,17 @@ impl<const N: usize> Registration<{ N }> {
     }
 }
 
+impl<const N: usize> file_operations::FileOpenAdapter for Registration<{ N }> {
+    type Arg = ();
+
+    unsafe fn convert(
+        _inode: *mut bindings::inode,
+        _file: *mut bindings::file,
+    ) -> *const Self::Arg {
+        &()
+    }
+}
+
 // SAFETY: `Registration` does not expose any of its state across threads
 // (it is fine for multiple threads to have a shared reference to it).
 unsafe impl<const N: usize> Sync for Registration<{ N }> {}

rust/kernel/file_operations.rs

@@ -81,12 +81,13 @@ macro_rules! from_kernel_result {
     }};
 }
 
-unsafe extern "C" fn open_callback<T: FileOperations>(
-    _inode: *mut bindings::inode,
+unsafe extern "C" fn open_callback<A: FileOpenAdapter, T: FileOpener<A::Arg>>(
+    inode: *mut bindings::inode,
     file: *mut bindings::file,
 ) -> c_types::c_int {
     from_kernel_result! {
-        let ptr = T::open()?.into_pointer();
+        let arg = A::convert(inode, file);
+        let ptr = T::open(&*arg)?.into_pointer();
         (*file).private_data = ptr as *mut c_types::c_void;
         Ok(0)
     }
@@ -199,11 +200,11 @@ unsafe extern "C" fn fsync_callback<T: FileOperations>(
     }
 }
 
-pub(crate) struct FileOperationsVtable<T>(marker::PhantomData<T>);
+pub(crate) struct FileOperationsVtable<A, T>(marker::PhantomData<A>, marker::PhantomData<T>);
 
-impl<T: FileOperations> FileOperationsVtable<T> {
+impl<A: FileOpenAdapter, T: FileOpener<A::Arg>> FileOperationsVtable<A, T> {
     pub(crate) const VTABLE: bindings::file_operations = bindings::file_operations {
-        open: Some(open_callback::<T>),
+        open: Some(open_callback::<A, T>),
         release: Some(release_callback::<T>),
         read: if T::TO_USE.read {
             Some(read_callback::<T>)
@@ -410,6 +411,39 @@ impl IoctlCommand {
     }
 }
 
+/// Trait for extracting file open arguments from kernel data structures.
+///
+/// This is meant to be implemented by registration managers.
+pub trait FileOpenAdapter {
+    /// The type of argument this adpter extracts.
+    type Arg;
+
+    /// Converts untyped data stored in [`struct inode`] and [`struct file`] (when [`struct
+    /// file_operations::open`] is called) into the given type. For example, for `miscdev`
+    /// devices, a pointer to the registered [`struct miscdev`] is stored in [`struct
+    /// file::private_data`].
+    ///
+    /// # Safety
+    ///
+    /// This function must be called only when [`struct file_operations::open`] is being called for
+    /// a file that was registered by the implementer.
+    unsafe fn convert(_inode: *mut bindings::inode, _file: *mut bindings::file)
+        -> *const Self::Arg;
+}
+
+/// Trait for implementers of kernel files.
+///
+/// In addition to the methods in [`FileOperations`], implementers must also provide
+/// [`FileOpener::open`] with a customised argument. This allows a single implementation of
+/// [`FileOperations`] to be used for different types of registrations, for example, `miscdev` and
+/// `chrdev`.
+pub trait FileOpener<T: ?Sized>: FileOperations {
+    /// Creates a new instance of this file.
+    ///
+    /// Corresponds to the `open` function pointer in `struct file_operations`.
+    fn open(context: &T) -> KernelResult<Self::Wrapper>;
+}
+
 /// Corresponds to the kernel's `struct file_operations`.
 ///
 /// You implement this trait whenever you would create a `struct file_operations`.
@@ -423,11 +457,6 @@ pub trait FileOperations: Sync + Sized {
     /// The pointer type that will be used to hold ourselves.
     type Wrapper: PointerWrapper<Self>;
 
-    /// Creates a new instance of this file.
-    ///
-    /// Corresponds to the `open` function pointer in `struct file_operations`.
-    fn open() -> KernelResult<Self::Wrapper>;
-
     /// Cleans up after the last reference to the file goes away.
     ///
     /// Note that the object is moved, so it will be freed automatically unless the implementation
@@ -502,7 +531,7 @@ impl<T> PointerWrapper<T> for Box<T> {
     }
 
     unsafe fn from_pointer(ptr: *const T) -> Self {
-        Box::<T>::from_raw(ptr as _)
+        Box::from_raw(ptr as _)
     }
 }
 
@@ -512,6 +541,6 @@ impl<T> PointerWrapper<T> for Arc<T> {
     }
 
     unsafe fn from_pointer(ptr: *const T) -> Self {
-        Arc::<T>::from_raw(ptr)
+        Arc::from_raw(ptr)
     }
 }

rust/kernel/lib.rs

@@ -140,5 +140,50 @@ fn panic(_info: &PanicInfo) -> ! {
     }
 }
 
+/// Calculates the offset of a field from the beginning of the struct it belongs to.
+#[macro_export]
+macro_rules! offset_of {
+    ($type:ty, $($f:tt)*) => {{
+        let tmp = core::mem::MaybeUninit::<$type>::uninit();
+        let ptr = tmp.as_ptr();
+        #[allow(unused_unsafe)]
+        let dev = unsafe { core::ptr::addr_of!((*ptr).$($f)*) as *const u8 };
+        #[allow(unused_unsafe)]
+        unsafe { dev.offset_from(ptr as *const u8) }
+    }}
+}
+
+/// Produces a pointer to an object from a pointer to one of its fields.
+///
+/// # Safety
+///
+/// Callers must ensure that the pointer to the field is in fact a pointer to the specified field,
+/// as opposed to a pointer to another object of the same type.
+///
+/// # Example
+///
+///```
+/// struct Test {
+///     a: u64,
+///     b: u32,
+/// }
+///
+/// fn test() {
+///     let test = Test{a: 10, b: 20};
+///     let b_ptr = &test.b;
+///     let test_alias = unsafe { container_of!(b_ptr, Test, b) };
+///     // This prints `true`.
+///     println!("{}", core::ptr::eq(&test, test_alias));
+/// }
+///```
+///
+#[macro_export]
+macro_rules! container_of {
+    ($ptr:expr, $type:ty, $($f:tt)*) => {{
+        let offset = $crate::offset_of!($type, $($f)*);
+        ($ptr as *const _ as *const u8).offset(-offset) as *const $type
+    }}
+}
+
 #[global_allocator]
 static ALLOCATOR: allocator::KernelAllocator = allocator::KernelAllocator;

rust/kernel/miscdev.rs

@@ -7,91 +7,97 @@
 //! Reference: <https://www.kernel.org/doc/html/latest/driver-api/misc_devices.html>
 
 use crate::error::{Error, KernelResult};
-use crate::file_operations::{FileOperations, FileOperationsVtable};
+use crate::file_operations::{FileOpenAdapter, FileOpener, FileOperationsVtable};
 use crate::{bindings, c_types, CStr};
 use alloc::boxed::Box;
 use core::marker::PhantomPinned;
 use core::pin::Pin;
 
 /// A registration of a miscellaneous device.
-pub struct Registration {
-    mdev: Option<bindings::miscdevice>,
+pub struct Registration<T: Sync = ()> {
+    registered: bool,
+    mdev: bindings::miscdevice,
     _pin: PhantomPinned,
+
+    /// Context initialised on construction and made available to all file instances on
+    /// [`FileOpener::open`].
+    pub context: T,
 }
 
-impl Registration {
+// SAFETY: The only method is `register()`, which requires a (pinned) mutable `Registration`, so it
+// is safe to pass `&Registration` to multiple threads because it offers no interior mutability,
+// except maybe through [`Registration::context`], but it is itself [`Sync`].
+unsafe impl<T: Sync> Sync for Registration<T> {}
+
+impl<T: Sync> Registration<T> {
     /// Creates a new [`Registration`] but does not register it yet.
     ///
     /// It is allowed to move.
-    pub fn new() -> Self {
+    pub fn new(context: T) -> Self {
         Self {
-            mdev: None,
+            registered: false,
+            mdev: bindings::miscdevice::default(),
             _pin: PhantomPinned,
+            context,
         }
     }
 
     /// Registers a miscellaneous device.
     ///
     /// Returns a pinned heap-allocated representation of the registration.
-    pub fn new_pinned<T: FileOperations>(
+    pub fn new_pinned<F: FileOpener<T>>(
         name: CStr<'static>,
         minor: Option<i32>,
+        state: T,
     ) -> KernelResult<Pin<Box<Self>>> {
-        let mut r = Pin::from(Box::try_new(Self::new())?);
-        r.as_mut().register::<T>(name, minor)?;
+        let mut r = Pin::from(Box::try_new(Self::new(state))?);
+        r.as_mut().register::<F>(name, minor)?;
         Ok(r)
     }
 
     /// Registers a miscellaneous device with the rest of the kernel.
     ///
-    /// It must be pinned because the memory block that represents the
-    /// registration is self-referential. If a minor is not given, the kernel
-    /// allocates a new one if possible.
-    pub fn register<T: FileOperations>(
+    /// It must be pinned because the memory block that represents the registration is
+    /// self-referential. If a minor is not given, the kernel allocates a new one if possible.
+    pub fn register<F: FileOpener<T>>(
         self: Pin<&mut Self>,
         name: CStr<'static>,
         minor: Option<i32>,
     ) -> KernelResult {
         // SAFETY: We must ensure that we never move out of `this`.
         let this = unsafe { self.get_unchecked_mut() };
-        if this.mdev.is_some() {
+        if this.registered {
             // Already registered.
             return Err(Error::EINVAL);
         }
 
-        this.mdev = Some(bindings::miscdevice::default());
-        let dev = this.mdev.as_mut().unwrap();
-        dev.fops = &FileOperationsVtable::<T>::VTABLE;
-        dev.name = name.as_ptr() as *const c_types::c_char;
-        dev.minor = minor.unwrap_or(bindings::MISC_DYNAMIC_MINOR as i32);
-        let ret = unsafe { bindings::misc_register(dev) };
+        this.mdev.fops = &FileOperationsVtable::<Self, F>::VTABLE;
+        this.mdev.name = name.as_ptr() as *const c_types::c_char;
+        this.mdev.minor = minor.unwrap_or(bindings::MISC_DYNAMIC_MINOR as i32);
+
+        let ret = unsafe { bindings::misc_register(&mut this.mdev) };
         if ret < 0 {
-            this.mdev = None;
             return Err(Error::from_kernel_errno(ret));
         }
+        this.registered = true;
         Ok(())
     }
 }
 
-impl Default for Registration {
-    fn default() -> Self {
-        Self::new()
+impl<T: Sync> FileOpenAdapter for Registration<T> {
+    type Arg = T;
+
+    unsafe fn convert(_inode: *mut bindings::inode, file: *mut bindings::file) -> *const Self::Arg {
+        let reg = crate::container_of!((*file).private_data, Self, mdev);
+        &(*reg).context
     }
 }
 
-// SAFETY: The only method is `register()`, which requires a (pinned) mutable
-// `Registration`, so it is safe to pass `&Registration` to multiple threads
-// because it offers no interior mutability.
-unsafe impl Sync for Registration {}
-
-impl Drop for Registration {
-    /// Removes the registration from the kernel if it has completed
-    /// successfully before.
+impl<T: Sync> Drop for Registration<T> {
+    /// Removes the registration from the kernel if it has completed successfully before.
     fn drop(&mut self) {
-        if let Some(ref mut dev) = self.mdev {
-            unsafe {
-                bindings::misc_deregister(dev);
-            }
+        if self.registered {
+            unsafe { bindings::misc_deregister(&mut self.mdev) }
         }
     }
 }