rust: add global lock support
Subsystems (3)
Alice Ryhl
maintainerPATCH 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
@@ -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
@@ -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: &'staticCStr , + key: &'staticLockClassKey , + ) { +// 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]>
Quoted 82 lines · Alice Ryhl
rust/kernel/sync/lock/global.rs new file +76
-0@@ -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 implementationBut 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>, + } + +
Alice Ryhl
maintainerQuoted 111 lines · Benno Lossin
Quoted 82 lines · Alice Ryhl
rust/kernel/sync/lock/global.rs new file +76
-0@@ -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# Safetysection.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
modbelow? 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
wrappertype 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_codelint.
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)?);
GuardTypis only used once, so you should be able to just inline it.Backendis 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 globalpub?
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
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
[...]
Alice Ryhl
maintainerQuoted 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_bytype 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
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_bytype 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
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
[...]
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
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
uninitanywhere, 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
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
uninitanywhere, 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
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
uninitanywhere, 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
ThisModulepointer?)---
Cheers,
Benno
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@@ -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# Safetysection.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
modbelow? 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
wrappertype 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_codelint.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)?);
GuardTypis only used once, so you should be able to just inline it.Backendis 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 globalpub?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
pubbeing unused. I'll look into this again.
Maybe the unreachable_pub lint can help?
---
Cheers,
Benno
Andreas Hindborg
reviewerQuoted 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
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
Andreas Hindborg
reviewerQuoted 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 tolib.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
Andreas Hindborg
reviewerHi 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_UNLOCKEDfrom 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@@ -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:visstatic $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
Alice Ryhl
maintainerQuoted 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_UNLOCKEDfrom 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@@ -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
wrapperoption 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
Andreas Hindborg
reviewerQuoted 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_UNLOCKEDfrom 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@@ -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
wrapperoption would be useful?
Quoted 2 lines
Probably only guard and
locked_byare 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