[PATCH RESEND v6 04/17] dt-bindings: battery: Voltage drop properties

[Matti Vaittinen <matti.vaittinen@linux.dev>]

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

From: Matti Vaittinen <mazziesaccount@gmail.com>

ROHM has developed a so called "zero-correction" -algorithm to improve
the fuel-gauging accuracy close to the point where battery is depleted.
This relies on battery specific "VDR" (voltage drop rate) tables, which
are measured from the battery, and which describe the voltage drop rate.
More thorough explanation about the "zero correction" and "VDR"
parameters is here:
https://lore.kernel.org/all/676253b9-ff69-7891-1f26-a8b5bb5a421b@fi.rohmeurope.com/

Document the VDR zero-correction specific battery properties used by the
BD71815, BD71828, BD72720 and some other ROHM chargers. (Note, charger
drivers aren't upstream yet).

Signed-off-by: Matti Vaittinen <mazziesaccount@gmail.com>
Reviewed-by: Rob Herring (Arm) <robh@kernel.org>
Reviewed-by: Linus Walleij <linusw@kernel.org>

---

Revision history:
 v5 =>:
 - No changes

 v4 => v5:
 - Move volt-drop parameters from rohm,vdr-battry,yaml to the
   battery.yaml
 - drop rohm, -prefix from volt-drop-* properties
 - Drop the rohm,vdr-battry,yaml
 - Add comment clarifying what the rohm,volt-drop-* properties are for
   because this may no longer be obvious as they were moved to common
   battery.yaml
 - Drop Linus Walleij's rb-tag because the concept was changed

 v3 => v4:
 - No changes

 v2 => v3:
 - Constrain VDR threshold voltage to 48V
 - Use standard '-bp' -suffix for the rohm,volt-drop-soc

 RFCv1 => v2:
 - Add units to rohm,volt-drop-soc (tenths of %)
 - Give real temperatures matching the VDR tables, instead of vague
   'high', 'normal', 'low', 'very low'. (Add table of temperatures and
   use number matching the right temperature index in the VDR table name).
 - Fix typoed 'algorithm' in commit message.

The parameters are describing the battery voltage drop rates - so they
are properties of the battery, not the charger. Thus they do not belong
in the charger node.

The right place for them is the battery node, which is described by the
generic "battery.yaml". There were some discussion whether these
properties should be in their own file, or if they should be added to
battery.yaml. Discussion can be found from:
https://lore.kernel.org/all/52b99bf7-bfea-4cee-aa57-4c13e87eaa0d@gmail.com/
This patch implements the volt-drop properties as generic (not vemdor
specific) properties in the battery.yaml. It's worth noting that these
properties are:

  - Meaningful only for those charger drivers which have the VDR
    algorithm implemented. (And even though the algorithm is not charger
    specific, AFAICS, it is currently only used by some ROHM PMIC
    drivers).
  - Technique of measuring the VDR tables for a battery is not widely
    known. AFAICS, only folks at ROHM are measuring those for some
    customer products. We do have those tables available for some of the
    products, like Kobo e-readers though.
---
 .../bindings/power/supply/battery.yaml        | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/devicetree/bindings/power/supply/battery.yaml b/Documentation/devicetree/bindings/power/supply/battery.yaml
index d1a2080557a0..8ebf05d9497c 100644
--- a/Documentation/devicetree/bindings/power/supply/battery.yaml
+++ b/Documentation/devicetree/bindings/power/supply/battery.yaml
@@ -128,6 +128,21 @@ properties:
       - description: alert when battery temperature is lower than this value
       - description: alert when battery temperature is higher than this value
 
+  # The volt-drop* -properties describe voltage-drop for a battery, described
+  # as VDROP in:
+  # https://patentimages.storage.googleapis.com/6c/f5/17/c1d901c220f6a9/US20150032394A1.pdf
+  volt-drop-thresh-microvolt:
+    description: Threshold for starting the VDR correction
+    maximum: 48000000
+
+  volt-drop-soc-bp:
+    description: Table of capacity values matching the values in VDR tables.
+      The value should be given as basis points, 1/100 of a percent.
+
+  volt-drop-temperatures-millicelsius:
+    description: An array containing the temperature in milli celsius, for each
+      of the VDR lookup table.
+
 required:
   - compatible
 
@@ -146,6 +161,13 @@ patternProperties:
         - description: battery capacity percent
           maximum: 100
 
+  '^volt-drop-[0-9]-microvolt':
+    description: Table of the voltage drop rate (VDR) values. Each entry in the
+      table should match a capacity value in the volt-drop-soc table.
+      Furthermore, the values should be obtained for the temperature given in
+      volt-drop-temperatures-millicelsius table at index matching the
+      number in this table's name.
+
 additionalProperties: false
 
 examples:
-- 
2.52.0


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