[PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

Add documentation and example for dt-bindings EL15203000.
LED board (aka RED LED board) from Crane Merchandising Systems.

Signed-off-by: Oleh Kravchenko <oleg@kaa.org.ua>
---
 .../bindings/leds/leds-el15203000.txt         | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/leds/leds-el15203000.txt

diff --git a/Documentation/devicetree/bindings/leds/leds-el15203000.txt b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
new file mode 100644
index 000000000000..457fd8d7226f
--- /dev/null
+++ b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
@@ -0,0 +1,53 @@
+Crane Merchandising System - el15203000 LED driver
+--------------------------------------------------
+
+This LED Board (aka RED LEDs board) is widely used in coffee vending machines
+produced by Crane Merchandising Systems.
+
+Required properties:
+- compatible : "crane,el15203000"
+- reg :
+	see Documentation/devicetree/bindings/spi/spi-bus.txt
+- spi-max-frequency : (optional)
+	see Documentation/devicetree/bindings/spi/spi-bus.txt
+
+LED sub-node properties:
+- label :
+	see Documentation/devicetree/bindings/leds/common.txt
+- linux,default-trigger : (optional)
+	see Documentation/devicetree/bindings/leds/common.txt
+- max-brightness : (optional)
+	Specify here 2 if LED has special effect. Effects by LED type:
+	- Pipe has leaking
+	- Screen Frame has blinking
+
+Example
+-------
+
+led-controller@0 {
+	compatible = "crane,el15203000";
+	reg = <0>;
+	spi-max-frequency = <50000>;
+	#address-cells = <1>;
+	#size-cells = <0>;
+
+	/* water pipe */
+	pipe@50 {
+		reg = <0x50>;
+		label = "red:pipe";
+		max-brightness = <2>;
+	};
+
+	/* screen frame */
+	screen@53 {
+		reg = <0x53>;
+		label = "red:screen";
+		max-brightness = <2>;
+	};
+
+	/* vending area */
+	vend@56 {
+		reg = <0x56>;
+		label = "red:vend";
+	};
+};
-- 
2.21.0

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Dan Murphy]

Oleh

On 6/7/19 1:40 PM, Oleh Kravchenko wrote:
> Add documentation and example for dt-bindings EL15203000.
> LED board (aka RED LED board) from Crane Merchandising Systems.
>
> Signed-off-by: Oleh Kravchenko <oleg@kaa.org.ua>
> ---
>   .../bindings/leds/leds-el15203000.txt         | 53 +++++++++++++++++++
>   1 file changed, 53 insertions(+)
>   create mode 100644 Documentation/devicetree/bindings/leds/leds-el15203000.txt
>
> diff --git a/Documentation/devicetree/bindings/leds/leds-el15203000.txt b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
> new file mode 100644
> index 000000000000..457fd8d7226f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/leds/leds-el15203000.txt
> @@ -0,0 +1,53 @@
> +Crane Merchandising System - el15203000 LED driver
> +--------------------------------------------------
> +
> +This LED Board (aka RED LEDs board) is widely used in coffee vending machines
> +produced by Crane Merchandising Systems.
> +
> +Required properties:
> +- compatible : "crane,el15203000"
> +- reg :
> +	see Documentation/devicetree/bindings/spi/spi-bus.txt
> +- spi-max-frequency : (optional)
> +	see Documentation/devicetree/bindings/spi/spi-bus.txt
> +
> +LED sub-node properties:
> +- label :
> +	see Documentation/devicetree/bindings/leds/common.txt

Add this

Optional LED sub-node properties:

And remove (optional) from the below.

> +- linux,default-trigger : (optional)
> +	see Documentation/devicetree/bindings/leds/common.txt
> +- max-brightness : (optional)
> +	Specify here 2 if LED has special effect. Effects by LED type:

s/Specify here 2/Specify 2

But this is not really max_brightness now this is a feature and now does 
not make sense in this context

