1// SPDX-License-Identifier: GPL-2.0
  2
  3//! A kernel spinlock.
  4//!
  5//! This module allows Rust code to use the kernel's `spinlock_t`.
  6
  7use crate::bindings;
  8
  9/// Creates a [`SpinLock`] 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_spinlock {
 15    ($inner:expr $(, $name:literal)? $(,)?) => {
 16        $crate::sync::SpinLock::new(
 17            $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!())
 18    };
 19}
 20
 21/// A spinlock.
 22///
 23/// Exposes the kernel's [`spinlock_t`]. When multiple CPUs attempt to lock the same spinlock, only
 24/// one at a time is allowed to progress, the others will block (spinning) until the spinlock is
 25/// unlocked, at which point another CPU will be allowed to make progress.
 26///
 27/// Instances of [`SpinLock`] need a lock class and to be pinned. The recommended way to create such
 28/// instances is with the [`pin_init`](crate::pin_init) and [`new_spinlock`] macros.
 29///
 30/// # Examples
 31///
 32/// The following example shows how to declare, allocate and initialise a struct (`Example`) that
 33/// contains an inner struct (`Inner`) that is protected by a spinlock.
 34///
 35/// ```
 36/// use kernel::{init::InPlaceInit, init::PinInit, new_spinlock, pin_init, sync::SpinLock};
 37///
 38/// struct Inner {
 39///     a: u32,
 40///     b: u32,
 41/// }
 42///
 43/// #[pin_data]
 44/// struct Example {
 45///     c: u32,
 46///     #[pin]
 47///     d: SpinLock<Inner>,
 48/// }
 49///
 50/// impl Example {
 51///     fn new() -> impl PinInit<Self> {
 52///         pin_init!(Self {
 53///             c: 10,
 54///             d <- new_spinlock!(Inner { a: 20, b: 30 }),
 55///         })
 56///     }
 57/// }
 58///
 59/// // Allocate a boxed `Example`.
 60/// let e = Box::pin_init(Example::new())?;
 61/// assert_eq!(e.c, 10);
 62/// assert_eq!(e.d.lock().a, 20);
 63/// assert_eq!(e.d.lock().b, 30);
 64/// # Ok::<(), Error>(())
 65/// ```
 66///
 67/// The following example shows how to use interior mutability to modify the contents of a struct
 68/// protected by a spinlock despite only having a shared reference:
 69///
 70/// ```
 71/// use kernel::sync::SpinLock;
 72///
 73/// struct Example {
 74///     a: u32,
 75///     b: u32,
 76/// }
 77///
 78/// fn example(m: &SpinLock<Example>) {
 79///     let mut guard = m.lock();
 80///     guard.a += 10;
 81///     guard.b += 20;
 82/// }
 83/// ```
 84///
 85/// [`spinlock_t`]: srctree/include/linux/spinlock.h
 86pub type SpinLock<T> = super::Lock<T, SpinLockBackend>;
 87
 88/// A kernel `spinlock_t` lock backend.
 89pub struct SpinLockBackend;
 90
 91// SAFETY: The underlying kernel `spinlock_t` object ensures mutual exclusion. `relock` uses the
 92// default implementation that always calls the same locking method.
 93unsafe impl super::Backend for SpinLockBackend {
 94    type State = bindings::spinlock_t;
 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` and
103        // `key` are valid for read indefinitely.
104        unsafe { bindings::__spin_lock_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::spin_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::spin_unlock(ptr) }
117    }
118}