Skip to contentSkip to conversation

In-place module initialisation

PATCH Superseded Wedson Almeida Filho 3 participants 12 messages Mar 27, 2024 – Mar 29, 2024

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover In-place module initialisation

From: Wedson Almeida Filho <[email protected]>

Introduce InPlaceModule, which allows modules to be initialised inplace, as opposed to the current state where modules must return an instance which is moved to its final memory location.

This allows us to have modules whose state hold objects that must be initialised inplace like locks. It also allows us to implement registrations (e.g., driver registration) inplace and have them similar to their C counterparts where no new allocations are needed.

This is built on top of the allocation APIs because the sample module is a modified version of rust_minimal, which would be incompatible with the allocation API series because it uses vectors.

Wedson Almeida Filho (2):
rust: introduce InPlaceModule
samples: rust: add in-place initialisation sample

 rust/kernel/lib.rs           | 25 ++++++++++++++++++++-
 rust/macros/module.rs        | 18 ++++++----------
 samples/rust/Kconfig         | 11 ++++++++++
 samples/rust/Makefile        |  1 +
 samples/rust/rust_inplace.rs | 42 ++++++++++++++++++++++++++++++++++++
 5 files changed, 84 insertions(+), 13 deletions(-)
 create mode 100644 samples/rust/rust_inplace.rs

base-commit: e0ff891dbadea6226042574a0cbfc24df0318b13

Signature · 1 line
2.34.1
#1 lore raw

PATCH 1/2 rust: introduce `InPlaceModule`

From: Wedson Almeida Filho <[email protected]>

This allows modules to be initialised in-place in pinned memory, which enables the usage of pinned types (e.g., mutexes, spinlocks, driver registrations, etc.) in modules without any extra allocations.

Drivers that don't need this may continue to implement Module without any changes.

---
 rust/kernel/lib.rs    | 25 ++++++++++++++++++++++++-
 rust/macros/module.rs | 18 ++++++------------
 2 files changed, 30 insertions(+), 13 deletions(-)
rust/kernel/lib.rs +24 -1
index 5c641233e26d..64aee4fbc53b 100644
@@ -62,7 +62,7 @@
 /// The top level entrypoint to implementing a kernel module.
 ///
 /// For any teardown or cleanup operations, your type may implement [`Drop`].
