Skip to contentSkip to conversation

Documentation: sysfs-class-power: Update Long_Life description

PATCH Applied Derek J. Clark 4 participants 4 messages Aug 3 – Sep 9

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: sysfs-class-power: Update Long_Life description

While adding charge limiting support to the Lenovo WMI drivers, there was some back and forth about whether charge_types or charge_control_end_threshold was the appropriate attribute to expose a battery charge limiting toggle that is fixed in the BIOS. The confusion arose because the charge_control_end_threshold description closely matches the functional change the hardware is making, while the charge_types functionality better suits the actual an on/off toggle that occurs in the BIOS. This specific scenario is not explicitly enumerated in the documentation, though it is fairly common.

Given that the original intention was to use it this way[1],[2], and that the samsung-laptop[3], ideapad-laptop[4], and lenovo-wmi-other[5] drivers all use the convention of charge_types with an exposed Long_Life and Standard value for this, codify it in the Documentation to avoid confusion in the future.

[1] https://lore.kernel.org/linux-pm/[email protected]/
[2] https://lore.kernel.org/platform-driver-x86/[email protected]/
[3] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=de2884c6cdd3d133704ce37393590dd1c761500c
[4] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=da8f2708f9b69707f4efeb432a18395e46b4666f
[5] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9ca8fc065b88b327acbfdc33454efea391639716

---
 Documentation/ABI/testing/sysfs-class-power | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
Documentation/ABI/testing/sysfs-class-power +9 -5
index 5641f1fd5fd6..98b389845d1e 100644
@@ -365,9 +365,12 @@ Contact:	[email protected]
 Description:
 		Represents a battery percentage level, above which charging will
 		stop. Not all hardware is capable of setting this to an arbitrary
-		percentage. Drivers will round written values to the nearest
-		supported value. Reading back the value will show the actual
-		threshold set by the driver.
+		value, instead providing different minimum, maximum, or step
+		values. Drivers will round written values to the nearest supported
+		value. Reading back the value will show the actual threshold set
+		by the driver. For hardware that only supports a single fixed
+		value, use charge_types with a value of "Long Life" (vs "Standard")
+		instead'
 
 		Access: Read, Write
 
@@ -398,8 +401,9 @@ Description:
 			when to start and stop charging. Advanced users
 			can use this to drastically extend battery life.
 		Long Life:
-			The charger reduces its charging rate in order to
-			prolong the battery health.
+			The charger firmware reduces its charging rate and/or
+			maximum charging percentage to a hardware specified
+			fixed limit in order to prolong the battery health.
 		Bypass:
 			The charger bypasses the charging path around the
 			integrated converter allowing for a "smart" wall
Signature · 1 line
2.55.0
#1 lore raw
Quoted 35 lines · Derek J. Clark

While adding charge limiting support to the Lenovo WMI drivers, there was some back and forth about whether charge_types or charge_control_end_threshold was the appropriate attribute to expose a battery charge limiting toggle that is fixed in the BIOS. The confusion arose because the charge_control_end_threshold description closely matches the functional change the hardware is making, while the charge_types functionality better suits the actual an on/off toggle that occurs in the BIOS. This specific scenario is not explicitly enumerated in the documentation, though it is fairly common.

Given that the original intention was to use it this way[1],[2], and that the samsung-laptop[3], ideapad-laptop[4], and lenovo-wmi-other[5] drivers all use the convention of charge_types with an exposed Long_Life and Standard value for this, codify it in the Documentation to avoid confusion in the future.

[1] https://lore.kernel.org/linux-pm/[email protected]/
[2] https://lore.kernel.org/platform-driver-x86/[email protected]/
[3] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=de2884c6cdd3d133704ce37393590dd1c761500c
[4] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=da8f2708f9b69707f4efeb432a18395e46b4666f
[5] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9ca8fc065b88b327acbfdc33454efea391639716

---
 Documentation/ABI/testing/sysfs-class-power | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
Documentation/ABI/testing/sysfs-class-power +0 -0
index 5641f1fd5fd6..98b389845d1e 100644
@@ -365,9 +365,12 @@ Contact:	[email protected]
 Description:
 		Represents a battery percentage level, above which charging will

Documentation/ABI/testing/sysfs-class-power Contact: [email protected] · line 373

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-power +6 -3
 		stop. Not all hardware is capable of setting this to an arbitrary
