[PATCH v2 0/3] Documentation for Device / Driver infrastructure

[PATCH v2 0/3] Documentation for Device / Driver infrastructure

[Danilo Krummrich]

This patch series expands the documentation for the generic device and driver
infrastructure and provides a guideline on how to implement bus and class
specific devices as well as bus specific driver infrastructure, i.e. bus
abstractions. It also expands on the existing documentation of device context
types.

Changes in v2:
  - Remove redundant DeviceContext dereference hierarchy.
  - Separate links as suggested by Alice.
  - Add a note that the guarantee for a Device reference to have a certain
    DeviceContext comes from the specific scope the Device reference is valid
    in.
  - "structures" -> "types"

Danilo Krummrich (3):
  device: rust: expand documentation for DeviceContext
  device: rust: expand documentation for Device
  driver: rust: expand documentation for driver infrastructure

 rust/kernel/device.rs | 208 +++++++++++++++++++++++++++++++++++++-----
 rust/kernel/driver.rs |  89 +++++++++++++++++-
 2 files changed, 271 insertions(+), 26 deletions(-)


base-commit: 51a486feac0ca002bee6429f03da0a6c206d0dc5
-- 
2.50.0

[PATCH v2 1/3] device: rust: expand documentation for DeviceContext

[Danilo Krummrich]

Expand the documentation around DeviceContext states and types, in order
to provide detailed information about their purpose and relationship
with each other.

Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
 rust/kernel/device.rs | 69 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 58 insertions(+), 11 deletions(-)

diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
index ca82926fd67f..f5d1db568f00 100644
--- a/rust/kernel/device.rs
+++ b/rust/kernel/device.rs
@@ -311,28 +311,75 @@ unsafe impl Send for Device {}
 // synchronization in `struct device`.
 unsafe impl Sync for Device {}
 
-/// Marker trait for the context of a bus specific device.
+/// Marker trait for the context or scope of a bus specific device.
 ///
-/// Some functions of a bus specific device should only be called from a certain context, i.e. bus
-/// callbacks, such as `probe()`.
+/// [`DeviceContext`] is a marker trait for types representing the context of a bus specific
+/// [`Device`].
 ///
-/// This is the marker trait for structures representing the context of a bus specific device.
+/// The specific device context types are: [`CoreInternal`], [`Core`], [`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
+/// [`Device<Core>`] can dereference to a [`Device<Bound>`].
+///
+/// The following enunumeration illustrates the dereference hierarchy of [`DeviceContext`] types.
+///
+/// - [`CoreInternal`] => [`Core`] => [`Bound`] => [`Normal`]
+///
+/// Bus devices can automatically implement the dereference hierarchy by using
+/// [`impl_device_context_deref`].
+///
+/// Note that the guarantee for a [`Device`] reference to have a certain [`DeviceContext`] comes
+/// from the specific scope the [`Device`] reference is valid in.
+///
+/// [`impl_device_context_deref`]: kernel::impl_device_context_deref
 pub trait DeviceContext: private::Sealed {}
 
-/// The [`Normal`] context is the context of a bus specific device when it is not an argument of
-/// any bus callback.
+/// The [`Normal`] context is the default [`DeviceContext`] of any [`Device`].
+///
+/// The normal context does not indicate any specific context. Any `Device<Ctx>` is also a valid
+/// [`Device<Normal>`]. It is the only [`DeviceContext`] for which it is valid to implement
+/// [`AlwaysRefCounted`] for.
+///
+/// [`AlwaysRefCounted`]: kernel::types::AlwaysRefCounted
 pub struct Normal;
 
-/// The [`Core`] context is the context of a bus specific device when it is supplied as argument of
-/// any of the bus callbacks, such as `probe()`.
+/// The [`Core`] context is the context of a bus specific device when it appears as argument of
+/// any bus specific callback, such as `probe()`.
+///
+/// The core context indicates that the [`Device<Core>`] reference's scope is limited to the bus
+/// callback it appears in. It is intended to be used for synchronization purposes. Bus device
+/// implementations can implement methods for [`Device<Core>`], such that they can only be called
+/// from bus callbacks.
 pub struct Core;
 
-/// Semantically the same as [`Core`] but reserved for internal usage of the corresponding bus
+/// Semantically the same as [`Core`], but reserved for internal usage of the corresponding bus
+/// abstraction.
+///
+/// The internal core context is intended to be used in exactly the same way as the [Core] context,
+/// with the difference that this [`DeviceContext`] is internal to the corresponding bus
 /// abstraction.
