xref: /linux/Documentation/driver-api/surface_aggregator/clients/dtx.rst (revision 8be98d2f2a0a262f8bf8a0bc1fdf522b3c7aab17) 
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.
719