There are a lot of different issues with backlight control around which can be generally put into these classes:

• Hotkeys change the brightness, but no OSD feedback and the brightness applet does not work. This normally is not a problem in Linux. If there is no vendor specific control mechanism and the generic ACPI interface is not defined (or not defined correctly), there is no way Linux can interact. In those cases the hotkeys are directly wired to the backlight control and no events are passed on to the OS.

• Backlight control works through the brightness applet but not via hotkeys. This is most likely a hotkey issue which might be further debugged looking at debugging hotkeys.

• Backlight control does not work, but there are entries in /sys/class/backlight. Might require the ACPI backlight driver to not take control to give a vendor specific driver a chance to register (see below).

• Backlight control does not work and there are no entries in /sys/class/backlight. Neither the ACPI backlight driver nor any vendor specific driver were able to find a valid interface. Either requires a new vendor driver (which is unlikely) or the ACPI BIOS is broken (see below). Updates to the ACPI BIOS are rare as well but in some cases it is possible to work with upstream to extend the Linux side to handle some of that brokenness.

Filing Bugs

When filing bugs about backlight control, try to classify the issue into the classes above. Also describe whether there was a kernel before that worked, or whether this was never the case. Also be very specific in the bug title about the laptop vendor and model. Backlight control is very specific to hardware and a bug titled "backlight control does not work" just causes other people to use that bug even if they got a completely different laptop. It is much simpler to look into issues separately than to mix things.

Also, depending on the class of issues, provide additional information about the kernel interface. Does it exist, do any values change when writing into the control files? Is there any effect?

If the kernel interface does not work, add the dump of the ACPI BIOS as described below.

Diagnostic Techniques

Disabling the ACPI backlight driver

In some cases the ACPI BIOS provides the interfaces required to control the backlight through the generic ACPI interface, but the actual methods are not implemented. So the ACPI driver register with the hardware and prevents any laptop specific drivers from doing so. In those cases it is possible to prevent the ACPI backlight driver from starting by adding the following line to the kernel boot parameters:

acpi_backlight=vendor

Unfortunately the thinkpad-acpi driver behaves differently, as it does not act on the ACPI driver being active or not, but on the ACPI methods being defined. Thus forcing the vendor specific driver to activate requires an additional

thinkpad-acpi.brightness_enable=1

Checking the kernel interfaces

To decide whether the missing brightness control is a hotkey, a X driver or a kernel issue, testing the kernel interfaces will give additional information.

The /proc/acpi/video interface

This actually is deprecated and would also only be working if the ACPI backlight driver is active. It will be described only for completeness. The ACPI backlight driver also exposes itself through the new sysfs interface.

/proc/acpi/video/
 |
 +- <GFX card>
 |   |
 |   +- <Display Device>
 |   |   |
 |   |   +- EDID
 |   |   +- brightness
 |   |   +- state
 |   |   +- info
 |   +- ...
 +- ...

Each discovered graphics card will have one entry and within that each defined output device will have its set of values. The brightness variable contains either "<not supported>" or the possible brightness values and the currently set value. This could, for example, look like this:

#> grep -r . /proc/acpi/video/GFX0/DD04/
proc/acpi/video/GFX0/DD04/EDID:<not supported>
/proc/acpi/video/GFX0/DD04/brightness:levels:  20 28 36 44 52 60 68 76 84 92 100
/proc/acpi/video/GFX0/DD04/brightness:current: 100
/proc/acpi/video/GFX0/DD04/state:state:     0x1d
/proc/acpi/video/GFX0/DD04/state:query:     0x00
/proc/acpi/video/GFX0/DD04/info:device_id:    0x0410
/proc/acpi/video/GFX0/DD04/info:type:         LCD
/proc/acpi/video/GFX0/DD04/info:known by bios: yes

So in this case there are 11 possible percentage values which, when written into the brightness file, would change the brightness of the display. Currently it is set to full brightness.

Note that only those discrete percentage values are defined. Writing other values results in an error.

Also note that the effect does not need to be immediate. When testing this, the laptop I used would take a bit and then gradually fade to the destination brightness.

The /sys/class/backlight interface

Contrary to the ACPI interface in /proc, the sysfs interface has only entries when there is an output device that supports backlight control.

/sys/class/backlight/
 |
 +- <output device with backlight control>
 |   |
 |   +- actual_brightness
 |   +- bl_power
 |   +- brightness
 |   +- ...
 |   +- max_brightness
 |   +- ...
 +- ...

The file actual_brightness contains the currently set brightness level. Reading brightness results in the same number. In max_brightness is the maximum number allowed to be written into brightness. While the ACPI /proc interface uses percentage levels, the sysfs interface uses index numbers between 0 and the maximum brightness.

ToDO: might be that actual_brightness queries the values on read, while brightness only returns the value written last. bl_power has no effect, what is it supposed to do?

#> grep . /sys/class/backlight/acpi_video0/*
/sys/class/backlight/acpi_video0/actual_brightness:10
/sys/class/backlight/acpi_video0/bl_power:0
/sys/class/backlight/acpi_video0/brightness:10
/sys/class/backlight/acpi_video0/max_brightness:10

Into the abyss: looking at the ACPI BIOS

Whenever the kernel interface does not work or is not present at all, it is time to put on the mining helmet and try to make sense of the information stored in the ACPI BIOS which can be obtained following this description. The next challenges will be to find the right section for the graphics device and the display devices defined there.

Finding the correct graphics device

The ACPI BIOS often contains not only the information for the graphics card used in the one laptop we are looking at, but has entries for every possible variation the vendor had in mind. So before further inspection, we need to find out which definition we have to look at.

The saga continues after lunch...