cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

dtx.rst (21468B)


      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) Interface
     11======================================================
     12
     13The ``surface_dtx`` driver is responsible for proper clipboard detachment
     14and re-attachment handling. To this end, it provides the ``/dev/surface/dtx``
     15device file, through which it can interface with a user-space daemon. This
     16daemon is then ultimately responsible for determining and taking necessary
     17actions, 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: Commands
     21(in other parts of the documentation also referred to as requests) and
     22events. Commands are sent to the EC and may have a different implications in
     23different contexts. Events are sent by the EC upon some internal state
     24change. Commands are always driver-initiated, whereas events are always
     25initiated by the EC.
     26
     27.. contents::
     28
     29Nomenclature
     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
     49Detachment Process
     50==================
     51
     52Warning: This part of the documentation is based on reverse engineering and
     53testing and thus may contain errors or be incomplete.
     54
     55Latch States
     56------------
     57
     58The latch mechanism has two major states: *open* and *closed*. In the
     59*closed* state (default), the clipboard is secured to the base, whereas in
     60the *open* state, the clipboard can be removed by a user.
     61
     62The latch can additionally be locked and, correspondingly, unlocked, which
     63can influence the detachment procedure. Specifically, this locking mechanism
     64is intended to prevent the dGPU, positioned in the base of the device, from
     65being hot-unplugged while in use. More details can be found in the
     66documentation for the detachment procedure below. By default, the latch is
     67unlocked.
     68
     69Detachment Procedure
     70--------------------
     71
     72Note 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
     74commands 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* button
     77on 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 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
     852. 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
     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 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
    103Valid 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
    137See :ref:`ioctls` for more details on these responses.
    138
    139It is important to note that, if the user presses the detach button at any
    140point when a detachment operation is in progress (i.e. after the EC has sent
    141the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it
    142received the corresponding response concluding the process), the detachment
    143process 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 the
    145detachment process.
    146
    147The detachment process may further be canceled by the EC due to hardware
    148failures or a low clipboard battery. This is done via a cancel event
    149(``SDTX_EVENT_CANCEL``) with the corresponding cancel reason.
    150
    151
    152User-Space Interface Documentation
    153==================================
    154
    155Error Codes and Status Values
    156-----------------------------
    157
    158Error and status codes are divided into different categories, which can be
    159used to determine if the status code is an error, and, if it is, the
    160severity 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
    186Other categories are reserved for future use. The ``SDTX_CATEGORY()`` macro
    187can 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
    189success 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 the
    193future.
    194
    195Currently 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
    231Other error codes are reserved for future use. Non-error status codes may
    232overlap 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
    272Again, other codes are reserved for future use.
    273
    274.. _events:
    275
    276Events
    277------
    278
    279Events can be received by reading from the device file. They are disabled by
    280default and have to be enabled by executing ``SDTX_IOCTL_EVENTS_ENABLE``
    281first. All events follow the layout prescribed by |sdtx_event|. Specific
    282event types can be identified by their event code, described in
    283|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 event
    285types 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 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
    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 the
    329user, either via a detach button press or a detach request
    330(``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 unfulfilled
    338preconditions (e.g. clipboard battery too low to detach) or hardware
    339failure. The reason for cancellation is given in the event payload detailed
    340below 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
    355Other error codes in this context are reserved for future use.
    356
    357These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern
    358between critical hardware errors (``SDTX_CATEGORY_HARDWARE_ERROR``) or
    359runtime errors (``SDTX_CATEGORY_RUNTIME_ERROR``), the latter of which may
    360happen during normal operation if certain preconditions for detachment are
    361not 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
    378Sent when the base connection state has changed, i.e. when the base has been
    379attached, detached, or detachment has become infeasible due to low clipboard
    380battery. The new state and, if a base is connected, ID of the base is
    381provided as payload of type |sdtx_base_info| with its layout presented
    382below:
    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
    400Possible values for ``state`` are:
    401
    402* ``SDTX_BASE_DETACHED``,
    403* ``SDTX_BASE_ATTACHED``, and
    404* ``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 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
    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``, and
    432* ``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 as
    440payload:
    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
    454Possible values for ``mode`` are:
    455
    456* ``SDTX_DEVICE_MODE_TABLET``,
    457* ``SDTX_DEVICE_MODE_LAPTOP``, and
    458* ``SDTX_DEVICE_MODE_STUDIO``.
    459
    460Other values are reserved for future use.
    461
    462.. _ioctls:
    463
    464IOCTLs
    465------
    466
    467The 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
    548Defined as ``_IO(0xA5, 0x22)``.
    549
    550Enable events for the current file descriptor. Events can be obtained by
    551reading 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 by
    559reading 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 opening
    567the latch on timeout. The latch is unlocked by default. This command will be
    568silently 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 on
    576timeout. The latch is unlocked by default. This command will not open the
    577latch when sent during an ongoing detachment process. It will be silently
    578ignored 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 no
    586detachment-process is active, detachment is requested. Otherwise the
    587currently active detachment-process will be aborted.
    588
    589If a detachment process is canceled by this operation, a generic detachment
    590request 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 ongoing
    600detachment 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 latch
    602lock is reset to the unlocked state.
    603
    604This command will be silently ignored if there is currently no detachment
    605procedure in progress.
    606
    607``SDTX_IOCTL_LATCH_HEARTBEAT``
    608^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    609
    610Defined as ``_IO(0xA5, 0x27)``.
    611
    612Sends a heartbeat, essentially resetting the detachment timeout. This
    613command can be used to keep the detachment process alive while work required
    614for the detachment to succeed is still in progress.
    615
    616This command will be silently ignored if there is currently no detachment
    617procedure 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 canceled
    625by this operation, a generic detachment request event
    626(``SDTX_EVENT_REQUEST``) will be sent.
    627
    628This command will be silently ignored if there is currently no detachment
    629procedure 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 type
    637of the base connected to the clipboard. This is command essentially provides
    638a way to query the information provided by the base connection change event
    639(``SDTX_EVENT_BASE_CONNECTION``).
    640
    641Possible values for ``struct sdtx_base_info.state`` are:
    642
    643* ``SDTX_BASE_DETACHED``,
    644* ``SDTX_BASE_ATTACHED``, and
    645* ``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 is
    655attached to the clipboard. This is command essentially provides a way to
    656query the information provided by the device mode change event
    657(``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 future
    666use.
    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 when
    675trying to open/close the latch. This is command essentially provides a way
    676to query the information provided by the latch status change event
    677(``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``, and
    685* ``SDTX_ERR_FAILED_TO_CLOSE``.
    686
    687Other values are reserved for future use.
    688
    689A Note on Base IDs
    690------------------
    691
    692Base types/IDs provided via ``SDTX_EVENT_BASE_CONNECTION`` or
    693``SDTX_IOCTL_GET_BASE_INFO`` are directly forwarded from the EC in the lower
    694byte of the combined |__u16| value, with the driver storing the EC type from
    695which this ID comes in the high byte (without this, base IDs over different
    696types of ECs may be overlapping).
    697
    698The ``SDTX_DEVICE_TYPE()`` macro can be used to determine the EC device
    699type. 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
    706Note that currently only the ``SSH`` type EC is supported, however ``HID``
    707type is reserved for future use.
    708
    709Structures and Enums
    710--------------------
    711
    712.. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h
    713
    714API Users
    715=========
    716
    717A user-space daemon utilizing this API can be found at
    718https://github.com/linux-surface/surface-dtx-daemon.