Lines Matching +full:user +full:- +full:defined
1 .. SPDX-License-Identifier: GPL-2.0+
10 User-Space DTX (Clipboard Detachment System) Interface
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
18 unloading/reloading the graphics-driver, user-notifications, etc.
24 change. Commands are always driver-initiated, whereas events are always
56 ------------
60 the *open* state, the clipboard can be removed by a user.
65 being hot-unplugged while in use. More details can be found in the
70 --------------------
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.
76 The detachment process is started with the user pressing the *detach* button
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
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
89 3. The EC waits for instructions from user-space and acts according to them.
93 - If the latch is unlocked, the EC will open the latch and the clipboard
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.
98 - If the latch is locked, the EC will *not* open the latch, meaning the
103 Valid responses by a user-space daemon to a detachment request event are:
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
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.
113 As this changes the latch state, a *latch-status* event
116 error or low battery, a latch-cancel event (``SDTX_EVENT_CANCEL``) will be
122 - Execute ``SDTX_IOCTL_LATCH_HEARTBEAT``. This will reset the internal timeout.
127 - Execute ``SDTX_IOCTL_LATCH_CANCEL``. This will abort the detachment process,
134 - Do nothing. The detachment process eventually times out as described in
139 It is important to note that, if the user presses the detach button at any
141 the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it
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
152 User-Space Interface Documentation
156 -----------------------------
162 .. flat-table:: Overview of Status/Error Categories.
164 :header-rows: 1
166 * - Name
167 - Value
168 - Short Description
170 * - ``STATUS``
171 - ``0x0000``
172 - Non-error status codes.
174 * - ``RUNTIME_ERROR``
175 - ``0x1000``
176 - Non-critical runtime errors.
178 * - ``HARDWARE_ERROR``
179 - ``0x2000``
180 - Critical hardware failures.
182 * - ``UNKNOWN``
183 - ``0xF000``
184 - Unknown error codes.
197 .. flat-table:: Overview of Error Codes.
199 :header-rows: 1
201 * - Name
202 - Category
203 - Value
204 - Short Description
206 * - ``SDTX_DETACH_NOT_FEASIBLE``
207 - ``RUNTIME``
208 - ``0x1001``
209 - Detachment not feasible due to low clipboard battery.
211 * - ``SDTX_DETACH_TIMEDOUT``
212 - ``RUNTIME``
213 - ``0x1002``
214 - Detachment process timed out while the latch was locked.
216 * - ``SDTX_ERR_FAILED_TO_OPEN``
217 - ``HARDWARE``
218 - ``0x2001``
219 - Failed to open latch.
221 * - ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``
222 - ``HARDWARE``
223 - ``0x2002``
224 - Failed to keep latch open.
226 * - ``SDTX_ERR_FAILED_TO_CLOSE``
227 - ``HARDWARE``
228 - ``0x2003``
229 - Failed to close latch.
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:
234 .. flat-table:: Latch Status Codes.
236 :header-rows: 1
238 * - Name
239 - Category
240 - Value
241 - Short Description
243 * - ``SDTX_LATCH_CLOSED``
244 - ``STATUS``
245 - ``0x0000``
246 - Latch is closed/has been closed.
248 * - ``SDTX_LATCH_OPENED``
249 - ``STATUS``
250 - ``0x0001``
251 - Latch is open/has been opened.
253 .. flat-table:: Base State Codes.
255 :header-rows: 1
257 * - Name
258 - Category
259 - Value
260 - Short Description
262 * - ``SDTX_BASE_DETACHED``
263 - ``STATUS``
264 - ``0x0000``
265 - Base has been detached/is not present.
267 * - ``SDTX_BASE_ATTACHED``
268 - ``STATUS``
269 - ``0x0001``
270 - Base has been attached/is present.
277 ------
289 .. flat-table:: Overview of DTX events.
291 :header-rows: 1
293 * - Name
294 - Code
295 - Payload
296 - Short Description
298 * - ``SDTX_EVENT_REQUEST``
299 - ``1``
300 - ``0`` bytes
301 - Detachment process initiated/aborted.
303 * - ``SDTX_EVENT_CANCEL``
304 - ``2``
305 - ``2`` bytes
306 - EC canceled detachment process.
308 * - ``SDTX_EVENT_BASE_CONNECTION``
309 - ``3``
310 - ``4`` bytes
311 - Base connection state changed.
313 * - ``SDTX_EVENT_LATCH_STATUS``
314 - ``4``
315 - ``2`` bytes
316 - Latch status changed.
318 * - ``SDTX_EVENT_DEVICE_MODE``
319 - ``5``
320 - ``2`` bytes
321 - Device mode changed.
329 user, either via a detach button press or a detach request
330 (``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space.
363 .. flat-table:: Detachment Cancel Event Payload
365 :header-rows: 1
367 * - Field
368 - Type
369 - Description
371 * - ``reason``
372 - |__u16|
373 - Reason for cancellation.
384 .. flat-table:: Base-Connection-Change Event Payload
386 :header-rows: 1
388 * - Field
389 - Type
390 - Description
392 * - ``state``
393 - |__u16|
394 - Base connection state.
396 * - ``base_id``
397 - |__u16|
398 - Type of base connected (zero if none).
414 .. flat-table:: Latch-Status-Change Event Payload
416 :header-rows: 1
418 * - Field
419 - Type
420 - Description
422 * - ``status``
423 - |__u16|
424 - Latch status.
442 .. flat-table:: Device-Mode-Change Event Payload
444 :header-rows: 1
446 * - Field
447 - Type
448 - Description
450 * - ``mode``
451 - |__u16|
452 - Device operation mode.
465 ------
469 .. flat-table:: Overview of DTX IOCTLs
471 :header-rows: 1
473 * - Type
474 - Number
475 - Direction
476 - Name
477 - Description
479 * - ``0xA5``
480 - ``0x21``
481 - ``-``
482 - ``EVENTS_ENABLE``
483 - Enable events for the current file descriptor.
485 * - ``0xA5``
486 - ``0x22``
487 - ``-``
488 - ``EVENTS_DISABLE``
489 - Disable events for the current file descriptor.
491 * - ``0xA5``
492 - ``0x23``
493 - ``-``
494 - ``LATCH_LOCK``
495 - Lock the latch.
497 * - ``0xA5``
498 - ``0x24``
499 - ``-``
500 - ``LATCH_UNLOCK``
501 - Unlock the latch.
503 * - ``0xA5``
504 - ``0x25``
505 - ``-``
506 - ``LATCH_REQUEST``
507 - Request clipboard detachment.
509 * - ``0xA5``
510 - ``0x26``
511 - ``-``
512 - ``LATCH_CONFIRM``
513 - Confirm clipboard detachment request.
515 * - ``0xA5``
516 - ``0x27``
517 - ``-``
518 - ``LATCH_HEARTBEAT``
519 - Send heartbeat signal to EC.
521 * - ``0xA5``
522 - ``0x28``
523 - ``-``
524 - ``LATCH_CANCEL``
525 - Cancel detachment process.
527 * - ``0xA5``
528 - ``0x29``
529 - ``R``
530 - ``GET_BASE_INFO``
531 - Get current base/connection information.
533 * - ``0xA5``
534 - ``0x2A``
535 - ``R``
536 - ``GET_DEVICE_MODE``
537 - Get current device operation mode.
539 * - ``0xA5``
540 - ``0x2B``
541 - ``R``
542 - ``GET_LATCH_STATUS``
543 - Get current device latch status.
548 Defined as ``_IO(0xA5, 0x22)``.
556 Defined as ``_IO(0xA5, 0x22)``.
564 Defined as ``_IO(0xA5, 0x23)``.
573 Defined as ``_IO(0xA5, 0x24)``.
583 Defined as ``_IO(0xA5, 0x25)``.
586 detachment-process is active, detachment is requested. Otherwise the
587 currently active detachment-process will be aborted.
597 Defined as ``_IO(0xA5, 0x26)``.
610 Defined as ``_IO(0xA5, 0x27)``.
622 Defined as ``_IO(0xA5, 0x28)``.
634 Defined as ``_IOR(0xA5, 0x29, struct sdtx_base_info)``.
652 Defined as ``_IOR(0xA5, 0x2A, __u16)``.
672 Defined as ``_IOR(0xA5, 0x2B, __u16)``.
690 ------------------
710 --------------------
712 .. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h
717 A user-space daemon utilizing this API can be found at
718 https://github.com/linux-surface/surface-dtx-daemon.