Skip to contentSkip to conversation

rust: add global lock support

PATCH Superseded Alice Ryhl 4 participants 18 messages Sep 30, 2024 – Oct 14, 2024

Subsystems (3)

v4 of 6 Superseded Latest is v6 →

lore
Share & tools
lore

Alice Ryhl

author maintainer
#0 lore raw

PATCH v4 1/1 rust: add global lock support

Add support for creating global variables that are wrapped in a mutex or spinlock. Optionally, the macro can generate a special LockedBy type that does not require a runtime check.

The implementation here is intended to replace the global mutex workaround found in the Rust Binder RFC [1]. In both cases, the global lock must be initialized before first use. The macro is unsafe to use for the same reason.

The separate initialization step is required because it is tricky to access the value of __ARCH_SPIN_LOCK_UNLOCKED from Rust. Doing so will require changes to the C side. That change will happen as a follow-up to this patch.

---
This patch is based on top of v6.12-rc1 with:
* https://lore.kernel.org/r/BL0PR02MB4914579914884B5D7473B3D6E96A2@BL0PR02MB4914.namprd02.prod.outlook.com
---
Changes in v4:
- Evaluate $value in the surrounding scope.
- Make types pub(crate) to avoid "private type in public interface"
errors when using the macro.
- Add trylock method.
- using https://lore.kernel.org/r/BL0PR02MB4914579914884B5D7473B3D6E96A2@BL0PR02MB4914.namprd02.prod.outlook.com
- Add Send/Sync implementations of LockedBy.
- Fix examples so they compile.
- Link to v3: https://lore.kernel.org/r/[email protected]

Changes in v3:
- Rewrite to provide a macro instead.
- Link to v2: https://lore.kernel.org/r/[email protected]

Changes in v2:
- Require self: Pin<&Self> and recommend Pin::static_ref.
- Other doc improvements including new example.
- Link to v1: https://lore.kernel.org/r/[email protected]

---
 rust/kernel/sync.rs             |   1 +
 rust/kernel/sync/lock.rs        |  31 ++++-
 rust/kernel/sync/lock/global.rs | 260 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 291 insertions(+), 1 deletion(-)
rust/kernel/sync.rs +1 -0
index 0ab20975a3b5..2e97e22715db 100644
@@ -14,6 +14,7 @@
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
 pub use condvar::{new_condvar, CondVar, CondVarTimeoutResult};
+pub use lock::global::global_lock;
 pub use lock::mutex::{new_mutex, Mutex};
 pub use lock::spinlock::{new_spinlock, SpinLock};
 pub use locked_by::LockedBy;
rust/kernel/sync/lock.rs +30 -1
index 360d06e9c57a..528e885ee535 100644
@@ -7,12 +7,14 @@
 
 use super::LockClassKey;
 use crate::{init::PinInit, pin_init, str::CStr, types::Opaque, types::ScopeGuard};
-use core::{cell::UnsafeCell, marker::PhantomData, marker::PhantomPinned};
+use core::{cell::UnsafeCell, marker::PhantomData, marker::PhantomPinned, pin::Pin};
 use macros::pin_data;
 
 pub mod mutex;
 pub mod spinlock;
 
+pub(super) mod global;
+
 /// The "backend" of a lock.
 ///
 /// It is the actual implementation of the lock, without the need to repeat patterns used in all
@@ -124,6 +126,33 @@ pub fn new(t: T, name: &'static CStr, key: &'static LockClassKey) -> impl PinIni
             }),
         })
     }
