| Message ID | 20240618234025.15036-9-dakr@redhat.com (mailing list archive) |
|---|---|
| State | Handled Elsewhere |
| Delegated to: | Bjorn Helgaas |
| Headers | show |
| Series | Device / Driver and PCI Rust abstractions | expand |
On Wed, Jun 19, 2024 at 01:39:54AM +0200, Danilo Krummrich wrote: > Add a Rust abstraction for the kernel's devres (device resource > management) implementation. Ah, here's the devm stuff. Why not put it right after the "revokable" stuff? And why have revokable at all? Why not just put it all here in devres? Who's going to use the generic type? Especially as it uses rcu when devres today does NOT use rcu, so you are might get some "interesting" issues with the interaction of the two. > The Devres type acts as a container to manage the lifetime and > accessibility of device bound resources. Therefore it registers a > devres callback and revokes access to the resource on invocation. Is this last sentence correct? Revokes on invocation? > Users of the Devres abstraction can simply free the corresponding > resources in their Drop implementation, which is invoked when either the > Devres instance goes out of scope or the devres callback leads to the > resource being revoked, which implies a call to drop_in_place(). That's not how a normal driver will use it, right? It's when the remove() callback comes into the driver. That might be well before Drop() happens, as there might be other things keeping that memory around (again, think of /dev/ node accesses.) > --- /dev/null > +++ b/rust/kernel/devres.rs > @@ -0,0 +1,168 @@ > +// SPDX-License-Identifier: GPL-2.0 One note for all of these new files, no copyright notices? I'm all for that, but I know a LOT of lawyers by people who work for companies that have been working on this code do NOT want to see files without copyright lines. So please go check. Otherwise you might get a "stern talking to" in the future when someone notices what you all did... > + > +//! 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::ffi::c_void; > +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 > +/// > +/// ``` > +/// # use kernel::{bindings, c_str, device::Device, devres::Devres, io::Io}; > +/// # use core::ops::Deref; > +/// > +/// // See also [`pci::Bar`] for a real example. > +/// struct IoMem<const SIZE: usize>(Io<SIZE>); > +/// > +/// impl<const SIZE: usize> IoMem<SIZE> { > +/// fn new(paddr: usize) -> Result<Self>{ > +/// > +/// // SAFETY: assert safety for this example > +/// let addr = unsafe { bindings::ioremap(paddr as _, SIZE.try_into().unwrap()) }; > +/// if addr.is_null() { > +/// return Err(ENOMEM); > +/// } > +/// > +/// // SAFETY: `addr` is guaranteed to be the start of a valid I/O mapped memory region of > +/// // size `SIZE`. > +/// let io = unsafe { Io::new(addr as _, SIZE)? }; > +/// > +/// Ok(IoMem(io)) > +/// } > +/// } > +/// > +/// impl<const SIZE: usize> Drop for IoMem<SIZE> { > +/// fn drop(&mut self) { > +/// // SAFETY: Safe as by the invariant of `Io`. > +/// unsafe { bindings::iounmap(self.0.base_addr() as _); }; > +/// } > +/// } > +/// > +/// impl<const SIZE: usize> Deref for IoMem<SIZE> { > +/// type Target = Io<SIZE>; > +/// > +/// fn deref(&self) -> &Self::Target { > +/// &self.0 > +/// } > +/// } > +/// > +/// # // SAFETY: *NOT* safe, just for the example to get an `ARef<Device>` instance > +/// # let dev = unsafe { Device::from_raw(core::ptr::null_mut()) }; > +/// > +/// let iomem = IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD).unwrap(); > +/// let devres = Devres::new(&dev, iomem, GFP_KERNEL).unwrap(); > +/// > +/// let res = devres.try_access().ok_or(ENXIO).unwrap(); > +/// res.writel(0x42, 0x0); > +/// ``` > +/// > +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(); > + 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) > + } > + > + unsafe extern "C" fn devres_callback(ptr: *mut 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()`. > + self.revoke(); > + } > +} Again, I don't think this can happen at "drop", it needs to happen earlier sometimes. Or maybe not, I can't tell when exactly is Drop called, where would I find that? thanks, greg k-h
diff --git a/rust/helpers.c b/rust/helpers.c index 824b7c0b98dc..269f97698588 100644 --- a/rust/helpers.c +++ b/rust/helpers.c @@ -287,6 +287,12 @@ void rust_helper_writeq_relaxed(u64 value, volatile void __iomem *addr) EXPORT_SYMBOL_GPL(rust_helper_writeq_relaxed); #endif +int rust_helper_devm_add_action(struct device *dev, void (*action)(void *), void *data) +{ + return devm_add_action(dev, action, data); +} +EXPORT_SYMBOL_GPL(rust_helper_devm_add_action); + /* * `bindgen` binds the C `size_t` type as the Rust `usize` type, so we can * use it in contexts where Rust expects a `usize` like slice (array) indices. diff --git a/rust/kernel/devres.rs b/rust/kernel/devres.rs new file mode 100644 index 000000000000..ab0a3eb1ea4f --- /dev/null +++ b/rust/kernel/devres.rs @@ -0,0 +1,168 @@ +// 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::ffi::c_void; +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 +/// +/// ``` +/// # use kernel::{bindings, c_str, device::Device, devres::Devres, io::Io}; +/// # use core::ops::Deref; +/// +/// // See also [`pci::Bar`] for a real example. +/// struct IoMem<const SIZE: usize>(Io<SIZE>); +/// +/// impl<const SIZE: usize> IoMem<SIZE> { +/// fn new(paddr: usize) -> Result<Self>{ +/// +/// // SAFETY: assert safety for this example +/// let addr = unsafe { bindings::ioremap(paddr as _, SIZE.try_into().unwrap()) }; +/// if addr.is_null() { +/// return Err(ENOMEM); +/// } +/// +/// // SAFETY: `addr` is guaranteed to be the start of a valid I/O mapped memory region of +/// // size `SIZE`. +/// let io = unsafe { Io::new(addr as _, SIZE)? }; +/// +/// Ok(IoMem(io)) +/// } +/// } +/// +/// impl<const SIZE: usize> Drop for IoMem<SIZE> { +/// fn drop(&mut self) { +/// // SAFETY: Safe as by the invariant of `Io`. +/// unsafe { bindings::iounmap(self.0.base_addr() as _); }; +/// } +/// } +/// +/// impl<const SIZE: usize> Deref for IoMem<SIZE> { +/// type Target = Io<SIZE>; +/// +/// fn deref(&self) -> &Self::Target { +/// &self.0 +/// } +/// } +/// +/// # // SAFETY: *NOT* safe, just for the example to get an `ARef<Device>` instance +/// # let dev = unsafe { Device::from_raw(core::ptr::null_mut()) }; +/// +/// let iomem = IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD).unwrap(); +/// let devres = Devres::new(&dev, iomem, GFP_KERNEL).unwrap(); +/// +/// let res = devres.try_access().ok_or(ENXIO).unwrap(); +/// res.writel(0x42, 0x0); +/// ``` +/// +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(); + 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) + } + + unsafe extern "C" fn devres_callback(ptr: *mut 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()`. + self.revoke(); + } +} diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index f4dd11014a65..ef9426e32c18 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -31,6 +31,7 @@ mod build_assert; pub mod device; pub mod device_id; +pub mod devres; pub mod driver; pub mod error; #[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]
Add a Rust abstraction for the kernel's devres (device resource management) implementation. The Devres type acts as a container to manage the lifetime and accessibility of device bound resources. Therefore it registers a devres callback and revokes access to the resource on invocation. Users of the Devres abstraction can simply free the corresponding resources in their Drop implementation, which is invoked when either the Devres instance goes out of scope or the devres callback leads to the resource being revoked, which implies a call to drop_in_place(). Signed-off-by: Danilo Krummrich <dakr@redhat.com> --- rust/helpers.c | 6 ++ rust/kernel/devres.rs | 168 ++++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 3 files changed, 175 insertions(+) create mode 100644 rust/kernel/devres.rs