Re: [PATCH v3 1/7] devicetree: power: add battery state machine documentation

[Sebastian Reichel <sre@kernel.org>]

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

Hi,

On Tue, Jan 10, 2017 at 10:19:57PM -0800, Matt Ranostay wrote:
> Documentation on battery properties that can be defined for
> fine tuning fuel gauge state machines.
> 
> Cc: Rob Herring <robh@kernel.org>
> Signed-off-by: Matt Ranostay <matt@ranostay.consulting>
> ---
>  .../devicetree/bindings/power/supply/battery.txt     | 20 ++++++++++++++++++++
>  1 file changed, 20 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..a6ca761e0a29
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/power/supply/battery.txt
> @@ -0,0 +1,20 @@
> +Battery State Machine Support

Let's also add a mandatory compatible string. This binding
is only relevant for dumb batteries, since other ones can
self-identify. I suggest

compatible = "fixed-battery"

> +Optional Properties
> + - nominal-microvolt: dead battery voltage in microvolts
> + - design-microwatt-hours: battery design mWh in microwatts
> + - design-microamp-hours: battery design mAh in microamps

I think we should mandate the property name of the phandle in the
generic binding instead of each potential fuel-gauge/charger.
Maybe something like the following paragraph:

Batteries are supposed to be referenced by chargers and/or
fuel-gauges using a phandle. The phandle's property should
be named "monitored-battery".

> +Example:
> +
> +	bat: battery@0 {
> +		nominal-microvolt = <3700000>;
> +		design-microwatt-hours = <5290000>;
> +		design-microamp-hours = <1430000>;
> +	};
> +
> +	charger: charger@0 {
> +		...
> +		monitored-battery = <&bat>;
> +		...
> +	};

Let's also add a fuel-gauge to the example to avoid any confusion
between fuel-gauge and battery.

fuel_gauge: fuel-gauge {
    ...
    monitored-battery = <&bat>;
    ...
};

-- Sebastian

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