[1/4] dt-bindings: power: supply: Add pm8916 VM-BMS

  Qualcomm Voltage Mode BMS is a battery monitoring block in PM8916 PMIC.
Document it's DT binding.

Signed-off-by: Nikita Travkin <nikita@trvn.ru>
---
 .../bindings/power/supply/qcom,pm8916-bms-vm.yaml  | 64 ++++++++++++++++++++++
 1 file changed, 64 insertions(+)
  

On Fri, Jul 28, 2023 at 10:19:30PM +0500, Nikita Travkin wrote:
> Qualcomm Voltage Mode BMS is a battery monitoring block in PM8916 PMIC.
> Document it's DT binding.
> 
> Signed-off-by: Nikita Travkin <nikita@trvn.ru>
> ---
>  .../bindings/power/supply/qcom,pm8916-bms-vm.yaml  | 64 ++++++++++++++++++++++
>  1 file changed, 64 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml
> new file mode 100644
> index 000000000000..455973d46862
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml
> @@ -0,0 +1,64 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/power/supply/qcom,pm8916-bms-vm.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Qualcomm Voltage Mode BMS
> +
> +maintainers:
> +  - Nikita Travkin <nikita@trvn.ru>
> +
> +description:
> +  Voltage Mode BMS is a hardware block found in some Qualcomm PMICs
> +  such as pm8916. This block performs battery voltage monitoring.
> +
> +allOf:
> +  - $ref: power-supply.yaml#
> +
> +properties:
> +  compatible:
> +    const: qcom,pm8916-bms-vm
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    items:
> +      - description: FIFO update done

You don't need items: here since you only have one - const: will do.

> +  interrupt-names:
> +    items:
> +      - const: fifo

Same here, but do you really need a name, when you have only one
interrupt?

Thanks,
Conor.

> +
> +  monitored-battery: true
> +
> +  power-supplies: true
> +
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - interrupt-names
> +  - monitored-battery
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    pmic {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      battery@4000 {
> +        compatible = "qcom,pm8916-bms-vm";
> +        reg = <0x4000>;
> +        interrupts = <0x0 0x40 4 IRQ_TYPE_EDGE_RISING>;
> +        interrupt-names = "fifo";
> +
> +        monitored-battery = <&battery>;
> +        power-supplies = <&pm8916_charger>;
> +      };
> +    };
> 
> -- 
> 2.41.0
>
  

Conor Dooley писал(а) 29.07.2023 15:03:
> On Fri, Jul 28, 2023 at 10:19:30PM +0500, Nikita Travkin wrote:
>> Qualcomm Voltage Mode BMS is a battery monitoring block in PM8916 PMIC.
>> Document it's DT binding.
>>
>> Signed-off-by: Nikita Travkin <nikita@trvn.ru>
>> ---
>>  .../bindings/power/supply/qcom,pm8916-bms-vm.yaml  | 64 ++++++++++++++++++++++
>>  1 file changed, 64 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml
>> new file mode 100644
>> index 000000000000..455973d46862
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml
>> @@ -0,0 +1,64 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/power/supply/qcom,pm8916-bms-vm.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Qualcomm Voltage Mode BMS
>> +
>> +maintainers:
>> +  - Nikita Travkin <nikita@trvn.ru>
>> +
>> +description:
>> +  Voltage Mode BMS is a hardware block found in some Qualcomm PMICs
>> +  such as pm8916. This block performs battery voltage monitoring.
>> +
>> +allOf:
>> +  - $ref: power-supply.yaml#
>> +
>> +properties:
>> +  compatible:
>> +    const: qcom,pm8916-bms-vm
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  interrupts:
>> +    items:
>> +      - description: FIFO update done
> 
> You don't need items: here since you only have one - const: will do.
> 

Ack.

>> +  interrupt-names:
>> +    items:
>> +      - const: fifo
> 
> Same here, but do you really need a name, when you have only one
> interrupt?
> 

