// SPDX-License-Identifier: GPL-2.0 //! A kernel spinlock.//!//! This module allows Rust code to use the kernel's `spinlock_t`. /// Creates a [`SpinLock`] initialiser with the given name and a newly-created lock class.////// It uses the name if one is given, otherwise it generates one based on the file name and line/// number.#[macro_export]macro_rules! new_spinlock {    ($inner:expr $(, $name:literal)? $(,)?) => {        $crate::sync::SpinLock::new(            $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!())    };}pub use new_spinlock; /// A spinlock.////// Exposes the kernel's [`spinlock_t`]. When multiple CPUs attempt to lock the same spinlock, only/// one at a time is allowed to progress, the others will block (spinning) until the spinlock is/// unlocked, at which point another CPU will be allowed to make progress.////// Instances of [`SpinLock`] need a lock class and to be pinned. The recommended way to create such/// instances is with the [`pin_init`](pin_init::pin_init) and [`new_spinlock`] macros.////// # Examples////// The following example shows how to declare, allocate and initialise a struct (`Example`) that/// contains an inner struct (`Inner`) that is protected by a spinlock.////// ```/// use kernel::sync::{new_spinlock, SpinLock};////// struct Inner {///     a: u32,///     b: u32,/// }////// #[pin_data]/// struct Example {///     c: u32,///     #[pin]///     d: SpinLock<Inner>,/// }////// impl Example {///     fn new() -> impl PinInit<Self> {///         pin_init!(Self {///             c: 10,///             d <- new_spinlock!(Inner { a: 20, b: 30 }),///         })///     }/// }////// // Allocate a boxed `Example`./// let e = KBox::pin_init(Example::new(), GFP_KERNEL)?;/// assert_eq!(e.c, 10);/// assert_eq!(e.d.lock().a, 20);/// assert_eq!(e.d.lock().b, 30);/// # Ok::<(), Error>(())/// ```////// The following example shows how to use interior mutability to modify the contents of a struct/// protected by a spinlock despite only having a shared reference:////// ```/// use kernel::sync::SpinLock;////// struct Example {///     a: u32,///     b: u32,/// }////// fn example(m: &SpinLock<Example>) {///     let mut guard = m.lock();///     guard.a += 10;///     guard.b += 20;/// }/// ```////// [`spinlock_t`]: srctree/include/linux/spinlock.hpub type SpinLock<T> = super::Lock<T, SpinLockBackend>; /// A kernel `spinlock_t` lock backend.pub struct SpinLockBackend; /// A [`Guard`] acquired from locking a [`SpinLock`].////// This is simply a type alias for a [`Guard`] returned from locking a [`SpinLock`]. It will unlock/// the [`SpinLock`] upon being dropped.////// [`Guard`]: super::Guardpub type SpinLockGuard<'a, T> = super::Guard<'a, T, SpinLockBackend>; // SAFETY: The underlying kernel `spinlock_t` object ensures mutual exclusion. `relock` uses the// default implementation that always calls the same locking method.unsafe impl super::Backend for SpinLockBackend {    type State = bindings::spinlock_t;    type GuardState = ();     #[inline]    unsafe fn init(        ptr: *mut Self::State,        name: *const crate::ffi::c_char,        key: *mut bindings::lock_class_key,    ) {        // SAFETY: The safety requirements ensure that `ptr` is valid for writes, and `name` and        // `key` are valid for read indefinitely.        unsafe { bindings::__spin_lock_init(ptr, name, key) }    }     #[inline]    unsafe fn lock(ptr: *mut Self::State) -> Self::GuardState {        // SAFETY: The safety requirements of this function ensure that `ptr` points to valid        // memory, and that it has been initialised before.        unsafe { bindings::spin_lock(ptr) }    }     #[inline]    unsafe fn unlock(ptr: *mut Self::State, _guard_state: &Self::GuardState) {        // SAFETY: The safety requirements of this function ensure that `ptr` is valid and that the        // caller is the owner of the spinlock.        unsafe { bindings::spin_unlock(ptr) }    }     #[inline]    unsafe fn try_lock(ptr: *mut Self::State) -> Option<Self::GuardState> {        // SAFETY: The `ptr` pointer is guaranteed to be valid and initialized before use.        let result = unsafe { bindings::spin_trylock(ptr) };         if result != 0 {            Some(())        } else {            None        }    }     #[inline]    unsafe fn assert_is_held(ptr: *mut Self::State) {        // SAFETY: The `ptr` pointer is guaranteed to be valid and initialized before use.        unsafe { bindings::spin_assert_is_held(ptr) }    }}