diff mbox

[PATCH/RFC,v9,06/19] DT: Add documentation for the mfd Maxim max77693

Message ID 1417622814-10845-7-git-send-email-j.anaszewski@samsung.com (mailing list archive)
State New, archived
Headers show

Commit Message

Jacek Anaszewski Dec. 3, 2014, 4:06 p.m. UTC
This patch adds device tree binding documentation for
the flash cell of the Maxim max77693 multifunctional device.

Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
Signed-off-by: Andrzej Hajda <a.hajda@samsung.com>
Acked-by: Kyungmin Park <kyungmin.park@samsung.com>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Chanwoo Choi <cw00.choi@samsung.com>
Cc: Bryan Wu <cooloney@gmail.com>
Cc: Richard Purdie <rpurdie@rpsys.net>
Cc: Rob Herring <robh+dt@kernel.org>
Cc: Pawel Moll <pawel.moll@arm.com>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Ian Campbell <ijc+devicetree@hellion.org.uk>
Cc: Kumar Gala <galak@codeaurora.org>
Cc: <devicetree@vger.kernel.org>
---
 Documentation/devicetree/bindings/mfd/max77693.txt |   89 ++++++++++++++++++++
 1 file changed, 89 insertions(+)

Comments

Sakari Ailus Dec. 4, 2014, 10:07 a.m. UTC | #1
Hi Jacek,

On Wed, Dec 03, 2014 at 05:06:41PM +0100, Jacek Anaszewski wrote:
> This patch adds device tree binding documentation for
> the flash cell of the Maxim max77693 multifunctional device.
> 
> Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
> Signed-off-by: Andrzej Hajda <a.hajda@samsung.com>
> Acked-by: Kyungmin Park <kyungmin.park@samsung.com>
> Cc: Lee Jones <lee.jones@linaro.org>
> Cc: Chanwoo Choi <cw00.choi@samsung.com>
> Cc: Bryan Wu <cooloney@gmail.com>
> Cc: Richard Purdie <rpurdie@rpsys.net>
> Cc: Rob Herring <robh+dt@kernel.org>
> Cc: Pawel Moll <pawel.moll@arm.com>
> Cc: Mark Rutland <mark.rutland@arm.com>
> Cc: Ian Campbell <ijc+devicetree@hellion.org.uk>
> Cc: Kumar Gala <galak@codeaurora.org>
> Cc: <devicetree@vger.kernel.org>
> ---
>  Documentation/devicetree/bindings/mfd/max77693.txt |   89 ++++++++++++++++++++
>  1 file changed, 89 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt b/Documentation/devicetree/bindings/mfd/max77693.txt
> index 01e9f30..25a6e78 100644
> --- a/Documentation/devicetree/bindings/mfd/max77693.txt
> +++ b/Documentation/devicetree/bindings/mfd/max77693.txt
> @@ -41,7 +41,66 @@ Optional properties:
>  	 To get more informations, please refer to documentaion.
>  	[*] refer Documentation/devicetree/bindings/pwm/pwm.txt
>  
> +- led : the LED submodule device node
> +
> +There are two led outputs available - fled1 and fled2. Each of them can
> +control a separate led or they can be connected together to double
> +the maximum current for a single connected led. One led is represented
> +by one child node.
> +
> +Required properties:
> +- compatible : Must be "maxim,max77693-led".
> +
> +Optional properties:
> +- maxim,fleds : Array of current outputs in order: fled1, fled2.
> +	Note: both current outputs can be connected to a single led
> +	Possible values:
> +		MAX77693_LED_FLED_UNUSED - the output is left disconnected,
> +		MAX77693_LED_FLED_USED - a diode is connected to the output.

As you have a LED sub-nodes for each LED already, isn't this redundant?

> +- maxim,trigger-type : Array of trigger types in order: flash, torch.
> +	Possible trigger types:
> +		MAX77693_LED_TRIG_TYPE_EDGE - Rising edge of the signal triggers
> +			the flash/torch,
> +		MAX77693_LED_TRIG_TYPE_LEVEL - Signal level controls duration of

How about: "Strobe pulse length ..."?

How long does the torch stay on if you use edge trigger for it? I've always
thought the torch enable pin was a practical joke. :-)

If you need it this for torch as well, I'd use separate properties for the
purpose, i.e. trigger-type-flash and trigger-type-torch.

> +			the flash/torch.
> +- maxim,trigger : Array of flags indicating which trigger can activate given led
> +	in order: fled1, fled2.
> +	Possible flag values (can be combined):
> +		MAX77693_LED_TRIG_FLASHEN - FLASHEN pin of the chip,
> +		MAX77693_LED_TRIG_TORCHEN - TORCHEN pin of the chip,
> +		MAX77693_LED_TRIG_SOFTWARE - software via I2C command.

Is there a need to prevent strobing using a certain method? Just wondering.

