1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ===================== 3 =====================
4 ACPI video extensions 4 ACPI video extensions
5 ===================== 5 =====================
6 6
7 This driver implement the ACPI Extensions For 7 This driver implement the ACPI Extensions For Display Adapters for
8 integrated graphics devices on motherboard, as 8 integrated graphics devices on motherboard, as specified in ACPI 2.0
9 Specification, Appendix B, allowing to perform 9 Specification, Appendix B, allowing to perform some basic control like
10 defining the video POST device, retrieving EDI 10 defining the video POST device, retrieving EDID information or to
11 setup a video output, etc. Note that this is 11 setup a video output, etc. Note that this is an ref. implementation
12 only. It may or may not work for your integra 12 only. It may or may not work for your integrated video device.
13 13
14 The ACPI video driver does 3 things regarding 14 The ACPI video driver does 3 things regarding backlight control.
15 15
16 Export a sysfs interface for user space to con 16 Export a sysfs interface for user space to control backlight level
17 ============================================== 17 ==================================================================
18 18
19 If the ACPI table has a video device, and acpi 19 If the ACPI table has a video device, and acpi_backlight=vendor kernel
20 command line is not present, the driver will r 20 command line is not present, the driver will register a backlight device
21 and set the required backlight operation struc 21 and set the required backlight operation structure for it for the sysfs
22 interface control. For every registered class 22 interface control. For every registered class device, there will be a
23 directory named acpi_videoX under /sys/class/b 23 directory named acpi_videoX under /sys/class/backlight.
24 24
25 The backlight sysfs interface has a standard d 25 The backlight sysfs interface has a standard definition here:
26 Documentation/ABI/stable/sysfs-class-backlight 26 Documentation/ABI/stable/sysfs-class-backlight.
27 27
28 And what ACPI video driver does is: 28 And what ACPI video driver does is:
29 29
30 actual_brightness: 30 actual_brightness:
31 on read, control method _BQC will be evaluat 31 on read, control method _BQC will be evaluated to
32 get the brightness level the firmware thinks 32 get the brightness level the firmware thinks it is at;
33 bl_power: 33 bl_power:
34 not implemented, will set the current bright 34 not implemented, will set the current brightness instead;
35 brightness: 35 brightness:
36 on write, control method _BCM will run to se 36 on write, control method _BCM will run to set the requested brightness level;
37 max_brightness: 37 max_brightness:
38 Derived from the _BCL package(see below); 38 Derived from the _BCL package(see below);
39 type: 39 type:
40 firmware 40 firmware
41 41
42 Note that ACPI video backlight driver will alw 42 Note that ACPI video backlight driver will always use index for
43 brightness, actual_brightness and max_brightne 43 brightness, actual_brightness and max_brightness. So if we have
44 the following _BCL package:: 44 the following _BCL package::
45 45
46 Method (_BCL, 0, NotSerialized) 46 Method (_BCL, 0, NotSerialized)
47 { 47 {
48 Return (Package (0x0C) 48 Return (Package (0x0C)
49 { 49 {
50 0x64, 50 0x64,
51 0x32, 51 0x32,
52 0x0A, 52 0x0A,
53 0x14, 53 0x14,
54 0x1E, 54 0x1E,
55 0x28, 55 0x28,
56 0x32, 56 0x32,
57 0x3C, 57 0x3C,
58 0x46, 58 0x46,
59 0x50, 59 0x50,
60 0x5A, 60 0x5A,
61 0x64 61 0x64
62 }) 62 })
63 } 63 }
64 64
65 The first two levels are for when laptop are o 65 The first two levels are for when laptop are on AC or on battery and are
66 not used by Linux currently. The remaining 10 66 not used by Linux currently. The remaining 10 levels are supported levels
67 that we can choose from. The applicable index 67 that we can choose from. The applicable index values are from 0 (that
68 corresponds to the 0x0A brightness value) to 9 68 corresponds to the 0x0A brightness value) to 9 (that corresponds to the
69 0x64 brightness value) inclusive. Each of thos 69 0x64 brightness value) inclusive. Each of those index values is regarded
70 as a "brightness level" indicator. Thus from t 70 as a "brightness level" indicator. Thus from the user space perspective
71 the range of available brightness levels is fr 71 the range of available brightness levels is from 0 to 9 (max_brightness)
72 inclusive. 72 inclusive.
73 73
74 Notify user space about hotkey event 74 Notify user space about hotkey event
75 ==================================== 75 ====================================
76 76
77 There are generally two cases for hotkey event 77 There are generally two cases for hotkey event reporting:
78 78
79 i) For some laptops, when user presses the hot 79 i) For some laptops, when user presses the hotkey, a scancode will be
80 generated and sent to user space through th 80 generated and sent to user space through the input device created by
81 the keyboard driver as a key type input eve 81 the keyboard driver as a key type input event, with proper remap, the
82 following key code will appear to user spac 82 following key code will appear to user space::
83 83
84 EV_KEY, KEY_BRIGHTNESSUP 84 EV_KEY, KEY_BRIGHTNESSUP
85 EV_KEY, KEY_BRIGHTNESSDOWN 85 EV_KEY, KEY_BRIGHTNESSDOWN
86 etc. 86 etc.
87 87
88 For this case, ACPI video driver does not need 88 For this case, ACPI video driver does not need to do anything(actually,
89 it doesn't even know this happened). 89 it doesn't even know this happened).
90 90
91 ii) For some laptops, the press of the hotkey 91 ii) For some laptops, the press of the hotkey will not generate the
92 scancode, instead, firmware will notify th 92 scancode, instead, firmware will notify the video device ACPI node
93 about the event. The event value is define 93 about the event. The event value is defined in the ACPI spec. ACPI
94 video driver will generate an key type inp 94 video driver will generate an key type input event according to the
95 notify value it received and send the even 95 notify value it received and send the event to user space through the
96 input device it created: 96 input device it created:
97 97
98 ===== ================== 98 ===== ==================
99 event keycode 99 event keycode
100 ===== ================== 100 ===== ==================
101 0x86 KEY_BRIGHTNESSUP 101 0x86 KEY_BRIGHTNESSUP
102 0x87 KEY_BRIGHTNESSDOWN 102 0x87 KEY_BRIGHTNESSDOWN
103 etc. 103 etc.
104 ===== ================== 104 ===== ==================
105 105
106 so this would lead to the same effect as case 106 so this would lead to the same effect as case i) now.
107 107
108 Once user space tool receives this event, it c 108 Once user space tool receives this event, it can modify the backlight
109 level through the sysfs interface. 109 level through the sysfs interface.
110 110
111 Change backlight level in the kernel 111 Change backlight level in the kernel
112 ==================================== 112 ====================================
113 113
114 This works for machines covered by case ii) in 114 This works for machines covered by case ii) in Section 2. Once the driver
115 received a notification, it will set the backl 115 received a notification, it will set the backlight level accordingly. This does
116 not affect the sending of event to user space, 116 not affect the sending of event to user space, they are always sent to user
117 space regardless of whether or not the video m 117 space regardless of whether or not the video module controls the backlight level
118 directly. This behaviour can be controlled thr 118 directly. This behaviour can be controlled through the brightness_switch_enabled
119 module parameter as documented in admin-guide/ 119 module parameter as documented in admin-guide/kernel-parameters.rst. It is
120 recommended to disable this behaviour once a G 120 recommended to disable this behaviour once a GUI environment starts up and
121 wants to have full control of the backlight le 121 wants to have full control of the backlight level.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.