235 lines
9.7 KiB
Plaintext
Raw Normal View History

# SPDX-License-Identifier: GPL-2.0-only
#
# Microsoft Surface Platform-Specific Drivers
#
menuconfig SURFACE_PLATFORMS
bool "Microsoft Surface Platform-Specific Device Drivers"
depends on ARM64 || X86 || COMPILE_TEST
default y
help
Say Y here to get to see options for platform-specific device drivers
for Microsoft Surface devices. This option alone does not add any
kernel code.
If you say N, all options in this submenu will be skipped and disabled.
if SURFACE_PLATFORMS
config SURFACE3_WMI
tristate "Surface 3 WMI Driver"
depends on ACPI_WMI
depends on DMI
depends on INPUT
depends on SPI
help
Say Y here if you have a Surface 3.
To compile this driver as a module, choose M here: the module will
be called surface3-wmi.
config SURFACE_3_POWER_OPREGION
tristate "Surface 3 battery platform operation region support"
depends on ACPI
depends on I2C
help
This driver provides support for ACPI operation
region of the Surface 3 battery platform driver.
platform/surface: Add Surface ACPI Notify driver The Surface ACPI Notify (SAN) device provides an ACPI interface to the Surface Aggregator EC, specifically the Surface Serial Hub interface. This interface allows EC requests to be made from ACPI code and can convert a subset of EC events back to ACPI notifications. Specifically, this interface provides a GenericSerialBus operation region ACPI code can execute a request by writing the request command data and payload to this operation region and reading back the corresponding response via a write-then-read operation. Furthermore, this interface provides a _DSM method to be called when certain events from the EC have been received, essentially turning them into ACPI notifications. The driver provided in this commit essentially takes care of translating the request data written to the operation region, executing the request, waiting for it to finish, and finally writing and translating back the response (if the request has one). Furthermore, this driver takes care of enabling the events handled via ACPI _DSM calls. Lastly, this driver also exposes an interface providing discrete GPU (dGPU) power-on notifications on the Surface Book 2, which are also received via the operation region interface (but not handled by the SAN driver directly), making them accessible to other drivers (such as a dGPU hot-plug driver that may be added later on). On 5th and 6th generation Surface devices (Surface Pro 5/2017, Pro 6, Book 2, Laptop 1 and 2), the SAN interface provides full battery and thermal subsystem access, as well as other EC based functionality. On those models, battery and thermal sensor devices are implemented as standard ACPI devices of that type, however, forward ACPI calls to the corresponding Surface Aggregator EC request via the SAN interface and receive corresponding notifications (e.g. battery information change) from it. This interface is therefore required to provide said functionality on those devices. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Reviewed-by: Hans de Goede <hdegoede@redhat.com> Link: https://lore.kernel.org/r/20201221183959.1186143-10-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2020-12-21 19:39:59 +01:00
config SURFACE_ACPI_NOTIFY
tristate "Surface ACPI Notify Driver"
depends on SURFACE_AGGREGATOR
help
Surface ACPI Notify (SAN) driver for Microsoft Surface devices.
This driver provides support for the ACPI interface (called SAN) of
the Surface System Aggregator Module (SSAM) EC. This interface is used
on 5th- and 6th-generation Microsoft Surface devices (including
Surface Pro 5 and 6, Surface Book 2, Surface Laptops 1 and 2, and in
reduced functionality on the Surface Laptop 3) to execute SSAM
requests directly from ACPI code, as well as receive SSAM events and
turn them into ACPI notifications. It essentially acts as a
translation layer between the SSAM controller and ACPI.
Specifically, this driver may be needed for battery status reporting,
thermal sensor access, and real-time clock information, depending on
the Surface device in question.
config SURFACE_AGGREGATOR_CDEV
tristate "Surface System Aggregator Module User-Space Interface"
depends on SURFACE_AGGREGATOR
help
Provides a misc-device interface to the Surface System Aggregator
Module (SSAM) controller.
This option provides a module (called surface_aggregator_cdev), that,
when loaded, will add a client device (and its respective driver) to
the SSAM controller. Said client device manages a misc-device
interface (/dev/surface/aggregator), which can be used by user-space
tools to directly communicate with the SSAM EC by sending requests and
receiving the corresponding responses.
The provided interface is intended for debugging and development only,
and should not be used otherwise.
config SURFACE_AGGREGATOR_HUB
tristate "Surface System Aggregator Module Subsystem Device Hubs"
depends on SURFACE_AGGREGATOR
depends on SURFACE_AGGREGATOR_BUS
help
Device-hub drivers for Surface System Aggregator Module (SSAM) subsystem
devices.
Provides subsystem hub drivers which manage client devices on various
SSAM subsystems. In some subsystems, notably the BAS subsystem managing
devices contained in the base of the Surface Book 3 and the KIP subsystem
managing type-cover devices in the Surface Pro 8 and Surface Pro X,
devices can be (hot-)removed. Hub devices and drivers are required to
manage these subdevices.
Devices managed via these hubs are:
- Battery/AC devices (Surface Book 3).
- HID input devices (7th-generation and later models with detachable
input devices).
Select M (recommended) or Y here if you want support for the above
mentioned devices on the corresponding Surface models. Without this
module, the respective devices mentioned above will not be instantiated
and thus any functionality provided by them will be missing, even when
drivers for these devices are present. This module only provides the
respective subsystem hubs. Both drivers and device specification (e.g.
via the Surface Aggregator Registry) for these devices still need to be
selected via other options.
platform/surface: Set up Surface Aggregator device registry The Surface System Aggregator Module (SSAM) subsystem provides various functionalities, which are separated by spreading them across multiple devices and corresponding drivers. Parts of that functionality / some of those devices, however, can (as far as we currently know) not be auto-detected by conventional means. While older (specifically 5th- and 6th-)generation models do advertise most of their functionality via standard platform devices in ACPI, newer generations do not. As we are currently also not aware of any feasible way to query said functionalities dynamically, this poses a problem. There is, however, a device in ACPI that seems to be used by Windows for identifying different Surface models: The Windows Surface Integration Device (WSID). This device seems to have a HID corresponding to the overall set of functionalities SSAM provides for the associated model. This commit introduces a registry providing non-detectable device information via software nodes. In addition, a SSAM platform hub driver is introduced, which takes care of creating and managing the SSAM devices specified in this registry. This approach allows for a hierarchical setup akin to ACPI and is easily extendable, e.g. via firmware node properties. Note that this commit only provides the basis for the platform hub and registry, and does not add any content to it. The registry will be expanded in subsequent commits. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Link: https://lore.kernel.org/r/20210212115439.1525216-2-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2021-02-12 12:54:34 +01:00
config SURFACE_AGGREGATOR_REGISTRY
tristate "Surface System Aggregator Module Device Registry"
depends on SURFACE_AGGREGATOR
depends on SURFACE_AGGREGATOR_BUS
help
Device-registry for Surface System Aggregator Module (SSAM) devices.
platform/surface: Set up Surface Aggregator device registry The Surface System Aggregator Module (SSAM) subsystem provides various functionalities, which are separated by spreading them across multiple devices and corresponding drivers. Parts of that functionality / some of those devices, however, can (as far as we currently know) not be auto-detected by conventional means. While older (specifically 5th- and 6th-)generation models do advertise most of their functionality via standard platform devices in ACPI, newer generations do not. As we are currently also not aware of any feasible way to query said functionalities dynamically, this poses a problem. There is, however, a device in ACPI that seems to be used by Windows for identifying different Surface models: The Windows Surface Integration Device (WSID). This device seems to have a HID corresponding to the overall set of functionalities SSAM provides for the associated model. This commit introduces a registry providing non-detectable device information via software nodes. In addition, a SSAM platform hub driver is introduced, which takes care of creating and managing the SSAM devices specified in this registry. This approach allows for a hierarchical setup akin to ACPI and is easily extendable, e.g. via firmware node properties. Note that this commit only provides the basis for the platform hub and registry, and does not add any content to it. The registry will be expanded in subsequent commits. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Link: https://lore.kernel.org/r/20210212115439.1525216-2-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2021-02-12 12:54:34 +01:00
Provides a module and driver which act as a device-registry for SSAM
client devices that cannot be detected automatically, e.g. via ACPI.
Such devices are instead provided and managed via this registry.
platform/surface: Set up Surface Aggregator device registry The Surface System Aggregator Module (SSAM) subsystem provides various functionalities, which are separated by spreading them across multiple devices and corresponding drivers. Parts of that functionality / some of those devices, however, can (as far as we currently know) not be auto-detected by conventional means. While older (specifically 5th- and 6th-)generation models do advertise most of their functionality via standard platform devices in ACPI, newer generations do not. As we are currently also not aware of any feasible way to query said functionalities dynamically, this poses a problem. There is, however, a device in ACPI that seems to be used by Windows for identifying different Surface models: The Windows Surface Integration Device (WSID). This device seems to have a HID corresponding to the overall set of functionalities SSAM provides for the associated model. This commit introduces a registry providing non-detectable device information via software nodes. In addition, a SSAM platform hub driver is introduced, which takes care of creating and managing the SSAM devices specified in this registry. This approach allows for a hierarchical setup akin to ACPI and is easily extendable, e.g. via firmware node properties. Note that this commit only provides the basis for the platform hub and registry, and does not add any content to it. The registry will be expanded in subsequent commits. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Link: https://lore.kernel.org/r/20210212115439.1525216-2-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2021-02-12 12:54:34 +01:00
Devices provided via this registry are:
- Platform profile (performance-/cooling-mode) device (5th- and later
generations).
- Battery/AC devices (7th-generation).
- HID input devices (7th-generation).
Select M (recommended) or Y here if you want support for the above
mentioned devices on the corresponding Surface models. Without this
module, the respective devices will not be instantiated and thus any
functionality provided by them will be missing, even when drivers for
these devices are present. In other words, this module only provides
the respective client devices. Drivers for these devices still need to
be selected via the other options.
platform/surface: Add KIP/POS tablet-mode switch driver Add a driver providing a tablet-mode switch input device for Microsoft Surface devices using the Surface Aggregator KIP subsystem (to manage detachable peripherals) or POS subsystem (to obtain device posture information). The KIP (full name unknown, abbreviation found through reverse engineering) subsystem is used on the Surface Pro 8 and Surface Pro X to manage the keyboard cover. Among other things, it provides information on the positioning (posture) of the cover (closed, laptop-style, detached, folded-back, ...), which can be used to implement an input device providing the SW_TABLET_MODE event. Similarly, the POS (posture information) subsystem provides such information on the Surface Laptop Studio, with the difference being that the keyboard is not detachable. As implementing the tablet-mode switch for both subsystems is largely similar, the driver proposed in this commit, in large, acts as a generic tablet mode switch driver framework for the Surface Aggregator Module. Specific implementations using this framework are provided for the KIP and POS subsystems, adding tablet-mode switch support to the aforementioned devices. A few more notes on the Surface Laptop Studio: A peculiarity of the Surface Laptop Studio is its "slate/tent" mode (symbolized: user> _/\). In this mode, the screen covers the keyboard but leaves the touchpad exposed. This is essentially a mode in-between tablet and laptop, and it is debatable whether tablet-mode should be enabled in this mode. We therefore let the user decide this via a module parameter. In particular, tablet-mode may bring up the on-screen touch keyboard more easily, which would be desirable in this mode. However, some user-space software currently also decides to disable keyboard and, more importantly, touchpad input, while the touchpad is still accessible in the "slate/tent" mode. Furthermore, this mode shares its identifier with "slate/flipped" mode where the screen is flipped 180° and the keyboard points away from the user (symbolized: user> /_). In this mode we would like to enable auto-rotation, something that user-space software may only do when tablet-mode is enabled. We therefore default to the slate-mode enabling the tablet-mode switch. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Link: https://lore.kernel.org/r/20220624183642.910893-3-luzmaximilian@gmail.com Reviewed-by: Hans de Goede <hdegoede@redhat.com> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2022-06-24 20:36:40 +02:00
config SURFACE_AGGREGATOR_TABLET_SWITCH
tristate "Surface Aggregator Generic Tablet-Mode Switch Driver"
depends on SURFACE_AGGREGATOR
depends on SURFACE_AGGREGATOR_BUS
depends on INPUT
help
Provides a tablet-mode switch input device on Microsoft Surface models
using the KIP subsystem for detachable keyboards (e.g. keyboard covers)
or the POS subsystem for device/screen posture changes.
The KIP subsystem is used on newer Surface generations to handle
detachable input peripherals, specifically the keyboard cover (containing
keyboard and touchpad) on the Surface Pro 8 and Surface Pro X. The POS
subsystem is used for device posture change notifications on the Surface
Laptop Studio. This module provides a driver to let user-space know when
the device should be considered in tablet-mode due to the keyboard cover
being detached or folded back (essentially signaling when the keyboard is
not available for input). It does so by creating a tablet-mode switch
input device, sending the standard SW_TABLET_MODE event on mode change.
Select M or Y here, if you want to provide tablet-mode switch input
events on the Surface Pro 8, Surface Pro X, and Surface Laptop Studio.
platform/surface: Add DTX driver The Microsoft Surface Book series devices consist of a so-called clipboard part (containing the CPU, touchscreen, and primary battery) and a base part (containing keyboard, secondary battery, and optional discrete GPU). These parts can be separated, i.e. the clipboard can be detached and used as tablet. This detachment process is initiated by pressing a button. On the Surface Book 2 and 3 (targeted with this commit), the Surface Aggregator Module (i.e. the embedded controller on those devices) attempts to send a notification to any listening client driver and waits for further instructions (i.e. whether the detachment process should continue or be aborted). If it does not receive a response in a certain time-frame, the detachment process (by default) continues and the clipboard can be physically separated. In other words, (by default and) without a driver, the detachment process takes about 10 seconds to complete. This commit introduces a driver for this detachment system (called DTX). This driver allows a user-space daemon to control and influence the detachment behavior. Specifically, it forwards any detachment requests to user-space, allows user-space to make such requests itself, and allows handling of those requests. Requests can be handled by either aborting, continuing/allowing, or delaying (i.e. resetting the timeout via a heartbeat commend). The user-space API is implemented via the /dev/surface/dtx miscdevice. In addition, user-space can change the default behavior on timeout from allowing detachment to disallowing it, which is useful if the (optional) discrete GPU is in use. Furthermore, this driver allows user-space to receive notifications about the state of the base, specifically when it is physically removed (as opposed to detachment requested), in what manner it is connected (i.e. in reverse-/tent-/studio- or laptop-mode), and what type of base is connected. Based on this information, the driver also provides a simple tablet-mode switch (aliasing all modes without keyboard access, i.e. tablet-mode and studio-mode to its reported tablet-mode). An implementation of such a user-space daemon, allowing configuration of detachment behavior via scripts (e.g. safely unmounting USB devices connected to the base before continuing) can be found at [1]. [1]: https://github.com/linux-surface/surface-dtx-daemon Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Link: https://lore.kernel.org/r/20210308184819.437438-2-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2021-03-08 19:48:17 +01:00
config SURFACE_DTX
tristate "Surface DTX (Detachment System) Driver"
depends on SURFACE_AGGREGATOR
depends on INPUT
help
Driver for the Surface Book clipboard detachment system (DTX).
On the Surface Book series devices, the display part containing the
CPU (called the clipboard) can be detached from the base (containing a
battery, the keyboard, and, optionally, a discrete GPU) by (if
necessary) unlocking and opening the latch connecting both parts.
This driver provides a user-space interface that can influence the
behavior of this process, which includes the option to abort it in
case the base is still in use or speed it up in case it is not.
Note that this module can be built without support for the Surface
Aggregator Bus (i.e. CONFIG_SURFACE_AGGREGATOR_BUS=n). In that case,
some devices, specifically the Surface Book 3, will not be supported.
config SURFACE_GPE
tristate "Surface GPE/Lid Support Driver"
depends on ACPI
depends on DMI
help
This driver marks the GPEs related to the ACPI lid device found on
Microsoft Surface devices as wakeup sources and prepares them
accordingly. It is required on those devices to allow wake-ups from
suspend by opening the lid.
config SURFACE_HOTPLUG
tristate "Surface Hot-Plug Driver"
depends on ACPI
depends on GPIOLIB
help
Driver for out-of-band hot-plug event signaling on Microsoft Surface
devices with hot-pluggable PCIe cards.
This driver is used on Surface Book (2 and 3) devices with a
hot-pluggable discrete GPU (dGPU). When not in use, the dGPU on those
devices can enter D3cold, which prevents in-band (standard) PCIe
hot-plug signaling. Thus, without this driver, detaching the base
containing the dGPU will not correctly update the state of the
corresponding PCIe device if it is in D3cold. This driver adds support
for out-of-band hot-plug notifications, ensuring that the device state
is properly updated even when the device in question is in D3cold.
Select M or Y here, if you want to (fully) support hot-plugging of
dGPU devices on the Surface Book 2 and/or 3 during D3cold.
config SURFACE_PLATFORM_PROFILE
tristate "Surface Platform Profile Driver"
depends on ACPI
depends on SURFACE_AGGREGATOR_REGISTRY
select ACPI_PLATFORM_PROFILE
help
Provides support for the ACPI platform profile on 5th- and later
generation Microsoft Surface devices.
More specifically, this driver provides ACPI platform profile support
on Microsoft Surface devices with a Surface System Aggregator Module
(SSAM) connected via the Surface Serial Hub (SSH / SAM-over-SSH). In
other words, this driver provides platform profile support on the
Surface Pro 5, Surface Book 2, Surface Laptop, Surface Laptop Go and
later. On those devices, the platform profile can significantly
influence cooling behavior, e.g. setting it to 'quiet' (default) or
'low-power' can significantly limit performance of the discrete GPU on
Surface Books, while in turn leading to lower power consumption and/or
less fan noise.
Select M or Y here, if you want to include ACPI platform profile
support on the above mentioned devices.
config SURFACE_PRO3_BUTTON
tristate "Power/home/volume buttons driver for Microsoft Surface Pro 3/4 tablet"
depends on ACPI
depends on INPUT
help
This driver handles the power/home/volume buttons on the Microsoft Surface Pro 3/4 tablet.
platform/surface: Add Surface Aggregator subsystem Add Surface System Aggregator Module core and Surface Serial Hub driver, required for the embedded controller found on Microsoft Surface devices. The Surface System Aggregator Module (SSAM, SAM or Surface Aggregator) is an embedded controller (EC) found on 4th and later generation Microsoft Surface devices, with the exception of the Surface Go series. This EC provides various functionality, depending on the device in question. This can include battery status and thermal reporting (5th and later generations), but also HID keyboard (6th+) and touchpad input (7th+) on Surface Laptop and Surface Book 3 series devices. This patch provides the basic necessities for communication with the SAM EC on 5th and later generation devices. On these devices, the EC provides an interface that acts as serial device, called the Surface Serial Hub (SSH). 4th generation devices, on which the EC interface is provided via an HID-over-I2C device, are not supported by this patch. Specifically, this patch adds a driver for the SSH device (device HID MSHW0084 in ACPI), as well as a controller structure and associated API. This represents the functional core of the Surface Aggregator kernel subsystem, introduced with this patch, and will be expanded upon in subsequent commits. The SSH driver acts as the main attachment point for this subsystem and sets-up and manages the controller structure. The controller in turn provides a basic communication interface, allowing to send requests from host to EC and receiving the corresponding responses, as well as managing and receiving events, sent from EC to host. It is structured into multiple layers, with the top layer presenting the API used by other kernel drivers and the lower layers modeled after the serial protocol used for communication. Said other drivers are then responsible for providing the (Surface model specific) functionality accessible through the EC (e.g. battery status reporting, thermal information, ...) via said controller structure and API, and will be added in future commits. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Link: https://lore.kernel.org/r/20201221183959.1186143-2-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2020-12-21 19:39:51 +01:00
source "drivers/platform/surface/aggregator/Kconfig"
endif # SURFACE_PLATFORMS