> +- maxim,boost-mode :
> +	In boost mode the device can produce up to 1.2A of total current
> +	on both outputs. The maximum current on each output is reduced
> +	to 625mA then. If there are two child led nodes defined then boost
> +	is enabled by default.
> +	Possible values:
> +		MAX77693_LED_BOOST_OFF - no boost,
> +		MAX77693_LED_BOOST_ADAPTIVE - adaptive mode,
> +		MAX77693_LED_BOOST_FIXED - fixed mode.
> +- maxim,boost-vout : Output voltage of the boost module in millivolts.
> +- maxim,vsys-min : Low input voltage level in millivolts. Flash is not fired
> +	if chip estimates that system voltage could drop below this level due
> +	to flash power consumption.
> +
> +Required properties of the LED child node:
> +- label : see Documentation/devicetree/bindings/leds/common.txt
> +- maxim,fled_id : Identifier of the fled output the led is connected to;

I'm pretty sure this will be needed for about every chip that can drive
multiple LEDs. Shouldn't it be documented in the generic documentation?

> +		MAX77693_LED_FLED1 - FLED1 output of the device - it has to be
> +			used also if a single LED is connected to both outputs,
> +		MAX77693_LED_FLED2 - FLED2 output of the device.
> +
> +Optional properties of the LED child node:
> +- max-microamp : see Documentation/devicetree/bindings/leds/common.txt
> +		Range: 15625 - 250000
> +- flash-max-microamp : see Documentation/devicetree/bindings/leds/common.txt
> +		Range: 15625 - 1000000
> +- flash-timeout-microsec : see Documentation/devicetree/bindings/leds/common.txt
> +		Range: 62500 - 1000000
> +
>  Example:
> +#include <dt-bindings/mfd/max77693.h>
> +
>  	max77693@66 {
>  		compatible = "maxim,max77693";
>  		reg = <0x66>;
> @@ -73,4 +132,34 @@ Example:
>  			pwms = <&pwm 0 40000 0>;
>  			pwm-names = "haptic";
>  		};
> +
> +		led {
> +			compatible = "maxim,max77693-led";
> +			maxim,fleds = <MAX77693_LED_FLED_USED
> +				       MAX77693_LED_FLED_USED>;
> +			maxim,trigger = <MAX77693_LED_TRIG_ALL
> +					 (MAX77693_LED_TRIG_TORCHEN |
> +					 MAX77693_LED_TRIG_SOFTWARE)>;
> +			maxim,trigger-type = <MAX77693_LED_TRIG_TYPE_EDGE
> +					      MAX77693_LED_TRIG_TYPE_LEVEL>;
> +			maxim,boost-mode = <MAX77693_LED_BOOST_ADAPTIVE>;
> +			maxim,boost-vout = <5000>;
> +			maxim,vsys-min = <2400>;
> +
> +			camera1_flash: led1 {
> +				maxim,fled_id = <MAX77693_LED_FLED1>;
> +				label = "max77693-flash1";
> +				max-microamp = <250000>;
> +				flash-max-microamp = <625000>;
> +				flash-timeout-microsec = <1000000>;
> +			};
> +
> +			camera2_flash: led2 {
> +				maxim,fled_id = <MAX77693_LED_FLED2>;
> +				label = "max77693-flash2";
> +				max-microamp = <250000>;
> +				flash-max-microamp = <500000>;
> +				flash-timeout-microsec = <1000000>;
> +			};
> +		};

I like how this looks like in general.

>  	};
Jacek Anaszewski Dec. 4, 2014, 11:40 a.m. UTC | #2
Hi Sakari,

Thanks for the review.

On 12/04/2014 11:07 AM, Sakari Ailus wrote:
> Hi Jacek,
>
> On Wed, Dec 03, 2014 at 05:06:41PM +0100, Jacek Anaszewski wrote:
>> This patch adds device tree binding documentation for
>> the flash cell of the Maxim max77693 multifunctional device.
>>
>> Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
>> Signed-off-by: Andrzej Hajda <a.hajda@samsung.com>
>> Acked-by: Kyungmin Park <kyungmin.park@samsung.com>
>> Cc: Lee Jones <lee.jones@linaro.org>
>> Cc: Chanwoo Choi <cw00.choi@samsung.com>
>> Cc: Bryan Wu <cooloney@gmail.com>
>> Cc: Richard Purdie <rpurdie@rpsys.net>
>> Cc: Rob Herring <robh+dt@kernel.org>
>> Cc: Pawel Moll <pawel.moll@arm.com>
>> Cc: Mark Rutland <mark.rutland@arm.com>
>> Cc: Ian Campbell <ijc+devicetree@hellion.org.uk>
>> Cc: Kumar Gala <galak@codeaurora.org>
>> Cc: <devicetree@vger.kernel.org>
>> ---
>>   Documentation/devicetree/bindings/mfd/max77693.txt |   89 ++++++++++++++++++++
>>   1 file changed, 89 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt b/Documentation/devicetree/bindings/mfd/max77693.txt
>> index 01e9f30..25a6e78 100644
>> --- a/Documentation/devicetree/bindings/mfd/max77693.txt
>> +++ b/Documentation/devicetree/bindings/mfd/max77693.txt
>> @@ -41,7 +41,66 @@ Optional properties:
>>   	 To get more informations, please refer to documentaion.
>>   	[*] refer Documentation/devicetree/bindings/pwm/pwm.txt
>>
>> +- led : the LED submodule device node
>> +
>> +There are two led outputs available - fled1 and fled2. Each of them can
>> +control a separate led or they can be connected together to double
>> +the maximum current for a single connected led. One led is represented
>> +by one child node.
>> +
>> +Required properties:
>> +- compatible : Must be "maxim,max77693-led".
>> +
>> +Optional properties:
>> +- maxim,fleds : Array of current outputs in order: fled1, fled2.
>> +	Note: both current outputs can be connected to a single led
>> +	Possible values:
>> +		MAX77693_LED_FLED_UNUSED - the output is left disconnected,
>> +		MAX77693_LED_FLED_USED - a diode is connected to the output.
>
> As you have a LED sub-nodes for each LED already, isn't this redundant?