You may need to use something different for this property or expose a 
file in the driver.


> +	- Pipe has leaking
> +	- Screen Frame has blinking
> +
> +Example
> +-------
> +
> +led-controller@0 {
> +	compatible = "crane,el15203000";
> +	reg = <0>;
> +	spi-max-frequency = <50000>;
> +	#address-cells = <1>;
> +	#size-cells = <0>;
> +
> +	/* water pipe */
> +	pipe@50 {
> +		reg = <0x50>;
> +		label = "red:pipe";
> +		max-brightness = <2>;
> +	};
> +
> +	/* screen frame */
> +	screen@53 {
> +		reg = <0x53>;
> +		label = "red:screen";
> +		max-brightness = <2>;
> +	};
> +
> +	/* vending area */
> +	vend@56 {
> +		reg = <0x56>;
> +		label = "red:vend";
> +	};
> +};

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 961 bytes --]



07.06.19 23:14, Dan Murphy пише:
> Oleh
> 
> On 6/7/19 1:40 PM, Oleh Kravchenko wrote:
>> +LED sub-node properties:
>> +- label :
>> +    see Documentation/devicetree/bindings/leds/common.txt
> 
> Add this
> 
> Optional LED sub-node properties:
> 
> And remove (optional) from the below.
> 

Done

>> +- linux,default-trigger : (optional)
>> +    see Documentation/devicetree/bindings/leds/common.txt
>> +- max-brightness : (optional)
>> +    Specify here 2 if LED has special effect. Effects by LED type:
> 
> s/Specify here 2/Specify 2
> 

Done

> But this is not really max_brightness now this is a feature and now does not make sense in this context
> 
> You may need to use something different for this property or expose a file in the driver.
> 
> 

Protocol for this board define 0x32 as brightness level.
This behaviur needed to keep backward compatibity.


-- 
Best regards,
Oleh Kravchenko



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Dan Murphy]

Oleh

On 6/7/19 3:53 PM, Oleh Kravchenko wrote:
>
> 07.06.19 23:14, Dan Murphy пише:
>> Oleh
>>
>> On 6/7/19 1:40 PM, Oleh Kravchenko wrote:
>>> +LED sub-node properties:
>>> +- label :
>>> +    see Documentation/devicetree/bindings/leds/common.txt
>> Add this
>>
>> Optional LED sub-node properties:
>>
>> And remove (optional) from the below.
>>
> Done
>
>>> +- linux,default-trigger : (optional)
>>> +    see Documentation/devicetree/bindings/leds/common.txt
>>> +- max-brightness : (optional)
>>> +    Specify here 2 if LED has special effect. Effects by LED type:
>> s/Specify here 2/Specify 2
>>
> Done
>
>> But this is not really max_brightness now this is a feature and now does not make sense in this context
>>
>> You may need to use something different for this property or expose a file in the driver.
>>
>>
> Protocol for this board define 0x32 as brightness level.
> This behaviur needed to keep backward compatibity.
>
>
Backwards compatibility to what?

This is a new driver there should be no DT that has this compatible or 
definition.

I will let Rob ack or nack this node.

Dan

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 614 bytes --]

Dan,

On 08.06.19 00:04, Dan Murphy wrote:
> Oleh
> But this is not really max_brightness now this is a feature and now
> does not make sense in this context
>>>
>>> You may need to use something different for this property or expose
>>> a file in the driver.
>>>
>>>
>> Protocol for this board define 0x32 as brightness level.
>> This behaviur needed to keep backward compatibity.
>>
>>
> Backwards compatibility to what?
With old/new boards.
>
> This is a new driver there should be no DT that has this compatible or
> definition.
>
> I will let Rob ack or nack this node.
>
> Dan
>



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Jacek Anaszewski]

Hi Oleh.

