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

[Mario Limonciello]

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
---
 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
-- 
2.43.0