Well, it seems so :)

>> +- maxim,trigger-type : Array of trigger types in order: flash, torch.
>> +	Possible trigger types:
>> +		MAX77693_LED_TRIG_TYPE_EDGE - Rising edge of the signal triggers
>> +			the flash/torch,
>> +		MAX77693_LED_TRIG_TYPE_LEVEL - Signal level controls duration of
>
> How about: "Strobe pulse length ..."?

OK, it will be more clear.

> How long does the torch stay on if you use edge trigger for it? I've always
> thought the torch enable pin was a practical joke. :-)

There is a torch timer available but I don't expose it to the user.

> If you need it this for torch as well, I'd use separate properties for the
> purpose, i.e. trigger-type-flash and trigger-type-torch.

OK.

>> +			the flash/torch.
>> +- maxim,trigger : Array of flags indicating which trigger can activate given led
>> +	in order: fled1, fled2.
>> +	Possible flag values (can be combined):
>> +		MAX77693_LED_TRIG_FLASHEN - FLASHEN pin of the chip,
>> +		MAX77693_LED_TRIG_TORCHEN - TORCHEN pin of the chip,
>> +		MAX77693_LED_TRIG_SOFTWARE - software via I2C command.
>
> Is there a need to prevent strobing using a certain method? Just wondering.

In some cases it could be convenient to prevent some options through
device tree.

>> +- maxim,boost-mode :
>> +	In boost mode the device can produce up to 1.2A of total current
>> +	on both outputs. The maximum current on each output is reduced
>> +	to 625mA then. If there are two child led nodes defined then boost
>> +	is enabled by default.
>> +	Possible values:
>> +		MAX77693_LED_BOOST_OFF - no boost,
>> +		MAX77693_LED_BOOST_ADAPTIVE - adaptive mode,
>> +		MAX77693_LED_BOOST_FIXED - fixed mode.
>> +- maxim,boost-vout : Output voltage of the boost module in millivolts.
>> +- maxim,vsys-min : Low input voltage level in millivolts. Flash is not fired
>> +	if chip estimates that system voltage could drop below this level due
>> +	to flash power consumption.
>> +
>> +Required properties of the LED child node:
>> +- label : see Documentation/devicetree/bindings/leds/common.txt
>> +- maxim,fled_id : Identifier of the fled output the led is connected to;
>
> I'm pretty sure this will be needed for about every chip that can drive
> multiple LEDs. Shouldn't it be documented in the generic documentation?

OK.

>> +		MAX77693_LED_FLED1 - FLED1 output of the device - it has to be
>> +			used also if a single LED is connected to both outputs,
>> +		MAX77693_LED_FLED2 - FLED2 output of the device.
>> +
>> +Optional properties of the LED child node:
>> +- max-microamp : see Documentation/devicetree/bindings/leds/common.txt
>> +		Range: 15625 - 250000
>> +- flash-max-microamp : see Documentation/devicetree/bindings/leds/common.txt
>> +		Range: 15625 - 1000000
>> +- flash-timeout-microsec : see Documentation/devicetree/bindings/leds/common.txt
>> +		Range: 62500 - 1000000
>> +
>>   Example:
>> +#include <dt-bindings/mfd/max77693.h>
>> +
>>   	max77693@66 {
>>   		compatible = "maxim,max77693";
>>   		reg = <0x66>;
>> @@ -73,4 +132,34 @@ Example:
>>   			pwms = <&pwm 0 40000 0>;
>>   			pwm-names = "haptic";
>>   		};
>> +
>> +		led {
>> +			compatible = "maxim,max77693-led";
>> +			maxim,fleds = <MAX77693_LED_FLED_USED
>> +				       MAX77693_LED_FLED_USED>;
>> +			maxim,trigger = <MAX77693_LED_TRIG_ALL
>> +					 (MAX77693_LED_TRIG_TORCHEN |
>> +					 MAX77693_LED_TRIG_SOFTWARE)>;
>> +			maxim,trigger-type = <MAX77693_LED_TRIG_TYPE_EDGE
>> +					      MAX77693_LED_TRIG_TYPE_LEVEL>;
>> +			maxim,boost-mode = <MAX77693_LED_BOOST_ADAPTIVE>;
>> +			maxim,boost-vout = <5000>;
>> +			maxim,vsys-min = <2400>;
>> +
>> +			camera1_flash: led1 {
>> +				maxim,fled_id = <MAX77693_LED_FLED1>;
>> +				label = "max77693-flash1";
>> +				max-microamp = <250000>;
>> +				flash-max-microamp = <625000>;
>> +				flash-timeout-microsec = <1000000>;
>> +			};
>> +
>> +			camera2_flash: led2 {
>> +				maxim,fled_id = <MAX77693_LED_FLED2>;
>> +				label = "max77693-flash2";
>> +				max-microamp = <250000>;
>> +				flash-max-microamp = <500000>;
>> +				flash-timeout-microsec = <1000000>;
>> +			};
>> +		};
>
> I like how this looks like in general.

