[3/3] thinkpad_acpi: document the battery controls

Commit Message

Ognjen Galic May 13, 2018, 3:30 p.m. UTC

This documents the new battery controls and wear leveling support
for Lenovo ThinkPad laptops.

Signed-off-by: Ognjen Galic <[e-mail]>
---
 Documentation/laptops/thinkpad-acpi.txt | 70 ++++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

Comments

Henrique de Moraes Holschuh May 14, 2018, 12:03 p.m. UTC | #1

On Sun, 13 May 2018, Ognjen Galic wrote:
> +Battery force discharging
> +--------------------------
> +
> +There is also support for AC overriding. This means that you can force the battery to discharge
> +even when AC is attached. This is also exposed via the generic ACPI driver:
> +
> +/sys/class/power_supply/BATx/force_discharge [int, 1, 0]
> +
> +Setting it to 1 forces the battery to discharge on AC.

This is used to run a battery "fuel gauge" callibration cycle.

One has to set the limits to 0,100 (i.e. disable the anti-wear
limiters), trigger a force_discharge, and wait until it discharges to
zero.  At that point, the EC is supposed to reset the force_discharge
bit by itself, and then you have to wait the battery to charge back to
full.

(and at least on older thinkpads, where you had to use SMAPI to do the
above, it didn't need much help from the operating system.  Once a
couple years you could just set force_discharge on both batteries (with
the thing connected to AC), shutdown the operating system, and go to
sleep.  By morning, it would be fully charged and both gauges
calibrated, still powered off, ready to go :P ).

Ognjen Galic May 14, 2018, 1:41 p.m. UTC | #2

On Mon, May 14, 2018 at 09:03:02AM -0300, Henrique de Moraes Holschuh wrote:
> On Sun, 13 May 2018, Ognjen Galic wrote:
> > +Battery force discharging
> > +--------------------------
> > +
> > +There is also support for AC overriding. This means that you can force the battery to discharge
> > +even when AC is attached. This is also exposed via the generic ACPI driver:
> > +
> > +/sys/class/power_supply/BATx/force_discharge [int, 1, 0]
> > +
> > +Setting it to 1 forces the battery to discharge on AC.
> 
> This is used to run a battery "fuel gauge" callibration cycle.
> 
> One has to set the limits to 0,100 (i.e. disable the anti-wear
> limiters), trigger a force_discharge, and wait until it discharges to
> zero.  At that point, the EC is supposed to reset the force_discharge
> bit by itself, and then you have to wait the battery to charge back to
> full.

That's the intended use case for this patches via an upcoming program I
am writing for userspace.

> 
> (and at least on older thinkpads, where you had to use SMAPI to do the
> above, it didn't need much help from the operating system.  Once a
> couple years you could just set force_discharge on both batteries (with
> the thing connected to AC), shutdown the operating system, and go to
> sleep.  By morning, it would be fully charged and both gauges
> calibrated, still powered off, ready to go :P ).
> 
> -- 
>   Henrique Holschuh

Patch

diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index 00b6dfed..3491d46f 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -1,6 +1,6 @@ 
 		     ThinkPad ACPI Extras Driver
 
-                            Version 0.25
+                            Version 0.27
                         October 16th,  2013
 
                Borislav Deianov <[e-mail]>
@@ -46,6 +46,9 @@  detailed description):
 	- Fan control and monitoring: fan speed, fan enable/disable
 	- WAN enable and disable
 	- UWB enable and disable
+	- Battery wear control (battery start and stop threshold)
+	- Battery inhibit charge
+	- Battery force discharge
 
 A compatibility table by model and feature is maintained on the web
 site, http://ibm-acpi.sf.net/. I appreciate any success or failure
@@ -1483,3 +1486,68 @@  Sysfs interface changelog:
 0x030000:	Thermal and fan sysfs attributes were moved to the hwmon
 		device instead of being attached to the backing platform
 		device.
+
+
+Battery wear control (charge and stop thresholds)
+--------------------------------------------------
+
+Since Linux 4.17 tpacpi supports setting of charge start and stop thresholds on certain
+Lenovo ThinkPad laptops. This feature is exposed via a new API from the ACPI battery driver
+also new in Linux 4.17.
+
+The new battery API allows developers to extended the standard attributes offered by the
+generic ACPI battery driver and add custom attributes from other drivers. thinkpad_acpi
+leverages this API and exposes a few custom attributes for wear control of the battery.
+
+Wear control is designed to stop the charging of the battery at a certain threshold and thus
+stop the cell from wearing out from constant charge cycles. So if you put the threshold at
+50%, the charge will only charge the battery when it is below 50% and it will stop at 50%.
+
+A lower level is also exposed, thus creating a charger "dead zone", a zone where the charger does
+nothing and the battery is in idle as if it was removed from the Thinkpad.
+
+For example, this is what happens when you set the values to 40% and 65%:
+
+            ┌      Discharging      ┐
+	    │                       │
+[0%--------40%       65%-----------100%] Battery 1
+ │                    │
+ └      Charging      ┘
+
+When plugged into AC and if the percentage is between 40% and 100% the battery is in idle.
+
+The attributes:
+---------------
+
+/sys/class/power_supply/BATx/charge_start_threshold [int, <0, >99]
+
+This sets the lower charge stop threshold for the battery. Its a integer and valid values are from
+0% to 99%.
+
+/sys/class/power_supply/BATx/charge_stop_threshold [int, <1, >100]
+
+This sets the upper charge threshold for the battery. Its a integer and the value values are from
+1% to 100%.
+
+Setting the lower limit to 0% and the upper limit to 100% disables the wear leveling control feature.
+
+
+Battery charge inhibiting
+--------------------------
+
+Preventing the battery from charging is also available as a manual override over the settings. Its exposed via
+the generic ACPI driver:
+
+/sys/class/power_supply/BATx/inhibit_charge [int, 1, 0]
+
+Setting it to 1 prevents the battery from charging.
+
+Battery force discharging
+--------------------------
+
+There is also support for AC overriding. This means that you can force the battery to discharge
+even when AC is attached. This is also exposed via the generic ACPI driver:
+
+/sys/class/power_supply/BATx/force_discharge [int, 1, 0]
+
+Setting it to 1 forces the battery to discharge on AC.