Skip to contentSkip to conversation

leds: multicolor: Add sysfs interface definition

RFC PATCH In review Dan Murphy 4 participants 12 messages Jan 30, 2019 – Feb 8, 2019 LED

lore
Share & tools
lore

Dan Murphy

author
#0 lore raw

RFC PATCH 1/1 leds: multicolor: Add sysfs interface definition

Add a documentation of LED Multicolor LED class specific sysfs attributes.

---
 .../ABI/testing/sysfs-class-led-multicolor    | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-led-multicolor
Documentation/ABI/testing/sysfs-class-led-multicolor new file +38 -0
new file mode 100644
index 000000000000..19f8da9b150e
@@ -0,0 +1,38 @@
+What:		/sys/class/leds/<led>/color/sync_enable
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	read/write
+		Writing a 1 to this file will enable the sychronization of all
+		the defined color LEDs within the LED node.  Writing a 0 to
+		this file will disable syncing.
+
+What:		/sys/class/leds/<led>/color/sync
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	write only
+		Writing a 1 to this file while sync_enable is set to 1 will
+		synchronize all defined LEDs within the LED node.  All LEDs
+		defined will be configured based on the brightness that has
+		been requested.
+
+		If sync_enable is set to 0 then writing a 1 to sync has no
+		affect on the LEDs.
+
+What:		/sys/class/leds/<led>/color/<led color>
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	read/write
+		These files are dynamically created based on the colors defined
+		by the registrar of the class.
+		The led color(s) can be but not limited to red, green, blue,
+		white, amber and violet.  If sync is enabled then writing the
+		brightness value of the LED is deferred until a 1 is
+		written to /sys/class/leds/<led>/color/sync.  If syncing is
+		disabled then the LED brightness value will be written
+		immediately to the LED driver.
+
+		The value of the color is from 0 to
+		/sys/class/leds/<led>/max_brightness.
Signature · 1 line
2.20.1.98.gecbdaf0899
#1 lore raw

Hi Dan,

Thank you for the RFC.

One vital thing is missing - documentation of brightness file must be updated to define its semantics for LED multi color class.

Either we need brightness-model file returning only "onoff" option available, or, for time being, fix the max_brightness for LED multi color class to 1 (which will map to max intensity level for each color).

Best regards,
Jacek Anaszewski

Quoted 54 lines · Dan Murphy

Add a documentation of LED Multicolor LED class specific sysfs attributes.

---
  .../ABI/testing/sysfs-class-led-multicolor    | 38 +++++++++++++++++++
  1 file changed, 38 insertions(+)

create mode 100644 Documentation/ABI/testing/sysfs-class-led-multicolor

Documentation/ABI/testing/sysfs-class-led-multicolor new file +38 -0
new file mode 100644
index 000000000000..19f8da9b150e
@@ -0,0 +1,38 @@
+What:		/sys/class/leds/<led>/color/sync_enable
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	read/write
+		Writing a 1 to this file will enable the sychronization of all
+		the defined color LEDs within the LED node.  Writing a 0 to
+		this file will disable syncing.
+
+What:		/sys/class/leds/<led>/color/sync
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	write only
+		Writing a 1 to this file while sync_enable is set to 1 will
+		synchronize all defined LEDs within the LED node.  All LEDs
+		defined will be configured based on the brightness that has
+		been requested.
+
+		If sync_enable is set to 0 then writing a 1 to sync has no
+		affect on the LEDs.
+
+What:		/sys/class/leds/<led>/color/<led color>
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	read/write
+		These files are dynamically created based on the colors defined
+		by the registrar of the class.
+		The led color(s) can be but not limited to red, green, blue,
+		white, amber and violet.  If sync is enabled then writing the
+		brightness value of the LED is deferred until a 1 is
+		written to /sys/class/leds/<led>/color/sync.  If syncing is
+		disabled then the LED brightness value will be written
+		immediately to the LED driver.
+
+		The value of the color is from 0 to
+		/sys/class/leds/<led>/max_brightness.
author
#2 lore raw

Jacek

Quoted 11 lines · Jacek Anaszewski

Hi Dan,

Thank you for the RFC.

One vital thing is missing - documentation of brightness file must be updated to define its semantics for LED multi color class.

Either we need brightness-model file returning only "onoff" option available, or, for time being, fix the max_brightness for LED multi color class to 1 (which will map to max intensity level for each color).

I can make max_brightness default to 1 if not set by the LED driver.

But the LP50xx has brightness controls so setting max_brightness from the driver should over ride the max of 1 in the upper level.

For devices that do not support brightness as a separate control we can create a file called max_brightness_<color> that defines the max that a specific color can be set to. If max_brightness is set to 1 then create max_brightness_<color>. If max_brightness > 1 then do not create the files.

I don't think we have fully vetted the brightness-model yet so I prefer to omit it and possibly introduce that later.

Dan

Quoted 59 lines

Best regards,
Jacek Anaszewski

Quoted 54 lines · Dan Murphy

