1 | /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */ |
2 | /* |
3 | * Surface DTX (clipboard detachment system driver) user-space interface. |
4 | * |
5 | * Definitions, structs, and IOCTLs for the /dev/surface/dtx misc device. This |
6 | * device allows user-space to control the clipboard detachment process on |
7 | * Surface Book series devices. |
8 | * |
9 | * Copyright (C) 2020-2021 Maximilian Luz <luzmaximilian@gmail.com> |
10 | */ |
11 | |
12 | #ifndef _UAPI_LINUX_SURFACE_AGGREGATOR_DTX_H |
13 | #define _UAPI_LINUX_SURFACE_AGGREGATOR_DTX_H |
14 | |
15 | #include <linux/ioctl.h> |
16 | #include <linux/types.h> |
17 | |
18 | /* Status/error categories */ |
19 | #define SDTX_CATEGORY_STATUS 0x0000 |
20 | #define SDTX_CATEGORY_RUNTIME_ERROR 0x1000 |
21 | #define SDTX_CATEGORY_HARDWARE_ERROR 0x2000 |
22 | #define SDTX_CATEGORY_UNKNOWN 0xf000 |
23 | |
24 | #define SDTX_CATEGORY_MASK 0xf000 |
25 | #define SDTX_CATEGORY(value) ((value) & SDTX_CATEGORY_MASK) |
26 | |
27 | #define SDTX_STATUS(code) ((code) | SDTX_CATEGORY_STATUS) |
28 | #define SDTX_ERR_RT(code) ((code) | SDTX_CATEGORY_RUNTIME_ERROR) |
29 | #define SDTX_ERR_HW(code) ((code) | SDTX_CATEGORY_HARDWARE_ERROR) |
30 | #define SDTX_UNKNOWN(code) ((code) | SDTX_CATEGORY_UNKNOWN) |
31 | |
32 | #define SDTX_SUCCESS(value) (SDTX_CATEGORY(value) == SDTX_CATEGORY_STATUS) |
33 | |
34 | /* Latch status values */ |
35 | #define SDTX_LATCH_CLOSED SDTX_STATUS(0x00) |
36 | #define SDTX_LATCH_OPENED SDTX_STATUS(0x01) |
37 | |
38 | /* Base state values */ |
39 | #define SDTX_BASE_DETACHED SDTX_STATUS(0x00) |
40 | #define SDTX_BASE_ATTACHED SDTX_STATUS(0x01) |
41 | |
42 | /* Runtime errors (non-critical) */ |
43 | #define SDTX_DETACH_NOT_FEASIBLE SDTX_ERR_RT(0x01) |
44 | #define SDTX_DETACH_TIMEDOUT SDTX_ERR_RT(0x02) |
45 | |
46 | /* Hardware errors (critical) */ |
47 | #define SDTX_ERR_FAILED_TO_OPEN SDTX_ERR_HW(0x01) |
48 | #define SDTX_ERR_FAILED_TO_REMAIN_OPEN SDTX_ERR_HW(0x02) |
49 | #define SDTX_ERR_FAILED_TO_CLOSE SDTX_ERR_HW(0x03) |
50 | |
51 | /* Base types */ |
52 | #define SDTX_DEVICE_TYPE_HID 0x0100 |
53 | #define SDTX_DEVICE_TYPE_SSH 0x0200 |
54 | |
55 | #define SDTX_DEVICE_TYPE_MASK 0x0f00 |
56 | #define SDTX_DEVICE_TYPE(value) ((value) & SDTX_DEVICE_TYPE_MASK) |
57 | |
58 | #define SDTX_BASE_TYPE_HID(id) ((id) | SDTX_DEVICE_TYPE_HID) |
59 | #define SDTX_BASE_TYPE_SSH(id) ((id) | SDTX_DEVICE_TYPE_SSH) |
60 | |
61 | /** |
62 | * enum sdtx_device_mode - Mode describing how (and if) the clipboard is |
63 | * attached to the base of the device. |
64 | * @SDTX_DEVICE_MODE_TABLET: The clipboard is detached from the base and the |
65 | * device operates as tablet. |
66 | * @SDTX_DEVICE_MODE_LAPTOP: The clipboard is attached normally to the base |
67 | * and the device operates as laptop. |
68 | * @SDTX_DEVICE_MODE_STUDIO: The clipboard is attached to the base in reverse. |
69 | * The device operates as tablet with keyboard and |
70 | * touchpad deactivated, however, the base battery |
71 | * and, if present in the specific device model, dGPU |
72 | * are available to the system. |
73 | */ |
74 | enum sdtx_device_mode { |
75 | SDTX_DEVICE_MODE_TABLET = 0x00, |
76 | SDTX_DEVICE_MODE_LAPTOP = 0x01, |
77 | SDTX_DEVICE_MODE_STUDIO = 0x02, |
78 | }; |
79 | |
80 | /** |
81 | * struct sdtx_event - Event provided by reading from the DTX device file. |
82 | * @length: Length of the event payload, in bytes. |
83 | * @code: Event code, detailing what type of event this is. |
84 | * @data: Payload of the event, containing @length bytes. |
85 | * |
86 | * See &enum sdtx_event_code for currently valid event codes. |
87 | */ |
88 | struct sdtx_event { |
89 | __u16 length; |
90 | __u16 code; |
91 | __u8 data[]; |
92 | } __attribute__((__packed__)); |
93 | |
94 | /** |
95 | * enum sdtx_event_code - Code describing the type of an event. |
96 | * @SDTX_EVENT_REQUEST: Detachment request event type. |
97 | * @SDTX_EVENT_CANCEL: Cancel detachment process event type. |
98 | * @SDTX_EVENT_BASE_CONNECTION: Base/clipboard connection change event type. |
99 | * @SDTX_EVENT_LATCH_STATUS: Latch status change event type. |
100 | * @SDTX_EVENT_DEVICE_MODE: Device mode change event type. |
101 | * |
102 | * Used in &struct sdtx_event to describe the type of the event. Further event |
103 | * codes are reserved for future use. Any event parser should be able to |
104 | * gracefully handle unknown events, i.e. by simply skipping them. |
105 | * |
106 | * Consult the DTX user-space interface documentation for details regarding |
107 | * the individual event types. |
108 | */ |
109 | enum sdtx_event_code { |
110 | SDTX_EVENT_REQUEST = 1, |
111 | SDTX_EVENT_CANCEL = 2, |
112 | SDTX_EVENT_BASE_CONNECTION = 3, |
113 | SDTX_EVENT_LATCH_STATUS = 4, |
114 | SDTX_EVENT_DEVICE_MODE = 5, |
115 | }; |
116 | |
117 | /** |
118 | * struct sdtx_base_info - Describes if and what type of base is connected. |
119 | * @state: The state of the connection. Valid values are %SDTX_BASE_DETACHED, |
120 | * %SDTX_BASE_ATTACHED, and %SDTX_DETACH_NOT_FEASIBLE (in case a base |
121 | * is attached but low clipboard battery prevents detachment). Other |
122 | * values are currently reserved. |
123 | * @base_id: The type of base connected. Zero if no base is connected. |
124 | */ |
125 | struct sdtx_base_info { |
126 | __u16 state; |
127 | __u16 base_id; |
128 | } __attribute__((__packed__)); |
129 | |
130 | /* IOCTLs */ |
131 | #define SDTX_IOCTL_EVENTS_ENABLE _IO(0xa5, 0x21) |
132 | #define SDTX_IOCTL_EVENTS_DISABLE _IO(0xa5, 0x22) |
133 | |
134 | #define SDTX_IOCTL_LATCH_LOCK _IO(0xa5, 0x23) |
135 | #define SDTX_IOCTL_LATCH_UNLOCK _IO(0xa5, 0x24) |
136 | |
137 | #define SDTX_IOCTL_LATCH_REQUEST _IO(0xa5, 0x25) |
138 | #define SDTX_IOCTL_LATCH_CONFIRM _IO(0xa5, 0x26) |
139 | #define SDTX_IOCTL_LATCH_HEARTBEAT _IO(0xa5, 0x27) |
140 | #define SDTX_IOCTL_LATCH_CANCEL _IO(0xa5, 0x28) |
141 | |
142 | #define SDTX_IOCTL_GET_BASE_INFO _IOR(0xa5, 0x29, struct sdtx_base_info) |
143 | #define SDTX_IOCTL_GET_DEVICE_MODE _IOR(0xa5, 0x2a, __u16) |
144 | #define SDTX_IOCTL_GET_LATCH_STATUS _IOR(0xa5, 0x2b, __u16) |
145 | |
146 | #endif /* _UAPI_LINUX_SURFACE_AGGREGATOR_DTX_H */ |
147 | |