amdgpu-backlight

amdgpu-backlight is a small C99 utility for controlling laptop-panel brightness through AMDGPU's native Linux backlight interface. It provides the core xbacklight-style operations without depending on X11:

amdgpu-backlight -get
amdgpu-backlight -inc 10
amdgpu-backlight -dec 10
amdgpu-backlight -set 50

Every successful operation prints the resulting integer percentage to stdout, which also makes the program convenient for hotkey scripts and status displays.

Kernel interface

The Linux backlight core exposes devices below:

/sys/class/backlight/<backlight>/

The stable userspace ABI documents these attributes:

• brightness — requested brightness, read/write, in the range 0 through max_brightness;
• actual_brightness — hardware-reported brightness, read-only;
• max_brightness — maximum brightness, read-only;
• bl_power — backlight power control;
• type — firmware, platform, or raw.

scale is also exposed by the backlight core but remains documented under the kernel's testing ABI. Current AMD Display Core can report linear or non-linear depending on the panel/brightness curve.

Current AMD Display Core source registers native eDP backlights using the name:

amdgpu_bl%d

For example:

/sys/class/backlight/amdgpu_bl0

The numeric suffix is derived by the driver and should not be assumed to be permanently tied to a particular panel. The Linux stable ABI guarantees the backlight class interface, not the AMDGPU device name itself.

amdgpu-backlight therefore discovers names matching amdgpu_bl<digits>. It auto-selects the device only when exactly one exists. On a machine exposing multiple AMDGPU backlights, select one explicitly:

amdgpu-backlight -list
amdgpu-backlight -device amdgpu_bl1 -inc 10

Semantics

The program deliberately uses brightness for current-state decisions. The kernel ABI notes that actual_brightness can differ because of hardware, blanking, or power-saving behavior and recommends that userspace generally use brightness for policy decisions.

-inc and -dec interpret their argument as a percentage of max_brightness, not a percentage of the current value. Results are clamped to the kernel range. No perceptual correction is applied when scale says non-linear; the percentage is the normalized value in the user-visible range exported by the driver.

Build

A C99 compiler and POSIX userspace are sufficient:

make
make test

Install under /usr/local by default:

sudo make install

or package into a staging root:

make DESTDIR="$PKG" PREFIX=/usr install

The installed files are:

$PREFIX/bin/amdgpu-backlight
$PREFIX/share/man/man1/amdgpu-backlight.1

Access policy

Changing brightness requires write access to the kernel's brightness attribute. Do not make this program set-user-ID. A narrow device policy is a better privilege boundary.

For a system where local display users are members of video, the example contrib/90-backlight.rules policy makes AMDGPU brightness attributes group-writable:

SUBSYSTEM=="backlight", KERNEL=="amdgpu_bl*", \
    RUN+="/bin/chgrp video /sys%p/brightness", \
    RUN+="/bin/chmod g+w /sys%p/brightness"

Reload the policy and trigger the backlight subsystem, or reboot:

sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=backlight

Verify the resulting authority directly:

ls -l /sys/class/backlight/amdgpu_bl0/brightness
test -w /sys/class/backlight/amdgpu_bl0/brightness && echo writable

Hotkeys

The earlier shell wrapper can now collapse to a direct call:

amdgpu-backlight -inc 10
amdgpu-backlight -dec 10

No X server connection is required.

References

• Linux backlight core: https://docs.kernel.org/gpu/backlight.html
• Stable backlight sysfs ABI: https://github.com/torvalds/linux/blob/master/Documentation/ABI/stable/sysfs-class-backlight
• Backlight scale testing ABI: https://github.com/torvalds/linux/blob/master/Documentation/ABI/testing/sysfs-class-backlight
• AMD Display Core backlight implementation: https://github.com/torvalds/linux/blob/master/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_backlight.c