Add a documentation of LED Multicolor LED class specific sysfs attributes.

---
  .../ABI/testing/sysfs-class-led-multicolor    | 38 +++++++++++++++++++

  1 file changed, 38 insertions(+)

  create mode 100644 Documentation/ABI/testing/sysfs-class-led-multicolor

Documentation/ABI/testing/sysfs-class-led-multicolor new file +38 -0
new file mode 100644
index 000000000000..19f8da9b150e
@@ -0,0 +1,38 @@
+What:        /sys/class/leds/<led>/color/sync_enable
+Date:        January 2019
+KernelVersion:    5.0
+Contact:    Dan Murphy <[email protected]>
+Description:    read/write
+        Writing a 1 to this file will enable the sychronization of all
+        the defined color LEDs within the LED node.  Writing a 0 to
+        this file will disable syncing.
+
+What:        /sys/class/leds/<led>/color/sync
+Date:        January 2019
+KernelVersion:    5.0
+Contact:    Dan Murphy <[email protected]>
+Description:    write only
+        Writing a 1 to this file while sync_enable is set to 1 will
+        synchronize all defined LEDs within the LED node.  All LEDs
+        defined will be configured based on the brightness that has
+        been requested.
+
+        If sync_enable is set to 0 then writing a 1 to sync has no
+        affect on the LEDs.
+
+What:        /sys/class/leds/<led>/color/<led color>
+Date:        January 2019
+KernelVersion:    5.0
+Contact:    Dan Murphy <[email protected]>
+Description:    read/write
+        These files are dynamically created based on the colors defined
+        by the registrar of the class.
+        The led color(s) can be but not limited to red, green, blue,
+        white, amber and violet.  If sync is enabled then writing the
+        brightness value of the LED is deferred until a 1 is
+        written to /sys/class/leds/<led>/color/sync.  If syncing is
+        disabled then the LED brightness value will be written
+        immediately to the LED driver.
+
+        The value of the color is from 0 to
+        /sys/class/leds/<led>/max_brightness.
Signature · 2 lines
------------------
Dan Murphy
#3 lore raw

Dan,

Quoted 15 lines · Dan Murphy

Jacek

Quoted 11 lines · Jacek Anaszewski

Hi Dan,

Thank you for the RFC.

One vital thing is missing - documentation of brightness file must be updated to define its semantics for LED multi color class.

Either we need brightness-model file returning only "onoff" option available, or, for time being, fix the max_brightness for LED multi color class to 1 (which will map to max intensity level for each color).

Quoted 4 lines

I can make max_brightness default to 1 if not set by the LED driver.

But the LP50xx has brightness controls so setting max_brightness from the driver should over ride the max of 1 in the upper level.

Yes, so the max_brightness should be updated basing on current brightness-model. For LEDn_BRIGHTNESS of LP50xx we could have "hw" or maybe even better just "lp50xx-linear" and "lp50xx-logarithmic"
- I just forgot about that capability of the device.

Quoted 3 lines

For devices that do not support brightness as a separate control we can create a file called max_brightness_<color> that defines the max that a specific color can be set to. If max_brightness is set to 1 then create max_brightness_<color>. If max_brightness > 1 then do not create the files.

Right. We will need dedicated max_brightness for each color. They should be placed also in the colors directory, next to the color files.

Quoted 2 lines

I don't think we have fully vetted the brightness-model yet so I prefer to omit it and possibly introduce that later.

We need to start from something. It will give better overview of the whole idea.

Best regards,
Jacek Anaszewski

Quoted 63 lines

Dan

Quoted 59 lines

Best regards,
Jacek Anaszewski

Quoted 54 lines · Dan Murphy

Add a documentation of LED Multicolor LED class specific sysfs attributes.

---
   .../ABI/testing/sysfs-class-led-multicolor    | 38 +++++++++++++++++++
   1 file changed, 38 insertions(+)

  create mode 100644 Documentation/ABI/testing/sysfs-class-led-multicolor

Documentation/ABI/testing/sysfs-class-led-multicolor new file +38 -0
new file mode 100644
index 000000000000..19f8da9b150e
@@ -0,0 +1,38 @@
+What:        /sys/class/leds/<led>/color/sync_enable
+Date:        January 2019
+KernelVersion:    5.0
+Contact:    Dan Murphy <[email protected]>
+Description:    read/write
+        Writing a 1 to this file will enable the sychronization of all
+        the defined color LEDs within the LED node.  Writing a 0 to
+        this file will disable syncing.
+
+What:        /sys/class/leds/<led>/color/sync
+Date:        January 2019
+KernelVersion:    5.0
+Contact:    Dan Murphy <[email protected]>
+Description:    write only
+        Writing a 1 to this file while sync_enable is set to 1 will
+        synchronize all defined LEDs within the LED node.  All LEDs
+        defined will be configured based on the brightness that has
+        been requested.
+
+        If sync_enable is set to 0 then writing a 1 to sync has no
+        affect on the LEDs.
+
+What:        /sys/class/leds/<led>/color/<led color>
+Date:        January 2019
+KernelVersion:    5.0
+Contact:    Dan Murphy <[email protected]>
+Description:    read/write
+        These files are dynamically created based on the colors defined
+        by the registrar of the class.
+        The led color(s) can be but not limited to red, green, blue,
+        white, amber and violet.  If sync is enabled then writing the
+        brightness value of the LED is deferred until a 1 is
+        written to /sys/class/leds/<led>/color/sync.  If syncing is
+        disabled then the LED brightness value will be written
+        immediately to the LED driver.
+
+        The value of the color is from 0 to
+        /sys/class/leds/<led>/max_brightness.
author
#4 lore raw

