8ecd32b668
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
6ca017658b ("[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>
2.2 KiB
What: /sys/class/backlight//bl_power Date: April 2005 KernelVersion: 2.6.12 Contact: Richard Purdie rpurdie@rpsys.net Description: Control BACKLIGHT power, values are compatible with FB_BLANK_* from fb.h
- 0 (FB_BLANK_UNBLANK) : power on.
- 4 (FB_BLANK_POWERDOWN) : power off
Users: HAL
What: /sys/class/backlight//brightness Date: April 2005 KernelVersion: 2.6.12 Contact: Richard Purdie rpurdie@rpsys.net Description: Control the brightness for this . Values are between 0 and max_brightness. This file will also show the brightness level stored in the driver, which may not be the actual brightness (see actual_brightness). Users: HAL
What: /sys/class/backlight//actual_brightness Date: March 2006 KernelVersion: 2.6.17 Contact: Richard Purdie rpurdie@rpsys.net Description: 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//max_brightness Date: April 2005 KernelVersion: 2.6.12 Contact: Richard Purdie rpurdie@rpsys.net Description: Maximum brightness for . Users: HAL
What: /sys/class/backlight//type Date: September 2010 KernelVersion: 2.6.37 Contact: Matthew Garrett mjg@redhat.com Description: The type of interface controlled by . "firmware": The driver uses a standard firmware interface "platform": The driver uses a platform-specific interface "raw": The driver controls hardware registers directly
In the general case, when multiple backlight
interfaces are available for a single device, firmware
control should be preferred to platform control should
be preferred to raw control. Using a firmware
interface reduces the probability of confusion with
the hardware and the OS independently updating the
backlight state. Platform interfaces are mostly a
holdover from pre-standardisation of firmware
interfaces.