+
+    /// # Safety
+    ///
+    /// Before any other method on this lock is called, `global_lock_helper_init` must be called.
+    #[doc(hidden)]
+    pub const unsafe fn global_lock_helper_new(state: Opaque<B::State>, data: T) -> Self {
+        Self {
+            state,
+            data: UnsafeCell::new(data),
+            _pin: PhantomPinned,
+        }
+    }
+
+    /// # Safety
+    ///
+    /// * This lock must have been created using `global_lock_helper_new`.
+    /// * Must only be called once for each lock.
+    #[doc(hidden)]
+    pub unsafe fn global_lock_helper_init(
+        self: Pin<&Self>,
+        name: &'static CStr,
+        key: &'static LockClassKey,
+    ) {
+        // SAFETY: The pointer to `state` is valid for the duration of this call, and both `name`
+        // and `key` are valid indefinitely.
+        unsafe { B::init(self.state.get(), name.as_char_ptr(), key.as_ptr()) }
+    }
 }
 
 impl<T: ?Sized, B: Backend> Lock<T, B> {
rust/kernel/sync/lock/global.rs new file +260 -0

260 lines not on this page · raw message

---
base-commit: e2bde5e2cb2e5b8dca87adce3a9eb605133518ea
change-id: 20240826-static-mutex-a4b228e0e6aa

Best regards,

Signature · 1 line
Alice Ryhl <[email protected]>
#1 lore raw
Quoted 82 lines · Alice Ryhl
rust/kernel/sync/lock/global.rs new file +76 -0
new file mode 100644
index 000000000000..fc02fac864f6
@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Support for defining statics containing locks.
+
+/// Defines a global lock.
+///
+/// Supports the following options:
+///
+/// * `value` specifies the initial value in the global lock.
+/// * `wrapper` specifies the name of the wrapper struct.
+/// * `guard` specifies the name of the guard type.
+/// * `locked_by` specifies the name of the `LockedBy` type.
+///
+/// # Examples
+///
+/// A global counter.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_COUNTER: Mutex<u32> = unsafe { uninit };
+///     value: 0;
+/// }
+///
+/// fn increment_counter() -> u32 {
+///     let mut guard = MY_COUNTER.lock();
+///     *guard += 1;
+///     *guard
+/// }
+///
+/// impl kernel::Module for MyModule {
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_COUNTER.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```
+///
+/// A global mutex used to protect all instances of a given struct.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_MUTEX: Mutex<()> = unsafe { uninit };
+///     value: ();
+///     guard: MyGuard;
+///     locked_by: LockedByMyMutex;
+/// }
+///
+/// /// All instances of this struct are protected by `MY_MUTEX`.
+/// struct MyStruct {
+///     my_counter: LockedByMyMutex<u32>,
+/// }
+///
+/// impl MyStruct {
+///     /// Increment the counter in this instance.
+///     ///
+///     /// The caller must hold the `MY_MUTEX` mutex.
+///     fn increment(&self, guard: &mut MyGuard) -> u32 {
+///         let my_counter = self.my_counter.as_mut(guard);
+///         *my_counter += 1;
+///         *my_counter
+///     }
+/// }
+///
+/// impl kernel::Module for MyModule {

rust/kernel/sync/lock/global.rs line 86

Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_MUTEX.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```

The docs here don't mention that you still need to call .init() manually (though the examples show it nicely). I don't know if we want macros to have a # Safety section.

rust/kernel/sync/lock/global.rs line 91

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

rust/kernel/sync/lock/global.rs line 101

Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+        wrapper: $wrapper:ident;
+        $( name: $lname:literal; )?
+        $(
+            guard: $guard:ident;
+            locked_by: $locked_by:ident;
+        )?
+    } => {
+        $crate::macros::paste! {
+            type [< __static_lock_ty_ $name >] = $valuety;
+            const [< __static_lock_init_ $name >]: [< __static_lock_ty_ $name >] = $value;

Why are these two items outside of the mod below? Also why do you need to define the type alias? You could just use $valuety, right?

Also,

    error: type `__static_lock_ty_VALUE` should have an upper camel case name
       --> rust/kernel/sync/lock/global.rs:100:18
        |
    100 |               type [< __static_lock_ty_ $name >] = $valuety;
        |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: convert the identifier to upper camel case: `StaticLockTyValue`

The same error affects the wrapper type forwarding below.

rust/kernel/sync/lock/global.rs line 103

Quoted 2 lines
rust/kernel/sync/lock/global.rs new file +2 -0
+
+            #[allow(unused_pub)]

error: unknown lint: unused_pub
--> rust/kernel/sync/lock/global.rs:103:21
|
103 | #[allow(unused_pub)]
| ^^^^^^^^^^ help: did you mean: unused_mut

Though I also get

    error: methods `init` and `lock` are never used
       --> rust/kernel/sync/lock/global.rs:128:42
        |
    122 | /                 impl $wrapper {
    123 | |                     /// Initialize the global lock.
    124 | |                     ///
    125 | |                     /// # Safety
    ...   |
    128 | |                     pub(crate) unsafe fn init(&'static self) {
        | |                                          ^^^^
    ...   |
    142 | |                     pub(crate) fn lock(&'static self) -> $crate::global_lock_inner!(guard $kind, $valuety $(, $guard)?) {
        | |                                   ^^^^
    ...   |
    146 | |                     }
    147 | |                 }
        | |_________________- methods in this implementation

But that is governed by the dead_code lint.

rust/kernel/sync/lock/global.rs line 108

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+            mod [< __static_lock_mod_ $name >] {
+                use super::[< __static_lock_ty_ $name >] as Val;
+                use super::[< __static_lock_init_ $name >] as INIT;
+                type Backend = $crate::global_lock_inner!(backend $kind);
+                type GuardTyp = $crate::global_lock_inner!(guard $kind, Val $(, $guard)?);

GuardTyp is only used once, so you should be able to just inline it. Backend is used twice, but I don't know if we need a type alias for it.

rust/kernel/sync/lock/global.rs line 113

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+
+                /// # Safety
+                ///
+                /// Must be used to initialize `super::$name`.
+                pub(super) const unsafe fn new() -> $wrapper {

Why is this function not associated to $wrapper?

rust/kernel/sync/lock/global.rs line 114

Quoted 1 line
rust/kernel/sync/lock/global.rs new file +1 -0
+                    let state = $crate::types::Opaque::uninit();

Why not add

    const INIT: $valuety = $value;

here instead of outside the mod.

rust/kernel/sync/lock/global.rs line 125

Quoted 11 lines
rust/kernel/sync/lock/global.rs new file +11 -0
+                    $wrapper {
+                        // SAFETY: The user of this macro promises to call `init` before calling
+                        // `lock`.
+                        inner: unsafe {
+                            $crate::sync::lock::Lock::global_lock_helper_new(state, INIT)
+                        }
+                    }
+                }
+
+                /// Wrapper type for a global lock.
+                pub(crate) struct $wrapper {

How can the wrapper struct be pub(crate) when the constant might be global pub?

    error: type `__static_lock_wrapper_INIT` is more private than the item `INIT`                                                                                                                                                           
       --> rust/kernel/sync/lock/global.rs:206:14
        |                                    
    206 |               };                       
        |                ^ static `INIT` is reachable at visibility `pub`
        |                 

The functions should probably just be pub.

---
Cheers,
Benno

Quoted 4 lines
rust/kernel/sync/lock/global.rs new file +4 -0
+                    inner: $crate::sync::lock::Lock<Val, Backend>,
+                }
+
+               
author maintainer
#2 lore raw
Quoted 111 lines · Benno Lossin
Quoted 82 lines · Alice Ryhl
rust/kernel/sync/lock/global.rs new file +76 -0
new file mode 100644
index 000000000000..fc02fac864f6
@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Support for defining statics containing locks.
+
+/// Defines a global lock.
+///
+/// Supports the following options:
+///
+/// * `value` specifies the initial value in the global lock.
+/// * `wrapper` specifies the name of the wrapper struct.
+/// * `guard` specifies the name of the guard type.
+/// * `locked_by` specifies the name of the `LockedBy` type.
+///
+/// # Examples
+///
+/// A global counter.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_COUNTER: Mutex<u32> = unsafe { uninit };
+///     value: 0;
+/// }
+///
+/// fn increment_counter() -> u32 {
+///     let mut guard = MY_COUNTER.lock();
+///     *guard += 1;
+///     *guard
+/// }
+///
+/// impl kernel::Module for MyModule {
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_COUNTER.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```
+///
+/// A global mutex used to protect all instances of a given struct.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_MUTEX: Mutex<()> = unsafe { uninit };
+///     value: ();
+///     guard: MyGuard;
+///     locked_by: LockedByMyMutex;
+/// }
+///
+/// /// All instances of this struct are protected by `MY_MUTEX`.
+/// struct MyStruct {
+///     my_counter: LockedByMyMutex<u32>,
+/// }
+///
+/// impl MyStruct {
+///     /// Increment the counter in this instance.
+///     ///
+///     /// The caller must hold the `MY_MUTEX` mutex.
+///     fn increment(&self, guard: &mut MyGuard) -> u32 {
+///         let my_counter = self.my_counter.as_mut(guard);
+///         *my_counter += 1;
+///         *my_counter
+///     }
+/// }
+///
+/// impl kernel::Module for MyModule {

rust/kernel/sync/lock/global.rs line 86

Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_MUTEX.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```

The docs here don't mention that you still need to call .init() manually (though the examples show it nicely). I don't know if we want macros to have a # Safety section.

rust/kernel/sync/lock/global.rs line 91

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

Quoted 11 lines

rust/kernel/sync/lock/global.rs line 101

Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+        wrapper: $wrapper:ident;
+        $( name: $lname:literal; )?
+        $(
+            guard: $guard:ident;
+            locked_by: $locked_by:ident;
+        )?
+    } => {
+        $crate::macros::paste! {
+            type [< __static_lock_ty_ $name >] = $valuety;
+            const [< __static_lock_init_ $name >]: [< __static_lock_ty_ $name >] = $value;
Quoted 3 lines

Why are these two items outside of the mod below? Also why do you need to define the type alias? You could just use $valuety, right?

Because they might access things that are in scope here, but not in scope inside the module.

Quoted 11 lines

Also,

    error: type `__static_lock_ty_VALUE` should have an upper camel case name
       --> rust/kernel/sync/lock/global.rs:100:18
        |
    100 |               type [< __static_lock_ty_ $name >] = $valuety;
        |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: convert the identifier to upper camel case: `StaticLockTyValue`

The same error affects the wrapper type forwarding below.

Quoted 8 lines

rust/kernel/sync/lock/global.rs line 103

Quoted 2 lines
rust/kernel/sync/lock/global.rs new file +2 -0
+
+            #[allow(unused_pub)]

error: unknown lint: unused_pub
--> rust/kernel/sync/lock/global.rs:103:21
|
103 | #[allow(unused_pub)]
| ^^^^^^^^^^ help: did you mean: unused_mut

Uhhh. This is the lint for when you mark a function pub but don't actually export it from the crate. But now I can't find the lint anywhere ... I'm so confused.

Quoted 20 lines

Though I also get

    error: methods `init` and `lock` are never used
       --> rust/kernel/sync/lock/global.rs:128:42
        |
    122 | /                 impl $wrapper {
    123 | |                     /// Initialize the global lock.
    124 | |                     ///
    125 | |                     /// # Safety
    ...   |
    128 | |                     pub(crate) unsafe fn init(&'static self) {
        | |                                          ^^^^
    ...   |
    142 | |                     pub(crate) fn lock(&'static self) -> $crate::global_lock_inner!(guard $kind, $valuety $(, $guard)?) {
        | |                                   ^^^^
    ...   |
    146 | |                     }
    147 | |                 }
        | |_________________- methods in this implementation
Quoted 1 line

But that is governed by the dead_code lint.

I guess I have to look into the lints again. I did not get this lint.

Quoted 9 lines

rust/kernel/sync/lock/global.rs line 108

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+            mod [< __static_lock_mod_ $name >] {
+                use super::[< __static_lock_ty_ $name >] as Val;
+                use super::[< __static_lock_init_ $name >] as INIT;
+                type Backend = $crate::global_lock_inner!(backend $kind);
+                type GuardTyp = $crate::global_lock_inner!(guard $kind, Val $(, $guard)?);

GuardTyp is only used once, so you should be able to just inline it. Backend is used twice, but I don't know if we need a type alias for it.

They're both used twice. Inlining them makes the lines really long.

Quoted 8 lines

rust/kernel/sync/lock/global.rs line 113

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+
+                /// # Safety
+                ///
+                /// Must be used to initialize `super::$name`.
+                pub(super) const unsafe fn new() -> $wrapper {

Why is this function not associated to $wrapper?

Quoted 7 lines

rust/kernel/sync/lock/global.rs line 114

Quoted 1 line
rust/kernel/sync/lock/global.rs new file +1 -0
+                    let state = $crate::types::Opaque::uninit();

Why not add

    const INIT: $valuety = $value;

here instead of outside the mod.

Because it might reference things that are only in scope outside of the module.

Quoted 15 lines

rust/kernel/sync/lock/global.rs line 125

Quoted 11 lines
rust/kernel/sync/lock/global.rs new file +11 -0
+                    $wrapper {
+                        // SAFETY: The user of this macro promises to call `init` before calling
+                        // `lock`.
+                        inner: unsafe {
+                            $crate::sync::lock::Lock::global_lock_helper_new(state, INIT)
+                        }
+                    }
+                }
+
+                /// Wrapper type for a global lock.
+                pub(crate) struct $wrapper {

How can the wrapper struct be pub(crate) when the constant might be global pub?

Quoted 8 lines
    error: type `__static_lock_wrapper_INIT` is more private than the item `INIT`
       --> rust/kernel/sync/lock/global.rs:206:14
        |
    206 |               };
        |                ^ static `INIT` is reachable at visibility `pub`
        |

The functions should probably just be pub.

I used to do that, but got some errors about pub being unused. I'll look into this again.

Alice

#3 lore raw

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

rust/kernel/sync/lock/global.rs line 91

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

	global_lock!{
	    static MY_LOCK: Mutex<u32> = unsafe { 0 };
	}

or

	global_lock!{
	    static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
	}

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

Besides, instead of a "guard" type name, could you make a generic guard type over the "locked_by" type? E.g.

	struct GlobalGuard<L: GlobalLockedBy>(Guard<...>, PhantomData<*mut L>);

I feel like this could make the relationship between the guard type and the locked_by type more obvious. But maybe there's something I'm missing?

Regards,
Boqun

[...]

author maintainer
#4 lore raw
Quoted 33 lines · Boqun Feng

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

rust/kernel/sync/lock/global.rs line 91

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { 0 };
        }

or

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
        }
Quoted 5 lines

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

uninit { 0 } looks pretty terrible IMO. Can we come up with something better?

Quoted 8 lines

Besides, instead of a "guard" type name, could you make a generic guard type over the "locked_by" type? E.g.

        struct GlobalGuard<L: GlobalLockedBy>(Guard<...>, PhantomData<*mut L>);

I feel like this could make the relationship between the guard type and the locked_by type more obvious. But maybe there's something I'm missing?

Sorry, I don't understand this. Why is the LockedBy type relevant to the guard?

Alice

#5 lore raw
Quoted 34 lines · Alice Ryhl
Quoted 33 lines · Boqun Feng

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

rust/kernel/sync/lock/global.rs line 91

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { 0 };
        }

or

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
        }
Quoted 8 lines
Quoted 5 lines

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

uninit { 0 } looks pretty terrible IMO. Can we come up with something better?

I'm trying, but in the meanwhile, another idea comes to me, can we just avoid using the global_lock! macro if "locked_by" is not needed? I.e. as the global counter in your examples, we probably need a new lock type in these cases but we don't use macros. I feel like macros don't bring us anything in these usages. As a result, we make global_lock! dedicated for locked_by usages, where values should usually be a ().

Quoted 11 lines
Quoted 8 lines

Besides, instead of a "guard" type name, could you make a generic guard type over the "locked_by" type? E.g.

        struct GlobalGuard<L: GlobalLockedBy>(Guard<...>, PhantomData<*mut L>);

I feel like this could make the relationship between the guard type and the locked_by type more obvious. But maybe there's something I'm missing?

Sorry, I don't understand this. Why is the LockedBy type relevant to the guard?

well, $locked_by's as_ref() and as_mut() both need a $guard reference, instead of asking users to provide an arbitrary $guard name, I thought it's better to just make $guard generic over $locked_by. However, I realise that $locked_by is a generic type over T, so my previous proposal doesn't work. How about another way around: making $locked_by type generic over $guard:

	pub(crate) struct GlobalLockedBy<T: ?Sized, G>(::core::cell::UnsafeCell<T>, ...);

(G is a $guard type)

and if we do

	global_lock!{
	    static MY_LOCK ...;
	    guard: MyGuard;
	}

we can have a struct:

	struct MyStruct {
	    inner: GlobalLockedBy<u32, MyGuard>
	}

instead of asking users to provide a name of the $locked_by type.

Does this makes sense?

Regards,
Boqun

Quoted 1 line

Alice

#6 lore raw
Quoted 35 lines · Boqun Feng
Quoted 34 lines · Alice Ryhl
Quoted 33 lines · Boqun Feng

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

rust/kernel/sync/lock/global.rs line 91

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { 0 };
        }

or

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
        }
