leds: core: add documentation for color extension

PATCH Superseded Heiner Kallweit 2 participants 6 messages Feb 25, 2016 – Mar 2, 2016

Subsystems (2)

Documentation LED

lore

Share & tools

lore

Heiner Kallweit

author

2016-02-25 22:17 UTC #0 lore raw

PATCH v4 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

---
 Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

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

Jacek Anaszewski

2016-02-29 16:14 UTC #1 lore raw

Quoted 27 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

---
  Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
  1 file changed, 22 insertions(+), 5 deletions(-)

Documentation/leds/leds-class.txt +5 -0

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).

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

Quoted 10 lines

Documentation/leds/leds-class.txt +10 -0

+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.

I was thinking especially about highlighting the use case when we set different hue and sat for different LEDs that are registered on some trigger, and a driver that is currently unaware of LED RGB extension can set only brightness and the LEDs will react with changing their colors but each of them in different manner, according to the hue and sat set.

Quoted 22 lines

Documentation/leds/leds-class.txt +6 -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
+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 · 2 lines

Best regards,
Jacek Anaszewski

Heiner Kallweit

author

2016-02-29 20:25 UTC #2 lore raw

Am 29.02.2016 um 17:14 schrieb Jacek Anaszewski:

Quoted 37 lines · Heiner Kallweit

Quoted 36 lines

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

---
  Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
  1 file changed, 22 insertions(+), 5 deletions(-)

Documentation/leds/leds-class.txt +14 -0

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:

Quoted 9 lines

Documentation/leds/leds-class.txt LED is defined in max_brightness file. The brightness file will set the brightne · line 25
Quoted 1 line
Documentation/leds/leds-class.txt +1 -0
+0x010000ff sets the LED to white color with full brightness.
I was thinking especially about highlighting the use case when we set different hue and sat for different LEDs that are registered on some trigger, and a driver that is currently unaware of LED RGB extension can set only brightness and the LEDs will react with changing their colors but each of them in different manner, according to the hue and sat set.

I have to admit that I have a hard time trying to understand what you mean. With "a driver that is currently unaware of LED RGB extension can set only brightness" you mean a driver calling led_trigger_event?
Arguments to led_trigger_event are always <= LED_FULL what means that the (potential) color of all LEDs attached to the trigger isn't touched.

Quoted 24 lines

Quoted 22 lines

Documentation/leds/leds-class.txt +6 -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
+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

Jacek Anaszewski

2016-03-01 09:26 UTC #3 lore raw

Quoted 47 lines · Heiner Kallweit

Am 29.02.2016 um 17:14 schrieb Jacek Anaszewski:
Quoted 37 lines · Heiner Kallweit
Quoted 36 lines
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
---
   Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
   1 file changed, 22 insertions(+), 5 deletions(-)
Documentation/leds/leds-class.txt +14 -0
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:
Quoted 9 lines
Documentation/leds/leds-class.txt LED is defined in max_brightness file. The brightness file will set the brightne · line 25
Quoted 1 line
Documentation/leds/leds-class.txt +1 -0
+0x010000ff sets the LED to white color with full brightness.
I was thinking especially about highlighting the use case when we set different hue and sat for different LEDs that are registered on some trigger, and a driver that is currently unaware of LED RGB extension can set only brightness and the LEDs will react with changing their colors but each of them in different manner, according to the hue and sat set.

Quoted 1 line

I have to admit that I have a hard time trying to understand what you mean.

I was writing this in a hurry - sorry about that.

Quoted 5 lines

With
"a driver that is currently unaware of LED RGB extension can set only brightness" you mean a driver calling led_trigger_event?
Arguments to led_trigger_event are always <= LED_FULL what means that the (potential) color of all LEDs attached to the trigger isn't touched.

Changing brightness in HSV model influences resultant color, doesn't it?

Quoted 27 lines

Quoted 24 lines

Quoted 22 lines

Documentation/leds/leds-class.txt +6 -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
+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 · 2 lines

Best regards,
Jacek Anaszewski