Hm, thinking of this more, the hardware actually has more than one
interrupt, even though this one seems to be the only really useful
one. Would a better way forward be to list all of them (and fix
the driver to get the value by it's name) or it would be
acceptable to leave the names here and extend the list at a later
date when (if ever) other interrupts are needed?

Thanks for the review!
Nikita

> Thanks,
> Conor.
> 
>> +
>> +  monitored-battery: true
>> +
>> +  power-supplies: true
>> +
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - interrupts
>> +  - interrupt-names
>> +  - monitored-battery
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/interrupt-controller/irq.h>
>> +    pmic {
>> +      #address-cells = <1>;
>> +      #size-cells = <0>;
>> +
>> +      battery@4000 {
>> +        compatible = "qcom,pm8916-bms-vm";
>> +        reg = <0x4000>;
>> +        interrupts = <0x0 0x40 4 IRQ_TYPE_EDGE_RISING>;
>> +        interrupt-names = "fifo";
>> +
>> +        monitored-battery = <&battery>;
>> +        power-supplies = <&pm8916_charger>;
>> +      };
>> +    };
>>
>> --
>> 2.41.0
>>
  

On Sat, Jul 29, 2023 at 05:06:14PM +0500, Nikita Travkin wrote:
> Conor Dooley писал(а) 29.07.2023 15:03:
> > On Fri, Jul 28, 2023 at 10:19:30PM +0500, Nikita Travkin wrote:

> >> +  interrupt-names:
> >> +    items:
> >> +      - const: fifo
> > 
> > Same here, but do you really need a name, when you have only one
> > interrupt?
> > 
> 
> Hm, thinking of this more, the hardware actually has more than one
> interrupt, even though this one seems to be the only really useful
> one. Would a better way forward be to list all of them 

Yes.

> (and fix
> the driver to get the value by it's name)

It's not a fix to do that, the order of the interrupts is not variable,
so there's nothing wrong with using the indices. You can do it if you
like.

> or it would be
> acceptable to leave the names here and extend the list at a later
> date when (if ever) other interrupts are needed?

If you know what they are, please describe them now, even if the driver
does not use them (yet).

Thanks,
Conor.
  

Conor Dooley писал(а) 29.07.2023 17:10:
> On Sat, Jul 29, 2023 at 05:06:14PM +0500, Nikita Travkin wrote:
>> Conor Dooley писал(а) 29.07.2023 15:03:
>> > On Fri, Jul 28, 2023 at 10:19:30PM +0500, Nikita Travkin wrote:
> 
>> >> +  interrupt-names:
>> >> +    items:
>> >> +      - const: fifo
>> >
>> > Same here, but do you really need a name, when you have only one
>> > interrupt?
>> >
>>
>> Hm, thinking of this more, the hardware actually has more than one
>> interrupt, even though this one seems to be the only really useful
>> one. Would a better way forward be to list all of them
> 
> Yes.
> 
>> (and fix
>> the driver to get the value by it's name)
> 
> It's not a fix to do that, the order of the interrupts is not variable,
> so there's nothing wrong with using the indices. You can do it if you
> like.
> 
>> or it would be
>> acceptable to leave the names here and extend the list at a later
>> date when (if ever) other interrupts are needed?
> 
> If you know what they are, please describe them now, even if the driver
> does not use them (yet).
> 

Thanks for the clarification! Will make sure both drivers have all
interrupts described in v2

Nikita

> Thanks,
> Conor.
  

On Sat, Jul 29, 2023 at 05:15:06PM +0500, Nikita Travkin wrote:
> Conor Dooley писал(а) 29.07.2023 17:10:
> > On Sat, Jul 29, 2023 at 05:06:14PM +0500, Nikita Travkin wrote:
> >> Conor Dooley писал(а) 29.07.2023 15:03:
> >> > On Fri, Jul 28, 2023 at 10:19:30PM +0500, Nikita Travkin wrote:
> > 
> >> >> +  interrupt-names:
> >> >> +    items:
> >> >> +      - const: fifo
> >> >
> >> > Same here, but do you really need a name, when you have only one
> >> > interrupt?
> >> >
> >>
> >> Hm, thinking of this more, the hardware actually has more than one
> >> interrupt, even though this one seems to be the only really useful
> >> one. Would a better way forward be to list all of them
> > 
> > Yes.
> > 
> >> (and fix
> >> the driver to get the value by it's name)
> > 
> > It's not a fix to do that, the order of the interrupts is not variable,
> > so there's nothing wrong with using the indices. You can do it if you
> > like.
> > 
> >> or it would be
> >> acceptable to leave the names here and extend the list at a later
> >> date when (if ever) other interrupts are needed?
> > 
> > If you know what they are, please describe them now, even if the driver
> > does not use them (yet).
> > 
> 
> Thanks for the clarification! Will make sure both drivers have all
> interrupts described in v2

Note that bindings describe hardware, not the driver. The driver need
not touch the other interrupts if it does not use them, but make the
hardware description (IOW the dt-binding) accurate & as complete as you
can.

Thanks,
Conor.