1 // SPDX-License-Identifier: GPL-2.0 2 3 //! A wrapper for data protected by a lock that does not wrap it. 4 5 use super::{lock::Backend, lock::Lock}; 6 use crate::build_assert; 7 use core::{cell::UnsafeCell, mem::size_of, ptr}; 8 9 /// Allows access to some data to be serialised by a lock that does not wrap it. 10 /// 11 /// In most cases, data protected by a lock is wrapped by the appropriate lock type, e.g., 12 /// [`super::Mutex`] or [`super::SpinLock`]. [`LockedBy`] is meant for cases when this is not 13 /// possible. For example, if a container has a lock and some data in the contained elements needs 14 /// to be protected by the same lock. 15 /// 16 /// [`LockedBy`] wraps the data in lieu of another locking primitive, and only allows access to it 17 /// when the caller shows evidence that the 'external' lock is locked. It panics if the evidence 18 /// refers to the wrong instance of the lock. 19 /// 20 /// # Examples 21 /// 22 /// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an 23 /// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in 24 /// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at 25 /// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also 26 /// locked; we enforce at run time that the right `InnerDirectory` is locked. 27 /// 28 /// ``` 29 /// use kernel::sync::{LockedBy, Mutex}; 30 /// 31 /// struct InnerFile { 32 /// bytes_used: u64, 33 /// } 34 /// 35 /// struct File { 36 /// _ino: u32, 37 /// inner: LockedBy<InnerFile, InnerDirectory>, 38 /// } 39 /// 40 /// struct InnerDirectory { 41 /// /// The sum of the bytes used by all files. 42 /// bytes_used: u64, 43 /// _files: Vec<File>, 44 /// } 45 /// 46 /// struct Directory { 47 /// _ino: u32, 48 /// inner: Mutex<InnerDirectory>, 49 /// } 50 /// 51 /// /// Prints `bytes_used` from both the directory and file. 52 /// fn print_bytes_used(dir: &Directory, file: &File) { 53 /// let guard = dir.inner.lock(); 54 /// let inner_file = file.inner.access(&guard); 55 /// pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used); 56 /// } 57 /// 58 /// /// Increments `bytes_used` for both the directory and file. 59 /// fn inc_bytes_used(dir: &Directory, file: &File) { 60 /// let mut guard = dir.inner.lock(); 61 /// guard.bytes_used += 10; 62 /// 63 /// let file_inner = file.inner.access_mut(&mut guard); 64 /// file_inner.bytes_used += 10; 65 /// } 66 /// 67 /// /// Creates a new file. 68 /// fn new_file(ino: u32, dir: &Directory) -> File { 69 /// File { 70 /// _ino: ino, 71 /// inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }), 72 /// } 73 /// } 74 /// ``` 75 pub struct LockedBy<T: ?Sized, U: ?Sized> { 76 owner: *const U, 77 data: UnsafeCell<T>, 78 } 79 80 // SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can. 81 unsafe impl<T: ?Sized + Send, U: ?Sized> Send for LockedBy<T, U> {} 82 83 // SAFETY: If `T` is not `Sync`, then parallel shared access to this `LockedBy` allows you to use 84 // `access_mut` to hand out `&mut T` on one thread at the time. The requirement that `T: Send` is 85 // sufficient to allow that. 86 // 87 // If `T` is `Sync`, then the `access` method also becomes available, which allows you to obtain 88 // several `&T` from several threads at once. However, this is okay as `T` is `Sync`. 89 unsafe impl<T: ?Sized + Send, U: ?Sized> Sync for LockedBy<T, U> {} 90 91 impl<T, U> LockedBy<T, U> { 92 /// Constructs a new instance of [`LockedBy`]. 93 /// 94 /// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure 95 /// that the right owner is being used to access the protected data. If the owner is freed, the 96 /// data becomes inaccessible; if another instance of the owner is allocated *on the same 97 /// memory location*, the data becomes accessible again: none of this affects memory safety 98 /// because in any case at most one thread (or CPU) can access the protected data at a time. 99 pub fn new<B: Backend>(owner: &Lock<U, B>, data: T) -> Self { 100 build_assert!( 101 size_of::<Lock<U, B>>() > 0, 102 "The lock type cannot be a ZST because it may be impossible to distinguish instances" 103 ); 104 Self { 105 owner: owner.data.get(), 106 data: UnsafeCell::new(data), 107 } 108 } 109 } 110 111 impl<T: ?Sized, U> LockedBy<T, U> { 112 /// Returns a reference to the protected data when the caller provides evidence (via a 113 /// reference) that the owner is locked. 114 /// 115 /// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&U` that matches 116 /// the data protected by the lock without actually holding it. 117 /// 118 /// # Panics 119 /// 120 /// Panics if `owner` is different from the data protected by the lock used in 121 /// [`new`](LockedBy::new). 122 pub fn access<'a>(&'a self, owner: &'a U) -> &'a T 123 where 124 T: Sync, 125 { 126 build_assert!( 127 size_of::<U>() > 0, 128 "`U` cannot be a ZST because `owner` wouldn't be unique" 129 ); 130 if !ptr::eq(owner, self.owner) { 131 panic!("mismatched owners"); 132 } 133 134 // SAFETY: `owner` is evidence that there are only shared references to the owner for the 135 // duration of 'a, so it's not possible to use `Self::access_mut` to obtain a mutable 136 // reference to the inner value that aliases with this shared reference. The type is `Sync` 137 // so there are no other requirements. 138 unsafe { &*self.data.get() } 139 } 140 141 /// Returns a mutable reference to the protected data when the caller provides evidence (via a 142 /// mutable owner) that the owner is locked mutably. 143 /// 144 /// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&mut U` that 145 /// matches the data protected by the lock without actually holding it. 146 /// 147 /// Showing a mutable reference to the owner is sufficient because we know no other references 148 /// can exist to it. 149 /// 150 /// # Panics 151 /// 152 /// Panics if `owner` is different from the data protected by the lock used in 153 /// [`new`](LockedBy::new). 154 pub fn access_mut<'a>(&'a self, owner: &'a mut U) -> &'a mut T { 155 build_assert!( 156 size_of::<U>() > 0, 157 "`U` cannot be a ZST because `owner` wouldn't be unique" 158 ); 159 if !ptr::eq(owner, self.owner) { 160 panic!("mismatched owners"); 161 } 162 163 // SAFETY: `owner` is evidence that there is only one reference to the owner. 164 unsafe { &mut *self.data.get() } 165 } 166 } 167