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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <DC0GV5DU4GGU.1G4FLQVXU62VI@nvidia.com>
Date: Tue, 12 Aug 2025 22:00:29 +0900
From: "Alexandre Courbot" <acourbot@...dia.com>
To: "Danilo Krummrich" <dakr@...nel.org>, <gregkh@...uxfoundation.org>,
 <rafael@...nel.org>, <ojeda@...nel.org>, <alex.gaynor@...il.com>,
 <boqun.feng@...il.com>, <gary@...yguo.net>, <bjorn3_gh@...tonmail.com>,
 <lossin@...nel.org>, <a.hindborg@...nel.org>, <aliceryhl@...gle.com>,
 <tmgross@...ch.edu>
Cc: <rust-for-linux@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
 "Daniel Almeida" <daniel.almeida@...labora.com>
Subject: Re: [PATCH v2 2/3] device: rust: expand documentation for Device

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@...labora.com>
> Reviewed-by: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@...nel.org>

Reviewed-by: Alexandre Courbot <acourbot@...dia.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.