Heiner Kallweit

author

2016-03-01 20:52 UTC #4 lore raw

Am 01.03.2016 um 10:25 schrieb Jacek Anaszewski:

Quoted 52 lines · Heiner Kallweit

Quoted 47 lines
Am 29.02.2016 um 17:14 schrieb Jacek Anaszewski:
Quoted 37 lines · Heiner Kallweit
Quoted 36 lines
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
---
   Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
   1 file changed, 22 insertions(+), 5 deletions(-)
Documentation/leds/leds-class.txt +14 -0
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:
Quoted 9 lines
Documentation/leds/leds-class.txt LED is defined in max_brightness file. The brightness file will set the brightne · line 25
Quoted 1 line
Documentation/leds/leds-class.txt +1 -0
+0x010000ff sets the LED to white color with full brightness.
I was thinking especially about highlighting the use case when we set different hue and sat for different LEDs that are registered on some trigger, and a driver that is currently unaware of LED RGB extension can set only brightness and the LEDs will react with changing their colors but each of them in different manner, according to the hue and sat set.
Quoted 1 line
I have to admit that I have a hard time trying to understand what you mean.
I was writing this in a hurry - sorry about that.

Quoted 8 lines

Quoted 5 lines
With
"a driver that is currently unaware of LED RGB extension can set only brightness" you mean a driver calling led_trigger_event?
Arguments to led_trigger_event are always <= LED_FULL what means that the (potential) color of all LEDs attached to the trigger isn't touched.
Changing brightness in HSV model influences resultant color, doesn't it?

Not in general, see led_rgb_adjust_hue_sat().
If brightness <= LED_FULL then hue and sat aren't touched. Only the value component is changed.

Quoted 29 lines

Quoted 27 lines

Quoted 24 lines

Quoted 22 lines

Documentation/leds/leds-class.txt +6 -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
+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

Jacek Anaszewski

2016-03-02 08:25 UTC #5 lore raw

Quoted 59 lines · Heiner Kallweit

Am 01.03.2016 um 10:25 schrieb Jacek Anaszewski:
Quoted 58 lines · Heiner Kallweit
Quoted 47 lines
Am 29.02.2016 um 17:14 schrieb Jacek Anaszewski:
Quoted 37 lines · Heiner Kallweit
Quoted 36 lines
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
---
    Documentation/leds/leds-class.txt | 27 ++++++++++++++++++++++-----
    1 file changed, 22 insertions(+), 5 deletions(-)
Documentation/leds/leds-class.txt +14 -0
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:
Quoted 9 lines
Documentation/leds/leds-class.txt LED is defined in max_brightness file. The brightness file will set the brightne · line 25
Quoted 1 line
Documentation/leds/leds-class.txt +1 -0
+0x010000ff sets the LED to white color with full brightness.
I was thinking especially about highlighting the use case when we set different hue and sat for different LEDs that are registered on some trigger, and a driver that is currently unaware of LED RGB extension can set only brightness and the LEDs will react with changing their colors but each of them in different manner, according to the hue and sat set.
Quoted 1 line
I have to admit that I have a hard time trying to understand what you mean.
I was writing this in a hurry - sorry about that.
Quoted 5 lines
With
"a driver that is currently unaware of LED RGB extension can set only brightness" you mean a driver calling led_trigger_event?
Arguments to led_trigger_event are always <= LED_FULL what means that the (potential) color of all LEDs attached to the trigger isn't touched.

Quoted 5 lines

Quoted 2 lines
Changing brightness in HSV model influences resultant color, doesn't it?
Not in general, see led_rgb_adjust_hue_sat().
If brightness <= LED_FULL then hue and sat aren't touched. Only the value component is changed.

Right, but change in value entails change in all three R G B components, which together compose resultant color.

Quoted 32 lines

Quoted 29 lines

Quoted 27 lines

Quoted 24 lines

Quoted 22 lines

Documentation/leds/leds-class.txt +6 -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
+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 · 2 lines

Best regards,
Jacek Anaszewski