[v1,02/11] DT: Add documentation for the mfd Maxim max77693

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>
---
 Documentation/devicetree/bindings/mfd/max77693.txt |   61 ++++++++++++++++++++
 1 file changed, 61 insertions(+)

Hi Jacek,

On Fri, Mar 20, 2015 at 04:03:22PM +0100, Jacek Anaszewski wrote:
> +Optional properties of the LED child node:
> +- label : see Documentation/devicetree/bindings/leds/common.txt

I'm still not comfortable using the label field as-is as the entity name in
the later patches, there's one important problem: it is not guaranteed to be
unique in the system.

Do you think this could be added to
Documentation/devicetree/bindings/leds/common.txt, with perhaps enforcing it
in the LED framework? Bryan, what do you think?

The alternative would be to simply ignore it in the entity name, but then
the name of the device would be different in the LED framework and Media
controller.

Hi Sakari,

On 03/21/2015 11:49 PM, Sakari Ailus wrote:
> Hi Jacek,
>
> On Fri, Mar 20, 2015 at 04:03:22PM +0100, Jacek Anaszewski wrote:
>> +Optional properties of the LED child node:
>> +- label : see Documentation/devicetree/bindings/leds/common.txt
>
> I'm still not comfortable using the label field as-is as the entity name in
> the later patches, there's one important problem: it is not guaranteed to be
> unique in the system.

I don't use it as-is in my patches. For max77603-led the i2c adapter id
and client address is added to it, and for aat1290 there is '_n' suffix
added. Nonetheless I didn't notice that the patch [1] was already
merged. It checks if a LED class device with given name isn't already
registered and adds a '_n" suffix if there was any. If it was exported
I could use it in the leds-aat1290 driver and avoid depending on the
static variable.

Whereas for I2C devices the problem doesn't exist (it is guaranteed that
no more than one I2C client with an address can be present on the
same bus), for devices driven through GPIOs we haven't stable unique
identifier.

I thought that we agreed on #v4l about adding numerical postfixes
in case of such devices.

> Do you think this could be added to
> Documentation/devicetree/bindings/leds/common.txt, with perhaps enforcing it
> in the LED framework? Bryan, what do you think?

The patch [1] seems to address the issue.

> The alternative would be to simply ignore it in the entity name, but then
> the name of the device would be different in the LED framework and Media
> controller.
>

This is the case currently - the names are different. The post fixes
are added only to media entity name. Perhaps they should be unified.


[1] http://www.spinics.net/lists/linux-leds/msg03137.html

Hi Jacek,

On Mon, Mar 23, 2015 at 10:54:11AM +0100, Jacek Anaszewski wrote:
> Hi Sakari,
> 
> On 03/21/2015 11:49 PM, Sakari Ailus wrote:
> >Hi Jacek,
> >
> >On Fri, Mar 20, 2015 at 04:03:22PM +0100, Jacek Anaszewski wrote:
> >>+Optional properties of the LED child node:
> >>+- label : see Documentation/devicetree/bindings/leds/common.txt
> >
> >I'm still not comfortable using the label field as-is as the entity name in
> >the later patches, there's one important problem: it is not guaranteed to be
> >unique in the system.
> 
> I don't use it as-is in my patches. For max77603-led the i2c adapter id
> and client address is added to it, and for aat1290 there is '_n' suffix
> added. Nonetheless I didn't notice that the patch [1] was already
> merged. It checks if a LED class device with given name isn't already
> registered and adds a '_n" suffix if there was any. If it was exported
> I could use it in the leds-aat1290 driver and avoid depending on the
> static variable.
> 
> Whereas for I2C devices the problem doesn't exist (it is guaranteed that
> no more than one I2C client with an address can be present on the
> same bus), for devices driven through GPIOs we haven't stable unique
> identifier.
> 
> I thought that we agreed on #v4l about adding numerical postfixes
> in case of such devices.
> 
> >Do you think this could be added to
> >Documentation/devicetree/bindings/leds/common.txt, with perhaps enforcing it
> >in the LED framework? Bryan, what do you think?
> 
> The patch [1] seems to address the issue.

Replied to that, you're cc'd.

For this patch:

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

On Fri, 20 Mar 2015, 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>
> ---
>  Documentation/devicetree/bindings/mfd/max77693.txt |   61 ++++++++++++++++++++
>  1 file changed, 61 insertions(+)

Bryan and/or one of the DT folks really need to Ack this.

> diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt b/Documentation/devicetree/bindings/mfd/max77693.txt
> index 38e6440..15c546e 100644
> --- a/Documentation/devicetree/bindings/mfd/max77693.txt
> +++ b/Documentation/devicetree/bindings/mfd/max77693.txt
> @@ -76,7 +76,53 @@ Optional properties:
>      Valid values: 4300000, 4700000, 4800000, 4900000
>      Default: 4300000
>  
> +- 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,trigger-type : Flash trigger type.
> +	Possible trigger types:
> +		LEDS_TRIG_TYPE_EDGE (0) - Rising edge of the signal triggers
> +			the flash,
> +		LEDS_TRIG_TYPE_LEVEL (1) - Strobe pulse length controls duration
> +			of the flash.
> +- 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 not enabled explicitly, boost setting defaults to
> +	LEDS_BOOST_FIXED in case both current sources are used.
> +	Possible values:
> +		LEDS_BOOST_OFF (0) - no boost,
> +		LEDS_BOOST_ADAPTIVE (1) - adaptive mode,
> +		LEDS_BOOST_FIXED (2) - fixed mode.
> +- maxim,boost-mvout : Output voltage of the boost module in millivolts.
> +- maxim,mvsys-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:
> +- led-sources : see Documentation/devicetree/bindings/leds/common.txt;
> +		device current output identifiers: 0 - FLED1, 1 - FLED2
> +
> +Optional properties of the LED child node:
> +- label : see Documentation/devicetree/bindings/leds/common.txt
> +- 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-us : see Documentation/devicetree/bindings/leds/common.txt
> +		Range: 62500 - 1000000
> +
>  Example:
> +#include <dt-bindings/leds/common.h>
> +
>  	max77693@66 {
>  		compatible = "maxim,max77693";
>  		reg = <0x66>;
> @@ -117,5 +163,20 @@ Example:
>  			maxim,thermal-regulation-celsius = <75>;
>  			maxim,battery-overcurrent-microamp = <3000000>;
>  			maxim,charge-input-threshold-microvolt = <4300000>;
> +
> +		led {
> +			compatible = "maxim,max77693-led";
> +			maxim,trigger-type = <LEDS_TRIG_TYPE_LEVEL>;
> +			maxim,boost-mode = <LEDS_BOOST_FIXED>;
> +			maxim,boost-mvout = <5000>;
> +			maxim,mvsys-min = <2400>;
> +
> +			camera_flash: flash-led {
> +				label = "max77693-flash";
> +				led-sources = <0>, <1>;
> +				max-microamp = <500000>;
> +				flash-max-microamp = <1250000>;
> +				flash-timeout-us = <1000000>;
> +			};
>  		};
>  	};