[PATCH v8 4/4] rust: leds: add multicolor classdev abstractions

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

Implement the abstractions needed for multicolor led class devices,
including:

* `led::MultiColor` - the led mode implementation

* `MultiColorSubLed` - a safe wrapper arround `mc_subled`

* `led::Device::new_multicolor()` - the function to register a multicolor
  led class device

* `led::Device::subleds()` - the function to access the brightness and
  intensity of the individual sub leds

Signed-off-by: Markus Probst <markus.probst@posteo.de>
---
 rust/bindings/bindings_helper.h |   1 +
 rust/kernel/led.rs              |   7 +-
 rust/kernel/led/multicolor.rs   | 195 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 202 insertions(+), 1 deletion(-)

diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index 2e43c66635a2..ba8605eeecce 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -61,6 +61,7 @@
 #include <linux/ioport.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>
diff --git a/rust/kernel/led.rs b/rust/kernel/led.rs
index c55f9852d378..4add9d15a5e0 100644
--- a/rust/kernel/led.rs
+++ b/rust/kernel/led.rs
@@ -44,8 +44,12 @@
     }, //
 };
 
+#[cfg(CONFIG_LEDS_CLASS_MULTICOLOR)]
+mod multicolor;
 mod normal;
 
+#[cfg(CONFIG_LEDS_CLASS_MULTICOLOR)]
+pub use multicolor::{MultiColor, MultiColorSubLed};
 pub use normal::Normal;
 
 /// The led class device representation.
@@ -288,7 +292,8 @@ 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::Mode {}
 
 impl<T: private::Mode> Mode for T {}
