Documentation/firmware-guide/acpi/video_extension.rst

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