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

["Alexandre Courbot" <acourbot@nvidia.com>]

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.