Documentation/admin-guide/laptops/samsung-galaxybook.rst - linux - Git at Google

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

 ==========================
 Samsung Galaxy Book Driver
 ==========================

 Joshua Grisham <josh@joshuagrisham.com>

 This is a Linux x86 platform driver for Samsung Galaxy Book series notebook
 devices which utilizes Samsung's ``SCAI`` ACPI device in order to control
 extra features and receive various notifications.

 Supported devices
 =================

 Any device with one of the supported ACPI device IDs should be supported. This
 covers most of the "Samsung Galaxy Book" series notebooks that are currently
 available as of this writing, and could include other Samsung notebook devices
 as well.

 Status
 ======

 The following features are currently supported:

 - :ref:`Keyboard backlight <keyboard-backlight>` control
 - :ref:`Performance mode <performance-mode>` control implemented using the
   platform profile interface
 - :ref:`Battery charge control end threshold
   <battery-charge-control-end-threshold>` (stop charging battery at given
   percentage value) implemented as a battery hook
 - :ref:`Firmware Attributes <firmware-attributes>` to allow control of various
   device settings
 - :ref:`Handling of Fn hotkeys <keyboard-hotkey-actions>` for various actions
 - :ref:`Handling of ACPI notifications and hotkeys
   <acpi-notifications-and-hotkey-actions>`

 Because different models of these devices can vary in their features, there is
 logic built within the driver which attempts to test each implemented feature
 for a valid response before enabling its support (registering additional devices
 or extensions, adding sysfs attributes, etc). Therefore, it can be important to
 note that not all features may be supported for your particular device.

 The following features might be possible to implement but will require
 additional investigation and are therefore not supported at this time:

 - "Dolby Atmos" mode for the speakers
 - "Outdoor Mode" for increasing screen brightness on models with ``SAM0427``
 - "Silent Mode" on models with ``SAM0427``

 .. _keyboard-backlight:

 Keyboard backlight
 ==================

 A new LED class named ``samsung-galaxybook::kbd_backlight`` is created which
 will then expose the device using the standard sysfs-based LED interface at
 ``/sys/class/leds/samsung-galaxybook::kbd_backlight``. Brightness can be
 controlled by writing the desired value to the ``brightness`` sysfs attribute or
 with any other desired userspace utility.

 .. note::
   Most of these devices have an ambient light sensor which also turns
   off the keyboard backlight under well-lit conditions. This behavior does not
   seem possible to control at this time, but can be good to be aware of.

 .. _performance-mode:

 Performance mode
 ================

 This driver implements the
 Documentation/userspace-api/sysfs-platform_profile.rst interface for working
 with the "performance mode" function of the Samsung ACPI device.

 Mapping of each Samsung "performance mode" to its respective platform profile is
 performed dynamically by the driver, as not all models support all of the same
 performance modes. Your device might have one or more of the following mappings:

 - "Silent" maps to ``low-power``
 - "Quiet" maps to ``quiet``
 - "Optimized" maps to ``balanced``
 - "High performance" maps to ``performance``

 The result of the mapping can be printed in the kernel log when the module is
 loaded. Supported profiles can also be retrieved from
 ``/sys/firmware/acpi/platform_profile_choices``, while
 ``/sys/firmware/acpi/platform_profile`` can be used to read or write the
 currently selected profile.

 The ``balanced`` platform profile will be set during module load if no profile
 has been previously set.

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

 Battery charge control end threshold
 ====================================

 This platform driver will add the ability to set the battery's charge control
 end threshold, but does not have the ability to set a start threshold.

 This feature is typically called "Battery Saver" by the various Samsung
 applications in Windows, but in Linux we have implemented the standardized
 "charge control threshold" sysfs interface on the battery device to allow for
 controlling this functionality from the userspace.

 The sysfs attribute
 ``/sys/class/power_supply/BAT1/charge_control_end_threshold`` can be used to
 read or set the desired charge end threshold.

 If you wish to maintain interoperability with the Samsung Settings application
 in Windows, then you should set the value to 100 to represent "off", or enable
 the feature using only one of the following values: 50, 60, 70, 80, or 90.
 Otherwise, the driver will accept any value between 1 and 100 as the percentage
 that you wish the battery to stop charging at.

 .. note::
   Some devices have been observed as automatically "turning off" the charge
   control end threshold if an input value of less than 30 is given.

 .. _firmware-attributes:

 Firmware Attributes
 ===================

 The following enumeration-typed firmware attributes are set up by this driver
 and should be accessible under
 ``/sys/class/firmware-attributes/samsung-galaxybook/attributes/`` if your device
 supports them:

 - ``power_on_lid_open`` (device should power on when the lid is opened)
 - ``usb_charging``  (USB ports can deliver power to connected devices even when
   the device is powered off or in a low sleep state)
 - ``block_recording`` (blocks access to camera and microphone)

 All of these attributes are simple boolean-like enumeration values which use 0
 to represent "off" and 1 to represent "on". Use the ``current_value`` attribute
 to get or change the setting on the device.

 Note that when ``block_recording`` is updated, the input device "Samsung Galaxy
 Book Lens Cover" will receive a ``SW_CAMERA_LENS_COVER`` switch event which
 reflects the current state.

 .. _keyboard-hotkey-actions:

 Keyboard hotkey actions (i8042 filter)
 ======================================

 The i8042 filter will swallow the keyboard events for the Fn+F9 hotkey (Multi-
 level keyboard backlight toggle) and Fn+F10 hotkey (Block recording toggle)
 and instead execute their actions within the driver itself.

 Fn+F9 will cycle through the brightness levels of the keyboard backlight. A
 notification will be sent using ``led_classdev_notify_brightness_hw_changed``
 so that the userspace can be aware of the change. This mimics the behavior of
 other existing devices where the brightness level is cycled internally by the
 embedded controller and then reported via a notification.

 Fn+F10 will toggle the value of the "block recording" setting, which blocks
 or allows usage of the built-in camera and microphone (and generates the same
 Lens Cover switch event mentioned above).

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

 ACPI notifications and hotkey actions
 =====================================

 ACPI notifications will generate ACPI netlink events under the device class
 ``samsung-galaxybook`` and bus ID matching the Samsung ACPI device ID found on
 your device. The events can be received using userspace tools such as
 ``acpi_listen`` and ``acpid``.

 The Fn+F11 Performance mode hotkey will be handled by the driver; each keypress
 will cycle to the next available platform profile.
	.. SPDX-License-Identifier: GPL-2.0-or-later

	==========================
	Samsung Galaxy Book Driver
	==========================

	Joshua Grisham <josh@joshuagrisham.com>

	This is a Linux x86 platform driver for Samsung Galaxy Book series notebook
	devices which utilizes Samsung's ``SCAI`` ACPI device in order to control
	extra features and receive various notifications.

	Supported devices
	=================

	Any device with one of the supported ACPI device IDs should be supported. This
	covers most of the "Samsung Galaxy Book" series notebooks that are currently
	available as of this writing, and could include other Samsung notebook devices
	as well.

	Status
	======

	The following features are currently supported:

	- :ref:`Keyboard backlight <keyboard-backlight>` control
	- :ref:`Performance mode <performance-mode>` control implemented using the
	platform profile interface
	- :ref:`Battery charge control end threshold
	<battery-charge-control-end-threshold>` (stop charging battery at given
	percentage value) implemented as a battery hook
	- :ref:`Firmware Attributes <firmware-attributes>` to allow control of various
	device settings
	- :ref:`Handling of Fn hotkeys <keyboard-hotkey-actions>` for various actions
	- :ref:`Handling of ACPI notifications and hotkeys
	<acpi-notifications-and-hotkey-actions>`

	Because different models of these devices can vary in their features, there is
	logic built within the driver which attempts to test each implemented feature
	for a valid response before enabling its support (registering additional devices
	or extensions, adding sysfs attributes, etc). Therefore, it can be important to
	note that not all features may be supported for your particular device.

	The following features might be possible to implement but will require
	additional investigation and are therefore not supported at this time:

	- "Dolby Atmos" mode for the speakers
	- "Outdoor Mode" for increasing screen brightness on models with ``SAM0427``
	- "Silent Mode" on models with ``SAM0427``

	.. _keyboard-backlight:

	Keyboard backlight
	==================

	A new LED class named ``samsung-galaxybook::kbd_backlight`` is created which
	will then expose the device using the standard sysfs-based LED interface at
	``/sys/class/leds/samsung-galaxybook::kbd_backlight``. Brightness can be
	controlled by writing the desired value to the ``brightness`` sysfs attribute or
	with any other desired userspace utility.

	.. note::
	Most of these devices have an ambient light sensor which also turns
	off the keyboard backlight under well-lit conditions. This behavior does not
	seem possible to control at this time, but can be good to be aware of.

	.. _performance-mode:

	Performance mode
	================

	This driver implements the
	Documentation/userspace-api/sysfs-platform_profile.rst interface for working
	with the "performance mode" function of the Samsung ACPI device.

	Mapping of each Samsung "performance mode" to its respective platform profile is
	performed dynamically by the driver, as not all models support all of the same
	performance modes. Your device might have one or more of the following mappings:

	- "Silent" maps to ``low-power``
	- "Quiet" maps to ``quiet``
	- "Optimized" maps to ``balanced``
	- "High performance" maps to ``performance``

	The result of the mapping can be printed in the kernel log when the module is
	loaded. Supported profiles can also be retrieved from
	``/sys/firmware/acpi/platform_profile_choices``, while
	``/sys/firmware/acpi/platform_profile`` can be used to read or write the
	currently selected profile.

	The ``balanced`` platform profile will be set during module load if no profile
	has been previously set.

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

	Battery charge control end threshold
	====================================

	This platform driver will add the ability to set the battery's charge control
	end threshold, but does not have the ability to set a start threshold.

	This feature is typically called "Battery Saver" by the various Samsung
	applications in Windows, but in Linux we have implemented the standardized
	"charge control threshold" sysfs interface on the battery device to allow for
	controlling this functionality from the userspace.

	The sysfs attribute
	``/sys/class/power_supply/BAT1/charge_control_end_threshold`` can be used to
	read or set the desired charge end threshold.

	If you wish to maintain interoperability with the Samsung Settings application
	in Windows, then you should set the value to 100 to represent "off", or enable
	the feature using only one of the following values: 50, 60, 70, 80, or 90.
	Otherwise, the driver will accept any value between 1 and 100 as the percentage
	that you wish the battery to stop charging at.

	.. note::
	Some devices have been observed as automatically "turning off" the charge
	control end threshold if an input value of less than 30 is given.

	.. _firmware-attributes:

	Firmware Attributes
	===================

	The following enumeration-typed firmware attributes are set up by this driver
	and should be accessible under
	``/sys/class/firmware-attributes/samsung-galaxybook/attributes/`` if your device
	supports them:

	- ``power_on_lid_open`` (device should power on when the lid is opened)
	- ``usb_charging`` (USB ports can deliver power to connected devices even when
	the device is powered off or in a low sleep state)
	- ``block_recording`` (blocks access to camera and microphone)

	All of these attributes are simple boolean-like enumeration values which use 0
	to represent "off" and 1 to represent "on". Use the ``current_value`` attribute
	to get or change the setting on the device.

	Note that when ``block_recording`` is updated, the input device "Samsung Galaxy
	Book Lens Cover" will receive a ``SW_CAMERA_LENS_COVER`` switch event which
	reflects the current state.

	.. _keyboard-hotkey-actions:

	Keyboard hotkey actions (i8042 filter)
	======================================

	The i8042 filter will swallow the keyboard events for the Fn+F9 hotkey (Multi-
	level keyboard backlight toggle) and Fn+F10 hotkey (Block recording toggle)
	and instead execute their actions within the driver itself.

	Fn+F9 will cycle through the brightness levels of the keyboard backlight. A
	notification will be sent using ``led_classdev_notify_brightness_hw_changed``
	so that the userspace can be aware of the change. This mimics the behavior of
	other existing devices where the brightness level is cycled internally by the
	embedded controller and then reported via a notification.

	Fn+F10 will toggle the value of the "block recording" setting, which blocks
	or allows usage of the built-in camera and microphone (and generates the same
	Lens Cover switch event mentioned above).

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

	ACPI notifications and hotkey actions
	=====================================

	ACPI notifications will generate ACPI netlink events under the device class
	``samsung-galaxybook`` and bus ID matching the Samsung ACPI device ID found on
	your device. The events can be received using userspace tools such as
	``acpi_listen`` and ``acpid``.

	The Fn+F11 Performance mode hotkey will be handled by the driver; each keypress
	will cycle to the next available platform profile.