-pub trait Module: Sized + Sync {
+pub trait Module: Sized + Sync + Send {
     /// Called at module initialization time.
     ///
     /// Use this method to perform whatever setup or registration your module
@@ -72,6 +72,29 @@ pub trait Module: Sized + Sync {
     fn init(module: &'static ThisModule) -> error::Result<Self>;
 }
 
+/// A module that is pinned and initialised in-place.
+pub trait InPlaceModule: Sync + Send {
+    /// Creates an initialiser for the module.
+    ///
+    /// It is called when the module is loaded.
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>;
+}
+
+impl<T: Module> InPlaceModule for T {
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error> {
+        let initer = move |slot: *mut Self| {
+            let m = <Self as Module>::init(module)?;
+
+            // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
+            unsafe { slot.write(m) };
+            Ok(())
+        };
+
+        // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
+        unsafe { init::pin_init_from_closure(initer) }
+    }
+}
+
 /// Equivalent to `THIS_MODULE` in the C API.
 ///
 /// C header: [`include/linux/export.h`](srctree/include/linux/export.h)
rust/macros/module.rs +6 -12
index 27979e582e4b..0b2bb4ec2fba 100644
@@ -208,7 +208,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             #[used]
             static __IS_RUST_MODULE: () = ();
 
-            static mut __MOD: Option<{type_}> = None;
+            static mut __MOD: core::mem::MaybeUninit<{type_}> = core::mem::MaybeUninit::uninit();
 
             // SAFETY: `__this_module` is constructed by the kernel at load time and will not be
             // freed until the module is unloaded.
@@ -275,23 +275,17 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             }}
 
             fn __init() -> core::ffi::c_int {{
-                match <{type_} as kernel::Module>::init(&THIS_MODULE) {{
-                    Ok(m) => {{
-                        unsafe {{
-                            __MOD = Some(m);
-                        }}
-                        return 0;
-                    }}
-                    Err(e) => {{
-                        return e.to_errno();
-                    }}
+                let initer = <{type_} as kernel::InPlaceModule>::init(&THIS_MODULE);
+                match unsafe {{ initer.__pinned_init(__MOD.as_mut_ptr()) }} {{
+                    Ok(m) => 0,
+                    Err(e) => e.to_errno(),
                 }}
             }}
 
             fn __exit() {{
                 unsafe {{
                     // Invokes `drop()` on `__MOD`, which should be used for cleanup.
-                    __MOD = None;
+                    __MOD.assume_init_drop();
                 }}
             }}
 
Signature · 1 line
2.34.1
Tested-by on v1 1/2
#2 lore raw

Re: [PATCH 1/2] rust: introduce `InPlaceModule`

Quoted 18 lines

This allows modules to be initialised in-place in pinned memory, which enables the usage of pinned types (e.g., mutexes, spinlocks, driver registrations, etc.) in modules without any extra allocations.

Drivers that don't need this may continue to implement Module without any changes.

---
 rust/kernel/lib.rs    | 25 ++++++++++++++++++++++++-
 rust/macros/module.rs | 18 ++++++------------
 2 files changed, 30 insertions(+), 13 deletions(-)
rust/kernel/lib.rs +0 -0
index 5c641233e26d..64aee4fbc53b 100644

rust/kernel/lib.rs line 65

Quoted 5 lines
rust/kernel/lib.rs +1 -1
@@ -62,7 +62,7 @@
 /// The top level entrypoint to implementing a kernel module.
 ///
 /// For any teardown or cleanup operations, your type may implement [`Drop`].
-pub trait Module: Sized + Sync {
+pub trait Module: Sized + Sync + Send {

This does not compile with CONFIG_AX88796B_RUST_PHY=y || m (or the phylib abstractions' doctests) since the module Registration is not Send.

I remember Trevor raising the question whether we want to require modules to be Send. I am not aware of any examples of !Send modules but I guess it would be possible to write code that is only correct under the assumption that it is loaded/unloaded in the same context.

@Trevor: Are you aware of any modules with that requirement?

I have been using this patch for quite a while with my TCP CCAs now (without the Send bound) and did not experience any other issues; thus offering:

- Best Valentin

Quoted 76 lines
rust/kernel/lib.rs +23 -0
     /// Called at module initialization time.
     ///
     /// Use this method to perform whatever setup or registration your module
@@ -72,6 +72,29 @@ pub trait Module: Sized + Sync {
     fn init(module: &'static ThisModule) -> error::Result<Self>;
 }
 
+/// A module that is pinned and initialised in-place.
+pub trait InPlaceModule: Sync + Send {
+    /// Creates an initialiser for the module.
+    ///
+    /// It is called when the module is loaded.
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>;
+}
+
+impl<T: Module> InPlaceModule for T {
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error> {
+        let initer = move |slot: *mut Self| {
+            let m = <Self as Module>::init(module)?;
+
+            // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
+            unsafe { slot.write(m) };
+            Ok(())
+        };
+
+        // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
+        unsafe { init::pin_init_from_closure(initer) }
+    }
+}
+
 /// Equivalent to `THIS_MODULE` in the C API.
 ///
 /// C header: [`include/linux/export.h`](srctree/include/linux/export.h)
rust/macros/module.rs +6 -13
index 27979e582e4b..0b2bb4ec2fba 100644
@@ -208,7 +208,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             #[used]
             static __IS_RUST_MODULE: () = ();
 
-            static mut __MOD: Option<{type_}> = None;
+            static mut __MOD: core::mem::MaybeUninit<{type_}> = core::mem::MaybeUninit::uninit();
 
             // SAFETY: `__this_module` is constructed by the kernel at load time and will not be
             // freed until the module is unloaded.
@@ -275,23 +275,17 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             }}
 
             fn __init() -> core::ffi::c_int {{
-                match <{type_} as kernel::Module>::init(&THIS_MODULE) {{
-                    Ok(m) => {{
-                        unsafe {{
-                            __MOD = Some(m);
-                        }}
-                        return 0;
-                    }}
-                    Err(e) => {{
-                        return e.to_errno();
-                    }}
+                let initer = <{type_} as kernel::InPlaceModule>::init(&THIS_MODULE);
+                match unsafe {{ initer.__pinned_init(__MOD.as_mut_ptr()) }} {{
+                    Ok(m) => 0,
+                    Err(e) => e.to_errno(),
                 }}
             }}
 
             fn __exit() {{
                 unsafe {{
                     // Invokes `drop()` on `__MOD`, which should be used for cleanup.
-                    __MOD = None;
+                    __MOD.assume_init_drop();
                 }}
             }}
 
--
#3 lore raw

Re: [PATCH 1/2] rust: introduce `InPlaceModule`

Quoted 14 lines · Valentin Obst
Quoted 14 lines

This allows modules to be initialised in-place in pinned memory, which enables the usage of pinned types (e.g., mutexes, spinlocks, driver registrations, etc.) in modules without any extra allocations.

Drivers that don't need this may continue to implement Module without any changes.

---
 rust/kernel/lib.rs    | 25 ++++++++++++++++++++++++-
 rust/macros/module.rs | 18 ++++++------------
 2 files changed, 30 insertions(+), 13 deletions(-)
Quoted 14 lines

rust/kernel/lib.rs line 65

Quoted 10 lines
rust/kernel/lib.rs +1 -1
index 5c641233e26d..64aee4fbc53b 100644
@@ -62,7 +62,7 @@
 /// The top level entrypoint to implementing a kernel module.
 ///
 /// For any teardown or cleanup operations, your type may implement [`Drop`].
-pub trait Module: Sized + Sync {
+pub trait Module: Sized + Sync + Send {

This does not compile with CONFIG_AX88796B_RUST_PHY=y || m (or the phylib abstractions' doctests) since the module Registration is not Send.

Thanks for the heads up. I thought I had enabled all rust code but indeed I was missing this. I will fix it in v2.

Quoted 4 lines

I remember Trevor raising the question whether we want to require modules to be Send. I am not aware of any examples of !Send modules but I guess it would be possible to write code that is only correct under the assumption that it is loaded/unloaded in the same context.

It might be possible in the future, but I don't believe it is now because all rust modules support unloading. And there is no guarantee that the thread unloading (and therefore calling module_exit) is the same that loaded (and called module_init), so a module must be Send to properly handle drop being called from a different thread.

Not requiring Send on the original Module trait was an oversight that I don't want to repeat in InPlaceModule.

Quoted 7 lines

@Trevor: Are you aware of any modules with that requirement?

I have been using this patch for quite a while with my TCP CCAs now (without the Send bound) and did not experience any other issues; thus offering:

Thanks!

Quoted 79 lines

- Best Valentin

Quoted 76 lines
rust/kernel/lib.rs +23 -0
     /// Called at module initialization time.
     ///
     /// Use this method to perform whatever setup or registration your module
@@ -72,6 +72,29 @@ pub trait Module: Sized + Sync {
     fn init(module: &'static ThisModule) -> error::Result<Self>;
 }
 
+/// A module that is pinned and initialised in-place.
+pub trait InPlaceModule: Sync + Send {
+    /// Creates an initialiser for the module.
+    ///
+    /// It is called when the module is loaded.
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>;
+}
+
+impl<T: Module> InPlaceModule for T {
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error> {
+        let initer = move |slot: *mut Self| {
+            let m = <Self as Module>::init(module)?;
+
+            // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
+            unsafe { slot.write(m) };
+            Ok(())
+        };
+
+        // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
+        unsafe { init::pin_init_from_closure(initer) }
+    }
+}
+
 /// Equivalent to `THIS_MODULE` in the C API.
 ///
 /// C header: [`include/linux/export.h`](srctree/include/linux/export.h)
rust/macros/module.rs +6 -13
index 27979e582e4b..0b2bb4ec2fba 100644
@@ -208,7 +208,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             #[used]
             static __IS_RUST_MODULE: () = ();
 
-            static mut __MOD: Option<{type_}> = None;
+            static mut __MOD: core::mem::MaybeUninit<{type_}> = core::mem::MaybeUninit::uninit();
 
             // SAFETY: `__this_module` is constructed by the kernel at load time and will not be
             // freed until the module is unloaded.
@@ -275,23 +275,17 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             }}
 
             fn __init() -> core::ffi::c_int {{
-                match <{type_} as kernel::Module>::init(&THIS_MODULE) {{
-                    Ok(m) => {{
-                        unsafe {{
-                            __MOD = Some(m);
-                        }}
-                        return 0;
-                    }}
-                    Err(e) => {{
-                        return e.to_errno();
-                    }}
+                let initer = <{type_} as kernel::InPlaceModule>::init(&THIS_MODULE);
+                match unsafe {{ initer.__pinned_init(__MOD.as_mut_ptr()) }} {{
+                    Ok(m) => 0,
+                    Err(e) => e.to_errno(),
                 }}
             }}
 
             fn __exit() {{
                 unsafe {{
                     // Invokes `drop()` on `__MOD`, which should be used for cleanup.
-                    __MOD = None;
+                    __MOD.assume_init_drop();
                 }}
             }}
 
--
#4 lore raw

Re: [PATCH 1/2] rust: introduce `InPlaceModule`

Quoted 38 lines · Wedson Almeida Filho
Quoted 14 lines · Valentin Obst
Quoted 14 lines

This allows modules to be initialised in-place in pinned memory, which enables the usage of pinned types (e.g., mutexes, spinlocks, driver registrations, etc.) in modules without any extra allocations.

Drivers that don't need this may continue to implement Module without any changes.

---
  rust/kernel/lib.rs    | 25 ++++++++++++++++++++++++-
  rust/macros/module.rs | 18 ++++++------------
  2 files changed, 30 insertions(+), 13 deletions(-)
Quoted 14 lines

rust/kernel/lib.rs line 65

Quoted 10 lines
rust/kernel/lib.rs +1 -1
index 5c641233e26d..64aee4fbc53b 100644
@@ -62,7 +62,7 @@
  /// The top level entrypoint to implementing a kernel module.
  ///
  /// For any teardown or cleanup operations, your type may implement [`Drop`].
-pub trait Module: Sized + Sync {
+pub trait Module: Sized + Sync + Send {

This does not compile with CONFIG_AX88796B_RUST_PHY=y || m (or the phylib abstractions' doctests) since the module Registration is not Send.

Thanks for the heads up. I thought I had enabled all rust code but indeed I was missing this. I will fix it in v2.

Quoted 4 lines

I remember Trevor raising the question whether we want to require modules to be Send. I am not aware of any examples of !Send modules but I guess it would be possible to write code that is only correct under the assumption that it is loaded/unloaded in the same context.

Quoted 8 lines

It might be possible in the future, but I don't believe it is now because all rust modules support unloading. And there is no guarantee that the thread unloading (and therefore calling module_exit) is the same that loaded (and called module_init), so a module must be Send to properly handle drop being called from a different thread.

Not requiring Send on the original Module trait was an oversight that I don't want to repeat in InPlaceModule.

I think that this change should go to the stable tree, can you split it into its own patch?

Signature · 2 lines
Cheers,
Benno
Quoted 14 lines
Quoted 8 lines

@Trevor: Are you aware of any modules with that requirement?

I have been using this patch for quite a while with my TCP CCAs now (without the Send bound) and did not experience any other issues; thus offering:

Thanks!

Quoted 3 lines

- Best Valentin

#5 lore raw

Re: [PATCH 1/2] rust: introduce `InPlaceModule`

Quoted 46 lines · Benno Lossin
Quoted 44 lines · Wedson Almeida Filho
Quoted 14 lines · Valentin Obst
Quoted 14 lines

This allows modules to be initialised in-place in pinned memory, which enables the usage of pinned types (e.g., mutexes, spinlocks, driver registrations, etc.) in modules without any extra allocations.

Drivers that don't need this may continue to implement Module without any changes.

---
  rust/kernel/lib.rs    | 25 ++++++++++++++++++++++++-
  rust/macros/module.rs | 18 ++++++------------
  2 files changed, 30 insertions(+), 13 deletions(-)
Quoted 14 lines

rust/kernel/lib.rs line 65

Quoted 10 lines
rust/kernel/lib.rs +1 -1
index 5c641233e26d..64aee4fbc53b 100644
@@ -62,7 +62,7 @@
  /// The top level entrypoint to implementing a kernel module.
  ///
  /// For any teardown or cleanup operations, your type may implement [`Drop`].
-pub trait Module: Sized + Sync {
+pub trait Module: Sized + Sync + Send {

This does not compile with CONFIG_AX88796B_RUST_PHY=y || m (or the phylib abstractions' doctests) since the module Registration is not Send.

Thanks for the heads up. I thought I had enabled all rust code but indeed I was missing this. I will fix it in v2.

Quoted 4 lines

I remember Trevor raising the question whether we want to require modules to be Send. I am not aware of any examples of !Send modules but I guess it would be possible to write code that is only correct under the assumption that it is loaded/unloaded in the same context.

It might be possible in the future, but I don't believe it is now because all rust modules support unloading. And there is no guarantee that the thread unloading (and therefore calling module_exit) is the same that loaded (and called module_init), so a module must be Send to properly handle drop being called from a different thread.

Quoted 5 lines
Quoted 2 lines

Not requiring Send on the original Module trait was an oversight that I don't want to repeat in InPlaceModule.

I think that this change should go to the stable tree, can you split it into its own patch?

Sure, I split it off in v2.

Note that you'll also need the [new] patch to rust/kernel/net/phy.rs.

Quoted 19 lines

--
Cheers,
Benno

Quoted 14 lines
Quoted 8 lines

@Trevor: Are you aware of any modules with that requirement?

I have been using this patch for quite a while with my TCP CCAs now (without the Send bound) and did not experience any other issues; thus offering:

Thanks!

Quoted 3 lines

- Best Valentin

Reviewed-by on v1 1/2
#6 lore raw

Re: [PATCH 1/2] rust: introduce `InPlaceModule`

In reply to Wedson Almeida Filho
Quoted 10 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows modules to be initialised in-place in pinned memory, which enables the usage of pinned types (e.g., mutexes, spinlocks, driver registrations, etc.) in modules without any extra allocations.

Drivers that don't need this may continue to implement Module without any changes.

I have some suggestions below, with those fixed,

Quoted 53 lines
---
 rust/kernel/lib.rs    | 25 ++++++++++++++++++++++++-
 rust/macros/module.rs | 18 ++++++------------
 2 files changed, 30 insertions(+), 13 deletions(-)
rust/kernel/lib.rs +24 -1
index 5c641233e26d..64aee4fbc53b 100644
@@ -62,7 +62,7 @@
 /// The top level entrypoint to implementing a kernel module.
 ///
 /// For any teardown or cleanup operations, your type may implement [`Drop`].
-pub trait Module: Sized + Sync {
+pub trait Module: Sized + Sync + Send {
     /// Called at module initialization time.
     ///
     /// Use this method to perform whatever setup or registration your module
@@ -72,6 +72,29 @@ pub trait Module: Sized + Sync {
     fn init(module: &'static ThisModule) -> error::Result<Self>;
 }
 
+/// A module that is pinned and initialised in-place.
+pub trait InPlaceModule: Sync + Send {
+    /// Creates an initialiser for the module.
+    ///
+    /// It is called when the module is loaded.
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>;
+}
+
+impl<T: Module> InPlaceModule for T {
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error> {
+        let initer = move |slot: *mut Self| {
+            let m = <Self as Module>::init(module)?;
+
+            // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
+            unsafe { slot.write(m) };
+            Ok(())
+        };
+
+        // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
+        unsafe { init::pin_init_from_closure(initer) }
+    }
+}
+
 /// Equivalent to `THIS_MODULE` in the C API.
 ///
 /// C header: [`include/linux/export.h`](srctree/include/linux/export.h)
rust/macros/module.rs +0 -0
index 27979e582e4b..0b2bb4ec2fba 100644

rust/macros/module.rs pub(crate) fn module(ts: TokenStream) -> TokenStream { · line 211

Quoted 5 lines
rust/macros/module.rs +1 -1
@@ -208,7 +208,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             #[used]
             static __IS_RUST_MODULE: () = ();
 
-            static mut __MOD: Option<{type_}> = None;
+            static mut __MOD: core::mem::MaybeUninit<{type_}> = core::mem::MaybeUninit::uninit();

I would prefer ::core::mem::MaybeUninit, since that prevents accidentally referring to a module named core.

Quoted 8 lines
rust/macros/module.rs +0 -1
             // SAFETY: `__this_module` is constructed by the kernel at load time and will not be
             // freed until the module is unloaded.
@@ -275,23 +275,17 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             }}
 
             fn __init() -> core::ffi::c_int {{
-                match <{type_} as kernel::Module>::init(&THIS_MODULE) {{

rust/macros/module.rs pub(crate) fn module(ts: TokenStream) -> TokenStream { · line 278

Quoted 10 lines
rust/macros/module.rs +1 -9
-                    Ok(m) => {{
-                        unsafe {{
-                            __MOD = Some(m);
-                        }}
-                        return 0;
-                    }}
-                    Err(e) => {{
-                        return e.to_errno();
-                    }}
+                let initer = <{type_} as kernel::InPlaceModule>::init(&THIS_MODULE);

Ditto with ::kernel::InPlaceModule.

rust/macros/module.rs pub(crate) fn module(ts: TokenStream) -> TokenStream { · line 279

Quoted 1 line
rust/macros/module.rs +1 -0
+                match unsafe {{ initer.__pinned_init(__MOD.as_mut_ptr()) }} {{

This requires that the PinInit trait is in scope, I would use:

     match unsafe {{ ::kernel::init::PinInit::__pinned_init(initer, __MOD.as_mut_ptr()) }} {{
Signature · 2 lines
Cheers,
Benno
Quoted 16 lines
rust/macros/module.rs +3 -2
+                    Ok(m) => 0,
+                    Err(e) => e.to_errno(),
                 }}
             }}
 
             fn __exit() {{
                 unsafe {{
                     // Invokes `drop()` on `__MOD`, which should be used for cleanup.
-                    __MOD = None;
+                    __MOD.assume_init_drop();
                 }}
             }}
 
--

2.34.1

#7 lore raw

Re: [PATCH 1/2] rust: introduce `InPlaceModule`

Quoted 73 lines · Benno Lossin
Quoted 10 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows modules to be initialised in-place in pinned memory, which enables the usage of pinned types (e.g., mutexes, spinlocks, driver registrations, etc.) in modules without any extra allocations.

Drivers that don't need this may continue to implement Module without any changes.

I have some suggestions below, with those fixed,

Quoted 56 lines
---
 rust/kernel/lib.rs    | 25 ++++++++++++++++++++++++-
 rust/macros/module.rs | 18 ++++++------------
 2 files changed, 30 insertions(+), 13 deletions(-)
rust/kernel/lib.rs +24 -1
index 5c641233e26d..64aee4fbc53b 100644
@@ -62,7 +62,7 @@
 /// The top level entrypoint to implementing a kernel module.
 ///
 /// For any teardown or cleanup operations, your type may implement [`Drop`].
-pub trait Module: Sized + Sync {
+pub trait Module: Sized + Sync + Send {
     /// Called at module initialization time.
     ///
     /// Use this method to perform whatever setup or registration your module
@@ -72,6 +72,29 @@ pub trait Module: Sized + Sync {
     fn init(module: &'static ThisModule) -> error::Result<Self>;
 }
 
+/// A module that is pinned and initialised in-place.
+pub trait InPlaceModule: Sync + Send {
+    /// Creates an initialiser for the module.
+    ///
+    /// It is called when the module is loaded.
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>;
+}
+
+impl<T: Module> InPlaceModule for T {
+    fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error> {
+        let initer = move |slot: *mut Self| {
+            let m = <Self as Module>::init(module)?;
+
+            // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
+            unsafe { slot.write(m) };
+            Ok(())
+        };
+
+        // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
+        unsafe { init::pin_init_from_closure(initer) }
+    }
+}
+
 /// Equivalent to `THIS_MODULE` in the C API.
 ///
 /// C header: [`include/linux/export.h`](srctree/include/linux/export.h)
rust/macros/module.rs +0 -0
index 27979e582e4b..0b2bb4ec2fba 100644
@@ -208,7 +208,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             #[used]
             static __IS_RUST_MODULE: () = ();
 
Quoted 5 lines

rust/macros/module.rs pub(crate) fn module(ts: TokenStream) -> TokenStream { · line 211

Quoted 2 lines
rust/macros/module.rs +1 -1
-            static mut __MOD: Option<{type_}> = None;
+            static mut __MOD: core::mem::MaybeUninit<{type_}> = core::mem::MaybeUninit::uninit();

I would prefer ::core::mem::MaybeUninit, since that prevents accidentally referring to a module named core.

Makes sense, changed in v3.

I also added a patch to v3 that adds :: to all cases in the code generated by the macro.

Quoted 22 lines
Quoted 9 lines
rust/macros/module.rs +0 -1
             // SAFETY: `__this_module` is constructed by the kernel at load time and will not be
             // freed until the module is unloaded.
@@ -275,23 +275,17 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
             }}
 
             fn __init() -> core::ffi::c_int {{
-                match <{type_} as kernel::Module>::init(&THIS_MODULE) {{

rust/macros/module.rs pub(crate) fn module(ts: TokenStream) -> TokenStream { · line 278

Quoted 10 lines
rust/macros/module.rs +1 -9
-                    Ok(m) => {{
-                        unsafe {{
-                            __MOD = Some(m);
-                        }}
-                        return 0;
-                    }}
-                    Err(e) => {{
-                        return e.to_errno();
-                    }}
+                let initer = <{type_} as kernel::InPlaceModule>::init(&THIS_MODULE);

Ditto with ::kernel::InPlaceModule.

Quoted 5 lines

rust/macros/module.rs pub(crate) fn module(ts: TokenStream) -> TokenStream { · line 279

Quoted 1 line
rust/macros/module.rs +1 -0
+                match unsafe {{ initer.__pinned_init(__MOD.as_mut_ptr()) }} {{

This requires that the PinInit trait is in scope, I would use:

     match unsafe {{ ::kernel::init::PinInit::__pinned_init(initer, __MOD.as_mut_ptr()) }} {{

Also changed in v3.

Quoted 21 lines

--
Cheers,
Benno

Quoted 16 lines
rust/macros/module.rs +3 -2
+                    Ok(m) => 0,
+                    Err(e) => e.to_errno(),
                 }}
             }}
 
             fn __exit() {{
                 unsafe {{
                     // Invokes `drop()` on `__MOD`, which should be used for cleanup.
-                    __MOD = None;
+                    __MOD.assume_init_drop();
                 }}
             }}
 
--

2.34.1

#8 lore raw

PATCH 2/2 samples: rust: add in-place initialisation sample

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This is a modified version of rust_minimal that is initialised in-place.

---
 samples/rust/Kconfig         | 11 ++++++++++
 samples/rust/Makefile        |  1 +
 samples/rust/rust_inplace.rs | 42 ++++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+)
 create mode 100644 samples/rust/rust_inplace.rs
samples/rust/Kconfig +11 -0
index b0f74a81c8f9..59f44a8b6958 100644
@@ -20,6 +20,17 @@ config SAMPLE_RUST_MINIMAL
 
 	  If unsure, say N.
 
+config SAMPLE_RUST_INPLACE
+	tristate "Minimal in-place"
+	help
+	  This option builds the Rust minimal module with in-place
+	  initialisation.
+
+	  To compile this as a module, choose M here:
+	  the module will be called rust_inplace.
+
+	  If unsure, say N.
+
 config SAMPLE_RUST_PRINT
 	tristate "Printing macros"
 	help
samples/rust/Makefile +1 -0
index 03086dabbea4..791fc18180e9 100644
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: GPL-2.0
 
 obj-$(CONFIG_SAMPLE_RUST_MINIMAL)		+= rust_minimal.o
+obj-$(CONFIG_SAMPLE_RUST_INPLACE)		+= rust_inplace.o
 obj-$(CONFIG_SAMPLE_RUST_PRINT)			+= rust_print.o
 
 subdir-$(CONFIG_SAMPLE_RUST_HOSTPROGS)		+= hostprogs
samples/rust/rust_inplace.rs new file +42 -0

42 lines not on this page · raw message

Signature · 1 line
2.34.1
#9 lore raw

Re: [PATCH 2/2] samples: rust: add in-place initialisation sample

Quoted 18 lines · Wedson Almeida Filho
samples/rust/rust_inplace.rs new file +12 -0
new file mode 100644
index 000000000000..ba8d051cac56
@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Rust minimal in-place sample.
+
+use kernel::prelude::*;
+
+module! {
+    type: RustInPlace,
+    name: "rust_inplace",
+    author: "Rust for Linux Contributors",
+    description: "Rust minimal in-place sample",
+    license: "GPL",

samples/rust/rust_inplace.rs line 22

Quoted 10 lines
samples/rust/rust_inplace.rs new file +10 -0
+}
+
+#[pin_data(PinnedDrop)]
+struct RustInPlace {
+    numbers: Vec<i32>,
+}
+
+impl kernel::InPlaceModule for RustInPlace {
+    fn init(_module: &'static ThisModule) -> impl PinInit<Self, Error> {
+        pr_info!("Rust minimal sample (init)\n");

This text needs updating.

samples/rust/rust_inplace.rs line 32

Quoted 10 lines
samples/rust/rust_inplace.rs new file +10 -0
+        pr_info!("Am I built-in? {}\n", !cfg!(MODULE));
+        try_pin_init!(Self {
+            numbers: {
+                let mut numbers = Vec::new();
+                numbers.push(72, GFP_KERNEL)?;
+                numbers.push(108, GFP_KERNEL)?;
+                numbers.push(200, GFP_KERNEL)?;
+                numbers
+            },
+        })

I think it might be useful to also have a field that needs pin-init, eg a Mutex or similar. What about placing the Vec inside of a mutex?

Signature · 2 lines
Cheers,
Benno
Quoted 13 lines
samples/rust/rust_inplace.rs new file +10 -1
+    }
+}
+
+#[pinned_drop]
+impl PinnedDrop for RustInPlace {
+    fn drop(self: Pin<&mut Self>) {
+        pr_info!("My numbers are {:?}\n", self.numbers);
+        pr_info!("Rust minimal inplace sample (exit)\n");
+    }
+}
--

2.34.1

#10 lore raw

Re: [PATCH 2/2] samples: rust: add in-place initialisation sample

Quoted 24 lines · Benno Lossin
Quoted 22 lines · Wedson Almeida Filho
samples/rust/rust_inplace.rs new file +16 -0
new file mode 100644
index 000000000000..ba8d051cac56
@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Rust minimal in-place sample.
+
+use kernel::prelude::*;
+
+module! {
+    type: RustInPlace,
+    name: "rust_inplace",
+    author: "Rust for Linux Contributors",
+    description: "Rust minimal in-place sample",
+    license: "GPL",
+}
+
+#[pin_data(PinnedDrop)]
+struct RustInPlace {
Quoted 8 lines

samples/rust/rust_inplace.rs line 22

Quoted 6 lines
samples/rust/rust_inplace.rs new file +6 -0
+    numbers: Vec<i32>,
+}
+
+impl kernel::InPlaceModule for RustInPlace {
+    fn init(_module: &'static ThisModule) -> impl PinInit<Self, Error> {
+        pr_info!("Rust minimal sample (init)\n");

This text needs updating.

Fixed in v2.

Quoted 12 lines

samples/rust/rust_inplace.rs line 32

Quoted 11 lines
samples/rust/rust_inplace.rs new file +10 -0
+        pr_info!("Am I built-in? {}\n", !cfg!(MODULE));
+        try_pin_init!(Self {
+            numbers: {
+                let mut numbers = Vec::new();
+                numbers.push(72, GFP_KERNEL)?;
+                numbers.push(108, GFP_KERNEL)?;
+                numbers.push(200, GFP_KERNEL)?;
+                numbers
+            },
+        })
Quoted 2 lines

I think it might be useful to also have a field that needs pin-init, eg a Mutex or similar. What about placing the Vec inside of a mutex?

I'm not sure this belongs in a "minimal" example.

But I added it in v2 because we're already violating minimality with vectors anyway. Perhaps we should later have minimal samples and rename these to something else.

Quoted 18 lines

--
Cheers,
Benno

Quoted 13 lines
samples/rust/rust_inplace.rs new file +10 -1
+    }
+}
+
+#[pinned_drop]
+impl PinnedDrop for RustInPlace {
+    fn drop(self: Pin<&mut Self>) {
+        pr_info!("My numbers are {:?}\n", self.numbers);
+        pr_info!("Rust minimal inplace sample (exit)\n");
+    }
+}
--

2.34.1

#11 lore raw

Re: [PATCH 2/2] samples: rust: add in-place initialisation sample

Quoted 13 lines · Wedson Almeida Filho
Quoted 12 lines · Benno Lossin
Quoted 10 lines · Wedson Almeida Filho
samples/rust/rust_inplace.rs new file +10 -0
+        pr_info!("Am I built-in? {}\n", !cfg!(MODULE));
+        try_pin_init!(Self {
+            numbers: {
+                let mut numbers = Vec::new();
+                numbers.push(72, GFP_KERNEL)?;
+                numbers.push(108, GFP_KERNEL)?;
+                numbers.push(200, GFP_KERNEL)?;
+                numbers
+            },
+        })
Quoted 8 lines
Quoted 2 lines

I think it might be useful to also have a field that needs pin-init, eg a Mutex or similar. What about placing the Vec inside of a mutex?

I'm not sure this belongs in a "minimal" example.

But I added it in v2 because we're already violating minimality with vectors anyway. Perhaps we should later have minimal samples and rename these to something else.

I think a fully minimal example would be less valuable as a learning resource. We can of course have both, but I think having real usage of pin-init in this example can help people get familiar with it.

Signature · 2 lines
Cheers,
Benno