diff mbox

[v3,2/4] mfd: pm8xxx-spmi: document DT bindings for Qualcomm SPMI PMICs

Message ID 1406205921-7452-3-git-send-email-svarbanov@mm-sol.com (mailing list archive)
State Superseded, archived
Headers show

Commit Message

Stanimir Varbanov July 24, 2014, 12:45 p.m. UTC
Document DT bindings used to describe the Qualcomm SPMI PMICs.
Currently the SPMI PMICs supported are pm8941, pm8841 and pma8084.

Signed-off-by: Stanimir Varbanov <svarbanov@mm-sol.com>
---
 .../devicetree/bindings/mfd/qcom,pm8xxx-spmi.txt   |   49 ++++++++++++++++++++
 1 files changed, 49 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/mfd/qcom,pm8xxx-spmi.txt

Comments

David Collins July 29, 2014, 10:23 p.m. UTC | #1
On 07/24/2014 05:45 AM, Stanimir Varbanov wrote:
> Document DT bindings used to describe the Qualcomm SPMI PMICs.
> Currently the SPMI PMICs supported are pm8941, pm8841 and pma8084.
> 
> Signed-off-by: Stanimir Varbanov <svarbanov@mm-sol.com>

(...)
> +Required properties for peripheral child nodes:
> +- compatible:      Should contain "qcom,pm8xxx-xxx", where "xxx" is
> +                   peripheral name. The "pm8xxx" can be any of supported PMICs,
> +                   see example below.

I don't think that this binding document should be imposing any formatting
restrictions on the compatible strings for QPNP peripheral drivers.  The
QPNP peripheral drivers in the downstream msm-3.10 tree [1] do not specify
per-PMIC compatible strings.  This is because ideally, a given QPNP
peripheral represents a hardware block that is identical in interface and
operation between PMICs.

These peripheral drivers determine the base address for a given device
instance via device tree reg and reg-names properties.  In order for this
to continue to work with the pm8xxx-spmi driver, some mechanism will need
to be introduced which creates resource structs for the
non-memory-mappable SPMI base addresses.  One possible solution is
currently being discussed in another thread [2].  This document will need
to be updated to show the child node reg property scheme once a solution
is reached.

(...)
> +Example:
> +
> +	pm8941@0 {
> +		compatible = "qcom,pm8941";
> +		reg = <0x0 SPMI_USID>;
> +
> +		rtc {
> +			compatible = "qcom,pm8941-rtc";
> +			interrupts = <0x0 0x61 0x1 IRQ_TYPE_EDGE_RISING>;
> +			interrupt-names = "alarm";
> +		};
> +	};

Can you please expand your example to include the second SID for the
PM8941 chip?  That way, it will be clear that each PMIC needs two DT
nodes; one for each SID.

Thanks,
David Collins

[1]: https://www.codeaurora.org/cgit/quic/la/kernel/msm-3.10/tree/?h=msm-3.10

[2]: https://lkml.org/lkml/2014/7/29/252
Stanimir Varbanov July 31, 2014, 8:58 a.m. UTC | #2
On 07/30/2014 01:23 AM, David Collins wrote:
> On 07/24/2014 05:45 AM, Stanimir Varbanov wrote:
>> Document DT bindings used to describe the Qualcomm SPMI PMICs.
>> Currently the SPMI PMICs supported are pm8941, pm8841 and pma8084.
>>
>> Signed-off-by: Stanimir Varbanov <svarbanov@mm-sol.com>
> 
> (...)
>> +Required properties for peripheral child nodes:
>> +- compatible:      Should contain "qcom,pm8xxx-xxx", where "xxx" is
>> +                   peripheral name. The "pm8xxx" can be any of supported PMICs,
>> +                   see example below.
> 
> I don't think that this binding document should be imposing any formatting
> restrictions on the compatible strings for QPNP peripheral drivers.  The
> QPNP peripheral drivers in the downstream msm-3.10 tree [1] do not specify
> per-PMIC compatible strings.  This is because ideally, a given QPNP
> peripheral represents a hardware block that is identical in interface and
> operation between PMICs.
> 

Isn't "hardware block that is identical in interface and operation
between PMICs" exactly the meaning of *compatible* property?

No *compatible* property, no platform device. We must have this property
for every peripheral driver.

> These peripheral drivers determine the base address for a given device
> instance via device tree reg and reg-names properties.  In order for this
> to continue to work with the pm8xxx-spmi driver, some mechanism will need
> to be introduced which creates resource structs for the
> non-memory-mappable SPMI base addresses.  One possible solution is
> currently being discussed in another thread [2].  This document will need
> to be updated to show the child node reg property scheme once a solution
> is reached.
> 

That's correct. If we reach the "reg" solution this binding document
must be changed.

> (...)
>> +Example:
>> +
>> +	pm8941@0 {
>> +		compatible = "qcom,pm8941";
>> +		reg = <0x0 SPMI_USID>;
>> +
>> +		rtc {
>> +			compatible = "qcom,pm8941-rtc";
>> +			interrupts = <0x0 0x61 0x1 IRQ_TYPE_EDGE_RISING>;
>> +			interrupt-names = "alarm";
>> +		};
>> +	};
> 
> Can you please expand your example to include the second SID for the
> PM8941 chip?  That way, it will be clear that each PMIC needs two DT
> nodes; one for each SID.