Quoted 9 lines
Quoted 8 lines
Quoted 5 lines

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

uninit { 0 } looks pretty terrible IMO. Can we come up with something better?

how about:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { data: 0 };
        }

?

"data: " will make it clear that the value is not for the lock state. "uninit" is dropped because the "unsafe" already requires the global variable to be initialised first. Or "unsafe { uninit, data: 0 }" if you want to keep the "uninit" part?

Regards,
Boqun

[...]

#7 lore raw
Quoted 42 lines · Boqun Feng
Quoted 41 lines · Boqun Feng
Quoted 40 lines · Alice Ryhl
Quoted 38 lines · Boqun Feng

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

Review

Quoted 5 lines
(quoted diff) +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { 0 };
        }

or

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
        }

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

Quoted 8 lines
Quoted 3 lines
Quoted 2 lines

uninit { 0 } looks pretty terrible IMO. Can we come up with something better?

how about:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { data: 0 };

I dislike this, since there is no uninit anywhere, but the mutex needs to be initialized.

Quoted 8 lines
        }

?

"data: " will make it clear that the value is not for the lock state. "uninit" is dropped because the "unsafe" already requires the global variable to be initialised first. Or "unsafe { uninit, data: 0 }" if you want to keep the "uninit" part?

That also looks weird to me...