Jacek

Quoted 20 lines · Jacek Anaszewski

Dan,

Quoted 17 lines · Dan Murphy

Jacek

Quoted 11 lines · Jacek Anaszewski

Hi Dan,

Thank you for the RFC.

One vital thing is missing - documentation of brightness file must be updated to define its semantics for LED multi color class.

Either we need brightness-model file returning only "onoff" option available, or, for time being, fix the max_brightness for LED multi color class to 1 (which will map to max intensity level for each color).

I can make max_brightness default to 1 if not set by the LED driver.

Quoted 8 lines
Quoted 2 lines

But the LP50xx has brightness controls so setting max_brightness from the driver should over ride the max of 1 in the upper level.

Yes, so the max_brightness should be updated basing on current brightness-model. For LEDn_BRIGHTNESS of LP50xx we could have "hw" or maybe even better just "lp50xx-linear" and "lp50xx-logarithmic"
- I just forgot about that capability of the device.

OK maybe "hw" would make sense as there may be other devices that have dedicated brightness controls over color controls.

Probably need to create a model for non-modeled cases like "rgb-independent". Dumb name but I could not think of anything better.

Quoted 8 lines
Quoted 3 lines

For devices that do not support brightness as a separate control we can create a file called max_brightness_<color> that defines the max that a specific color can be set to.  If max_brightness is set to 1 then create max_brightness_<color>.  If max_brightness > 1 then do not create the files.

Right. We will need dedicated max_brightness for each color. They should be placed also in the colors directory, next to the color files.

OK will document this.

Quoted 6 lines
Quoted 2 lines

I don't think we have fully vetted the brightness-model yet so I prefer to omit it and possibly introduce that later.

We need to start from something. It will give better overview of the whole idea.

OK. Don't get me wrong I don't oppose this idea I am just trying to figure out how the user space would know what models and brightness levels are available.

I mean we can read the brightness-models and present the available models but then how does the user know what and how many levels are in each model? And how do we govern putting them in the right order?

The DT file can get messed up, per the previous example rgb-green = <0x277c33 0x37b048 0x47e45d>;

This is assumed to be from dimmest to brightest. But that is just an assumption

What if the entry looked like this?
rgb-green = <0x37b048 0x277c33 0x47e45d>;

Then echo 1 > brightness is not really a lower intensity then echo 2 > brightness. I know this is a product level issue but this can be misused and there is no way for maintainers or reviewers to really catch this error in code reviews.

The driver can map the brightness to the appropriate level requested by the class but again not sure how the user space can know what is available. And there is nothing from stopping a definition of up to 2^32 brightness combinations. This I know is unrealistic but the capability is there

I am wondering if there should be some sort of coefficient that can be defined that is applied to each color (no complex math). I can see this working in a linear device but logrithimic maybe an issue.

Like

rgb-green = <0x277c33>; //Coefficient used to set the dimmest allowed brightness for the color model.

echo 1 > brightness

red = 0x27
green = 0x7c
blue = 0x33

echo 2 > brightness

red = 0x28
green = 0x7d
blue = 0x34

echo 3 > brightness

red = 0x29
green = 0x7e
blue = 0x35

This example would give you 132 different brightness levels. green is the brightest defined color so the step calculation is

255-124+1 = 132 (zero based) as 0 is off.

There can be a file called rgb_green_max which can be read to indicate how many brightness levels can be achieved. If the user goes beyond the steps then throw -EINVAL at them.

These brightness models probably should be put into a separate directory to isolate and not clutter the colors directory. And writing brightness to these models would be immediate no sync involved.

Dan

Quoted 5 lines

Best regards,
Jacek Anaszewski

Quoted 2 lines

Dan

<snip>--
------------------
Dan Murphy

#5 lore raw

Dan,

Quoted 26 lines · Dan Murphy

Jacek

Quoted 23 lines · Jacek Anaszewski

Dan,

Quoted 19 lines · Dan Murphy

Jacek

Quoted 11 lines · Jacek Anaszewski

Hi Dan,

Thank you for the RFC.

One vital thing is missing - documentation of brightness file must be updated to define its semantics for LED multi color class.

Either we need brightness-model file returning only "onoff" option available, or, for time being, fix the max_brightness for LED multi color class to 1 (which will map to max intensity level for each color).

