719 lines · plain
1.. SPDX-License-Identifier: GPL-2.0+2 3.. |__u16| replace:: :c:type:`__u16 <__u16>`4.. |sdtx_event| replace:: :c:type:`struct sdtx_event <sdtx_event>`5.. |sdtx_event_code| replace:: :c:type:`enum sdtx_event_code <sdtx_event_code>`6.. |sdtx_base_info| replace:: :c:type:`struct sdtx_base_info <sdtx_base_info>`7.. |sdtx_device_mode| replace:: :c:type:`struct sdtx_device_mode <sdtx_device_mode>`8 9======================================================10User-Space DTX (Clipboard Detachment System) Interface11======================================================12 13The ``surface_dtx`` driver is responsible for proper clipboard detachment14and re-attachment handling. To this end, it provides the ``/dev/surface/dtx``15device file, through which it can interface with a user-space daemon. This16daemon is then ultimately responsible for determining and taking necessary17actions, such as unmounting devices attached to the base,18unloading/reloading the graphics-driver, user-notifications, etc.19 20There are two basic communication principles used in this driver: Commands21(in other parts of the documentation also referred to as requests) and22events. Commands are sent to the EC and may have a different implications in23different contexts. Events are sent by the EC upon some internal state24change. Commands are always driver-initiated, whereas events are always25initiated by the EC.26 27.. contents::28 29Nomenclature30============31 32* **Clipboard:**33 The detachable upper part of the Surface Book, housing the screen and CPU.34 35* **Base:**36 The lower part of the Surface Book from which the clipboard can be37 detached, optionally (model dependent) housing the discrete GPU (dGPU).38 39* **Latch:**40 The mechanism keeping the clipboard attached to the base in normal41 operation and allowing it to be detached when requested.42 43* **Silently ignored commands:**44 The command is accepted by the EC as a valid command and acknowledged45 (following the standard communication protocol), but the EC does not act46 upon it, i.e. ignores it.e upper part of the47 48 49Detachment Process50==================51 52Warning: This part of the documentation is based on reverse engineering and53testing and thus may contain errors or be incomplete.54 55Latch States56------------57 58The latch mechanism has two major states: *open* and *closed*. In the59*closed* state (default), the clipboard is secured to the base, whereas in60the *open* state, the clipboard can be removed by a user.61 62The latch can additionally be locked and, correspondingly, unlocked, which63can influence the detachment procedure. Specifically, this locking mechanism64is intended to prevent the dGPU, positioned in the base of the device, from65being hot-unplugged while in use. More details can be found in the66documentation for the detachment procedure below. By default, the latch is67unlocked.68 69Detachment Procedure70--------------------71 72Note that the detachment process is governed fully by the EC. The73``surface_dtx`` driver only relays events from the EC to user-space and74commands from user-space to the EC, i.e. it does not influence this process.75 76The detachment process is started with the user pressing the *detach* button77on the base of the device or executing the ``SDTX_IOCTL_LATCH_REQUEST`` IOCTL.78Following that:79 801. The EC turns on the indicator led on the detach-button, sends a81 *detach-request* event (``SDTX_EVENT_REQUEST``), and awaits further82 instructions/commands. In case the latch is unlocked, the led will flash83 green. If the latch has been locked, the led will be solid red84 852. The event is, via the ``surface_dtx`` driver, relayed to user-space, where86 an appropriate user-space daemon can handle it and send instructions back87 to the EC via IOCTLs provided by this driver.88 893. The EC waits for instructions from user-space and acts according to them.90 If the EC does not receive any instructions in a given period, it will91 time out and continue as follows:92 93 - If the latch is unlocked, the EC will open the latch and the clipboard94 can be detached from the base. This is the exact behavior as without95 this driver or any user-space daemon. See the ``SDTX_IOCTL_LATCH_CONFIRM``96 description below for more details on the follow-up behavior of the EC.97 98 - If the latch is locked, the EC will *not* open the latch, meaning the99 clipboard cannot be detached from the base. Furthermore, the EC sends100 an cancel event (``SDTX_EVENT_CANCEL``) detailing this with the cancel101 reason ``SDTX_DETACH_TIMEDOUT`` (see :ref:`events` for details).102 103Valid responses by a user-space daemon to a detachment request event are:104 105- Execute ``SDTX_IOCTL_LATCH_REQUEST``. This will immediately abort the106 detachment process. Furthermore, the EC will send a detach-request event,107 similar to the user pressing the detach-button to cancel said process (see108 below).109 110- Execute ``SDTX_IOCTL_LATCH_CONFIRM``. This will cause the EC to open the111 latch, after which the user can separate clipboard and base.112 113 As this changes the latch state, a *latch-status* event114 (``SDTX_EVENT_LATCH_STATUS``) will be sent once the latch has been opened115 successfully. If the EC fails to open the latch, e.g. due to hardware116 error or low battery, a latch-cancel event (``SDTX_EVENT_CANCEL``) will be117 sent with the cancel reason indicating the specific failure.118 119 If the latch is currently locked, the latch will automatically be120 unlocked before it is opened.121 122- Execute ``SDTX_IOCTL_LATCH_HEARTBEAT``. This will reset the internal timeout.123 No other actions will be performed, i.e. the detachment process will neither124 be completed nor canceled, and the EC will still be waiting for further125 responses.126 127- Execute ``SDTX_IOCTL_LATCH_CANCEL``. This will abort the detachment process,128 similar to ``SDTX_IOCTL_LATCH_REQUEST``, described above, or the button129 press, described below. A *generic request* event (``SDTX_EVENT_REQUEST``)130 is send in response to this. In contrast to those, however, this command131 does not trigger a new detachment process if none is currently in132 progress.133 134- Do nothing. The detachment process eventually times out as described in135 point 3.136 137See :ref:`ioctls` for more details on these responses.138 139It is important to note that, if the user presses the detach button at any140point when a detachment operation is in progress (i.e. after the EC has sent141the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it142received the corresponding response concluding the process), the detachment143process is canceled on the EC-level and an identical event is being sent.144Thus a *detach-request* event, by itself, does not signal the start of the145detachment process.146 147The detachment process may further be canceled by the EC due to hardware148failures or a low clipboard battery. This is done via a cancel event149(``SDTX_EVENT_CANCEL``) with the corresponding cancel reason.150 151 152User-Space Interface Documentation153==================================154 155Error Codes and Status Values156-----------------------------157 158Error and status codes are divided into different categories, which can be159used to determine if the status code is an error, and, if it is, the160severity and type of that error. The current categories are:161 162.. flat-table:: Overview of Status/Error Categories.163 :widths: 2 1 3164 :header-rows: 1165 166 * - Name167 - Value168 - Short Description169 170 * - ``STATUS``171 - ``0x0000``172 - Non-error status codes.173 174 * - ``RUNTIME_ERROR``175 - ``0x1000``176 - Non-critical runtime errors.177 178 * - ``HARDWARE_ERROR``179 - ``0x2000``180 - Critical hardware failures.181 182 * - ``UNKNOWN``183 - ``0xF000``184 - Unknown error codes.185 186Other categories are reserved for future use. The ``SDTX_CATEGORY()`` macro187can be used to determine the category of any status value. The188``SDTX_SUCCESS()`` macro can be used to check if the status value is a189success value (``SDTX_CATEGORY_STATUS``) or if it indicates a failure.190 191Unknown status or error codes sent by the EC are assigned to the ``UNKNOWN``192category by the driver and may be implemented via their own code in the193future.194 195Currently used error codes are:196 197.. flat-table:: Overview of Error Codes.198 :widths: 2 1 1 3199 :header-rows: 1200 201 * - Name202 - Category203 - Value204 - Short Description205 206 * - ``SDTX_DETACH_NOT_FEASIBLE``207 - ``RUNTIME``208 - ``0x1001``209 - Detachment not feasible due to low clipboard battery.210 211 * - ``SDTX_DETACH_TIMEDOUT``212 - ``RUNTIME``213 - ``0x1002``214 - Detachment process timed out while the latch was locked.215 216 * - ``SDTX_ERR_FAILED_TO_OPEN``217 - ``HARDWARE``218 - ``0x2001``219 - Failed to open latch.220 221 * - ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``222 - ``HARDWARE``223 - ``0x2002``224 - Failed to keep latch open.225 226 * - ``SDTX_ERR_FAILED_TO_CLOSE``227 - ``HARDWARE``228 - ``0x2003``229 - Failed to close latch.230 231Other error codes are reserved for future use. Non-error status codes may232overlap and are generally only unique within their use-case:233 234.. flat-table:: Latch Status Codes.235 :widths: 2 1 1 3236 :header-rows: 1237 238 * - Name239 - Category240 - Value241 - Short Description242 243 * - ``SDTX_LATCH_CLOSED``244 - ``STATUS``245 - ``0x0000``246 - Latch is closed/has been closed.247 248 * - ``SDTX_LATCH_OPENED``249 - ``STATUS``250 - ``0x0001``251 - Latch is open/has been opened.252 253.. flat-table:: Base State Codes.254 :widths: 2 1 1 3255 :header-rows: 1256 257 * - Name258 - Category259 - Value260 - Short Description261 262 * - ``SDTX_BASE_DETACHED``263 - ``STATUS``264 - ``0x0000``265 - Base has been detached/is not present.266 267 * - ``SDTX_BASE_ATTACHED``268 - ``STATUS``269 - ``0x0001``270 - Base has been attached/is present.271 272Again, other codes are reserved for future use.273 274.. _events:275 276Events277------278 279Events can be received by reading from the device file. They are disabled by280default and have to be enabled by executing ``SDTX_IOCTL_EVENTS_ENABLE``281first. All events follow the layout prescribed by |sdtx_event|. Specific282event types can be identified by their event code, described in283|sdtx_event_code|. Note that other event codes are reserved for future use,284thus an event parser must be able to handle any unknown/unsupported event285types gracefully, by relying on the payload length given in the event header.286 287Currently provided event types are:288 289.. flat-table:: Overview of DTX events.290 :widths: 2 1 1 3291 :header-rows: 1292 293 * - Name294 - Code295 - Payload296 - Short Description297 298 * - ``SDTX_EVENT_REQUEST``299 - ``1``300 - ``0`` bytes301 - Detachment process initiated/aborted.302 303 * - ``SDTX_EVENT_CANCEL``304 - ``2``305 - ``2`` bytes306 - EC canceled detachment process.307 308 * - ``SDTX_EVENT_BASE_CONNECTION``309 - ``3``310 - ``4`` bytes311 - Base connection state changed.312 313 * - ``SDTX_EVENT_LATCH_STATUS``314 - ``4``315 - ``2`` bytes316 - Latch status changed.317 318 * - ``SDTX_EVENT_DEVICE_MODE``319 - ``5``320 - ``2`` bytes321 - Device mode changed.322 323Individual events in more detail:324 325``SDTX_EVENT_REQUEST``326^^^^^^^^^^^^^^^^^^^^^^327 328Sent when a detachment process is started or, if in progress, aborted by the329user, either via a detach button press or a detach request330(``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space.331 332Does not have any payload.333 334``SDTX_EVENT_CANCEL``335^^^^^^^^^^^^^^^^^^^^^336 337Sent when a detachment process is canceled by the EC due to unfulfilled338preconditions (e.g. clipboard battery too low to detach) or hardware339failure. The reason for cancellation is given in the event payload detailed340below and can be one of341 342* ``SDTX_DETACH_TIMEDOUT``: Detachment timed out while the latch was locked.343 The latch has neither been opened nor unlocked.344 345* ``SDTX_DETACH_NOT_FEASIBLE``: Detachment not feasible due to low clipboard346 battery.347 348* ``SDTX_ERR_FAILED_TO_OPEN``: Could not open the latch (hardware failure).349 350* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``: Could not keep the latch open (hardware351 failure).352 353* ``SDTX_ERR_FAILED_TO_CLOSE``: Could not close the latch (hardware failure).354 355Other error codes in this context are reserved for future use.356 357These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern358between critical hardware errors (``SDTX_CATEGORY_HARDWARE_ERROR``) or359runtime errors (``SDTX_CATEGORY_RUNTIME_ERROR``), the latter of which may360happen during normal operation if certain preconditions for detachment are361not given.362 363.. flat-table:: Detachment Cancel Event Payload364 :widths: 1 1 4365 :header-rows: 1366 367 * - Field368 - Type369 - Description370 371 * - ``reason``372 - |__u16|373 - Reason for cancellation.374 375``SDTX_EVENT_BASE_CONNECTION``376^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^377 378Sent when the base connection state has changed, i.e. when the base has been379attached, detached, or detachment has become infeasible due to low clipboard380battery. The new state and, if a base is connected, ID of the base is381provided as payload of type |sdtx_base_info| with its layout presented382below:383 384.. flat-table:: Base-Connection-Change Event Payload385 :widths: 1 1 4386 :header-rows: 1387 388 * - Field389 - Type390 - Description391 392 * - ``state``393 - |__u16|394 - Base connection state.395 396 * - ``base_id``397 - |__u16|398 - Type of base connected (zero if none).399 400Possible values for ``state`` are:401 402* ``SDTX_BASE_DETACHED``,403* ``SDTX_BASE_ATTACHED``, and404* ``SDTX_DETACH_NOT_FEASIBLE``.405 406Other values are reserved for future use.407 408``SDTX_EVENT_LATCH_STATUS``409^^^^^^^^^^^^^^^^^^^^^^^^^^^410 411Sent when the latch status has changed, i.e. when the latch has been opened,412closed, or an error occurred. The current status is provided as payload:413 414.. flat-table:: Latch-Status-Change Event Payload415 :widths: 1 1 4416 :header-rows: 1417 418 * - Field419 - Type420 - Description421 422 * - ``status``423 - |__u16|424 - Latch status.425 426Possible values for ``status`` are:427 428* ``SDTX_LATCH_CLOSED``,429* ``SDTX_LATCH_OPENED``,430* ``SDTX_ERR_FAILED_TO_OPEN``,431* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and432* ``SDTX_ERR_FAILED_TO_CLOSE``.433 434Other values are reserved for future use.435 436``SDTX_EVENT_DEVICE_MODE``437^^^^^^^^^^^^^^^^^^^^^^^^^^438 439Sent when the device mode has changed. The new device mode is provided as440payload:441 442.. flat-table:: Device-Mode-Change Event Payload443 :widths: 1 1 4444 :header-rows: 1445 446 * - Field447 - Type448 - Description449 450 * - ``mode``451 - |__u16|452 - Device operation mode.453 454Possible values for ``mode`` are:455 456* ``SDTX_DEVICE_MODE_TABLET``,457* ``SDTX_DEVICE_MODE_LAPTOP``, and458* ``SDTX_DEVICE_MODE_STUDIO``.459 460Other values are reserved for future use.461 462.. _ioctls:463 464IOCTLs465------466 467The following IOCTLs are provided:468 469.. flat-table:: Overview of DTX IOCTLs470 :widths: 1 1 1 1 4471 :header-rows: 1472 473 * - Type474 - Number475 - Direction476 - Name477 - Description478 479 * - ``0xA5``480 - ``0x21``481 - ``-``482 - ``EVENTS_ENABLE``483 - Enable events for the current file descriptor.484 485 * - ``0xA5``486 - ``0x22``487 - ``-``488 - ``EVENTS_DISABLE``489 - Disable events for the current file descriptor.490 491 * - ``0xA5``492 - ``0x23``493 - ``-``494 - ``LATCH_LOCK``495 - Lock the latch.496 497 * - ``0xA5``498 - ``0x24``499 - ``-``500 - ``LATCH_UNLOCK``501 - Unlock the latch.502 503 * - ``0xA5``504 - ``0x25``505 - ``-``506 - ``LATCH_REQUEST``507 - Request clipboard detachment.508 509 * - ``0xA5``510 - ``0x26``511 - ``-``512 - ``LATCH_CONFIRM``513 - Confirm clipboard detachment request.514 515 * - ``0xA5``516 - ``0x27``517 - ``-``518 - ``LATCH_HEARTBEAT``519 - Send heartbeat signal to EC.520 521 * - ``0xA5``522 - ``0x28``523 - ``-``524 - ``LATCH_CANCEL``525 - Cancel detachment process.526 527 * - ``0xA5``528 - ``0x29``529 - ``R``530 - ``GET_BASE_INFO``531 - Get current base/connection information.532 533 * - ``0xA5``534 - ``0x2A``535 - ``R``536 - ``GET_DEVICE_MODE``537 - Get current device operation mode.538 539 * - ``0xA5``540 - ``0x2B``541 - ``R``542 - ``GET_LATCH_STATUS``543 - Get current device latch status.544 545``SDTX_IOCTL_EVENTS_ENABLE``546^^^^^^^^^^^^^^^^^^^^^^^^^^^^547 548Defined as ``_IO(0xA5, 0x22)``.549 550Enable events for the current file descriptor. Events can be obtained by551reading from the device, if enabled. Events are disabled by default.552 553``SDTX_IOCTL_EVENTS_DISABLE``554^^^^^^^^^^^^^^^^^^^^^^^^^^^^^555 556Defined as ``_IO(0xA5, 0x22)``.557 558Disable events for the current file descriptor. Events can be obtained by559reading from the device, if enabled. Events are disabled by default.560 561``SDTX_IOCTL_LATCH_LOCK``562^^^^^^^^^^^^^^^^^^^^^^^^^563 564Defined as ``_IO(0xA5, 0x23)``.565 566Locks the latch, causing the detachment procedure to abort without opening567the latch on timeout. The latch is unlocked by default. This command will be568silently ignored if the latch is already locked.569 570``SDTX_IOCTL_LATCH_UNLOCK``571^^^^^^^^^^^^^^^^^^^^^^^^^^^572 573Defined as ``_IO(0xA5, 0x24)``.574 575Unlocks the latch, causing the detachment procedure to open the latch on576timeout. The latch is unlocked by default. This command will not open the577latch when sent during an ongoing detachment process. It will be silently578ignored if the latch is already unlocked.579 580``SDTX_IOCTL_LATCH_REQUEST``581^^^^^^^^^^^^^^^^^^^^^^^^^^^^582 583Defined as ``_IO(0xA5, 0x25)``.584 585Generic latch request. Behavior depends on the context: If no586detachment-process is active, detachment is requested. Otherwise the587currently active detachment-process will be aborted.588 589If a detachment process is canceled by this operation, a generic detachment590request event (``SDTX_EVENT_REQUEST``) will be sent.591 592This essentially behaves the same as a detachment button press.593 594``SDTX_IOCTL_LATCH_CONFIRM``595^^^^^^^^^^^^^^^^^^^^^^^^^^^^596 597Defined as ``_IO(0xA5, 0x26)``.598 599Acknowledges and confirms a latch request. If sent during an ongoing600detachment process, this command causes the latch to be opened immediately.601The latch will also be opened if it has been locked. In this case, the latch602lock is reset to the unlocked state.603 604This command will be silently ignored if there is currently no detachment605procedure in progress.606 607``SDTX_IOCTL_LATCH_HEARTBEAT``608^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^609 610Defined as ``_IO(0xA5, 0x27)``.611 612Sends a heartbeat, essentially resetting the detachment timeout. This613command can be used to keep the detachment process alive while work required614for the detachment to succeed is still in progress.615 616This command will be silently ignored if there is currently no detachment617procedure in progress.618 619``SDTX_IOCTL_LATCH_CANCEL``620^^^^^^^^^^^^^^^^^^^^^^^^^^^621 622Defined as ``_IO(0xA5, 0x28)``.623 624Cancels detachment in progress (if any). If a detachment process is canceled625by this operation, a generic detachment request event626(``SDTX_EVENT_REQUEST``) will be sent.627 628This command will be silently ignored if there is currently no detachment629procedure in progress.630 631``SDTX_IOCTL_GET_BASE_INFO``632^^^^^^^^^^^^^^^^^^^^^^^^^^^^633 634Defined as ``_IOR(0xA5, 0x29, struct sdtx_base_info)``.635 636Get the current base connection state (i.e. attached/detached) and the type637of the base connected to the clipboard. This is command essentially provides638a way to query the information provided by the base connection change event639(``SDTX_EVENT_BASE_CONNECTION``).640 641Possible values for ``struct sdtx_base_info.state`` are:642 643* ``SDTX_BASE_DETACHED``,644* ``SDTX_BASE_ATTACHED``, and645* ``SDTX_DETACH_NOT_FEASIBLE``.646 647Other values are reserved for future use.648 649``SDTX_IOCTL_GET_DEVICE_MODE``650^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^651 652Defined as ``_IOR(0xA5, 0x2A, __u16)``.653 654Returns the device operation mode, indicating if and how the base is655attached to the clipboard. This is command essentially provides a way to656query the information provided by the device mode change event657(``SDTX_EVENT_DEVICE_MODE``).658 659Returned values are:660 661* ``SDTX_DEVICE_MODE_LAPTOP``662* ``SDTX_DEVICE_MODE_TABLET``663* ``SDTX_DEVICE_MODE_STUDIO``664 665See |sdtx_device_mode| for details. Other values are reserved for future666use.667 668 669``SDTX_IOCTL_GET_LATCH_STATUS``670^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^671 672Defined as ``_IOR(0xA5, 0x2B, __u16)``.673 674Get the current latch status or (presumably) the last error encountered when675trying to open/close the latch. This is command essentially provides a way676to query the information provided by the latch status change event677(``SDTX_EVENT_LATCH_STATUS``).678 679Returned values are:680 681* ``SDTX_LATCH_CLOSED``,682* ``SDTX_LATCH_OPENED``,683* ``SDTX_ERR_FAILED_TO_OPEN``,684* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and685* ``SDTX_ERR_FAILED_TO_CLOSE``.686 687Other values are reserved for future use.688 689A Note on Base IDs690------------------691 692Base types/IDs provided via ``SDTX_EVENT_BASE_CONNECTION`` or693``SDTX_IOCTL_GET_BASE_INFO`` are directly forwarded from the EC in the lower694byte of the combined |__u16| value, with the driver storing the EC type from695which this ID comes in the high byte (without this, base IDs over different696types of ECs may be overlapping).697 698The ``SDTX_DEVICE_TYPE()`` macro can be used to determine the EC device699type. This can be one of700 701* ``SDTX_DEVICE_TYPE_HID``, for Surface Aggregator Module over HID, and702 703* ``SDTX_DEVICE_TYPE_SSH``, for Surface Aggregator Module over Surface Serial704 Hub.705 706Note that currently only the ``SSH`` type EC is supported, however ``HID``707type is reserved for future use.708 709Structures and Enums710--------------------711 712.. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h713 714API Users715=========716 717A user-space daemon utilizing this API can be found at718https://github.com/linux-surface/surface-dtx-daemon.719