[PATCH 0/3] mfd: Improve DT binding docs for max77686 and max77802

[PATCH 0/3] mfd: Improve DT binding docs for max77686 and max77802

[Javier Martinez Canillas]

Hello Lee,

This series contains some improvements for the Device Tree bindings of
the Maxim MAX77686 and MAX77802 multi-function devices.

Patch #1 changes the max77686 binding to not suggest using a deprecated
property of the regulator DT binding.

Patch #2 adds a DT binding for the mfd portion of the max77802 that was
missing.

Patch #3 moves the regulator portion of the max77686 to the regulator's
DT binding sub-directory since it is a better fit for this information.
This third patch needs an ack from the regulator sub-system maintainer.


Javier Martinez Canillas (3):
  mfd: max77686: Don't suggest in binding to use a deprecated property
  mfd: Add DT binding for Maxim MAX77802 IC
  mfd: max77686: Split out regulator part from the DT binding

 Documentation/devicetree/bindings/mfd/max77686.txt | 61 +------------------
 Documentation/devicetree/bindings/mfd/max77802.txt | 26 ++++++++
 .../devicetree/bindings/regulator/max77686.txt     | 71 ++++++++++++++++++++++
 3 files changed, 100 insertions(+), 58 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/mfd/max77802.txt
 create mode 100644 Documentation/devicetree/bindings/regulator/max77686.txt

-- 
2.4.3

[PATCH 1/3] mfd: max77686: Don't suggest in binding to use a deprecated property

[Javier Martinez Canillas]

The regulator-compatible property from the regulator DT binding was
deprecated. But the max77686 DT binding doc still suggest to use it
instead of the regulator node name's which is the correct approach.

Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
---

 Documentation/devicetree/bindings/mfd/max77686.txt | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/Documentation/devicetree/bindings/mfd/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt
index 163bd81a4607..8221102d3fc2 100644
--- a/Documentation/devicetree/bindings/mfd/max77686.txt
+++ b/Documentation/devicetree/bindings/mfd/max77686.txt
@@ -26,7 +26,7 @@ Optional node:
 	};
 	refer Documentation/devicetree/bindings/regulator/regulator.txt
 
-  The regulator-compatible property of regulator should initialized with string
+  The regulator node's name should be initialized with a string
 to get matched with their hardware counterparts as follow:
 
 	-LDOn 	:	for LDOs, where n can lie in range 1 to 26.
