leds: multicolor: Introduce a multicolor class definition

What:		/sys/class/leds/<led>/brightness

Date:		March 2020

KernelVersion:	5.9

Contact:	Dan Murphy <dmurphy@ti.com>

Description:	read/write

		Writing to this file will update all LEDs within the group to a

		calculated percentage of what each color LED intensity is set

		to. The percentage is calculated for each grouped LED via the

		equation below:

		led_brightness = brightness * multi_intensity/max_brightness

		For additional details please refer to

		Documentation/leds/leds-class-multicolor.rst.

		The value of the LED is from 0 to

		/sys/class/leds/<led>/max_brightness.

What:		/sys/class/leds/<led>/multi_index

Date:		March 2020

KernelVersion:	5.9

Contact:	Dan Murphy <dmurphy@ti.com>

Description:	read

		The multi_index array, when read, will output the LED colors

		as an array of strings as they are indexed in the

		multi_intensity file.

What:		/sys/class/leds/<led>/multi_intensity

Date:		March 2020

KernelVersion:	5.9

Contact:	Dan Murphy <dmurphy@ti.com>

Description:	read/write

		This file contains array of integers. Order of components is

		described by the multi_index array. The maximum intensity should

		not exceed /sys/class/leds/<led>/max_brightness.

   leds-class

   leds-class-flash

   leds-class-multicolor

   ledtrig-oneshot

   ledtrig-transient

   ledtrig-usbport

.. SPDX-License-Identifier: GPL-2.0

====================================

Multicolor LED handling under Linux

====================================

Description

===========

The multicolor class groups monochrome LEDs and allows controlling two

aspects of the final combined color: hue and lightness. The former is

controlled via the multi_intensity array file and the latter is controlled

via brightness file.

Multicolor Class Control

========================

The multicolor class presents files that groups the colors as indexes in an

array.  These files are children under the LED parent node created by the

led_class framework.  The led_class framework is documented in led-class.rst

within this documentation directory.

Each colored LED will be indexed under the multi_* files. The order of the

colors will be arbitrary. The multi_index file can be read to determine the

color name to indexed value.

The multi_index file is an array that contains the string list of the colors as

they are defined in each multi_* array file.

The multi_intensity is an array that can be read or written to for the

individual color intensities.  All elements within this array must be written in

order for the color LED intensities to be updated.

Directory Layout Example

========================

root:/sys/class/leds/multicolor:status# ls -lR

-rw-r--r--    1 root     root          4096 Oct 19 16:16 brightness

-r--r--r--    1 root     root          4096 Oct 19 16:16 max_brightness

-r--r--r--    1 root     root          4096 Oct 19 16:16 multi_index

-rw-r--r--    1 root     root          4096 Oct 19 16:16 multi_intensity

Multicolor Class Brightness Control

===================================

The brightness level for each LED is calculated based on the color LED

intensity setting divided by the global max_brightness setting multiplied by

the requested brightness.

led_brightness = brightness * multi_intensity/max_brightness

Example:

A user first writes the multi_intensity file with the brightness levels

for each LED that are necessary to achieve a certain color output from a

multicolor LED group.

cat /sys/class/leds/multicolor:status/multi_index

green blue red

echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity

red -

	intensity = 138

	max_brightness = 255

green -

	intensity = 43

	max_brightness = 255

blue -

	intensity = 226

	max_brightness = 255

The user can control the brightness of that multicolor LED group by writing the

global 'brightness' control.  Assuming a max_brightness of 255 the user

may want to dim the LED color group to half.  The user would write a value of

128 to the global brightness file then the values written to each LED will be

adjusted base on this value.

cat /sys/class/leds/multicolor:status/max_brightness

255

echo 128 > /sys/class/leds/multicolor:status/brightness

adjusted_red_value = 128 * 138/255 = 69

adjusted_green_value = 128 * 43/255 = 21

adjusted_blue_value = 128 * 226/255 = 113

Reading the global brightness file will return the current brightness value of

the color LED group.

cat /sys/class/leds/multicolor:status/brightness

128

	  for the flash related features of a LED device. It can be built

	  as a module.

config LEDS_CLASS_MULTICOLOR

	tristate "LED Multicolor Class Support"

	depends on LEDS_CLASS

	help

	  This option enables the multicolor LED sysfs class in /sys/class/leds.

	  It wraps LED class and adds multicolor LED specific sysfs attributes

	  and kernel internal API to it. You'll need this to provide support

	  for multicolor LEDs that are grouped together. This class is not

	  intended for single color LEDs. It can be built as a module.

config LEDS_BRIGHTNESS_HW_CHANGED

	bool "LED Class brightness_hw_changed attribute support"

	depends on LEDS_CLASS

obj-$(CONFIG_NEW_LEDS)			+= led-core.o

obj-$(CONFIG_LEDS_CLASS)		+= led-class.o

obj-$(CONFIG_LEDS_CLASS_FLASH)		+= led-class-flash.o

obj-$(CONFIG_LEDS_CLASS_MULTICOLOR)	+= led-class-multicolor.o

obj-$(CONFIG_LEDS_TRIGGERS)		+= led-triggers.o

# LED Platform Drivers (keep this sorted, M-| sort)