-		percentage. Drivers will round written values to the nearest
-		supported value. Reading back the value will show the actual
-		threshold set by the driver.
+		value, instead providing different minimum, maximum, or step
+		values. Drivers will round written values to the nearest supported
+		value. Reading back the value will show the actual threshold set
+		by the driver. For hardware that only supports a single fixed
+		value, use charge_types with a value of "Long Life" (vs "Standard")
+		instead'

maybe instead.
?

Quoted 15 lines
Documentation/ABI/testing/sysfs-class-power +3 -2
 		Access: Read, Write
 
@@ -398,8 +401,9 @@ Description:
 			when to start and stop charging. Advanced users
 			can use this to drastically extend battery life.
 		Long Life:
-			The charger reduces its charging rate in order to
-			prolong the battery health.
+			The charger firmware reduces its charging rate and/or
+			maximum charging percentage to a hardware specified
+			fixed limit in order to prolong the battery health.
 		Bypass:
 			The charger bypasses the charging path around the
 			integrated converter allowing for a "smart" wall
Signature · 1 line
~Randy
Reviewed-by on v1 1/1
#2 lore raw
In reply to Derek J. Clark

Hi Derek,

Quoted 16 lines · Derek J. Clark

While adding charge limiting support to the Lenovo WMI drivers, there was some back and forth about whether charge_types or charge_control_end_threshold was the appropriate attribute to expose a battery charge limiting toggle that is fixed in the BIOS. The confusion arose because the charge_control_end_threshold description closely matches the functional change the hardware is making, while the charge_types functionality better suits the actual an on/off toggle that occurs in the BIOS. This specific scenario is not explicitly enumerated in the documentation, though it is fairly common.

Given that the original intention was to use it this way[1],[2], and that the samsung-laptop[3], ideapad-laptop[4], and lenovo-wmi-other[5] drivers all use the convention of charge_types with an exposed Long_Life and Standard value for this, codify it in the Documentation to avoid confusion in the future.

Quoted 8 lines

[1] https://lore.kernel.org/linux-pm/[email protected]/
[2] https://lore.kernel.org/platform-driver-x86/[email protected]/
[3] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=de2884c6cdd3d133704ce37393590dd1c761500c
[4] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=da8f2708f9b69707f4efeb432a18395e46b4666f
[5] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9ca8fc065b88b327acbfdc33454efea391639716

Thank you for updating the docs, patch looks good to me:

Regards,

Hans

Quoted 36 lines
---
 Documentation/ABI/testing/sysfs-class-power | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
Documentation/ABI/testing/sysfs-class-power +9 -5
index 5641f1fd5fd6..98b389845d1e 100644
@@ -365,9 +365,12 @@ Contact:	[email protected]
 Description:
 		Represents a battery percentage level, above which charging will
 		stop. Not all hardware is capable of setting this to an arbitrary
-		percentage. Drivers will round written values to the nearest
-		supported value. Reading back the value will show the actual
-		threshold set by the driver.
+		value, instead providing different minimum, maximum, or step
+		values. Drivers will round written values to the nearest supported
+		value. Reading back the value will show the actual threshold set
+		by the driver. For hardware that only supports a single fixed
+		value, use charge_types with a value of "Long Life" (vs "Standard")
+		instead'
 
 		Access: Read, Write
 
@@ -398,8 +401,9 @@ Description:
 			when to start and stop charging. Advanced users
 			can use this to drastically extend battery life.
 		Long Life:
-			The charger reduces its charging rate in order to
-			prolong the battery health.
+			The charger firmware reduces its charging rate and/or
+			maximum charging percentage to a hardware specified
+			fixed limit in order to prolong the battery health.
 		Bypass:
 			The charger bypasses the charging path around the
 			integrated converter allowing for a "smart" wall
#3 lore raw
In reply to Derek J. Clark
Quoted 11 lines · Derek J. Clark

While adding charge limiting support to the Lenovo WMI drivers, there was some back and forth about whether charge_types or charge_control_end_threshold was the appropriate attribute to expose a battery charge limiting toggle that is fixed in the BIOS. The confusion arose because the charge_control_end_threshold description closely matches the functional change the hardware is making, while the charge_types functionality better suits the actual an on/off toggle that occurs in the BIOS. This specific scenario is not explicitly enumerated in the documentation, though it is fairly common.

[...]

Applied, thanks!

[1/1] Documentation: sysfs-class-power: Update Long_Life description

      commit: 801471494b95bb4aa405ec7a6e318a7ca4cbb086

Best regards,

Signature · 1 line
Sebastian Reichel <[email protected]>