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

   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 ======================================================
  10 User-Space DTX (Clipboard Detachment System) Interface
  11 ======================================================
  12
  13 The ``surface_dtx`` driver is responsible for proper clipboard detachment
  14 and re-attachment handling. To this end, it provides the ``/dev/surface/dtx``
  15 device file, through which it can interface with a user-space daemon. This
  16 daemon is then ultimately responsible for determining and taking necessary
  17 actions, such as unmounting devices attached to the base,
  18 unloading/reloading the graphics-driver, user-notifications, etc.
  19
  20 There are two basic communication principles used in this driver: Commands
  21 (in other parts of the documentation also referred to as requests) and
  22 events. Commands are sent to the EC and may have a different implications in
  23 different contexts. Events are sent by the EC upon some internal state
  24 change. Commands are always driver-initiated, whereas events are always
  25 initiated by the EC.
  26
  27 .. contents::
  28
  29 Nomenclature
  30 ============
  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 be
  37   detached, optionally (model dependent) housing the discrete GPU (dGPU).
  38
  39 * **Latch:**
  40   The mechanism keeping the clipboard attached to the base in normal
  41   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 acknowledged
  45   (following the standard communication protocol), but the EC does not act
  46   upon it, i.e. ignores it.e upper part of the
  47
  48
  49 Detachment Process
  50 ==================
  51
  52 Warning: This part of the documentation is based on reverse engineering and
  53 testing and thus may contain errors or be incomplete.
  54
  55 Latch States
  56 ------------
  57
  58 The latch mechanism has two major states: *open* and *closed*. In the
  59 *closed* state (default), the clipboard is secured to the base, whereas in
  60 the *open* state, the clipboard can be removed by a user.
  61
  62 The latch can additionally be locked and, correspondingly, unlocked, which
  63 can influence the detachment procedure. Specifically, this locking mechanism
  64 is intended to prevent the dGPU, positioned in the base of the device, from
  65 being hot-unplugged while in use. More details can be found in the
  66 documentation for the detachment procedure below. By default, the latch is
  67 unlocked.
  68
  69 Detachment Procedure
  70 --------------------
  71
  72 Note that the detachment process is governed fully by the EC. The
  73 ``surface_dtx`` driver only relays events from the EC to user-space and
  74 commands from user-space to the EC, i.e. it does not influence this process.
  75
  76 The detachment process is started with the user pressing the *detach* button
  77 on the base of the device or executing the ``SDTX_IOCTL_LATCH_REQUEST`` IOCTL.
  78 Following that:
  79
  80 1. The EC turns on the indicator led on the detach-button, sends a
  81    *detach-request* event (``SDTX_EVENT_REQUEST``), and awaits further
  82    instructions/commands. In case the latch is unlocked, the led will flash
  83    green. If the latch has been locked, the led will be solid red
  84
  85 2. The event is, via the ``surface_dtx`` driver, relayed to user-space, where
  86    an appropriate user-space daemon can handle it and send instructions back
  87    to the EC via IOCTLs provided by this driver.
  88
  89 3. 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 will
  91    time out and continue as follows:
  92
  93    - If the latch is unlocked, the EC will open the latch and the clipboard
  94      can be detached from the base. This is the exact behavior as without
  95      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 the
  99      clipboard cannot be detached from the base. Furthermore, the EC sends
 100      an cancel event (``SDTX_EVENT_CANCEL``) detailing this with the cancel
 101      reason ``SDTX_DETACH_TIMEDOUT`` (see :ref:`events` for details).
 102
 103 Valid responses by a user-space daemon to a detachment request event are:
 104
 105 - Execute ``SDTX_IOCTL_LATCH_REQUEST``. This will immediately abort the
 106   detachment process. Furthermore, the EC will send a detach-request event,
 107   similar to the user pressing the detach-button to cancel said process (see
 108   below).
 109
 110 - Execute ``SDTX_IOCTL_LATCH_CONFIRM``. This will cause the EC to open the
 111   latch, after which the user can separate clipboard and base.
 112
 113   As this changes the latch state, a *latch-status* event
 114   (``SDTX_EVENT_LATCH_STATUS``) will be sent once the latch has been opened
 115   successfully. If the EC fails to open the latch, e.g. due to hardware
 116   error or low battery, a latch-cancel event (``SDTX_EVENT_CANCEL``) will be
 117   sent with the cancel reason indicating the specific failure.
 118
 119   If the latch is currently locked, the latch will automatically be
 120   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 neither
 124   be completed nor canceled, and the EC will still be waiting for further
 125   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 button
 129   press, described below. A *generic request* event (``SDTX_EVENT_REQUEST``)
 130   is send in response to this. In contrast to those, however, this command
 131   does not trigger a new detachment process if none is currently in
 132   progress.
 133
 134 - Do nothing. The detachment process eventually times out as described in
 135   point 3.
 136
 137 See :ref:`ioctls` for more details on these responses.
 138
 139 It is important to note that, if the user presses the detach button at any
 140 point when a detachment operation is in progress (i.e. after the EC has sent
 141 the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it
 142 received the corresponding response concluding the process), the detachment
 143 process is canceled on the EC-level and an identical event is being sent.
 144 Thus a *detach-request* event, by itself, does not signal the start of the
 145 detachment process.
 146
 147 The detachment process may further be canceled by the EC due to hardware
 148 failures or a low clipboard battery. This is done via a cancel event
 149 (``SDTX_EVENT_CANCEL``) with the corresponding cancel reason.
 150
 151
 152 User-Space Interface Documentation
 153 ==================================
 154
 155 Error Codes and Status Values
 156 -----------------------------
 157
 158 Error and status codes are divided into different categories, which can be
 159 used to determine if the status code is an error, and, if it is, the
 160 severity and type of that error. The current categories are:
 161
 162 .. flat-table:: Overview of Status/Error Categories.
 163    :widths: 2 1 3
 164    :header-rows: 1
 165
 166    * - Name
 167      - Value
 168      - Short Description
 169
 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
 186 Other categories are reserved for future use. The ``SDTX_CATEGORY()`` macro
 187 can be used to determine the category of any status value. The
 188 ``SDTX_SUCCESS()`` macro can be used to check if the status value is a
 189 success value (``SDTX_CATEGORY_STATUS``) or if it indicates a failure.
 190
 191 Unknown status or error codes sent by the EC are assigned to the ``UNKNOWN``
 192 category by the driver and may be implemented via their own code in the
 193 future.
 194
 195 Currently used error codes are:
 196
 197 .. flat-table:: Overview of Error Codes.
 198    :widths: 2 1 1 3
 199    :header-rows: 1
 200
 201    * - Name
 202      - Category
 203      - Value
 204      - Short Description
 205
 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
 231 Other error codes are reserved for future use. Non-error status codes may
 232 overlap and are generally only unique within their use-case:
 233
 234 .. flat-table:: Latch Status Codes.
 235    :widths: 2 1 1 3
 236    :header-rows: 1
 237
 238    * - Name
 239      - Category
 240      - Value
 241      - Short Description
 242
 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 3
 255    :header-rows: 1
 256
 257    * - Name
 258      - Category
 259      - Value
 260      - Short Description
 261
 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
 272 Again, other codes are reserved for future use.
 273
 274 .. _events:
 275
 276 Events
 277 ------
 278
 279 Events can be received by reading from the device file. They are disabled by
 280 default and have to be enabled by executing ``SDTX_IOCTL_EVENTS_ENABLE``
 281 first. All events follow the layout prescribed by |sdtx_event|. Specific
 282 event types can be identified by their event code, described in
 283 |sdtx_event_code|. Note that other event codes are reserved for future use,
 284 thus an event parser must be able to handle any unknown/unsupported event
 285 types gracefully, by relying on the payload length given in the event header.
 286
 287 Currently provided event types are:
 288
 289 .. flat-table:: Overview of DTX events.
 290    :widths: 2 1 1 3
 291    :header-rows: 1
 292
 293    * - Name
 294      - Code
 295      - Payload
 296      - Short Description
 297
 298    * - ``SDTX_EVENT_REQUEST``
 299      - ``1``
 300      - ``0`` bytes
 301      - Detachment process initiated/aborted.
 302
 303    * - ``SDTX_EVENT_CANCEL``
 304      - ``2``
 305      - ``2`` bytes
 306      - EC canceled detachment process.
 307
 308    * - ``SDTX_EVENT_BASE_CONNECTION``
 309      - ``3``
 310      - ``4`` bytes
 311      - Base connection state changed.
 312
 313    * - ``SDTX_EVENT_LATCH_STATUS``
 314      - ``4``
 315      - ``2`` bytes
 316      - Latch status changed.
 317
 318    * - ``SDTX_EVENT_DEVICE_MODE``
 319      - ``5``
 320      - ``2`` bytes
 321      - Device mode changed.
 322
 323 Individual events in more detail:
 324
 325 ``SDTX_EVENT_REQUEST``
 326 ^^^^^^^^^^^^^^^^^^^^^^
 327
 328 Sent when a detachment process is started or, if in progress, aborted by the
 329 user, either via a detach button press or a detach request
 330 (``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space.
 331
 332 Does not have any payload.
 333
 334 ``SDTX_EVENT_CANCEL``
 335 ^^^^^^^^^^^^^^^^^^^^^
 336
 337 Sent when a detachment process is canceled by the EC due to unfulfilled
 338 preconditions (e.g. clipboard battery too low to detach) or hardware
 339 failure. The reason for cancellation is given in the event payload detailed
 340 below and can be one of
 341
 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 clipboard
 346   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 (hardware
 351   failure).
 352
 353 * ``SDTX_ERR_FAILED_TO_CLOSE``: Could not close the latch (hardware failure).
 354
 355 Other error codes in this context are reserved for future use.
 356
 357 These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern
 358 between critical hardware errors (``SDTX_CATEGORY_HARDWARE_ERROR``) or
 359 runtime errors (``SDTX_CATEGORY_RUNTIME_ERROR``), the latter of which may
 360 happen during normal operation if certain preconditions for detachment are
 361 not given.
 362
 363 .. flat-table:: Detachment Cancel Event Payload
 364    :widths: 1 1 4
 365    :header-rows: 1
 366
 367    * - Field
 368      - Type
 369      - Description
 370
 371    * - ``reason``
 372      - |__u16|
 373      - Reason for cancellation.
 374
 375 ``SDTX_EVENT_BASE_CONNECTION``
 376 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 377
 378 Sent when the base connection state has changed, i.e. when the base has been
 379 attached, detached, or detachment has become infeasible due to low clipboard
 380 battery. The new state and, if a base is connected, ID of the base is
 381 provided as payload of type |sdtx_base_info| with its layout presented
 382 below:
 383
 384 .. flat-table:: Base-Connection-Change Event Payload
 385    :widths: 1 1 4
 386    :header-rows: 1
 387
 388    * - Field
 389      - Type
 390      - Description
 391
 392    * - ``state``
 393      - |__u16|
 394      - Base connection state.
 395
 396    * - ``base_id``
 397      - |__u16|
 398      - Type of base connected (zero if none).
 399
 400 Possible values for ``state`` are:
 401
 402 * ``SDTX_BASE_DETACHED``,
 403 * ``SDTX_BASE_ATTACHED``, and
 404 * ``SDTX_DETACH_NOT_FEASIBLE``.
 405
 406 Other values are reserved for future use.
 407
 408 ``SDTX_EVENT_LATCH_STATUS``
 409 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 410
 411 Sent when the latch status has changed, i.e. when the latch has been opened,
 412 closed, or an error occurred. The current status is provided as payload:
 413
 414 .. flat-table:: Latch-Status-Change Event Payload
 415    :widths: 1 1 4
 416    :header-rows: 1
 417
 418    * - Field
 419      - Type
 420      - Description
 421
 422    * - ``status``
 423      - |__u16|
 424      - Latch status.
 425
 426 Possible 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``, and
 432 * ``SDTX_ERR_FAILED_TO_CLOSE``.
 433
 434 Other values are reserved for future use.
 435
 436 ``SDTX_EVENT_DEVICE_MODE``
 437 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 438
 439 Sent when the device mode has changed. The new device mode is provided as
 440 payload:
 441
 442 .. flat-table:: Device-Mode-Change Event Payload
 443    :widths: 1 1 4
 444    :header-rows: 1
 445
 446    * - Field
 447      - Type
 448      - Description
 449
 450    * - ``mode``
 451      - |__u16|
 452      - Device operation mode.
 453
 454 Possible values for ``mode`` are:
 455
 456 * ``SDTX_DEVICE_MODE_TABLET``,
 457 * ``SDTX_DEVICE_MODE_LAPTOP``, and
 458 * ``SDTX_DEVICE_MODE_STUDIO``.
 459
 460 Other values are reserved for future use.
 461
 462 .. _ioctls:
 463
 464 IOCTLs
 465 ------
 466
 467 The following IOCTLs are provided:
 468
 469 .. flat-table:: Overview of DTX IOCTLs
 470    :widths: 1 1 1 1 4
 471    :header-rows: 1
 472
 473    * - Type
 474      - Number
 475      - Direction
 476      - Name
 477      - Description
 478
 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
 548 Defined as ``_IO(0xA5, 0x22)``.
 549
 550 Enable events for the current file descriptor. Events can be obtained by
 551 reading from the device, if enabled. Events are disabled by default.
 552
 553 ``SDTX_IOCTL_EVENTS_DISABLE``
 554 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 555
 556 Defined as ``_IO(0xA5, 0x22)``.
 557
 558 Disable events for the current file descriptor. Events can be obtained by
 559 reading from the device, if enabled. Events are disabled by default.
 560
 561 ``SDTX_IOCTL_LATCH_LOCK``
 562 ^^^^^^^^^^^^^^^^^^^^^^^^^
 563
 564 Defined as ``_IO(0xA5, 0x23)``.
 565
 566 Locks the latch, causing the detachment procedure to abort without opening
 567 the latch on timeout. The latch is unlocked by default. This command will be
 568 silently ignored if the latch is already locked.
 569
 570 ``SDTX_IOCTL_LATCH_UNLOCK``
 571 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 572
 573 Defined as ``_IO(0xA5, 0x24)``.
 574
 575 Unlocks the latch, causing the detachment procedure to open the latch on
 576 timeout. The latch is unlocked by default. This command will not open the
 577 latch when sent during an ongoing detachment process. It will be silently
 578 ignored if the latch is already unlocked.
 579
 580 ``SDTX_IOCTL_LATCH_REQUEST``
 581 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 582
 583 Defined as ``_IO(0xA5, 0x25)``.
 584
 585 Generic latch request. Behavior depends on the context: If no
 586 detachment-process is active, detachment is requested. Otherwise the
 587 currently active detachment-process will be aborted.
 588
 589 If a detachment process is canceled by this operation, a generic detachment
 590 request event (``SDTX_EVENT_REQUEST``) will be sent.
 591
 592 This essentially behaves the same as a detachment button press.
 593
 594 ``SDTX_IOCTL_LATCH_CONFIRM``
 595 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 596
 597 Defined as ``_IO(0xA5, 0x26)``.
 598
 599 Acknowledges and confirms a latch request. If sent during an ongoing
 600 detachment process, this command causes the latch to be opened immediately.
 601 The latch will also be opened if it has been locked. In this case, the latch
 602 lock is reset to the unlocked state.
 603
 604 This command will be silently ignored if there is currently no detachment
 605 procedure in progress.
 606
 607 ``SDTX_IOCTL_LATCH_HEARTBEAT``
 608 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 609
 610 Defined as ``_IO(0xA5, 0x27)``.
 611
 612 Sends a heartbeat, essentially resetting the detachment timeout. This
 613 command can be used to keep the detachment process alive while work required
 614 for the detachment to succeed is still in progress.
 615
 616 This command will be silently ignored if there is currently no detachment
 617 procedure in progress.
 618
 619 ``SDTX_IOCTL_LATCH_CANCEL``
 620 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 621
 622 Defined as ``_IO(0xA5, 0x28)``.
 623
 624 Cancels detachment in progress (if any). If a detachment process is canceled
 625 by this operation, a generic detachment request event
 626 (``SDTX_EVENT_REQUEST``) will be sent.
 627
 628 This command will be silently ignored if there is currently no detachment
 629 procedure in progress.
 630
 631 ``SDTX_IOCTL_GET_BASE_INFO``
 632 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 633
 634 Defined as ``_IOR(0xA5, 0x29, struct sdtx_base_info)``.
 635
 636 Get the current base connection state (i.e. attached/detached) and the type
 637 of the base connected to the clipboard. This is command essentially provides
 638 a way to query the information provided by the base connection change event
 639 (``SDTX_EVENT_BASE_CONNECTION``).
 640
 641 Possible values for ``struct sdtx_base_info.state`` are:
 642
 643 * ``SDTX_BASE_DETACHED``,
 644 * ``SDTX_BASE_ATTACHED``, and
 645 * ``SDTX_DETACH_NOT_FEASIBLE``.
 646
 647 Other values are reserved for future use.
 648
 649 ``SDTX_IOCTL_GET_DEVICE_MODE``
 650 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 651
 652 Defined as ``_IOR(0xA5, 0x2A, __u16)``.
 653
 654 Returns the device operation mode, indicating if and how the base is
 655 attached to the clipboard. This is command essentially provides a way to
 656 query the information provided by the device mode change event
 657 (``SDTX_EVENT_DEVICE_MODE``).
 658
 659 Returned values are:
 660
 661 * ``SDTX_DEVICE_MODE_LAPTOP``
 662 * ``SDTX_DEVICE_MODE_TABLET``
 663 * ``SDTX_DEVICE_MODE_STUDIO``
 664
 665 See |sdtx_device_mode| for details. Other values are reserved for future
 666 use.
 667
 668
 669 ``SDTX_IOCTL_GET_LATCH_STATUS``
 670 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 671
 672 Defined as ``_IOR(0xA5, 0x2B, __u16)``.
 673
 674 Get the current latch status or (presumably) the last error encountered when
 675 trying to open/close the latch. This is command essentially provides a way
 676 to query the information provided by the latch status change event
 677 (``SDTX_EVENT_LATCH_STATUS``).
 678
 679 Returned values are:
 680
 681 * ``SDTX_LATCH_CLOSED``,
 682 * ``SDTX_LATCH_OPENED``,
 683 * ``SDTX_ERR_FAILED_TO_OPEN``,
 684 * ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and
 685 * ``SDTX_ERR_FAILED_TO_CLOSE``.
 686
 687 Other values are reserved for future use.
 688
 689 A Note on Base IDs
 690 ------------------
 691
 692 Base types/IDs provided via ``SDTX_EVENT_BASE_CONNECTION`` or
 693 ``SDTX_IOCTL_GET_BASE_INFO`` are directly forwarded from the EC in the lower
 694 byte of the combined |__u16| value, with the driver storing the EC type from
 695 which this ID comes in the high byte (without this, base IDs over different
 696 types of ECs may be overlapping).
 697
 698 The ``SDTX_DEVICE_TYPE()`` macro can be used to determine the EC device
 699 type. This can be one of
 700
 701 * ``SDTX_DEVICE_TYPE_HID``, for Surface Aggregator Module over HID, and
 702
 703 * ``SDTX_DEVICE_TYPE_SSH``, for Surface Aggregator Module over Surface Serial
 704   Hub.
 705
 706 Note that currently only the ``SSH`` type EC is supported, however ``HID``
 707 type is reserved for future use.
 708
 709 Structures and Enums
 710 --------------------
 711
 712 .. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h
 713
 714 API Users
 715 =========
 716
 717 A user-space daemon utilizing this API can be found at
 718 https://github.com/linux-surface/surface-dtx-daemon.