Samsung Galaxy Book Driver | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

지원 범위

samsung-galaxybook.rst:1-50

ACPI ID 기반 probe와 모델별 feature detection을 설명합니다.

LED와 performance

samsung-galaxybook.rst:51-93

keyboard backlight와 Samsung mode의 platform profile mapping을 안내합니다.

Battery와 firmware

samsung-galaxybook.rst:94-143

charge end threshold와 firmware attribute 세 가지를 정리합니다.

Hotkey와 ACPI event

samsung-galaxybook.rst:144-174

Fn+F9/F10/F11 action과 ACPI netlink event를 설명합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0-or-later

3 ==========================

4 Samsung Galaxy Book Driver

5 ==========================

7 Joshua Grisham <josh@joshuagrisham.com>

9 This is a Linux x86 platform driver for Samsung Galaxy Book series notebook

10 devices which utilizes Samsung's ``SCAI`` ACPI device in order to control

11 extra features and receive various notifications.

13 Supported devices

14 =================

16 Any device with one of the supported ACPI device IDs should be supported. This

17 covers most of the "Samsung Galaxy Book" series notebooks that are currently

18 available as of this writing, and could include other Samsung notebook devices

19 as well.

21 Status

22 ======

24 The following features are currently supported:

26 - :ref:`Keyboard backlight <keyboard-backlight>` control

27 - :ref:`Performance mode <performance-mode>` control implemented using the

28 platform profile interface

29 - :ref:`Battery charge control end threshold

30 <battery-charge-control-end-threshold>` (stop charging battery at given

31 percentage value) implemented as a battery hook

32 - :ref:`Firmware Attributes <firmware-attributes>` to allow control of various

33 device settings

34 - :ref:`Handling of Fn hotkeys <keyboard-hotkey-actions>` for various actions

35 - :ref:`Handling of ACPI notifications and hotkeys

36 <acpi-notifications-and-hotkey-actions>`

38 Because different models of these devices can vary in their features, there is

39 logic built within the driver which attempts to test each implemented feature

40 for a valid response before enabling its support (registering additional devices

41 or extensions, adding sysfs attributes, etc). Therefore, it can be important to

42 note that not all features may be supported for your particular device.

44 The following features might be possible to implement but will require

45 additional investigation and are therefore not supported at this time:

47 - "Dolby Atmos" mode for the speakers

48 - "Outdoor Mode" for increasing screen brightness on models with ``SAM0427``

49 - "Silent Mode" on models with ``SAM0427``

51 .. _keyboard-backlight:

53 Keyboard backlight

54 ==================

56 A new LED class named ``samsung-galaxybook::kbd_backlight`` is created which

57 will then expose the device using the standard sysfs-based LED interface at

58 ``/sys/class/leds/samsung-galaxybook::kbd_backlight``. Brightness can be

59 controlled by writing the desired value to the ``brightness`` sysfs attribute or

60 with any other desired userspace utility.

62 .. note::

63 Most of these devices have an ambient light sensor which also turns

64 off the keyboard backlight under well-lit conditions. This behavior does not

65 seem possible to control at this time, but can be good to be aware of.

67 .. _performance-mode:

69 Performance mode

70 ================

72 This driver implements the

73 Documentation/userspace-api/sysfs-platform_profile.rst interface for working

74 with the "performance mode" function of the Samsung ACPI device.

76 Mapping of each Samsung "performance mode" to its respective platform profile is

77 performed dynamically by the driver, as not all models support all of the same

78 performance modes. Your device might have one or more of the following mappings:

80 - "Silent" maps to ``low-power``

81 - "Quiet" maps to ``quiet``

82 - "Optimized" maps to ``balanced``

83 - "High performance" maps to ``performance``

85 The result of the mapping can be printed in the kernel log when the module is

86 loaded. Supported profiles can also be retrieved from

87 ``/sys/firmware/acpi/platform_profile_choices``, while

88 ``/sys/firmware/acpi/platform_profile`` can be used to read or write the

89 currently selected profile.

91 The ``balanced`` platform profile will be set during module load if no profile

92 has been previously set.

94 .. _battery-charge-control-end-threshold:

96 Battery charge control end threshold

97 ====================================

99 This platform driver will add the ability to set the battery's charge control

100 end threshold, but does not have the ability to set a start threshold.

101

102 This feature is typically called "Battery Saver" by the various Samsung

103 applications in Windows, but in Linux we have implemented the standardized

104 "charge control threshold" sysfs interface on the battery device to allow for

105 controlling this functionality from the userspace.

106

107 The sysfs attribute