Sure, will do.
David Collins July 31, 2014, 8:53 p.m. UTC | #3
On 07/31/2014 01:58 AM, Stanimir Varbanov wrote:
> On 07/30/2014 01:23 AM, David Collins wrote:
>> On 07/24/2014 05:45 AM, Stanimir Varbanov wrote:
>>> Document DT bindings used to describe the Qualcomm SPMI PMICs.
>>> Currently the SPMI PMICs supported are pm8941, pm8841 and pma8084.
>>>
>>> Signed-off-by: Stanimir Varbanov <svarbanov@mm-sol.com>
>>
>> (...)
>>> +Required properties for peripheral child nodes:
>>> +- compatible:      Should contain "qcom,pm8xxx-xxx", where "xxx" is
>>> +                   peripheral name. The "pm8xxx" can be any of supported PMICs,
>>> +                   see example below.
>>
>> I don't think that this binding document should be imposing any formatting
>> restrictions on the compatible strings for QPNP peripheral drivers.  The
>> QPNP peripheral drivers in the downstream msm-3.10 tree [1] do not specify
>> per-PMIC compatible strings.  This is because ideally, a given QPNP
>> peripheral represents a hardware block that is identical in interface and
>> operation between PMICs.
>>
> 
> Isn't "hardware block that is identical in interface and operation
> between PMICs" exactly the meaning of *compatible* property?
> 
> No *compatible* property, no platform device. We must have this property
> for every peripheral driver.

I am not suggesting that we remove the compatible property for peripheral
device nodes.  I agree that these nodes need to have a compatible
property.  My concern is that this binding document should not require the
peripheral nodes to have compatible property values that are PMIC specific.

For example, in the downstream msm-3.10 branch the power-on peripheral
uses the same compatible string regardless of what PMIC the peripheral is
found on: "qcom,qpnp-power-on" [1].  There is no reason for the driver to
care about what PMIC the peripheral is found on.  Therefore, it does not
make sense to force it to support compatible strings like
"qcom,pm8941-power-on", "qcom,pm8841-power-on", "qcom,pma8084-power-on", etc.

Every QPNP PMIC peripheral has its own set of type and version registers
that allow software to auto-detect its capabilities at runtime.

Take care,
David

[1]:
https://www.codeaurora.org/cgit/quic/la/kernel/msm-3.10/tree/Documentation/devicetree/bindings/platform/msm/qpnp-power-on.txt?h=msm-3.10
diff mbox

Patch

diff --git a/Documentation/devicetree/bindings/mfd/qcom,pm8xxx-spmi.txt b/Documentation/devicetree/bindings/mfd/qcom,pm8xxx-spmi.txt
new file mode 100644
index 0000000..2b7f5b6
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/qcom,pm8xxx-spmi.txt
@@ -0,0 +1,49 @@ 
+          Qualcomm PM8XXX SPMI PMICs multi-function device bindings
+
+The Qualcomm PM8XXX series presently includes PM8941, PM8841 and PMA8084
+PMICs.  These PMICs use a QPNP scheme through SPMI interface.
+QPNP is effectively a partitioning scheme for dividing the SPMI extended
+register space up into logical pieces, and set of fixed register
+locations/definitions within these regions, with some of these regions
+specifically used for interrupt handling.
+
+The QPNP PMICs are used with the Qualcomm Snapdragon series SoCs, and are
+interfaced to the chip via the SPMI (System Power Management Interface) bus.
+Support for multiple independent functions are implemented by splitting the
+16-bit SPMI slave address space into 256 smaller fixed-size regions, 256 bytes
+each. A function can consume one or more of these fixed-size register regions.
+
+Required properties:
+- compatible:      Should contain one of:
+                     "qcom,pm8941"
+                     "qcom,pm8841"
+                     "qcom,pma8084"
+- reg:             Specifies the SPMI USID slave address for this device.
+                   For more information see:
+                   Documentation/devicetree/bindings/spmi/spmi.txt
+
+Required properties for peripheral child nodes:
+- compatible:      Should contain "qcom,pm8xxx-xxx", where "xxx" is
+                   peripheral name. The "pm8xxx" can be any of supported PMICs,
+                   see example below.
+
+Optional properties for peripheral child nodes:
+- interrupts:      Interrupts are specified as a 4-tuple. For more information
+                   see:
+                   Documentation/devicetree/bindings/spmi/qcom,spmi-pmic-arb.txt
+- interrupt-names: Corresponding interrupt name to the interrupts property
+
+Each child node represents a function of the PMIC.
+
+Example:
+
+	pm8941@0 {
+		compatible = "qcom,pm8941";
+		reg = <0x0 SPMI_USID>;
+
+		rtc {
+			compatible = "qcom,pm8941-rtc";
+			interrupts = <0x0 0x61 0x1 IRQ_TYPE_EDGE_RISING>;
+			interrupt-names = "alarm";
+		};
+	};