0001 .. SPDX-License-Identifier: GPL-2.0+
0002
0003 .. |__u16| replace:: :c:type:`__u16 <__u16>`
0004 .. |sdtx_event| replace:: :c:type:`struct sdtx_event <sdtx_event>`
0005 .. |sdtx_event_code| replace:: :c:type:`enum sdtx_event_code <sdtx_event_code>`
0006 .. |sdtx_base_info| replace:: :c:type:`struct sdtx_base_info <sdtx_base_info>`
0007 .. |sdtx_device_mode| replace:: :c:type:`struct sdtx_device_mode <sdtx_device_mode>`
0008
0009 ======================================================
0010 User-Space DTX (Clipboard Detachment System) Interface
0011 ======================================================
0012
0013 The ``surface_dtx`` driver is responsible for proper clipboard detachment
0014 and re-attachment handling. To this end, it provides the ``/dev/surface/dtx``
0015 device file, through which it can interface with a user-space daemon. This
0016 daemon is then ultimately responsible for determining and taking necessary
0017 actions, such as unmounting devices attached to the base,
0018 unloading/reloading the graphics-driver, user-notifications, etc.
0019
0020 There are two basic communication principles used in this driver: Commands
0021 (in other parts of the documentation also referred to as requests) and
0022 events. Commands are sent to the EC and may have a different implications in
0023 different contexts. Events are sent by the EC upon some internal state
0024 change. Commands are always driver-initiated, whereas events are always
0025 initiated by the EC.
0026
0027 .. contents::
0028
0029 Nomenclature
0030 ============
0031
0032 * **Clipboard:**
0033 The detachable upper part of the Surface Book, housing the screen and CPU.
0034
0035 * **Base:**
0036 The lower part of the Surface Book from which the clipboard can be
0037 detached, optionally (model dependent) housing the discrete GPU (dGPU).
0038
0039 * **Latch:**
0040 The mechanism keeping the clipboard attached to the base in normal
0041 operation and allowing it to be detached when requested.
0042
0043 * **Silently ignored commands:**
0044 The command is accepted by the EC as a valid command and acknowledged
0045 (following the standard communication protocol), but the EC does not act
0046 upon it, i.e. ignores it.e upper part of the
0047
0048
0049 Detachment Process
0050 ==================
0051
0052 Warning: This part of the documentation is based on reverse engineering and
0053 testing and thus may contain errors or be incomplete.
0054
0055 Latch States
0056 ------------
0057
0058 The latch mechanism has two major states: *open* and *closed*. In the
0059 *closed* state (default), the clipboard is secured to the base, whereas in
0060 the *open* state, the clipboard can be removed by a user.
0061
0062 The latch can additionally be locked and, correspondingly, unlocked, which
0063 can influence the detachment procedure. Specifically, this locking mechanism
0064 is intended to prevent the dGPU, positioned in the base of the device, from
0065 being hot-unplugged while in use. More details can be found in the
0066 documentation for the detachment procedure below. By default, the latch is
0067 unlocked.
0068
0069 Detachment Procedure
0070 --------------------
0071
0072 Note that the detachment process is governed fully by the EC. The
0073 ``surface_dtx`` driver only relays events from the EC to user-space and
0074 commands from user-space to the EC, i.e. it does not influence this process.
0075
0076 The detachment process is started with the user pressing the *detach* button
0077 on the base of the device or executing the ``SDTX_IOCTL_LATCH_REQUEST`` IOCTL.
0078 Following that:
0079
0080 1. The EC turns on the indicator led on the detach-button, sends a
0081 *detach-request* event (``SDTX_EVENT_REQUEST``), and awaits further
0082 instructions/commands. In case the latch is unlocked, the led will flash
0083 green. If the latch has been locked, the led will be solid red
0084
0085 2. The event is, via the ``surface_dtx`` driver, relayed to user-space, where
0086 an appropriate user-space daemon can handle it and send instructions back
0087 to the EC via IOCTLs provided by this driver.
0088
0089 3. The EC waits for instructions from user-space and acts according to them.
0090 If the EC does not receive any instructions in a given period, it will
0091 time out and continue as follows:
0092
0093 - If the latch is unlocked, the EC will open the latch and the clipboard
0094 can be detached from the base. This is the exact behavior as without
0095 this driver or any user-space daemon. See the ``SDTX_IOCTL_LATCH_CONFIRM``
0096 description below for more details on the follow-up behavior of the EC.
0097
0098 - If the latch is locked, the EC will *not* open the latch, meaning the
0099 clipboard cannot be detached from the base. Furthermore, the EC sends
0100 an cancel event (``SDTX_EVENT_CANCEL``) detailing this with the cancel
0101 reason ``SDTX_DETACH_TIMEDOUT`` (see :ref:`events` for details).
0102
0103 Valid responses by a user-space daemon to a detachment request event are:
0104
0105 - Execute ``SDTX_IOCTL_LATCH_REQUEST``. This will immediately abort the
0106 detachment process. Furthermore, the EC will send a detach-request event,
0107 similar to the user pressing the detach-button to cancel said process (see
0108 below).
0109
0110 - Execute ``SDTX_IOCTL_LATCH_CONFIRM``. This will cause the EC to open the
0111 latch, after which the user can separate clipboard and base.
0112
0113 As this changes the latch state, a *latch-status* event
0114 (``SDTX_EVENT_LATCH_STATUS``) will be sent once the latch has been opened
0115 successfully. If the EC fails to open the latch, e.g. due to hardware
0116 error or low battery, a latch-cancel event (``SDTX_EVENT_CANCEL``) will be
0117 sent with the cancel reason indicating the specific failure.
0118
0119 If the latch is currently locked, the latch will automatically be
0120 unlocked before it is opened.
0121
0122 - Execute ``SDTX_IOCTL_LATCH_HEARTBEAT``. This will reset the internal timeout.
0123 No other actions will be performed, i.e. the detachment process will neither
0124 be completed nor canceled, and the EC will still be waiting for further
0125 responses.
0126
0127 - Execute ``SDTX_IOCTL_LATCH_CANCEL``. This will abort the detachment process,
0128 similar to ``SDTX_IOCTL_LATCH_REQUEST``, described above, or the button
0129 press, described below. A *generic request* event (``SDTX_EVENT_REQUEST``)
0130 is send in response to this. In contrast to those, however, this command
0131 does not trigger a new detachment process if none is currently in
0132 progress.
0133
0134 - Do nothing. The detachment process eventually times out as described in
0135 point 3.
0136
0137 See :ref:`ioctls` for more details on these responses.
0138
0139 It is important to note that, if the user presses the detach button at any
0140 point when a detachment operation is in progress (i.e. after the EC has sent
0141 the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it
0142 received the corresponding response concluding the process), the detachment
0143 process is canceled on the EC-level and an identical event is being sent.
0144 Thus a *detach-request* event, by itself, does not signal the start of the
0145 detachment process.
0146
0147 The detachment process may further be canceled by the EC due to hardware
0148 failures or a low clipboard battery. This is done via a cancel event
0149 (``SDTX_EVENT_CANCEL``) with the corresponding cancel reason.
0150
0151
0152 User-Space Interface Documentation
0153 ==================================
0154
0155 Error Codes and Status Values
0156 -----------------------------
0157
0158 Error and status codes are divided into different categories, which can be
0159 used to determine if the status code is an error, and, if it is, the
0160 severity and type of that error. The current categories are:
0161
0162 .. flat-table:: Overview of Status/Error Categories.
0163 :widths: 2 1 3
0164 :header-rows: 1
0165
0166 * - Name
0167 - Value
0168 - Short Description
0169
0170 * - ``STATUS``
0171 - ``0x0000``
0172 - Non-error status codes.
0173
0174 * - ``RUNTIME_ERROR``
0175 - ``0x1000``
0176 - Non-critical runtime errors.
0177
0178 * - ``HARDWARE_ERROR``
0179 - ``0x2000``
0180 - Critical hardware failures.
0181
0182 * - ``UNKNOWN``
0183 - ``0xF000``
0184 - Unknown error codes.
0185
0186 Other categories are reserved for future use. The ``SDTX_CATEGORY()`` macro
0187 can be used to determine the category of any status value. The
0188 ``SDTX_SUCCESS()`` macro can be used to check if the status value is a
0189 success value (``SDTX_CATEGORY_STATUS``) or if it indicates a failure.
0190
0191 Unknown status or error codes sent by the EC are assigned to the ``UNKNOWN``
0192 category by the driver and may be implemented via their own code in the
0193 future.
0194
0195 Currently used error codes are:
0196
0197 .. flat-table:: Overview of Error Codes.
0198 :widths: 2 1 1 3
0199 :header-rows: 1
0200
0201 * - Name
0202 - Category
0203 - Value
0204 - Short Description
0205
0206 * - ``SDTX_DETACH_NOT_FEASIBLE``
0207 - ``RUNTIME``
0208 - ``0x1001``
0209 - Detachment not feasible due to low clipboard battery.
0210
0211 * - ``SDTX_DETACH_TIMEDOUT``
0212 - ``RUNTIME``
0213 - ``0x1002``
0214 - Detachment process timed out while the latch was locked.
0215
0216 * - ``SDTX_ERR_FAILED_TO_OPEN``
0217 - ``HARDWARE``
0218 - ``0x2001``
0219 - Failed to open latch.
0220
0221 * - ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``
0222 - ``HARDWARE``
0223 - ``0x2002``
0224 - Failed to keep latch open.
0225
0226 * - ``SDTX_ERR_FAILED_TO_CLOSE``
0227 - ``HARDWARE``
0228 - ``0x2003``
0229 - Failed to close latch.
0230
0231 Other error codes are reserved for future use. Non-error status codes may
0232 overlap and are generally only unique within their use-case:
0233
0234 .. flat-table:: Latch Status Codes.
0235 :widths: 2 1 1 3
0236 :header-rows: 1
0237
0238 * - Name
0239 - Category
0240 - Value
0241 - Short Description
0242
0243 * - ``SDTX_LATCH_CLOSED``
0244 - ``STATUS``
0245 - ``0x0000``
0246 - Latch is closed/has been closed.
0247
0248 * - ``SDTX_LATCH_OPENED``
0249 - ``STATUS``
0250 - ``0x0001``
0251 - Latch is open/has been opened.
0252
0253 .. flat-table:: Base State Codes.
0254 :widths: 2 1 1 3
0255 :header-rows: 1
0256
0257 * - Name
0258 - Category
0259 - Value
0260 - Short Description
0261
0262 * - ``SDTX_BASE_DETACHED``
0263 - ``STATUS``
0264 - ``0x0000``
0265 - Base has been detached/is not present.
0266
0267 * - ``SDTX_BASE_ATTACHED``
0268 - ``STATUS``
0269 - ``0x0001``
0270 - Base has been attached/is present.
0271
0272 Again, other codes are reserved for future use.
0273
0274 .. _events:
0275
0276 Events
0277 ------
0278
0279 Events can be received by reading from the device file. They are disabled by
0280 default and have to be enabled by executing ``SDTX_IOCTL_EVENTS_ENABLE``
0281 first. All events follow the layout prescribed by |sdtx_event|. Specific
0282 event types can be identified by their event code, described in
0283 |sdtx_event_code|. Note that other event codes are reserved for future use,
0284 thus an event parser must be able to handle any unknown/unsupported event
0285 types gracefully, by relying on the payload length given in the event header.
0286
0287 Currently provided event types are:
0288
0289 .. flat-table:: Overview of DTX events.
0290 :widths: 2 1 1 3
0291 :header-rows: 1
0292
0293 * - Name
0294 - Code
0295 - Payload
0296 - Short Description
0297
0298 * - ``SDTX_EVENT_REQUEST``
0299 - ``1``
0300 - ``0`` bytes
0301 - Detachment process initiated/aborted.
0302
0303 * - ``SDTX_EVENT_CANCEL``
0304 - ``2``
0305 - ``2`` bytes
0306 - EC canceled detachment process.
0307
0308 * - ``SDTX_EVENT_BASE_CONNECTION``
0309 - ``3``
0310 - ``4`` bytes
0311 - Base connection state changed.
0312
0313 * - ``SDTX_EVENT_LATCH_STATUS``
0314 - ``4``
0315 - ``2`` bytes
0316 - Latch status changed.
0317
0318 * - ``SDTX_EVENT_DEVICE_MODE``
0319 - ``5``
0320 - ``2`` bytes
0321 - Device mode changed.
0322
0323 Individual events in more detail:
0324
0325 ``SDTX_EVENT_REQUEST``
0326 ^^^^^^^^^^^^^^^^^^^^^^
0327
0328 Sent when a detachment process is started or, if in progress, aborted by the
0329 user, either via a detach button press or a detach request
0330 (``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space.
0331
0332 Does not have any payload.
0333
0334 ``SDTX_EVENT_CANCEL``
0335 ^^^^^^^^^^^^^^^^^^^^^
0336
0337 Sent when a detachment process is canceled by the EC due to unfulfilled
0338 preconditions (e.g. clipboard battery too low to detach) or hardware
0339 failure. The reason for cancellation is given in the event payload detailed
0340 below and can be one of
0341
0342 * ``SDTX_DETACH_TIMEDOUT``: Detachment timed out while the latch was locked.
0343 The latch has neither been opened nor unlocked.
0344
0345 * ``SDTX_DETACH_NOT_FEASIBLE``: Detachment not feasible due to low clipboard
0346 battery.
0347
0348 * ``SDTX_ERR_FAILED_TO_OPEN``: Could not open the latch (hardware failure).
0349
0350 * ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``: Could not keep the latch open (hardware
0351 failure).
0352
0353 * ``SDTX_ERR_FAILED_TO_CLOSE``: Could not close the latch (hardware failure).
0354
0355 Other error codes in this context are reserved for future use.
0356
0357 These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern
0358 between critical hardware errors (``SDTX_CATEGORY_HARDWARE_ERROR``) or
0359 runtime errors (``SDTX_CATEGORY_RUNTIME_ERROR``), the latter of which may
0360 happen during normal operation if certain preconditions for detachment are
0361 not given.
0362
0363 .. flat-table:: Detachment Cancel Event Payload
0364 :widths: 1 1 4
0365 :header-rows: 1
0366
0367 * - Field
0368 - Type
0369 - Description
0370
0371 * - ``reason``
0372 - |__u16|
0373 - Reason for cancellation.
0374
0375 ``SDTX_EVENT_BASE_CONNECTION``
0376 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0377
0378 Sent when the base connection state has changed, i.e. when the base has been
0379 attached, detached, or detachment has become infeasible due to low clipboard
0380 battery. The new state and, if a base is connected, ID of the base is
0381 provided as payload of type |sdtx_base_info| with its layout presented
0382 below:
0383
0384 .. flat-table:: Base-Connection-Change Event Payload
0385 :widths: 1 1 4
0386 :header-rows: 1
0387
0388 * - Field
0389 - Type
0390 - Description
0391
0392 * - ``state``
0393 - |__u16|
0394 - Base connection state.
0395
0396 * - ``base_id``
0397 - |__u16|
0398 - Type of base connected (zero if none).
0399
0400 Possible values for ``state`` are:
0401
0402 * ``SDTX_BASE_DETACHED``,
0403 * ``SDTX_BASE_ATTACHED``, and
0404 * ``SDTX_DETACH_NOT_FEASIBLE``.
0405
0406 Other values are reserved for future use.
0407
0408 ``SDTX_EVENT_LATCH_STATUS``
0409 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
0410
0411 Sent when the latch status has changed, i.e. when the latch has been opened,
0412 closed, or an error occurred. The current status is provided as payload:
0413
0414 .. flat-table:: Latch-Status-Change Event Payload
0415 :widths: 1 1 4
0416 :header-rows: 1
0417
0418 * - Field
0419 - Type
0420 - Description
0421
0422 * - ``status``
0423 - |__u16|
0424 - Latch status.
0425
0426 Possible values for ``status`` are:
0427
0428 * ``SDTX_LATCH_CLOSED``,
0429 * ``SDTX_LATCH_OPENED``,
0430 * ``SDTX_ERR_FAILED_TO_OPEN``,
0431 * ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and
0432 * ``SDTX_ERR_FAILED_TO_CLOSE``.
0433
0434 Other values are reserved for future use.
0435
0436 ``SDTX_EVENT_DEVICE_MODE``
0437 ^^^^^^^^^^^^^^^^^^^^^^^^^^
0438
0439 Sent when the device mode has changed. The new device mode is provided as
0440 payload:
0441
0442 .. flat-table:: Device-Mode-Change Event Payload
0443 :widths: 1 1 4
0444 :header-rows: 1
0445
0446 * - Field
0447 - Type
0448 - Description
0449
0450 * - ``mode``
0451 - |__u16|
0452 - Device operation mode.
0453
0454 Possible values for ``mode`` are:
0455
0456 * ``SDTX_DEVICE_MODE_TABLET``,
0457 * ``SDTX_DEVICE_MODE_LAPTOP``, and
0458 * ``SDTX_DEVICE_MODE_STUDIO``.
0459
0460 Other values are reserved for future use.
0461
0462 .. _ioctls:
0463
0464 IOCTLs
0465 ------
0466
0467 The following IOCTLs are provided:
0468
0469 .. flat-table:: Overview of DTX IOCTLs
0470 :widths: 1 1 1 1 4
0471 :header-rows: 1
0472
0473 * - Type
0474 - Number
0475 - Direction
0476 - Name
0477 - Description
0478
0479 * - ``0xA5``
0480 - ``0x21``
0481 - ``-``
0482 - ``EVENTS_ENABLE``
0483 - Enable events for the current file descriptor.
0484
0485 * - ``0xA5``
0486 - ``0x22``
0487 - ``-``
0488 - ``EVENTS_DISABLE``
0489 - Disable events for the current file descriptor.
0490
0491 * - ``0xA5``
0492 - ``0x23``
0493 - ``-``
0494 - ``LATCH_LOCK``
0495 - Lock the latch.
0496
0497 * - ``0xA5``
0498 - ``0x24``
0499 - ``-``
0500 - ``LATCH_UNLOCK``
0501 - Unlock the latch.
0502
0503 * - ``0xA5``
0504 - ``0x25``
0505 - ``-``
0506 - ``LATCH_REQUEST``
0507 - Request clipboard detachment.
0508
0509 * - ``0xA5``
0510 - ``0x26``
0511 - ``-``
0512 - ``LATCH_CONFIRM``
0513 - Confirm clipboard detachment request.
0514
0515 * - ``0xA5``
0516 - ``0x27``
0517 - ``-``
0518 - ``LATCH_HEARTBEAT``
0519 - Send heartbeat signal to EC.
0520
0521 * - ``0xA5``
0522 - ``0x28``
0523 - ``-``
0524 - ``LATCH_CANCEL``
0525 - Cancel detachment process.
0526
0527 * - ``0xA5``
0528 - ``0x29``
0529 - ``R``
0530 - ``GET_BASE_INFO``
0531 - Get current base/connection information.
0532
0533 * - ``0xA5``
0534 - ``0x2A``
0535 - ``R``
0536 - ``GET_DEVICE_MODE``
0537 - Get current device operation mode.
0538
0539 * - ``0xA5``
0540 - ``0x2B``
0541 - ``R``
0542 - ``GET_LATCH_STATUS``
0543 - Get current device latch status.
0544
0545 ``SDTX_IOCTL_EVENTS_ENABLE``
0546 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0547
0548 Defined as ``_IO(0xA5, 0x22)``.
0549
0550 Enable events for the current file descriptor. Events can be obtained by
0551 reading from the device, if enabled. Events are disabled by default.
0552
0553 ``SDTX_IOCTL_EVENTS_DISABLE``
0554 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0555
0556 Defined as ``_IO(0xA5, 0x22)``.
0557
0558 Disable events for the current file descriptor. Events can be obtained by
0559 reading from the device, if enabled. Events are disabled by default.
0560
0561 ``SDTX_IOCTL_LATCH_LOCK``
0562 ^^^^^^^^^^^^^^^^^^^^^^^^^
0563
0564 Defined as ``_IO(0xA5, 0x23)``.
0565
0566 Locks the latch, causing the detachment procedure to abort without opening
0567 the latch on timeout. The latch is unlocked by default. This command will be
0568 silently ignored if the latch is already locked.
0569
0570 ``SDTX_IOCTL_LATCH_UNLOCK``
0571 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
0572
0573 Defined as ``_IO(0xA5, 0x24)``.
0574
0575 Unlocks the latch, causing the detachment procedure to open the latch on
0576 timeout. The latch is unlocked by default. This command will not open the
0577 latch when sent during an ongoing detachment process. It will be silently
0578 ignored if the latch is already unlocked.
0579
0580 ``SDTX_IOCTL_LATCH_REQUEST``
0581 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0582
0583 Defined as ``_IO(0xA5, 0x25)``.
0584
0585 Generic latch request. Behavior depends on the context: If no
0586 detachment-process is active, detachment is requested. Otherwise the
0587 currently active detachment-process will be aborted.
0588
0589 If a detachment process is canceled by this operation, a generic detachment
0590 request event (``SDTX_EVENT_REQUEST``) will be sent.
0591
0592 This essentially behaves the same as a detachment button press.
0593
0594 ``SDTX_IOCTL_LATCH_CONFIRM``
0595 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0596
0597 Defined as ``_IO(0xA5, 0x26)``.
0598
0599 Acknowledges and confirms a latch request. If sent during an ongoing
0600 detachment process, this command causes the latch to be opened immediately.
0601 The latch will also be opened if it has been locked. In this case, the latch
0602 lock is reset to the unlocked state.
0603
0604 This command will be silently ignored if there is currently no detachment
0605 procedure in progress.
0606
0607 ``SDTX_IOCTL_LATCH_HEARTBEAT``
0608 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0609
0610 Defined as ``_IO(0xA5, 0x27)``.
0611
0612 Sends a heartbeat, essentially resetting the detachment timeout. This
0613 command can be used to keep the detachment process alive while work required
0614 for the detachment to succeed is still in progress.
0615
0616 This command will be silently ignored if there is currently no detachment
0617 procedure in progress.
0618
0619 ``SDTX_IOCTL_LATCH_CANCEL``
0620 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
0621
0622 Defined as ``_IO(0xA5, 0x28)``.
0623
0624 Cancels detachment in progress (if any). If a detachment process is canceled
0625 by this operation, a generic detachment request event
0626 (``SDTX_EVENT_REQUEST``) will be sent.
0627
0628 This command will be silently ignored if there is currently no detachment
0629 procedure in progress.
0630
0631 ``SDTX_IOCTL_GET_BASE_INFO``
0632 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0633
0634 Defined as ``_IOR(0xA5, 0x29, struct sdtx_base_info)``.
0635
0636 Get the current base connection state (i.e. attached/detached) and the type
0637 of the base connected to the clipboard. This is command essentially provides
0638 a way to query the information provided by the base connection change event
0639 (``SDTX_EVENT_BASE_CONNECTION``).
0640
0641 Possible values for ``struct sdtx_base_info.state`` are:
0642
0643 * ``SDTX_BASE_DETACHED``,
0644 * ``SDTX_BASE_ATTACHED``, and
0645 * ``SDTX_DETACH_NOT_FEASIBLE``.
0646
0647 Other values are reserved for future use.
0648
0649 ``SDTX_IOCTL_GET_DEVICE_MODE``
0650 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0651
0652 Defined as ``_IOR(0xA5, 0x2A, __u16)``.
0653
0654 Returns the device operation mode, indicating if and how the base is
0655 attached to the clipboard. This is command essentially provides a way to
0656 query the information provided by the device mode change event
0657 (``SDTX_EVENT_DEVICE_MODE``).
0658
0659 Returned values are:
0660
0661 * ``SDTX_DEVICE_MODE_LAPTOP``
0662 * ``SDTX_DEVICE_MODE_TABLET``
0663 * ``SDTX_DEVICE_MODE_STUDIO``
0664
0665 See |sdtx_device_mode| for details. Other values are reserved for future
0666 use.
0667
0668
0669 ``SDTX_IOCTL_GET_LATCH_STATUS``
0670 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0671
0672 Defined as ``_IOR(0xA5, 0x2B, __u16)``.
0673
0674 Get the current latch status or (presumably) the last error encountered when
0675 trying to open/close the latch. This is command essentially provides a way
0676 to query the information provided by the latch status change event
0677 (``SDTX_EVENT_LATCH_STATUS``).
0678
0679 Returned values are:
0680
0681 * ``SDTX_LATCH_CLOSED``,
0682 * ``SDTX_LATCH_OPENED``,
0683 * ``SDTX_ERR_FAILED_TO_OPEN``,
0684 * ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and
0685 * ``SDTX_ERR_FAILED_TO_CLOSE``.
0686
0687 Other values are reserved for future use.
0688
0689 A Note on Base IDs
0690 ------------------
0691
0692 Base types/IDs provided via ``SDTX_EVENT_BASE_CONNECTION`` or
0693 ``SDTX_IOCTL_GET_BASE_INFO`` are directly forwarded from the EC in the lower
0694 byte of the combined |__u16| value, with the driver storing the EC type from
0695 which this ID comes in the high byte (without this, base IDs over different
0696 types of ECs may be overlapping).
0697
0698 The ``SDTX_DEVICE_TYPE()`` macro can be used to determine the EC device
0699 type. This can be one of
0700
0701 * ``SDTX_DEVICE_TYPE_HID``, for Surface Aggregator Module over HID, and
0702
0703 * ``SDTX_DEVICE_TYPE_SSH``, for Surface Aggregator Module over Surface Serial
0704 Hub.
0705
0706 Note that currently only the ``SSH`` type EC is supported, however ``HID``
0707 type is reserved for future use.
0708
0709 Structures and Enums
0710 --------------------
0711
0712 .. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h
0713
0714 API Users
0715 =========
0716
0717 A user-space daemon utilizing this API can be found at
0718 https://github.com/linux-surface/surface-dtx-daemon.
