About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / acpi / video_extension.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

1	ACPI video extensions
2	~~~~~~~~~~~~~~~~~~~~~
3	
4	This driver implement the ACPI Extensions For Display Adapters for
5	integrated graphics devices on motherboard, as specified in ACPI 2.0
6	Specification, Appendix B, allowing to perform some basic control like
7	defining the video POST device, retrieving EDID information or to
8	setup a video output, etc.  Note that this is an ref. implementation
9	only.  It may or may not work for your integrated video device.
10	
11	The ACPI video driver does 3 things regarding backlight control:
12	
13	1 Export a sysfs interface for user space to control backlight level
14	
15	If the ACPI table has a video device, and acpi_backlight=vendor kernel
16	command line is not present, the driver will register a backlight device
17	and set the required backlight operation structure for it for the sysfs
18	interface control. For every registered class device, there will be a
19	directory named acpi_videoX under /sys/class/backlight.
20	
21	The backlight sysfs interface has a standard definition here:
22	Documentation/ABI/stable/sysfs-class-backlight.
23	
24	And what ACPI video driver does is:
25	actual_brightness: on read, control method _BQC will be evaluated to
26	get the brightness level the firmware thinks it is at;
27	bl_power: not implemented, will set the current brightness instead;
28	brightness: on write, control method _BCM will run to set the requested
29	brightness level;
30	max_brightness: Derived from the _BCL package(see below);
31	type: firmware
32	
33	Note that ACPI video backlight driver will always use index for
34	brightness, actual_brightness and max_brightness. So if we have
35	the following _BCL package:
36	
37	Method (_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	
56	The first two levels are for when laptop are on AC or on battery and are
57	not used by Linux currently. The remaining 10 levels are supported levels
58	that we can choose from. The applicable index values are from 0 (that
59	corresponds to the 0x0A brightness value) to 9 (that corresponds to the
60	0x64 brightness value) inclusive. Each of those index values is regarded
61	as a "brightness level" indicator. Thus from the user space perspective
62	the range of available brightness levels is from 0 to 9 (max_brightness)
63	inclusive.
64	
65	2 Notify user space about hotkey event
66	
67	There are generally two cases for hotkey event reporting:
68	i) 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	
77	For this case, ACPI video driver does not need to do anything(actually,
78	it doesn't even know this happened).
79	
80	ii) 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	
92	so this would lead to the same effect as case i) now.
93	
94	Once user space tool receives this event, it can modify the backlight
95	level through the sysfs interface.
96	
97	3 Change backlight level in the kernel
98	
99	This works for machines covered by case ii) in Section 2. Once the driver
100	received a notification, it will set the backlight level accordingly. This does
101	not affect the sending of event to user space, they are always sent to user
102	space regardless of whether or not the video module controls the backlight level
103	directly. This behaviour can be controlled through the brightness_switch_enabled
104	module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to
105	disable this behaviour once a GUI environment starts up and wants to have full
106	control of the backlight level.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog