rust: leds: add led classdev abstractions
v21 cover rust: leds: add led classdev abstractions
This patch series has previously been contained in
https://lore.kernel.org/rust-for-linux/[email protected]/T/#t
which added a rust written led driver for a microcontroller via i2c.
As the reading and writing to the i2c client via the register! macro has not been implemented yet [1], the patch series will only contain the additional abstractions required.
This series depends on [1].
[1] https://lore.kernel.org/rust-for-linux/[email protected]/
The following changes were made:
* add basic led classdev abstractions to register and unregister leds
* add basic led classdev abstractions to register and unregister multicolor leds
Changes since v20:
* resolve Sashiko regressions:
* fix typo
* fix fwnode refcount decremented too early
Changes since v19:
* rebase on v7.2-rc1:
* Add max_intensity to MultiColorSubLed
* use safer KBox::pin_slice instead of KVec
(len might not equal capacity)
* explicitly call FwNode::dec_ref instead of dropping a reconstructed ARef<FwNode>.
* remove direct access to intensity and brightness fields, which may get mutated concurrently by the C side
* fix safety comments pointing to functions from previous revisions
Changes since v18:
* add inlines
* fix invalid documentation
* improve led color duplicate checking
Changes since v17:
* use lifetimes instead of Devres
Changes since v16:
* use for loops for duplicate checking
Changes since v15:
* fix issues reported by Sashiko bot:
* fix returning error not possible on brightness_get callback
Changes since v14:
* fix issues reported by Sashiko bot:
* add missing inlines
* add missing Sync trait bound
* fix vertical import layout for public export of private types
* fix potential memory leak, if a multicolor led device with over u32::MAX subleds is registered
* remove default_trigger option
* fix missing CAST doc
Changes since v13:
* rebased onto v7.1-rc1
Changes since v12:
* add led::DeviceBuilder::name() and `DeviceBuilderState'
* add led::Color::as_c_str
Changes since v11:
* use led::DeviceBuilder instead of led::InitData
* use static_assert instead of const { assert!(...) }
* restructured patches to avoid moving led::Device from rust/kernel/led.rs to rust/kernel/led/normal.rs in the 2. patch
Changes since v10:
* allow in-place initialization of LedOps
* run rustfmt for code inside try_pin_init!
Changes since v9:
* add missing periods in documentation
* duplicate led::Device and led::Adapter instead of using a complex trait
* fix imports not using prelude
* adapt to CStr change
* documented led::Color::Multi and led::Color::Rgb
Changes since v8:
* accept Option<ARef<Fwnode>> in led::InitData::fwnode()
* make functions in MultiColorSubLed const
* drop the "rust: Add trait to convert a device reference to a bus device reference" patch, as it has been picked into driver-core
Changes since v7:
* adjusted import style
* added classdev parameter to callback functions in LedOps
* implement led::Color
* extend led::InitData with
- initial_brightness
- default_trigger
- default_color
* split generic and normal led classdev abstractions up (see patch 3/4)
* add multicolor led class device abstractions (see patch 4/4)
* added MAINTAINERS entry
Changes since v6:
* fixed typos
* improved documentation
Changes since v5:
* rename IntoBusDevice trait into AsBusDevice
* fix documentation about LedOps::BLOCKING
* removed dependency on i2c bindings
* added AsBusDevice implementation for platform::Device
* removed device::Device fallback implementation
* document that AsBusDevice must not be used by drivers and is intended for bus and class device abstractions only.
Changes since v4:
* add abstraction to convert a device reference to a bus device reference
* require the bus device as parent device and provide it in class device callbacks
* remove Pin<Vec<_>> abstraction (as not relevant for the led abstractions)
* fixed formatting in led::Device::new
* fixed LedOps::BLOCKING did the inverse effect
Changes since v3:
* fixed kunit tests failing because of example in documentation
Changes since v2:
* return Devres on led::Device creation
* replace KBox<T> with T in struct definition
* increment and decrement reference-count of fwnode
* make a device parent mandatory for led classdev creation
* rename led::Handler to led::LedOps
* add optional brightness_get function to led::LedOps
* use #[vtable] instead of const BLINK: bool
* use Opaque::cast_from instead of casting a pointer
* improve documentation
* improve support for older rust versions
* use &Device<Bound> for parent
Changes since v1:
* fixed typos noticed by Onur Özkan
---
Markus Probst (3):
rust: leds: add basic led classdev abstractions
rust: leds: add Mode trait
rust: leds: add multicolor classdev abstractions
MAINTAINERS | 8 + rust/bindings/bindings_helper.h | 1 + rust/kernel/led.rs | 339 +++++++++++++++++++++++++++++ rust/kernel/led/multicolor.rs | 460 ++++++++++++++++++++++++++++++++++++++++ rust/kernel/led/normal.rs | 238 +++++++++++++++++++++ rust/kernel/lib.rs | 1 + 6 files changed, 1047 insertions(+)
---
base-commit: 728e68a889bcf257b1e67298b12c360e5c3a13e0
change-id: 20251114-rust_leds-a959f7c2f7f9
PATCH v21 1/3 rust: leds: add basic led classdev abstractions
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::DeviceBuilder - the builder for the led class device
* led::Device - a safe wrapper around led_classdev
--- MAINTAINERS | 8 ++ rust/kernel/led.rs | 288 ++++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/led/normal.rs | 230 ++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 4 files changed, 527 insertions(+)
MAINTAINERS +8 -0
@@ -14662,6 +14662,14 @@ F: drivers/leds/ F: include/dt-bindings/leds/ F: include/linux/leds.h +LED SUBSYSTEM [RUST] +M: Markus Probst <[email protected]> +L: [email protected] +L: [email protected] +S: Maintained +F: rust/kernel/led.rs +F: rust/kernel/led/ + LEGO MINDSTORMS EV3 R: David Lechner <[email protected]> S: Maintained
rust/kernel/led.rs new file +288 -0
288 lines not on this page · raw message
rust/kernel/led/normal.rs new file +230 -0
230 lines not on this page · raw message
rust/kernel/lib.rs +1 -0
@@ -90,6 +90,7 @@pub mod jump_label;#[cfg( CONFIG_KUNIT )] pub mod kunit; +pub mod led;pub mod list;pub mod maple_tree;pub mod miscdevice;
Signature · 1 line
2.53.0
[email protected]
AI reviewRe: [PATCH v21 1/3] rust: leds: add basic led classdev abstractions
Thank you for your contribution! Sashiko AI review found 3 potential issue(s) to consider: - [High] The `blink_set_callback` creates multiple mutable references (`&mut usize`) to the same shared…
Thank you for your contribution! Sashiko AI review found 3 potential issue(s) to consider:
- [High] The blink_set_callback creates multiple mutable references (&mut usize) to the same shared memory concurrently, violating Rust's strict aliasing rules.
- [High] The DeviceBuilder::build method erases the lifetime of the name string, allowing the led_classdev.name pointer to outlive the string and causing a Use-After-Free.
- [High] Unsound FwNode reference count management in Device::drop retrieves the fwnode directly from the mutable C structure, leading to refcount underflow and Use-After-Free. --
commit d59e3e50bab36d2a8936041aa09ed5823876969f
Author: Markus Probst <[email protected]>
rust: leds: add basic led classdev abstractions
Implement the core abstractions needed for led class devices, including LedOps, DeviceBuilder, and Device.
Quoted 5 lines
rust/kernel/led/normal.rs new file +0
-0
[ ... ]
rust/kernel/led/normal.rs line 27
Quoted 7 lines
rust/kernel/led/normal.rs new file +7
-0+impl <'a,S :DeviceBuilderState >DeviceBuilder <'a,S > { +/// Registers a new [`Device`]. +pub fn build <'bound: 'a,T :LedOps + 'bound>( + self, + parent: &'boundT ::Bus , + ops:impl PinInit <T ,Error > + 'a, + ) ->impl PinInit <Device <'bound,T >,Error > + 'a {
[Severity: High]
Is the lifetime bound <'bound: 'a> backwards here?
By specifying 'bound: 'a, the returned Device ('bound) is explicitly permitted to outlive the builder's string lifetime ('a).
Because the raw pointer to this string is written directly into the led_classdev.name field, a driver could initialize a Device with a temporary string, which drops the string while leaving led_cdev->name dangling. Can this lead to a use-after-free?
[ ... ]
Quoted 12 lines
rust/kernel/led/normal.rs new file +12
-0+unsafe extern "C" fn blink_set_callback ( + led_cdev: *mut bindings::led_classdev , + delay_on: *mut usize , + delay_off: *mut usize , + ) ->i32 { +from_result (|| { +// SAFETY: The function's contract guarantees that `led_cdev` is a valid pointer to a +// `led_classdev` embedded within a `led::Device`. +let classdev =unsafe {Device ::<T >::from_raw (led_cdev) }; +// SAFETY: `classdev.parent()` is guaranteed to be contained in `T::Bus`. +let parent =unsafe {T ::Bus ::from_device (classdev.parent ()) }; +
rust/kernel/led/normal.rs line 206
Quoted 10 lines
rust/kernel/led/normal.rs new file +10
-0+ classdev.ops.blink_set ( + parent, + classdev, +// SAFETY: The function's contract guarantees that `delay_on` points to a `usize` +// and is exclusive for the period of this function. +unsafe { &mut *delay_on }, +// SAFETY: The function's contract guarantees that `delay_off` points to a `usize` +// and is exclusive for the period of this function. +unsafe { &mut *delay_off }, + )?;
[Severity: High]
Could this lead to a strict aliasing violation by creating multiple mutable references to the same shared memory concurrently?
In the C LED subsystem, sysfs write operations to delay_on and delay_off can invoke led_blink_set() concurrently across different threads without holding locks on the device.
This passes pointers to the shared led_cdev->blink_delay_on and led_cdev->blink_delay_off fields directly into the blink_set callback. By unconditionally casting these raw C pointers to &mut usize in Rust, the callback can create overlapping mutable references to the exact same memory locations.
[ ... ]
rust/kernel/led/normal.rs line 224
Quoted 13 lines
rust/kernel/led/normal.rs new file +13
-0+#[pinned_drop] +impl <'bound,T :LedOps + 'bound>PinnedDrop for Device <'bound,T > { +fn drop (self:Pin <&mut Self >) { +let raw = self.classdev.get (); +// SAFETY: The existence of `self` guarantees that `self.classdev.get()` is a pointer to a +// valid `led_classdev`. +let dev: &device::Device =unsafe { device::Device ::from_raw ((*raw).dev) }; + +let _fwnode = dev + .fwnode () +// SAFETY: the reference count of `fwnode` has previously been +// incremented in `led::DeviceBuilder::build`. + .map (|fwnode|unsafe {ARef ::from_raw (NonNull ::from (fwnode)) });
[Severity: High]
Does this unsoundly steal a reference count from the C field dev->fwnode?
In DeviceBuilder::build, self.fwnode is passed to C and its refcount is leaked via core::mem::forget. However, if self.fwnode was initially None, no reference count is leaked.
If dev->fwnode is subsequently populated by external C code, this PinnedDrop implementation blindly constructs an ARef and drops it. Since Rust never incremented this refcount, could this result in an underflow and an eventual use-after-free of the FwNode?
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
Alice Ryhl
reviewerRe: [PATCH v21 1/3] rust: leds: add basic led classdev abstractions
In reply to Markus ProbstQuoted 60 lines · Markus Probst
Implement the core abstractions needed for led class devices, including:
*
led::LedOps- the trait for handling leds, includingbrightness_set,brightness_getandblink_set*
led::DeviceBuilder- the builder for the led class device*
led::Device- a safe wrapper aroundled_classdevSigned-off-by Markus Probst <[email protected]>--- MAINTAINERS | 8 ++ rust/kernel/led.rs | 288 ++++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/led/normal.rs | 230 ++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 4 files changed, 527 insertions(+)MAINTAINERS +8
-0@@ -14662,6 +14662,14 @@ F: drivers/leds/ F: include/dt-bindings/leds/ F: include/linux/leds.h +LED SUBSYSTEM [RUST] +M: Markus Probst <[email protected]> +L: [email protected] +L: [email protected] +S: Maintained +F: rust/kernel/led.rs +F: rust/kernel/led/ + LEGO MINDSTORMS EV3 R: David Lechner <[email protected]> S: Maintainedrust/kernel/led.rs new file +18
-0@@ -0,0 +1,288 @@ +// 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, + ptr::NonNull ,// +}; + +use crate ::{ + container_of, + device::{ + self, + property::FwNode , +AsBusDevice ,
rust/kernel/led.rs line 28
Quoted 10 lines
rust/kernel/led.rs new file +10
-0+ Bound, // + }, + error::{ + from_result, + to_result, + VTABLE_DEFAULT_ERROR, // + }, + macros::vtable, + prelude::*, + str::CStrExt,
CStrExt is in the prelude. Please check for unnecessary imports.
Quoted 23 lines
rust/kernel/led/normal.rs new file +17
-0@@ -0,0 +1,230 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Led mode for the `struct led_classdev`. +//! +//! C header: [`include/linux/leds.h`](srctree/include/linux/leds.h) + +use super ::*; + +/// The led class device representation. +/// +/// This structure represents the Rust abstraction for a led class device. +#[pin_data( PinnedDrop )] +pub struct Device <'bound,T :LedOps + 'bound> { +#[pin] + ops:T , +#[pin] + classdev:Opaque <bindings::led_classdev >,
rust/kernel/led/normal.rs line 27
Quoted 10 lines
rust/kernel/led/normal.rs new file +10
-0+ _p: PhantomData<&'bound ()>, +} + +impl <'a,S :DeviceBuilderState >DeviceBuilder <'a,S > { +/// Registers a new [`Device`]. +pub fn build <'bound: 'a,T :LedOps + 'bound>( + self, + parent: &'boundT ::Bus , + ops:impl PinInit <T ,Error > + 'a, + ) ->impl PinInit <Device <'bound,T >,Error > + 'a {
I think it would be useful to separate out the two lifetimes more clearly. You have two sets of lifetimes:
* 'bound which is the duration in which the bus device is bound.
* 'a which is the duration in which the name/devicename fields are valid.
And these have different constraints because 'bound is much larger than 'a. The 'bound lifetime is longer than the entire Device struct, but the 'a lifetime only needs to last for the duration of the initialization because (I assume) the strings are copied by led_classdev_register_ext
So under that logic, I would rename 'a to 'name or something like that to indicate what it's the lifetime of.
Note that if I'm wrong about the lifetime of the name strings, then this code should be changed accordingly. It looks like you're actually stashing the pointers in the led_classdev, and if that outlives this initializer, then the current lifetimes are wrong, and Device must also be annotated with 'name to indicate this additional lifetime.
Quoted 51 lines
rust/kernel/led/normal.rs new file +51
-0+const_assert! (T ::MAX_BRIGHTNESS <=i32 ::MAX .unsigned_abs () || !T ::HAS_BRIGHTNESS_GET ); + + try_pin_init!(Device { + ops <- ops, + classdev <- Opaque::try_ffi_init(|ptr: *mut bindings::led_classdev| { + // SAFETY: `try_ffi_init` guarantees that `ptr` is valid for write. + // `led_classdev` gets fully initialized in-place by + // `led_classdev_register_ext` including `mutex` and `list_head`. + unsafe { + ptr.write(bindings::led_classdev { + brightness_set: (!T::BLOCKING) + .then_some(Adapter::<T>::brightness_set_callback), + brightness_set_blocking: T::BLOCKING + .then_some(Adapter::<T>::brightness_set_blocking_callback), + brightness_get: T::HAS_BRIGHTNESS_GET + .then_some(Adapter::<T>::brightness_get_callback), + blink_set: T::HAS_BLINK_SET.then_some(Adapter::<T>::blink_set_callback), + max_brightness: T::MAX_BRIGHTNESS, + brightness: self.initial_brightness, + color: self.color as u32, + name: self.name.map_or(core::ptr::null(), CStrExt::as_char_ptr), + ..bindings::led_classdev::default() + }) + }; + + let mut init_data = bindings::led_init_data { + fwnode: self + .fwnode + .as_ref() + .map_or(core::ptr::null_mut(), |fwnode| fwnode.as_raw()), + default_label: core::ptr::null(), + devicename: self + .devicename + .map_or(core::ptr::null(), CStrExt::as_char_ptr), + devname_mandatory: self.devname_mandatory, + }; + + // SAFETY: + // - `parent.as_ref().as_raw()` is guaranteed to be a pointer to a valid + // `device`. + // - `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, + if self.name.is_none() { + &raw mut init_data + } else { + core::ptr::null_mut() + }, + )
rust/kernel/led/normal.rs line 88
Quoted 10 lines
rust/kernel/led/normal.rs new file +10
-0+ })?; + + core::mem::forget (self.fwnode);// keep the reference count incremented + +Ok ::<_ ,Error >(()) + }), + _p: PhantomData, + }) + } +}
Alice
Re: [PATCH v21 1/3] rust: leds: add basic led classdev abstractions
Quoted 65 lines · Alice Ryhl
Quoted 64 lines · Markus Probst
Implement the core abstractions needed for led class devices, including:
*
led::LedOps- the trait for handling leds, includingbrightness_set,brightness_getandblink_set*
led::DeviceBuilder- the builder for the led class device*
led::Device- a safe wrapper aroundled_classdevSigned-off-by Markus Probst <[email protected]>--- MAINTAINERS | 8 ++ rust/kernel/led.rs | 288 ++++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/led/normal.rs | 230 ++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 4 files changed, 527 insertions(+)MAINTAINERS +8
-0@@ -14662,6 +14662,14 @@ F: drivers/leds/ F: include/dt-bindings/leds/ F: include/linux/leds.h +LED SUBSYSTEM [RUST] +M: Markus Probst <[email protected]> +L: [email protected] +L: [email protected] +S: Maintained +F: rust/kernel/led.rs +F: rust/kernel/led/ + LEGO MINDSTORMS EV3 R: David Lechner <[email protected]> S: Maintainedrust/kernel/led.rs new file +22
-0@@ -0,0 +1,288 @@ +// 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, + ptr::NonNull ,// +}; + +use crate ::{ + container_of, + device::{ + self, + property::FwNode , +AsBusDevice , +Bound ,// + }, + error::{ + from_result,
Quoted 8 lines
rust/kernel/led.rs line 28
Quoted 6 lines
rust/kernel/led.rs new file +6
-0+ to_result, + VTABLE_DEFAULT_ERROR, // + }, + macros::vtable, + prelude::*, + str::CStrExt,CStrExt is in the prelude. Please check for unnecessary imports.
There is ause super::*; in rust/kernel/led/normal.rs and rust/kernel/led/multicolor.rs, which both make use of CStrExt. The latter being in patch 3.
Quoted 42 lines
Quoted 24 lines
rust/kernel/led/normal.rs new file +17
-0@@ -0,0 +1,230 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Led mode for the `struct led_classdev`. +//! +//! C header: [`include/linux/leds.h`](srctree/include/linux/leds.h) + +use super ::*; + +/// The led class device representation. +/// +/// This structure represents the Rust abstraction for a led class device. +#[pin_data( PinnedDrop )] +pub struct Device <'bound,T :LedOps + 'bound> { +#[pin] + ops:T , +#[pin] + classdev:Opaque <bindings::led_classdev >,rust/kernel/led/normal.rs line 27
Quoted 10 lines
rust/kernel/led/normal.rs new file +10
-0+ _p: PhantomData<&'bound ()>, +} + +impl <'a,S :DeviceBuilderState >DeviceBuilder <'a,S > { +/// Registers a new [`Device`]. +pub fn build <'bound: 'a,T :LedOps + 'bound>( + self, + parent: &'boundT ::Bus , + ops:impl PinInit <T ,Error > + 'a, + ) ->impl PinInit <Device <'bound,T >,Error > + 'a {I think it would be useful to separate out the two lifetimes more clearly. You have two sets of lifetimes:
* 'bound which is the duration in which the bus device is bound.
* 'a which is the duration in which thename/devicenamefields are valid.
Quoted 7 lines
And these have different constraints because 'bound is much larger than 'a. The 'bound lifetime is longer than the entire Device struct, but the 'a lifetime only needs to last for the duration of the initialization because (I assume) the strings are copied by
led_classdev_register_extSo under that logic, I would rename 'a to 'name or something like that to indicate what it's the lifetime of.
Preferably 'init, which can be used in other class device abstractions as well if needed.
Quoted 6 lines
Note that if I'm wrong about the lifetime of the name strings, then this code should be changed accordingly. It looks like you're actually stashing the pointers in the
led_classdev, and if that outlives this initializer, then the current lifetimes are wrong, and Device must also be annotated with 'name to indicate this additional lifetime.
name and devicename only need to be valid for the duration of led_classdev_register_ext.
Quoted 54 lines
Quoted 54 lines
rust/kernel/led/normal.rs new file +53
-0+const_assert! (T ::MAX_BRIGHTNESS <=i32 ::MAX .unsigned_abs () || !T ::HAS_BRIGHTNESS_GET ); + +try_pin_init! (Device { + ops <- ops, + classdev <-Opaque ::try_ffi_init(|ptr: *mut bindings::led_classdev | { +// SAFETY: `try_ffi_init` guarantees that `ptr` is valid for write. +// `led_classdev` gets fully initialized in-place by +// `led_classdev_register_ext` including `mutex` and `list_head`. +unsafe { + ptr.write (bindings::led_classdev { + brightness_set: (!T ::BLOCKING ) + .then_some (Adapter ::<T >::brightness_set_callback), + brightness_set_blocking:T ::BLOCKING + .then_some (Adapter ::<T >::brightness_set_blocking_callback), + brightness_get:T ::HAS_BRIGHTNESS_GET + .then_some (Adapter ::<T >::brightness_get_callback), + blink_set:T ::HAS_BLINK_SET .then_some (Adapter ::<T >::blink_set_callback), + max_brightness:T ::MAX_BRIGHTNESS , + brightness: self.initial_brightness, + color: self.coloras u32 , + name: self.name.map_or (core::ptr::null (),CStrExt ::as_char_ptr), + ..bindings::led_classdev::default () + }) + }; + +let mut init_data = bindings::led_init_data { + fwnode: self + .fwnode + .as_ref () + .map_or (core::ptr::null_mut (), |fwnode| fwnode.as_raw ()), + default_label: core::ptr::null (), + devicename: self + .devicename + .map_or (core::ptr::null (),CStrExt ::as_char_ptr), + devname_mandatory: self.devname_mandatory, + }; + +// SAFETY: +// - `parent.as_ref().as_raw()` is guaranteed to be a pointer to a valid +// `device`. +// - `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, +if self.name.is_none () { + &raw mut init_data + }else { + core::ptr::null_mut () + }, + ) + })?; +
Quoted 8 lines
rust/kernel/led/normal.rs line 88
Quoted 8 lines
rust/kernel/led/normal.rs new file +8
-0+ core::mem::forget (self.fwnode);// keep the reference count incremented + +Ok ::<_ ,Error >(()) + }), + _p: PhantomData, + }) + } +}
Thanks
- Markus Probst
Quoted 2 lines
Alice
Alice Ryhl
reviewerRe: [PATCH v21 1/3] rust: leds: add basic led classdev abstractions
Quoted 74 lines · Markus Probst
Quoted 65 lines · Alice Ryhl
Quoted 64 lines · Markus Probst
Implement the core abstractions needed for led class devices, including:
*
led::LedOps- the trait for handling leds, includingbrightness_set,brightness_getandblink_set*
led::DeviceBuilder- the builder for the led class device*
led::Device- a safe wrapper aroundled_classdevSigned-off-by Markus Probst <[email protected]>--- MAINTAINERS | 8 ++ rust/kernel/led.rs | 288 ++++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/led/normal.rs | 230 ++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 4 files changed, 527 insertions(+)MAINTAINERS +8
-0@@ -14662,6 +14662,14 @@ F: drivers/leds/ F: include/dt-bindings/leds/ F: include/linux/leds.h +LED SUBSYSTEM [RUST] +M: Markus Probst <[email protected]> +L: [email protected] +L: [email protected] +S: Maintained +F: rust/kernel/led.rs +F: rust/kernel/led/ + LEGO MINDSTORMS EV3 R: David Lechner <[email protected]> S: Maintainedrust/kernel/led.rs new file +22
-0@@ -0,0 +1,288 @@ +// 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, + ptr::NonNull ,// +}; + +use crate ::{ + container_of, + device::{ + self, + property::FwNode , +AsBusDevice , +Bound ,// + }, + error::{ + from_result,Quoted 8 lines
rust/kernel/led.rs line 28
Quoted 6 lines
rust/kernel/led.rs new file +6
-0+ to_result, + VTABLE_DEFAULT_ERROR, // + }, + macros::vtable, + prelude::*, + str::CStrExt,CStrExt is in the prelude. Please check for unnecessary imports.
Quoted 4 lines
There is a
use super::*;inrust/kernel/led/normal.rsandrust/kernel/led/multicolor.rs, which both make use of CStrExt. The latter being in patch 3.
I understand that you are using it. However, it's still unnecessary because you also imported prelude::*.
Quoted 46 lines
Quoted 46 lines
Quoted 23 lines
rust/kernel/led/normal.rs new file +17
-0@@ -0,0 +1,230 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Led mode for the `struct led_classdev`. +//! +//! C header: [`include/linux/leds.h`](srctree/include/linux/leds.h) + +use super ::*; + +/// The led class device representation. +/// +/// This structure represents the Rust abstraction for a led class device. +#[pin_data( PinnedDrop )] +pub struct Device <'bound,T :LedOps + 'bound> { +#[pin] + ops:T , +#[pin] + classdev:Opaque <bindings::led_classdev >,rust/kernel/led/normal.rs line 27
Quoted 10 lines
rust/kernel/led/normal.rs new file +10
-0+ _p: PhantomData<&'bound ()>, +} + +impl <'a,S :DeviceBuilderState >DeviceBuilder <'a,S > { +/// Registers a new [`Device`]. +pub fn build <'bound: 'a,T :LedOps + 'bound>( + self, + parent: &'boundT ::Bus , + ops:impl PinInit <T ,Error > + 'a, + ) ->impl PinInit <Device <'bound,T >,Error > + 'a {I think it would be useful to separate out the two lifetimes more clearly. You have two sets of lifetimes:
* 'bound which is the duration in which the bus device is bound.
* 'a which is the duration in which thename/devicenamefields are valid.And these have different constraints because 'bound is much larger than 'a. The 'bound lifetime is longer than the entire Device struct, but the 'a lifetime only needs to last for the duration of the initialization because (I assume) the strings are copied by
led_classdev_register_ext
Quoted 4 lines
Quoted 2 lines
So under that logic, I would rename 'a to 'name or something like that to indicate what it's the lifetime of.
Preferably 'init, which can be used in other class device abstractions as well if needed.
Sounds good.
Quoted 8 lines
Quoted 6 lines
Note that if I'm wrong about the lifetime of the name strings, then this code should be changed accordingly. It looks like you're actually stashing the pointers in the
led_classdev, and if that outlives this initializer, then the current lifetimes are wrong, and Device must also be annotated with 'name to indicate this additional lifetime.name and devicename only need to be valid for the duration of
led_classdev_register_ext.
Great.
Alice
Gary Guo
reviewerRe: [PATCH v21 1/3] rust: leds: add basic led classdev abstractions
In reply to Alice RyhlQuoted 120 lines · Alice Ryhl
Quoted 60 lines · Markus Probst
Implement the core abstractions needed for led class devices, including:
*
led::LedOps- the trait for handling leds, includingbrightness_set,brightness_getandblink_set*
led::DeviceBuilder- the builder for the led class device*
led::Device- a safe wrapper aroundled_classdevSigned-off-by Markus Probst <[email protected]>--- MAINTAINERS | 8 ++ rust/kernel/led.rs | 288 ++++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/led/normal.rs | 230 ++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 4 files changed, 527 insertions(+)MAINTAINERS +8
-0@@ -14662,6 +14662,14 @@ F: drivers/leds/ F: include/dt-bindings/leds/ F: include/linux/leds.h +LED SUBSYSTEM [RUST] +M: Markus Probst <[email protected]> +L: [email protected] +L: [email protected] +S: Maintained +F: rust/kernel/led.rs +F: rust/kernel/led/ + LEGO MINDSTORMS EV3 R: David Lechner <[email protected]> S: Maintainedrust/kernel/led.rs new file +18
-0@@ -0,0 +1,288 @@ +// 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, + ptr::NonNull ,// +}; + +use crate ::{ + container_of, + device::{ + self, + property::FwNode , +AsBusDevice ,rust/kernel/led.rs line 28
Quoted 10 lines
rust/kernel/led.rs new file +10
-0+ Bound, // + }, + error::{ + from_result, + to_result, + VTABLE_DEFAULT_ERROR, // + }, + macros::vtable, + prelude::*, + str::CStrExt,CStrExt is in the prelude. Please check for unnecessary imports.
Quoted 23 lines
rust/kernel/led/normal.rs new file +17
-0@@ -0,0 +1,230 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Led mode for the `struct led_classdev`. +//! +//! C header: [`include/linux/leds.h`](srctree/include/linux/leds.h) + +use super ::*; + +/// The led class device representation. +/// +/// This structure represents the Rust abstraction for a led class device. +#[pin_data( PinnedDrop )] +pub struct Device <'bound,T :LedOps + 'bound> { +#[pin] + ops:T , +#[pin] + classdev:Opaque <bindings::led_classdev >,rust/kernel/led/normal.rs line 27
Quoted 10 lines
rust/kernel/led/normal.rs new file +10
-0+ _p: PhantomData<&'bound ()>, +} + +impl <'a,S :DeviceBuilderState >DeviceBuilder <'a,S > { +/// Registers a new [`Device`]. +pub fn build <'bound: 'a,T :LedOps + 'bound>( + self, + parent: &'boundT ::Bus , + ops:impl PinInit <T ,Error > + 'a, + ) ->impl PinInit <Device <'bound,T >,Error > + 'a {I think it would be useful to separate out the two lifetimes more clearly. You have two sets of lifetimes:
* 'bound which is the duration in which the bus device is bound.
* 'a which is the duration in which thename/devicenamefields are valid.And these have different constraints because 'bound is much larger than 'a. The 'bound lifetime is longer than the entire Device struct, but the 'a lifetime only needs to last for the duration of the initialization because (I assume) the strings are copied by
led_classdev_register_ext
Quoted 8 lines
So under that logic, I would rename 'a to 'name or something like that to indicate what it's the lifetime of.
Note that if I'm wrong about the lifetime of the name strings, then this code should be changed accordingly. It looks like you're actually stashing the pointers in the
led_classdev, and if that outlives this initializer, then the current lifetimes are wrong, and Device must also be annotated with 'name to indicate this additional lifetime.
The lifetime here would probably be better named 'init.
It's the same case for async desugaring, where the lifetime is to capture everything used in the initializer.
Best,
Gary
PATCH v21 2/3 rust: leds: add Mode trait
In reply to Markus ProbstAdd the led::Mode trait to allow for other types of led class devices in led::LedOps.
--- rust/kernel/led.rs | 27 +++++++++++++++++++++++---- rust/kernel/led/normal.rs | 22 +++++++++++++++------- 2 files changed, 38 insertions(+), 11 deletions(-)
rust/kernel/led.rs +23 -4
@@ -32,7 +32,10 @@mod normal; -pub use normal::Device ; +pub use normal::{ +Device , +Normal ,// +};/// The name of the led is determined by the driver. pub enum Named {}
@@ -161,6 +164,7 @@ pub fn name(self, name: &'a CStr) -> Self {/// #[vtable] /// impl led::LedOps for MyLedOps { /// type Bus = platform::Device<device::Bound>; +/// type Mode = led::Normal; /// const BLOCKING: bool = false; /// const MAX_BRIGHTNESS: u32 = 255; ///
@@ -182,6 +186,11 @@ pub trait LedOps: Send + Sync + Sized {#[allow(private_bounds)] type Bus :AsBusDevice <Bound >; +/// The led mode to use. +/// +/// See [`Mode`]. +type Mode :Mode ; +/// If set true, [`LedOps::brightness_set`] and [`LedOps::blink_set`] must perform the /// operation immediately. If set false, they must not sleep. const BLOCKING :bool ;
@@ -194,7 +203,7 @@ pub trait LedOps: Send + Sync + Sized {fn brightness_set <'bound>( &self, dev: &'boundSelf ::Bus , - classdev: &Device <'bound,Self >, + classdev: &<Self ::Mode as Mode >::Device <'bound,Self >, brightness:u32 , ) ->Result <()>;
@@ -202,7 +211,7 @@ fn brightness_set<'bound>(fn brightness_get <'bound>( &self, dev: &'boundSelf ::Bus , - classdev: &Device <'bound,Self >, + classdev: &<Self ::Mode as Mode >::Device <'bound,Self >, ) ->Result <u32 > {let _ = (dev, classdev);build_error! (VTABLE_DEFAULT_ERROR )
@@ -219,7 +228,7 @@ fn brightness_get<'bound>(fn blink_set <'bound>( &self, dev: &'boundSelf ::Bus , - classdev: &Device <'bound,Self >, + classdev: &<Self ::Mode as Mode >::Device <'bound,Self >, delay_on: &mut usize , delay_off: &mut usize , ) ->Result <()> {
@@ -283,6 +292,16 @@ fn try_from(value: u32) -> core::result::Result<Self, Self::Error> { } } +/// The led mode. +/// +/// Each led mode has its own led class device type with different capabilities. +/// +/// See [`Normal`]. +pub trait Mode : private::Sealed { +/// The class device for the led mode. +type Device <'bound,T :LedOps <Mode =Self > + 'bound>; +} +mod private {pub trait Sealed {} }
rust/kernel/led/normal.rs +15 -7
@@ -6,11 +6,19 @@use super ::*; +/// The led mode for the `struct led_classdev`. Leds with this mode can only have a fixed color. +pub enum Normal {} + +impl Mode for Normal { +type Device <'bound,T :LedOps <Mode =Self > + 'bound> =Device <'bound,T >; +} +impl private::Sealed for Normal {} +/// The led class device representation. /// /// This structure represents the Rust abstraction for a led class device. #[pin_data( PinnedDrop )] -pub struct Device <'bound,T :LedOps + 'bound> { +pub struct Device <'bound,T :LedOps <Mode =Normal > + 'bound> {#[pin] ops:T , #[pin]
@@ -20,7 +28,7 @@ pub struct Device<'bound, T: LedOps + 'bound> {impl <'a,S :DeviceBuilderState >DeviceBuilder <'a,S > {/// Registers a new [`Device`]. -pub fn build <'bound: 'a,T :LedOps + 'bound>( +pub fn build <'bound: 'a,T :LedOps <Mode =Normal > + 'bound>( self, parent: &'boundT ::Bus , ops: impl PinInit<T, Error> + 'a,
@@ -87,7 +95,7 @@ pub fn build<'bound: 'a, T: LedOps + 'bound>( } } -impl <'bound,T :LedOps + 'bound>Device <'bound,T > { +impl <'bound,T :LedOps <Mode =Normal > + 'bound>Device <'bound,T > {/// # Safety /// `led_cdev` must be a valid pointer to a `led_classdev` embedded within a /// `led::Device`.
@@ -107,17 +115,17 @@ fn parent(&self) -> &'bound device::Device<Bound> { }// SAFETY: A `led::Device` can be unregistered from any thread. -unsafe impl <'bound,T :LedOps + 'bound +Send >Send for Device <'bound,T > {} +unsafe impl <'bound,T :LedOps <Mode =Normal > + 'bound +Send >Send for Device <'bound,T > {}// SAFETY: `led::Device` can be shared among threads because all methods of `led::Device` // are thread safe. -unsafe impl <'bound,T :LedOps + 'bound +Sync >Sync for Device <'bound,T > {} +unsafe impl <'bound,T :LedOps <Mode =Normal > + 'bound +Sync >Sync for Device <'bound,T > {}struct Adapter <T :LedOps > { _p:PhantomData <T >, } -impl <T :LedOps >Adapter <T > { +impl <T :LedOps <Mode =Normal >>Adapter <T > {/// # Safety /// `led_cdev` must be a valid pointer to a `led_classdev` embedded within a /// `led::Device`.
@@ -210,7 +218,7 @@ impl<T: LedOps> Adapter<T> { }#[pinned_drop] -impl <'bound,T :LedOps + 'bound>PinnedDrop for Device <'bound,T > { +impl <'bound,T :LedOps <Mode =Normal > + 'bound>PinnedDrop for Device <'bound,T > {fn drop (self:Pin <&mut Self >) {let raw = self.classdev.get ();// SAFETY: The existence of `self` guarantees that `self.classdev.get()` is a pointer to a
Signature · 1 line
2.53.0
[email protected]
AI reviewRe: [PATCH v21 2/3] rust: leds: add Mode trait
Sashiko has reviewed this patch and found no issues. It looks great!
Quoted 4 lines
Add the
led::Modetrait to allow for other types of led class devices inled::LedOps.Signed-off-by Markus Probst <[email protected]>
Sashiko has reviewed this patch and found no issues. It looks great!
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=2
PATCH v21 3/3 rust: leds: add multicolor classdev abstractions
In reply to Markus ProbstImplement the abstractions needed for multicolor led class devices, including:
* led::MultiColor - the led mode implementation
* MultiColorSubLed - a safe wrapper arround mc_subled
* led::MultiColorDevice - a safe wrapper around led_classdev_mc
* led::DeviceBuilder::build_multicolor - a function to register a new multicolor led class device
--- rust/bindings/bindings_helper.h | 1 + rust/kernel/led.rs | 34 ++- rust/kernel/led/multicolor.rs | 460 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 494 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
@@ -68,6 +68,7 @@#include <linux/iosys-map.h> #include <linux/jiffies.h> #include <linux/jump_label.h> +#include <linux/led-class-multicolor.h> #include <linux/mdio.h> #include <linux/mm.h> #include <linux/miscdevice.h>
rust/kernel/led.rs +33 -1
@@ -30,8 +30,16 @@ types::Opaque, // }; +#[cfg( CONFIG_LEDS_CLASS_MULTICOLOR )] +mod multicolor;mod normal; +#[cfg( CONFIG_LEDS_CLASS_MULTICOLOR )] +pub use multicolor::{ +MultiColor , +MultiColorDevice , +MultiColorSubLed ,// +};pub use normal::{Device ,Normal ,//
@@ -255,7 +263,24 @@ pub enum Color { Violet = bindings::LED_COLOR_ID_VIOLET, Yellow = bindings::LED_COLOR_ID_YELLOW, Ir = bindings::LED_COLOR_ID_IR, +#[cfg_attr( +CONFIG_LEDS_CLASS_MULTICOLOR , +doc = "Use this color for a [`MultiColor`] led." +)] +#[cfg_attr( +not( CONFIG_LEDS_CLASS_MULTICOLOR ), +doc = "Use this color for a `MultiColor` led." +)] +/// If the led supports RGB, use [`Color::Rgb`] instead. Multi = bindings::LED_COLOR_ID_MULTI, +#[cfg_attr( +CONFIG_LEDS_CLASS_MULTICOLOR , +doc = "Use this color for a [`MultiColor`] led with rgb support." +)] +#[cfg_attr( +not( CONFIG_LEDS_CLASS_MULTICOLOR ), +doc = "Use this color for a `MultiColor` led with rgb support." +)] Rgb = bindings::LED_COLOR_ID_RGB, Purple = bindings::LED_COLOR_ID_PURPLE, Orange = bindings::LED_COLOR_ID_ORANGE,
@@ -296,7 +321,14 @@ fn try_from(value: u32) -> core::result::Result<Self, Self::Error> {/// /// Each led mode has its own led class device type with different capabilities. /// -/// See [`Normal`]. +#[cfg_attr( +CONFIG_LEDS_CLASS_MULTICOLOR , +doc = "See [`Normal`] and [`MultiColor`]." +)] +#[cfg_attr( +not( CONFIG_LEDS_CLASS_MULTICOLOR ), +doc = "See [`Normal`] and `MultiColor`." +)] pub trait Mode : private::Sealed {/// The class device for the led mode. type Device <'bound,T :LedOps <Mode =Self > + 'bound>;
rust/kernel/led/multicolor.rs new file +460 -0
460 lines not on this page · raw message
Signature · 1 line
2.53.0
[email protected]
AI reviewRe: [PATCH v21 3/3] rust: leds: add multicolor classdev abstractions
Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider: - [High] Unsynchronized reads of concurrently modified `intensity` and `brightness` fields in…
Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [High] Unsynchronized reads of concurrently modified intensity and brightness fields in MultiColorSubLed cause a data race and Undefined Behavior in safe Rust.
- [High] Flawed fwnode reference counting ownership in MultiColorDevice leads to potential Use-After-Free or memory leak.
--
commit 53cb84fc2ecc8ded772da6376e83ccc60f89c50f
Author: Markus Probst <[email protected]>
rust: leds: add multicolor classdev abstractions
Implement the abstractions needed for multicolor led class devices.
Quoted 6 lines
rust/kernel/led/multicolor.rs new file +0
-0@@ -0,0 +1,460 @@
[ ... ]
rust/kernel/led/multicolor.rs line 142
Quoted 8 lines
rust/kernel/led/multicolor.rs new file +8
-0+/// The intensity of the sub led. +#[inline] +pub const fn intensity (&self) ->u32 { +// SAFETY: +// - `self.intensity.get()` is a valid pointer to `u32`. +// - We don't have exclusive or immutable access to `self.intensity`, +// but the alignment should prevent "load tearing". +unsafe { *self.intensity.get () }
[Severity: High]
Does this unsynchronized raw pointer read risk causing a data race and Undefined Behavior in safe Rust?
The C multicolor LED core modifies subled_info[i].intensity and brightness concurrently when a user writes to sysfs attributes. Meanwhile, this safe Rust getter method performs an unsynchronized raw pointer read. Since MultiColorDevice implements Sync, multiple threads can share MultiColorSubLed and read these fields at any time.
Should this use core::ptr::read_volatile to ensure soundness?
rust/kernel/led/multicolor.rs line 152
Quoted 10 lines
rust/kernel/led/multicolor.rs new file +10
-0+ } + +/// The brightness of the sub led. +#[inline] +pub const fn brightness (&self) ->u32 { +// SAFETY: +// - `self.brightness.get()` is a valid pointer to `u32`. +// - We don't have exclusive or immutable access to `self.brightness`, +// but the alignment should prevent "load tearing". +unsafe { *self.brightness.get () }
[Severity: High]
Similarly, does this unsynchronized read of brightness risk causing a data race when the C side modifies it concurrently?
Should core::ptr::read_volatile be used here as well?
[ ... ]
Quoted 5 lines
rust/kernel/led/multicolor.rs new file +5
-0+ to_result(unsafe { + bindings::led_classdev_multicolor_register_ext( + parent.as_ref().as_raw(), + ptr, + if self.name.is_none() {
rust/kernel/led/multicolor.rs line 258
Quoted 10 lines
rust/kernel/led/multicolor.rs new file +10
-0+ &raw mut init_data + }else { + core::ptr::null_mut () + }, + ) + })?; + + subled_guard.dismiss (); + + core::mem::forget (self.fwnode);// keep the reference count incremented
[Severity: High]
Does leaking the fwnode reference count to the C subsystem and then trying to reclaim it in drop() by reading dev.fwnode() risk a Use-After-Free?
If the kernel (e.g. ACPI) assigns a different fwnode to the device after registration, dev.fwnode() will return this new fwnode. The drop() implementation below would then incorrectly take ownership of the new fwnode's reference count and drop it, while permanently leaking the originally passed fwnode.
Should MultiColorDevice store Option<ARef<FwNode>> locally to ensure it only manages the exact reference it uniquely owns?
Quoted 5 lines
rust/kernel/led/multicolor.rs new file +5
-0+ +Ok ::<_ ,Error >(()) + }), + _p: PhantomData, + })
[ ... ]
rust/kernel/led/multicolor.rs line 438
Quoted 13 lines
rust/kernel/led/multicolor.rs new file +13
-0+#[pinned_drop] +impl <'bound,T :LedOps <Mode =MultiColor > + 'bound>PinnedDrop for MultiColorDevice <'bound,T > { +fn drop (self:Pin <&mut Self >) { +let raw = self.classdev.get (); +// SAFETY: The existence of `self` guarantees that `self.classdev.get()` is a pointer to a +// valid `led_classdev_mc`. +let dev: &device::Device =unsafe { device::Device ::from_raw ((*raw).led_cdev.dev) }; + +let _fwnode = dev + .fwnode () +// SAFETY: the reference count of `fwnode` has previously been +// incremented in `led::DeviceBuilder::build_multicolor`. + .map (|fwnode|unsafe {ARef ::from_raw (NonNull ::from (fwnode)) });
[Severity: High]
Is it safe to unconditionally reconstruct an ARef from dev.fwnode() here?
As mentioned above, if dev.fwnode() returns a different fwnode than the one originally passed to build_multicolor, this will drop a reference it does not own, potentially leading to a Use-After-Free, while the originally leaked reference remains un-dropped.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=3