1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
// SPDX-License-Identifier: GPL-2.0
//! Devres abstraction
//!
//! [`Devres`] represents an abstraction for the kernel devres (device resource management)
//! implementation.
use crate::{
alloc::Flags,
bindings,
device::Device,
error::{Error, Result},
prelude::*,
revocable::Revocable,
sync::Arc,
};
use core::ops::Deref;
#[pin_data]
struct DevresInner<T> {
#[pin]
data: Revocable<T>,
}
/// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to
/// manage their lifetime.
///
/// [`Device`] bound resources should be freed when either the resource goes out of scope or the
/// [`Device`] is unbound respectively, depending on what happens first.
///
/// To achieve that [`Devres`] registers a devres callback on creation, which is called once the
/// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]).
///
/// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource
/// anymore.
///
/// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s
/// [`Drop`] implementation.
///
/// # Example
///
/// ```no_run
/// # use kernel::{bindings, c_str, device::Device, devres::Devres, io::{Io, IoRaw}};
/// # use core::ops::Deref;
///
/// // See also [`pci::Bar`] for a real example.
/// struct IoMem<const SIZE: usize>(IoRaw<SIZE>);
///
/// impl<const SIZE: usize> IoMem<SIZE> {
/// /// # Safety
/// ///
/// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs
/// /// virtual address space.
/// unsafe fn new(paddr: usize) -> Result<Self>{
/// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is
/// // valid for `ioremap`.
/// let addr = unsafe { bindings::ioremap(paddr as _, SIZE as _) };
/// if addr.is_null() {
/// return Err(ENOMEM);
/// }
///
/// Ok(IoMem(IoRaw::new(addr as _, SIZE)?))
/// }
/// }
///
/// impl<const SIZE: usize> Drop for IoMem<SIZE> {
/// fn drop(&mut self) {
/// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`.
/// unsafe { bindings::iounmap(self.0.addr() as _); };
/// }
/// }
///
/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
/// type Target = Io<SIZE>;
///
/// fn deref(&self) -> &Self::Target {
/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
/// unsafe { Io::from_raw(&self.0) }
/// }
/// }
/// # fn no_run() -> Result<(), Error> {
/// # // SAFETY: Invalid usage; just for the example to get an `ARef<Device>` instance.
/// # let dev = unsafe { Device::get_device(core::ptr::null_mut()) };
///
/// // SAFETY: Invalid usage for example purposes.
/// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };
/// let devres = Devres::new(&dev, iomem, GFP_KERNEL)?;
///
/// let res = devres.try_access().ok_or(ENXIO)?;
/// res.writel(0x42, 0x0);
/// # Ok(())
/// # }
/// ```
pub struct Devres<T>(Arc<DevresInner<T>>);
impl<T> DevresInner<T> {
fn new(dev: &Device, data: T, flags: Flags) -> Result<Arc<DevresInner<T>>> {
let inner = Arc::pin_init(
pin_init!( DevresInner {
data <- Revocable::new(data),
}),
flags,
)?;
// Convert `Arc<DevresInner>` into a raw pointer and make devres own this reference until
// `Self::devres_callback` is called.
let data = inner.clone().into_raw();
// SAFETY: `devm_add_action` guarantees to call `Self::devres_callback` once `dev` is
// detached.
let ret = unsafe {
bindings::devm_add_action(dev.as_raw(), Some(Self::devres_callback), data as _)
};
if ret != 0 {
// SAFETY: We just created another reference to `inner` in order to pass it to
// `bindings::devm_add_action`. If `bindings::devm_add_action` fails, we have to drop
// this reference accordingly.
let _ = unsafe { Arc::from_raw(data) };
return Err(Error::from_errno(ret));
}
Ok(inner)
}
#[allow(clippy::missing_safety_doc)]
unsafe extern "C" fn devres_callback(ptr: *mut kernel::ffi::c_void) {
let ptr = ptr as *mut DevresInner<T>;
// Devres owned this memory; now that we received the callback, drop the `Arc` and hence the
// reference.
// SAFETY: Safe, since we leaked an `Arc` reference to devm_add_action() in
// `DevresInner::new`.
let inner = unsafe { Arc::from_raw(ptr) };
inner.data.revoke();
}
}
impl<T> Devres<T> {
/// Creates a new [`Devres`] instance of the given `data`. The `data` encapsulated within the
/// returned `Devres` instance' `data` will be revoked once the device is detached.
pub fn new(dev: &Device, data: T, flags: Flags) -> Result<Self> {
let inner = DevresInner::new(dev, data, flags)?;
Ok(Devres(inner))
}
/// Same as [`Devres::new`], but does not return a `Devres` instance. Instead the given `data`
/// is owned by devres and will be revoked / dropped, once the device is detached.
pub fn new_foreign_owned(dev: &Device, data: T, flags: Flags) -> Result {
let _ = DevresInner::new(dev, data, flags)?;
Ok(())
}
}
impl<T> Deref for Devres<T> {
type Target = Revocable<T>;
fn deref(&self) -> &Self::Target {
&self.0.data
}
}
impl<T> Drop for Devres<T> {
fn drop(&mut self) {
// Revoke the data, such that it gets dropped already and the actual resource is freed.
//
// `DevresInner` has to stay alive until the devres callback has been called. This is
// necessary since we don't know when `Devres` is dropped and calling
// `devm_remove_action()` instead could race with `devres_release_all()`.
//
// SAFETY: When `drop` runs, it's guaranteed that nobody is accessing the revocable data
// anymore, hence it is safe not to wait for the grace period to finish.
unsafe { self.revoke_nosync() };
}
}
|
