samsung-galaxybook.rst

  1.. SPDX-License-Identifier: GPL-2.0-or-later
  2
  3==========================
  4Samsung Galaxy Book Driver
  5==========================
  6
  7Joshua Grisham <josh@joshuagrisham.com>
  8
  9This is a Linux x86 platform driver for Samsung Galaxy Book series notebook
 10devices which utilizes Samsung's ``SCAI`` ACPI device in order to control
 11extra features and receive various notifications.
 12
 13Supported devices
 14=================
 15
 16Any device with one of the supported ACPI device IDs should be supported. This
 17covers most of the "Samsung Galaxy Book" series notebooks that are currently
 18available as of this writing, and could include other Samsung notebook devices
 19as well.
 20
 21Status
 22======
 23
 24The following features are currently supported:
 25
 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>`
 37
 38Because different models of these devices can vary in their features, there is
 39logic built within the driver which attempts to test each implemented feature
 40for a valid response before enabling its support (registering additional devices
 41or extensions, adding sysfs attributes, etc). Therefore, it can be important to
 42note that not all features may be supported for your particular device.
 43
 44The following features might be possible to implement but will require
 45additional investigation and are therefore not supported at this time:
 46
 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``
 50
 51.. _keyboard-backlight:
 52
 53Keyboard backlight
 54==================
 55
 56A new LED class named ``samsung-galaxybook::kbd_backlight`` is created which
 57will then expose the device using the standard sysfs-based LED interface at
 58``/sys/class/leds/samsung-galaxybook::kbd_backlight``. Brightness can be
 59controlled by writing the desired value to the ``brightness`` sysfs attribute or
 60with any other desired userspace utility.
 61
 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.
 66
 67.. _performance-mode:
 68
 69Performance mode
 70================
 71
 72This driver implements the
 73Documentation/userspace-api/sysfs-platform_profile.rst interface for working
 74with the "performance mode" function of the Samsung ACPI device.
 75
 76Mapping of each Samsung "performance mode" to its respective platform profile is
 77performed dynamically by the driver, as not all models support all of the same
 78performance modes. Your device might have one or more of the following mappings:
 79
 80- "Silent" maps to ``low-power``
 81- "Quiet" maps to ``quiet``
 82- "Optimized" maps to ``balanced``
 83- "High performance" maps to ``performance``
 84
 85The result of the mapping can be printed in the kernel log when the module is
 86loaded. 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
 89currently selected profile.
 90
 91The ``balanced`` platform profile will be set during module load if no profile
 92has been previously set.
 93
 94.. _battery-charge-control-end-threshold:
 95
 96Battery charge control end threshold
 97====================================
 98
 99This platform driver will add the ability to set the battery's charge control
100end threshold, but does not have the ability to set a start threshold.
101
102This feature is typically called "Battery Saver" by the various Samsung
103applications in Windows, but in Linux we have implemented the standardized
104"charge control threshold" sysfs interface on the battery device to allow for
105controlling this functionality from the userspace.
106
107The sysfs attribute
108``/sys/class/power_supply/BAT1/charge_control_end_threshold`` can be used to
109read or set the desired charge end threshold.
110
111If you wish to maintain interoperability with the Samsung Settings application
112in Windows, then you should set the value to 100 to represent "off", or enable
113the feature using only one of the following values: 50, 60, 70, 80, or 90.
114Otherwise, the driver will accept any value between 1 and 100 as the percentage
115that 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
123Firmware Attributes
124===================
125
126The following enumeration-typed firmware attributes are set up by this driver
127and should be accessible under
128``/sys/class/firmware-attributes/samsung-galaxybook/attributes/`` if your device
129supports 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
136All of these attributes are simple boolean-like enumeration values which use 0
137to represent "off" and 1 to represent "on". Use the ``current_value`` attribute
138to get or change the setting on the device.
139
140Note that when ``block_recording`` is updated, the input device "Samsung Galaxy
141Book Lens Cover" will receive a ``SW_CAMERA_LENS_COVER`` switch event which
142reflects the current state.
143
144.. _keyboard-hotkey-actions:
145
146Keyboard hotkey actions (i8042 filter)
147======================================
148
149The i8042 filter will swallow the keyboard events for the Fn+F9 hotkey (Multi-
150level keyboard backlight toggle) and Fn+F10 hotkey (Block recording toggle)
151and instead execute their actions within the driver itself.
152
153Fn+F9 will cycle through the brightness levels of the keyboard backlight. A
154notification will be sent using ``led_classdev_notify_brightness_hw_changed``
155so that the userspace can be aware of the change. This mimics the behavior of
156other existing devices where the brightness level is cycled internally by the
157embedded controller and then reported via a notification.
158
159Fn+F10 will toggle the value of the "block recording" setting, which blocks
160or allows usage of the built-in camera and microphone (and generates the same
161Lens Cover switch event mentioned above).
162
163.. _acpi-notifications-and-hotkey-actions:
164
165ACPI notifications and hotkey actions
166=====================================
167
168ACPI notifications will generate ACPI netlink events under the device class
169``samsung-galaxybook`` and bus ID matching the Samsung ACPI device ID found on
170your device. The events can be received using userspace tools such as
171``acpi_listen`` and ``acpid``.
172
173The Fn+F11 Performance mode hotkey will be handled by the driver; each keypress
174will cycle to the next available platform profile.