108 ``/sys/class/power_supply/BAT1/charge_control_end_threshold`` can be used to

109 read or set the desired charge end threshold.

110

111 If you wish to maintain interoperability with the Samsung Settings application

112 in Windows, then you should set the value to 100 to represent "off", or enable

113 the feature using only one of the following values: 50, 60, 70, 80, or 90.

114 Otherwise, the driver will accept any value between 1 and 100 as the percentage

115 that you wish the battery to stop charging at.

116

117 .. note::

118 Some devices have been observed as automatically "turning off" the charge

119 control end threshold if an input value of less than 30 is given.

120

121 .. _firmware-attributes:

122

123 Firmware Attributes

124 ===================

125

126 The following enumeration-typed firmware attributes are set up by this driver

127 and should be accessible under

128 ``/sys/class/firmware-attributes/samsung-galaxybook/attributes/`` if your device

129 supports them:

130

131 - ``power_on_lid_open`` (device should power on when the lid is opened)

132 - ``usb_charging`` (USB ports can deliver power to connected devices even when

133 the device is powered off or in a low sleep state)

134 - ``block_recording`` (blocks access to camera and microphone)

135

136 All of these attributes are simple boolean-like enumeration values which use 0

137 to represent "off" and 1 to represent "on". Use the ``current_value`` attribute

138 to get or change the setting on the device.

139

140 Note that when ``block_recording`` is updated, the input device "Samsung Galaxy

141 Book Lens Cover" will receive a ``SW_CAMERA_LENS_COVER`` switch event which

142 reflects the current state.

143

144 .. _keyboard-hotkey-actions:

145

146 Keyboard hotkey actions (i8042 filter)

147 ======================================

148

149 The i8042 filter will swallow the keyboard events for the Fn+F9 hotkey (Multi-

150 level keyboard backlight toggle) and Fn+F10 hotkey (Block recording toggle)

151 and instead execute their actions within the driver itself.

152

153 Fn+F9 will cycle through the brightness levels of the keyboard backlight. A

154 notification will be sent using ``led_classdev_notify_brightness_hw_changed``

155 so that the userspace can be aware of the change. This mimics the behavior of

156 other existing devices where the brightness level is cycled internally by the

157 embedded controller and then reported via a notification.

158

159 Fn+F10 will toggle the value of the "block recording" setting, which blocks

160 or allows usage of the built-in camera and microphone (and generates the same

161 Lens Cover switch event mentioned above).

162

163 .. _acpi-notifications-and-hotkey-actions:

164

165 ACPI notifications and hotkey actions

166 =====================================

167

168 ACPI notifications will generate ACPI netlink events under the device class

169 ``samsung-galaxybook`` and bus ID matching the Samsung ACPI device ID found on

170 your device. The events can be received using userspace tools such as

171 ``acpi_listen`` and ``acpid``.

172

173 The Fn+F11 Performance mode hotkey will be handled by the driver; each keypress

174 will cycle to the next available platform profile.

175

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Samsung Galaxy Book driver 개요

1-20

SPDX-License-Identifier: `GPL-2.0-or-later`

작성자: Joshua Grisham <josh@joshuagrisham.com>

이 Linux x86 platform driver는 Samsung Galaxy Book series notebook의 `SCAI` ACPI device를 사용하여 추가 기능을 제어하고 여러 notification을 받습니다.

지원하는 ACPI device ID 중 하나를 가진 device라면 지원되어야 합니다. 작성 시점에 판매되는 대부분의 Samsung Galaxy Book series notebook이 여기에 포함되며 다른 Samsung notebook도 포함될 수 있습니다.

지원 상태와 미지원 후보 기능

21-50

현재 지원 기능은 다음과 같습니다.

기능	구현 interface
Keyboard backlight 제어	standard LED class
Performance mode 제어	platform profile
Battery charge control end threshold	battery hook과 charge-control sysfs
Firmware Attributes	firmware-attributes class
Fn hotkey action	i8042 filter
ACPI notification·hotkey	ACPI netlink event

모델마다 기능이 다를 수 있으므로 driver는 각 기능을 enable하기 전에 유효한 응답을 test합니다. 응답이 유효할 때만 추가 device나 extension을 register하고 sysfs attribute를 추가합니다. 따라서 특정 device에서는 모든 기능이 지원되지 않을 수 있습니다.

speaker용 `Dolby Atmos` mode, `SAM0427` 모델의 screen brightness를 높이는 `Outdoor Mode`, 같은 모델의 `Silent Mode`는 구현 가능할 수 있지만 추가 조사가 필요해 현재 지원하지 않습니다.

