[PATCH] docs: backlight: Clarify `actual_brightness`

[Lee Jones]

On Tue, 15 Apr 2025, Mario Limonciello wrote:

> On 4/15/2025 10:53 AM, Lee Jones 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?
> 
> Is this question for your background or are you saying these should be
> enumerated here in the documentation?

Both.

> Richard Purdie mentioned:
> 
> "The challenge back then was that things like framebuffer blanking would
> turn off the backlight but the single brightness attribute was implemented
> inconsistently. Some drivers would report no backlight when blanking was
> active, some would report the value stored in brightness. This had multiple
> issues"
> 
> For AMD the two cases that can cause this on amdgpu are Custom brightness
> curves and Adaptive Backlight Management (ABM).

Okay, that was for me.  Please update the documentation. =:-)

-- 
Lee Jones [李琼斯]