diff --git a/rust/kernel/led/multicolor.rs b/rust/kernel/led/multicolor.rs
new file mode 100644
index 000000000000..3afefaef6498
--- /dev/null
+++ b/rust/kernel/led/multicolor.rs
@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Led mode for the `struct led_classdev_mc`.
+//!
+//! C header: [`include/linux/led-class-multicolor.h`](srctree/include/linux/led-class-multicolor.h)
+
+use crate::{
+    alloc::KVec,
+    error::code::EINVAL,
+    prelude::*, //
+};
+
+use super::*;
+
+/// The led mode for the `struct led_classdev_mc`. Leds with this mode can have multiple colors.
+pub enum MultiColor {}
+
+/// The multicolor sub led info representation.
+///
+/// This structure represents the Rust abstraction for a C `struct mc_subled`.
+#[repr(C)]
+#[derive(Copy, Clone, Debug)]
+pub struct MultiColorSubLed {
+    /// the color of the sub led
+    pub color: Color,
+    /// the brightness of the sub led.
+    ///
+    /// The value will be automatically calculated.
+    /// See `MultiColor::pre_brightness_set`.
+    pub brightness: u32,
+    /// the intensity of the sub led.
+    pub intensity: u32,
+    /// arbitrary data for the driver to store.
+    pub channel: u32,
+    _p: PhantomData<()>, // Only allow creation with `MultiColorSubLed::new`.
+}
+
+// We directly pass a reference to the `subled_info` field in `led_classdev_mc` to the driver via
+// `Device::subleds()`.
+// We need safeguards to ensure `MultiColorSubLed` and `mc_subled` stay identical.
+const _: () = {
+    use core::mem::offset_of;
+
+    const fn assert_same_type<T>(_: &T, _: &T) {}
+
+    let rust_zeroed = MultiColorSubLed {
+        color: Color::White,
+        brightness: 0,
+        intensity: 0,
+        channel: 0,
+        _p: PhantomData,
+    };
+    let c_zeroed = bindings::mc_subled {
+        color_index: 0,
+        brightness: 0,
+        intensity: 0,
+        channel: 0,
+    };
+
+    assert!(offset_of!(MultiColorSubLed, color) == offset_of!(bindings::mc_subled, color_index));
+    assert_same_type(&0u32, &c_zeroed.color_index);
+
+    assert!(
+        offset_of!(MultiColorSubLed, brightness) == offset_of!(bindings::mc_subled, brightness)
+    );
+    assert_same_type(&rust_zeroed.brightness, &c_zeroed.brightness);
+
+    assert!(offset_of!(MultiColorSubLed, intensity) == offset_of!(bindings::mc_subled, intensity));
+    assert_same_type(&rust_zeroed.intensity, &c_zeroed.intensity);
+
+    assert!(offset_of!(MultiColorSubLed, channel) == offset_of!(bindings::mc_subled, channel));
+    assert_same_type(&rust_zeroed.channel, &c_zeroed.channel);
+
+    assert!(size_of::<MultiColorSubLed>() == size_of::<bindings::mc_subled>());
+};
+
+impl MultiColorSubLed {
+    /// Create a new multicolor sub led info.
+    pub fn new(color: Color) -> Self {
+        Self {
+            color,
+            brightness: 0,
+            intensity: 0,
+            channel: 0,
+            _p: PhantomData,
+        }
+    }
+
+    /// Set arbitrary data for the driver.
+    pub fn channel(mut self, channel: u32) -> Self {
+        self.channel = channel;
+        self
+    }
+
+    /// Set the initial intensity of the subled.
+    pub fn initial_intensity(mut self, intensity: u32) -> Self {
+        self.intensity = intensity;
+        self
+    }
+}
+
+impl private::Mode for MultiColor {
+    type Type = bindings::led_classdev_mc;
+    const REGISTER: RegisterFunc<Self::Type> = bindings::led_classdev_multicolor_register_ext;
+    const UNREGISTER: UnregisterFunc<Self::Type> = bindings::led_classdev_multicolor_unregister;
+
+    unsafe fn device<'a>(raw: *mut Self::Type) -> &'a device::Device {
+        // SAFETY:
+        // - The function's contract guarantees that `raw` is a valid pointer to `led_classdev`.
+        unsafe { device::Device::from_raw((*raw).led_cdev.dev) }
+    }
+
+    unsafe fn from_classdev(led_cdev: *mut bindings::led_classdev) -> *mut Self::Type {
+        // SAFETY: The function's contract guarantees that `led_cdev` is a valid pointer to
+        // `led_classdev` embedded within a `Self::Type`.
+        unsafe { container_of!(led_cdev, bindings::led_classdev_mc, led_cdev) }
+    }
+
+    unsafe fn pre_brightness_set(raw: *mut Self::Type, brightness: u32) {
+        // SAFETY: The function's contract guarantees that `raw` is a valid pointer to
+        // `led_classdev_mc`.
+        unsafe { bindings::led_mc_calc_color_components(raw, brightness) };
+    }
+
+    fn release(led_cdev: &mut Self::Type) {
+        // SAFETY: `subled_info` is guaranteed to be a valid array pointer to `mc_subled` with the
+        // length and capacity of `led_cdev.num_colors`. See `led::Device::new_multicolor`.
+        let _subleds_vec = unsafe {
+            KVec::from_raw_parts(
+                led_cdev.subled_info,
+                led_cdev.num_colors as usize,
+                led_cdev.num_colors as usize,
+            )
+        };
+    }
+}
+
+impl<T: LedOps<Mode = MultiColor>> Device<T> {
+    /// Registers a new multicolor led classdev.
+    ///
+    /// The [`Device`] will be unregistered on drop.
+    pub fn new_multicolor<'a>(
+        parent: &'a T::Bus,
+        init_data: InitData<'a>,
+        ops: T,
+        subleds: &'a [MultiColorSubLed],
+    ) -> impl PinInit<Devres<Self>, Error> + 'a {
+        assert!(subleds.len() <= u32::MAX as usize);
+        Self::__new(parent, init_data, ops, |led_cdev| {
+            let mut subleds_vec = KVec::new();
+            subleds_vec.extend_from_slice(subleds, GFP_KERNEL)?;
+            let (subled_info, num_colors, capacity) = subleds_vec.into_raw_parts();
+            debug_assert_eq!(num_colors, capacity);
+
+            let mut used = 0;
+            if subleds.iter().any(|subled| {
+                let bit = 1 << (subled.color as u32);
+                if (used & bit) != 0 {
+                    true
+                } else {
+                    used |= bit;
+                    false
+                }
+            }) {
+                dev_err!(parent.as_ref(), "duplicate color in multicolor led\n");
+                return Err(EINVAL);
+            }
+
+            Ok(bindings::led_classdev_mc {
+                led_cdev,
+                // CAST: We checked above that the length of subleds fits into a u32.
+                num_colors: num_colors as u32,
+                // CAST: The safeguards in the const block ensure that `MultiColorSubLed` has an
+                // identical layout to `mc_subled`.
+                subled_info: subled_info.cast::<bindings::mc_subled>(),
+            })
+        })
+    }
+
+    /// Returns the subleds passed to [`Device::new_multicolor`].
+    pub fn subleds(&self) -> &[MultiColorSubLed] {
+        // SAFETY: The existence of `self` guarantees that `self.classdev.get()` is a pointer to a
+        // valid `led_classdev_mc`.
+        let raw = unsafe { &*self.classdev.get() };
+        // SAFETY: `raw.subled_info` is a valid pointer to `mc_subled[num_colors]`.
+        // CAST: The safeguards in the const block ensure that `MultiColorSubLed` has an identical
+        // layout to `mc_subled`.
+        unsafe {
+            core::slice::from_raw_parts(
+                raw.subled_info.cast::<MultiColorSubLed>(),
+                raw.num_colors as usize,
+            )
+        }
+    }
+}

-- 
2.51.0