[PATCH] ABI: testing: sysfs-class-power: clarify charge_type documentation

[PATCH] ABI: testing: sysfs-class-power: clarify charge_type documentation

[Andres Salomon]

The existing docs here are a bit vague. This reformats and rewords it,
and is based upon the wording originally used by the dell-laptop driver
battery documentation and also sysfs-class-power-wilco.

The wording for "Long Life" and "Bypass" remain the same, because I'm
unfamiliar with hardware that use them.

Signed-off-by: Andres Salomon <dilinger@queued.net>
---
 Documentation/ABI/testing/sysfs-class-power | 38 +++++++++++++++------
 1 file changed, 27 insertions(+), 11 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index 7c81f0a25a48..84973f66b42c 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -377,17 +377,33 @@ What:		/sys/class/power_supply/<supply_name>/charge_type
 Date:		July 2009
 Contact:	linux-pm@vger.kernel.org
 Description:
-		Represents the type of charging currently being applied to the
-		battery. "Trickle", "Fast", and "Standard" all mean different
-		charging speeds. "Adaptive" means that the charger uses some
-		algorithm to adjust the charge rate dynamically, without
-		any user configuration required. "Custom" means that the charger
-		uses the charge_control_* properties as configuration for some
-		different algorithm. "Long Life" means the charger reduces its
-		charging rate in order to prolong the battery health. "Bypass"
-		means the charger bypasses the charging path around the
-		integrated converter allowing for a "smart" wall adaptor to
-		perform the power conversion externally.
+		Select the charging algorithm to use for a battery.
+
+		Standard:
+			Fully charge the battery at a moderate rate.
+		Fast:
+			Quickly charge the battery using fast-charge
+			technology. This is typically harder on the battery
+			than standard charging and may lower its lifespan.
+		Trickle:
+			Users who primarily operate the system while
+			plugged into an external power source can extend
+			battery life with this mode. Vendor tooling may
+			call this "Primarily AC Use".
+		Adaptive:
+			Automatically optimize battery charge rate based
+			on typical usage pattern.
+		Custom:
+			Use the charge_control_* properties to determine
+			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.
+		Bypass:
+			The charger bypasses the charging path around the
+			integrated converter allowing for a "smart" wall
+			adaptor to perform the power conversion externally.
 
 		Access: Read, Write
 
-- 
2.39.2



-- 
I'm available for contract & employment work, please contact me if
interested.

Re: [PATCH] ABI: testing: sysfs-class-power: clarify charge_type documentation

[Hans de Goede]

Hi,

On 8/20/24 10:19 AM, Andres Salomon wrote:
> The existing docs here are a bit vague. This reformats and rewords it,
> and is based upon the wording originally used by the dell-laptop driver
> battery documentation and also sysfs-class-power-wilco.
> 
> The wording for "Long Life" and "Bypass" remain the same, because I'm
> unfamiliar with hardware that use them.
> 
> Signed-off-by: Andres Salomon <dilinger@queued.net>

Thanks, patch looks good to me:

Reviewed-by: Hans de Goede <hdegoede@redhat.com>

Regards,

Hans




> ---
>  Documentation/ABI/testing/sysfs-class-power | 38 +++++++++++++++------
>  1 file changed, 27 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> index 7c81f0a25a48..84973f66b42c 100644
> --- a/Documentation/ABI/testing/sysfs-class-power
> +++ b/Documentation/ABI/testing/sysfs-class-power
> @@ -377,17 +377,33 @@ What:		/sys/class/power_supply/<supply_name>/charge_type
>  Date:		July 2009
>  Contact:	linux-pm@vger.kernel.org
>  Description:
> -		Represents the type of charging currently being applied to the
> -		battery. "Trickle", "Fast", and "Standard" all mean different
> -		charging speeds. "Adaptive" means that the charger uses some
> -		algorithm to adjust the charge rate dynamically, without
> -		any user configuration required. "Custom" means that the charger
> -		uses the charge_control_* properties as configuration for some
> -		different algorithm. "Long Life" means the charger reduces its
> -		charging rate in order to prolong the battery health. "Bypass"
> -		means the charger bypasses the charging path around the
> -		integrated converter allowing for a "smart" wall adaptor to
> -		perform the power conversion externally.
> +		Select the charging algorithm to use for a battery.
> +
> +		Standard:
> +			Fully charge the battery at a moderate rate.
> +		Fast:
> +			Quickly charge the battery using fast-charge
> +			technology. This is typically harder on the battery
> +			than standard charging and may lower its lifespan.
> +		Trickle:
> +			Users who primarily operate the system while
> +			plugged into an external power source can extend
> +			battery life with this mode. Vendor tooling may
> +			call this "Primarily AC Use".
> +		Adaptive:
> +			Automatically optimize battery charge rate based
> +			on typical usage pattern.
> +		Custom:
> +			Use the charge_control_* properties to determine
> +			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.
> +		Bypass:
> +			The charger bypasses the charging path around the
> +			integrated converter allowing for a "smart" wall
> +			adaptor to perform the power conversion externally.
>  
>  		Access: Read, Write
>  

Re: [PATCH] ABI: testing: sysfs-class-power: clarify charge_type documentation

[Sebastian Reichel]

On Tue, 20 Aug 2024 04:19:42 -0400, Andres Salomon wrote:
> The existing docs here are a bit vague. This reformats and rewords it,
> and is based upon the wording originally used by the dell-laptop driver
> battery documentation and also sysfs-class-power-wilco.
> 
> The wording for "Long Life" and "Bypass" remain the same, because I'm
> unfamiliar with hardware that use them.
> 
> [...]

Applied, thanks!

[1/1] ABI: testing: sysfs-class-power: clarify charge_type documentation
      commit: 919a4719026f68a9d6b5b87db2e935564cdf42a5

Best regards,
-- 
Sebastian Reichel <sebastian.reichel@collabora.com>