docs: backlight: Clarify `actual_brightness`

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@kernel.org>
Cc: Lennart Poettering <lennart@poettering.net>
Cc: richard.purdie@linuxfoundation.org
Link: https://github.com/systemd/systemd/pull/36881
Reviewed-by: Harry Wentland <harry.wentland@amd.com>
Link: https://lore.kernel.org/r/20250415192101.2033518-1-superm1@kernel.org
Signed-off-by: Mario Limonciello <mario.limonciello@amd.com>

diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
index 6102d6bebdf9ad6ba9672bd62f9ae63954cad6c6..40b8c46b95b284dd8f75e2bdd4d27aae7588226d 100644 (file)
--- 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@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