But I haven't come up with a good alternative

---
Cheers,
Benno

#8 lore raw
Quoted 59 lines · Benno Lossin
Quoted 42 lines · Boqun Feng
Quoted 41 lines · Boqun Feng
Quoted 40 lines · Alice Ryhl
Quoted 38 lines · Boqun Feng

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

Review

Quoted 5 lines
(quoted diff) +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { 0 };
        }

or

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
        }

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

Quoted 8 lines
Quoted 3 lines
Quoted 2 lines

uninit { 0 } looks pretty terrible IMO. Can we come up with something better?

how about:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { data: 0 };

I dislike this, since there is no uninit anywhere, but the mutex needs to be initialized.

Quoted 4 lines
        }

?

Quoted 9 lines
Quoted 4 lines

"data: " will make it clear that the value is not for the lock state. "uninit" is dropped because the "unsafe" already requires the global variable to be initialised first. Or "unsafe { uninit, data: 0 }" if you want to keep the "uninit" part?

That also looks weird to me...

But I haven't come up with a good alternative

How about a "fake" MaybyUninit:

	global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { MaybeUninit::new(0).assume_init() };
	}

?

I feel like we need to put the data in the initialization expression because if we resolve the initialization issues and can skip the extra init step, we pretty much want to use the macro like:

	global_lock!{
            static MY_LOCK: Mutex<u32> = { data: 0 };
	    // maybe even
            // static MY_LOCK: Mutex<u32> = { 0 };
	}

instead of

	global_lock!{
            static MY_LOCK: Mutex<u32> = init;
	    value = 0;
	}

, right?

So we need to think about providing a smooth way for users to transfer. Not just adjust the changes (which I believe is a good practice for coccinelle), but also the conceptual model "oh now I don't need to provide a 'value=' field?". Hence even though the above proposals may look weird, but I think that's still better?

Regards,
Boqun

Quoted 4 lines

---
Cheers,
Benno

#9 lore raw
Quoted 70 lines · Boqun Feng
Quoted 59 lines · Benno Lossin
Quoted 42 lines · Boqun Feng
Quoted 41 lines · Boqun Feng
Quoted 40 lines · Alice Ryhl
Quoted 38 lines · Boqun Feng

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

Review

Quoted 5 lines
(quoted diff) +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { 0 };
        }

or

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
        }

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

Quoted 8 lines
Quoted 3 lines
Quoted 2 lines

uninit { 0 } looks pretty terrible IMO. Can we come up with something better?

how about:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { data: 0 };

I dislike this, since there is no uninit anywhere, but the mutex needs to be initialized.

Quoted 4 lines
        }

?

Quoted 9 lines
Quoted 4 lines