I can make max_brightness default to 1 if not set by the LED driver.

But the LP50xx has brightness controls so setting max_brightness from the driver should over ride the max of 1 in the upper level.

Quoted 8 lines
Quoted 5 lines

Yes, so the max_brightness should be updated basing on current brightness-model. For LEDn_BRIGHTNESS of LP50xx we could have "hw" or maybe even better just "lp50xx-linear" and "lp50xx-logarithmic"
- I just forgot about that capability of the device.

OK maybe "hw" would make sense as there may be other devices that have dedicated brightness controls over color controls.

Single "hw" doesn't address both linear and logarithmic. This is device specific, so I don't see anything wrong in "lp50xx-*", provided that it will be documented.

Quoted 2 lines

Probably need to create a model for non-modeled cases like "rgb-independent". Dumb name but I could not think of anything better.

There is no point in having any rgb* brightness model since increasing rgb in an arbitrary way will not give the impression of increasing color intensity (lightness of the same hue). With DT defined hsl-<color> ranges there is no way to verify that levels arrangement makes sense with regard to preserving hue, this is a matter of trust. But we should state that it is highly recommended to obey this constraint so as to not mislead users.

Quoted 14 lines
Quoted 8 lines
Quoted 3 lines

For devices that do not support brightness as a separate control we can create a file called max_brightness_<color> that defines the max that a specific color can be set to.  If max_brightness is set to 1 then create max_brightness_<color>.  If max_brightness > 1 then do not create the files.

Right. We will need dedicated max_brightness for each color. They should be placed also in the colors directory, next to the color files.

OK will document this.

Quoted 3 lines
Quoted 2 lines

I don't think we have fully vetted the brightness-model yet so I prefer to omit it and possibly introduce that later.

Quoted 6 lines
Quoted 3 lines

We need to start from something. It will give better overview of the whole idea.

OK. Don't get me wrong I don't oppose this idea I am just trying to figure out how the user space would know what models and brightness levels are available.

$ cat brightness-model
lp50xx-linear lp50xx-logarithmic onoff hsl-green hsl=blue

max_brightness will return available number of brightness levels for each brightness model.

I'd not bother with presenting whole range of available color presets. Userspace can verify the brightness->color mapping by reading colors/<color> files after setting given brightness level.

However, I'm not sure how useful it will be. This is a gist of this whole discussion - we cannot be certain about exact color effect produced with given settings.

Quoted 2 lines

I mean we can read the brightness-models and present the available models but then how does the user know what and how many levels are in each model? And how do we govern putting them in the right order?

cat max_brightness will return number of levels for the model currently set. Regarding the order - we must rely on the DT array arrangement. In case of hardware originated brightness model we must trust hardware implementation.

Quoted 7 lines

The DT file can get messed up, per the previous example rgb-green = <0x277c33 0x37b048 0x47e45d>;

This is assumed to be from dimmest to brightest. But that is just an assumption

What if the entry looked like this?
rgb-green = <0x37b048 0x277c33 0x47e45d>;

We can do nothing. It is just the cost of leaving some decisions to DT.

Quoted 36 lines

Then echo 1 > brightness is not really a lower intensity then echo 2 > brightness. I know this is a product level issue but this can be misused and there is no way for maintainers or reviewers to really catch this error in code reviews.

The driver can map the brightness to the appropriate level requested by the class but again not sure how the user space can know what is available. And there is nothing from stopping a definition of up to 2^32 brightness combinations. This I know is unrealistic but the capability is there

I am wondering if there should be some sort of coefficient that can be defined that is applied to each color (no complex math). I can see this working in a linear device but logrithimic maybe an issue.

Like

rgb-green = <0x277c33>; //Coefficient used to set the dimmest allowed brightness for the color model.

echo 1 > brightness

red = 0x27
green = 0x7c
blue = 0x33

echo 2 > brightness

red = 0x28
green = 0x7d
blue = 0x34

echo 3 > brightness

red = 0x29
green = 0x7e
blue = 0x35

This example would give you 132 different brightness levels. green is the brightest defined color so the step calculation is

Quoted 7 lines

255-124+1 = 132 (zero based) as 0 is off.

There can be a file called rgb_green_max which can be read to indicate how many brightness levels can be achieved. If the user goes beyond the steps then throw -EINVAL at them.

These brightness models probably should be put into a separate directory to isolate and not clutter the colors directory. And writing brightness to these models would be immediate no sync involved.

I intended that brightness-model location would be the main LED class device directory.

And the whole concept is simple. We allow to set what we get from DT or from the hardware. Without verification exceeding beyond max_brightness values defined per iout.

Signature · 2 lines
Best regards,
Jacek Anaszewski
author
#6 lore raw

Jacek

Quoted 35 lines · Jacek Anaszewski

Dan,

Quoted 32 lines · Dan Murphy

Jacek

Quoted 28 lines · Jacek Anaszewski

Dan,

Quoted 15 lines · Dan Murphy

Jacek