Keyboard backlight

51-66

driver는 `samsung-galaxybook::kbd_backlight` LED class를 만들고 표준 sysfs LED interface인 `/sys/class/leds/samsung-galaxybook::kbd_backlight`에 device를 노출합니다. `brightness` sysfs attribute에 원하는 값을 쓰거나 다른 user-space utility를 사용하여 brightness를 제어할 수 있습니다.

참고: 대부분의 device에는 주변이 밝을 때 keyboard backlight를 끄는 ambient light sensor도 있습니다. 현재 이 동작은 제어할 수 없는 것으로 보이지만 운용할 때 알아 둘 필요가 있습니다.

Performance mode와 platform profile

67-93

driver는 Samsung ACPI device의 performance-mode 기능을 위해 `Documentation/userspace-api/sysfs-platform_profile.rst` interface를 구현합니다.

모든 모델이 같은 performance mode를 지원하지 않으므로 driver가 Samsung mode를 platform profile에 동적으로 mapping합니다.

Samsung performance mode	platform profile
Silent	low-power
Quiet	quiet
Optimized	balanced
High performance	performance

mapping 결과는 module load 때 kernel log에 출력할 수 있습니다. 지원 profile은 `/sys/firmware/acpi/platform_profile_choices`에서 읽고, 현재 선택한 profile은 `/sys/firmware/acpi/platform_profile`에서 읽거나 쓸 수 있습니다.

이전에 설정한 profile이 없다면 module load 때 `balanced` profile을 설정합니다.

Battery charge control end threshold

94-120

이 platform driver는 battery의 charge-control end threshold를 설정할 수 있게 하지만 start threshold는 설정할 수 없습니다.

Samsung Windows application에서는 보통 이 기능을 `Battery Saver`라 부릅니다. Linux에서는 battery device의 표준 `charge control threshold` sysfs interface로 구현했습니다.

`/sys/class/power_supply/BAT1/charge_control_end_threshold`에서 원하는 충전 종료 threshold를 읽거나 설정할 수 있습니다.

Windows의 Samsung Settings application과 호환성을 유지하려면 off를 뜻하는 100, 또는 기능을 enable하는 50·60·70·80·90 중 하나만 사용하십시오. 호환성이 필요하지 않다면 driver는 battery 충전을 멈출 percentage로 1부터 100 사이의 모든 값을 받습니다.

참고: 일부 device는 30보다 작은 값을 입력하면 charge-control end threshold를 자동으로 끄는 것으로 관찰되었습니다.

Firmware Attributes

121-143

device가 지원한다면 다음 enumeration type firmware attribute가 `/sys/class/firmware-attributes/samsung-galaxybook/attributes/` 아래에 만들어집니다.

attribute	동작
power_on_lid_open	lid를 열 때 device 전원을 켭니다.
usb_charging	device가 꺼져 있거나 낮은 sleep state일 때도 USB port가 연결 device에 전력을 공급합니다.
block_recording	camera와 microphone 접근을 차단합니다.

모든 attribute는 `0`이 off, `1`이 on인 단순 boolean형 enumeration입니다. `current_value` attribute로 device 설정을 읽거나 바꿉니다.

`block_recording`을 갱신하면 `Samsung Galaxy Book Lens Cover` input device가 현재 상태를 반영하는 `SW_CAMERA_LENS_COVER` switch event를 받습니다.

Keyboard hotkey action

144-162

i8042 filter는 Fn+F9(multi-level keyboard backlight toggle)과 Fn+F10(block recording toggle)의 keyboard event를 소비하고, 대신 driver 내부에서 action을 실행합니다.

Fn+F9는 keyboard backlight brightness level을 순환합니다. `led_classdev_notify_brightness_hw_changed`로 notification을 보내 user space가 변경을 알 수 있게 합니다. embedded controller가 내부적으로 brightness level을 순환한 뒤 notification으로 보고하는 다른 device의 동작을 모방합니다.

Fn+F10은 built-in camera와 microphone 사용을 차단하거나 허용하는 `block recording` 설정을 toggle하며, 앞서 설명한 Lens Cover switch event도 생성합니다.

ACPI notification과 Fn+F11

163-174

ACPI notification은 device class `samsung-galaxybook`과 해당 device에서 찾은 Samsung ACPI device ID와 일치하는 bus ID 아래에 ACPI netlink event를 생성합니다. `acpi_listen`이나 `acpid` 같은 user-space tool로 받을 수 있습니다.

driver는 Fn+F11 performance-mode hotkey를 처리하며 keypress마다 사용 가능한 다음 platform profile로 순환합니다.