+///
+/// This context mainly exists to share generic [`Device`] infrastructure that should only be called
+/// from bus callbacks with bus abstractions, but without making them accessible for drivers.
 pub struct CoreInternal;
 
-/// The [`Bound`] context is the context of a bus specific device reference when it is guaranteed to
-/// be bound for the duration of its lifetime.
+/// The [`Bound`] context is the [`DeviceContext`] of a bus specific device when it is guaranteed to
+/// be bound to a driver.
+///
+/// The bound context indicates that for the entire duration of the lifetime of a [`Device<Bound>`]
+/// reference, the [`Device`] is guaranteed to be bound to a driver.
+///
+/// Some APIs, such as [`dma::CoherentAllocation`] or [`Devres`] rely on the [`Device`] to be bound,
+/// which can be proven with the [`Bound`] device context.
+///
+/// Any abstraction that can guarantee a scope where the corresponding bus device is bound, should
+/// provide a [`Device<Bound>`] reference to its users for this scope. This allows users to benefit
+/// from optimizations for accessing device resources, see also [`Devres::access`].
+///
+/// [`Devres`]: kernel::devres::Devres
+/// [`Devres::access`]: kernel::devres::Devres::access
+/// [`dma::CoherentAllocation`]: kernel::dma::CoherentAllocation
 pub struct Bound;
 
 mod private {
-- 
2.50.0

Re: [PATCH v2 1/3] device: rust: expand documentation for DeviceContext

[Alice Ryhl]

On Tue, Jul 22, 2025 at 04:59:59PM +0200, Danilo Krummrich wrote:
> Expand the documentation around DeviceContext states and types, in order
> to provide detailed information about their purpose and relationship
> with each other.
> 
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH v2 1/3] device: rust: expand documentation for DeviceContext

[Alexandre Courbot]

On Tue Jul 22, 2025 at 11:59 PM JST, Danilo Krummrich wrote:
> Expand the documentation around DeviceContext states and types, in order
> to provide detailed information about their purpose and relationship
> with each other.
>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>

A couple of nits below.

> ---
>  rust/kernel/device.rs | 69 ++++++++++++++++++++++++++++++++++++-------
>  1 file changed, 58 insertions(+), 11 deletions(-)
>
> diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
> index ca82926fd67f..f5d1db568f00 100644
> --- a/rust/kernel/device.rs
> +++ b/rust/kernel/device.rs
> @@ -311,28 +311,75 @@ unsafe impl Send for Device {}
>  // synchronization in `struct device`.
>  unsafe impl Sync for Device {}
>  
> -/// Marker trait for the context of a bus specific device.
> +/// Marker trait for the context or scope of a bus specific device.
>  ///
> -/// Some functions of a bus specific device should only be called from a certain context, i.e. bus
> -/// callbacks, such as `probe()`.
> +/// [`DeviceContext`] is a marker trait for types representing the context of a bus specific
> +/// [`Device`].
>  ///
> -/// This is the marker trait for structures representing the context of a bus specific device.
> +/// The specific device context types are: [`CoreInternal`], [`Core`], [`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
> +/// [`Device<Core>`] can dereference to a [`Device<Bound>`].
> +///
> +/// The following enunumeration illustrates the dereference hierarchy of [`DeviceContext`] types.

Typo: enumeration

> +///
> +/// - [`CoreInternal`] => [`Core`] => [`Bound`] => [`Normal`]
> +///
> +/// Bus devices can automatically implement the dereference hierarchy by using
> +/// [`impl_device_context_deref`].
> +///
> +/// Note that the guarantee for a [`Device`] reference to have a certain [`DeviceContext`] comes
> +/// from the specific scope the [`Device`] reference is valid in.
> +///
> +/// [`impl_device_context_deref`]: kernel::impl_device_context_deref
>  pub trait DeviceContext: private::Sealed {}
>  
> -/// The [`Normal`] context is the context of a bus specific device when it is not an argument of
> -/// any bus callback.
> +/// The [`Normal`] context is the default [`DeviceContext`] of any [`Device`].
> +///
> +/// The normal context does not indicate any specific context. Any `Device<Ctx>` is also a valid
> +/// [`Device<Normal>`]. It is the only [`DeviceContext`] for which it is valid to implement
> +/// [`AlwaysRefCounted`] for.
> +///
> +/// [`AlwaysRefCounted`]: kernel::types::AlwaysRefCounted
>  pub struct Normal;
>  
> -/// The [`Core`] context is the context of a bus specific device when it is supplied as argument of
> -/// any of the bus callbacks, such as `probe()`.
> +/// The [`Core`] context is the context of a bus specific device when it appears as argument of
> +/// any bus specific callback, such as `probe()`.
> +///
> +/// The core context indicates that the [`Device<Core>`] reference's scope is limited to the bus
> +/// callback it appears in. It is intended to be used for synchronization purposes. Bus device
> +/// implementations can implement methods for [`Device<Core>`], such that they can only be called
> +/// from bus callbacks.
>  pub struct Core;
>  
> -/// Semantically the same as [`Core`] but reserved for internal usage of the corresponding bus
> +/// Semantically the same as [`Core`], but reserved for internal usage of the corresponding bus
> +/// abstraction.
> +///
> +/// The internal core context is intended to be used in exactly the same way as the [Core] context,

