Skip to contentSkip to conversation

leds: core: add documentation for color extension

PATCH In review Heiner Kallweit 2 participants 2 messages Mar 2, 2016 – Mar 4, 2016

Subsystems (2)
Documentation LED
lore
Share & tools
lore

Heiner Kallweit

author
#0 lore raw

PATCH v6 3/4 leds: core: add documentation for color extension

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

Signed-off-by Heiner Kallweit <[email protected]>

---
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
v6:
- add docu for this feature to Documentation/ABI/testing/sysfs-class-led

---
 Documentation/ABI/testing/sysfs-class-led | 11 +++++++++++
 Documentation/leds/leds-class.txt         | 27 ++++++++++++++++++++++-----
 2 files changed, 33 insertions(+), 5 deletions(-)
Documentation/ABI/testing/sysfs-class-led +11 -0
index 3646ec8..20357d5 100644
@@ -7,6 +7,17 @@ Description:
 		have hardware brightness support so will just be turned on for
 		non-zero brightness settings. The value is between 0 and
 		/sys/class/leds/<led>/max_brightness.
+		If a driver uses the RGB LED feature then this attribute is
+		interpreted as a HSV color model value:
+		<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.
+		Flag F enables setting hue and saturation even if both are 0.
+		For details and examples see Documentation/leds/leds-class.txt
 
 What:		/sys/class/leds/<led>/max_brightness
 Date:		March 2006
Documentation/leds/leds-class.txt +22 -5
index d406d98..b1e4cba 100644
@@ -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
Signature · 1 line
2.7.1
#1 lore raw

Hi Heiner,

Please split the sysfs-class-led part to a separate patch.

Quoted 46 lines · Heiner Kallweit

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

Signed-off-by Heiner Kallweit <[email protected]>

---
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
v6:
- add docu for this feature to Documentation/ABI/testing/sysfs-class-led

---
  Documentation/ABI/testing/sysfs-class-led | 11 +++++++++++
  Documentation/leds/leds-class.txt         | 27 ++++++++++++++++++++++-----
  2 files changed, 33 insertions(+), 5 deletions(-)
Documentation/ABI/testing/ renamed from Documentation/ABI/testing/sysfs-class-led +11 -0
index 3646ec8..20357d5 100644
@@ -7,6 +7,17 @@ Description:
  		have hardware brightness support so will just be turned on for
  		non-zero brightness settings. The value is between 0 and
  		/sys/class/leds/<led>/max_brightness.
+		If a driver uses the RGB LED feature then this attribute is
+		interpreted as a HSV color model value:
+		<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.
+		Flag F enables setting hue and saturation even if both are 0.
+		For details and examples see Documentation/leds/leds-class.txt
 
  What:		/sys/class/leds/<led>/max_brightness
  Date:		March 2006
Documentation/leds/leds-class.txt +0 -0
index d406d98..b1e4cba 100644

Documentation/leds/leds-class.txt LED is defined in max_brightness file. The brightness file will set the brightne · line 11

Quoted 4 lines
Documentation/leds/leds-class.txt +1 -0
@@ -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

s/colour/RGB/

Quoted 5 lines
Documentation/leds/leds-class.txt +5 -0
+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

Documentation/leds/leds-class.txt LED is defined in max_brightness file. The brightness file will set the brightne · line 26

Quoted 10 lines
Documentation/leds/leds-class.txt +10 -0
+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.
+

I had to play a bit with RGB<->HSV conversion to get the flavour of the HSV color model, and indeed, changing the brightness byte alone influences only the intensity of the perceived color, despite that all RGB components are changed. Effectively I find this description sufficient.

Documentation/leds/leds-class.txt Is currently of the form: · line 64

Quoted 13 lines
Documentation/leds/leds-class.txt +1 -5
  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

s/colour/RGB/

Quoted 9 lines
Documentation/leds/leds-class.txt +5 -0
+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