119 lines · rust
1// SPDX-License-Identifier: GPL-2.02 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 line10/// 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 is24/// 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 such29/// instances is with the [`pin_init`](crate::pin_init) and [`new_mutex`] macros.30///31/// # Examples32///33/// The following example shows how to declare, allocate and initialise a struct (`Example`) that34/// 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 = Box::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 struct69/// 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.h87pub 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 core::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` and103 // `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 valid109 // 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 the115 // caller is the owner of the mutex.116 unsafe { bindings::mutex_unlock(ptr) };117 }118}119