kernel/
module.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Module-related types and helpers.
4
5/// The entrypoint to implementing a kernel module.
6///
7/// For any teardown or cleanup operations, your type may implement [`Drop`].
8pub trait Module: Sized + Sync + Send {
9    /// Called at module initialization time.
10    ///
11    /// Use this method to perform whatever setup or registration your module
12    /// should do.
13    ///
14    /// Equivalent to the `module_init` macro in the C API.
15    fn init(module: &'static ThisModule) -> crate::error::Result<Self>;
16}
17
18/// A module that is pinned and initialised in-place.
19pub trait InPlaceModule: Sync + Send {
20    /// Creates an initialiser for the module.
21    ///
22    /// It is called when the module is loaded.
23    fn init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, crate::error::Error>;
24}
25
26impl<T: Module> InPlaceModule for T {
27    fn init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, crate::error::Error> {
28        let initer = move |slot: *mut Self| {
29            let m = <Self as Module>::init(module)?;
30
31            // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
32            unsafe { slot.write(m) };
33            Ok(())
34        };
35
36        // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
37        unsafe { pin_init::pin_init_from_closure(initer) }
38    }
39}
40
41/// Metadata attached to a [`Module`] or [`InPlaceModule`].
42pub trait ModuleMetadata {
43    /// The name of the module as specified in the `module!` macro.
44    const NAME: &'static crate::str::CStr;
45
46    /// The module's `THIS_MODULE` pointer.
47    const THIS_MODULE: ThisModule;
48}
49
50/// Returns a reference to the `THIS_MODULE` of the given module type.
51#[inline]
52pub const fn this_module<M: ModuleMetadata>() -> &'static ThisModule {
53    &M::THIS_MODULE
54}
55
56/// Equivalent to `THIS_MODULE` in the C API.
57///
58/// C header: [`include/linux/init.h`](srctree/include/linux/init.h)
59pub struct ThisModule(*mut crate::bindings::module);
60
61// SAFETY: `THIS_MODULE` may be used from all threads within a module.
62unsafe impl Sync for ThisModule {}
63
64impl ThisModule {
65    /// Creates a [`ThisModule`] given the `THIS_MODULE` pointer.
66    ///
67    /// # Safety
68    ///
69    /// The pointer must be equal to the right `THIS_MODULE`.
70    pub const unsafe fn from_ptr(ptr: *mut crate::bindings::module) -> ThisModule {
71        ThisModule(ptr)
72    }
73
74    /// Access the raw pointer for this module.
75    ///
76    /// It is up to the user to use it correctly.
77    pub const fn as_ptr(&self) -> *mut crate::bindings::module {
78        self.0
79    }
80}
kernel/module.rs

kernel/
module.rs
