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: <aIHa31DiaRvNK1Kb@google.com>
Date: Thu, 24 Jul 2025 07:03:59 +0000
From: Alice Ryhl <aliceryhl@...gle.com>
To: Danilo Krummrich <dakr@...nel.org>
Cc: 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, 
	tmgross@...ch.edu, 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 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@...labora.com>
> Reviewed-by: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@...nel.org>

A few nits below, but in general looks good.

Reviewed-by: Alice Ryhl <aliceryhl@...gle.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