Quoted 11 lines · Jacek Anaszewski

Hi Dan,

Thank you for the RFC.

One vital thing is missing - documentation of brightness file must be updated to define its semantics for LED multi color class.

Either we need brightness-model file returning only "onoff" option available, or, for time being, fix the max_brightness for LED multi color class to 1 (which will map to max intensity level for each color).

Quoted 4 lines

I can make max_brightness default to 1 if not set by the LED driver.

But the LP50xx has brightness controls so setting max_brightness from the driver should over ride the max of 1 in the upper level.

Yes, so the max_brightness should be updated basing on current brightness-model. For LEDn_BRIGHTNESS of LP50xx we could have "hw" or maybe even better just "lp50xx-linear" and "lp50xx-logarithmic"
- I just forgot about that capability of the device.

Quoted 7 lines
Quoted 2 lines

OK maybe "hw" would make sense as there may be other devices that have dedicated brightness controls over color controls.

Single "hw" doesn't address both linear and logarithmic. This is device specific, so I don't see anything wrong in "lp50xx-*", provided that it will be documented.

OK. This would need to be lp50xx specific.

Quoted 11 lines
Quoted 2 lines

Probably need to create a model for non-modeled cases like "rgb-independent".  Dumb name but I could not think of anything better.

There is no point in having any rgb* brightness model since increasing rgb in an arbitrary way will not give the impression of increasing color intensity (lightness of the same hue). With DT defined hsl-<color> ranges there is no way to verify that levels arrangement makes sense with regard to preserving hue, this is a matter of trust. But we should state that it is highly recommended to obey this constraint so as to not mislead users.

OK. I will document this in v2 for discussion

Quoted 18 lines
Quoted 18 lines
Quoted 8 lines
Quoted 3 lines

For devices that do not support brightness as a separate control we can create a file called max_brightness_<color> that defines the max that a specific color can be set to.  If max_brightness is set to 1 then create max_brightness_<color>.  If max_brightness > 1 then do not create the files.

Right. We will need dedicated max_brightness for each color. They should be placed also in the colors directory, next to the color files.

OK will document this.

Quoted 6 lines
Quoted 2 lines

I don't think we have fully vetted the brightness-model yet so I prefer to omit it and possibly introduce that later.

We need to start from something. It will give better overview of the whole idea.

Quoted 9 lines
Quoted 2 lines

OK.  Don't get me wrong I don't oppose this idea I am just trying to figure out how the user space would know what models and brightness levels are available.

$ cat brightness-model
lp50xx-linear lp50xx-logarithmic onoff hsl-green hsl=blue

max_brightness will return available number of brightness levels for each brightness model.

So max_brightness here would be dynamic?
Or could we read hsl-<color> and get the number of levels and not mess with the max_brightness definition?

Or should that be the current level?

Quoted 5 lines

I'd not bother with presenting whole range of available color presets. Userspace can verify the brightness->color mapping by reading colors/<color> files after setting given brightness level.

Userspace would have to have knowledge of the values set in order to verify the color values.

Quoted 4 lines

However, I'm not sure how useful it will be. This is a gist of this whole discussion - we cannot be certain about exact color effect produced with given settings.

Quoted 8 lines
Quoted 2 lines

I mean we can read the brightness-models and present the available models but then how does the user know what and how many levels are in each model?  And how do we govern putting them in the right order?

cat max_brightness will return number of levels for the model currently set. Regarding the order - we must rely on the DT array arrangement. In case of hardware originated brightness model we must trust hardware implementation.

Another question on this is what is the proposed definition of the DT value?

is it supposed to be 0xrrggbb? What about other colors like Amber? This was demonstrated in one of the videos you sent.

Maybe it should be rgb-<color> and not hsl-<color> because these values are not hsl values but instead RGB values.

Quoted 10 lines
Quoted 7 lines

The DT file can get messed up, per the previous example rgb-green = <0x277c33 0x37b048 0x47e45d>;

This is assumed to be from dimmest to brightest.  But that is just an assumption

What if the entry looked like this?
rgb-green = <0x37b048 0x277c33 0x47e45d>;

We can do nothing. It is just the cost of leaving some decisions to DT.

<snip>

Quoted 8 lines

I intended that brightness-model location would be the main LED class device directory.

And the whole concept is simple. We allow to set what we get from DT or from the hardware. Without verification exceeding beyond max_brightness values defined per iout.

Yes this is simple will put some documentation around it for discussion

Dan

Signature · 2 lines
------------------
Dan Murphy
#7 lore raw

Hi Dan,

Quoted 41 lines · Dan Murphy

Jacek

Quoted 38 lines · Jacek Anaszewski

Dan,

Quoted 34 lines · Dan Murphy

Jacek

Quoted 20 lines · Jacek Anaszewski

Dan,

Quoted 17 lines · Dan Murphy

Jacek

Quoted 11 lines · Jacek Anaszewski

Hi Dan,

Thank you for the RFC.

One vital thing is missing - documentation of brightness file must be updated to define its semantics for LED multi color class.