Nice :)

>>   	};
>

Best Regards,
Jacek Anaszewski
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Pavel Machek Dec. 4, 2014, 4:12 p.m. UTC | #3
Hi!

> >>+- maxim,boost-mode :
> >>+	In boost mode the device can produce up to 1.2A of total current
> >>+	on both outputs. The maximum current on each output is reduced
> >>+	to 625mA then. If there are two child led nodes defined then boost
> >>+	is enabled by default.
> >>+	Possible values:
> >>+		MAX77693_LED_BOOST_OFF - no boost,
> >>+		MAX77693_LED_BOOST_ADAPTIVE - adaptive mode,
> >>+		MAX77693_LED_BOOST_FIXED - fixed mode.
> >>+- maxim,boost-vout : Output voltage of the boost module in millivolts.
> >>+- maxim,vsys-min : Low input voltage level in millivolts. Flash is not fired
> >>+	if chip estimates that system voltage could drop below this level due
> >>+	to flash power consumption.
> >>+
> >>+Required properties of the LED child node:
> >>+- label : see Documentation/devicetree/bindings/leds/common.txt
> >>+- maxim,fled_id : Identifier of the fled output the led is connected to;
> >
> >I'm pretty sure this will be needed for about every chip that can drive
> >multiple LEDs. Shouldn't it be documented in the generic documentation?
> 
> OK.

Well... "fled_id" is not exactly suitable name. On other busses, it
would be "reg = <1>"?

								Pavel
Jacek Anaszewski Dec. 8, 2014, 10:29 a.m. UTC | #4
Hi Pavel,

On 12/04/2014 05:12 PM, Pavel Machek wrote:
> Hi!
>
>>>> +- maxim,boost-mode :
>>>> +	In boost mode the device can produce up to 1.2A of total current
>>>> +	on both outputs. The maximum current on each output is reduced
>>>> +	to 625mA then. If there are two child led nodes defined then boost
>>>> +	is enabled by default.
>>>> +	Possible values:
>>>> +		MAX77693_LED_BOOST_OFF - no boost,
>>>> +		MAX77693_LED_BOOST_ADAPTIVE - adaptive mode,
>>>> +		MAX77693_LED_BOOST_FIXED - fixed mode.
>>>> +- maxim,boost-vout : Output voltage of the boost module in millivolts.
>>>> +- maxim,vsys-min : Low input voltage level in millivolts. Flash is not fired
>>>> +	if chip estimates that system voltage could drop below this level due
>>>> +	to flash power consumption.
>>>> +
>>>> +Required properties of the LED child node:
>>>> +- label : see Documentation/devicetree/bindings/leds/common.txt
>>>> +- maxim,fled_id : Identifier of the fled output the led is connected to;
>>>
>>> I'm pretty sure this will be needed for about every chip that can drive
>>> multiple LEDs. Shouldn't it be documented in the generic documentation?
>>
>> OK.
>
> Well... "fled_id" is not exactly suitable name. On other busses, it
> would be "reg = <1>"?

I'm ok with "reg". This scheme is used for pca963x.txt and is described
as "number of LED line". We could define it similarly in the common.txt.
A device would have to specify the range of allowed values though.
I would add such a note to the generic binding.

Regards,
Jacek
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Sakari Ailus Dec. 9, 2014, 2:09 p.m. UTC | #5
Hi Jacek,

On Thu, Dec 04, 2014 at 12:40:48PM +0100, Jacek Anaszewski wrote:
> >>+			the flash/torch.
> >>+- maxim,trigger : Array of flags indicating which trigger can activate given led
> >>+	in order: fled1, fled2.
> >>+	Possible flag values (can be combined):
> >>+		MAX77693_LED_TRIG_FLASHEN - FLASHEN pin of the chip,
> >>+		MAX77693_LED_TRIG_TORCHEN - TORCHEN pin of the chip,
> >>+		MAX77693_LED_TRIG_SOFTWARE - software via I2C command.
> >
> >Is there a need to prevent strobing using a certain method? Just wondering.
> 
> In some cases it could be convenient to prevent some options through
> device tree.

