Re: [PATCH v9 1/3] rust: leds: add basic led classdev abstractions

[Markus Probst <markus.probst@posteo.de>]

On Thu, 2025-11-20 at 11:34 +0000, Alice Ryhl wrote:
> On Wed, Nov 19, 2025 at 02:11:21PM +0000, Markus Probst wrote:
> > Implement the core abstractions needed for led class devices, including:
> > 
> > * `led::LedOps` - the trait for handling leds, including
> >   `brightness_set`, `brightness_get` and `blink_set`
> > 
> > * `led::InitData` - data set for the led class device
> > 
> > * `led::Device` - a safe wrapper around `led_classdev`
> > 
> > Signed-off-by: Markus Probst <markus.probst@posteo.de>
> > ---
> >  MAINTAINERS        |   7 +
> >  rust/kernel/led.rs | 472 +++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  rust/kernel/lib.rs |   1 +
> >  3 files changed, 480 insertions(+)
> > 
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index b71ea515240a..80cb030911b7 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -14112,6 +14112,13 @@ F:	drivers/leds/
> >  F:	include/dt-bindings/leds/
> >  F:	include/linux/leds.h
> >  
> > +LED SUBSYSTEM [RUST]
> > +M:	Markus Probst <markus.probst@posteo.de>
> > +L:	linux-leds@vger.kernel.org
> > +L:	rust-for-linux@vger.kernel.org
> > +S:	Maintained
> > +F:	rust/kernel/led.rs
> > +
> >  LEGO MINDSTORMS EV3
> >  R:	David Lechner <david@lechnology.com>
> >  S:	Maintained
> > diff --git a/rust/kernel/led.rs b/rust/kernel/led.rs
> > new file mode 100644
> > index 000000000000..fca55f02be8d
> > --- /dev/null
> > +++ b/rust/kernel/led.rs
> > @@ -0,0 +1,472 @@
> > +// SPDX-License-Identifier: GPL-2.0
> > +
> > +//! Abstractions for the leds driver model.
> > +//!
> > +//! C header: [`include/linux/leds.h`](srctree/include/linux/leds.h)
> > +
> > +use core::{
> > +    marker::PhantomData,
> > +    mem::transmute,
> > +    pin::Pin,
> > +    ptr::NonNull, //
> > +};
> > +
> > +use pin_init::{
> > +    pin_data,
> > +    pinned_drop,
> > +    PinInit, //
> > +};
> > +
> > +use crate::{
> > +    build_error,
> > +    container_of,
> > +    device::{
> > +        self,
> > +        property::FwNode,
> > +        AsBusDevice,
> > +        Bound, //
> > +    },
> > +    devres::Devres,
> > +    error::{
> > +        code::EINVAL,
> > +        from_result,
> > +        to_result,
> > +        Error,
> > +        Result,
> > +        VTABLE_DEFAULT_ERROR, //
> > +    },
> > +    macros::vtable,
> > +    str::CStr,
> > +    try_pin_init,
> > +    types::{
> > +        ARef,
> > +        Opaque, //
> > +    }, //
> > +};
> 
> Please import kernel::prelude::* and remove all the imports that are
> available from the prelude.
> 
> > +impl<'a> InitData<'a> {
> > +    /// Sets the firmware node
> > +    pub fn fwnode(self, fwnode: Option<ARef<FwNode>>) -> Self {
> 
> I'm thinking that perhaps this should just be a `&'a FwNode` instead?
> That way, you can increment the refcount in Device::new() if
> registration is successful.
This was the way I have done it in v8. I issue with this approch is, if
the fwnode is optional, you have to do this ugly code:

let mut init_data = InitData::new()
    .default_label(c_str!(":label"))
    .devicename(c_str!("devicename"));

let child_fwnode = fwnode.child_by_name(c_str!("led"));

if let Some(child_fwnode_ref) = &child_fwnode {
    init_data = init_data.fwnode(child_fwnode_ref);
}

Instead of

let mut init_data = InitData::new()
    .fwnode(fwnode.child_by_name(c_str!("led")))
    .default_label(c_str!(":label"))
    .devicename(c_str!("devicename"));

Furthermore, most of the functions in the rust abstractions return a
`ARef<FwNode>` anyway. The only exception I found is
`device::Device::fwnode()`, but an led driver usually has more than one
led to its unlikely that the root fwnode will be directly passed to an
led classdev. As a result with the `&'a FwNode` approach, the led
abstraction would increment the reference count once, and the driver
will then decrement it once (dropping of the ARef<FwNode>).
Sounds like a tiny overhead to me.

> 
> > +        Self { fwnode, ..self }
> > +    }
> > +
> > +    /// Sets a default label
> 
> There are many missing periods in doc-comments.
> 
> > +/// Trait defining the operations for a LED driver.
> > +///
> > +/// # Examples
> > +///
> > +///```
> > +/// # use kernel::{
> > +/// #     c_str, device, devres::Devres,
> > +/// #     error::Result, led,
> > +/// #     macros::vtable, platform, prelude::*,
> > +/// # };
> > +/// # use core::pin::Pin;
> > +///
> > +/// struct MyLedOps;
> 
> When using # in examples, please do not have an empty line before
> beginning the example. It shows up as a weird extra empty line in the
> rendered docs.
> 
> You could consider just making the imports displayed here also.
> 
> Also the ``` both above and below the example usually has a space:
> 
> /// ```
> 
> rather than
> 
> ///```
> 
> > +                    // SAFETY:
> > +                    // - `parent.as_raw()` is guaranteed to be a pointer to a valid `device`
> > +                    //    or a null pointer.
> > +                    // - `ptr` is guaranteed to be a pointer to an initialized `led_classdev`.
> > +                    to_result(unsafe {
> > +                        bindings::led_classdev_register_ext(
> > +                            parent.as_ref().as_raw(),
> > +                            ptr,
> > +                            &mut init_data_raw,
> > +                        )
> > +                    })?;
> > +
> > +                    core::mem::forget(init_data.fwnode); // keep the reference count incremented
> 
> This led abstraction implicitly takes a refcount on the fwnode and then
> drops it when the device is unbound.
I did look through the led classdev code and noticed that the fwnode
refcount isn't incremented. From what I can tell, the driver is
responsible to ensure the fwnode refcount never hits 0 while the led
classdev is registered. Thats why I incremented the refcount of the
fwnode to ensure the safety requirement is met.

Thanks
- Markus Probst

> 
> Lee, can you confirm that taking a refcount on the fwnode is the right
> way to use the LED subsytem?
> 
> Alice