rust: LED abstractions
cover rust: LED abstractions
This RFC implements a basic LED abstraction to show how this would work with rust.
Currently this just implements a sample driver, to show how to use the abstraction, which just prints the requested state, supporting a on/off LED and an led with brightness level up to 255 and hardware blinking. I intend to write a hardware specific driver for submitting.
The abstractions is a generic struct that holds a generic driver data on which the vtable is implemented. Because this struct also holds the c led_classdev (include/linux/leds.h) struct this struct is pinned and is using pin_init to create and directly register the LED. Dropping the struct unregisteres the LED. I plan to also add devm functions later, but as device abstractions in rust are not yet that far I opted agains that for the first iteration of the LED abstractions.
This is currently using core::time::Duration for the blinking interval, but will likely change that to use the Delta time type from FUJITA Tomonori [1].
This is requiring the Opaque::try_ffi_init patch by Alice Ryhl[2] which just got merged into char-misc-testing.
[1]: https://lore.kernel.org/rust-for-linux/[email protected]/
[2]: https://lore.kernel.org/rust-for-linux/[email protected]/
Fiona Behrens (2):
rust: LED abstraction
samples: rust: led sample
rust/kernel/leds.rs | 399 +++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + samples/rust/Kconfig | 10 + samples/rust/Makefile | 1 + samples/rust/rust_led.rs | 103 ++++++++++ 5 files changed, 515 insertions(+) create mode 100644 rust/kernel/leds.rs create mode 100644 samples/rust/rust_led.rs
Signature · 1 line
2.46.0
RFC PATCH 1/2 rust: LED abstraction
Add abstractions for a simple LED, supporting Single color LED and hardware accelerated blinking.
This is implemented using a pinned Led struct which holds driver data and the C led_classdev struct. The driver data then implements a vtable which currently provides brightness_set, brightness_get and blink_set. This LED is then registered with the LED core and unregistered when it is dropped.
--- rust/kernel/leds.rs | 399 ++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + 2 files changed, 401 insertions(+) create mode 100644 rust/kernel/leds.rs
rust/kernel/leds.rs new file +399 -0
@@ -0,0 +1,399 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! LED subsystem abstractions. +//! +//! C header: [`includes/linux/leds.h`](srctree/include/linux/leds.h) + +use core::ffi::c_ulong; +use core::num::NonZeroU8 ; +use core::ptr; +use core::time::Duration ; + +use crate ::device::Device ; +use crate ::{error::from_result, init::PinInit , prelude::*, types::Opaque }; + +/// Color of an LED. +#[derive( Copy , Clone )] +pub enum Color { +/// White +White , +/// Red +Red , +/// Green +Green , +/// Blue +Blue , +/// Amber +Amber , +/// Violet +Violet , +/// Yellow +Yellow , +/// Purple +Purple , +/// Orange +Orange , +/// Pink +Pink , +/// Cyan +Cyan , +/// Lime +Lime , + +/// Infrared +IR , +/// Multicolor LEDs +Multi , +/// Multicolor LEDs that can do arbitrary color, +/// so this would include `RGBW` and similar +RGB , +} + +impl Color { +/// Get String representation of the Color. +pub fn name_cstr (&self) ->Option <&'staticCStr > { +// SAFETY: C function call, enum is valid argument. +let name =unsafe { bindings::led_get_color_name (u32::from (self)as u8 ) }; +if name.is_null () { +return None ; + } +// SAFETY: pointer from above, valid for static lifetime. +Some (unsafe {CStr ::from_char_ptr (name) }) + } + +/// Get String representation of the Color. +#[inline] +pub fn name (&self) ->Option <&'staticstr > { +// SAFETY: name from C name array which is valid UTF-8. + self.name_cstr () + .map (|name|unsafe { name.as_str_unchecked () }) + } +} + +impl core::fmt::Display for Color { +fn fmt (&self, f: &mut core::fmt::Formatter <'_>) -> core::fmt::Result { + f.write_str (self.name ().unwrap_or ("Invalid color" )) + } +} + +impl From <Color >for u32 { +fn from (color:Color ) ->Self { +match color { +Color ::White => bindings::LED_COLOR_ID_WHITE , +Color ::Red => bindings::LED_COLOR_ID_RED , +Color ::Green => bindings::LED_COLOR_ID_GREEN , +Color ::Blue => bindings::LED_COLOR_ID_BLUE , +Color ::Amber => bindings::LED_COLOR_ID_AMBER , +Color ::Violet => bindings::LED_COLOR_ID_VIOLET , +Color ::Yellow => bindings::LED_COLOR_ID_YELLOW , +Color ::Purple => bindings::LED_COLOR_ID_PURPLE , +Color ::Orange => bindings::LED_COLOR_ID_ORANGE , +Color ::Pink => bindings::LED_COLOR_ID_PINK , +Color ::Cyan => bindings::LED_COLOR_ID_CYAN , +Color ::Lime => bindings::LED_COLOR_ID_LIME , +Color ::IR => bindings::LED_COLOR_ID_IR , +Color ::Multi => bindings::LED_COLOR_ID_MULTI , +Color ::RGB => bindings::LED_COLOR_ID_RGB , + } + } +} + +impl From <&Color >for u32 { +fn from (color: &Color ) ->Self { + (*color).into () + } +} + +impl TryFrom <u32 >for Color { +type Error =Error ; + +fn try_from (value:u32 ) ->Result <Self ,Self ::Error > { +Ok (match value { + bindings::LED_COLOR_ID_WHITE =>Color ::White , + bindings::LED_COLOR_ID_RED =>Color ::Red , + bindings::LED_COLOR_ID_GREEN =>Color ::Green , + bindings::LED_COLOR_ID_BLUE =>Color ::Blue , + bindings::LED_COLOR_ID_AMBER =>Color ::Amber , + bindings::LED_COLOR_ID_VIOLET =>Color ::Violet , + bindings::LED_COLOR_ID_YELLOW =>Color ::Yellow , + bindings::LED_COLOR_ID_PURPLE =>Color ::Purple , + bindings::LED_COLOR_ID_ORANGE =>Color ::Orange , + bindings::LED_COLOR_ID_PINK =>Color ::Pink , + bindings::LED_COLOR_ID_CYAN =>Color ::Cyan , + bindings::LED_COLOR_ID_LIME =>Color ::Lime , + bindings::LED_COLOR_ID_IR =>Color ::IR , + bindings::LED_COLOR_ID_MULTI =>Color ::Multi , + bindings::LED_COLOR_ID_RGB =>Color ::RGB , + _ =>return Err (EINVAL ), + }) + } +} + +/// Config for the LED. +/// +/// Some fields are optional and only used depending on how the led is registered. +pub struct LedConfig { +/// Color of the LED. +pub color:Color , +} + +/// A Led backed by a C `struct led_classdev`, additionally offering +/// driver data storage. +/// +/// The LED is unregistered once this LED struct is dropped. +// TODO: add devm register variant +#[pin_data( PinnedDrop )] +pub struct Led <T > { +#[pin] + led:Opaque <bindings::led_classdev >, +/// Driver private data +pub data:T , +} + +impl <T >Led <T > { +/// Return a raw reference to `Self` from a raw `struct led_classdev` C pointer. +/// +/// # Safety +/// +/// `ptr` must point to a [`bindings::led_classdev`] field in a struct of type `Self`. +unsafe fn led_container_of (ptr: *mut bindings::led_classdev ) -> *mut Self { +let ptr = ptr.cast ::<Opaque <bindings::led_classdev >>(); + +// SAFETY: By the safety requirement of this function ptr is embedded in self. +unsafe {crate ::container_of!(ptr,Self , led).cast_mut () } + } +} + +impl <'a,T >Led <T > +where +T :Operations + 'a, +{ +/// Register a new LED with a predefine name. +pub fn register_with_name ( + name: &'aCStr , + device:Option <&'aDevice >, + config: &'aLedConfig , + data:T , + ) ->impl PinInit <Self ,Error > + 'a { +try_pin_init! (Self { + led <-Opaque ::try_ffi_init (move |place: *mut bindings::led_classdev | { +// SAFETY: `place` is a pointer to a live allocation, so erasing is valid. +unsafe { place.write_bytes (0 ,1 ) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_with_name (place, name) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_config (place, config) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_vtable (place) }; + +let dev = device.map (|dev| dev.as_raw ()).unwrap_or (ptr::null_mut ()); +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +crate ::error::to_result (unsafe { + bindings::led_classdev_register_ext (dev, place, ptr::null_mut ()) + }) + }), + data: data, + }) + } + +/// Add nameto the led_classdev. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_with_name (ptr: *mut bindings::led_classdev , name: &'aCStr ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let name_ptr =unsafe { ptr::addr_of_mut!((*ptr).name) }; +// SAFETY: `name_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (name_ptr, name.as_char_ptr ()) }; + } + +/// Add config to led_classdev. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_config (ptr: *mut bindings::led_classdev , config: &'aLedConfig ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let color_ptr =unsafe { ptr::addr_of_mut!((*ptr).color) }; +// SAFETY: `color_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (color_ptr, config.color.into ()) }; + } +} + +impl <T >Led <T > +where +T :Operations , +{ +/// Add the Operations vtable to the `led_classdev` struct. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_vtable (ptr: *mut bindings::led_classdev ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let max_brightness =unsafe { ptr::addr_of_mut!((*ptr).max_brightness) }; +// SAFETY: `max_brightness` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (max_brightness,T ::MAX_BRIGHTNESS as _ ) }; + +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let set_fn: *mut Option <_ > =unsafe { ptr::addr_of_mut!((*ptr).brightness_set) }; +// SAFETY: `set_fn` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (set_fn,Some (brightness_set ::<T >)) } + +if T ::HAS_BRIGHTNESS_GET { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let get_fn: *mut Option <_ > =unsafe { ptr::addr_of_mut!((*ptr).brightness_get) }; +// SAFETY: `set_fn` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (get_fn,Some (brightness_get ::<T >)) } + } + +if T ::HAS_BLINK_SET { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let blink_fn: *mut Option <_ > =unsafe { ptr::addr_of_mut!((*ptr).blink_set) }; +// SAFETY: `set_fn` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (blink_fn,Some (blink_set ::<T >)) } + } + } +} + +#[pinned_drop] +impl <T >PinnedDrop for Led <T > { +fn drop (self:Pin <&mut Self >) { +// SAEFTY: led is pointing to a live allocation +unsafe { bindings::led_classdev_unregister (self.led.get ()) } + } +} + +// SAFETY: `struct led_classdev` holds a mutex. +unsafe impl <T :Send >Send for Led <T > {} +// SAFETY: `struct led_classdev` holds a mutex. +unsafe impl <T :Sync >Sync for Led <T > {} + +/// LED brightness. +#[derive( Debug , Copy , Clone )] +pub enum Brightness { +/// LED off. +Off , +/// Led set to the given value. +On (NonZeroU8 ), +} + +impl Brightness { +/// Half LED brightness +// SAFETY: constant value non zero +pub const HALF :Self =Self ::On (unsafe {NonZeroU8 ::new_unchecked (127 ) }); +/// Full LED brightness. +pub const FULL :Self =Self ::On (NonZeroU8 ::MAX ); + +/// Convert C brightness value to Rust brightness enum +fn from_c_enum (brightness: bindings::led_brightness ) ->Self { + u8::try_from (brightness) + .map (NonZeroU8 ::new) + .map (|brightness| brightness.map (Self ::On ).unwrap_or (Self ::Off )) + .inspect_err (|_|pr_warn! ("Brightness out of u8 range\n" )) + .unwrap_or (Self ::FULL ) + } + +/// Convert rust brightness enum to C value +fn as_c_enum (&self) -> bindings::led_brightness { + u8::from (self)as bindings::led_brightness + } +} + +impl From <&Brightness >for u8 { +fn from (brightness: &Brightness ) ->Self { +match brightness { +Brightness ::Off =>0 , +Brightness ::On (v) => v.get (), + } + } +} + +/// Led operations vtable. +// TODO: add blocking variant (either via const generic or second trait) +#[macros::vtable] +pub trait Operations :Sized { +/// The maximum brightnes this led supports. +const MAX_BRIGHTNESS :u8 ; + +/// Set LED brightness level. +/// This functions must not sleep. +fn brightness_set (this: &mut Led <Self >, brightness:Brightness ); + +/// Get the LED brightness level. +fn brightness_get (_this: &mut Led <Self >) ->Brightness { +crate ::build_error (crate ::error::VTABLE_DEFAULT_ERROR ) + } + +/// Activae hardware accelerated blink, delays are in milliseconds +fn blink_set ( + _this: &mut Led <Self >, + _delay_on:Duration , + _delay_off:Duration , + ) ->Result <(Duration ,Duration )> { +crate ::build_error (crate ::error::VTABLE_DEFAULT_ERROR ) + } +} + +unsafe extern "C" fn brightness_set <T >( + led_cdev: *mut bindings::led_classdev , + brightness: bindings::led_brightness , +)where +T :Operations , +{ +// SAFETY: By the safety requirement of this function `led_cdev` is embedded inside a `Led<T>` +// struct. +let led =unsafe { &mut *(Led ::<T >::led_container_of (led_cdev.cast ())) }; +let brightness =Brightness ::from_c_enum (brightness); +T ::brightness_set (led, brightness); +} + +unsafe extern "C" fn brightness_get <T >( + led_cdev: *mut bindings::led_classdev , +) -> bindings::led_brightness +where +T :Operations , +{ +// SAFETY: By the safety requirement of this function `led_cdev` is embedded inside a `Led<T>` +// struct. +let led =unsafe { &mut *(Led ::<T >::led_container_of (led_cdev.cast ())) }; +T ::brightness_get (led).as_c_enum () +} + +unsafe extern "C" fn blink_set <T >( + led_cdev: *mut bindings::led_classdev , + delay_on: *mut c_ulong , + delay_off: *mut c_ulong , +) ->i32 +where +T :Operations , +{ +from_result (|| { +// SAFETY: By the safety requirement of this function `led_cdev` is embedded inside a +// `Led<T>` struct. +let led =unsafe { &mut *(Led ::<T >::led_container_of (led_cdev.cast ())) }; + +// SAFETY: By the safety requirement of this function `delay_on` is pointing to a valid +// `c_uint` +let on =Duration ::from_millis (unsafe { *delay_on }as u64 ); +// SAFETY: By the safety requirement of this function `delay_off` is pointing to a valid +// `c_uint` +let off =Duration ::from_millis (unsafe { *delay_off }as u64 ); + +let (on, off) =T ::blink_set (led, on, off)?; + +// writing back return values +// SAFETY: By the safety requirement of this function `delay_on` is pointing to a valid +// `c_uint` +unsafe { ptr::write (delay_on, on.as_millis ()as c_ulong ) }; +// SAFETY: By the safety requirement of this function `delay_off` is pointing to a valid +// `c_uint` +unsafe { ptr::write (delay_off, off.as_millis ()as c_ulong ) }; + +Ok (0 ) + }) +}
rust/kernel/lib.rs +2 -0
@@ -38,6 +38,8 @@pub mod ioctl;#[cfg( CONFIG_KUNIT )] pub mod kunit; +#[cfg( CONFIG_NEW_LEDS )] +pub mod leds;pub mod list;#[cfg( CONFIG_NET )] pub mod net;
Signature · 1 line
2.46.0
Re: [RFC PATCH 1/2] rust: LED abstraction
Quoted 17 lines · Fiona Behrens
rust/kernel/leds.rs new file +17
-0+/// Color of an LED. +#[derive( Copy , Clone )] +pub enum Color { +/// White +White , +/// Red +Red , +/// Green +Green , +/// Blue +Blue , +/// Amber +Amber , +/// Violet +Violet , +/// Yellow +Yellow ,
rust/kernel/leds.rs line 41
Quoted 10 lines
rust/kernel/leds.rs new file +10
-0+/// Purple + Purple, +/// Orange + Orange, +/// Pink + Pink, +/// Cyan + Cyan, +/// Lime + Lime,
Why these repetitions?
Quoted 14 lines
rust/kernel/leds.rs new file +14
-0+impl TryFrom <u32 >for Color { +type Error =Error ; + +fn try_from (value:u32 ) ->Result <Self ,Self ::Error > { +Ok (match value { + bindings::LED_COLOR_ID_WHITE =>Color ::White , + bindings::LED_COLOR_ID_RED =>Color ::Red , + bindings::LED_COLOR_ID_GREEN =>Color ::Green , + bindings::LED_COLOR_ID_BLUE =>Color ::Blue , + bindings::LED_COLOR_ID_AMBER =>Color ::Amber , + bindings::LED_COLOR_ID_VIOLET =>Color ::Violet , + bindings::LED_COLOR_ID_YELLOW =>Color ::Yellow , + bindings::LED_COLOR_ID_PURPLE =>Color ::Purple , + bindings::LED_COLOR_ID_ORANGE =>Color ::Orange ,
rust/kernel/leds.rs line 130
Quoted 10 lines
rust/kernel/leds.rs new file +10
-0+ bindings::LED_COLOR_ID_PINK => Color::Pink, + bindings::LED_COLOR_ID_CYAN => Color::Cyan, + bindings::LED_COLOR_ID_LIME => Color::Lime, + bindings::LED_COLOR_ID_IR => Color::IR, + bindings::LED_COLOR_ID_MULTI => Color::Multi, + bindings::LED_COLOR_ID_RGB => Color::RGB, + _ => return Err(EINVAL), + }) + } +}
How does Rust compile these? If these constants compile to the same numeric values, i.e. if
LED_COLOR_ID_AMBER == Color::Amber,
will the compiler compile away the function?
How do enums work in Rust?
Quoted 1 line
+impl<'a, T> Led<T>
offtopic, what is 'a ? What does the ' mean? Is impl<> something like template in c++?
rust/kernel/leds.rs line 169
Quoted 2 lines
rust/kernel/leds.rs new file +2
-0+where + T: Operations + 'a,
What does + mean here?
Quoted 5 lines
rust/kernel/leds.rs new file +5
-0+/// LED brightness. +#[derive( Debug , Copy , Clone )] +pub enum Brightness { +/// LED off. +Off ,
rust/kernel/leds.rs line 290
Quoted 10 lines
rust/kernel/leds.rs new file +10
-0+/// Led set to the given value. + On(NonZeroU8), +} + +impl Brightness { +/// Half LED brightness +// SAFETY: constant value non zero +pub const HALF :Self =Self ::On (unsafe {NonZeroU8 ::new_unchecked (127 ) }); +/// Full LED brightness. +pub const FULL :Self =Self ::On (NonZeroU8 ::MAX );
These LED_OFF, LED_ON, LED_HALF and LED_FULL are deprecated constants that should not be used anymore. enum led_brightness will be either uint8_t or usigned int in the future.
Is it possible to not infect Rust with these deprecated constants?
Marek
Alice Ryhl
reviewerRe: [RFC PATCH 1/2] rust: LED abstraction
Quoted 24 lines · Marek Behún
Quoted 21 lines · Fiona Behrens
rust/kernel/leds.rs new file +21
-0+/// Color of an LED. +#[derive( Copy , Clone )] +pub enum Color { +/// White +White , +/// Red +Red , +/// Green +Green , +/// Blue +Blue , +/// Amber +Amber , +/// Violet +Violet , +/// Yellow +Yellow , +/// Purple +Purple , +/// Orange +Orange ,
Quoted 8 lines
rust/kernel/leds.rs line 41
Quoted 6 lines
rust/kernel/leds.rs new file +6
-0+/// Pink + Pink, +/// Cyan + Cyan, +/// Lime + Lime,Why these repetitions?
My guess is that it's to silence the warning about undocumented public items. It may make sense to just silence the warning in this case.
Quoted 21 lines
Quoted 21 lines
rust/kernel/leds.rs new file +21
-0+impl TryFrom <u32 >for Color { +type Error =Error ; + +fn try_from (value:u32 ) ->Result <Self ,Self ::Error > { +Ok (match value { + bindings::LED_COLOR_ID_WHITE =>Color ::White , + bindings::LED_COLOR_ID_RED =>Color ::Red , + bindings::LED_COLOR_ID_GREEN =>Color ::Green , + bindings::LED_COLOR_ID_BLUE =>Color ::Blue , + bindings::LED_COLOR_ID_AMBER =>Color ::Amber , + bindings::LED_COLOR_ID_VIOLET =>Color ::Violet , + bindings::LED_COLOR_ID_YELLOW =>Color ::Yellow , + bindings::LED_COLOR_ID_PURPLE =>Color ::Purple , + bindings::LED_COLOR_ID_ORANGE =>Color ::Orange , + bindings::LED_COLOR_ID_PINK =>Color ::Pink , + bindings::LED_COLOR_ID_CYAN =>Color ::Cyan , + bindings::LED_COLOR_ID_LIME =>Color ::Lime , + bindings::LED_COLOR_ID_IR =>Color ::IR , + bindings::LED_COLOR_ID_MULTI =>Color ::Multi , + bindings::LED_COLOR_ID_RGB =>Color ::RGB , + _ =>return Err (EINVAL ),
Quoted 8 lines
rust/kernel/leds.rs line 130
Quoted 3 lines
rust/kernel/leds.rs new file +3
-0+ }) + } +}How does Rust compile these? If these constants compile to the same numeric values, i.e. if
LED_COLOR_ID_AMBER==Color::Amber,
will the compiler compile away the function?
Well, it can't compile away the part where it returns EINVAL when the u32 is not a valid color. But other than that, these matches are usually optimized pretty well. I just tried a few different examples in godbolt to confirm it. See e.g.:
https://rust.godbolt.org/z/WWM7891zW
That said, this relies on the assumption that they are represented using the same values. We probably want to change the declaration to this:
#[derive(Copy, Clone)]
pub enum Color {
White = bindings::LED_COLOR_ID_WHITE,
Red = bindings::LED_COLOR_ID_RED,
Green = bindings::LED_COLOR_ID_GREEN,
...
}
That way we are guaranteed that the enum uses the right values for the enum to make the conversion free.
Quoted 1 line
How do enums work in Rust?
In this case, the enum has no fields. In that case, the enum is a value that is only allowed to have certain values.
Enums are also allowed to have fields. In this case, you can think of it as a discriminated union, though in some cases Rust will store it in a more clever way. You can look up the "null pointer optimization" for an example of that.
Quoted 4 lines
Quoted 1 line
+impl<'a, T> Led<T>
offtopic, what is 'a ? What does the ' mean? Is impl<> something like template in c++?
Things starting with a tick are lifetimes, so 'a is the name of a lifetime. That said, this usage of lifetimes looks incorrect to me, so I wouldn't look too closely at this instance.
As for impl<>, then yes sort of. It is the <> that makes it like a template. When you have an impl TypeName { ... } block, then that defines methods for TypeName, which you can call as either value.method(...) or TypeName::method(...) depending on the signature. When you write impl<T>, then this means that it is a template (we use the word "generic" in Rust rather than "template"), that is
impl<T> TypeName<T> { ... }
becomes the following infinite list of impl blocks:
impl TypeName<i32> { ... }
impl TypeName<u32> { ... }
impl TypeName<String> { ... }
impl TypeName<TcpStream> { ... }
// ... and so on for all possible types
This logic works anywhere that <T> appears. For example, struct TypeName<T> { ... } is short-hand for the following infinite list of structs:
struct TypeName<i32> { ... }
struct TypeName<u32> { ... }
struct TypeName<String> { ... }
struct TypeName<TcpStream> { ... }
// ... and so on for all possible types
Of course, only things in this infinite list that you actually use end up in the final binary.
The where T: Operations part is a filter for the infinite list. It restricts it so that only types T that implement the Operations trait are present in the list; all other types are filtered out.
Quoted 4 lines
rust/kernel/leds.rs line 169
Quoted 2 lines
rust/kernel/leds.rs new file +2
-0+where + T: Operations + 'a,What does + mean here?
This is the same as:
where
T: Operations,
T: 'athat is, apply two filters to the infinite list I mentioned above. The meaning of T: 'a when the RHS is a lifetime is that T must not be a type containing a lifetime annotation shorter than 'a.
Quoted 23 lines
Quoted 5 lines
rust/kernel/leds.rs new file +5
-0+/// LED brightness. +#[derive( Debug , Copy , Clone )] +pub enum Brightness { +/// LED off. +Off ,rust/kernel/leds.rs line 290
Quoted 10 lines
rust/kernel/leds.rs new file +10
-0+/// Led set to the given value. + On(NonZeroU8), +} + +impl Brightness { +/// Half LED brightness +// SAFETY: constant value non zero +pub const HALF :Self =Self ::On (unsafe {NonZeroU8 ::new_unchecked (127 ) }); +/// Full LED brightness. +pub const FULL :Self =Self ::On (NonZeroU8 ::MAX );These
LED_OFF,LED_ON,LED_HALFandLED_FULLare deprecated constants that should not be used anymore. enumled_brightnesswill be eitheruint8_tor usigned int in the future.Is it possible to not infect Rust with these deprecated constants?
Marek
Re: [RFC PATCH 1/2] rust: LED abstraction
Quoted 3 lines · Alice Ryhl
signature. When you write
impl<T>, then this means that it is a template (we use the word "generic" in Rust rather than "template"),
Marek: a main difference is that generics in Rust require you to spell out everything your type needs in order to be able to use it in the implementation, unlike C++ templates which will gladly accept any type as long as the resulting code compiles (i.e. whether the types make sense or not).
So in C++ you may typically do just T, while in Rust you typically restrict your types with bounds and wheres clauses like Alice shows.
I hope that clarifies a bit!
Cheers,
Miguel
Alice Ryhl
reviewerRe: [RFC PATCH 1/2] rust: LED abstraction
In reply to Fiona BehrensQuoted 49 lines · Fiona Behrens
rust/kernel/leds.rs new file +49
-0+impl <'a,T >Led <T > +where +T :Operations + 'a, +{ +/// Register a new LED with a predefine name. +pub fn register_with_name ( + name: &'aCStr , + device:Option <&'aDevice >, + config: &'aLedConfig , + data:T , + ) ->impl PinInit <Self ,Error > + 'a { +try_pin_init! (Self { + led <-Opaque ::try_ffi_init (move |place: *mut bindings::led_classdev | { +// SAFETY: `place` is a pointer to a live allocation, so erasing is valid. +unsafe { place.write_bytes (0 ,1 ) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_with_name (place, name) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_config (place, config) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_vtable (place) }; + +let dev = device.map (|dev| dev.as_raw ()).unwrap_or (ptr::null_mut ()); +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +crate ::error::to_result (unsafe { + bindings::led_classdev_register_ext (dev, place, ptr::null_mut ()) + }) + }), + data: data, + }) + } + +/// Add nameto the led_classdev. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_with_name (ptr: *mut bindings::led_classdev , name: &'aCStr ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let name_ptr =unsafe { ptr::addr_of_mut!((*ptr).name) }; +// SAFETY: `name_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (name_ptr, name.as_char_ptr ()) }; + } + +/// Add config to led_classdev. +///
rust/kernel/leds.rs line 225
Quoted 10 lines
rust/kernel/leds.rs new file +10
-0+/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_config (ptr: *mut bindings::led_classdev , config: &'aLedConfig ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let color_ptr =unsafe { ptr::addr_of_mut!((*ptr).color) }; +// SAFETY: `color_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (color_ptr, config.color.into ()) }; + } +}
This usage of lifetimes looks incorrect to me. It looks like you are trying to say that the references must be valid for longer than the Led<T>, but what you are writing here does not enforce that. The Led struct must be annotated with the 'a lifetime if you want that, but I'm inclined to say you should not go for the lifetime solution in the first place.
Alice
Re: [RFC PATCH 1/2] rust: LED abstraction
Quoted 59 lines · Alice Ryhl
Quoted 58 lines · Fiona Behrens
rust/kernel/leds.rs new file +58
-0+impl <'a,T >Led <T > +where +T :Operations + 'a, +{ +/// Register a new LED with a predefine name. +pub fn register_with_name ( + name: &'aCStr , + device:Option <&'aDevice >, + config: &'aLedConfig , + data:T , + ) ->impl PinInit <Self ,Error > + 'a { +try_pin_init! (Self { + led <-Opaque ::try_ffi_init (move |place: *mut bindings::led_classdev | { +// SAFETY: `place` is a pointer to a live allocation, so erasing is valid. +unsafe { place.write_bytes (0 ,1 ) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_with_name (place, name) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_config (place, config) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_vtable (place) }; + +let dev = device.map (|dev| dev.as_raw ()).unwrap_or (ptr::null_mut ()); +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +crate ::error::to_result (unsafe { + bindings::led_classdev_register_ext (dev, place, ptr::null_mut ()) + }) + }), + data: data, + }) + } + +/// Add nameto the led_classdev. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_with_name (ptr: *mut bindings::led_classdev , name: &'aCStr ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let name_ptr =unsafe { ptr::addr_of_mut!((*ptr).name) }; +// SAFETY: `name_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (name_ptr, name.as_char_ptr ()) }; + } + +/// Add config to led_classdev. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_config (ptr: *mut bindings::led_classdev , config: &'aLedConfig ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let color_ptr =unsafe { ptr::addr_of_mut!((*ptr).color) }; +// SAFETY: `color_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (color_ptr, config.color.into ()) }; + }
Quoted 8 lines
Quoted 1 line
+}
This usage of lifetimes looks incorrect to me. It looks like you are trying to say that the references must be valid for longer than the Led<T>, but what you are writing here does not enforce that. The Led struct must be annotated with the 'a lifetime if you want that, but I'm inclined to say you should not go for the lifetime solution in the first place.
The led_classdev_register_ext function copies the name, therefore the idea was that the name only has to exists until the pin init function is called, which should be the case with how I used the lifetimes here
Fiona
Quoted 2 lines
Alice
Alice Ryhl
reviewerRe: [RFC PATCH 1/2] rust: LED abstraction
Quoted 71 lines · Fiona Behrens
Quoted 59 lines · Alice Ryhl
Quoted 58 lines · Fiona Behrens
rust/kernel/leds.rs new file +58
-0+impl <'a,T >Led <T > +where +T :Operations + 'a, +{ +/// Register a new LED with a predefine name. +pub fn register_with_name ( + name: &'aCStr , + device:Option <&'aDevice >, + config: &'aLedConfig , + data:T , + ) ->impl PinInit <Self ,Error > + 'a { +try_pin_init! (Self { + led <-Opaque ::try_ffi_init (move |place: *mut bindings::led_classdev | { +// SAFETY: `place` is a pointer to a live allocation, so erasing is valid. +unsafe { place.write_bytes (0 ,1 ) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_with_name (place, name) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_config (place, config) }; + +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +unsafe {Self ::build_vtable (place) }; + +let dev = device.map (|dev| dev.as_raw ()).unwrap_or (ptr::null_mut ()); +// SAFETY: `place` is a pointer to a live allocation of `bindings::led_classdev`. +crate ::error::to_result (unsafe { + bindings::led_classdev_register_ext (dev, place, ptr::null_mut ()) + }) + }), + data: data, + }) + } + +/// Add nameto the led_classdev. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_with_name (ptr: *mut bindings::led_classdev , name: &'aCStr ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let name_ptr =unsafe { ptr::addr_of_mut!((*ptr).name) }; +// SAFETY: `name_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (name_ptr, name.as_char_ptr ()) }; + } + +/// Add config to led_classdev. +/// +/// # Safety +/// +/// `ptr` has to be valid. +unsafe fn build_config (ptr: *mut bindings::led_classdev , config: &'aLedConfig ) { +// SAFETY: `ptr` is pointing to a live allocation, so the deref is safe. +let color_ptr =unsafe { ptr::addr_of_mut!((*ptr).color) }; +// SAFETY: `color_ptr` points to a valid allocation and we have exclusive access. +unsafe { ptr::write (color_ptr, config.color.into ()) }; + }Quoted 8 lines
Quoted 1 line
+}
This usage of lifetimes looks incorrect to me. It looks like you are trying to say that the references must be valid for longer than the Led<T>, but what you are writing here does not enforce that. The Led struct must be annotated with the 'a lifetime if you want that, but I'm inclined to say you should not go for the lifetime solution in the first place.
Quoted 1 line
The
led_classdev_register_extfunction copies the name, therefore the idea was that the name only has to exists until the pin init function is called, which should be the case with how I used the lifetimes here
In that case you should be able to get rid of the lifetime like this:
impl<T> Led<T>
where
T: Operations,
{
/// Register a new LED with a predefine name.
pub fn register_with_name(
name: &CStr,
device: Option<&Device>,
config: &LedConfig,
data: T,
) -> impl PinInit<Self, Error> {
...
}RFC PATCH 2/2 samples: rust: led sample
In reply to Fiona BehrensProvide an initial sample LED driver that just prints the current requested LED state.
This is not intended to be merged, but as a placeholder until the abstactions for hardware access are written.
--- samples/rust/Kconfig | 10 ++++ samples/rust/Makefile | 1 + samples/rust/rust_led.rs | 103 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+) create mode 100644 samples/rust/rust_led.rs
samples/rust/Kconfig +10 -0
@@ -30,6 +30,16 @@ config SAMPLE_RUST_PRINT If unsure, say N. +config SAMPLE_RUST_LED + tristate "Led subsystem" + help + This option builds the Rust LED subsystem sample. + + To compile this as a module, choose M here: + the module will be called rust_led. + + If unsure, say N. + config SAMPLE_RUST_HOSTPROGS bool "Host programs" help
samples/rust/Makefile +1 -0
@@ -2,5 +2,6 @@ obj-$(CONFIG_SAMPLE_RUST_MINIMAL) += rust_minimal.o obj-$(CONFIG_SAMPLE_RUST_PRINT) += rust_print.o +obj-$(CONFIG_SAMPLE_RUST_LED) += rust_led.o subdir-$(CONFIG_SAMPLE_RUST_HOSTPROGS) += hostprogs
samples/rust/rust_led.rs new file +103 -0
103 lines not on this page · raw message
Signature · 1 line
2.46.0
Lee Jones
maintainerQuoted 26 lines · Fiona Behrens
This RFC implements a basic LED abstraction to show how this would work with rust.
Currently this just implements a sample driver, to show how to use the abstraction, which just prints the requested state, supporting a on/off LED and an led with brightness level up to 255 and hardware blinking. I intend to write a hardware specific driver for submitting.
The abstractions is a generic struct that holds a generic driver data on which the vtable is implemented. Because this struct also holds the c
led_classdev(include/linux/leds.h) struct this struct is pinned and is usingpin_initto create and directly register the LED. Dropping the struct unregisteres the LED. I plan to also add devm functions later, but as device abstractions in rust are not yet that far I opted agains that for the first iteration of the LED abstractions.This is currently using
core::time::Durationfor the blinking interval, but will likely change that to use the Delta time type from FUJITA Tomonori [1].This is requiring the
Opaque::try_ffi_initpatch by Alice Ryhl[2] which just got merged into char-misc-testing.[1]: https://lore.kernel.org/rust-for-linux/[email protected]/
[2]: https://lore.kernel.org/rust-for-linux/[email protected]/Fiona Behrens (2):
rust: LED abstraction
samples: rust: led sample
Quoted 8 lines
rust/kernel/leds.rs | 399 +++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + samples/rust/Kconfig | 10 + samples/rust/Makefile | 1 + samples/rust/rust_led.rs | 103 ++++++++++ 5 files changed, 515 insertions(+) create mode 100644 rust/kernel/leds.rs create mode 100644 samples/rust/rust_led.rs
FYI: I'm not ignoring this patch-set. On the contrary. I'm trying to place myself into a position where I can not only review it with some confidence, but use it to author LED drivers.
Signature · 1 line
Lee Jones [李琼斯]
Quoted 37 lines · Lee Jones
Quoted 26 lines · Fiona Behrens
This RFC implements a basic LED abstraction to show how this would work with rust.
Currently this just implements a sample driver, to show how to use the abstraction, which just prints the requested state, supporting a on/off LED and an led with brightness level up to 255 and hardware blinking. I intend to write a hardware specific driver for submitting.
The abstractions is a generic struct that holds a generic driver data on which the vtable is implemented. Because this struct also holds the c
led_classdev(include/linux/leds.h) struct this struct is pinned and is usingpin_initto create and directly register the LED. Dropping the struct unregisteres the LED. I plan to also add devm functions later, but as device abstractions in rust are not yet that far I opted agains that for the first iteration of the LED abstractions.This is currently using
core::time::Durationfor the blinking interval, but will likely change that to use the Delta time type from FUJITA Tomonori [1].This is requiring the
Opaque::try_ffi_initpatch by Alice Ryhl[2] which just got merged into char-misc-testing.[1]: https://lore.kernel.org/rust-for-linux/[email protected]/
[2]: https://lore.kernel.org/rust-for-linux/[email protected]/Fiona Behrens (2):
rust: LED abstraction
samples: rust: led sampleQuoted 8 lines
rust/kernel/leds.rs | 399 +++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 2 + samples/rust/Kconfig | 10 + samples/rust/Makefile | 1 + samples/rust/rust_led.rs | 103 ++++++++++ 5 files changed, 515 insertions(+) create mode 100644 rust/kernel/leds.rs create mode 100644 samples/rust/rust_led.rs
Quoted 4 lines
FYI: I'm not ignoring this patch-set. On the contrary. I'm trying to place myself into a position where I can not only review it with some confidence, but use it to author LED drivers.
Ah amazing, the first RFC was to probe for a general would LED accept rust code, and this sounds like a yes. Nice!
Currently still working on a LED driver for a Lenovo board that does not (as of when I started, and think still not yet) have a C driver for the LED. Current things missing is a static dmi match table (idea is to hardcoded that for now) and a abstraction for port memory but working on that, and can otherwise just go around that with unsafe calls in the driver itself.
- Fiona
Quoted 2 lines
Signature · 1 line
Lee Jones [李琼斯]