"data: " will make it clear that the value is not for the lock state. "uninit" is dropped because the "unsafe" already requires the global variable to be initialised first. Or "unsafe { uninit, data: 0 }" if you want to keep the "uninit" part?

That also looks weird to me...

But I haven't come up with a good alternative

Quoted 7 lines

How about a "fake" MaybyUninit:

	global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { MaybeUninit::new(0).assume_init() };
	}

?

That still suggests to the user, that the contents are initialized.

Quoted 17 lines

I feel like we need to put the data in the initialization expression because if we resolve the initialization issues and can skip the extra init step, we pretty much want to use the macro like:

	global_lock!{
            static MY_LOCK: Mutex<u32> = { data: 0 };
	    // maybe even
            // static MY_LOCK: Mutex<u32> = { 0 };
	}

instead of

	global_lock!{
            static MY_LOCK: Mutex<u32> = init;
	    value = 0;
	}
Quoted 6 lines

, right?

So we need to think about providing a smooth way for users to transfer. Not just adjust the changes (which I believe is a good practice for coccinelle), but also the conceptual model "oh now I don't need to provide a 'value=' field?".

I think we can just use a multiline regex to find global_lock! and then change the current way. It shouldn't be that difficult to change.

Quoted 2 lines

Hence even though the above proposals may look weird, but I think that's still better?

Do you think that we will have 1000s of users by the time we change it? I don't think so, but I don't know how often drivers use global locks. I think we should discourage them. People still can have a "global" lock by putting it inside of their Module struct (they need access to the module, but maybe we should have a function that gives them the module for the ThisModule pointer?)

---
Cheers,
Benno

#10 lore raw
Quoted 100 lines · Benno Lossin
Quoted 70 lines · Boqun Feng
Quoted 59 lines · Benno Lossin
Quoted 42 lines · Boqun Feng
Quoted 41 lines · Boqun Feng
Quoted 40 lines · Alice Ryhl
Quoted 38 lines · Boqun Feng

On Thu, Oct 10, 2024 at 12:53:00PM +0200, Alice Ryhl wrote:
[...]

Quoted 12 lines
Quoted 12 lines

Review

Quoted 5 lines
(quoted diff) +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 5 lines
Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

While we are at it, how about we make the syntax:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { 0 };
        }

or

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { uninit { 0 } };
        }

?

i.e. instead of a "value" field, we put it in the "initialization expression". To me, this make it more clear that "value" is the initialized value protected by the lock. Thoughts?

Quoted 8 lines
Quoted 3 lines
Quoted 2 lines

uninit { 0 } looks pretty terrible IMO. Can we come up with something better?

how about:

        global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { data: 0 };

I dislike this, since there is no uninit anywhere, but the mutex needs to be initialized.

Quoted 4 lines
        }

?

Quoted 9 lines
Quoted 4 lines

"data: " will make it clear that the value is not for the lock state. "uninit" is dropped because the "unsafe" already requires the global variable to be initialised first. Or "unsafe { uninit, data: 0 }" if you want to keep the "uninit" part?

That also looks weird to me...

But I haven't come up with a good alternative

Quoted 7 lines

How about a "fake" MaybyUninit:

	global_lock!{
            static MY_LOCK: Mutex<u32> = unsafe { MaybeUninit::new(0).assume_init() };
	}

?

That still suggests to the user, that the contents are initialized.

Quoted 19 lines

I feel like we need to put the data in the initialization expression because if we resolve the initialization issues and can skip the extra init step, we pretty much want to use the macro like:

	global_lock!{
            static MY_LOCK: Mutex<u32> = { data: 0 };
	    // maybe even
            // static MY_LOCK: Mutex<u32> = { 0 };
	}

instead of

	global_lock!{
            static MY_LOCK: Mutex<u32> = init;
	    value = 0;
	}

, right?

Quoted 8 lines
Quoted 4 lines

So we need to think about providing a smooth way for users to transfer. Not just adjust the changes (which I believe is a good practice for coccinelle), but also the conceptual model "oh now I don't need to provide a 'value=' field?".

I think we can just use a multiline regex to find global_lock! and then change the current way. It shouldn't be that difficult to change.

This only solves the "not just" part of the problem, it still confuses the users why "value=" used to be a field but then becomes in the initialization expression. In fact, after I take a deep look, I think we should also move the optional "name=" field (the name for lockdep class) to the static-item-like statement, i.e.

    global_lock!{
        // I use a new format here, which I think it's better than
	// previous proposed formats.
        static MY_LOCK: Mutex<u32> = { unsafe { uninit }, data: 0, name: "my_lock" };
    }

I think it makes more sense than making "value=" and "name=" as fields. Think about this: we choose to use a statement in global_lock!() macro that is similar to a static item because we want to let users know what the macro does is similar as defining a static item, right? If so, wouldn't it make more sense to have the initialization inputs in the static-item-like statement instead of a separate field? This will provide a clear picture to users that which macro parameter participates the initialization of the static variable.

Besides, for guard/locked_by, the current format will be something like:

    global_lock!{
        static MY_LOCK: Mutex<u32> = unsafe { uninit };
	value=0;
	guard=MyGuard;
	locked_by=MyLockedBy;
    }

"value=" is the value used to initialize MY_LOCK, and "guard=" and "locked_by=" are the types associated with the static variable, making these three parallel in the same level doesn't really make logical sense to me. I cannot find any reason this is better than making "value=" part of the initialization expression.

Your argument seems to be that will be weird, however, as you mentioned below, you don't think there will be many users, so being weird but accurate on what are used to initialize the static variable is fine. ;-)

Plus, there is no implementation difficulty, so let do it right.

Regards,
Boqun

Quoted 14 lines
Quoted 2 lines

Hence even though the above proposals may look weird, but I think that's still better?

Do you think that we will have 1000s of users by the time we change it? I don't think so, but I don't know how often drivers use global locks. I think we should discourage them. People still can have a "global" lock by putting it inside of their Module struct (they need access to the module, but maybe we should have a function that gives them the module for the ThisModule pointer?)

---
Cheers,
Benno

