Backlight

Differences between revisions 1 and 12 (spanning 11 versions)
Revision 1 as of 2010-06-16 10:17:08
Size: 7019
Editor: p5B2E4B9B
Comment:
Revision 12 as of 2012-06-25 16:31:36
Size: 14944
Editor: penalvch
Comment: 1) added <<BR>> before showkey -s 2) removed extra *
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
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 [[https://wiki.ubuntu.com/Hotkeys/Troubleshooting|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.
<<Include(Kernel/MenuBar)>>
||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<
TableOfContents>>||

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

 * Hotkeys change the brightness, but no OSD feedback and the brightness applet does not work.
  *
There is nothing that the kernel can do to resolve this situation. Since 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 [[https://wiki.ubuntu.com/Hotkeys/Troubleshooting|debugging hotkeys]].
 * Backlight control does not work, but there are entries in {{{/sys/class/backlight}}}.
  * This may
require the ACPI backlight driver to not take control so that a vendor specific driver will have 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.

= Reporting Backlight Bugs =

 * Please do not report a backlight bug without first reading this wiki article and performing all the relevant actions mentioned here. Failure to do so will delay your bug getting addressed as quickly as possible.
 *
When filing bugs about backlight control, please classify the issue into one of the classes above. Also describe whether there was a previous kernel 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 have 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.

== Report Minimum Requirements ==

 * Please file backlight bugs by executing at the Terminal: <<BR>> {{{ubuntu-bug linux}}} <<BR>> <<BR>> If it turns out to be a non-linux package issue, it can be changed to the appropriate package.
 * Install the prerequisites by executing at the Terminal: <<BR>> {{{sudo apt-get install -y acpidump fwts dmidecode}}}
 * Execute each of the following via a terminal, and post the results to your report: <<BR>> {{{grep -r . /proc/acpi/video}}} <<BR>> {{{ls /sys/class/backlight}}} <<BR>> {{{sudo acpidump -o acpidump.txt}}} <<BR>> {{{acpixtract acpidump.txt}}} <<BR>> {{{iasl -d DSDT.dat}}} <<BR>> {{{sudo fwts > fwts}}} <<BR>> {{{sudo fwts method > fwts method}}} <<BR>> {{{dmesg | grep 'ACPI: Video'}}} <<BR>> {{{dmidecode > dmidecode.log}}} <<BR>> {{{cat /proc/version}}}
 * If your backlight hotkeys are Fn+Left and Fn+Right, add kernel parameter atkbd.softraw=0 to /boot/grub/menu.lst . Then, switch to any console, e.g. Ctrl+Alt+F1, login by root account and execute:<<BR>> {{{showkey -s}}} <<BR>> <<BR>> Then, press Fn+Left and Fn+Right key to check the code that shows up on screen. Post the results to the report. For example: <<BR>> <<BR>> Fn+Left: <<BR>> 0xe0 0x4c 0xe0 0xcc <<BR>> <<BR>> Fn+Right: <<BR>> 0xe0 0x54 0xe0 0xd4

=== Thinkpads ===

 * Add kernel parameters thinkpad-acpi.brightness_enable=1 acpi_backlight=vendor to /boot/grub/menu.lst . Execute: <<BR>> {{{sudo update grub}}} <<BR>> <<BR>> Restart, and comment on if brightness may be changed via hotkeys and/or brightness applet.
 * As well, execute the following and post results to your report: <<BR>> {{{lsmod | grep thinkpad_acpi}}}

=== Intel ===

 * If using an intel board, add the kernel parameter acpi_backlight=vendor /boot/grub/menu.lst . Execute: <<BR>> {{{sudo update grub}}} <<BR>> <<BR>> Restart, and comment on if brightness may be changed via hotkeys and/or brightness applet. Then execute the following and post results to your report: <<BR>> {{{ls -la /sys/class/backlight/intel_backlight/}}}

 * Comment on how the brightness changes if one executes: <<BR>> {{{sudo su}}} <<BR>> {{{sudo echo 8 > /sys/class/backlight/intel_backlight/brightness}}}
Line 26: Line 50:
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 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:
Line 31: Line 55:

You can check to see if your system uses the '''thinkpad-acpi''' driver by using the following command:

{{{
lsmod | grep thinkpad_acpi
}}}

=== Disabling ACPI brightness adjustments ===

If ACPI can control the brightness but the control is somehow incorrect, you can disable ACPI brightness changes with boot parameter `acpi.brightness_switch_enabled=0` (also accessible in `/sys/module/video/parameters/brightness_switch_enabled`). Note that this does not ''release'' ACPI control as `acpi_backlight=vendor` does (sometimes acpi=off is suggested but this completely turns off the ACPI subsystem). Changing this attribute merely suppresses events from the video device to be forwarded and therefore to be ignored. Writing values into the kernel interfaces should still work.
Line 73: Line 107:
{i} 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. {i} Also note that the effect may not be immediate. When testing this, the laptop I used would take a bit and then gradually fade to the destination brightness.
Line 95: Line 129:
/!\ 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? /!\ 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?
Line 113: Line 147:
The saga continues after lunch... If the video device is handled by the ACPI video driver and just the backlight interface is not working, the name of the used graphics device can be obtained by looking at the output of dmesg.

{{{
#> dmesg|grep 'ACPI: Video'
[ 2.941100] ACPI: Video Device [GFX0] (multi-head: yes rom: no post: no)
}}}

So we know we need to look for ''GFX0'' in the DSDT. But if the definition is bad enough to be not detected by the ACPI driver? In that case we might be successful through the backdoor. In other words from the info we got of the PCI bus.

{{{
#> lspci |grep VGA
00:02.0 VGA compatible controller: Intel Corporation Mobile 945GME Express Integrated Graphics Controller (rev 03)
}}}

So the graphics device is attached as PCI device 2 functional endpoint 0. Let's search for "''_ADR.*00020000''" in the disassembled DSDT:

{{{
            Device (GFX0)
            {
                Name (_ADR, 0x00020000)
                ...
}}}

So this nicely matches the name we are expecting. If we don't know the name and maybe there are other devices (on another bus) with the same ID. Well there are a few methods that are required for a device to be considered as a video device. The ACPI spec (Appendix B.) requires two methods to be defined at the graphics device level. Actually only one, but there is (as so often room for interpretation). Linux used to require both but this was changed to be ok with one of them.

 _DOS:: (Display Output Switching) This method is required by the ACPI spec for supporting brightness control. This method allows control over how the BIOS handles events to switch the output display or what to do about the brightness when changing from AC to DC. Technically this is not really required for setting the brightness and some BIOS vendors "forgot" to implement this, even when supplying methods to set the brightness.

 _DOD:: (Display Output Devices) This returns a list of attributes of the output devices which are connected to a certain graphics device. This allows to enumerate the attached output devices and also gather some information. Strictly this is also not required to find the methods to control the backlight, but for completeness allows to check the type of the output as brightness control is only defined to LCD screens.

Essentially one of these two methods must be defined for the graphics device. Otherwise the ACPI driver will not detect it as a valid video device. In which case only the BIOS/laptop vendor can resolve this.

=== Verifying the methods to control the brightiness ===

Every output device has to define methods which allow interaction (defined in Appendix B.6 of the ACPI spec). The following methods are related to the brightness control:

 _BCL:: (Backlight Control Levels) This method is supposed to return a list of percentage values. The first two are supposed to be the brightness level on AC power and on battery. The remaining should be a list of supported levels (in ascending order might be sensible, but never count on it). This seems to be a field of generous interpretation by vendors. Some leave out the first two, some sort in reverse, some use index numbers instead of percentage values or a mix of all. The Linux ACPI driver tries hard to make something of what gets returned. But there are limits.
 {{{
 Method (_BCL, 0) {
   // List of supported brightness levels
   Return (Package(7){
     80, // level when machine has full power
     50, // level when machine is on batteries
     // other supported levels
     20, 40, 60, 80, 100
   }
 }
 }}}

 _BCM:: (Backlight Control Modify) Supposed to take a percentage value defined by _BCL and set the brightness accordingly. Again, one needs to "guess" whether the actual implementation uses a relative index number instead.

 _BCQ:: (Backlight Control Query) Gets the currently set brightness. This would need to be a value defined in the list returned by _BCL but, as one would make an educated guess, there is variation, too.

Reading the method definitions requires some knowledge about the ACPI AML language and some persistence on hunting down more or less complex implementations. Some are more obvious than others. There have been cases where percentage values got converted into index values and then (incorrectly) back on query.

Also often the values get stored into a register of the embedded controller which does not necessarily need to have any result on the brightness.
----
CategoryDebugging

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

  • Hotkeys change the brightness, but no OSD feedback and the brightness applet does not work.
    • There is nothing that the kernel can do to resolve this situation. Since 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.

    • This may require the ACPI backlight driver to not take control so that a vendor specific driver will have 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.

Reporting Backlight Bugs

  • Please do not report a backlight bug without first reading this wiki article and performing all the relevant actions mentioned here. Failure to do so will delay your bug getting addressed as quickly as possible.
  • When filing bugs about backlight control, please classify the issue into one of the classes above. Also describe whether there was a previous kernel 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 have 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.

Report Minimum Requirements

  • Please file backlight bugs by executing at the Terminal:
    ubuntu-bug linux

    If it turns out to be a non-linux package issue, it can be changed to the appropriate package.

  • Install the prerequisites by executing at the Terminal:
    sudo apt-get install -y acpidump fwts dmidecode

  • Execute each of the following via a terminal, and post the results to your report:
    grep -r . /proc/acpi/video
    ls /sys/class/backlight
    sudo acpidump -o acpidump.txt
    acpixtract acpidump.txt
    iasl -d DSDT.dat
    sudo fwts > fwts
    sudo fwts method > fwts method
    dmesg | grep 'ACPI: Video'
    dmidecode > dmidecode.log
    cat /proc/version

  • If your backlight hotkeys are Fn+Left and Fn+Right, add kernel parameter atkbd.softraw=0 to /boot/grub/menu.lst . Then, switch to any console, e.g. Ctrl+Alt+F1, login by root account and execute:
    showkey -s

    Then, press Fn+Left and Fn+Right key to check the code that shows up on screen. Post the results to the report. For example:

    Fn+Left:
    0xe0 0x4c 0xe0 0xcc

    Fn+Right:
    0xe0 0x54 0xe0 0xd4

Thinkpads

  • Add kernel parameters thinkpad-acpi.brightness_enable=1 acpi_backlight=vendor to /boot/grub/menu.lst . Execute:
    sudo update grub

    Restart, and comment on if brightness may be changed via hotkeys and/or brightness applet.

  • As well, execute the following and post results to your report:
    lsmod | grep thinkpad_acpi

Intel

  • If using an intel board, add the kernel parameter acpi_backlight=vendor /boot/grub/menu.lst . Execute:
    sudo update grub

    Restart, and comment on if brightness may be changed via hotkeys and/or brightness applet. Then execute the following and post results to your report:
    ls -la /sys/class/backlight/intel_backlight/

  • Comment on how the brightness changes if one executes:
    sudo su
    sudo echo 8 > /sys/class/backlight/intel_backlight/brightness

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

You can check to see if your system uses the thinkpad-acpi driver by using the following command:

lsmod | grep thinkpad_acpi

Disabling ACPI brightness adjustments

If ACPI can control the brightness but the control is somehow incorrect, you can disable ACPI brightness changes with boot parameter acpi.brightness_switch_enabled=0 (also accessible in /sys/module/video/parameters/brightness_switch_enabled). Note that this does not release ACPI control as acpi_backlight=vendor does (sometimes acpi=off is suggested but this completely turns off the ACPI subsystem). Changing this attribute merely suppresses events from the video device to be forwarded and therefore to be ignored. Writing values into the kernel interfaces should still work.

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

Warning /!\ 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.

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

(i) Also note that the effect may not 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.

Warning /!\ 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.

If the video device is handled by the ACPI video driver and just the backlight interface is not working, the name of the used graphics device can be obtained by looking at the output of dmesg.

#> dmesg|grep 'ACPI: Video'
[    2.941100] ACPI: Video Device [GFX0] (multi-head: yes  rom: no  post: no)

So we know we need to look for GFX0 in the DSDT. But if the definition is bad enough to be not detected by the ACPI driver? In that case we might be successful through the backdoor. In other words from the info we got of the PCI bus.

#> lspci |grep VGA
00:02.0 VGA compatible controller: Intel Corporation Mobile 945GME Express Integrated Graphics Controller (rev 03)

So the graphics device is attached as PCI device 2 functional endpoint 0. Let's search for "_ADR.*00020000" in the disassembled DSDT:

            Device (GFX0)
            {
                Name (_ADR, 0x00020000)
                ...

So this nicely matches the name we are expecting. If we don't know the name and maybe there are other devices (on another bus) with the same ID. Well there are a few methods that are required for a device to be considered as a video device. The ACPI spec (Appendix B.) requires two methods to be defined at the graphics device level. Actually only one, but there is (as so often room for interpretation). Linux used to require both but this was changed to be ok with one of them.

_DOS
(Display Output Switching) This method is required by the ACPI spec for supporting brightness control. This method allows control over how the BIOS handles events to switch the output display or what to do about the brightness when changing from AC to DC. Technically this is not really required for setting the brightness and some BIOS vendors "forgot" to implement this, even when supplying methods to set the brightness.
_DOD
(Display Output Devices) This returns a list of attributes of the output devices which are connected to a certain graphics device. This allows to enumerate the attached output devices and also gather some information. Strictly this is also not required to find the methods to control the backlight, but for completeness allows to check the type of the output as brightness control is only defined to LCD screens.

Essentially one of these two methods must be defined for the graphics device. Otherwise the ACPI driver will not detect it as a valid video device. In which case only the BIOS/laptop vendor can resolve this.

Verifying the methods to control the brightiness

Every output device has to define methods which allow interaction (defined in Appendix B.6 of the ACPI spec). The following methods are related to the brightness control:

_BCL
(Backlight Control Levels) This method is supposed to return a list of percentage values. The first two are supposed to be the brightness level on AC power and on battery. The remaining should be a list of supported levels (in ascending order might be sensible, but never count on it). This seems to be a field of generous interpretation by vendors. Some leave out the first two, some sort in reverse, some use index numbers instead of percentage values or a mix of all. The Linux ACPI driver tries hard to make something of what gets returned. But there are limits.
 Method (_BCL, 0) {
   // List of supported brightness levels
   Return (Package(7){
     80, // level when machine has full power
     50, // level when machine is on batteries
     // other supported levels
     20, 40, 60, 80, 100
   }
 }
_BCM
(Backlight Control Modify) Supposed to take a percentage value defined by _BCL and set the brightness accordingly. Again, one needs to "guess" whether the actual implementation uses a relative index number instead.
_BCQ
(Backlight Control Query) Gets the currently set brightness. This would need to be a value defined in the list returned by _BCL but, as one would make an educated guess, there is variation, too.

Reading the method definitions requires some knowledge about the ACPI AML language and some persistence on hunting down more or less complex implementations. Some are more obvious than others. There have been cases where percentage values got converted into index values and then (incorrectly) back on query.

Also often the values get stored into a register of the embedded controller which does not necessarily need to have any result on the brightness.


CategoryDebugging

Kernel/Debugging/Backlight (last edited 2023-07-14 06:48:38 by vanvugt)