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

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.

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