[PATCH 3/3] thinkpad_acpi: document the battery controls

[Ognjen Galic <smclt30p-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

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

Signed-off-by: Ognjen Galic <smclt30p@gmail.com>
---
 Documentation/laptops/thinkpad-acpi.txt | 70 ++++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

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 <borislav@users.sf.net>
@@ -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.
-- 
2.17.0


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
ibm-acpi-devel mailing list
ibm-acpi-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/ibm-acpi-devel