Re: [PATCH 2/3] dt-bindings: mfd: Convert pm8xxx bindings to yaml

[skakit@codeaurora.org]

Hi Bjorn,

On 2021-03-11 22:33, Bjorn Andersson wrote:
> On Thu 11 Mar 01:29 CST 2021, satya priya wrote:
> 
>> Convert pm8xxx rtc bindings from .txt to .yaml format.
>> 
> 
> Wonderful initiative, thank you!
> 
>> Signed-off-by: satya priya <skakit@codeaurora.org>
>> ---
>>  .../devicetree/bindings/mfd/qcom-pm8xxx.txt        |  99 
>> -------------------
>>  .../devicetree/bindings/mfd/qcom-pm8xxx.yaml       | 108 
>> +++++++++++++++++++++
>>  2 files changed, 108 insertions(+), 99 deletions(-)
>>  delete mode 100644 
>> Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt
>>  create mode 100644 
>> Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml
>> 
>> diff --git a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt 
>> b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt
>> deleted file mode 100644
>> index 9e5eba4..0000000
>> --- a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt
>> +++ /dev/null
>> @@ -1,99 +0,0 @@
>> -Qualcomm PM8xxx PMIC multi-function devices
>> -
>> -The PM8xxx family of Power Management ICs are used to provide 
>> regulated
>> -voltages and other various functionality to Qualcomm SoCs.
>> -
>> -= PROPERTIES
>> -
>> -- compatible:
>> -	Usage: required
>> -	Value type: <string>
>> -	Definition: must be one of:
>> -		    "qcom,pm8058"
>> -		    "qcom,pm8821"
>> -		    "qcom,pm8921"
>> -
>> -- #address-cells:
>> -	Usage: required
>> -	Value type: <u32>
>> -	Definition: must be 1
>> -
>> -- #size-cells:
>> -	Usage: required
>> -	Value type: <u32>
>> -	Definition: must be 0
>> -
>> -- interrupts:
>> -	Usage: required
>> -	Value type: <prop-encoded-array>
>> -	Definition: specifies the interrupt that indicates a subdevice
>> -		    has generated an interrupt (summary interrupt). The
>> -		    format of the specifier is defined by the binding document
>> -		    describing the node's interrupt parent.
>> -
>> -- #interrupt-cells:
>> -	Usage: required
>> -	Value type : <u32>
>> -	Definition: must be 2. Specifies the number of cells needed to 
>> encode
>> -		    an interrupt source. The 1st cell contains the interrupt
>> -		    number. The 2nd cell is the trigger type and level flags
>> -		    encoded as follows:
>> -
>> -			1 = low-to-high edge triggered
>> -			2 = high-to-low edge triggered
>> -			4 = active high level-sensitive
>> -			8 = active low level-sensitive
>> -
>> -- interrupt-controller:
>> -	Usage: required
>> -	Value type: <empty>
>> -	Definition: identifies this node as an interrupt controller
>> -
>> -= SUBCOMPONENTS
>> -
>> -The PMIC contains multiple independent functions, each described in a 
>> subnode.
>> -The below bindings specify the set of valid subnodes.
>> -
>> -== Real-Time Clock
>> -
>> -- compatible:
>> -	Usage: required
>> -	Value type: <string>
>> -	Definition: must be one of:
>> -		    "qcom,pm8058-rtc"
>> -		    "qcom,pm8921-rtc"
>> -		    "qcom,pm8941-rtc"
>> -		    "qcom,pm8018-rtc"
>> -
>> -- reg:
>> -	Usage: required
>> -	Value type: <prop-encoded-array>
>> -	Definition: single entry specifying the base address of the RTC 
>> registers
>> -
>> -- interrupts:
>> -	Usage: required
>> -	Value type: <prop-encoded-array>
>> -	Definition: single entry specifying the RTC's alarm interrupt
>> -
>> -- allow-set-time:
>> -	Usage: optional
>> -	Value type: <empty>
>> -	Definition: indicates that the setting of RTC time is allowed by
>> -		    the host CPU
>> -
>> -= EXAMPLE
>> -
>> -	pmicintc: pmic@0 {
>> -		compatible = "qcom,pm8921";
>> -		interrupts = <104 8>;
>> -		#interrupt-cells = <2>;
>> -		interrupt-controller;
>> -		#address-cells = <1>;
>> -		#size-cells = <0>;
>> -
>> -		rtc@11d {
>> -			compatible = "qcom,pm8921-rtc";
>> -			reg = <0x11d>;
>> -			interrupts = <0x27 0>;
>> -		};
>> -	};
>> diff --git a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml 
>> b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml
>> new file mode 100644
>> index 0000000..b4892f1
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml
>> @@ -0,0 +1,108 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/mfd/qcom-pm8xxx.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Qualcomm PM8xxx PMIC multi-function devices
>> +
>> +maintainers:
>> +  - Lee Jones <lee.jones@linaro.org>
> 
> While Lee is maintainer of the mfd core, it would be better if this was
> someone looking out for the Qualcomm PMIC binding specifically.
> 
>> +
>> +description: |
>> +  The PM8xxx family of Power Management ICs are used to provide 
>> regulated
>> +  voltages and other various functionality to Qualcomm SoCs.
>> +
>> +properties:
>> +  compatible:
>> +    enum:
>> +      - qcom,pm8058
>> +      - qcom,pm8821
>> +      - qcom,pm8921
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  '#address-cells':
>> +     const: 1
>> +
>> +  '#size-cells':
>> +     const: 0
>> +
>> +  interrupts:
>> +    description: |
>> +      Specifies the interrupt that indicates a subdevice has 
>> generated an
>> +      interrupt (summary interrupt).
>> +
>> +  '#interrupt-cells':
>> +    description: |
>> +      Specifies the number of cells needed to encode an interrupt 
>> source.
>> +      The 1st cell contains the interrupt number. The 2nd cell is the
>> +      trigger type.
>> +    const: 2
>> +
>> +  interrupt-controller: true
>> +
>> +patternProperties:
>> +  "rtc@[0-9a-f]+$":
> 
> Can we somehow link this to individual binding docs instead of listing
> all the possible functions here?
> 

