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