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

[Alice Ryhl <aliceryhl@google.com>]

On Mon, Jul 21, 2025 at 01:42:17PM +0200, Greg KH wrote:
> On Mon, Jul 21, 2025 at 11:26:23AM +0000, Alice Ryhl wrote:
> > On Fri, Jul 18, 2025 at 12:45:38AM +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.
> > > 
> > > Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> > 
> > Overall I think this series is pretty great. It also clarifies some
> > things for me, particularly the difference between bus and class
> > devices.
> > 
> > > +/// # Device Types
> > >  ///
> > > +/// A [`Device`] can represent either a bus device or a class device.
> > >  ///
> > > +/// ## 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.
> > 
> > This raises a few questions for me.
> > 
> > The first one is "why"? On other series I have been told that interrupts
> > must be registered and deregistered before the device is unbound. Does
> > the same not apply to interrupts for an input device such as a USB
> > keyboard?
> 
> USB drivers don't have interrupts :)

I guess that if class drivers never have interrupts, then that is an
answer to my question.

> Seriously, generally, yes, you should always unregister your irq handler
> BEFORE you unbind the driver from the device, otherwise the callback
> logic normally assumes that the driver is bound to the device and the
> pointers are almost always "stale" at that time.
> 
> But I don't understand what interrupts have to do with the above
> documentation, what's the connection?

The connection is that to request an irq you must have a &Device<Bound>,
so if you can only obtain a &Device<Bound> to a bus device, then that
means that you can never request an irq for a class device.

> > The second one is why we use the same `Device` type for both cases?
> > Would it not make more sense to have a BusDevice and ClassDevice type?
> 
> We used to have both types, years/decades ago, and in the end, just gave
> up and merged them together as it really didn't make much sense as the
> structure really was the same type of thing everywhere.  So let's not go
> back to that mess if we can prevent it please.
> 
> We also used to have a out-of-tree patchset that just merged class and
> bus together, as they are almost the same thing as well, but that just
> caused too much confusion so we never merged it.

Okay, thanks!

Alice