blob: 78b32ac024666cff2467f5ef4d90d5a613410008 [file] [log] [blame]
Pavel Machek5ce47e52005-06-25 14:55:10 -07001ACPI video extensions
2~~~~~~~~~~~~~~~~~~~~~
3
4This driver implement the ACPI Extensions For Display Adapters for
5integrated graphics devices on motherboard, as specified in ACPI 2.0
6Specification, Appendix B, allowing to perform some basic control like
7defining the video POST device, retrieving EDID information or to
8setup a video output, etc. Note that this is an ref. implementation
9only. It may or may not work for your integrated video device.
Linus Torvalds1da177e2005-04-16 15:20:36 -070010
Aaron Lu86393862013-06-20 15:08:57 +080011The ACPI video driver does 3 things regarding backlight control:
Linus Torvalds1da177e2005-04-16 15:20:36 -070012
Aaron Lu86393862013-06-20 15:08:57 +0800131 Export a sysfs interface for user space to control backlight level
Linus Torvalds1da177e2005-04-16 15:20:36 -070014
Aaron Lu86393862013-06-20 15:08:57 +080015If the ACPI table has a video device, and acpi_backlight=vendor kernel
16command line is not present, the driver will register a backlight device
17and set the required backlight operation structure for it for the sysfs
18interface control. For every registered class device, there will be a
19directory named acpi_videoX under /sys/class/backlight.
Linus Torvalds1da177e2005-04-16 15:20:36 -070020
Aaron Lu86393862013-06-20 15:08:57 +080021The backlight sysfs interface has a standard definition here:
22Documentation/ABI/stable/sysfs-class-backlight.
Linus Torvalds1da177e2005-04-16 15:20:36 -070023
Aaron Lu86393862013-06-20 15:08:57 +080024And what ACPI video driver does is:
25actual_brightness: on read, control method _BQC will be evaluated to
26get the brightness level the firmware thinks it is at;
27bl_power: not implemented, will set the current brightness instead;
28brightness: on write, control method _BCM will run to set the requested
29brightness level;
30max_brightness: Derived from the _BCL package(see below);
31type: firmware
Linus Torvalds1da177e2005-04-16 15:20:36 -070032
Aaron Lu86393862013-06-20 15:08:57 +080033Note that ACPI video backlight driver will always use index for
34brightness, actual_brightness and max_brightness. So if we have
35the following _BCL package:
36
37Method (_BCL, 0, NotSerialized)
38{
39 Return (Package (0x0C)
40 {
41 0x64,
42 0x32,
43 0x0A,
44 0x14,
45 0x1E,
46 0x28,
47 0x32,
48 0x3C,
49 0x46,
50 0x50,
51 0x5A,
52 0x64
53 })
54}
55
56The first two levels are for when laptop are on AC or on battery and are
57not used by Linux currently. The remaining 10 levels are supported levels
58that we can choose from. The applicable index values are from 0 (that
59corresponds to the 0x0A brightness value) to 9 (that corresponds to the
600x64 brightness value) inclusive. Each of those index values is regarded
61as a "brightness level" indicator. Thus from the user space perspective
62the range of available brightness levels is from 0 to 9 (max_brightness)
63inclusive.
64
652 Notify user space about hotkey event
66
67There are generally two cases for hotkey event reporting:
68i) For some laptops, when user presses the hotkey, a scancode will be
69 generated and sent to user space through the input device created by
70 the keyboard driver as a key type input event, with proper remap, the
71 following key code will appear to user space:
72
73 EV_KEY, KEY_BRIGHTNESSUP
74 EV_KEY, KEY_BRIGHTNESSDOWN
75 etc.
76
77For this case, ACPI video driver does not need to do anything(actually,
78it doesn't even know this happened).
79
80ii) For some laptops, the press of the hotkey will not generate the
81 scancode, instead, firmware will notify the video device ACPI node
82 about the event. The event value is defined in the ACPI spec. ACPI
83 video driver will generate an key type input event according to the
84 notify value it received and send the event to user space through the
85 input device it created:
86
87 event keycode
88 0x86 KEY_BRIGHTNESSUP
89 0x87 KEY_BRIGHTNESSDOWN
90 etc.
91
92so this would lead to the same effect as case i) now.
93
94Once user space tool receives this event, it can modify the backlight
95level through the sysfs interface.
96
973 Change backlight level in the kernel
98
99This works for machines covered by case ii) in Section 2. Once the driver
100received a notification, it will set the backlight level accordingly. This does
101not affect the sending of event to user space, they are always sent to user
102space regardless of whether or not the video module controls the backlight level
103directly. This behaviour can be controlled through the brightness_switch_enabled
104module parameter as documented in kernel-parameters.txt. It is recommended to
105disable this behaviour once a GUI environment starts up and wants to have full
106control of the backlight level.