#11 lore raw
In reply to Alice Ryhl
Quoted 128 lines · Alice Ryhl
Quoted 111 lines · Benno Lossin
Quoted 82 lines · Alice Ryhl
rust/kernel/sync/lock/global.rs new file +76 -0
new file mode 100644
index 000000000000..fc02fac864f6
@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Support for defining statics containing locks.
+
+/// Defines a global lock.
+///
+/// Supports the following options:
+///
+/// * `value` specifies the initial value in the global lock.
+/// * `wrapper` specifies the name of the wrapper struct.
+/// * `guard` specifies the name of the guard type.
+/// * `locked_by` specifies the name of the `LockedBy` type.
+///
+/// # Examples
+///
+/// A global counter.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_COUNTER: Mutex<u32> = unsafe { uninit };
+///     value: 0;
+/// }
+///
+/// fn increment_counter() -> u32 {
+///     let mut guard = MY_COUNTER.lock();
+///     *guard += 1;
+///     *guard
+/// }
+///
+/// impl kernel::Module for MyModule {
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_COUNTER.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```
+///
+/// A global mutex used to protect all instances of a given struct.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_MUTEX: Mutex<()> = unsafe { uninit };
+///     value: ();
+///     guard: MyGuard;
+///     locked_by: LockedByMyMutex;
+/// }
+///
+/// /// All instances of this struct are protected by `MY_MUTEX`.
+/// struct MyStruct {
+///     my_counter: LockedByMyMutex<u32>,
+/// }
+///
+/// impl MyStruct {
+///     /// Increment the counter in this instance.
+///     ///
+///     /// The caller must hold the `MY_MUTEX` mutex.
+///     fn increment(&self, guard: &mut MyGuard) -> u32 {
+///         let my_counter = self.my_counter.as_mut(guard);
+///         *my_counter += 1;
+///         *my_counter
+///     }
+/// }
+///
+/// impl kernel::Module for MyModule {

rust/kernel/sync/lock/global.rs line 86

Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_MUTEX.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```

The docs here don't mention that you still need to call .init() manually (though the examples show it nicely). I don't know if we want macros to have a # Safety section.

rust/kernel/sync/lock/global.rs line 91

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;

I would find it more natural to use = instead of : here, since then it would read as a normal statement with the semicolon at the end. Another alternative would be to use , instead of ;, but that doesn't work nicely with the static keyword above (although you could make the user write it in another {}, but that also isn't ideal...).

Quoted 2 lines

Using = instead of : makes my editor put the correct amount of indentation there, : adds a lot of extra spaces.

That seems sensible.

