[PATCH v5 3/4] leds: core: add documentation for color extension

[PATCH v5 3/4] leds: core: add documentation for color extension

[Heiner Kallweit]

Document the color extension in Documentation/leds/leds-class.txt

Signed-off-by: Heiner Kallweit <hkallweit1@gmail.com>
---
v2:
- introduced to patch series
v3:
- document extension in more detail
v4:
- Better explain why flag LED_SET_HUE_SAT is needed
v5:
- no changes
---
 Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt
index d406d98..b1e4cba 100644
--- a/Documentation/leds/leds-class.txt
+++ b/Documentation/leds/leds-class.txt
@@ -8,6 +8,22 @@ LED is defined in max_brightness file. The brightness file will set the brightne
 of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware
 brightness support so will just be turned on for non-zero brightness settings.
 
+If a driver uses the colour extension of the LED core then the brightness
+file can be used to set hue / saturation / value. The brightness value is
+interpreted as: <0000000F><HHHHHHHH><SSSSSSSS><VVVVVVVV>
+Usage of the least byte is identical to monochrome mode. Saturation can be
+0-255 and hue 0-251 (Colour circle is mapped to 0-252).
+If hue and saturation both are 0 the current colour is preserved and only
+the brightness is set. This ensures backwards compatibility with monochrome
+mode, e.g. for led_set_brightness() calls from triggers.
+However we might want to have the option to set all HSV components, even
+if hue and saturation both are 0 (e.g. via brightness sysfs attribute).
+Use case: Set color to white (hue = 0 and saturation = 0).
+Therefore the default behaviour can be overridden with flag F (LED_SET_HUE_SAT).
+If this flag is set then hue and saturation are not checked for being 0 and
+the color components are set unconditionally. Example:
+0x010000ff sets the LED to white color with full brightness.
+
 The class also introduces the optional concept of an LED trigger. A trigger
 is a kernel based source of led events. Triggers can either be simple or
 complex. A simple trigger isn't configurable and is designed to slot into
@@ -45,11 +61,12 @@ Is currently of the form:
 
 "devicename:colour:function"
 
-There have been calls for LED properties such as colour to be exported as
-individual led class attributes. As a solution which doesn't incur as much
-overhead, I suggest these become part of the device name. The naming scheme
-above leaves scope for further attributes should they be needed. If sections
-of the name don't apply, just leave that section blank.
+If the colour extension is used hsv / rgb can be used instead of a specific
+colour.  There have been calls for LED properties such as colour to be
+exported as individual led class attributes. As a solution which doesn't
+incur as much overhead, I suggest these become part of the device name.
+The naming scheme above leaves scope for further attributes should they be
+needed. If sections of the name don't apply, just leave that section blank.
 
 
 Brightness setting API
-- 
2.7.1

Re: [PATCH v5 3/4] leds: core: add documentation for color extension

[Greg KH]

On Tue, Mar 01, 2016 at 10:29:31PM +0100, Heiner Kallweit wrote:
> Document the color extension in Documentation/leds/leds-class.txt
> 
> Signed-off-by: Heiner Kallweit <hkallweit1@gmail.com>
> ---
> v2:
> - introduced to patch series
> v3:
> - document extension in more detail
> v4:
> - Better explain why flag LED_SET_HUE_SAT is needed
> v5:
> - no changes
> ---
>  Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
>  1 file changed, 22 insertions(+), 5 deletions(-)

What aboud Documentation/ABI/ ?

Re: [PATCH v5 3/4] leds: core: add documentation for color extension

[Jacek Anaszewski]

On 03/01/2016 10:41 PM, Greg KH wrote:
> On Tue, Mar 01, 2016 at 10:29:31PM +0100, Heiner Kallweit wrote:
>> Document the color extension in Documentation/leds/leds-class.txt
>>
>> Signed-off-by: Heiner Kallweit <hkallweit1@gmail.com>
>> ---
>> v2:
>> - introduced to patch series
>> v3:
>> - document extension in more detail
>> v4:
>> - Better explain why flag LED_SET_HUE_SAT is needed
>> v5:
>> - no changes
>> ---
>>   Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
>>   1 file changed, 22 insertions(+), 5 deletions(-)
>
> What aboud Documentation/ABI/ ?
>
>

Right, I haven't pushed for this so far, but now, as the functionality
seems to be reaching its final shape, please update also:

Documentation/ABI/testing/sysfs-class-led

-- 
Best regards,
Jacek Anaszewski

Re: [PATCH v5 3/4] leds: core: add documentation for color extension

[Heiner Kallweit]

On Wed, Mar 2, 2016 at 9:38 AM, Jacek Anaszewski
<j.anaszewski@samsung.com> wrote:
> On 03/01/2016 10:41 PM, Greg KH wrote:
>>
>> On Tue, Mar 01, 2016 at 10:29:31PM +0100, Heiner Kallweit wrote:
>>>
>>> Document the color extension in Documentation/leds/leds-class.txt
>>>
>>> Signed-off-by: Heiner Kallweit <hkallweit1@gmail.com>
>>> ---
>>> v2:
>>> - introduced to patch series
>>> v3:
>>> - document extension in more detail
>>> v4:
>>> - Better explain why flag LED_SET_HUE_SAT is needed
>>> v5:
>>> - no changes
>>> ---
>>>   Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
>>>   1 file changed, 22 insertions(+), 5 deletions(-)
>>
>>
>> What aboud Documentation/ABI/ ?
>>
Thanks for the hint. Will update also this part of the documentation.

>>
>
> Right, I haven't pushed for this so far, but now, as the functionality
> seems to be reaching its final shape, please update also:
>
> Documentation/ABI/testing/sysfs-class-led
>
>
> --
> Best regards,
> Jacek Anaszewski