[PATCH v2] docs: backlight: Clarify `actual_brightness`

[Harry Wentland]

On 2025-04-15 15:20, Mario Limonciello wrote:
> From: Mario Limonciello <mario.limonciello at amd.com>
> 
> Currently userspace software systemd treats `brightness` and
> `actual_brightness` identically due to a bug found in an out of tree
> driver.
> 
> This however causes problems for in-tree drivers that use brightness
> to report user requested `brightness` and `actual_brightness` to report
> what the hardware actually has programmed.
> 
> Clarify the documentation to match the behavior described in commit
> 6ca017658b1f9 ("[PATCH] backlight: Backlight Class Improvements").
> 
> Cc: Lee Jones <lee at kernel.org>
> Cc: Lennart Poettering <lennart at poettering.net>
> Cc: richard.purdie at linuxfoundation.org
> Link: https://github.com/systemd/systemd/pull/36881
> Signed-off-by: Mario Limonciello <mario.limonciello at amd.com>
> ---
> v2:
>  * Add more explanation

Reviewed-by: Harry Wentland <harry.wentland at amd.com>

Harry

> ---
>  Documentation/ABI/stable/sysfs-class-backlight | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
> index 6102d6bebdf9a..40b8c46b95b28 100644
> --- a/Documentation/ABI/stable/sysfs-class-backlight
> +++ b/Documentation/ABI/stable/sysfs-class-backlight
> @@ -26,7 +26,12 @@ Date:		March 2006
>  KernelVersion:	2.6.17
>  Contact:	Richard Purdie <rpurdie at rpsys.net>
>  Description:
> -		Show the actual brightness by querying the hardware.
> +		Show the actual brightness by querying the hardware. Due
> +		to implementation differences in hardware this may not
> +		match the value in 'brightness'. For example some hardware
> +		may treat blanking differently or have custom power saving
> +		features. Userspace should generally use the values in
> +		'brightness' to make decisions.
>  Users:		HAL
>  
>  What:		/sys/class/backlight/<backlight>/max_brightness