Quoted 11 lines
Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+        wrapper: $wrapper:ident;
+        $( name: $lname:literal; )?
+        $(
+            guard: $guard:ident;
+            locked_by: $locked_by:ident;
+        )?
+    } => {
+        $crate::macros::paste! {
+            type [< __static_lock_ty_ $name >] = $valuety;
+            const [< __static_lock_init_ $name >]: [< __static_lock_ty_ $name >] = $value;
Quoted 6 lines
Quoted 3 lines

Why are these two items outside of the mod below? Also why do you need to define the type alias? You could just use $valuety, right?

Because they might access things that are in scope here, but not in scope inside the module.

Right... That's rather annoying...

Quoted 20 lines
Quoted 11 lines

Also,

    error: type `__static_lock_ty_VALUE` should have an upper camel case name
       --> rust/kernel/sync/lock/global.rs:100:18
        |
    100 |               type [< __static_lock_ty_ $name >] = $valuety;
        |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: convert the identifier to upper camel case: `StaticLockTyValue`

The same error affects the wrapper type forwarding below.

Quoted 8 lines

rust/kernel/sync/lock/global.rs line 103

Quoted 2 lines
rust/kernel/sync/lock/global.rs new file +2 -0
+
+            #[allow(unused_pub)]

error: unknown lint: unused_pub
--> rust/kernel/sync/lock/global.rs:103:21
|
103 | #[allow(unused_pub)]
| ^^^^^^^^^^ help: did you mean: unused_mut

Quoted 3 lines

Uhhh. This is the lint for when you mark a function pub but don't actually export it from the crate. But now I can't find the lint anywhere ... I'm so confused.

Maybe you mean unreachable_pub?

Quoted 20 lines
Quoted 20 lines

Though I also get

    error: methods `init` and `lock` are never used
       --> rust/kernel/sync/lock/global.rs:128:42
        |
    122 | /                 impl $wrapper {
    123 | |                     /// Initialize the global lock.
    124 | |                     ///
    125 | |                     /// # Safety
    ...   |
    128 | |                     pub(crate) unsafe fn init(&'static self) {
        | |                                          ^^^^
    ...   |
    142 | |                     pub(crate) fn lock(&'static self) -> $crate::global_lock_inner!(guard $kind, $valuety $(, $guard)?) {
        | |                                   ^^^^
    ...   |
    146 | |                     }
    147 | |                 }
        | |_________________- methods in this implementation
Quoted 3 lines
Quoted 1 line

But that is governed by the dead_code lint.

I guess I have to look into the lints again. I did not get this lint.

I just put a global_lock! invocation into lib.rs and didn't use any of the functions. But maybe we want that to error?

Quoted 11 lines
Quoted 9 lines

rust/kernel/sync/lock/global.rs line 108

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+            mod [< __static_lock_mod_ $name >] {
+                use super::[< __static_lock_ty_ $name >] as Val;
+                use super::[< __static_lock_init_ $name >] as INIT;
+                type Backend = $crate::global_lock_inner!(backend $kind);
+                type GuardTyp = $crate::global_lock_inner!(guard $kind, Val $(, $guard)?);

GuardTyp is only used once, so you should be able to just inline it. Backend is used twice, but I don't know if we need a type alias for it.

They're both used twice. Inlining them makes the lines really long.

Ah I missed the one on try_lock. It's fine to keep them.

Quoted 22 lines
Quoted 22 lines

rust/kernel/sync/lock/global.rs line 125

Quoted 11 lines
rust/kernel/sync/lock/global.rs new file +11 -0
+                    $wrapper {
+                        // SAFETY: The user of this macro promises to call `init` before calling
+                        // `lock`.
+                        inner: unsafe {
+                            $crate::sync::lock::Lock::global_lock_helper_new(state, INIT)
+                        }
+                    }
+                }
+
+                /// Wrapper type for a global lock.
+                pub(crate) struct $wrapper {

How can the wrapper struct be pub(crate) when the constant might be global pub?

    error: type `__static_lock_wrapper_INIT` is more private than the item `INIT`
       --> rust/kernel/sync/lock/global.rs:206:14
        |
    206 |               };
        |                ^ static `INIT` is reachable at visibility `pub`
        |
Quoted 4 lines
Quoted 1 line

The functions should probably just be pub.

I used to do that, but got some errors about pub being unused. I'll look into this again.

Maybe the unreachable_pub lint can help?

---
Cheers,
Benno

#12 lore raw
In reply to Benno Lossin
Quoted 9 lines · Benno Lossin

Also,

    error: type `__static_lock_ty_VALUE` should have an upper camel case name
       --> rust/kernel/sync/lock/global.rs:100:18
        |
    100 |               type [< __static_lock_ty_ $name >] = $valuety;
        |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: convert the identifier to upper camel case: `StaticLockTyValue`

How did you manage to get these errors? The only thing I get from clippy is this:

CC rust/doctests_kernel_generated_kunit.o
warning: question mark operator is useless here

    --> rust/doctests_kernel_generated.rs:4744:1
     |
4744 | / kernel::sync::global_lock! {
4745 | |     // SAFETY: Initialized in module initializer before first use.
4746 | |     static MY_COUNTER: Mutex<u32> = unsafe { uninit };
4747 | |     value: 0;
4748 | | }
     | |_^
     |

= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#needless_question_mark
= note: -W clippy::needless-question-mark implied by -W clippy::all
= help: to override -W clippy::all add #[allow(clippy::needless_question_mark)]
= note: this warning originates in the macro $crate::global_lock which comes from the expansion of the macro kernel::sync::global_lock (in Nightly builds, run with -Z macro-backtrace for more info)

warning: 1 warning emitted

BR Andreas

#13 lore raw
Quoted 5 lines · Andreas Hindborg
Quoted 3 lines · Benno Lossin

Also,

Quoted 8 lines
Quoted 6 lines
    error: type `__static_lock_ty_VALUE` should have an upper camel case name
       --> rust/kernel/sync/lock/global.rs:100:18
        |
    100 |               type [< __static_lock_ty_ $name >] = $valuety;
        |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: convert the identifier to upper camel case: `StaticLockTyValue`

How did you manage to get these errors?

I added a global_lock! invocation to lib.rs. Otherwise I also don't get them (they might also be emitted from the examples, but I didn't compile those).

---
Cheers,
Benno

#14 lore raw
Quoted 13 lines · Benno Lossin
Quoted 12 lines · Andreas Hindborg
Quoted 9 lines · Benno Lossin

Also,

    error: type `__static_lock_ty_VALUE` should have an upper camel case name
       --> rust/kernel/sync/lock/global.rs:100:18
        |
    100 |               type [< __static_lock_ty_ $name >] = $valuety;
        |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: convert the identifier to upper camel case: `StaticLockTyValue`
Quoted 5 lines
Quoted 1 line

How did you manage to get these errors?

I added a global_lock! invocation to lib.rs. Otherwise I also don't get them (they might also be emitted from the examples, but I didn't compile those).

I build the examples for kunit, but I did not get any warnings. Interesting.

BR Andreas

#15 lore raw
In reply to Alice Ryhl

Hi Alice,

Quoted 9 lines · Alice Ryhl

Add support for creating global variables that are wrapped in a mutex or spinlock. Optionally, the macro can generate a special LockedBy type that does not require a runtime check.

The implementation here is intended to replace the global mutex workaround found in the Rust Binder RFC [1]. In both cases, the global lock must be initialized before first use. The macro is unsafe to use for the same reason.

Quoted 4 lines

The separate initialization step is required because it is tricky to access the value of __ARCH_SPIN_LOCK_UNLOCKED from Rust. Doing so will require changes to the C side. That change will happen as a follow-up to this patch.

Why is this a challenge? It seems to work with locks that are not global.

[...]

Quoted 8 lines
rust/kernel/sync/lock/global.rs new file +2 -0
new file mode 100644
index 000000000000..fc02fac864f6
@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: GPL-2.0
+

rust/kernel/sync/lock/global.rs line 12

Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+// Copyright (C) 2024 Google LLC.
+
+//! Support for defining statics containing locks.
+
+/// Defines a global lock.
+///
+/// Supports the following options:
+///
+/// * `value` specifies the initial value in the global lock.
+/// * `wrapper` specifies the name of the wrapper struct.

Could you add an example to demonstrate when using wrapper option would be useful?

Quoted 133 lines
rust/kernel/sync/lock/global.rs new file +133 -0
+/// * `guard` specifies the name of the guard type.
+/// * `locked_by` specifies the name of the `LockedBy` type.
+///
+/// # Examples
+///
+/// A global counter.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_COUNTER: Mutex<u32> = unsafe { uninit };
+///     value: 0;
+/// }
+///
+/// fn increment_counter() -> u32 {
+///     let mut guard = MY_COUNTER.lock();
+///     *guard += 1;
+///     *guard
+/// }
+///
+/// impl kernel::Module for MyModule {
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_COUNTER.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```
+///
+/// A global mutex used to protect all instances of a given struct.
+///
+/// ```
+/// # mod ex {
+/// # use kernel::prelude::*;
+/// kernel::sync::global_lock! {
+///     // SAFETY: Initialized in module initializer before first use.
+///     static MY_MUTEX: Mutex<()> = unsafe { uninit };
+///     value: ();
+///     guard: MyGuard;
+///     locked_by: LockedByMyMutex;
+/// }
+///
+/// /// All instances of this struct are protected by `MY_MUTEX`.
+/// struct MyStruct {
+///     my_counter: LockedByMyMutex<u32>,
+/// }
+///
+/// impl MyStruct {
+///     /// Increment the counter in this instance.
+///     ///
+///     /// The caller must hold the `MY_MUTEX` mutex.
+///     fn increment(&self, guard: &mut MyGuard) -> u32 {
+///         let my_counter = self.my_counter.as_mut(guard);
+///         *my_counter += 1;
+///         *my_counter
+///     }
+/// }
+///
+/// impl kernel::Module for MyModule {
+///     fn init(_module: &'static ThisModule) -> Result<Self> {
+///         // SAFETY: called exactly once
+///         unsafe { MY_MUTEX.init() };
+///
+///         Ok(MyModule {})
+///     }
+/// }
+/// # struct MyModule {}
+/// # }
+/// ```
+#[macro_export]
+macro_rules! global_lock {
+    {
+        $(#[$meta:meta])* $pub:vis static $name:ident: $kind:ident<$valuety:ty> = unsafe { uninit };
+        value: $value:expr;
+        wrapper: $wrapper:ident;
+        $( name: $lname:literal; )?
+        $(
+            guard: $guard:ident;
+            locked_by: $locked_by:ident;
+        )?
+    } => {
+        $crate::macros::paste! {
+            type [< __static_lock_ty_ $name >] = $valuety;
+            const [< __static_lock_init_ $name >]: [< __static_lock_ty_ $name >] = $value;
+
+            #[allow(unused_pub)]
+            mod [< __static_lock_mod_ $name >] {
+                use super::[< __static_lock_ty_ $name >] as Val;
+                use super::[< __static_lock_init_ $name >] as INIT;
+                type Backend = $crate::global_lock_inner!(backend $kind);
+                type GuardTyp = $crate::global_lock_inner!(guard $kind, Val $(, $guard)?);
+
+                /// # Safety
+                ///
+                /// Must be used to initialize `super::$name`.
+                pub(super) const unsafe fn new() -> $wrapper {
+                    let state = $crate::types::Opaque::uninit();
+                    $wrapper {
+                        // SAFETY: The user of this macro promises to call `init` before calling
+                        // `lock`.
+                        inner: unsafe {
+                            $crate::sync::lock::Lock::global_lock_helper_new(state, INIT)
+                        }
+                    }
+                }
+
+                /// Wrapper type for a global lock.
+                pub(crate) struct $wrapper {
+                    inner: $crate::sync::lock::Lock<Val, Backend>,
+                }
+
+                impl $wrapper {
+                    /// Initialize the global lock.
+                    ///
+                    /// # Safety
+                    ///
+                    /// This method must not be called more than once.
+                    pub(crate) unsafe fn init(&'static self) {
+                        // SAFETY:
+                        // * This type can only be created by `new`.
+                        // * Caller promises to not call this method more than once.
+                        unsafe {
+                            $crate::sync::lock::Lock::global_lock_helper_init(
+                                ::core::pin::Pin::static_ref(&self.inner),
+                                $crate::optional_name!($($lname)?),
+                                $crate::static_lock_class!(),
+                            );
+                        }

rust/kernel/sync/lock/global.rs line 155

Quoted 10 lines
rust/kernel/sync/lock/global.rs new file +10 -0
+                    }
+
+                    /// Lock this global lock.
+                    pub(crate) fn lock(&'static self) -> GuardTyp {
+                        $crate::global_lock_inner!(new_guard $($guard)? {
+                            self.inner.lock()
+                        })
+                    }
+
+                    /// Lock this global lock.

"Try to lock..." ?

Best regards,
Andreas

author maintainer
#16 lore raw
Quoted 14 lines · Andreas Hindborg

Hi Alice,

Quoted 9 lines · Alice Ryhl

Add support for creating global variables that are wrapped in a mutex or spinlock. Optionally, the macro can generate a special LockedBy type that does not require a runtime check.

The implementation here is intended to replace the global mutex workaround found in the Rust Binder RFC [1]. In both cases, the global lock must be initialized before first use. The macro is unsafe to use for the same reason.

Quoted 7 lines
Quoted 4 lines

The separate initialization step is required because it is tricky to access the value of __ARCH_SPIN_LOCK_UNLOCKED from Rust. Doing so will require changes to the C side. That change will happen as a follow-up to this patch.

Why is this a challenge? It seems to work with locks that are not global.

Because normal locks are not initialized in a const expression.

Quoted 13 lines
Quoted 13 lines
rust/kernel/sync/lock/global.rs new file +7 -0
new file mode 100644
index 000000000000..fc02fac864f6
@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Support for defining statics containing locks.
+
+/// Defines a global lock.
Quoted 8 lines

rust/kernel/sync/lock/global.rs line 12

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+///
+/// Supports the following options:
+///
+/// * `value` specifies the initial value in the global lock.
+/// * `wrapper` specifies the name of the wrapper struct.

Could you add an example to demonstrate when using wrapper option would be useful?

Probably only guard and locked_by are useful, but I think you need to give the wrapper a name to reasonably use guard/locked_by.

Quoted 3 lines

rust/kernel/sync/lock/global.rs line 13

Quoted 1 line
rust/kernel/sync/lock/global.rs new file +1 -0
+                    /// Lock this global lock.

"Try to lock..." ?

Thanks. Good point.

Alice

#17 lore raw
Quoted 47 lines · Alice Ryhl
Quoted 14 lines · Andreas Hindborg

Hi Alice,

Quoted 9 lines · Alice Ryhl

Add support for creating global variables that are wrapped in a mutex or spinlock. Optionally, the macro can generate a special LockedBy type that does not require a runtime check.

The implementation here is intended to replace the global mutex workaround found in the Rust Binder RFC [1]. In both cases, the global lock must be initialized before first use. The macro is unsafe to use for the same reason.

Quoted 7 lines
Quoted 4 lines

The separate initialization step is required because it is tricky to access the value of __ARCH_SPIN_LOCK_UNLOCKED from Rust. Doing so will require changes to the C side. That change will happen as a follow-up to this patch.

Why is this a challenge? It seems to work with locks that are not global.

Because normal locks are not initialized in a const expression.

Quoted 13 lines
Quoted 13 lines
rust/kernel/sync/lock/global.rs new file +7 -0
new file mode 100644
index 000000000000..fc02fac864f6
@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: GPL-2.0
+
+// Copyright (C) 2024 Google LLC.
+
+//! Support for defining statics containing locks.
+
+/// Defines a global lock.
Quoted 8 lines

rust/kernel/sync/lock/global.rs line 12

Quoted 5 lines
rust/kernel/sync/lock/global.rs new file +5 -0
+///
+/// Supports the following options:
+///
+/// * `value` specifies the initial value in the global lock.
+/// * `wrapper` specifies the name of the wrapper struct.

Could you add an example to demonstrate when using wrapper option would be useful?

Quoted 2 lines

Probably only guard and locked_by are useful, but I think you need to give the wrapper a name to reasonably use guard/locked_by.

Could you expand the example to show this, or would it become too long?

BR Andreas