On 6/7/19 11:17 PM, Oleh Kravchenko wrote:
> Dan,
> 
> On 08.06.19 00:04, Dan Murphy wrote:
>> Oleh
>> But this is not really max_brightness now this is a feature and now
>> does not make sense in this context
>>>>
>>>> You may need to use something different for this property or expose
>>>> a file in the driver.
>>>>
>>>>
>>> Protocol for this board define 0x32 as brightness level.
>>> This behaviur needed to keep backward compatibity.
>>>
>>>
>> Backwards compatibility to what?
> With old/new boards.

You have in your driver the following:

+ * BRIGHTNESS	Can be 0x30 (OFF), 0x31 (ON).
+ * 		0x32 (Effect) can be used for 0x50 (leaking) and
+ * 		for 0x53 (blinking)

If your max-brightness DT property is to be used for controlling this,
then I don't see how it would be backward compatible with anything.

Clearly, you don't need max-brightness DT property at all.

For blinking you can use blink_set op. To be able to recommend
you anoptimal solution for the effect we would need more
details regarding its nature.

>> This is a new driver there should be no DT that has this compatible or
>> definition.
>>
>> I will let Rob ack or nack this node.
>>
>> Dan
>>
> 
> 

-- 
Best regards,
Jacek Anaszewski

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Dan Murphy]

Oleh

On 6/7/19 4:17 PM, Oleh Kravchenko wrote:
> Dan,
>
> On 08.06.19 00:04, Dan Murphy wrote:
>> Oleh
>> But this is not really max_brightness now this is a feature and now
>> does not make sense in this context
>>>> You may need to use something different for this property or expose
>>>> a file in the driver.
>>>>
>>>>
>>> Protocol for this board define 0x32 as brightness level.
>>> This behaviur needed to keep backward compatibity.
>>>
>>>
>> Backwards compatibility to what?
> With old/new boards.

This does not make sense.

How would a device tree entry or a file that controls the blinking have 
to deal with the hardware?

If it allows feature setting then you should create a bool in the device 
tree.

el15203000-blink;

If the board supports the feature you set this and create a file to 
dis/enable the feature.

If the board does not support it then no file is created.

max_brightness for this device appears to be 1.

Dan


>> This is a new driver there should be no DT that has this compatible or
>> definition.
>>
>> I will let Rob ack or nack this node.
>>
>> Dan
>>
>

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 1842 bytes --]

Jacek,

08.06.19 00:23, Jacek Anaszewski пише:
> Hi Oleh.
> 
> On 6/7/19 11:17 PM, Oleh Kravchenko wrote:
>> Dan,
>>
>> On 08.06.19 00:04, Dan Murphy wrote:
>>> Oleh
>>> But this is not really max_brightness now this is a feature and now
>>> does not make sense in this context
>>>>>
>>>>> You may need to use something different for this property or expose
>>>>> a file in the driver.
>>>>>
>>>>>
>>>> Protocol for this board define 0x32 as brightness level.
>>>> This behaviur needed to keep backward compatibity.
>>>>
>>>>
>>> Backwards compatibility to what?
>> With old/new boards.
> 
> You have in your driver the following:
> 
> + * BRIGHTNESS    Can be 0x30 (OFF), 0x31 (ON).
> + *         0x32 (Effect) can be used for 0x50 (leaking) and
> + *         for 0x53 (blinking)
> 
> If your max-brightness DT property is to be used for controlling this,
> then I don't see how it would be backward compatible with anything.
> 
> Clearly, you don't need max-brightness DT property at all.

What I should do with board which accept brightness in range 0x30 - 0x3a?
Where 0x3a means special effect.

> 
> For blinking you can use blink_set op. To be able to recommend
> you anoptimal solution for the effect we would need more
> details regarding its nature.

Thanks, I will do that.
But how to properly handle other effects? Not only blinking?

