Merge tag 'leds-next-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/lee/leds

Pull LED updates from Lee Jones:
 "New Support & Features:
   - Samsung S2MU005: Add support for the Samsung S2MU005 PMIC which
     includes flash and RGB LED controllers
   - Texas Instruments:
       - LP5812: Add support for the TI LP5812 LED driver
       - LP5860: Add support for the Texas Instruments LP5860 LED matrix
         driver via SPI

  Improvements & Fixes:
   - Core:
       - Adjust the brightness sysfs node documentation to clarify that
         only decimal values are accepted
       - Fix a race condition in the software blink logic when stopping
         blinking and setting brightness simultaneously
       - Introduce the `multi_max_intensity` sysfs attribute for
         multicolor LEDs to support hardware-based global brightness
         control
       - Replace OF-based device lookup with firmware node equivalents
         to support ACPI and software nodes
       - Return `ENODATA` when reading brightness from
         hardware-controlled LEDs
       - Set the coherent DMA mask to zero for the Samsung PMIC device
         to suppress unnecessary "DMA mask not set" messages
   - ams OSRAM AS3668: Fix a Kconfig symbol name mismatch in the
     Makefile that prevented the driver from being built
   - BlinkM: Fix spelling and comment style issues in the driver
   - DAC124S085: Declare the SPI command word as `__le16` to ensure
     correct endianness and pass sparse checks
   - GPIO Trigger: Use `GPIOD_FLAGS_BIT_NONEXCLUSIVE` to allow sharing
     GPIOs between the LED trigger and other drivers
   - NXP PCA9532: Fix an issue where the LED would stop blinking when
     changing brightness to a non-zero value
   - Qualcomm: Unify the user-visible company name to "Qualcomm" across
     flash LED config options
   - Qualcomm LPG: Optimize memory allocation by combining main
     structure and channels into a single allocation using flexible
     array members
   - Texas Instruments
       - LP5860: Add missing `CONFIG_OF` dependency to prevent build
         warnings
       - TPS6131x: Increase the overvoltage protection threshold to 6V
         to avoid false triggers with 5V input supplies
   - Userspace LEDs (uLEDs):
       - Fix a potential buffer overread by using `strnchr()` for name
         string validation
       - Return `-EFAULT` on `copy_to_user()` failure to properly handle
         read errors

  Cleanups & Refactoring:
   - Core:
       - Convert various `i2c_device_id` arrays to use named
         initializers for improved robustness and readability
       - Multi-color: Fix incorrect `KernelVersion` and `Date` tags for
         the `multi_max_intensity` ABI
   - Broadcom BCM63138 / ChromeOS EC: Move `MODULE_DEVICE_TABLE`
     declarations next to the ID tables for consistency
   - LP5812: Fix a sysfs ABI reference in the documentation
   - ST1202: Remove an unused legacy GPIO header include

  Device Tree Binding Updates:
   - Class: Document the keyboard backlight LED class naming
     conventions, including a new scheme for zoned backlights
   - Core: Dual-license the common LED bindings header under GPLv2
     and BSD-2-Clause
   - IR SPI LED: Add a new 30% duty-cycle value for the IR transmitter
     used in Xiaomi Redmi Note 8
   - Samsung S2M series:
       - Document the flash LED device bindings for Samsung S2M series
         PMICs
       - Document the pattern behavior for Samsung S2M series PMIC RGB
       - S2MU005: Add device tree bindings for the S2MU005 PMIC,
         including its flash and RGB LED sub-devices
   - TI LM3560: Document the TI LM3559 and LM3560 synchronous boost
     flash drivers"

* tag 'leds-next-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/lee/leds: (30 commits)
  leds: tps6131x: Increase overvoltage protection threshold to 6V
  leds: Fix sysfs ABI date
  leds: Fix CONFIG_OF dependency for LEDS_LP5860_CORE
  leds: uleds: Fix potential buffer overread
  leds: Use named initializers for arrays of i2c_device_data
  leds: uleds: Return -EFAULT on copy_to_user() failure
  leds: core: Report ENODATA for brightness of hardware controlled LED
  leds: class: Use firmware nodes for device lookup
  Documentation: leds: Document pattern behavior of Samsung S2M series PMIC RGB LEDs
  leds: rgb: Add support for Samsung S2M series PMIC RGB LED device
  leds: flash: Add support for Samsung S2M series PMIC flash LED device
  dt-bindings: leds: Document Samsung S2M series PMIC flash LED device
  leds: core: Fix race condition for software blink
  leds: Adjust documentation of brightness sysfs node
  leds: dac124s085: Declare SPI command word as __le16
  leds: Introduce the multi_max_intensity sysfs attribute
  dt-bindings: leds: Document TI LM3560 Synchronous Boost Flash Driver
  leds: bcm63138/cros_ec: Move MODULE_DEVICE_TABLE next to the table itself
  leds: Add support for TI LP5860 LED driver chip
  Documentation: leds: leds-class: Document keyboard backlight LED class naming
  ...

1 files changed, 29 insertions, 1 deletions

diff --git a/include/linux/led-class-multicolor.h b/include/linux/led-class-multicolor.h
index db9f34c6736e..8a05836cae25 100644
--- a/include/linux/led-class-multicolor.h
+++ b/include/linux/led-class-multicolor.h
@@ -9,10 +9,31 @@
 #include <linux/leds.h>
 #include <dt-bindings/leds/common.h>
 
+/**
+ * struct mc_subled - Color component description.
+ * @color_index: Color ID.
+ * @brightness: Scaled intensity.
+ * @intensity: Current intensity.
+ * @max_intensity: Maximum supported intensity value.
+ * @channel: Channel index.
+ *
+ * Describes a color component of a multicolor LED. Many multicolor LEDs
+ * do not support global brightness control in hardware, so they use
+ * the brightness field in connection with led_mc_calc_color_components()
+ * to perform the intensity scaling in software.
+ * Such drivers should set max_intensity to 0 to signal the multicolor LED core
+ * that the maximum global brightness of the LED class device should be used for
+ * limiting incoming intensity values.
+ *
+ * Multicolor LEDs that do support global brightness control in hardware
+ * should instead set max_intensity to the maximum intensity value supported
+ * by the hardware for a given color component.
+ */
 struct mc_subled {
 	unsigned int color_index;
 	unsigned int brightness;
 	unsigned int intensity;
+	unsigned int max_intensity;
 	unsigned int channel;
 };
 
@@ -53,7 +74,14 @@ int led_classdev_multicolor_register_ext(struct device *parent,
  */
 void led_classdev_multicolor_unregister(struct led_classdev_mc *mcled_cdev);
 
-/* Calculate brightness for the monochrome LED cluster */
+/**
+ * led_mc_calc_color_components() - Calculates component brightness values of a LED cluster.
+ * @mcled_cdev - Multicolor LED class device of the LED cluster.
+ * @brightness - Global brightness of the LED cluster.
+ *
+ * Calculates the brightness values for each color component of a monochrome LED cluster,
+ * see Documentation/leds/leds-class-multicolor.rst for details.
+ */
 int led_mc_calc_color_components(struct led_classdev_mc *mcled_cdev,
 				 enum led_brightness brightness);