Documentation/driver-api/surface_aggregator/clients/dtx.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/surface_aggregator/clients/dtx.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/surface_aggregator/clients/dtx.rst
Extension
.rst
Size
21468 bytes
Lines
719
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0+

.. |__u16| replace:: :c:type:`__u16 <__u16>`
.. |sdtx_event| replace:: :c:type:`struct sdtx_event <sdtx_event>`
.. |sdtx_event_code| replace:: :c:type:`enum sdtx_event_code <sdtx_event_code>`
.. |sdtx_base_info| replace:: :c:type:`struct sdtx_base_info <sdtx_base_info>`
.. |sdtx_device_mode| replace:: :c:type:`struct sdtx_device_mode <sdtx_device_mode>`

======================================================
User-Space DTX (Clipboard Detachment System) Interface
======================================================

The ``surface_dtx`` driver is responsible for proper clipboard detachment
and re-attachment handling. To this end, it provides the ``/dev/surface/dtx``
device file, through which it can interface with a user-space daemon. This
daemon is then ultimately responsible for determining and taking necessary
actions, such as unmounting devices attached to the base,
unloading/reloading the graphics-driver, user-notifications, etc.

There are two basic communication principles used in this driver: Commands
(in other parts of the documentation also referred to as requests) and
events. Commands are sent to the EC and may have a different implications in
different contexts. Events are sent by the EC upon some internal state
change. Commands are always driver-initiated, whereas events are always
initiated by the EC.

.. contents::

Nomenclature
============

* **Clipboard:**
  The detachable upper part of the Surface Book, housing the screen and CPU.

* **Base:**
  The lower part of the Surface Book from which the clipboard can be
  detached, optionally (model dependent) housing the discrete GPU (dGPU).

* **Latch:**
  The mechanism keeping the clipboard attached to the base in normal
  operation and allowing it to be detached when requested.

* **Silently ignored commands:**
  The command is accepted by the EC as a valid command and acknowledged
  (following the standard communication protocol), but the EC does not act
  upon it, i.e. ignores it.e upper part of the


Detachment Process
==================

Warning: This part of the documentation is based on reverse engineering and
testing and thus may contain errors or be incomplete.

Latch States
------------

The latch mechanism has two major states: *open* and *closed*. In the
*closed* state (default), the clipboard is secured to the base, whereas in
the *open* state, the clipboard can be removed by a user.

The latch can additionally be locked and, correspondingly, unlocked, which
can influence the detachment procedure. Specifically, this locking mechanism
is intended to prevent the dGPU, positioned in the base of the device, from
being hot-unplugged while in use. More details can be found in the
documentation for the detachment procedure below. By default, the latch is
unlocked.

Detachment Procedure
--------------------

Annotation

Implementation Notes