Lines Matching +full:linux +full:- +full:event +full:- +full:codes
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 ------------
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.
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
100 an cancel event (``SDTX_EVENT_CANCEL``) detailing this with the cancel
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
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,
129 press, described below. A *generic request* event (``SDTX_EVENT_REQUEST``)
134 - Do nothing. The detachment process eventually times out as described in
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
148 failures or a low clipboard battery. This is done via a cancel event
152 User-Space Interface Documentation
155 Error Codes and Status Values
156 -----------------------------
158 Error and status codes are divided into different categories, which can be
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.
191 Unknown status or error codes sent by the EC are assigned to the ``UNKNOWN``
195 Currently used error codes are:
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.
272 Again, other codes are reserved for future use.
277 ------
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.
287 Currently provided event types are:
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.
330 (``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space.
339 failure. The reason for cancellation is given in the event payload detailed
355 Other error codes in this context are reserved for future use.
357 These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern
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.
586 detachment-process is active, detachment is requested. Otherwise the
587 currently active detachment-process will be aborted.
590 request event (``SDTX_EVENT_REQUEST``) will be sent.
625 by this operation, a generic detachment request event
638 a way to query the information provided by the base connection change event
656 query the information provided by the device mode change event
676 to query the information provided by the latch status change event
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.