[PATCH] docs: backlight: Clarify `actual_brightness`

[Jani Nikula]

On Tue, 15 Apr 2025, Lee Jones <lee at kernel.org> wrote:
> On Tue, 08 Apr 2025, 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: 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>
>> ---
>>  Documentation/ABI/stable/sysfs-class-backlight | 4 +++-
>>  1 file changed, 3 insertions(+), 1 deletion(-)
>> 
>> diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
>> index 6102d6bebdf9a..909cacde85041 100644
>> --- a/Documentation/ABI/stable/sysfs-class-backlight
>> +++ b/Documentation/ABI/stable/sysfs-class-backlight
>> @@ -26,7 +26,9 @@ 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. This
>> +		takes into account other factors besides the value programmed
>> +		for 'brightness' and may not match the value in 'brightness'.
>
> Which factors?  Under what circumstances may the values not match?

At least for i915, the brightness range in sysfs isn't guaranteed to be
the range in hardware. For example, you might want sysfs to start from
0, but the hardware has a minimum that is non-zero. Or you might just
want to have a fixed range, say, 0-100 in sysfs. Any scaling may
introduce rounding errors in the round-trip.

BR,
Jani.


-- 
Jani Nikula, Intel