[PATCH] Documentation: sysfs-class-power: Update Long_Life description

[PATCH] Documentation: sysfs-class-power: Update Long_Life description

[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/49993a42-aa91-46bf-acef-4a089db4c2db@redhat.com/
[2] https://lore.kernel.org/platform-driver-x86/20241209204051.8786-1-hdegoede@redhat.com/
[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

Suggested-by: Hans de Goede <hansg@kernel.org>
Signed-off-by: Derek J. Clark  <derekjohn.clark@gmail.com>
---
 Documentation/ABI/testing/sysfs-class-power | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index 5641f1fd5fd6..98b389845d1e 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -365,9 +365,12 @@ Contact:	linux-pm@vger.kernel.org
 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
-- 
2.55.0

Re: [PATCH] Documentation: sysfs-class-power: Update Long_Life description

[Randy Dunlap]

On 8/3/26 2:07 PM, Derek J. Clark wrote:
> 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/49993a42-aa91-46bf-acef-4a089db4c2db@redhat.com/
> [2] https://lore.kernel.org/platform-driver-x86/20241209204051.8786-1-hdegoede@redhat.com/
> [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
> 
> Suggested-by: Hans de Goede <hansg@kernel.org>
> Signed-off-by: Derek J. Clark  <derekjohn.clark@gmail.com>
> ---
>  Documentation/ABI/testing/sysfs-class-power | 14 +++++++++-----
>  1 file changed, 9 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> index 5641f1fd5fd6..98b389845d1e 100644
> --- a/Documentation/ABI/testing/sysfs-class-power
> +++ b/Documentation/ABI/testing/sysfs-class-power
> @@ -365,9 +365,12 @@ Contact:	linux-pm@vger.kernel.org
>  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'

maybe		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

-- 
~Randy

Re: [PATCH] Documentation: sysfs-class-power: Update Long_Life description

[Hans de Goede]

Hi Derek,

On 3-Aug-26 23:07, Derek J. Clark wrote:
> 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/49993a42-aa91-46bf-acef-4a089db4c2db@redhat.com/
> [2] https://lore.kernel.org/platform-driver-x86/20241209204051.8786-1-hdegoede@redhat.com/
> [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
> 
> Suggested-by: Hans de Goede <hansg@kernel.org>
> Signed-off-by: Derek J. Clark  <derekjohn.clark@gmail.com>

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

Reviewed-by: Hans de Goede <johannes.goede@oss.qualcomm.com>

Regards,

Hans


> ---
>  Documentation/ABI/testing/sysfs-class-power | 14 +++++++++-----
>  1 file changed, 9 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> index 5641f1fd5fd6..98b389845d1e 100644
> --- a/Documentation/ABI/testing/sysfs-class-power
> +++ b/Documentation/ABI/testing/sysfs-class-power
> @@ -365,9 +365,12 @@ Contact:	linux-pm@vger.kernel.org
>  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