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