Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: driver-api: Add Surface DTX driver documentation
Add documentation for the user-space interface of the Surface DTX
(detachment system) driver, used on Microsoft Surface Book series
devices.
Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20210308184819.437438-4-luzmaximilian@gmail.com
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
authored by
Maximilian Luz
and committed by
Hans de Goede
f614a1e2
e893d45f
+720
+718
Documentation/driver-api/surface_aggregator/clients/dtx.rst
+718
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.
+1
Documentation/driver-api/surface_aggregator/clients/index.rst
+1
Documentation/driver-api/surface_aggregator/clients/index.rst
+1
MAINTAINERS
+1
MAINTAINERS
···
11865
11865
M: Maximilian Luz <luzmaximilian@gmail.com>
11866
11866
L: platform-driver-x86@vger.kernel.org
11867
11867
S: Maintained
11868
+
F: Documentation/driver-api/surface_aggregator/clients/dtx.rst
11868
11869
F: drivers/platform/surface/surface_dtx.c
11869
11870
F: include/uapi/linux/surface_aggregator/dtx.h
11870
11871