Documentation: sysfs-class-power: Update Long_Life description
Subsystems (2)
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
@@ -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
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_typesorcharge_control_end_thresholdwas the appropriate attribute to expose a battery charge limiting toggle that is fixed in the BIOS. The confusion arose because thecharge_control_end_thresholddescription closely matches the functional change the hardware is making, while thecharge_typesfunctionality 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_typeswith an exposedLong_Lifeand 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=9ca8fc065b88b327acbfdc33454efea391639716Suggested-by Hans de Goede <[email protected]>Signed-off-by Derek J. Clark <[email protected]>--- Documentation/ABI/testing/sysfs-class-power | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-)Documentation/ABI/testing/sysfs-class-power +0
-0@@ -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
-3stop. 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
-2Access: 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
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_typesorcharge_control_end_thresholdwas the appropriate attribute to expose a battery charge limiting toggle that is fixed in the BIOS. The confusion arose because thecharge_control_end_thresholddescription closely matches the functional change the hardware is making, while thecharge_typesfunctionality 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_typeswith an exposedLong_Lifeand 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=9ca8fc065b88b327acbfdc33454efea391639716Suggested-by Hans de Goede <[email protected]>Signed-off-by Derek J. Clark <[email protected]>
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@@ -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
Sebastian Reichel
AppliedQuoted 11 lines · Derek J. Clark
While adding charge limiting support to the Lenovo WMI drivers, there was some back and forth about whether
charge_typesorcharge_control_end_thresholdwas the appropriate attribute to expose a battery charge limiting toggle that is fixed in the BIOS. The confusion arose because thecharge_control_end_thresholddescription closely matches the functional change the hardware is making, while thecharge_typesfunctionality 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]>