Loading...
1// SPDX-License-Identifier: GPL-2.0
2
3//! A kernel mutex.
4//!
5//! This module allows Rust code to use the kernel's `struct mutex`.
6
7/// Creates a [`Mutex`] initialiser with the given name and a newly-created lock class.
8///
9/// It uses the name if one is given, otherwise it generates one based on the file name and line
10/// number.
11#[macro_export]
12macro_rules! new_mutex {
13 ($inner:expr $(, $name:literal)? $(,)?) => {
14 $crate::sync::Mutex::new(
15 $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!())
16 };
17}
18pub use new_mutex;
19
20/// A mutual exclusion primitive.
21///
22/// Exposes the kernel's [`struct mutex`]. When multiple threads attempt to lock the same mutex,
23/// only one at a time is allowed to progress, the others will block (sleep) until the mutex is
24/// unlocked, at which point another thread will be allowed to wake up and make progress.
25///
26/// Since it may block, [`Mutex`] needs to be used with care in atomic contexts.
27///
28/// Instances of [`Mutex`] need a lock class and to be pinned. The recommended way to create such
29/// instances is with the [`pin_init`](crate::pin_init) and [`new_mutex`] macros.
30///
31/// # Examples
32///
33/// The following example shows how to declare, allocate and initialise a struct (`Example`) that
34/// contains an inner struct (`Inner`) that is protected by a mutex.
35///
36/// ```
37/// use kernel::sync::{new_mutex, Mutex};
38///
39/// struct Inner {
40/// a: u32,
41/// b: u32,
42/// }
43///
44/// #[pin_data]
45/// struct Example {
46/// c: u32,
47/// #[pin]
48/// d: Mutex<Inner>,
49/// }
50///
51/// impl Example {
52/// fn new() -> impl PinInit<Self> {
53/// pin_init!(Self {
54/// c: 10,
55/// d <- new_mutex!(Inner { a: 20, b: 30 }),
56/// })
57/// }
58/// }
59///
60/// // Allocate a boxed `Example`.
61/// let e = KBox::pin_init(Example::new(), GFP_KERNEL)?;
62/// assert_eq!(e.c, 10);
63/// assert_eq!(e.d.lock().a, 20);
64/// assert_eq!(e.d.lock().b, 30);
65/// # Ok::<(), Error>(())
66/// ```
67///
68/// The following example shows how to use interior mutability to modify the contents of a struct
69/// protected by a mutex despite only having a shared reference:
70///
71/// ```
72/// use kernel::sync::Mutex;
73///
74/// struct Example {
75/// a: u32,
76/// b: u32,
77/// }
78///
79/// fn example(m: &Mutex<Example>) {
80/// let mut guard = m.lock();
81/// guard.a += 10;
82/// guard.b += 20;
83/// }
84/// ```
85///
86/// [`struct mutex`]: srctree/include/linux/mutex.h
87pub type Mutex<T> = super::Lock<T, MutexBackend>;
88
89/// A kernel `struct mutex` lock backend.
90pub struct MutexBackend;
91
92// SAFETY: The underlying kernel `struct mutex` object ensures mutual exclusion.
93unsafe impl super::Backend for MutexBackend {
94 type State = bindings::mutex;
95 type GuardState = ();
96
97 unsafe fn init(
98 ptr: *mut Self::State,
99 name: *const crate::ffi::c_char,
100 key: *mut bindings::lock_class_key,
101 ) {
102 // SAFETY: The safety requirements ensure that `ptr` is valid for writes, and `name` and
103 // `key` are valid for read indefinitely.
104 unsafe { bindings::__mutex_init(ptr, name, key) }
105 }
106
107 unsafe fn lock(ptr: *mut Self::State) -> Self::GuardState {
108 // SAFETY: The safety requirements of this function ensure that `ptr` points to valid
109 // memory, and that it has been initialised before.
110 unsafe { bindings::mutex_lock(ptr) };
111 }
112
113 unsafe fn unlock(ptr: *mut Self::State, _guard_state: &Self::GuardState) {
114 // SAFETY: The safety requirements of this function ensure that `ptr` is valid and that the
115 // caller is the owner of the mutex.
116 unsafe { bindings::mutex_unlock(ptr) };
117 }
118
119 unsafe fn try_lock(ptr: *mut Self::State) -> Option<Self::GuardState> {
120 // SAFETY: The `ptr` pointer is guaranteed to be valid and initialized before use.
121 let result = unsafe { bindings::mutex_trylock(ptr) };
122
123 if result != 0 {
124 Some(())
125 } else {
126 None
127 }
128 }
129}
1// SPDX-License-Identifier: GPL-2.0
2
3//! A kernel mutex.
4//!
5//! This module allows Rust code to use the kernel's `struct mutex`.
6
7use crate::bindings;
8
9/// Creates a [`Mutex`] initialiser with the given name and a newly-created lock class.
10///
11/// It uses the name if one is given, otherwise it generates one based on the file name and line
12/// number.
13#[macro_export]
14macro_rules! new_mutex {
15 ($inner:expr $(, $name:literal)? $(,)?) => {
16 $crate::sync::Mutex::new(
17 $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!())
18 };
19}
20
21/// A mutual exclusion primitive.
22///
23/// Exposes the kernel's [`struct mutex`]. When multiple threads attempt to lock the same mutex,
24/// only one at a time is allowed to progress, the others will block (sleep) until the mutex is
25/// unlocked, at which point another thread will be allowed to wake up and make progress.
26///
27/// Since it may block, [`Mutex`] needs to be used with care in atomic contexts.
28///
29/// Instances of [`Mutex`] need a lock class and to be pinned. The recommended way to create such
30/// instances is with the [`pin_init`](crate::pin_init) and [`new_mutex`] macros.
31///
32/// # Examples
33///
34/// The following example shows how to declare, allocate and initialise a struct (`Example`) that
35/// contains an inner struct (`Inner`) that is protected by a mutex.
36///
37/// ```
38/// use kernel::{init::InPlaceInit, init::PinInit, new_mutex, pin_init, sync::Mutex};
39///
40/// struct Inner {
41/// a: u32,
42/// b: u32,
43/// }
44///
45/// #[pin_data]
46/// struct Example {
47/// c: u32,
48/// #[pin]
49/// d: Mutex<Inner>,
50/// }
51///
52/// impl Example {
53/// fn new() -> impl PinInit<Self> {
54/// pin_init!(Self {
55/// c: 10,
56/// d <- new_mutex!(Inner { a: 20, b: 30 }),
57/// })
58/// }
59/// }
60///
61/// // Allocate a boxed `Example`.
62/// let e = Box::pin_init(Example::new())?;
63/// assert_eq!(e.c, 10);
64/// assert_eq!(e.d.lock().a, 20);
65/// assert_eq!(e.d.lock().b, 30);
66/// # Ok::<(), Error>(())
67/// ```
68///
69/// The following example shows how to use interior mutability to modify the contents of a struct
70/// protected by a mutex despite only having a shared reference:
71///
72/// ```
73/// use kernel::sync::Mutex;
74///
75/// struct Example {
76/// a: u32,
77/// b: u32,
78/// }
79///
80/// fn example(m: &Mutex<Example>) {
81/// let mut guard = m.lock();
82/// guard.a += 10;
83/// guard.b += 20;
84/// }
85/// ```
86///
87/// [`struct mutex`]: srctree/include/linux/mutex.h
88pub type Mutex<T> = super::Lock<T, MutexBackend>;
89
90/// A kernel `struct mutex` lock backend.
91pub struct MutexBackend;
92
93// SAFETY: The underlying kernel `struct mutex` object ensures mutual exclusion.
94unsafe impl super::Backend for MutexBackend {
95 type State = bindings::mutex;
96 type GuardState = ();
97
98 unsafe fn init(
99 ptr: *mut Self::State,
100 name: *const core::ffi::c_char,
101 key: *mut bindings::lock_class_key,
102 ) {
103 // SAFETY: The safety requirements ensure that `ptr` is valid for writes, and `name` and
104 // `key` are valid for read indefinitely.
105 unsafe { bindings::__mutex_init(ptr, name, key) }
106 }
107
108 unsafe fn lock(ptr: *mut Self::State) -> Self::GuardState {
109 // SAFETY: The safety requirements of this function ensure that `ptr` points to valid
110 // memory, and that it has been initialised before.
111 unsafe { bindings::mutex_lock(ptr) };
112 }
113
114 unsafe fn unlock(ptr: *mut Self::State, _guard_state: &Self::GuardState) {
115 // SAFETY: The safety requirements of this function ensure that `ptr` is valid and that the
116 // caller is the owner of the mutex.
117 unsafe { bindings::mutex_unlock(ptr) };
118 }
119}