Hans de Goede (![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png)
hansdegoede) wrote2014-05-02 02:12 pm
hansdegoede) wrote2014-05-02 02:12 pm
The brightness saga
I've been debugging various backlight brightness problems lately, and I've learned a lot in the process. First lets take a look at how all the bits fit together. There are 3 parts involved in changing the brightness:
The brightness keys can be hooked up in a number of ways. Sometimes they function as normal keyboard keys generating extended keycodes. On other cases they are reporting events through some firmware interface (ie ACPI) and they require a driver to be loaded listening for these firmware events.
Processing the keypresses
This is normally done by your desktop environment (Gnome, KDE, etc.) some part of your DE will listen to the events and react to them.
If the acpi video driver is active it may be processing its own events and changing the brightness itself, this usually is underiable as now the
brightness gets changed twice for each keypress. Fedora has this disabled by default. For other distros it is advisable to disable this by adding
video.brightness_switch_enabled=0 to your kernel commandline.
Controlling the actual backlight
This unfortunately is quite complicated. Most laptops have multiple ways to control the backlight, some of which sometimes do not work. You can see
which interfaces are currently available on your laptop by doing:
ls /sys/class/backlight
There are usually 1 or more firmware interfaces, usually the standard ACPI video interface, as well as a vendor specific interface. On a Lenovo Yoga 2 11, I counted 3 firmware interfaces known to Linux, acpi-video, ideapad-laptop and thinkpad_acpi all could create a backlight interface (and none of them
worked). Besides the firmware interface there will often also be a direct hardware (raw) interface, ie /sys/class/backlight/intel_backlight.
Detecting where the problem is
The first step is to figure out in which of the 3 parts listed above the problem is. If you get an on screen display (osd) showing the brightness
setting when you press your brigthness up / down setting, but the brightness does not change, then detecting and processing the keypresses works fine, and there is a problem with controlling the actual backlight.
If the osd does not show then install evemu, and as root run evemu-record, this will show you a list of input devices. You can select capturing raw events from one of them by entering the number for the device. Try these one by one, and for each press the brightness keys and see if they generate events. Likely candidates for generating brightness key events are "Video Bus", something with your laptop model / manufacturer name in it, something with WMI in it, and the actual keyboard device. If one of these generates events for the brightness keys, and the events are KEY_BRIGHTNESSUP/DOWN then the detection of the keypresses works fine and there is a problem in the processing of them by your DE. If there are no events, or the events have the wrong key-codes, then file a bug against the kernel.
Note in some rare cases the OSD will not show, but the backlight brightness will change, this means all steps are done purely in the laptops firmware, and any DE brightness control / change notification will not be possible. There is nothing which can be done to fix this.
Debugging backlight control problems
Backlight control not working usually indicates a problem with one of the firmware interfaces. Note that if more then one backlight interface is present that DE-s will just pick one, DE-s prefer the firmware interfaces.
There are a number of kernel commandline options which influence the various firmware backlight drivers. To debug backlight control problems try these *one* by *one*, please do not mix and match! For each boot with a new kernel option do "ls /sys/class/backlight" and save the output + which kernel option it belongs to. The options below are listed from most likely to help to least likely. Once you've found an option which makes the backlight work properly, make sure to test it also works with suspend and resume, and then you can stop going through the list. Here are the options to try;
Filing bugs
When filing a bug please for brightness problems please always put your exact laptop model in the Summary of the bug. Also please always run the following 2 commands:
When the bug is a problem about backlight control please also add the output of "ls /sys/class/backlight" for each boot with different kernel commandline
options you've tried, including the output for a boot without any kernel options.
- Detecting brightness up / down keypresses
- Processing the keypresses
- Controlling the actual backlight
The brightness keys can be hooked up in a number of ways. Sometimes they function as normal keyboard keys generating extended keycodes. On other cases they are reporting events through some firmware interface (ie ACPI) and they require a driver to be loaded listening for these firmware events.
Processing the keypresses
This is normally done by your desktop environment (Gnome, KDE, etc.) some part of your DE will listen to the events and react to them.
If the acpi video driver is active it may be processing its own events and changing the brightness itself, this usually is underiable as now the
brightness gets changed twice for each keypress. Fedora has this disabled by default. For other distros it is advisable to disable this by adding
video.brightness_switch_enabled=0 to your kernel commandline.
Controlling the actual backlight
This unfortunately is quite complicated. Most laptops have multiple ways to control the backlight, some of which sometimes do not work. You can see
which interfaces are currently available on your laptop by doing:
ls /sys/class/backlight
There are usually 1 or more firmware interfaces, usually the standard ACPI video interface, as well as a vendor specific interface. On a Lenovo Yoga 2 11, I counted 3 firmware interfaces known to Linux, acpi-video, ideapad-laptop and thinkpad_acpi all could create a backlight interface (and none of them
worked). Besides the firmware interface there will often also be a direct hardware (raw) interface, ie /sys/class/backlight/intel_backlight.
Detecting where the problem is
The first step is to figure out in which of the 3 parts listed above the problem is. If you get an on screen display (osd) showing the brightness
setting when you press your brigthness up / down setting, but the brightness does not change, then detecting and processing the keypresses works fine, and there is a problem with controlling the actual backlight.
If the osd does not show then install evemu, and as root run evemu-record, this will show you a list of input devices. You can select capturing raw events from one of them by entering the number for the device. Try these one by one, and for each press the brightness keys and see if they generate events. Likely candidates for generating brightness key events are "Video Bus", something with your laptop model / manufacturer name in it, something with WMI in it, and the actual keyboard device. If one of these generates events for the brightness keys, and the events are KEY_BRIGHTNESSUP/DOWN then the detection of the keypresses works fine and there is a problem in the processing of them by your DE. If there are no events, or the events have the wrong key-codes, then file a bug against the kernel.
Note in some rare cases the OSD will not show, but the backlight brightness will change, this means all steps are done purely in the laptops firmware, and any DE brightness control / change notification will not be possible. There is nothing which can be done to fix this.
Debugging backlight control problems
Backlight control not working usually indicates a problem with one of the firmware interfaces. Note that if more then one backlight interface is present that DE-s will just pick one, DE-s prefer the firmware interfaces.
There are a number of kernel commandline options which influence the various firmware backlight drivers. To debug backlight control problems try these *one* by *one*, please do not mix and match! For each boot with a new kernel option do "ls /sys/class/backlight" and save the output + which kernel option it belongs to. The options below are listed from most likely to help to least likely. Once you've found an option which makes the backlight work properly, make sure to test it also works with suspend and resume, and then you can stop going through the list. Here are the options to try;
- video.use_native_backlight=1
- acpi_backlight=vendor
- acpi_osi="!Windows 2012"
- acpi_osi="!Windows 2009"
Filing bugs
When filing a bug please for brightness problems please always put your exact laptop model in the Summary of the bug. Also please always run the following 2 commands:
- dmesg > dmesg.log
- grep '.*' /sys/class/dmi/id/*_* 2> /dev/null > dmi.log
When the bug is a problem about backlight control please also add the output of "ls /sys/class/backlight" for each boot with different kernel commandline
options you've tried, including the output for a boot without any kernel options.