path: root/Documentation/userspace-api
diff options
authorMaximilian Luz <>2021-03-08 19:48:17 +0100
committerHans de Goede <>2021-03-17 18:39:38 +0100
commit1d609992832e900378b305f9f8dcf0ce8473049e (patch)
tree22e8a312d731f5368dbcc8e3cea0b048280f96ca /Documentation/userspace-api
parent87eaede45385e384faf5b15d9c718a951667bdd0 (diff)
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]: Signed-off-by: Maximilian Luz <> Link: Signed-off-by: Hans de Goede <>
Diffstat (limited to 'Documentation/userspace-api')
1 files changed, 2 insertions, 0 deletions
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index 599bd4493944..1c28b8ef6677 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -327,6 +327,8 @@ Code Seq# Include File Comments
0xA4 00-1F uapi/asm/sgx.h <>
0xA5 01 linux/surface_aggregator/cdev.h Microsoft Surface Platform System Aggregator
+0xA5 20-2F linux/surface_aggregator/dtx.h Microsoft Surface DTX driver
+ <>
0xAA 00-3F linux/uapi/linux/userfaultfd.h
0xAB 00-1F linux/nbd.h
0xAC 00-1F linux/raw.h