Do you have that need now?

If not, I'd propose to postpone this and add it only if there ever is one.
Jacek Anaszewski Dec. 9, 2014, 2:13 p.m. UTC | #6
Hi Sakari,

On 12/09/2014 03:09 PM, Sakari Ailus wrote:
> Hi Jacek,
>
> On Thu, Dec 04, 2014 at 12:40:48PM +0100, Jacek Anaszewski wrote:
>>>> +			the flash/torch.
>>>> +- maxim,trigger : Array of flags indicating which trigger can activate given led
>>>> +	in order: fled1, fled2.
>>>> +	Possible flag values (can be combined):
>>>> +		MAX77693_LED_TRIG_FLASHEN - FLASHEN pin of the chip,
>>>> +		MAX77693_LED_TRIG_TORCHEN - TORCHEN pin of the chip,
>>>> +		MAX77693_LED_TRIG_SOFTWARE - software via I2C command.
>>>
>>> Is there a need to prevent strobing using a certain method? Just wondering.
>>
>> In some cases it could be convenient to prevent some options through
>> device tree.
>
> Do you have that need now?
>
> If not, I'd propose to postpone this and add it only if there ever is one.
>

No, I don't. So let's postpone it.

Best Regards,
Jacek Anaszewski
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Jacek Anaszewski Dec. 10, 2014, 10:02 a.m. UTC | #7
Hi Sakari,

On 12/04/2014 12:40 PM, Jacek Anaszewski wrote:

> On 12/04/2014 11:07 AM, Sakari Ailus wrote:
>> Hi Jacek,
>>
>> On Wed, Dec 03, 2014 at 05:06:41PM +0100, Jacek Anaszewski wrote:
>>> This patch adds device tree binding documentation for
>>> the flash cell of the Maxim max77693 multifunctional device.
>>>
>>> Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
>>> Signed-off-by: Andrzej Hajda <a.hajda@samsung.com>
>>> Acked-by: Kyungmin Park <kyungmin.park@samsung.com>
>>> Cc: Lee Jones <lee.jones@linaro.org>
>>> Cc: Chanwoo Choi <cw00.choi@samsung.com>
>>> Cc: Bryan Wu <cooloney@gmail.com>
>>> Cc: Richard Purdie <rpurdie@rpsys.net>
>>> Cc: Rob Herring <robh+dt@kernel.org>
>>> Cc: Pawel Moll <pawel.moll@arm.com>
>>> Cc: Mark Rutland <mark.rutland@arm.com>
>>> Cc: Ian Campbell <ijc+devicetree@hellion.org.uk>
>>> Cc: Kumar Gala <galak@codeaurora.org>
>>> Cc: <devicetree@vger.kernel.org>
>>> ---
>>>   Documentation/devicetree/bindings/mfd/max77693.txt |   89
>>> ++++++++++++++++++++
>>>   1 file changed, 89 insertions(+)
>>>
>>> diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt
>>> b/Documentation/devicetree/bindings/mfd/max77693.txt
>>> index 01e9f30..25a6e78 100644
>>> --- a/Documentation/devicetree/bindings/mfd/max77693.txt
>>> +++ b/Documentation/devicetree/bindings/mfd/max77693.txt
>>> @@ -41,7 +41,66 @@ Optional properties:
>>>        To get more informations, please refer to documentaion.
>>>       [*] refer Documentation/devicetree/bindings/pwm/pwm.txt
>>>
>>> +- led : the LED submodule device node
>>> +
>>> +There are two led outputs available - fled1 and fled2. Each of them can
>>> +control a separate led or they can be connected together to double
>>> +the maximum current for a single connected led. One led is represented
>>> +by one child node.
>>> +
>>> +Required properties:
>>> +- compatible : Must be "maxim,max77693-led".
>>> +
>>> +Optional properties:
>>> +- maxim,fleds : Array of current outputs in order: fled1, fled2.
>>> +    Note: both current outputs can be connected to a single led
>>> +    Possible values:
>>> +        MAX77693_LED_FLED_UNUSED - the output is left disconnected,
>>> +        MAX77693_LED_FLED_USED - a diode is connected to the output.
>>
>> As you have a LED sub-nodes for each LED already, isn't this redundant?
>
> Well, it seems so :)

I agreed here recklessly. This property allows to describe the
situation when one LED is connected to both outputs. Single sub-node
can describe two type of designs: one LED connected to a single
output or one LED connected to both outputs. Therefore additional
property is needed to assess what is the actual case.

Best Regards,
Jacek Anaszewski

--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Sakari Ailus Dec. 10, 2014, 10:50 a.m. UTC | #8
Hi Jacek,