And how to define it by device tree?
Driver can't get this information about what is really supported.
I don't want define effect code inside DT.

 
>>> This is a new driver there should be no DT that has this compatible or
>>> definition.
>>>
>>> I will let Rob ack or nack this node.
>>>
>>> Dan
>>>
>>
>>
> 

-- 
Best regards,
Oleh Kravchenko
Phone: +380972763224 | oleg@kaa.org.ua | Skype: oleg_krava


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Oleh Kravchenko]

[-- Attachment #1.1: Type: text/plain, Size: 853 bytes --]

Hello Jacek,

08.06.19 00:48, Oleh Kravchenko пише:
> Jacek,
> 
>> For blinking you can use blink_set op. To be able to recommend
>> you anoptimal solution for the effect we would need more
>> details regarding its nature.
> 
> Thanks, I will do that.
> But how to properly handle other effects? Not only blinking?

	int		(*blink_set)(struct led_classdev *led_cdev,
				     unsigned long *delay_on,
				     unsigned long *delay_off);

My LED board doesn't support any delay settings at all.
Should I always set delay_on, delay_off to zero?

 
> And how to define it by device tree?
> Driver can't get this information about what is really supported.
> I don't want define effect code inside DT.
> 
>  
>>>> This is a new driver there should be no DT that has this compatible or

-- 
Best regards,
Oleh Kravchenko



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2 1/2] dt-bindings: Add docs for EL15203000

[Jacek Anaszewski]

Hi Oleh,

On 6/7/19 11:48 PM, Oleh Kravchenko wrote:
> Jacek,
> 
> 08.06.19 00:23, Jacek Anaszewski пише:
>> Hi Oleh.
>>
>> On 6/7/19 11:17 PM, Oleh Kravchenko wrote:
>>> Dan,
>>>
>>> On 08.06.19 00:04, Dan Murphy wrote:
>>>> Oleh
>>>> But this is not really max_brightness now this is a feature and now
>>>> does not make sense in this context
>>>>>>
>>>>>> You may need to use something different for this property or expose
>>>>>> a file in the driver.
>>>>>>
>>>>>>
>>>>> Protocol for this board define 0x32 as brightness level.
>>>>> This behaviur needed to keep backward compatibity.
>>>>>
>>>>>
>>>> Backwards compatibility to what?
>>> With old/new boards.
>>
>> You have in your driver the following:
>>
>> + * BRIGHTNESS    Can be 0x30 (OFF), 0x31 (ON).
>> + *         0x32 (Effect) can be used for 0x50 (leaking) and
>> + *         for 0x53 (blinking)
>>
>> If your max-brightness DT property is to be used for controlling this,
>> then I don't see how it would be backward compatible with anything.
>>
>> Clearly, you don't need max-brightness DT property at all.
> 
> What I should do with board which accept brightness in range 0x30 - 0x3a?
> Where 0x3a means special effect.

I believe 0x3a is a typo since above you have 0x32 for the effect.

Anyway, we shouldn't propagate hardware design flaws to the userspace
interface. You have ON/OFF register values for manipulating brightness,
so use them appropriately. struct led_classdev's max_brightness property
should be set to 1, as already pointed out by Dan.

>> For blinking you can use blink_set op. To be able to recommend
>> you anoptimal solution for the effect we would need more
>> details regarding its nature.
> 
> Thanks, I will do that.
> But how to properly handle other effects? Not only blinking?

For the effects we could probably use pattern trigger, but we need
more information on how it can be configured.

> And how to define it by device tree?
> Driver can't get this information about what is really supported.
> I don't want define effect code inside DT.

We now have led-pattern DT property, which allows to initialize a LED
with the DT provided pattern
(see Documentation/devicetree/bindings/leds/common.txt).

>>>> This is a new driver there should be no DT that has this compatible or
>>>> definition.
>>>>
>>>> I will let Rob ack or nack this node.
>>>>
>>>> Dan
>>>>
>>>
>>>
>>
> 

-- 
Best regards,
Jacek Anaszewski