projects/linux·blob v7.0-rc3 · refs

340 lines · 10.7 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! Devres abstraction
4//!
5//! [`Devres`] represents an abstraction for the kernel devres (device resource management)
6//! implementation.
7
8use crate::{
9 alloc::Flags,
10 bindings,
11 device::{
12 Bound,
13 Device, //
14 },
15 error::to_result,
16 prelude::*,
17 revocable::{
18 Revocable,
19 RevocableGuard, //
20 },
21 sync::{
22 aref::ARef,
23 rcu,
24 Arc, //
25 },
26 types::ForeignOwnable,
27};
28
29/// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to
30/// manage their lifetime.
31///
32/// [`Device`] bound resources should be freed when either the resource goes out of scope or the
33/// [`Device`] is unbound respectively, depending on what happens first. In any case, it is always
34/// guaranteed that revoking the device resource is completed before the corresponding [`Device`]
35/// is unbound.
36///
37/// To achieve that [`Devres`] registers a devres callback on creation, which is called once the
38/// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]).
39///
40/// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource
41/// anymore.
42///
43/// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s
44/// [`Drop`] implementation.
45///
46/// # Examples
47///
48/// ```no_run
49/// use kernel::{
50/// bindings,
51/// device::{
52/// Bound,
53/// Device,
54/// },
55/// devres::Devres,
56/// io::{
57/// Io,
58/// IoKnownSize,
59/// Mmio,
60/// MmioRaw,
61/// PhysAddr, //
62/// },
63/// prelude::*,
64/// };
65/// use core::ops::Deref;
66///
67/// // See also [`pci::Bar`] for a real example.
68/// struct IoMem<const SIZE: usize>(MmioRaw<SIZE>);
69///
70/// impl<const SIZE: usize> IoMem<SIZE> {
71/// /// # Safety
72/// ///
73/// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs
74/// /// virtual address space.
75/// unsafe fn new(paddr: usize) -> Result<Self>{
76/// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is
77/// // valid for `ioremap`.
78/// let addr = unsafe { bindings::ioremap(paddr as PhysAddr, SIZE) };
79/// if addr.is_null() {
80/// return Err(ENOMEM);
81/// }
82///
83/// Ok(IoMem(MmioRaw::new(addr as usize, SIZE)?))
84/// }
85/// }
86///
87/// impl<const SIZE: usize> Drop for IoMem<SIZE> {
88/// fn drop(&mut self) {
89/// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`.
90/// unsafe { bindings::iounmap(self.0.addr() as *mut c_void); };
91/// }
92/// }
93///
94/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
95/// type Target = Mmio<SIZE>;
96///
97/// fn deref(&self) -> &Self::Target {
98/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
99/// unsafe { Mmio::from_raw(&self.0) }
100/// }
101/// }
102/// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> {
103/// // SAFETY: Invalid usage for example purposes.
104/// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };
105/// let devres = Devres::new(dev, iomem)?;
106///
107/// let res = devres.try_access().ok_or(ENXIO)?;
108/// res.write8(0x42, 0x0);
109/// # Ok(())
110/// # }
111/// ```
112pub struct Devres<T: Send> {
113 dev: ARef<Device>,
114 /// Pointer to [`Self::devres_callback`].
115 ///
116 /// Has to be stored, since Rust does not guarantee to always return the same address for a
117 /// function. However, the C API uses the address as a key.
118 callback: unsafe extern "C" fn(*mut c_void),
119 data: Arc<Revocable<T>>,
120}
121
122impl<T: Send> Devres<T> {
123 /// Creates a new [`Devres`] instance of the given `data`.
124 ///
125 /// The `data` encapsulated within the returned `Devres` instance' `data` will be
126 /// (revoked)[`Revocable`] once the device is detached.
127 pub fn new<E>(dev: &Device<Bound>, data: impl PinInit<T, E>) -> Result<Self>
128 where
129 Error: From<E>,
130 {
131 let callback = Self::devres_callback;
132 let data = Arc::pin_init(Revocable::new(data), GFP_KERNEL)?;
133 let devres_data = data.clone();
134
135 // SAFETY:
136 // - `dev.as_raw()` is a pointer to a valid bound device.
137 // - `data` is guaranteed to be a valid for the duration of the lifetime of `Self`.
138 // - `devm_add_action()` is guaranteed not to call `callback` for the entire lifetime of
139 // `dev`.
140 to_result(unsafe {
141 bindings::devm_add_action(
142 dev.as_raw(),
143 Some(callback),
144 Arc::as_ptr(&data).cast_mut().cast(),
145 )
146 })?;
147
148 // `devm_add_action()` was successful and has consumed the reference count.
149 core::mem::forget(devres_data);
150
151 Ok(Self {
152 dev: dev.into(),
153 callback,
154 data,
155 })
156 }
157
158 fn data(&self) -> &Revocable<T> {
159 &self.data
160 }
161
162 #[allow(clippy::missing_safety_doc)]
163 unsafe extern "C" fn devres_callback(ptr: *mut kernel::ffi::c_void) {
164 // SAFETY: In `Self::new` we've passed a valid pointer of `Revocable<T>` to
165 // `devm_add_action()`, hence `ptr` must be a valid pointer to `Revocable<T>`.
166 let data = unsafe { Arc::from_raw(ptr.cast::<Revocable<T>>()) };
167
168 data.revoke();
169 }
170
171 fn remove_action(&self) -> bool {
172 // SAFETY:
173 // - `self.dev` is a valid `Device`,
174 // - the `action` and `data` pointers are the exact same ones as given to
175 // `devm_add_action()` previously,
176 (unsafe {
177 bindings::devm_remove_action_nowarn(
178 self.dev.as_raw(),
179 Some(self.callback),
180 core::ptr::from_ref(self.data()).cast_mut().cast(),
181 )
182 } == 0)
183 }
184
185 /// Return a reference of the [`Device`] this [`Devres`] instance has been created with.
186 pub fn device(&self) -> &Device {
187 &self.dev
188 }
189
190 /// Obtain `&'a T`, bypassing the [`Revocable`].
191 ///
192 /// This method allows to directly obtain a `&'a T`, bypassing the [`Revocable`], by presenting
193 /// a `&'a Device<Bound>` of the same [`Device`] this [`Devres`] instance has been created with.
194 ///
195 /// # Errors
196 ///
197 /// An error is returned if `dev` does not match the same [`Device`] this [`Devres`] instance
198 /// has been created with.
199 ///
200 /// # Examples
201 ///
202 /// ```no_run
203 /// #![cfg(CONFIG_PCI)]
204 /// use kernel::{
205 /// device::Core,
206 /// devres::Devres,
207 /// io::{
208 /// Io,
209 /// IoKnownSize, //
210 /// },
211 /// pci, //
212 /// };
213 ///
214 /// fn from_core(dev: &pci::Device<Core>, devres: Devres<pci::Bar<0x4>>) -> Result {
215 /// let bar = devres.access(dev.as_ref())?;
216 ///
217 /// let _ = bar.read32(0x0);
218 ///
219 /// // might_sleep()
220 ///
221 /// bar.write32(0x42, 0x0);
222 ///
223 /// Ok(())
224 /// }
225 /// ```
226 pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T> {
227 if self.dev.as_raw() != dev.as_raw() {
228 return Err(EINVAL);
229 }
230
231 // SAFETY: `dev` being the same device as the device this `Devres` has been created for
232 // proves that `self.data` hasn't been revoked and is guaranteed to not be revoked as long
233 // as `dev` lives; `dev` lives at least as long as `self`.
234 Ok(unsafe { self.data().access() })
235 }
236
237 /// [`Devres`] accessor for [`Revocable::try_access`].
238 pub fn try_access(&self) -> Option<RevocableGuard<'_, T>> {
239 self.data().try_access()
240 }
241
242 /// [`Devres`] accessor for [`Revocable::try_access_with`].
243 pub fn try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R> {
244 self.data().try_access_with(f)
245 }
246
247 /// [`Devres`] accessor for [`Revocable::try_access_with_guard`].
248 pub fn try_access_with_guard<'a>(&'a self, guard: &'a rcu::Guard) -> Option<&'a T> {
249 self.data().try_access_with_guard(guard)
250 }
251}
252
253// SAFETY: `Devres` can be send to any task, if `T: Send`.
254unsafe impl<T: Send> Send for Devres<T> {}
255
256// SAFETY: `Devres` can be shared with any task, if `T: Sync`.
257unsafe impl<T: Send + Sync> Sync for Devres<T> {}
258
259impl<T: Send> Drop for Devres<T> {
260 fn drop(&mut self) {
261 // SAFETY: When `drop` runs, it is guaranteed that nobody is accessing the revocable data
262 // anymore, hence it is safe not to wait for the grace period to finish.
263 if unsafe { self.data().revoke_nosync() } {
264 // We revoked `self.data` before the devres action did, hence try to remove it.
265 if self.remove_action() {
266 // SAFETY: In `Self::new` we have taken an additional reference count of `self.data`
267 // for `devm_add_action()`. Since `remove_action()` was successful, we have to drop
268 // this additional reference count.
269 drop(unsafe { Arc::from_raw(Arc::as_ptr(&self.data)) });
270 }
271 }
272 }
273}
274
275/// Consume `data` and [`Drop::drop`] `data` once `dev` is unbound.
276fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result
277where
278 P: ForeignOwnable + Send + 'static,
279{
280 let ptr = data.into_foreign();
281
282 #[allow(clippy::missing_safety_doc)]
283 unsafe extern "C" fn callback<P: ForeignOwnable>(ptr: *mut kernel::ffi::c_void) {
284 // SAFETY: `ptr` is the pointer to the `ForeignOwnable` leaked above and hence valid.
285 drop(unsafe { P::from_foreign(ptr.cast()) });
286 }
287
288 // SAFETY:
289 // - `dev.as_raw()` is a pointer to a valid and bound device.
290 // - `ptr` is a valid pointer the `ForeignOwnable` devres takes ownership of.
291 to_result(unsafe {
292 // `devm_add_action_or_reset()` also calls `callback` on failure, such that the
293 // `ForeignOwnable` is released eventually.
294 bindings::devm_add_action_or_reset(dev.as_raw(), Some(callback::<P>), ptr.cast())
295 })
296}
297
298/// Encapsulate `data` in a [`KBox`] and [`Drop::drop`] `data` once `dev` is unbound.
299///
300/// # Examples
301///
302/// ```no_run
303/// use kernel::{
304/// device::{
305/// Bound,
306/// Device, //
307/// },
308/// devres, //
309/// };
310///
311/// /// Registration of e.g. a class device, IRQ, etc.
312/// struct Registration;
313///
314/// impl Registration {
315/// fn new() -> Self {
316/// // register
317///
318/// Self
319/// }
320/// }
321///
322/// impl Drop for Registration {
323/// fn drop(&mut self) {
324/// // unregister
325/// }
326/// }
327///
328/// fn from_bound_context(dev: &Device<Bound>) -> Result {
329/// devres::register(dev, Registration::new(), GFP_KERNEL)
330/// }
331/// ```
332pub fn register<T, E>(dev: &Device<Bound>, data: impl PinInit<T, E>, flags: Flags) -> Result
333where
334 T: Send + 'static,
335 Error: From<E>,
336{
337 let data = KBox::pin_init(data, flags)?;
338
339 register_foreign(dev, data)
340}