On Wed, Dec 10, 2014 at 11:02:07AM +0100, Jacek Anaszewski wrote:
> Hi Sakari,
> 
> On 12/04/2014 12:40 PM, Jacek Anaszewski wrote:
> 
> >On 12/04/2014 11:07 AM, Sakari Ailus wrote:
> >>Hi Jacek,
> >>
> >>On Wed, Dec 03, 2014 at 05:06:41PM +0100, Jacek Anaszewski wrote:
> >>>This patch adds device tree binding documentation for
> >>>the flash cell of the Maxim max77693 multifunctional device.
> >>>
> >>>Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
> >>>Signed-off-by: Andrzej Hajda <a.hajda@samsung.com>
> >>>Acked-by: Kyungmin Park <kyungmin.park@samsung.com>
> >>>Cc: Lee Jones <lee.jones@linaro.org>
> >>>Cc: Chanwoo Choi <cw00.choi@samsung.com>
> >>>Cc: Bryan Wu <cooloney@gmail.com>
> >>>Cc: Richard Purdie <rpurdie@rpsys.net>
> >>>Cc: Rob Herring <robh+dt@kernel.org>
> >>>Cc: Pawel Moll <pawel.moll@arm.com>
> >>>Cc: Mark Rutland <mark.rutland@arm.com>
> >>>Cc: Ian Campbell <ijc+devicetree@hellion.org.uk>
> >>>Cc: Kumar Gala <galak@codeaurora.org>
> >>>Cc: <devicetree@vger.kernel.org>
> >>>---
> >>>  Documentation/devicetree/bindings/mfd/max77693.txt |   89
> >>>++++++++++++++++++++
> >>>  1 file changed, 89 insertions(+)
> >>>
> >>>diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt
> >>>b/Documentation/devicetree/bindings/mfd/max77693.txt
> >>>index 01e9f30..25a6e78 100644
> >>>--- a/Documentation/devicetree/bindings/mfd/max77693.txt
> >>>+++ b/Documentation/devicetree/bindings/mfd/max77693.txt
> >>>@@ -41,7 +41,66 @@ Optional properties:
> >>>       To get more informations, please refer to documentaion.
> >>>      [*] refer Documentation/devicetree/bindings/pwm/pwm.txt
> >>>
> >>>+- led : the LED submodule device node
> >>>+
> >>>+There are two led outputs available - fled1 and fled2. Each of them can
> >>>+control a separate led or they can be connected together to double
> >>>+the maximum current for a single connected led. One led is represented
> >>>+by one child node.
> >>>+
> >>>+Required properties:
> >>>+- compatible : Must be "maxim,max77693-led".
> >>>+
> >>>+Optional properties:
> >>>+- maxim,fleds : Array of current outputs in order: fled1, fled2.
> >>>+    Note: both current outputs can be connected to a single led
> >>>+    Possible values:
> >>>+        MAX77693_LED_FLED_UNUSED - the output is left disconnected,
> >>>+        MAX77693_LED_FLED_USED - a diode is connected to the output.
> >>
> >>As you have a LED sub-nodes for each LED already, isn't this redundant?
> >
> >Well, it seems so :)
> 
> I agreed here recklessly. This property allows to describe the

If this is reckless then we're doing very, very well. :-D

> situation when one LED is connected to both outputs. Single sub-node
> can describe two type of designs: one LED connected to a single
> output or one LED connected to both outputs. Therefore additional
> property is needed to assess what is the actual case.

Which output do you say such LED is connected then?

I wonder if the reg property could be made an array, so you could say the
LED is connected to this and that output.

The advantage would be that this still works even if you have three outputs.
On 10/12/14 11:02, Jacek Anaszewski wrote:
>>>> +Optional properties:
>>>> >>> +- maxim,fleds : Array of current outputs in order: fled1, fled2.

s/current outputs/LED current regulator outputs used/ ?

>>>> >>> +    Note: both current outputs can be connected to a single led

s/led/LED ? And there seem to be other similar occurrences that would
need to be put in upper case.

>>>> >>> +    Possible values:
>>>> >>> +        MAX77693_LED_FLED_UNUSED - the output is left disconnected,
>>>> >>> +        MAX77693_LED_FLED_USED - a diode is connected to the output.

As noted below, I would simply use 0/1 for these.

>>> >>
>>> >> As you have a LED sub-nodes for each LED already, isn't this redundant?
>> >
>> > Well, it seems so :)
>
> I agreed here recklessly. This property allows to describe the
> situation when one LED is connected to both outputs. Single sub-node
> can describe two type of designs: one LED connected to a single
> output or one LED connected to both outputs. Therefore additional
> property is needed to assess what is the actual case.

How about renaming  "maxim,fleds" to "maxim,active-outputs" ?
And simply using 0 and 1 to indicate if one is used or not, rather
than defining macros for these true/false values ?

--
Regards,
Sylwester
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Hi,