you mean we should split this into two:
qcom-pm8xxx.yaml and qcom-pm8xxx-rtc.yaml
Please correct me if wrong.

> Regards,
> Bjorn
> 
>> +    type: object
>> +    properties:
>> +      compatible:
>> +        enum:
>> +          - qcom,pm8058-rtc
>> +          - qcom,pm8921-rtc
>> +          - qcom,pm8941-rtc
>> +          - qcom,pm8018-rtc
>> +
>> +      reg:
>> +        description: Specifies the base address of the RTC registers
>> +
>> +      interrupts:
>> +        description: Specifies the RTC's alarm interrupts
>> +
>> +      allow-set-time:
>> +        $ref: /schemas/types.yaml#/definitions/flag
>> +        description:
>> +          Indicates that the setting of RTC time is allowed by the 
>> host CPU.
>> +
>> +    required:
>> +      - compatible
>> +      - reg
>> +      - interrupts
>> +
>> +    additionalProperties: false
>> +
>> +required:
>> +  - compatible
>> +  - '#address-cells'
>> +  - '#size-cells'
>> +  - interrupts
>> +  - '#interrupt-cells'
>> +  - interrupt-controller
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/spmi/spmi.h>
>> +    spmi_bus: spmi@c440000 {
>> +      reg = <0x0c440000 0x1100>;
>> +      #address-cells = <2>;
>> +      #size-cells = <0>;
>> +      pmicintc: pmic@0 {
>> +        reg = <0x0 SPMI_USID>;
>> +        compatible = "qcom,pm8921";
>> +        interrupts = <104 8>;
>> +        #interrupt-cells = <2>;
>> +        interrupt-controller;
>> +        #address-cells = <1>;
>> +        #size-cells = <0>;
>> +
>> +        pm8921_rtc: rtc@11d {
>> +          compatible = "qcom,pm8921-rtc";
>> +          reg = <0x11d>;
>> +          interrupts = <0x27 0>;
>> +        };
>> +      };
>> +    };
>> +...
>> --
>> QUALCOMM INDIA, on behalf of Qualcomm Innovation Center, Inc. is a 
>> member
>> of Code Aurora Forum, hosted by The Linux Foundation
>>