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. 175