Re: [RFC PATCH 3/5] documention: leds: Add multicolor class documentation

[Randy Dunlap <rdunlap@infradead.org>]

Hi,

On 4/1/19 10:33 AM, Dan Murphy wrote:
> Add the support documentation on the multicolor LED framework.
> This document defines the directores and file generated by the

                            directories and files

> multicolor framework.  It also documents usage.
> 
> Signed-off-by: Dan Murphy <dmurphy@ti.com>
> ---
>  Documentation/leds/leds-class-multicolor.txt | 99 ++++++++++++++++++++
>  1 file changed, 99 insertions(+)
>  create mode 100644 Documentation/leds/leds-class-multicolor.txt
> 
> diff --git a/Documentation/leds/leds-class-multicolor.txt b/Documentation/leds/leds-class-multicolor.txt
> new file mode 100644
> index 000000000000..8112b99a7668
> --- /dev/null
> +++ b/Documentation/leds/leds-class-multicolor.txt
> @@ -0,0 +1,99 @@
> +
> +Multi Color LED handling under Linux
> +=================================================
> +
> +Authors: Dan Murphy <dmurphy@ti.com>

or Author:

> +
> +Description
> +-----------
> +There are varying monochrome LED colors available for application.  These
> +LEDs can be used as a single use case LED or can be mixed with other color
> +LEDs to produce the full spectrum of color.  Color LEDs that are grouped
> +can be presented under a single LED node with individual color control.
> +The multicolor class groups these LEDs and allows dynamically setting the value
> +of a single LED or setting the brightness values of the LEDs in the group and
> +updating the LEDs virtually simultaneously.
> +
> +Multicolor Class Control
> +-------------------------
> +The multicolor class presents the LED groups under a directory called "colors".
> +This directory is a child under the LED parent node created but the led_class

                                                       created by

> +framework.  The led_class framework is documented in led-class.txt within this
> +documentation directory. 
> +
> +Each colored LED is given it's own directory.  These directories can be but not

                             its                                    huh???????????

> +limited to red, green, blue, white, amber, yellow and violet.  Under these
> +directories the brightness and max_brightness files are presented for each LED.
> +
> +Under the "colors" directory there are two files created "sync" and

                                                    created:

> +"sync_enable". The sync_enable file controls whether the LED brightness
> +value is set real time or if the LED brightness value setting is deferred until
> +the "sync" file is written.  If sync_enable is set then writing to each LED
> +"brightness" file will store the brightness value.  Once the "sync" file is
> +written then each LED color defined in the node will write the brightness of
> +the LED in the device driver.
> +
> +If "sync_enable" is not set then writing the brightness value of the LED to the
> +device driver is done immediately.  Writing the "sync" file has no affect.
> +
> +Directory Layout Example
> +------------------------
> +root:/sys/class/leds/rgb:grouped_leds# ls -lR colors/
> +colors/:
> +drwxr-xr-x    2 root     root             0 Jun 28 20:21 blue
> +drwxr-xr-x    2 root     root             0 Jun 28 20:21 green
> +drwxr-xr-x    2 root     root             0 Jun 28 20:21 red
> +--w-------    1 root     root          4096 Jun 28 20:21 sync
> +-rw-------    1 root     root          4096 Jun 28 20:22 sync_enable
> +
> +colors/blue:
> +-rw-------    1 root     root          4096 Jun 28 20:21 brightness
> +-r--------    1 root     root          4096 Jun 28 20:27 max_brightness
> +
> +colors/green:
> +-rw-------    1 root     root          4096 Jun 28 20:22 brightness
> +-r--------    1 root     root          4096 Jun 28 20:27 max_brightness
> +
> +colors/red:
> +-rw-------    1 root     root          4096 Jun 28 20:21 brightness
> +-r--------    1 root     root          4096 Jun 28 20:27 max_brightness
> +
> +Example of Writing LEDs with Sync Enabled
> +-----------------------------------------
> +Below the red, green and blue LEDs are set to corresponding values.  These
> +values are stored and not written until the sync file is written.
> +
> +cd /sys/class/leds/rgb:grouped_leds/colors
> +
> +echo 1 > sync_enable
> +
> +echo 100 > red/brightness
> +echo 80 > green/brightness
> +echo 180 > blue/brightness
> +
> +* LED device driver has not been updated and the LED states have not changed.
> +* Writing the LED brightness files again will only change the stored value and
> +* not the device driver value.
> +
> +echo 1 > sync
> +
> +* LED device driver has been updated the LEDs should present the brightness

                                updated; the LEDs

> +* levels that have been set.  Since sync_enable is still enabled writing to the
> +* LED brightness files will not change the current brightnesses.
> +
> +Example of Writing LEDs with Sync Disabled
> +------------------------------------------
> +Below the values of each LED are written to the device driver immediately upon
> +request.
> +
> +cd /sys/class/leds/rgb:grouped_leds/colors
> +
> +echo 0 > sync_enable
> +
> +echo 100 > red/brightness // Red LED should be on with the current brightness
> +echo 80 > green/brightness // Green LED should be on with the current brightness
> +echo 180 > blue/brightness // Blue LED should be on with the current brightness
> +.
> +.
> +.
> +echo 0 > green/brightness // Green LED should be off
> 

cheers.
-- 
~Randy