On 04/12/14 17:12, Pavel Machek wrote:
>>>> +- maxim,boost-mode :
>>>> > >>+	In boost mode the device can produce up to 1.2A of total current
>>>> > >>+	on both outputs. The maximum current on each output is reduced
>>>> > >>+	to 625mA then. If there are two child led nodes defined then boost
>>>> > >>+	is enabled by default.
>>>> > >>+	Possible values:
>>>> > >>+		MAX77693_LED_BOOST_OFF - no boost,
>>>> > >>+		MAX77693_LED_BOOST_ADAPTIVE - adaptive mode,
>>>> > >>+		MAX77693_LED_BOOST_FIXED - fixed mode.
>>>> > >>+- maxim,boost-vout : Output voltage of the boost module in millivolts.
>>>> > >>+- maxim,vsys-min : Low input voltage level in millivolts. Flash is not fired
>>>> > >>+	if chip estimates that system voltage could drop below this level due
>>>> > >>+	to flash power consumption.
>>>> > >>+
>>>> > >>+Required properties of the LED child node:
>>>> > >>+- label : see Documentation/devicetree/bindings/leds/common.txt
>>>> > >>+- maxim,fled_id : Identifier of the fled output the led is connected to;
>>> > >
>>> > >I'm pretty sure this will be needed for about every chip that can drive
>>> > >multiple LEDs. Shouldn't it be documented in the generic documentation?
>> > 
>> > OK.
>
> Well... "fled_id" is not exactly suitable name. On other busses, it
> would be "reg = <1>"?

I think we need to clarify what the LED device node subnodes really mean.
I thought initially they describe a physical current output of the LED
controller, but it turns out the subnode corresponds to a LED attached
to the LED controller.  Since a LED can be connected to multiple outputs
of the LED controller I think 'reg' property doesn't make sense here.

Then presumably we should use a property in each subnode, telling which
LED controller outputs a LED is connected to?

For instance, if we assign numbers 0, 1 to FLED1, FLED2 outputs of
MAX77693 and there is just one LED connected to those outputs we would
have something like:

max77693: led {
	compatible = "maxim,max77693-led";	
	...
	led1 {
		maxim,fled-sources = <0 1>;
		...
	};
};

Feel free to propose better name for the property, I guess we need to
avoid "maxim,current-sources" due to ambiguity of the word "current".

--
Regards,
Sylwester
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Jacek Anaszewski Dec. 10, 2014, 12:41 p.m. UTC | #11
On 12/10/2014 01:20 PM, Sylwester Nawrocki wrote:
> Hi,
>
> On 04/12/14 17:12, Pavel Machek wrote:
>>>>> +- maxim,boost-mode :
>>>>>>>> +	In boost mode the device can produce up to 1.2A of total current
>>>>>>>> +	on both outputs. The maximum current on each output is reduced
>>>>>>>> +	to 625mA then. If there are two child led nodes defined then boost
>>>>>>>> +	is enabled by default.
>>>>>>>> +	Possible values:
>>>>>>>> +		MAX77693_LED_BOOST_OFF - no boost,
>>>>>>>> +		MAX77693_LED_BOOST_ADAPTIVE - adaptive mode,
>>>>>>>> +		MAX77693_LED_BOOST_FIXED - fixed mode.
>>>>>>>> +- maxim,boost-vout : Output voltage of the boost module in millivolts.
>>>>>>>> +- maxim,vsys-min : Low input voltage level in millivolts. Flash is not fired
>>>>>>>> +	if chip estimates that system voltage could drop below this level due
>>>>>>>> +	to flash power consumption.
>>>>>>>> +
>>>>>>>> +Required properties of the LED child node:
>>>>>>>> +- label : see Documentation/devicetree/bindings/leds/common.txt
>>>>>>>> +- maxim,fled_id : Identifier of the fled output the led is connected to;
>>>>>>
>>>>>> I'm pretty sure this will be needed for about every chip that can drive
>>>>>> multiple LEDs. Shouldn't it be documented in the generic documentation?
>>>>
>>>> OK.
>>
>> Well... "fled_id" is not exactly suitable name. On other busses, it
>> would be "reg = <1>"?
>
> I think we need to clarify what the LED device node subnodes really mean.
> I thought initially they describe a physical current output of the LED
> controller, but it turns out the subnode corresponds to a LED attached
> to the LED controller.  Since a LED can be connected to multiple outputs
> of the LED controller I think 'reg' property doesn't make sense here.
>
> Then presumably we should use a property in each subnode, telling which
> LED controller outputs a LED is connected to?
>
> For instance, if we assign numbers 0, 1 to FLED1, FLED2 outputs of
> MAX77693 and there is just one LED connected to those outputs we would
> have something like:
>
> max77693: led {
> 	compatible = "maxim,max77693-led";	
> 	...
> 	led1 {
> 		maxim,fled-sources = <0 1>;
> 		...
> 	};
> };
>
> Feel free to propose better name for the property, I guess we need to
> avoid "maxim,current-sources" due to ambiguity of the word "current".

For me this sounds reasonable. Moreover we will avoid the need for
address-cells and size-cells properties in the parent node.

Best Regards,
Jacek Anaszewski
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
diff mbox

