Commit 1d609992 authored by Maximilian Luz's avatar Maximilian Luz Committed by Hans de Goede
Browse files

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: default avatarMaximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20210308184819.437438-2-luzmaximilian@gmail.com


Signed-off-by: default avatarHans de Goede <hdegoede@redhat.com>
parent 87eaede4

Documentation/userspace-api/ioctl/ioctl-number.rst

+2 −0
Original line number Diff line number Diff line
@@ -327,6 +327,8 @@ Code Seq# Include File Comments 
0xA4  00-1F  uapi/asm/sgx.h                                          <mailto:linux-sgx@vger.kernel.org>

0xA5  01     linux/surface_aggregator/cdev.h                         Microsoft Surface Platform System Aggregator

                                                                     <mailto:luzmaximilian@gmail.com>

0xA5  20-2F  linux/surface_aggregator/dtx.h                          Microsoft Surface DTX driver

                                                                     <mailto:luzmaximilian@gmail.com>

0xAA  00-3F  linux/uapi/linux/userfaultfd.h

0xAB  00-1F  linux/nbd.h

0xAC  00-1F  linux/raw.h

MAINTAINERS

+7 −0
Original line number Diff line number Diff line
@@ -11861,6 +11861,13 @@ F: drivers/scsi/smartpqi/smartpqi*.[ch] 
F:	include/linux/cciss*.h

F:	include/uapi/linux/cciss*.h









MICROSOFT SURFACE DTX DRIVER









M:	Maximilian Luz <luzmaximilian@gmail.com>









L:	platform-driver-x86@vger.kernel.org









S:	Maintained









F:	drivers/platform/surface/surface_dtx.c









F:	include/uapi/linux/surface_aggregator/dtx.h

















MICROSOFT SURFACE GPE LID SUPPORT DRIVER









M:	Maximilian Luz <luzmaximilian@gmail.com>









L:	platform-driver-x86@vger.kernel.org
































drivers/platform/surface/Kconfig



+16
−0






























Original line number
Diff line number
Diff line







@@ -104,6 +104,22 @@ config SURFACE_AGGREGATOR_REGISTRY







	  the respective client devices. Drivers for these devices still need to









	  be selected via the other options.



















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.



















config SURFACE_GPE









	tristate "Surface GPE/Lid Support Driver"









	depends on DMI
































drivers/platform/surface/Makefile



+1
−0






























Original line number
Diff line number
Diff line







@@ -11,6 +11,7 @@ obj-$(CONFIG_SURFACE_ACPI_NOTIFY)	+= surface_acpi_notify.o







obj-$(CONFIG_SURFACE_AGGREGATOR)	+= aggregator/









obj-$(CONFIG_SURFACE_AGGREGATOR_CDEV)	+= surface_aggregator_cdev.o









obj-$(CONFIG_SURFACE_AGGREGATOR_REGISTRY) += surface_aggregator_registry.o









obj-$(CONFIG_SURFACE_DTX)		+= surface_dtx.o









obj-$(CONFIG_SURFACE_GPE)		+= surface_gpe.o









obj-$(CONFIG_SURFACE_HOTPLUG)		+= surface_hotplug.o









obj-$(CONFIG_SURFACE_PLATFORM_PROFILE)	+= surface_platform_profile.o
































drivers/platform/surface/surface_dtx.c
0 → 100644



+1201
−0




























File added.
Preview size limit exceeded, changes collapsed.