Either we need brightness-model file returning only "onoff" option available, or, for time being, fix the max_brightness for LED multi color class to 1 (which will map to max intensity level for each color).

I can make max_brightness default to 1 if not set by the LED driver.

Quoted 8 lines
Quoted 2 lines

But the LP50xx has brightness controls so setting max_brightness from the driver should over ride the max of 1 in the upper level.

Yes, so the max_brightness should be updated basing on current brightness-model. For LEDn_BRIGHTNESS of LP50xx we could have "hw" or maybe even better just "lp50xx-linear" and "lp50xx-logarithmic"
- I just forgot about that capability of the device.

OK maybe "hw" would make sense as there may be other devices that have dedicated brightness controls over color controls.

Quoted 6 lines
Quoted 4 lines

Single "hw" doesn't address both linear and logarithmic. This is device specific, so I don't see anything wrong in "lp50xx-*", provided that it will be documented.

OK. This would need to be lp50xx specific.

Thinking more of it - "hw_logarithmic" and "hw_linear" should also do. It would be even better option as it is generic.

My only concern here is how to document them. I we chose lp50xx-* prefixed names, then we could just refer to the data sheet.

For generic hw_{logarithmic|linear} brightness models we will need precise description. Actually it will be needed also for DT provided color levels. People must have good reference to know how to arrange DT color arrays.

It would be best to refer to standards, e.g. CIECAM02 [0], description of hue [1] and the overall relationship between "six technically defined dimensions of color appearance: brightness (luminance), lightness, colorfulness, chroma, saturation, and hue." I've found also interesting presentation [2].

After we agree on the interface I can try to put these together.

Quoted 35 lines
Quoted 11 lines
Quoted 2 lines

Probably need to create a model for non-modeled cases like "rgb-independent".  Dumb name but I could not think of anything better.

There is no point in having any rgb* brightness model since increasing rgb in an arbitrary way will not give the impression of increasing color intensity (lightness of the same hue). With DT defined hsl-<color> ranges there is no way to verify that levels arrangement makes sense with regard to preserving hue, this is a matter of trust. But we should state that it is highly recommended to obey this constraint so as to not mislead users.

OK. I will document this in v2 for discussion

Quoted 21 lines
Quoted 20 lines
Quoted 8 lines
Quoted 3 lines

For devices that do not support brightness as a separate control we can create a file called max_brightness_<color> that defines the max that a specific color can be set to.  If max_brightness is set to 1 then create max_brightness_<color>.  If max_brightness > 1 then do not create the files.

Right. We will need dedicated max_brightness for each color. They should be placed also in the colors directory, next to the color files.

OK will document this.

Quoted 6 lines
Quoted 2 lines

I don't think we have fully vetted the brightness-model yet so I prefer to omit it and possibly introduce that later.

We need to start from something. It will give better overview of the whole idea.

OK.  Don't get me wrong I don't oppose this idea I am just trying to figure out how the user space would know what models and brightness levels are available.

Quoted 8 lines
Quoted 6 lines
$ cat brightness-model
lp50xx-linear lp50xx-logarithmic onoff hsl-green hsl=blue

max_brightness will return available number of brightness levels for each brightness model.

So max_brightness here would be dynamic?

Yes.

Quoted 1 line

Or could we read hsl-<color> and get the number of levels and not mess with the max_brightness definition?

