rust: add driver module.

It defines general functionality related to registering drivers with
their respective subsystems, and registering modules that implement
drivers.

This is in preparation for adding support for Amba and PCI drivers.

Signed-off-by: Wedson Almeida Filho <[email protected]>

Author: wedsonaf

rust/kernel/driver.rs

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Generic support for drivers of different buses (e.g., PCI, Platform, Amba, etc.).
+//!
+//! Each bus/subsystem is expected to implement [`DriverOps`], which allows drivers to register
+//! using the [`Registration`] class.
+
+use crate::{str::CStr, Error, KernelModule, Result, ScopeGuard, ThisModule};
+use alloc::{boxed::Box, vec::Vec};
+use core::{cell::UnsafeCell, mem::MaybeUninit, pin::Pin};
+
+/// A subsystem (e.g., PCI, Platform, Amba, etc.) that allows drivers to be written for it.
+pub trait DriverOps {
+    /// The type that holds information about the registration. This is typically a struct defined
+    /// by the C portion of the kernel.
+    type RegType: Default;
+
+    /// The type that holds identification data for the devices supported by the driver. In
+    /// addition to the information required by the bus, it may also store device-specific data
+    /// using Rust types.
+    type IdType: 'static;
+
+    /// The table of ids containing all supported devices.
+    const ID_TABLE: &'static [Self::IdType];
+
+    /// The raw type that holds identification data for the devices supported by the driver. This
+    /// is typically a struct defined by the C portion of the kernel.
+    ///
+    /// A zero-terminated array of this type is produced and passed to the C portion during
+    /// registration.
+    type RawIdType;
+
+    /// Registers a driver.
+    ///
+    /// # Safety
+    ///
+    /// `reg` must point to valid, initialised, and writable memory. It may be modified by this
+    /// function to hold registration state.
+    ///
+    /// `id_table` must point to a valid for read zero-terminated array of IDs.
+    ///
+    /// On success, `reg` and `id_table` must remain pinned and valid until the matching call to
+    /// [`DriverOps::unregister`].
+    unsafe fn register(
+        reg: *mut Self::RegType,
+        name: &'static CStr,
+        id_table: *const Self::RawIdType,
+    ) -> Result;
+
+    /// Unregisters a driver previously registered with [`DriverOps::register`].
+    ///
+    /// # Safety
+    ///
+    /// `reg` must point to valid writable memory, initialised by a previous successful call to
+    /// [`DriverOps::register`].
+    unsafe fn unregister(reg: *mut Self::RegType);
+
+    /// Converts an id into a raw id.
+    ///
+    /// This is used when building a zero-terminated array from the Rust array.
+    fn to_raw_id(index: usize, id: &Self::IdType) -> Self::RawIdType;
+}
+
+/// The registration of a driver.
+pub struct Registration<T: DriverOps> {
+    is_registered: bool,
+    concrete_reg: UnsafeCell<T::RegType>,
+    id_table: Vec<MaybeUninit<T::RawIdType>>,
+}
+
+// SAFETY: `Registration` has no fields or methods accessible via `&Registration`, so it is safe to
+// share references to it with multiple threads as nothing can be done.
+unsafe impl<T: DriverOps> Sync for Registration<T> {}
+
+impl<T: DriverOps> Registration<T> {
+    /// Creates a new instance of the registration object.
+    pub fn new() -> Self {
+        Self {
+            is_registered: false,
+            concrete_reg: UnsafeCell::new(T::RegType::default()),
+            id_table: Vec::new(),
+        }
+    }
+
+    /// Allocates a pinned registration object and registers it.
+    ///
+    /// Returns a pinned heap-allocated representation of the registration.
+    pub fn new_pinned(name: &'static CStr) -> Result<Pin<Box<Self>>> {
+        let mut reg = Pin::from(Box::try_new(Self::new())?);
+        reg.as_mut().register(name)?;
+        Ok(reg)
+    }
+
+    /// Registers a driver with its subsystem.
+    ///
+    /// It must be pinned because the memory block that represents the registration is potentially
+    /// self-referential.
+    pub fn register(self: Pin<&mut Self>, name: &'static CStr) -> Result {
+        // SAFETY: We never move out of `this`.
+        let this = unsafe { self.get_unchecked_mut() };
+        if this.is_registered {
+            // Already registered.
+            return Err(Error::EINVAL);
+        }
+
+        if this.id_table.is_empty() {
+            this.build_table()?;
+        }
+
+        // SAFETY: `concrete_reg` was initialised via its default constructor. `id_table` was just
+        // initialised above with a zero terminating entry. Both are only freed after `Self::drop`
+        // is called, which first calls `T::unregister`.
+        unsafe {
+            T::register(
+                this.concrete_reg.get(),
+                name,
+                &this.id_table[0] as *const _ as *const _,
+            )
+        }?;
+
+        this.is_registered = true;
+        Ok(())
+    }
+
+    /// Builds the zero-terminated raw-type array of supported devices.
+    ///
+    /// This is not ideal because the table is built at runtime. Once Rust fully supports const
+    /// generics, we can build the table at compile time.
+    fn build_table(&mut self) -> Result {
+        // Clear the table on failure, to indicate that the table isn't initialised.
+        let mut table = ScopeGuard::new_with_data(&mut self.id_table, |t| t.clear());
+
+        table.try_reserve_exact(T::ID_TABLE.len() + 1)?;
+        for (i, id) in T::ID_TABLE.iter().enumerate() {
+            table.try_push(MaybeUninit::new(T::to_raw_id(i, id)))?;
+        }
+        table.try_push(MaybeUninit::zeroed())?;
+        table.dismiss();
+        Ok(())
+    }
+}
+
+impl<T: DriverOps> Default for Registration<T> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<T: DriverOps> Drop for Registration<T> {
+    fn drop(&mut self) {
+        if self.is_registered {
+            // SAFETY: This path only runs if a previous call to `T::register` completed
+            // successfully.
+            unsafe { T::unregister(self.concrete_reg.get()) };
+        }
+    }
+}
+
+/// Custom code within device removal.
+pub trait DeviceRemoval {
+    /// Cleans resources up when the device is removed.
+    ///
+    /// This is called when a device is removed and offers implementers the chance to run some code
+    /// that cleans state up.
+    fn device_remove(&self);
+}
+
+/// A kernel module that only registers the given driver on init.
+///
+/// This is a helper struct to make it easier to define single-functionality modules, in this case,
+/// modules that offer a single driver.
+pub struct Module<T: DriverOps> {
+    _driver: Pin<Box<Registration<T>>>,
+}
+
+impl<T: DriverOps> KernelModule for Module<T> {
+    fn init(name: &'static CStr, _module: &'static ThisModule) -> Result<Self> {
+        Ok(Self {
+            _driver: Registration::new_pinned(name)?,
+        })
+    }
+}
+
+/// Declares a kernel module that exposes a single driver.
+///
+/// It is meant to be used as a helper by other subsystems so they can more easily expose their own
+/// macros.
+#[macro_export]
+macro_rules! module_driver {
+    (<$gen_type:ident>, $driver_ops:ty, { type: $type:ty, $($f:tt)* }) => {
+        type Ops<$gen_type> = $driver_ops;
+        type ModuleType = $crate::driver::Module<Ops<$type>>;
+        $crate::prelude::module! {
+            type: ModuleType,
+            $($f)*
+        }
+    }
+}

rust/kernel/lib.rs

@@ -44,6 +44,7 @@ pub mod bindings;
 pub mod buffer;
 pub mod c_types;
 pub mod chrdev;
+pub mod driver;
 mod error;
 pub mod file;
 pub mod file_operations;