요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
=====================
ACPI video extensions
=====================
This driver implement the ACPI Extensions For Display Adapters for
integrated graphics devices on motherboard, as specified in ACPI 2.0
Specification, Appendix B, allowing to perform some basic control like
defining the video POST device, retrieving EDID information or to
setup a video output, etc. Note that this is an ref. implementation
only. It may or may not work for your integrated video device.
The ACPI video driver does 3 things regarding backlight control.
Export a sysfs interface for user space to control backlight level
==================================================================
If the ACPI table has a video device, and acpi_backlight=vendor kernel
command line is not present, the driver will register a backlight device
and set the required backlight operation structure for it for the sysfs
interface control. For every registered class device, there will be a
directory named acpi_videoX under /sys/class/backlight.
The backlight sysfs interface has a standard definition here:
Documentation/ABI/stable/sysfs-class-backlight.
And what ACPI video driver does is:
actual_brightness:
on read, control method _BQC will be evaluated to
get the brightness level the firmware thinks it is at;
bl_power:
not implemented, will set the current brightness instead;
brightness:
on write, control method _BCM will run to set the requested brightness level;
max_brightness:
Derived from the _BCL package(see below);
type:
firmware
Note that ACPI video backlight driver will always use index for
brightness, actual_brightness and max_brightness. So if we have
the following _BCL package::
Method (_BCL, 0, NotSerialized)
{
Return (Package (0x0C)
{
0x64,
0x32,
0x0A,
0x14,
0x1E,
0x28,
0x32,
0x3C,
0x46,
0x50,
0x5A,
0x64
})
}
The first two levels are for when laptop are on AC or on battery and are
not used by Linux currently. The remaining 10 levels are supported levels
that we can choose from. The applicable index values are from 0 (that
corresponds to the 0x0A brightness value) to 9 (that corresponds to the
0x64 brightness value) inclusive. Each of those index values is regarded
as a "brightness level" indicator. Thus from the user space perspective
the range of available brightness levels is from 0 to 9 (max_brightness)
inclusive.
Notify user space about hotkey event
====================================
There are generally two cases for hotkey event reporting:
i) For some laptops, when user presses the hotkey, a scancode will be
generated and sent to user space through the input device created by
the keyboard driver as a key type input event, with proper remap, the
following key code will appear to user space::
EV_KEY, KEY_BRIGHTNESSUP
EV_KEY, KEY_BRIGHTNESSDOWN
etc.
For this case, ACPI video driver does not need to do anything(actually,
it doesn't even know this happened).
ii) For some laptops, the press of the hotkey will not generate the
scancode, instead, firmware will notify the video device ACPI node
about the event. The event value is defined in the ACPI spec. ACPI
video driver will generate an key type input event according to the
notify value it received and send the event to user space through the
input device it created:
===== ==================
event keycode
===== ==================
0x86 KEY_BRIGHTNESSUP
0x87 KEY_BRIGHTNESSDOWN
etc.
===== ==================
so this would lead to the same effect as case i) now.
Once user space tool receives this event, it can modify the backlight
level through the sysfs interface.
Change backlight level in the kernel
====================================
This works for machines covered by case ii) in Section 2. Once the driver
received a notification, it will set the backlight level accordingly. This does
not affect the sending of event to user space, they are always sent to user
space regardless of whether or not the video module controls the backlight level
directly. This behaviour can be controlled through the brightness_switch_enabled
module parameter as documented in admin-guide/kernel-parameters.rst. It is
recommended to disable this behaviour once a GUI environment starts up and
wants to have full control of the backlight level.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
ACPI video extension의 범위
1-15이 driver는 ACPI 2.0 Specification Appendix B에 규정된 `ACPI Extensions For Display Adapters`의 reference implementation이다. motherboard에 통합된 graphics device를 대상으로 video POST device 지정, EDID 정보 조회, video output 설정 같은 기본 제어를 제공한다.
Reference implementation이라는 표현은 모든 integrated video device에서 동작을 보장한다는 뜻이 아니다. 장비의 ACPI table과 firmware method 구현에 따라 동작할 수도 있고 그렇지 않을 수도 있으므로, native graphics driver나 vendor별 구현을 대신하는 보편적 계층으로 해석해서는 안 된다.
Backlight와 관련해 ACPI video driver는 세 가지 일을 한다. 사용자 공간이 밝기를 제어할 sysfs interface를 내보내고, hotkey event를 사용자 공간에 알리며, 특정 firmware notification 경로에서는 kernel 안에서 밝기를 직접 바꿀 수도 있다. 뒤의 각 절은 이 세 책임을 분리해 설명한다.
Display adapter extension이 제공하는 제어 범위를 정리한다.
같은 driver 안에서도 제어 interface, event 전달, 직접 변경은 별개다.
.. SPDX-License-Identifier: GPL-2.0
=====================
ACPI video extensions
=====================
This driver implement the ACPI Extensions For Display Adapters for
integrated graphics devices on motherboard, as specified in ACPI 2.0
Specification, Appendix B, allowing to perform some basic control like
defining the video POST device, retrieving EDID information or to
setup a video output, etc. Note that this is an ref. implementation
only. It may or may not work for your integrated video device.
The ACPI video driver does 3 things regarding backlight control.
사용자 공간용 backlight sysfs interface
16-41ACPI table에 video device가 있고 kernel command line에 `acpi_backlight=vendor`가 없으면 driver는 backlight device와 필요한 backlight operation structure를 등록한다. 등록된 class device마다 `/sys/class/backlight` 아래에 `acpi_videoX`라는 directory가 생긴다. `acpi_backlight=vendor`를 지정한 경우에는 vendor 경로를 선택하므로 이 ACPI 등록 조건이 성립하지 않는다.
Backlight sysfs의 표준 정의는 `Documentation/ABI/stable/sysfs-class-backlight`에 있다. ACPI video driver는 이 공통 ABI의 attribute를 firmware control method에 연결한다. 사용자는 ACPI method를 직접 호출하지 않고 표준 class interface를 읽고 쓴다.
`actual_brightness`를 읽으면 `_BQC`를 평가해 firmware가 현재라고 인식하는 밝기 level을 얻는다. `brightness`에 쓰면 `_BCM`이 요청한 level을 설정한다. `max_brightness`는 `_BCL` package에서 계산하며 `type`은 `firmware`다. `bl_power`는 구현되지 않았고 현재 brightness를 대신 설정한다는 것이 원문의 설명이다.
각 attribute의 값은 뒤에서 설명하는 `_BCL` index 체계를 따른다. 따라서 firmware의 raw 밝기 값과 sysfs에서 보이는 정수를 같은 값으로 가정해서는 안 된다.
표준 attribute와 ACPI firmware method의 연결을 보존한다.
ACPI class device가 생성되는 조건과 결과다.
Export a sysfs interface for user space to control backlight level
==================================================================
If the ACPI table has a video device, and acpi_backlight=vendor kernel
command line is not present, the driver will register a backlight device
and set the required backlight operation structure for it for the sysfs
interface control. For every registered class device, there will be a
directory named acpi_videoX under /sys/class/backlight.
The backlight sysfs interface has a standard definition here:
Documentation/ABI/stable/sysfs-class-backlight.
And what ACPI video driver does is:
actual_brightness:
on read, control method _BQC will be evaluated to
get the brightness level the firmware thinks it is at;
bl_power:
not implemented, will set the current brightness instead;
brightness:
on write, control method _BCM will run to set the requested brightness level;
max_brightness:
Derived from the _BCL package(see below);
type:
firmware
_BCL package와 index 기반 밝기
42-73ACPI video backlight driver는 `brightness`, `actual_brightness`, `max_brightness`에 firmware의 raw value가 아니라 index를 사용한다. 예제 `_BCL` method는 `Package (0x0C)`에 12개 값을 반환한다. 앞의 `0x64`와 `0x32`는 각각 laptop이 AC 전원과 battery에서 사용할 기본 level이지만 Linux는 현재 이 두 값을 사용하지 않는다.
나머지 10개 값 `0x0A`, `0x14`, `0x1E`, `0x28`, `0x32`, `0x3C`, `0x46`, `0x50`, `0x5A`, `0x64`가 선택 가능한 supported level이다. Driver는 이 목록의 위치를 밝기 level indicator로 노출한다.
따라서 적용 가능한 index는 `0`부터 `9`까지다. Index `0`은 raw brightness `0x0A`에, index `9`는 `0x64`에 대응한다. 사용자 공간에서 보이는 범위 역시 `0..9`이며 `max_brightness`는 `9`다. 예제에서 sysfs에 `0x64`나 100을 직접 쓰는 의미가 아니다.
이 index 규칙은 밝기 단계의 간격이 균일하다는 보장도 하지 않는다. Firmware가 `_BCL`에 나열한 지원 순서와 값을 driver가 index로 매핑한다는 계약만 제공한다.
12개 package element를 기본값 두 개와 선택 단계 열 개로 나눈다.
Raw firmware 값과 sysfs brightness index의 차이를 보여 준다.
Note that ACPI video backlight driver will always use index for
brightness, actual_brightness and max_brightness. So if we have
the following _BCL package::
Method (_BCL, 0, NotSerialized)
{
Return (Package (0x0C)
{
0x64,
0x32,
0x0A,
0x14,
0x1E,
0x28,
0x32,
0x3C,
0x46,
0x50,
0x5A,
0x64
})
}
The first two levels are for when laptop are on AC or on battery and are
not used by Linux currently. The remaining 10 levels are supported levels
that we can choose from. The applicable index values are from 0 (that
corresponds to the 0x0A brightness value) to 9 (that corresponds to the
0x64 brightness value) inclusive. Each of those index values is regarded
as a "brightness level" indicator. Thus from the user space perspective
the range of available brightness levels is from 0 to 9 (max_brightness)
inclusive.
Hotkey event를 사용자 공간에 전달하는 두 경로
74-110밝기 hotkey 보고에는 두 가지 일반적인 경로가 있다. 첫 번째는 keyboard driver 경로다. 사용자가 hotkey를 누르면 scancode가 생성되고 keyboard driver가 만든 input device를 통해 key type input event로 사용자 공간에 전달된다. 적절히 remap되면 `EV_KEY, KEY_BRIGHTNESSUP` 또는 `EV_KEY, KEY_BRIGHTNESSDOWN` 같은 keycode가 보인다.
첫 번째 경로에서는 ACPI video driver가 할 일이 없으며, 실제로 hotkey가 눌렸다는 사실조차 알지 못한다. Event의 생성과 전달 책임이 keyboard input stack에 있기 때문이다.
두 번째 경로에서는 hotkey가 scancode를 만들지 않는다. 대신 firmware가 video device의 ACPI node에 명세상 event value로 notify한다. ACPI video driver는 받은 값에 따라 key type input event를 생성하고 자신이 만든 input device로 사용자 공간에 전달한다. `0x86`은 `KEY_BRIGHTNESSUP`, `0x87`은 `KEY_BRIGHTNESSDOWN`에 대응한다.
두 번째 경로도 최종적으로는 첫 번째 경로와 같은 input keycode를 사용자 공간에 제공한다. 사용자 공간 도구는 이 event를 받은 뒤 앞 절의 sysfs interface를 통해 backlight level을 변경할 수 있다. Event 전달과 밝기 변경은 별도 단계다.
Scancode 유무와 event 생성 주체를 구분한다.
원문의 event table을 같은 값으로 구조화한다.
Notify user space about hotkey event
====================================
There are generally two cases for hotkey event reporting:
i) For some laptops, when user presses the hotkey, a scancode will be
generated and sent to user space through the input device created by
the keyboard driver as a key type input event, with proper remap, the
following key code will appear to user space::
EV_KEY, KEY_BRIGHTNESSUP
EV_KEY, KEY_BRIGHTNESSDOWN
etc.
For this case, ACPI video driver does not need to do anything(actually,
it doesn't even know this happened).
ii) For some laptops, the press of the hotkey will not generate the
scancode, instead, firmware will notify the video device ACPI node
about the event. The event value is defined in the ACPI spec. ACPI
video driver will generate an key type input event according to the
notify value it received and send the event to user space through the
input device it created:
===== ==================
event keycode
===== ==================
0x86 KEY_BRIGHTNESSUP
0x87 KEY_BRIGHTNESSDOWN
etc.
===== ==================
so this would lead to the same effect as case i) now.
Once user space tool receives this event, it can modify the backlight
level through the sysfs interface.
Kernel 내부의 직접 밝기 변경
111-121Kernel이 직접 backlight level을 바꾸는 동작은 앞 절의 case ii), 즉 firmware가 video device ACPI node에 notify하는 장비에 적용된다. Driver가 notification을 받으면 해당 event에 맞춰 밝기 level을 설정한다.
직접 변경 여부와 관계없이 input event는 항상 사용자 공간으로 전달된다. Video module이 밝기를 이미 조정했다고 해서 event 전송이 생략되지 않으므로, 사용자 공간 정책과 kernel 동작이 동시에 적용될 가능성을 고려해야 한다.
이 동작은 `brightness_switch_enabled` module parameter로 제어하며 자세한 정의는 `admin-guide/kernel-parameters.rst`에 있다. GUI environment가 시작되어 backlight level을 완전히 제어하려 한다면 kernel의 직접 변경 동작을 비활성화하는 것이 권장된다.
직접 brightness 변경과 event 전달이 독립적임을 나타낸다.
중복 밝기 변경을 피하기 위한 권장 설정 흐름이다.
Change backlight level in the kernel
====================================
This works for machines covered by case ii) in Section 2. Once the driver
received a notification, it will set the backlight level accordingly. This does
not affect the sending of event to user space, they are always sent to user
space regardless of whether or not the video module controls the backlight level
directly. This behaviour can be controlled through the brightness_switch_enabled
module parameter as documented in admin-guide/kernel-parameters.rst. It is
recommended to disable this behaviour once a GUI environment starts up and
wants to have full control of the backlight level.
요약·해설
video_extension.rst:1-121ACPI video driver는 integrated graphics용 display adapter extension의 reference implementation이다. Backlight 영역에서는 sysfs class device 등록, firmware hotkey notify의 input event 변환, 선택적인 kernel 직접 밝기 변경이라는 세 역할을 수행한다.
Sysfs의 `brightness` 계열 값은 `_BCL` raw value가 아니라 index다. 예제의 앞 두 package 값은 AC·battery 기본값으로 현재 Linux가 쓰지 않으며, 나머지 10개 값이 index `0..9`에 대응한다. `_BQC`는 현재 값 조회, `_BCM`은 요청 값 설정에 사용된다.
Hotkey는 keyboard scancode 경로와 ACPI notify 경로 중 하나로 보고될 수 있다. 두 경로 모두 사용자 공간에는 `KEY_BRIGHTNESSUP`·`KEY_BRIGHTNESSDOWN` event를 제공한다. GUI가 밝기를 전담하면 `brightness_switch_enabled`로 kernel의 직접 변경을 끄는 것이 권장된다.
Firmware method, input event, 사용자 공간 제어의 관계를 한 번에 본다.