For hw_{linear|logarithmic| it will return the brightness resolution supported by the hardware.
For hsl-<color> (or whatever we will call it) it will return the number of elements in the array the currently chosen brightness-model refers to.

Quoted 1 line

Or should that be the current level?

Hmm? Current level will be available after executing "cat brightness".

Quoted 8 lines
Quoted 5 lines

I'd not bother with presenting whole range of available color presets. Userspace can verify the brightness->color mapping by reading colors/<color> files after setting given brightness level.

Userspace would have to have knowledge of the values set in order to verify the color values.

For the single element array:

some-color-model = <0xaabbcc>;

user will get this:

$ echo some-color-model > brightness-model
$ echo 1 > brightness
$ cat colors/red   // prints 0xaa
$ cat colors/green // prints 0xbb
$ cat colors/blue  // prints 0xcc
Quoted 13 lines
Quoted 4 lines

However, I'm not sure how useful it will be. This is a gist of this whole discussion - we cannot be certain about exact color effect produced with given settings.

Quoted 8 lines
Quoted 2 lines

I mean we can read the brightness-models and present the available models but then how does the user know what and how many levels are in each model?  And how do we govern putting them in the right order?

cat max_brightness will return number of levels for the model currently set. Regarding the order - we must rely on the DT array arrangement. In case of hardware originated brightness model we must trust hardware implementation.

Quoted 7 lines

Another question on this is what is the proposed definition of the DT value?

is it supposed to be 0xrrggbb? What about other colors like Amber? This was demonstrated in one of the videos you sent.

Maybe it should be rgb-<color> and not hsl-<color> because these values are not hsl values but instead RGB values.

Right, it should be possible to have even more than 4 LEDs in the LED multi-color class device. We shouldn't also limit the number of brightness levels for a single LED to one byte, as current framework also doesn't do that.

For 5 LEDs in the cluster, the array containing three brightness level would look like below (dummy values):

purple-linear-0 = <198 323 442 238 43 90>;
purple-linear-1 = <200 323 442 238 43 90>;
purple-linear-2 = <398 323 442 238 43 90>;

One more thing related to the brightness-model interface - instead of a file it must be a directory with files named after colors ranges defined in DT. There is PAGE_SIZE limit imposed on the sysfs file size, and we already had a report about crash caused by triggers file size that exceeded this limit due to large number of cpus available on the platform, that created equally large number of cpu triggers.

Also, if we will have those files, we will be able to report the number of available brightness levels per each color range.

Quoted 17 lines
Quoted 10 lines
Quoted 7 lines

The DT file can get messed up, per the previous example rgb-green = <0x277c33 0x37b048 0x47e45d>;

This is assumed to be from dimmest to brightest.  But that is just an assumption

What if the entry looked like this?
rgb-green = <0x37b048 0x277c33 0x47e45d>;

We can do nothing. It is just the cost of leaving some decisions to DT.

<snip>

Quoted 4 lines

I intended that brightness-model location would be the main LED class device directory.

Quoted 9 lines
Quoted 4 lines

And the whole concept is simple. We allow to set what we get from DT or from the hardware. Without verification exceeding beyond max_brightness values defined per iout.

Yes this is simple will put some documentation around it for discussion

Dan

[0] https://en.wikipedia.org/wiki/CIECAM02
[1] https://en.wikipedia.org/wiki/Hue
[2] http://rit-mcsl.org/fairchild/PDFs/AppearanceLec.pdf

Signature · 2 lines
Best regards,
Jacek Anaszewski
#8 lore raw
In reply to Dan Murphy
Quoted 2 lines · Dan Murphy

Add a documentation of LED Multicolor LED class specific sysfs attributes.

No, sorry. This does not most of the requirements.

Pavel

Requirements for RGB LED interface:

1) Userspace should be able to set the white color

2) Userspace should be able to arbitrary color from well known list and it should approximately match what would CRT, LCD or OLED monitor display. Color list is for example here:

https://www.rapidtables.com/web/color/RGB_Color.html

2a) LEDs probably slightly change color as they age. That's out of scope, unless the variation is much greater than on monitors.

3a) Manufacturing differences cause small color variation. Again, that's out of scope, unless the variation is much greater than on monitors.

Nice to have features:

3) Full range of available colors/intensities should be available to userspace

4) Interface should work well with existing triggers

5) It would be nice if userland knew how many lumens are produced at each wavelength for each setting (again, minus aging and manufacturing variations).

6) Complexity of math in kernel should be low, and preferably it should be integer or fixed point

Problems:

a) RGB LEDs are usually not balanced. Setting 100% PWM on red/green/blue channels will result in nothing close to white light. In fact, to get white light on N900, blue and green channel's PWM needs to be set pretty low, as in 5%.

b) LED class does not define any relation between "brightness" in sysfs and ammount of light in lumens. Some drivers use close to linear relation, some use exponential relation. Human eyes percieve logarithm of lumens. RGB color model uses even more complex function.

https://en.wikipedia.org/wiki/Gamma_correction
#Windows, Mac, sRGB and TV/video standard gammas
https://en.wikipedia.org/wiki/SRGB#Specification_of_the_transformation

c) Except for white LEDs, LEDs are basically sources of single wavelength of light, while CRTs and LCDs produce broader spectrums.

d) RG, RGBW and probably other LED combinations exist.

e) Not all "red" LEDs will produce same wavelength. Similar differences will exist for other colors.

f) We have existing RGB LEDs represented as three separate monochromatic LEDs in sysfs.

Quoted 50 lines
---
 .../ABI/testing/sysfs-class-led-multicolor    | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-led-multicolor
Documentation/ABI/testing/sysfs-class-led-multicolor new file +38 -0
new file mode 100644
index 000000000000..19f8da9b150e
@@ -0,0 +1,38 @@
+What:		/sys/class/leds/<led>/color/sync_enable
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	read/write
+		Writing a 1 to this file will enable the sychronization of all
+		the defined color LEDs within the LED node.  Writing a 0 to
+		this file will disable syncing.
+
+What:		/sys/class/leds/<led>/color/sync
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	write only
+		Writing a 1 to this file while sync_enable is set to 1 will
+		synchronize all defined LEDs within the LED node.  All LEDs
+		defined will be configured based on the brightness that has
+		been requested.
+
+		If sync_enable is set to 0 then writing a 1 to sync has no
+		affect on the LEDs.
+
+What:		/sys/class/leds/<led>/color/<led color>
+Date:		January 2019
+KernelVersion:	5.0
+Contact:	Dan Murphy <[email protected]>
+Description:	read/write
+		These files are dynamically created based on the colors defined
+		by the registrar of the class.
+		The led color(s) can be but not limited to red, green, blue,
+		white, amber and violet.  If sync is enabled then writing the
+		brightness value of the LED is deferred until a 1 is
+		written to /sys/class/leds/<led>/color/sync.  If syncing is
+		disabled then the LED brightness value will be written
+		immediately to the LED driver.
+
+		The value of the color is from 0 to
+		/sys/class/leds/<led>/max_brightness.
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
#9 lore raw

