[v2,1/2] dt-bindings: leds: Add SC27xx breathing light controller documentation

Message ID f393ca5a99059e7086307b99fc435777fe09018b.1525757122.git.baolin.wang@linaro.org
State New
Headers show
Series
  • [v2,1/2] dt-bindings: leds: Add SC27xx breathing light controller documentation
Related show

Commit Message

Baolin Wang May 8, 2018, 5:39 a.m.
This patch adds the binding documentation for Spreadtrum SC27xx series
breathing light controller, which supports 3 outputs: red LED, green
LED and blue LED.

Signed-off-by: Baolin Wang <baolin.wang@linaro.org>

---
Changes since v1:
 - Change the compatible string to be one explicit SoC name.
 - Change the child node name.
 - Change to be upper case for the first character.
---
 .../devicetree/bindings/leds/leds-sc27xx-bltc.txt  |   41 ++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt

-- 
1.7.9.5

Comments

Jacek Anaszewski May 10, 2018, 7:41 p.m. | #1
Hi Pavel,

On 05/10/2018 01:37 PM, Pavel Machek wrote:
> Hi!

> 

>>>> This patch adds Spreadtrum SC27xx PMIC series breathing light controller

>>>> driver, which can support 3 LEDs. Each LED can work at normal PWM mode

>>>> and breathing mode.

>>>>

>>>> diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx

>>>> new file mode 100644

>>>> index 0000000..22166fb

>>>> --- /dev/null

>>>> +++ b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx

>>>> @@ -0,0 +1,19 @@

>>>> +What:		/sys/class/leds/<led>/rise_time

>>>> +What:		/sys/class/leds/<led>/high_time

>>>> +What:		/sys/class/leds/<led>/fall_time

>>>> +What:		/sys/class/leds/<led>/low_time

>>>> +Date:		May 2018

>>>> +KernelVersion:	4.18

>>>> +Contact:	Xiaotong Lu <xiaotong.lu@spreadtrum.com>

>>>> +Description:

>>>> +		Set the pattern generator rise, high, fall and low

>>>> +		times (0..63). It's unit is 0.125s, it should be > 0.

>>>> +

>>>> +		1 - 125 ms

>>>> +		2 - 250 ms

>>>> +		3 - 375 ms

>>>> +		...

>>>> +		...

>>>> +		...

>>>> +		62 - 7.75 s

>>>> +		63 - 7.875 s

>>>

>>> How does this interact with triggers? With manually setting

>>> brightness? Are the pattern generators independend for the LEDs?

>>>

>>> Can you generate white breathing pattern? If so, how?

>>>

>>> How do you select between normal and breathing modes?

>>>

>>> I'd specify times in miliseconds or something, this is way too

>>> hardware specific.

>>

>> Agreed.

>>

>>> Now... functionality like this is common between many LED

>>> controllers. N900 could do this kind of "breathing", too, and it also

>>> supports other patterns.

>>>

>>> I believe we need interface common between different LED controllers.

>>>

>>> And I guess it would be easiest if you dropped this part from initial

>>> merge.

>>

>> I disagree here. We already had the same discussion at the occasion

>> of the patch [0] and it turned out to be a dead-end [1]. Now we have

>> neither the driver nor the generic pattern interface.

>>

>> We also already have some older LED class drivers that implement custom

>> pattern interfaces (e.g. drivers/leds/leds-lm3533.c) and the same

>> approach can be applied in this case.

> 

> Please don't. It was mistake to implement custom pattern interfaces

> back then, it is still mistake now.


It turned out to be really hard to cover all known pattern generator
implementations with generic interface. Sure, it would be nice to have
one, but the whole discussion around [0] only unveiled the diversity of
parameters to cover. And still new devices appear on the market.

We would have to propose a set of pattern schemes and allow to
add new ones to it.

> If we really need solution now, I'd recommend "pattern" file with

> 

> "<delta time> <brightness> <delta time> <brightness>".

> 

> In this specific case, hardware only supports patterns in this format:

> 

> low_time 0 rise_time 255 high_time 255 fall_time 0

> 

> so driver would simply -EINVAL on anything else.


I'm fine with the pattern file, but the pattern format would have
to be defined in the per-driver ABI documentation. It wouldn't much
differ from the custom pattern approach though, unless I'm missing some
gain of having pattern setting in a uniformly named single sysfs file
(with semantics differing from driver to driver).

-- 
Best regards,
Jacek Anaszewski

Patch

diff --git a/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt
new file mode 100644
index 0000000..b3de7fc
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-sc27xx-bltc.txt
@@ -0,0 +1,41 @@ 
+LEDs connected to Spreadtrum SC27XX PMIC breathing light controller
+
+The SC27xx breathing light controller supports to 3 outputs:
+red LED, green LED and blue LED. Each LED can work at normal
+PWM mode or breath light mode.
+
+Required properties:
+- compatible: Should be "sprd,sc2731-bltc".
+- #address-cells: Must be 1.
+- #size-cells: Must be 0.
+- reg: Specify controller address.
+
+Required child properties:
+- reg: Number of LED line (could be from 0 to 2).
+
+Optional child properties:
+- label: See Documentation/devicetree/bindings/leds/common.txt.
+
+Examples:
+
+led-controller@200 {
+	compatible = "sprd,sc2731-bltc";
+	#address-cells = <1>;
+	#size-cells = <0>;
+	reg = <0x200>;
+
+	led@0 {
+		label = "red";
+		reg = <0x0>;
+	};
+
+	led@1 {
+		label = "green";
+		reg = <0x1>;
+	};
+
+	led@2 {
+		label = "blue";
+		reg = <0x2>;
+	};
+};