[Core] -> [`Core`] I suppose?

Re: [PATCH v2 1/3] device: rust: expand documentation for DeviceContext

[Daniel Almeida]

Hi Danilo,

> On 22 Jul 2025, at 11:59, Danilo Krummrich <dakr@kernel.org> wrote:
> 
> Expand the documentation around DeviceContext states and types, in order
> to provide detailed information about their purpose and relationship
> with each other.
> 
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> ---
> rust/kernel/device.rs | 69 ++++++++++++++++++++++++++++++++++++-------
> 1 file changed, 58 insertions(+), 11 deletions(-)
> 
> diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
> index ca82926fd67f..f5d1db568f00 100644
> --- a/rust/kernel/device.rs
> +++ b/rust/kernel/device.rs
> @@ -311,28 +311,75 @@ unsafe impl Send for Device {}
> // synchronization in `struct device`.
> unsafe impl Sync for Device {}
> 
> -/// Marker trait for the context of a bus specific device.
> +/// Marker trait for the context or scope of a bus specific device.
> ///
> -/// Some functions of a bus specific device should only be called from a certain context, i.e. bus
> -/// callbacks, such as `probe()`.
> +/// [`DeviceContext`] is a marker trait for types representing the context of a bus specific
> +/// [`Device`].
> ///
> -/// This is the marker trait for structures representing the context of a bus specific device.
> +/// The specific device context types are: [`CoreInternal`], [`Core`], [`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
> +/// [`Device<Core>`] can dereference to a [`Device<Bound>`].
> +///
> +/// The following enunumeration illustrates the dereference hierarchy of [`DeviceContext`] types.
> +///
> +/// - [`CoreInternal`] => [`Core`] => [`Bound`] => [`Normal`]
> +///
> +/// Bus devices can automatically implement the dereference hierarchy by using
> +/// [`impl_device_context_deref`].
> +///
> +/// Note that the guarantee for a [`Device`] reference to have a certain [`DeviceContext`] comes
> +/// from the specific scope the [`Device`] reference is valid in.
> +///
> +/// [`impl_device_context_deref`]: kernel::impl_device_context_deref
> pub trait DeviceContext: private::Sealed {}
> 
> -/// The [`Normal`] context is the context of a bus specific device when it is not an argument of
> -/// any bus callback.
> +/// The [`Normal`] context is the default [`DeviceContext`] of any [`Device`].
> +///
> +/// The normal context does not indicate any specific context. Any `Device<Ctx>` is also a valid
> +/// [`Device<Normal>`]. It is the only [`DeviceContext`] for which it is valid to implement
> +/// [`AlwaysRefCounted`] for.
> +///
> +/// [`AlwaysRefCounted`]: kernel::types::AlwaysRefCounted
> pub struct Normal;
> 
> -/// The [`Core`] context is the context of a bus specific device when it is supplied as argument of
> -/// any of the bus callbacks, such as `probe()`.
> +/// The [`Core`] context is the context of a bus specific device when it appears as argument of
> +/// any bus specific callback, such as `probe()`.
> +///
> +/// The core context indicates that the [`Device<Core>`] reference's scope is limited to the bus
> +/// callback it appears in. It is intended to be used for synchronization purposes. Bus device
> +/// implementations can implement methods for [`Device<Core>`], such that they can only be called
> +/// from bus callbacks.
> pub struct Core;
> 
> -/// Semantically the same as [`Core`] but reserved for internal usage of the corresponding bus
> +/// Semantically the same as [`Core`], but reserved for internal usage of the corresponding bus
> +/// abstraction.
> +///
> +/// The internal core context is intended to be used in exactly the same way as the [Core] context,
> +/// with the difference that this [`DeviceContext`] is internal to the corresponding bus
> /// abstraction.
> +///
> +/// This context mainly exists to share generic [`Device`] infrastructure that should only be called
> +/// from bus callbacks with bus abstractions, but without making them accessible for drivers.
> pub struct CoreInternal;
> 
> -/// The [`Bound`] context is the context of a bus specific device reference when it is guaranteed to
> -/// be bound for the duration of its lifetime.
> +/// The [`Bound`] context is the [`DeviceContext`] of a bus specific device when it is guaranteed to
> +/// be bound to a driver.
> +///
> +/// The bound context indicates that for the entire duration of the lifetime of a [`Device<Bound>`]
> +/// reference, the [`Device`] is guaranteed to be bound to a driver.
> +///
> +/// Some APIs, such as [`dma::CoherentAllocation`] or [`Devres`] rely on the [`Device`] to be bound,
> +/// which can be proven with the [`Bound`] device context.
> +///
> +/// Any abstraction that can guarantee a scope where the corresponding bus device is bound, should
> +/// provide a [`Device<Bound>`] reference to its users for this scope. This allows users to benefit
> +/// from optimizations for accessing device resources, see also [`Devres::access`].
> +///
> +/// [`Devres`]: kernel::devres::Devres
> +/// [`Devres::access`]: kernel::devres::Devres::access
> +/// [`dma::CoherentAllocation`]: kernel::dma::CoherentAllocation
> pub struct Bound;
> 
> mod private {
> -- 
> 2.50.0
> 
> 

Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>

[PATCH v2 2/3] device: rust: expand documentation for Device

[Danilo Krummrich]

The documentation for the generic Device type is outdated and deserves
much more detail.

Hence, expand the documentation and cover topics such as device types,
device contexts, as well as information on how to use the generic device
infrastructure to implement bus and class specific device types.

Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
 rust/kernel/device.rs | 139 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 126 insertions(+), 13 deletions(-)

diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
index f5d1db568f00..9cc35ea6db98 100644
--- a/rust/kernel/device.rs
+++ b/rust/kernel/device.rs
@@ -15,23 +15,130 @@
 
 pub mod property;
 
-/// A reference-counted device.
+/// The core representation of a device in the kernel's driver model.
 ///
-/// This structure represents the Rust abstraction for a C `struct device`. This implementation
-/// abstracts the usage of an already existing C `struct device` within Rust code that we get
-/// passed from the C side.
+/// This structure represents the Rust abstraction for a C `struct device`. A [`Device`] can either
+/// exist as temporary reference (see also [`Device::from_raw`]), which is only valid within a
+/// certain scope or as [`ARef<Device>`], owning a dedicated reference count.
 ///
-/// An instance of this abstraction can be obtained temporarily or permanent.
+/// # Device Types
 ///
-/// A temporary one is bound to the lifetime of the C `struct device` pointer used for creation.
-/// A permanent instance is always reference-counted and hence not restricted by any lifetime
-/// boundaries.
+/// A [`Device`] can represent either a bus device or a class device.
 ///
-/// For subsystems it is recommended to create a permanent instance to wrap into a subsystem
-/// specific device structure (e.g. `pci::Device`). This is useful for passing it to drivers in
-/// `T::probe()`, such that a driver can store the `ARef<Device>` (equivalent to storing a
-/// `struct device` pointer in a C driver) for arbitrary purposes, e.g. allocating DMA coherent
-/// memory.
+/// ## Bus Devices
+///
+/// A bus device is a [`Device`] that is associated with a physical or virtual bus. Examples of
+/// buses include PCI, USB, I2C, and SPI. Devices attached to a bus are registered with a specific
+/// bus type, which facilitates matching devices with appropriate drivers based on IDs or other
+/// identifying information. Bus devices are visible in sysfs under `/sys/bus/<bus-name>/devices/`.
+///
+/// ## Class Devices
+///
+/// A class device is a [`Device`] that is associated with a logical category of functionality
+/// rather than a physical bus. Examples of classes include block devices, network interfaces, sound
+/// cards, and input devices. Class devices are grouped under a common class and exposed to
+/// userspace via entries in `/sys/class/<class-name>/`.
+///
+/// # Device Context
+///
+/// [`Device`] references are generic over a [`DeviceContext`], which represents the type state of
+/// a [`Device`].
+///
+/// As the name indicates, this type state represents the context of the scope the [`Device`]
+/// 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`].
+///
+/// Unless selected otherwise [`Device`] defaults to the [`Normal`] [`DeviceContext`], which by
+/// itself has no additional requirements.
+///
+/// It is always up to the caller of [`Device::from_raw`] to select the correct [`DeviceContext`]
+/// type for the corresponding scope the [`Device`] reference is created in.
+///
+/// All [`DeviceContext`] types other than [`Normal`] are intended to be used with
+/// [bus devices](#bus-devices) only.
+///
+/// # Implementing Bus Devices
+///
+/// This section provides a guideline to implement bus specific devices, such as [`pci::Device`] or
+/// [`platform::Device`].
+///
+/// A bus specific device should be defined as follows.
+///
+/// ```ignore
+/// #[repr(transparent)]
+/// pub struct Device<Ctx: device::DeviceContext = device::Normal>(
+///     Opaque<bindings::bus_device_type>,
+///     PhantomData<Ctx>,
+/// );
+/// ```
+///
+/// Since devices are reference counted, [`AlwaysRefCounted`] should be implemented for `Device`
+/// (i.e. `Device<Normal>`). Note that [`AlwaysRefCounted`] must not be implemented for any other
+/// [`DeviceContext`], since all other device context types are only valid in a certain scope.
+///
+/// In order to be able to implement the [`DeviceContext`] dereference hierarchy, bus device
+/// implementations should call the [`impl_device_context_deref`] macro as shown below.
+///
+/// ```ignore
+/// // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s
+/// // generic argument.
+/// kernel::impl_device_context_deref!(unsafe { Device });
+/// ```
+/// In order to convert from a any [`Device<Ctx>`] to [`ARef<Device>`], bus devices can implement
+/// the following macro call.
+///
+/// ```ignore
+/// kernel::impl_device_context_into_aref!(Device);
+/// ```
+/// Bus devices should also implement the following [`AsRef`] implementation, such that users can
+/// easily derive a generic [`Device`] reference.
+///
+/// ```ignore
+/// impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
+///     fn as_ref(&self) -> &device::Device<Ctx> {
+///         ...
+///     }
+/// }
+/// ```
+///
+/// # Implementing Class Devices
+///
+/// Class device implementations require less infrastructure and depend slightly more on the
+/// specific subsystem.
+///
+/// An example implementation for a class device could look like this.
+///
+/// ```ignore
+/// #[repr(C)]
+/// #[pin_data]
+/// pub struct Device<T: class::Driver> {
+///     dev: Opaque<bindings::class_device_type>,
+///     #[pin]
+///     data: T::Data,
+/// }
+/// ```
+///
+/// This class device uses the sub-classing pattern to embed the driver's private data within the
+/// allocation of the class device. For this to be possible the class device is generic over the
+/// class specific `Driver` trait implementation.
+///
+/// Just like any device, class devices are reference counted and should hence implement
+/// [`AlwaysRefCounted`] for `Device`.
+///
+/// Class devices should also implement the following [`AsRef`] implementation, such that users can
+/// easily derive a generic [`Device`] reference.
+///
+/// ```ignore
+/// impl<T: class::Driver> AsRef<device::Device> for Device<T> {
+///     fn as_ref(&self) -> &device::Device {
+///         ...
+///     }
+/// }
+/// ```
+///
+/// An example for a class device implementation is [`drm::Device`].
 ///
 /// # Invariants
 ///
@@ -42,6 +149,12 @@
 ///
 /// `bindings::device::release` is valid to be called from any thread, hence `ARef<Device>` can be
 /// dropped from any thread.
+///
+/// [`AlwaysRefCounted`]: kernel::types::AlwaysRefCounted
+/// [`drm::Device`]: kernel::drm::Device
+/// [`impl_device_context_deref`]: kernel::impl_device_context_deref
+/// [`pci::Device`]: kernel::pci::Device
+/// [`platform::Device`]: kernel::platform::Device
 #[repr(transparent)]
 pub struct Device<Ctx: DeviceContext = Normal>(Opaque<bindings::device>, PhantomData<Ctx>);
 
-- 
2.50.0

Re: [PATCH v2 2/3] device: rust: expand documentation for Device

[Alice Ryhl]

On Tue, Jul 22, 2025 at 05:00:00PM +0200, Danilo Krummrich wrote:
> The documentation for the generic Device type is outdated and deserves
> much more detail.
> 
> Hence, expand the documentation and cover topics such as device types,
> device contexts, as well as information on how to use the generic device
> infrastructure to implement bus and class specific device types.
> 
> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

A few nits below, but in general looks good.

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

> -/// This structure represents the Rust abstraction for a C `struct device`. This implementation
> -/// abstracts the usage of an already existing C `struct device` within Rust code that we get
> -/// passed from the C side.
> +/// This structure represents the Rust abstraction for a C `struct device`. A [`Device`] can either
> +/// exist as temporary reference (see also [`Device::from_raw`]), which is only valid within a
> +/// certain scope or as [`ARef<Device>`], owning a dedicated reference count.

Doesn't there need to be a comma between "scope" and "or"?

It's possible that I'm confusing the danish and english comma rules, but
I got confused when reading this.

> +/// # Implementing Class Devices
> +///
> +/// Class device implementations require less infrastructure and depend slightly more on the
> +/// specific subsystem.
> +///
> +/// An example implementation for a class device could look like this.
> +///
> +/// ```ignore
> +/// #[repr(C)]
> +/// #[pin_data]
> +/// pub struct Device<T: class::Driver> {
> +///     dev: Opaque<bindings::class_device_type>,
> +///     #[pin]
> +///     data: T::Data,

Should the `dev` field not also be pinned?

Alice

Re: [PATCH v2 2/3] device: rust: expand documentation for Device

[Danilo Krummrich]

On Thu Jul 24, 2025 at 9:03 AM CEST, Alice Ryhl wrote:
> On Tue, Jul 22, 2025 at 05:00:00PM +0200, Danilo Krummrich wrote:
>> The documentation for the generic Device type is outdated and deserves
>> much more detail.
>> 
>> Hence, expand the documentation and cover topics such as device types,
>> device contexts, as well as information on how to use the generic device
>> infrastructure to implement bus and class specific device types.
>> 
>> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
>> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
>
> A few nits below, but in general looks good.
>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
>
>> -/// This structure represents the Rust abstraction for a C `struct device`. This implementation
>> -/// abstracts the usage of an already existing C `struct device` within Rust code that we get
>> -/// passed from the C side.
>> +/// This structure represents the Rust abstraction for a C `struct device`. A [`Device`] can either
>> +/// exist as temporary reference (see also [`Device::from_raw`]), which is only valid within a
>> +/// certain scope or as [`ARef<Device>`], owning a dedicated reference count.
>
> Doesn't there need to be a comma between "scope" and "or"?
>
> It's possible that I'm confusing the danish and english comma rules, but
> I got confused when reading this.

No, I think you're right.

>> +/// # Implementing Class Devices
>> +///
>> +/// Class device implementations require less infrastructure and depend slightly more on the
>> +/// specific subsystem.
>> +///
>> +/// An example implementation for a class device could look like this.
>> +///
>> +/// ```ignore
>> +/// #[repr(C)]
>> +/// #[pin_data]
>> +/// pub struct Device<T: class::Driver> {
>> +///     dev: Opaque<bindings::class_device_type>,
>> +///     #[pin]
>> +///     data: T::Data,
>
> Should the `dev` field not also be pinned?

I think we should just remove any pin stuff from the example, that's an
implementation detail.

--

In case you're curious, the reason it's there is because that's how drm::Device
is defined. However, drm::Device doesn't need the pin stuff either, but I forgot
to remove it. See drm::Device::new():

    /// Create a new `drm::Device` for a `drm::Driver`.
    pub fn new(dev: &device::Device, data: impl PinInit<T::Data, Error>) -> Result<ARef<Self>> {
        // SAFETY:
        // - `VTABLE`, as a `const` is pinned to the read-only section of the compilation,
        // - `dev` is valid by its type invarants,
        let raw_drm: *mut Self = unsafe {
            bindings::__drm_dev_alloc(
                dev.as_raw(),
                &Self::VTABLE,
                mem::size_of::<Self>(),
                mem::offset_of!(Self, dev),
            )
        }
        .cast();
        let raw_drm = NonNull::new(from_err_ptr(raw_drm)?).ok_or(ENOMEM)?;

        // SAFETY: `raw_drm` is a valid pointer to `Self`.
        let raw_data = unsafe { ptr::addr_of_mut!((*raw_drm.as_ptr()).data) };

        // SAFETY:
        // - `raw_data` is a valid pointer to uninitialized memory.
        // - `raw_data` will not move until it is dropped.
        unsafe { data.__pinned_init(raw_data) }.inspect_err(|_| {
            // SAFETY: `__drm_dev_alloc()` was successful, hence `raw_drm` must be valid and the
            // refcount must be non-zero.
            unsafe { bindings::drm_dev_put(ptr::addr_of_mut!((*raw_drm.as_ptr()).dev).cast()) };
        })?;

        // SAFETY: The reference count is one, and now we take ownership of that reference as a
        // `drm::Device`.
        Ok(unsafe { ARef::from_raw(raw_drm) })
    }

While we use data.__pinned_init(), I don't think the drm::Device needs any of
the pin macros.

- Danilo

Re: [PATCH v2 2/3] device: rust: expand documentation for Device

[Alexandre Courbot]

On Wed Jul 23, 2025 at 12:00 AM JST, Danilo Krummrich wrote:
> The documentation for the generic Device type is outdated and deserves
> much more detail.
>
> Hence, expand the documentation and cover topics such as device types,
> device contexts, as well as information on how to use the generic device
> infrastructure to implement bus and class specific device types.
>
> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>

<snip>
> +/// # Implementing Bus Devices
> +///
> +/// This section provides a guideline to implement bus specific devices, such as [`pci::Device`] or
> +/// [`platform::Device`].
> +///
> +/// A bus specific device should be defined as follows.
> +///
> +/// ```ignore
> +/// #[repr(transparent)]
> +/// pub struct Device<Ctx: device::DeviceContext = device::Normal>(
> +///     Opaque<bindings::bus_device_type>,
> +///     PhantomData<Ctx>,
> +/// );
> +/// ```
> +///
> +/// Since devices are reference counted, [`AlwaysRefCounted`] should be implemented for `Device`
> +/// (i.e. `Device<Normal>`). Note that [`AlwaysRefCounted`] must not be implemented for any other
> +/// [`DeviceContext`], since all other device context types are only valid in a certain scope.

supernit: "valid within a certain scope"?

> +///
> +/// In order to be able to implement the [`DeviceContext`] dereference hierarchy, bus device
> +/// implementations should call the [`impl_device_context_deref`] macro as shown below.
> +///
> +/// ```ignore
> +/// // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s
> +/// // generic argument.
> +/// kernel::impl_device_context_deref!(unsafe { Device });
> +/// ```
> +/// In order to convert from a any [`Device<Ctx>`] to [`ARef<Device>`], bus devices can implement

Missing empty line after the code block? I don't think this would break
rendering though.

> +/// the following macro call.
> +///
> +/// ```ignore
> +/// kernel::impl_device_context_into_aref!(Device);
> +/// ```
> +/// Bus devices should also implement the following [`AsRef`] implementation, such that users can

Here as well.

[PATCH v2 3/3] driver: rust: expand documentation for driver infrastructure

[Danilo Krummrich]

Add documentation about generic driver infrastructure, representing a
guideline on how the generic driver infrastructure is intended to be
used to implement bus specific driver APIs.

This covers aspects such as the bus specific driver trait, adapter
implementation, driver registration and custom device ID types.

Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
 rust/kernel/driver.rs | 89 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/driver.rs b/rust/kernel/driver.rs
index a8f2675ba7a7..279e3af20682 100644
--- a/rust/kernel/driver.rs
+++ b/rust/kernel/driver.rs
@@ -2,8 +2,93 @@
 
 //! Generic support for drivers of different buses (e.g., PCI, Platform, Amba, etc.).
 //!
-//! Each bus / subsystem is expected to implement [`RegistrationOps`], which allows drivers to
-//! register using the [`Registration`] class.
+//! This documentation describes how to implement a bus specific driver API and how to align it with
+//! the design of (bus specific) devices.
+//!
+//! Note: Readers are expected to know the content of the documentation of [`Device`] and
+//! [`DeviceContext`].
+//!
+//! # Driver Trait
+//!
+//! The main driver interface is defined by a bus specific driver trait. For instance:
+//!
+//! ```ignore
+//! pub trait Driver: Send {
+//!     /// The type holding information about each device ID supported by the driver.
+//!     type IdInfo: 'static;
+//!
+//!     /// The table of OF device ids supported by the driver.
+//!     const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = None;
+//!
+//!     /// The table of ACPI device ids supported by the driver.
+//!     const ACPI_ID_TABLE: Option<acpi::IdTable<Self::IdInfo>> = None;
+//!
+//!     /// Driver probe.
+//!     fn probe(dev: &Device<device::Core>, id_info: &Self::IdInfo) -> Result<Pin<KBox<Self>>>;
+//!
+//!     /// Driver unbind (optional).
+//!     fn unbind(dev: &Device<device::Core>, this: Pin<&Self>) {
+//!         let _ = (dev, this);
+//!     }
+//! }
+//! ```
+//!
+//! For specific examples see [`auxiliary::Driver`], [`pci::Driver`] and [`platform::Driver`].
+//!
+//! The `probe()` callback should return a `Result<Pin<KBox<Self>>>`, i.e. the driver's private
+//! data. The bus abstraction should store the pointer in the corresponding bus device. The generic
+//! [`Device`] infrastructure provides common helpers for this purpose on its
+//! [`Device<CoreInternal>`] implementation.
+//!
+//! All driver callbacks should provide a reference to the driver's private data. Once the driver
+//! is unbound from the device, the bus abstraction should take back the ownership of the driver's
+//! private data from the corresponding [`Device`] and [`drop`] it.
+//!
+//! All driver callbacks should provide a [`Device<Core>`] reference (see also [`device::Core`]).
+//!
+//! # Adapter
+//!
+//! The adapter implementation of a bus represents the abstraction layer between the C bus
+//! callbacks and the Rust bus callbacks. It therefore has to be generic over an implementation of
+//! the [driver trait](#driver-trait).
+//!
+//! ```ignore
+//! pub struct Adapter<T: Driver>;
+//! ```
+//!
+//! There's a common [`Adapter`] trait that can be implemented to inherit common driver
+//! infrastructure, such as finding the ID info from an [`of::IdTable`] or [`acpi::IdTable`].
+//!
+//! # Driver Registration
+//!
+//! In order to register C driver types (such as `struct platform_driver`) the [adapter](#adapter)
+//! should implement the [`RegistrationOps`] trait.
+//!
+//! This trait implementation can be used to create the actual registration with the common
+//! [`Registration`] type.
+//!
+//! Typically, bus abstractions want to provide a bus specific `module_bus_driver!` macro, which
+//! creates a kernel module with exactly one [`Registration`] for the bus specific adapter.
+//!
+//! The generic driver infrastructure provides a helper for this with the [`module_driver`] macro.
+//!
+//! # Device IDs
+//!
+//! Besides the common device ID types, such as [`of::DeviceId`] and [`acpi::DeviceId`], most buses
+//! may need to implement their own device ID types.
+//!
+//! For this purpose the generic infrastructure in [`device_id`] should be used.
+//!
+//! [`auxiliary::Driver`]: kernel::auxiliary::Driver
+//! [`Core`]: device::Core
+//! [`Device`]: device::Device
+//! [`Device<Core>`]: device::Device<device::Core>
+//! [`Device<CoreInternal>`]: device::Device<device::CoreInternal>
+//! [`DeviceContext`]: device::DeviceContext
+//! [`device_id`]: kernel::device_id
+//! [`module_driver`]: kernel::module_driver
+//! [`pci::Driver`]: kernel::pci::Driver
+//! [`platform::Driver`]: kernel::platform::Driver
 
 use crate::error::{Error, Result};
 use crate::{acpi, device, of, str::CStr, try_pin_init, types::Opaque, ThisModule};
-- 
2.50.0

Re: [PATCH v2 3/3] driver: rust: expand documentation for driver infrastructure

[Alice Ryhl]

On Tue, Jul 22, 2025 at 05:00:01PM +0200, Danilo Krummrich wrote:
> Add documentation about generic driver infrastructure, representing a
> guideline on how the generic driver infrastructure is intended to be
> used to implement bus specific driver APIs.
> 
> This covers aspects such as the bus specific driver trait, adapter
> implementation, driver registration and custom device ID types.
> 
> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH v2 3/3] driver: rust: expand documentation for driver infrastructure

[Alexandre Courbot]

On Wed Jul 23, 2025 at 12:00 AM JST, Danilo Krummrich wrote:
> Add documentation about generic driver infrastructure, representing a
> guideline on how the generic driver infrastructure is intended to be
> used to implement bus specific driver APIs.
>
> This covers aspects such as the bus specific driver trait, adapter
> implementation, driver registration and custom device ID types.
>
> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>

Re: [PATCH v2 0/3] Documentation for Device / Driver infrastructure

[Danilo Krummrich]

On Tue Jul 22, 2025 at 4:59 PM CEST, Danilo Krummrich wrote:

Applied to driver-core-linus, thanks!

> Danilo Krummrich (3):
>   device: rust: expand documentation for DeviceContext

    [ Fix two minor typos. - Danilo ]

>   device: rust: expand documentation for Device

    [ Add empty line after code blocks, "in" -> "within", remove unnecessary
      pin annotations in class device example. - Danilo ]

>   driver: rust: expand documentation for driver infrastructure