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