Re: [PATCH v4 2/8] devicetree: power: add battery state machine documentation

[Sebastian Reichel <sre-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 2946 bytes --]

On Sun, Jan 22, 2017 at 02:22:12PM -0800, Liam Breck wrote:
> I think Matt meant the following :-)
> 
> Note: nominal-microvolt is not the correct term for termination voltage.
> Changed to termination-microvolt

That's right.

> Documentation on battery properties that can be defined for
> fine tuning fuel gauge state machines.

Maybe:

Documentation for batteries, that cannot identify themself. The
information is required by fuel-gauge and charger chips for
proper handling of the battery.

> From: Matt Ranostay <matt-sk+viVC6FLCDq+mSdOJa79kegs52MxvZ@public.gmane.org>
> Cc: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Cc: devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Signed-off-by: Matt Ranostay <matt-sk+viVC6FLCDq+mSdOJa79kegs52MxvZ@public.gmane.org>
> ---
>  .../devicetree/bindings/power/supply/battery.txt   | 34 ++++++++++++++++++++++
>  1 file changed, 34 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/power/supply/battery.txt
> 
> diff --git a/Documentation/devicetree/bindings/power/supply/battery.txt b/Documentation/devicetree/bindings/power/supply/battery.txt
> new file mode 100644
> index 000000000000..398b4d622883
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/power/supply/battery.txt
> @@ -0,0 +1,34 @@
> +Battery Characteristics
> +
> +Required Properties:
> + - compatible: Must be "fixed-battery"
> +
> +Optional Properties:
> + - termination-microvolt: dead battery voltage

I think this is not named optimally, since it's not
clear if its related to charging.

> + - design-microwatt-hours: battery design energy
> + - design-microamp-hours: battery design capacity
> +
> +Batteries must be referenced by chargers and/or fuel-gauges
> +using a phandle. The phandle's property should be named
> +"monitored-battery".
> +
> +Example:
> +
> +	bat: battery {
> +		compatible = "fixed-battery";
> +		terminate-microvolt = <3700000>;
> +		design-microwatt-hours = <5290000>;
> +		design-microamp-hours = <1430000>;
> +	};
> +
> +	charger: charger@0 {
> +		....
> +		monitored-battery = <&bat>;
> +		...
> +	};
> +
> +	fuel_gauge: fuel_gauge@0 {
> +		....
> +		monitored-battery = <&bat>;
> +		...
> +	};

The charger stuff does does not integrate well with
pre-existing support for power-supplies property
described in
Documentation/devicetree/bindings/power/supply/power_supply.txt

I think the proper chain would be:

bat: battery {
	compatible = "fixed-battery";
	terminate-microvolt = <3700000>;
	design-microwatt-hours = <5290000>;
	design-microamp-hours = <1430000>;
};

fuel_gauge: fuel_gauge@0 {
	...
	monitored-battery = <&bat>;
    power-supplies = <&charger>;
	...
};

charger: charger@0 {
	...
};

I added the power-supplies node to the fuel-gauge instead of the battery,
since fuel-gauge + fixed-battery is basically a smart battery.

-- Sebastian

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]