Hi All,

Quoted 9 lines · Pavel Machek
Quoted 2 lines · Dan Murphy

Add a documentation of LED Multicolor LED class specific sysfs attributes.

No, sorry. This does not most of the requirements.

Pavel

Requirements for RGB LED interface:

...

I have tried to capture relevant parts of ideas and requirements and usage in a wiki page in github:

https://github.com/vesajaaskelainen/linux-multicolor-leds/wiki

I believe the discussion is good to perform in mailing list -- I am happy to update or give you access to update the wiki so we could have easy to use summary/details source during discussions.

Ideas on the interface seem to be a bit drifting so I apologize if some of Your ideas were not captured.

There has been at least two direct proposals for userspace interface and I tried to provide usage example also for Dan's proposal. Feel free to correct me if I made a mistake.

I believe it is a good to create summary page as there seems to many aspects to be though out. What do you feel on this approach?

Thanks,
Vesa Jääskeläinen

#10 lore raw

Hi All,

Quoted 19 lines · Vesa Jääskeläinen

Hi All,

Quoted 9 lines · Pavel Machek
Quoted 2 lines · Dan Murphy

Add a documentation of LED Multicolor LED class specific sysfs attributes.

No, sorry. This does not most of the requirements.

                                Pavel

Requirements for RGB LED interface:

...

I have tried to capture relevant parts of ideas and requirements and usage in a wiki page in github:

https://github.com/vesajaaskelainen/linux-multicolor-leds/wiki

Quoted 7 lines

I believe the discussion is good to perform in mailing list -- I am happy to update or give you access to update the wiki so we could have easy to use summary/details source during discussions.

Ideas on the interface seem to be a bit drifting so I apologize if some of Your ideas were not captured.

There has been at least two direct proposals for userspace interface and I tried to provide usage example also for Dan's proposal. Feel free to correct me if I made a mistake.

I believe it is a good to create summary page as there seems to many aspects to be though out. What do you feel on this approach?

And should we perhaps move this discussion only to linux-leds mailing list for successive replies :) ? So we don't generate too broad traffic.

Thanks,
Vesa Jääskeläinen

author
#11 lore raw

Veas

Quoted 24 lines · Vesa Jääskeläinen

Hi All,

Quoted 21 lines · Vesa Jääskeläinen

Hi All,

Quoted 9 lines · Pavel Machek
Quoted 2 lines · Dan Murphy

Add a documentation of LED Multicolor LED class specific sysfs attributes.

No, sorry. This does not most of the requirements.

                                Pavel

Requirements for RGB LED interface:

...

I have tried to capture relevant parts of ideas and requirements and usage in a wiki page in github:

https://github.com/vesajaaskelainen/linux-multicolor-leds/wiki

I believe the discussion is good to perform in mailing list -- I am happy to update or give you access to update the wiki so we could have easy to use summary/details source during discussions.

Quoted 8 lines
Quoted 5 lines

Ideas on the interface seem to be a bit drifting so I apologize if some of Your ideas were not captured.

There has been at least two direct proposals for userspace interface and I tried to provide usage example also for Dan's proposal. Feel free to correct me if I made a mistake.

I believe it is a good to create summary page as there seems to many aspects to be though out. What do you feel on this approach?

And should we perhaps move this discussion only to linux-leds mailing list for successive replies :) ? So we don't generate too broad traffic.

Thank you for this. I have posted updated documentation and posted updated code that includes a test file that does nothing but register a dummy node. This was tested on raspberry pi 5.0-rc kernel.

Also the code is updated for the LP50xx and a HACK for Droid4.

brightness-model is still an open topic on the best way to implement this so we have not introduced the code yet.

Here is the ABI doc
http://git.ti.com/gitweb/?p=ti-analog-linux-kernel/dmurphy-analog.git;a=blob;f=Documentation/ABI/testing/sysfs-class-led-multicolor;h=45629199791285200e3775fc0b4dde1dfebb130f;hb=ce08183aa24edc0d883550339eef93fd72b4ac45

Here is the class description
http://git.ti.com/gitweb/?p=ti-analog-linux-kernel/dmurphy-analog.git;a=blob;f=Documentation/leds/leds-class-multicolor.txt;h=357f045a826aac71d65704891c18e7fb31e5cb9b;hb=refs/heads/multicolor_class

Dan

Quoted 2 lines

Thanks,
Vesa Jääskeläinen

Signature · 2 lines
------------------
Dan Murphy