Skip to contentSkip to conversation

rust: device: add BoundInternal device context and InternalBoundContext trait

PATCH In review Danilo Krummrich 2 participants 4 messages May 30 – Jun 29

Subsystems (2)
lore
Share & tools
lore

Danilo Krummrich

author maintainer
#0 lore raw

PATCH 1/2 rust: device: add BoundInternal device context and InternalBoundContext trait

Add a new BoundInternal device context type for cases where bus abstractions need access to internal device infrastructure, where CoreInternal would not be justified.

Introduce the InternalBoundContext marker trait, implemented by both CoreInternal and BoundInternal, to allow methods that require internal bus abstraction access to a bound device to be generic over both contexts.

The deref hierarchy now has two branches:
- CoreInternal<'a> => Core<'a> => Bound => Normal
- BoundInternal => Bound => Normal

Update impl_device_context_deref! and impl_device_context_into_aref! macros to emit the BoundInternal => Bound deref and the corresponding ARef conversion.

---
This is needed by both the serdev bus code [1] and the runtime PM series [2].

[1] https://lore.kernel.org/driver-core/[email protected]/
[2] https://lore.kernel.org/driver-core/[email protected]/

---
 rust/kernel/device.rs | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)
rust/kernel/device.rs +41 -2
index 645afc49a27d..354c4045f404 100644
@@ -54,7 +54,8 @@
 /// reference is valid in. For instance, the [`Bound`] context guarantees that the [`Device`] is
 /// bound to a driver for the entire duration of the existence of a [`Device<Bound>`] reference.
 ///
-/// Other [`DeviceContext`] types besides [`Bound`] are [`Normal`], [`Core`] and [`CoreInternal`].
+/// Other [`DeviceContext`] types besides [`Bound`] are [`Normal`], [`Core`], [`CoreInternal`] and
+/// [`BoundInternal`].
 ///
 /// Unless selected otherwise [`Device`] defaults to the [`Normal`] [`DeviceContext`], which by
 /// itself has no additional requirements.
@@ -476,7 +477,8 @@ unsafe impl Sync for Device<Bound> {}
 /// [`DeviceContext`] is a marker trait for types representing the context of a bus specific
 /// [`Device`].
 ///
-/// The specific device context types are: [`CoreInternal`], [`Core`], [`Bound`] and [`Normal`].
+/// The specific device context types are: [`CoreInternal`], [`Core`], [`BoundInternal`], [`Bound`]
+/// and [`Normal`].
 ///
 /// [`DeviceContext`] types are hierarchical, which means that there is a strict hierarchy that
 /// defines which [`DeviceContext`] type can be derived from another. For instance, any
@@ -485,6 +487,11 @@ unsafe impl Sync for Device<Bound> {}
 /// The following enumeration illustrates the dereference hierarchy of [`DeviceContext`] types.
 ///
 /// - [`CoreInternal`] => [`Core`] => [`Bound`] => [`Normal`]
+/// - [`BoundInternal`] => [`Bound`] => [`Normal`]
+///
+/// Both [`CoreInternal`] and [`BoundInternal`] implement the [`InternalBoundContext`] trait,
+/// which provides access to internal bus abstraction methods on [`Device`] that are not available
+/// to drivers.
 ///
 /// Bus devices can automatically implement the dereference hierarchy by using
 /// [`impl_device_context_deref`].
@@ -524,6 +531,18 @@ pub trait DeviceContext: private::Sealed {}
 /// from bus callbacks with bus abstractions, but without making them accessible for drivers.
 pub struct CoreInternal<'a>(PhantomData<&'a ()>);
 
+/// Semantically the same as [`Bound`], but reserved for internal usage of the corresponding bus
+/// abstraction.
+///
+/// The internal bound context is intended to be used in exactly the same way as the [`Bound`]
+/// context, with the difference that this [`DeviceContext`] is internal to the corresponding bus
+/// abstraction.
+///
+/// This context exists for cases where the bus abstraction needs access to internal device
+/// infrastructure (such as [`Device::drvdata_borrow`]), where [`CoreInternal`] would not be
+/// justified.
+pub struct BoundInternal;
+
 /// The [`Bound`] context is the [`DeviceContext`] of a bus specific device when it is guaranteed to
 /// be bound to a driver.
 ///
@@ -546,16 +565,28 @@ mod private {
     pub trait Sealed {}
 
     impl Sealed for super::Bound {}
+    impl Sealed for super::BoundInternal {}
     impl<'a> Sealed for super::Core<'a> {}
     impl<'a> Sealed for super::CoreInternal<'a> {}
     impl Sealed for super::Normal {}
 }
 
 impl DeviceContext for Bound {}
+impl DeviceContext for BoundInternal {}
 impl<'a> DeviceContext for Core<'a> {}
 impl<'a> DeviceContext for CoreInternal<'a> {}
 impl DeviceContext for Normal {}
 