Patch

diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt b/Documentation/devicetree/bindings/mfd/max77693.txt
index 01e9f30..25a6e78 100644
--- a/Documentation/devicetree/bindings/mfd/max77693.txt
+++ b/Documentation/devicetree/bindings/mfd/max77693.txt
@@ -41,7 +41,66 @@  Optional properties:
 	 To get more informations, please refer to documentaion.
 	[*] refer Documentation/devicetree/bindings/pwm/pwm.txt
 
+- led : the LED submodule device node
+
+There are two led outputs available - fled1 and fled2. Each of them can
+control a separate led or they can be connected together to double
+the maximum current for a single connected led. One led is represented
+by one child node.
+
+Required properties:
+- compatible : Must be "maxim,max77693-led".
+
+Optional properties:
+- maxim,fleds : Array of current outputs in order: fled1, fled2.
+	Note: both current outputs can be connected to a single led
+	Possible values:
+		MAX77693_LED_FLED_UNUSED - the output is left disconnected,
+		MAX77693_LED_FLED_USED - a diode is connected to the output.
+- maxim,trigger-type : Array of trigger types in order: flash, torch.
+	Possible trigger types:
+		MAX77693_LED_TRIG_TYPE_EDGE - Rising edge of the signal triggers
+			the flash/torch,
+		MAX77693_LED_TRIG_TYPE_LEVEL - Signal level controls duration of
+			the flash/torch.
+- maxim,trigger : Array of flags indicating which trigger can activate given led
+	in order: fled1, fled2.
+	Possible flag values (can be combined):
+		MAX77693_LED_TRIG_FLASHEN - FLASHEN pin of the chip,
+		MAX77693_LED_TRIG_TORCHEN - TORCHEN pin of the chip,
+		MAX77693_LED_TRIG_SOFTWARE - software via I2C command.
+- maxim,boost-mode :
+	In boost mode the device can produce up to 1.2A of total current
+	on both outputs. The maximum current on each output is reduced
+	to 625mA then. If there are two child led nodes defined then boost
+	is enabled by default.
+	Possible values:
+		MAX77693_LED_BOOST_OFF - no boost,
+		MAX77693_LED_BOOST_ADAPTIVE - adaptive mode,
+		MAX77693_LED_BOOST_FIXED - fixed mode.
+- maxim,boost-vout : Output voltage of the boost module in millivolts.
+- maxim,vsys-min : Low input voltage level in millivolts. Flash is not fired
+	if chip estimates that system voltage could drop below this level due
+	to flash power consumption.
+
+Required properties of the LED child node:
+- label : see Documentation/devicetree/bindings/leds/common.txt
+- maxim,fled_id : Identifier of the fled output the led is connected to;
+		MAX77693_LED_FLED1 - FLED1 output of the device - it has to be
+			used also if a single LED is connected to both outputs,
+		MAX77693_LED_FLED2 - FLED2 output of the device.
+
+Optional properties of the LED child node:
+- max-microamp : see Documentation/devicetree/bindings/leds/common.txt
+		Range: 15625 - 250000
+- flash-max-microamp : see Documentation/devicetree/bindings/leds/common.txt
+		Range: 15625 - 1000000
+- flash-timeout-microsec : see Documentation/devicetree/bindings/leds/common.txt
+		Range: 62500 - 1000000
+
 Example:
+#include <dt-bindings/mfd/max77693.h>
+
 	max77693@66 {
 		compatible = "maxim,max77693";
 		reg = <0x66>;
@@ -73,4 +132,34 @@  Example:
 			pwms = <&pwm 0 40000 0>;
 			pwm-names = "haptic";
 		};
+
+		led {
+			compatible = "maxim,max77693-led";
+			maxim,fleds = <MAX77693_LED_FLED_USED
+				       MAX77693_LED_FLED_USED>;
+			maxim,trigger = <MAX77693_LED_TRIG_ALL
+					 (MAX77693_LED_TRIG_TORCHEN |
+					 MAX77693_LED_TRIG_SOFTWARE)>;
+			maxim,trigger-type = <MAX77693_LED_TRIG_TYPE_EDGE
+					      MAX77693_LED_TRIG_TYPE_LEVEL>;
+			maxim,boost-mode = <MAX77693_LED_BOOST_ADAPTIVE>;
+			maxim,boost-vout = <5000>;
+			maxim,vsys-min = <2400>;
+
+			camera1_flash: led1 {
+				maxim,fled_id = <MAX77693_LED_FLED1>;
+				label = "max77693-flash1";
+				max-microamp = <250000>;
+				flash-max-microamp = <625000>;
+				flash-timeout-microsec = <1000000>;
+			};
+
+			camera2_flash: led2 {
+				maxim,fled_id = <MAX77693_LED_FLED2>;
+				label = "max77693-flash2";
+				max-microamp = <250000>;
+				flash-max-microamp = <500000>;
+				flash-timeout-microsec = <1000000>;
+			};
+		};
 	};