@@ -55,16 +55,14 @@ Example:
 		reg = <0x09>;
 
 		voltage-regulators {
-			ldo11_reg {
-				regulator-compatible = "LDO11";
+			ldo11_reg: LDO11 {
 				regulator-name = "vdd_ldo11";
 				regulator-min-microvolt = <1900000>;
 				regulator-max-microvolt = <1900000>;
 				regulator-always-on;
 			};
 
-			buck1_reg {
-				regulator-compatible = "BUCK1";
+			buck1_reg: BUCK1 {
 				regulator-name = "vdd_mif";
 				regulator-min-microvolt = <950000>;
 				regulator-max-microvolt = <1300000>;
@@ -72,8 +70,7 @@ Example:
 				regulator-boot-on;
 			};
 
-			buck9_reg {
-				regulator-compatible = "BUCK9";
+			buck9_reg: BUCK9 {
 				regulator-name = "CAM_ISP_CORE_1.2V";
 				regulator-min-microvolt = <1000000>;
 				regulator-max-microvolt = <1200000>;
-- 
2.4.3

Re: [PATCH 1/3] mfd: max77686: Don't suggest in binding to use a deprecated property

[Krzysztof Kozlowski]

On 13.07.2015 16:42, Javier Martinez Canillas wrote:
> The regulator-compatible property from the regulator DT binding was
> deprecated. But the max77686 DT binding doc still suggest to use it
> instead of the regulator node name's which is the correct approach.
> 
> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
> ---
> 
>  Documentation/devicetree/bindings/mfd/max77686.txt | 11 ++++-------
>  1 file changed, 4 insertions(+), 7 deletions(-)

Reviewed-by: Krzysztof Kozlowski <k.kozlowski@samsung.com>

Best regards,
Krzysztof

[PATCH 2/3] mfd: Add DT binding for Maxim MAX77802 IC

[Javier Martinez Canillas]

The MAX77802 is a chip that contains regulators, 2 32kHz clocks,
a RTC and an I2C interface to program the individual components.

The are already DT bindings for the regulators and clocks and
these reference to a bindings/mfd/max77802.txt file, that didn't
exist, for the details about the PMIC.

Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
---

 Documentation/devicetree/bindings/mfd/max77802.txt | 26 ++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mfd/max77802.txt

diff --git a/Documentation/devicetree/bindings/mfd/max77802.txt b/Documentation/devicetree/bindings/mfd/max77802.txt
new file mode 100644
index 000000000000..875ebebbc5b0
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/max77802.txt
@@ -0,0 +1,26 @@
+Maxim MAX77802 multi-function device
+
+The Maxim MAX77802 is a power management chip (PMIC) that contains 10 high
+efficiency Buck regulators, 32 Low-dropout (LDO) regulators used to power
+up application processors and peripherals, a 2-channel 32kHz clock outputs,
+a Real-Time-Clock (RTC) and a I2C interface to program the individual
+regulators, clocks outputs and the RTC.
+
+Binding for the built-in 32k clock generator block is defined separately
+in the bindings/clk/maxim,max77802.txt file and binding for the regulators
+is defined in the bindings/regulator/max77802.txt file.
+
+Required properties:
+- compatible : Must be "maxim,max77686";
+- reg : Specifies the i2c slave address of PMIC block.
+- interrupts : This i2c device has an IRQ line connected to the main SoC.
+- interrupt-parent : The parent interrupt controller.
+
+Example:
+
+	max77802@09 {
+		compatible = "maxim,max77802";
+		interrupt-parent = <&intc>;
+		interrupts = <26 0>;
+		reg = <0x09>;
+	};
-- 
2.4.3

Re: [PATCH 2/3] mfd: Add DT binding for Maxim MAX77802 IC

[Krzysztof Kozlowski]

On 13.07.2015 16:42, Javier Martinez Canillas wrote:
> The MAX77802 is a chip that contains regulators, 2 32kHz clocks,
> a RTC and an I2C interface to program the individual components.
> 
> The are already DT bindings for the regulators and clocks and
> these reference to a bindings/mfd/max77802.txt file, that didn't
> exist, for the details about the PMIC.
> 
> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
> ---
> 
>  Documentation/devicetree/bindings/mfd/max77802.txt | 26 ++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mfd/max77802.txt

I wonder what happened with previous email...
http://www.spinics.net/lists/kernel/msg1784726.html

> 
> diff --git a/Documentation/devicetree/bindings/mfd/max77802.txt b/Documentation/devicetree/bindings/mfd/max77802.txt
> new file mode 100644
> index 000000000000..875ebebbc5b0
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/max77802.txt
> @@ -0,0 +1,26 @@
> +Maxim MAX77802 multi-function device
> +
> +The Maxim MAX77802 is a power management chip (PMIC) that contains 10 high
> +efficiency Buck regulators, 32 Low-dropout (LDO) regulators used to power
> +up application processors and peripherals, a 2-channel 32kHz clock outputs,
> +a Real-Time-Clock (RTC) and a I2C interface to program the individual
> +regulators, clocks outputs and the RTC.
> +
> +Binding for the built-in 32k clock generator block is defined separately
> +in the bindings/clk/maxim,max77802.txt file and binding for the regulators
> +is defined in the bindings/regulator/max77802.txt file.
> +
> +Required properties:
> +- compatible : Must be "maxim,max77686";

Shouldn't this be 77802?

Best regards,
Krzysztof

> +- reg : Specifies the i2c slave address of PMIC block.
> +- interrupts : This i2c device has an IRQ line connected to the main SoC.
> +- interrupt-parent : The parent interrupt controller.
> +
> +Example:
> +
> +	max77802@09 {
> +		compatible = "maxim,max77802";
> +		interrupt-parent = <&intc>;
> +		interrupts = <26 0>;
> +		reg = <0x09>;
> +	};
> 

Re: [PATCH 2/3] mfd: Add DT binding for Maxim MAX77802 IC

[Javier Martinez Canillas]

Hello Krzysztof,

Thanks a lot for the feedback.

On 07/13/2015 09:53 AM, Krzysztof Kozlowski wrote:
> On 13.07.2015 16:42, Javier Martinez Canillas wrote:
>> The MAX77802 is a chip that contains regulators, 2 32kHz clocks,
>> a RTC and an I2C interface to program the individual components.
>>
>> The are already DT bindings for the regulators and clocks and
>> these reference to a bindings/mfd/max77802.txt file, that didn't
>> exist, for the details about the PMIC.
>>
>> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
>> ---
>>
>>  Documentation/devicetree/bindings/mfd/max77802.txt | 26 ++++++++++++++++++++++
>>  1 file changed, 26 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/mfd/max77802.txt
> 
> I wonder what happened with previous email...
> http://www.spinics.net/lists/kernel/msg1784726.html
>

The story is that in v9 I split the series to add the max77802 clock and
regulators support as different series to avoid the cross subsystem churn:

[PATCH v9 0/6] Add Maxim 77802 clocks support
https://lwn.net/Articles/608834/

[PATCH v9 0/2] Add Maxim 77802 regulator support
https://lkml.org/lkml/2014/8/18/71

But then forgot to add the common DT binding for the PMIC in bindings/mfd...

>>
>> diff --git a/Documentation/devicetree/bindings/mfd/max77802.txt b/Documentation/devicetree/bindings/mfd/max77802.txt
>> new file mode 100644
>> index 000000000000..875ebebbc5b0
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mfd/max77802.txt
>> @@ -0,0 +1,26 @@
>> +Maxim MAX77802 multi-function device
>> +
>> +The Maxim MAX77802 is a power management chip (PMIC) that contains 10 high
>> +efficiency Buck regulators, 32 Low-dropout (LDO) regulators used to power
>> +up application processors and peripherals, a 2-channel 32kHz clock outputs,
>> +a Real-Time-Clock (RTC) and a I2C interface to program the individual
>> +regulators, clocks outputs and the RTC.
>> +
>> +Binding for the built-in 32k clock generator block is defined separately
>> +in the bindings/clk/maxim,max77802.txt file and binding for the regulators
>> +is defined in the bindings/regulator/max77802.txt file.
>> +
>> +Required properties:
>> +- compatible : Must be "maxim,max77686";
> 
> Shouldn't this be 77802?
>

right, thanks for pointing out this. It is a copy & paste error. I'll wait a
couple of days for more feedback and re-post.

> Best regards,
> Krzysztof
> 

Best regards,
-- 
Javier Martinez Canillas
Open Source Group
Samsung Research America

Re: [PATCH 2/3] mfd: Add DT binding for Maxim MAX77802 IC

[Sergei Shtylyov]

Hello.

On 7/13/2015 10:42 AM, Javier Martinez Canillas wrote:

> The MAX77802 is a chip that contains regulators, 2 32kHz clocks,
> a RTC and an I2C interface to program the individual components.

> The are already DT bindings for the regulators and clocks and
> these reference to a bindings/mfd/max77802.txt file, that didn't
> exist, for the details about the PMIC.

> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
> ---
>
>   Documentation/devicetree/bindings/mfd/max77802.txt | 26 ++++++++++++++++++++++
>   1 file changed, 26 insertions(+)
>   create mode 100644 Documentation/devicetree/bindings/mfd/max77802.txt

> diff --git a/Documentation/devicetree/bindings/mfd/max77802.txt b/Documentation/devicetree/bindings/mfd/max77802.txt
> new file mode 100644
> index 000000000000..875ebebbc5b0
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/max77802.txt
> @@ -0,0 +1,26 @@
> +Maxim MAX77802 multi-function device
> +
> +The Maxim MAX77802 is a power management chip (PMIC) that contains 10 high
> +efficiency Buck regulators, 32 Low-dropout (LDO) regulators used to power
> +up application processors and peripherals, a 2-channel 32kHz clock outputs,
> +a Real-Time-Clock (RTC) and a I2C interface to program the individual
> +regulators, clocks outputs and the RTC.
> +
> +Binding for the built-in 32k clock generator block is defined separately
> +in the bindings/clk/maxim,max77802.txt file and binding for the regulators
> +is defined in the bindings/regulator/max77802.txt file.
> +
> +Required properties:
> +- compatible : Must be "maxim,max77686";
> +- reg : Specifies the i2c slave address of PMIC block.
> +- interrupts : This i2c device has an IRQ line connected to the main SoC.
> +- interrupt-parent : The parent interrupt controller.
> +
> +Example:
> +
> +	max77802@09 {

    Sigh, I'm tired of saying this over and over again: please don't name the 
nodes with teh chip names. The ePAPR standard says: "The name of a node should 
be somewhat generic, reflecting the function of the device and not its 3 
precise programming model."

WBR, Sergei

Re: [PATCH 2/3] mfd: Add DT binding for Maxim MAX77802 IC

[Javier Martinez Canillas]

Hello Sergei,

On 07/13/2015 03:11 PM, Sergei Shtylyov wrote:
> Hello.
> 
> On 7/13/2015 10:42 AM, Javier Martinez Canillas wrote:
> 
>> The MAX77802 is a chip that contains regulators, 2 32kHz clocks,
>> a RTC and an I2C interface to program the individual components.
> 
>> The are already DT bindings for the regulators and clocks and
>> these reference to a bindings/mfd/max77802.txt file, that didn't
>> exist, for the details about the PMIC.
> 
>> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
>> ---
>>
>>   Documentation/devicetree/bindings/mfd/max77802.txt | 26 ++++++++++++++++++++++
>>   1 file changed, 26 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/mfd/max77802.txt
> 
>> diff --git a/Documentation/devicetree/bindings/mfd/max77802.txt b/Documentation/devicetree/bindings/mfd/max77802.txt
>> new file mode 100644
>> index 000000000000..875ebebbc5b0
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mfd/max77802.txt
>> @@ -0,0 +1,26 @@
>> +Maxim MAX77802 multi-function device
>> +
>> +The Maxim MAX77802 is a power management chip (PMIC) that contains 10 high
>> +efficiency Buck regulators, 32 Low-dropout (LDO) regulators used to power
>> +up application processors and peripherals, a 2-channel 32kHz clock outputs,
>> +a Real-Time-Clock (RTC) and a I2C interface to program the individual
>> +regulators, clocks outputs and the RTC.
>> +
>> +Binding for the built-in 32k clock generator block is defined separately
>> +in the bindings/clk/maxim,max77802.txt file and binding for the regulators
>> +is defined in the bindings/regulator/max77802.txt file.
>> +
>> +Required properties:
>> +- compatible : Must be "maxim,max77686";
>> +- reg : Specifies the i2c slave address of PMIC block.
>> +- interrupts : This i2c device has an IRQ line connected to the main SoC.
>> +- interrupt-parent : The parent interrupt controller.
>> +
>> +Example:
>> +
>> +    max77802@09 {
> 
>    Sigh, I'm tired of saying this over and over again: please don't name the nodes with teh chip names. The ePAPR standard says: "The name of a node should be somewhat generic, reflecting the function of the device and not its 3 precise programming model."
> 

Ok, I'll change this to be pmic@ when re-spinning the patches.

> WBR, Sergei
> 

Best regards,
-- 
Javier Martinez Canillas
Open Source Group
Samsung Research America

[PATCH 3/3] mfd: max77686: Split out regulator part from the DT binding

[Javier Martinez Canillas]

The Maxim MAX77686 PMIC is a multi-function device with regulators,
clocks and a RTC. The DT bindings for the clocks are in a separate
file but the bindings for the regulators are inside the mfd part.

To make it consistent with the clocks portion of the binding and
because is more natural to look for regulator bindings under the
bindings/regulator sub-directory, split the regulator portion of
the DT binding and add it as a separate file.

Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>

---

 Documentation/devicetree/bindings/mfd/max77686.txt | 58 +-----------------
 .../devicetree/bindings/regulator/max77686.txt     | 71 ++++++++++++++++++++++
 2 files changed, 74 insertions(+), 55 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/regulator/max77686.txt

diff --git a/Documentation/devicetree/bindings/mfd/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt
index 8221102d3fc2..8a276dd5ea46 100644
--- a/Documentation/devicetree/bindings/mfd/max77686.txt
+++ b/Documentation/devicetree/bindings/mfd/max77686.txt
@@ -8,7 +8,8 @@ client while probing.This document describes the binding for mfd device and
 PMIC submodule.
 
 Binding for the built-in 32k clock generator block is defined separately
-in bindings/clk/maxim,max77686.txt file.
+in the bindings/clk/maxim,max77686.txt file and binding for the regulators
+is defined in the bindings/regulator/max77686.txt file.
 
 Required properties:
 - compatible : Must be "maxim,max77686";
@@ -16,36 +17,6 @@ Required properties:
 - interrupts : This i2c device has an IRQ line connected to the main SoC.
 - interrupt-parent : The parent interrupt controller.
 
-Optional node:
-- voltage-regulators : The regulators of max77686 have to be instantiated
-  under subnode named "voltage-regulators" using the following format.
-
-	regulator_name {
-		regulator-compatible = LDOn/BUCKn
-		standard regulator constraints....
-	};
-	refer Documentation/devicetree/bindings/regulator/regulator.txt
-
-  The regulator node's name should be initialized with a string
-to get matched with their hardware counterparts as follow:
-
-	-LDOn 	:	for LDOs, where n can lie in range 1 to 26.
-		 	example: LDO1, LDO2, LDO26.
-	-BUCKn 	:	for BUCKs, where n can lie in range 1 to 9.
-			example: BUCK1, BUCK5, BUCK9.
-
-  Regulators which can be turned off during system suspend:
-	-LDOn	:	2, 6-8, 10-12, 14-16,
-	-BUCKn	:	1-4.
-  Use standard regulator bindings for it ('regulator-off-in-suspend').
-
-  LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable
-  control. To turn this feature on this property must be added to the regulator
-  sub-node:
-	- maxim,ena-gpios :	one GPIO specifier enable control (the gpio
-				flags are actually ignored and always
-				ACTIVE_HIGH is used)
-
 Example:
 
 	max77686@09 {
@@ -53,27 +24,4 @@ Example:
 		interrupt-parent = <&wakeup_eint>;
 		interrupts = <26 0>;
 		reg = <0x09>;
-
-		voltage-regulators {
-			ldo11_reg: LDO11 {
-				regulator-name = "vdd_ldo11";
-				regulator-min-microvolt = <1900000>;
-				regulator-max-microvolt = <1900000>;
-				regulator-always-on;
-			};
-
-			buck1_reg: BUCK1 {
-				regulator-name = "vdd_mif";
-				regulator-min-microvolt = <950000>;
-				regulator-max-microvolt = <1300000>;
-				regulator-always-on;
-				regulator-boot-on;
-			};
-
-			buck9_reg: BUCK9 {
-				regulator-name = "CAM_ISP_CORE_1.2V";
-				regulator-min-microvolt = <1000000>;
-				regulator-max-microvolt = <1200000>;
-				maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>;
-			};
-	}
+	};
diff --git a/Documentation/devicetree/bindings/regulator/max77686.txt b/Documentation/devicetree/bindings/regulator/max77686.txt
new file mode 100644
index 000000000000..04b7604c219e
--- /dev/null
+++ b/Documentation/devicetree/bindings/regulator/max77686.txt
@@ -0,0 +1,71 @@
+Binding for Maxim MAX77686 regulators
+
+This is a part of the device tree bindings of MAX77686 multi-function device.
+More information can be found in bindings/mfd/max77686.txt file.
+
+The MAX77802 PMIC has 9 high-efficiency Buck and 26 Low-dropout (LDO)
+regulators that can be controlled over I2C.
+
+Following properties should be present in main device node of the MFD chip.
+
+Optional node:
+- voltage-regulators : The regulators of max77686 have to be instantiated
+  under subnode named "voltage-regulators" using the following format.
+
+	regulator_name {
+		regulator-compatible = LDOn/BUCKn
+		standard regulator constraints....
+	};
+	refer Documentation/devicetree/bindings/regulator/regulator.txt
+
+  The regulator node's name should be initialized with a string
+to get matched with their hardware counterparts as follow:
+
+	-LDOn 	:	for LDOs, where n can lie in range 1 to 26.
+			example: LDO1, LDO2, LDO26.
+	-BUCKn 	:	for BUCKs, where n can lie in range 1 to 9.
+			example: BUCK1, BUCK5, BUCK9.
+
+  Regulators which can be turned off during system suspend:
+	-LDOn	:	2, 6-8, 10-12, 14-16,
+	-BUCKn	:	1-4.
+  Use standard regulator bindings for it ('regulator-off-in-suspend').
+
+  LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable
+  control. To turn this feature on this property must be added to the regulator
+  sub-node:
+	- maxim,ena-gpios :	one GPIO specifier enable control (the gpio
+				flags are actually ignored and always
+				ACTIVE_HIGH is used)
+
+Example:
+
+	max77686@09 {
+		compatible = "maxim,max77686";
+		interrupt-parent = <&wakeup_eint>;
+		interrupts = <26 0>;
+		reg = <0x09>;
+
+		voltage-regulators {
+			ldo11_reg: LDO11 {
+				regulator-name = "vdd_ldo11";
+				regulator-min-microvolt = <1900000>;
+				regulator-max-microvolt = <1900000>;
+				regulator-always-on;
+			};
+
+			buck1_reg: BUCK1 {
+				regulator-name = "vdd_mif";
+				regulator-min-microvolt = <950000>;
+				regulator-max-microvolt = <1300000>;
+				regulator-always-on;
+				regulator-boot-on;
+			};
+
+			buck9_reg: BUCK9 {
+				regulator-name = "CAM_ISP_CORE_1.2V";
+				regulator-min-microvolt = <1000000>;
+				regulator-max-microvolt = <1200000>;
+				maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>;
+			};
+	};
-- 
2.4.3

Re: [PATCH 3/3] mfd: max77686: Split out regulator part from the DT binding

[Krzysztof Kozlowski]

On 13.07.2015 16:42, Javier Martinez Canillas wrote:
> The Maxim MAX77686 PMIC is a multi-function device with regulators,
> clocks and a RTC. The DT bindings for the clocks are in a separate
> file but the bindings for the regulators are inside the mfd part.
> 
> To make it consistent with the clocks portion of the binding and
> because is more natural to look for regulator bindings under the
> bindings/regulator sub-directory, split the regulator portion of
> the DT binding and add it as a separate file.
> 
> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
> 
> ---
> 
>  Documentation/devicetree/bindings/mfd/max77686.txt | 58 +-----------------
>  .../devicetree/bindings/regulator/max77686.txt     | 71 ++++++++++++++++++++++
>  2 files changed, 74 insertions(+), 55 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/regulator/max77686.txt

Actually I would prefer the opposite - merging everything into one file
(clocks, regulators -> mfd) because:

1. Separate files introduce some duplication (like introduction and
common part of example node).

2. It is easier to track the changes and update them. For example when
adding a new chipset to the driver one may forgot about updating other
files. When moving files one may forgot to update hard-coded path in
some other file.

3. When comparing existing DTS with documentation or when creating new
DTS for the device it is just faster to fetch everything (knowledge,
example node) from one file.

However I understand that such opinion may be not suited for the idea of
MFD...

Best regards,
Krzysztof

> 
> diff --git a/Documentation/devicetree/bindings/mfd/max77686.txt b/Documentation/devicetree/bindings/mfd/max77686.txt
> index 8221102d3fc2..8a276dd5ea46 100644
> --- a/Documentation/devicetree/bindings/mfd/max77686.txt
> +++ b/Documentation/devicetree/bindings/mfd/max77686.txt
> @@ -8,7 +8,8 @@ client while probing.This document describes the binding for mfd device and
>  PMIC submodule.
>  
>  Binding for the built-in 32k clock generator block is defined separately
> -in bindings/clk/maxim,max77686.txt file.
> +in the bindings/clk/maxim,max77686.txt file and binding for the regulators
> +is defined in the bindings/regulator/max77686.txt file.
>  
>  Required properties:
>  - compatible : Must be "maxim,max77686";
> @@ -16,36 +17,6 @@ Required properties:
>  - interrupts : This i2c device has an IRQ line connected to the main SoC.
>  - interrupt-parent : The parent interrupt controller.
>  
> -Optional node:
> -- voltage-regulators : The regulators of max77686 have to be instantiated
> -  under subnode named "voltage-regulators" using the following format.
> -
> -	regulator_name {
> -		regulator-compatible = LDOn/BUCKn
> -		standard regulator constraints....
> -	};
> -	refer Documentation/devicetree/bindings/regulator/regulator.txt
> -
> -  The regulator node's name should be initialized with a string
> -to get matched with their hardware counterparts as follow:
> -
> -	-LDOn 	:	for LDOs, where n can lie in range 1 to 26.
> -		 	example: LDO1, LDO2, LDO26.
> -	-BUCKn 	:	for BUCKs, where n can lie in range 1 to 9.
> -			example: BUCK1, BUCK5, BUCK9.
> -
> -  Regulators which can be turned off during system suspend:
> -	-LDOn	:	2, 6-8, 10-12, 14-16,
> -	-BUCKn	:	1-4.
> -  Use standard regulator bindings for it ('regulator-off-in-suspend').
> -
> -  LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable
> -  control. To turn this feature on this property must be added to the regulator
> -  sub-node:
> -	- maxim,ena-gpios :	one GPIO specifier enable control (the gpio
> -				flags are actually ignored and always
> -				ACTIVE_HIGH is used)
> -
>  Example:
>  
>  	max77686@09 {
> @@ -53,27 +24,4 @@ Example:
>  		interrupt-parent = <&wakeup_eint>;
>  		interrupts = <26 0>;
>  		reg = <0x09>;
> -
> -		voltage-regulators {
> -			ldo11_reg: LDO11 {
> -				regulator-name = "vdd_ldo11";
> -				regulator-min-microvolt = <1900000>;
> -				regulator-max-microvolt = <1900000>;
> -				regulator-always-on;
> -			};
> -
> -			buck1_reg: BUCK1 {
> -				regulator-name = "vdd_mif";
> -				regulator-min-microvolt = <950000>;
> -				regulator-max-microvolt = <1300000>;
> -				regulator-always-on;
> -				regulator-boot-on;
> -			};
> -
> -			buck9_reg: BUCK9 {
> -				regulator-name = "CAM_ISP_CORE_1.2V";
> -				regulator-min-microvolt = <1000000>;
> -				regulator-max-microvolt = <1200000>;
> -				maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>;
> -			};
> -	}
> +	};
> diff --git a/Documentation/devicetree/bindings/regulator/max77686.txt b/Documentation/devicetree/bindings/regulator/max77686.txt
> new file mode 100644
> index 000000000000..04b7604c219e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/regulator/max77686.txt
> @@ -0,0 +1,71 @@
> +Binding for Maxim MAX77686 regulators
> +
> +This is a part of the device tree bindings of MAX77686 multi-function device.
> +More information can be found in bindings/mfd/max77686.txt file.
> +
> +The MAX77802 PMIC has 9 high-efficiency Buck and 26 Low-dropout (LDO)
> +regulators that can be controlled over I2C.
> +
> +Following properties should be present in main device node of the MFD chip.
> +
> +Optional node:
> +- voltage-regulators : The regulators of max77686 have to be instantiated
> +  under subnode named "voltage-regulators" using the following format.
> +
> +	regulator_name {
> +		regulator-compatible = LDOn/BUCKn
> +		standard regulator constraints....
> +	};
> +	refer Documentation/devicetree/bindings/regulator/regulator.txt
> +
> +  The regulator node's name should be initialized with a string
> +to get matched with their hardware counterparts as follow:
> +
> +	-LDOn 	:	for LDOs, where n can lie in range 1 to 26.
> +			example: LDO1, LDO2, LDO26.
> +	-BUCKn 	:	for BUCKs, where n can lie in range 1 to 9.
> +			example: BUCK1, BUCK5, BUCK9.
> +
> +  Regulators which can be turned off during system suspend:
> +	-LDOn	:	2, 6-8, 10-12, 14-16,
> +	-BUCKn	:	1-4.
> +  Use standard regulator bindings for it ('regulator-off-in-suspend').
> +
> +  LDO20, LDO21, LDO22, BUCK8 and BUCK9 can be configured to GPIO enable
> +  control. To turn this feature on this property must be added to the regulator
> +  sub-node:
> +	- maxim,ena-gpios :	one GPIO specifier enable control (the gpio
> +				flags are actually ignored and always
> +				ACTIVE_HIGH is used)
> +
> +Example:
> +
> +	max77686@09 {
> +		compatible = "maxim,max77686";
> +		interrupt-parent = <&wakeup_eint>;
> +		interrupts = <26 0>;
> +		reg = <0x09>;
> +
> +		voltage-regulators {
> +			ldo11_reg: LDO11 {
> +				regulator-name = "vdd_ldo11";
> +				regulator-min-microvolt = <1900000>;
> +				regulator-max-microvolt = <1900000>;
> +				regulator-always-on;
> +			};
> +
> +			buck1_reg: BUCK1 {
> +				regulator-name = "vdd_mif";
> +				regulator-min-microvolt = <950000>;
> +				regulator-max-microvolt = <1300000>;
> +				regulator-always-on;
> +				regulator-boot-on;
> +			};
> +
> +			buck9_reg: BUCK9 {
> +				regulator-name = "CAM_ISP_CORE_1.2V";
> +				regulator-min-microvolt = <1000000>;
> +				regulator-max-microvolt = <1200000>;
> +				maxim,ena-gpios = <&gpm0 3 GPIO_ACTIVE_HIGH>;
> +			};
> +	};
> 

Re: [PATCH 3/3] mfd: max77686: Split out regulator part from the DT binding

[Javier Martinez Canillas]

Hello Krzysztof,

On 07/13/2015 10:03 AM, Krzysztof Kozlowski wrote:
> On 13.07.2015 16:42, Javier Martinez Canillas wrote:
>> The Maxim MAX77686 PMIC is a multi-function device with regulators,
>> clocks and a RTC. The DT bindings for the clocks are in a separate
>> file but the bindings for the regulators are inside the mfd part.
>>
>> To make it consistent with the clocks portion of the binding and
>> because is more natural to look for regulator bindings under the
>> bindings/regulator sub-directory, split the regulator portion of
>> the DT binding and add it as a separate file.
>>
>> Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
>>
>> ---
>>
>>  Documentation/devicetree/bindings/mfd/max77686.txt | 58 +-----------------
>>  .../devicetree/bindings/regulator/max77686.txt     | 71 ++++++++++++++++++++++
>>  2 files changed, 74 insertions(+), 55 deletions(-)
>>  create mode 100644 Documentation/devicetree/bindings/regulator/max77686.txt
> 
> Actually I would prefer the opposite - merging everything into one file
> (clocks, regulators -> mfd) because:
> 
> 1. Separate files introduce some duplication (like introduction and
> common part of example node).
> 
> 2. It is easier to track the changes and update them. For example when
> adding a new chipset to the driver one may forgot about updating other
> files. When moving files one may forgot to update hard-coded path in
> some other file.
> 
> 3. When comparing existing DTS with documentation or when creating new
> DTS for the device it is just faster to fetch everything (knowledge,
> example node) from one file.
>

Yes, I also wondered about going the opposite way but then thought
that is more natural to look for clock bindings under bindings/clock
and for regulators drivers under bindings/regulator...
 
> However I understand that such opinion may be not suited for the idea of
> MFD...
>

...but I don't have a strong opinion and can do the other way if folks
are more fond with that single file approach.

What I think is that it should be consistent, either everything is in mfd
for all PMICs or everything is split.

The max77686 for example has a somehow arbitrary split since the clocks
are in another file but the regulators are in the same mfd binding doc.

> Best regards,
> Krzysztof
>

Best regards,
-- 
Javier Martinez Canillas
Open Source Group
Samsung Research America