+/// Marker trait for [`DeviceContext`] types that have internal bound-level access.
+///
+/// This trait is implemented by [`CoreInternal`] and [`BoundInternal`], allowing methods that
+/// require internal bus abstraction access to a bound device to be generic over both contexts.
+///
+/// Methods bounded by this trait are available to bus abstractions but not to drivers.
+pub trait InternalBoundContext: DeviceContext {}
+impl<'a> InternalBoundContext for CoreInternal<'a> {}
+impl InternalBoundContext for BoundInternal {}
+
 impl<Ctx: DeviceContext> AsRef<Device<Ctx>> for Device<Ctx> {
     #[inline]
     fn as_ref(&self) -> &Device<Ctx> {
@@ -661,6 +692,13 @@ macro_rules! impl_device_context_deref {
             <'a> $crate::device::Core<'a> => $crate::device::Bound
         });
 
+        // SAFETY: This macro has the exact same safety requirement as
+        // `__impl_device_context_deref!`.
+        ::kernel::__impl_device_context_deref!(unsafe {
+            $device,
+            $crate::device::BoundInternal => $crate::device::Bound
+        });
+
         // SAFETY: This macro has the exact same safety requirement as
         // `__impl_device_context_deref!`.
         ::kernel::__impl_device_context_deref!(unsafe {
@@ -700,6 +738,7 @@ macro_rules! impl_device_context_into_aref {
         ::kernel::__impl_device_context_into_aref!(
             <'a> $crate::device::Core<'a>, $device
         );
+        ::kernel::__impl_device_context_into_aref!($crate::device::BoundInternal, $device);
         ::kernel::__impl_device_context_into_aref!($crate::device::Bound, $device);
     };
 }

base-commit: 016267b521b18529c977c9eca9597a1669c3d73c

Signature · 1 line
2.54.0
author maintainer
#1 lore raw

PATCH 2/2 rust: device: move drvdata_borrow() to InternalBoundContext

Move drvdata_borrow() from impl Device<CoreInternal<'a>> to impl<Ctx: InternalBoundContext> Device<Ctx>, making it available from both CoreInternal and BoundInternal contexts.

Fold drvdata_unchecked() (previously on Device<Bound>) directly into drvdata_borrow(), since it was only called from there and the generic context cannot resolve methods through the deref chain.

---
 rust/kernel/device.rs | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)
rust/kernel/device.rs +2 -16
index 354c4045f404..b538c39982a6 100644
@@ -236,7 +236,9 @@ pub(crate) unsafe fn drvdata_obtain<T>(&self) -> Option<Pin<KBox<T>>> {
         //   in `into_foreign()`.
         Some(unsafe { Pin::<KBox<T>>::from_foreign(ptr.cast()) })
     }
+}
 
+impl<Ctx: InternalBoundContext> Device<Ctx> {
     /// Borrow the driver's private data bound to this [`Device`].
     ///
     /// # Safety
@@ -246,22 +248,6 @@ pub(crate) unsafe fn drvdata_obtain<T>(&self) -> Option<Pin<KBox<T>>> {
     /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
     ///   [`Device::set_drvdata`].
     pub unsafe fn drvdata_borrow<T>(&self) -> Pin<&T> {
-        // SAFETY: `drvdata_unchecked()` has the exact same safety requirements as the ones
-        // required by this method.
-        unsafe { self.drvdata_unchecked() }
-    }
-}
-
-impl Device<Bound> {
-    /// Borrow the driver's private data bound to this [`Device`].
-    ///
-    /// # Safety
-    ///
-    /// - Must only be called after a preceding call to [`Device::set_drvdata`] and before
-    ///   the device is fully unbound.
-    /// - The type `T` must match the type of the `ForeignOwnable` previously stored by
-    ///   [`Device::set_drvdata`].
-    unsafe fn drvdata_unchecked<T>(&self) -> Pin<&T> {
         // SAFETY: By the type invariants, `self.as_raw()` is a valid pointer to a `struct device`.
         let ptr = unsafe { bindings::dev_get_drvdata(self.as_raw()) };
 
Signature · 1 line
2.54.0
Reviewed-by on v1 2/2
#2 lore raw

Re: [PATCH 2/2] rust: device: move drvdata_borrow() to InternalBoundContext

Quoted 4 lines · Danilo Krummrich

Move drvdata_borrow() from impl Device<CoreInternal<'a>> to impl<Ctx: InternalBoundContext> Device<Ctx>, making it available from both CoreInternal and BoundInternal contexts.

Quoted 9 lines

Fold drvdata_unchecked() (previously on Device<Bound>) directly into drvdata_borrow(), since it was only called from there and the generic context cannot resolve methods through the deref chain.

---
 rust/kernel/device.rs | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)

Thanks
- Markus Probst

Reviewed-by on v1 1/2
#3 lore raw
In reply to Danilo Krummrich
Quoted 18 lines · Danilo Krummrich

Add a new BoundInternal device context type for cases where bus abstractions need access to internal device infrastructure, where CoreInternal would not be justified.

Introduce the InternalBoundContext marker trait, implemented by both CoreInternal and BoundInternal, to allow methods that require internal bus abstraction access to a bound device to be generic over both contexts.

The deref hierarchy now has two branches:
- CoreInternal<'a> => Core<'a> => Bound => Normal
- BoundInternal => Bound => Normal

Update impl_device_context_deref! and impl_device_context_into_aref! macros to emit the BoundInternal => Bound deref and the corresponding ARef conversion.

Quoted 8 lines

---
This is needed by both the serdev bus code [1] and the runtime PM series [2].

[1] https://lore.kernel.org/driver-core/[email protected]/
[2] https://lore.kernel.org/driver-core/[email protected]/

---
 rust/kernel/device.rs | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

Thanks
- Markus Probst