|
| 1 | +.. SPDX-License-Identifier: GPL-2.0-or-later |
| 2 | +
|
| 3 | +========================== |
| 4 | +Samsung Galaxy Book Driver |
| 5 | +========================== |
| 6 | + |
| 7 | +Joshua Grisham <josh@joshuagrisham.com> |
| 8 | + |
| 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. |
| 12 | + |
| 13 | +Supported devices |
| 14 | +================= |
| 15 | + |
| 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. |
| 20 | + |
| 21 | +Status |
| 22 | +====== |
| 23 | + |
| 24 | +The 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 | + |
| 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. |
| 43 | + |
| 44 | +The following features might be possible to implement but will require |
| 45 | +additional 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 | + |
| 53 | +Keyboard backlight |
| 54 | +================== |
| 55 | + |
| 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. |
| 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 | + |
| 69 | +Performance mode |
| 70 | +================ |
| 71 | + |
| 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. |
| 75 | + |
| 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: |
| 79 | + |
| 80 | +- "Silent" maps to ``low-power`` |
| 81 | +- "Quiet" maps to ``quiet`` |
| 82 | +- "Optimized" maps to ``balanced`` |
| 83 | +- "High performance" maps to ``performance`` |
| 84 | + |
| 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. |
| 90 | + |
| 91 | +The ``balanced`` platform profile will be set during module load if no profile |
| 92 | +has been previously set. |
| 93 | + |
| 94 | +.. _battery-charge-control-end-threshold: |
| 95 | + |
| 96 | +Battery charge control end threshold |
| 97 | +==================================== |
| 98 | + |
| 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. |
0 commit comments