Skip to contentSkip to conversation

docs: backlight: Clarify `actual_brightness`

PATCH In review Mario Limonciello 2 participants 2 messages Apr 15, 2025 – May 5, 2025 Backlight class/subsystem

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 docs: backlight: Clarify `actual_brightness`

From: Mario Limonciello <[email protected]>

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").

---
v2:
* Add more explanation

---
 Documentation/ABI/stable/sysfs-class-backlight | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/ABI/stable/sysfs-class-backlight +6 -1
index 6102d6bebdf9a..40b8c46b95b28 100644
@@ -26,7 +26,12 @@ Date:		March 2006
 KernelVersion:	2.6.17
 Contact:	Richard Purdie <[email protected]>
 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
Signature · 1 line
2.43.0
Reviewed-by on v2 1/1
#1 lore raw
Quoted 13 lines · Mario Limonciello

From: Mario Limonciello <[email protected]>

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").

Quoted 8 lines

---
v2:
* Add more explanation

Harry

Quoted 22 lines
---
 Documentation/ABI/stable/sysfs-class-backlight | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/ABI/stable/sysfs-class-backlight +6 -1
index 6102d6bebdf9a..40b8c46b95b28 100644
@@ -26,7 +26,12 @@ Date:		March 2006
 KernelVersion:	2.6.17
 Contact:	Richard Purdie <[email protected]>
 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