1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
2 | /* |
3 | * HID driver for UC-Logic devices not fully compliant with HID standard |
4 | * - tablet initialization and parameter retrieval |
5 | * |
6 | * Copyright (c) 2018 Nikolai Kondrashov |
7 | */ |
8 | |
9 | /* |
10 | * This program is free software; you can redistribute it and/or modify it |
11 | * under the terms of the GNU General Public License as published by the Free |
12 | * Software Foundation; either version 2 of the License, or (at your option) |
13 | * any later version. |
14 | */ |
15 | |
16 | #ifndef _HID_UCLOGIC_PARAMS_H |
17 | #define _HID_UCLOGIC_PARAMS_H |
18 | |
19 | #include <linux/usb.h> |
20 | #include <linux/hid.h> |
21 | #include <linux/list.h> |
22 | |
23 | #define UCLOGIC_MOUSE_FRAME_QUIRK BIT(0) |
24 | #define UCLOGIC_BATTERY_QUIRK BIT(1) |
25 | |
26 | /* Types of pen in-range reporting */ |
27 | enum uclogic_params_pen_inrange { |
28 | /* Normal reports: zero - out of proximity, one - in proximity */ |
29 | UCLOGIC_PARAMS_PEN_INRANGE_NORMAL = 0, |
30 | /* Inverted reports: zero - in proximity, one - out of proximity */ |
31 | UCLOGIC_PARAMS_PEN_INRANGE_INVERTED, |
32 | /* No reports */ |
33 | UCLOGIC_PARAMS_PEN_INRANGE_NONE, |
34 | }; |
35 | |
36 | /* Types of frames */ |
37 | enum uclogic_params_frame_type { |
38 | /* Frame with buttons */ |
39 | UCLOGIC_PARAMS_FRAME_BUTTONS = 0, |
40 | /* Frame with buttons and a dial */ |
41 | UCLOGIC_PARAMS_FRAME_DIAL, |
42 | /* Frame with buttons and a mouse (shaped as a dial + touchpad) */ |
43 | UCLOGIC_PARAMS_FRAME_MOUSE, |
44 | }; |
45 | |
46 | /* |
47 | * Pen report's subreport data. |
48 | */ |
49 | struct uclogic_params_pen_subreport { |
50 | /* |
51 | * The value of the second byte of the pen report indicating this |
52 | * subreport. If zero, the subreport should be considered invalid and |
53 | * not matched. |
54 | */ |
55 | __u8 value; |
56 | |
57 | /* |
58 | * The ID to be assigned to the report, if the second byte of the pen |
59 | * report is equal to "value". Only valid if "value" is not zero. |
60 | */ |
61 | __u8 id; |
62 | }; |
63 | |
64 | /* |
65 | * Tablet interface's pen input parameters. |
66 | * |
67 | * Must use declarative (descriptive) language, not imperative, to simplify |
68 | * understanding and maintain consistency. |
69 | * |
70 | * Noop (preserving functionality) when filled with zeroes. |
71 | */ |
72 | struct uclogic_params_pen { |
73 | /* |
74 | * True if pen usage is invalid for this interface and should be |
75 | * ignored, false otherwise. |
76 | */ |
77 | bool usage_invalid; |
78 | /* |
79 | * Pointer to report descriptor part describing the pen inputs. |
80 | * Allocated with kmalloc. NULL if the part is not specified. |
81 | */ |
82 | __u8 *desc_ptr; |
83 | /* |
84 | * Size of the report descriptor. |
85 | * Only valid, if "desc_ptr" is not NULL. |
86 | */ |
87 | unsigned int desc_size; |
88 | /* Report ID, if reports should be tweaked, zero if not */ |
89 | unsigned int id; |
90 | /* The list of subreports, only valid if "id" is not zero */ |
91 | struct uclogic_params_pen_subreport subreport_list[3]; |
92 | /* Type of in-range reporting, only valid if "id" is not zero */ |
93 | enum uclogic_params_pen_inrange inrange; |
94 | /* |
95 | * True, if reports include fragmented high resolution coords, with |
96 | * high-order X and then Y bytes following the pressure field. |
97 | * Only valid if "id" is not zero. |
98 | */ |
99 | bool fragmented_hires; |
100 | /* |
101 | * True if the pen reports tilt in bytes at offset 10 (X) and 11 (Y), |
102 | * and the Y tilt direction is flipped. |
103 | * Only valid if "id" is not zero. |
104 | */ |
105 | bool tilt_y_flipped; |
106 | }; |
107 | |
108 | /* |
109 | * Parameters of frame control inputs of a tablet interface. |
110 | * |
111 | * Must use declarative (descriptive) language, not imperative, to simplify |
112 | * understanding and maintain consistency. |
113 | * |
114 | * Noop (preserving functionality) when filled with zeroes. |
115 | */ |
116 | struct uclogic_params_frame { |
117 | /* |
118 | * Pointer to report descriptor part describing the frame inputs. |
119 | * Allocated with kmalloc. NULL if the part is not specified. |
120 | */ |
121 | __u8 *desc_ptr; |
122 | /* |
123 | * Size of the report descriptor. |
124 | * Only valid, if "desc_ptr" is not NULL. |
125 | */ |
126 | unsigned int desc_size; |
127 | /* |
128 | * Report ID, if reports should be tweaked, zero if not. |
129 | */ |
130 | unsigned int id; |
131 | /* |
132 | * The suffix to add to the input device name, if not NULL. |
133 | */ |
134 | const char *suffix; |
135 | /* |
136 | * Number of the least-significant bit of the 2-bit state of a rotary |
137 | * encoder, in the report. Cannot point to a 2-bit field crossing a |
138 | * byte boundary. Zero if not present. Only valid if "id" is not zero. |
139 | */ |
140 | unsigned int re_lsb; |
141 | /* |
142 | * Offset of the Wacom-style device ID byte in the report, to be set |
143 | * to pad device ID (0xf), for compatibility with Wacom drivers. Zero |
144 | * if no changes to the report should be made. The ID byte will be set |
145 | * to zero whenever the byte pointed by "touch_byte" is zero, if |
146 | * the latter is valid. Only valid if "id" is not zero. |
147 | */ |
148 | unsigned int dev_id_byte; |
149 | /* |
150 | * Offset of the touch ring/strip state byte, in the report. |
151 | * Zero if not present. If dev_id_byte is also valid and non-zero, |
152 | * then the device ID byte will be cleared when the byte pointed to by |
153 | * this offset is zero. Only valid if "id" is not zero. |
154 | */ |
155 | unsigned int touch_byte; |
156 | /* |
157 | * The value to anchor the reversed touch ring/strip reports at. |
158 | * I.e. one, if the reports should be flipped without offset. |
159 | * Zero if no reversal should be done. |
160 | * Only valid if "touch_byte" is valid and not zero. |
161 | */ |
162 | __s8 touch_flip_at; |
163 | /* |
164 | * Maximum value of the touch ring/strip report around which the value |
165 | * should be wrapped when flipping according to "touch_flip_at". |
166 | * The minimum valid value is considered to be one, with zero being |
167 | * out-of-proximity (finger lift) value. |
168 | * Only valid if "touch_flip_at" is valid and not zero. |
169 | */ |
170 | __s8 touch_max; |
171 | /* |
172 | * Offset of the bitmap dial byte, in the report. Zero if not present. |
173 | * Only valid if "id" is not zero. A bitmap dial sends reports with a |
174 | * dedicated bit per direction: 1 means clockwise rotation, 2 means |
175 | * counterclockwise, as opposed to the normal 1 and -1. |
176 | */ |
177 | unsigned int bitmap_dial_byte; |
178 | }; |
179 | |
180 | /* |
181 | * List of works to be performed when a certain raw event is received. |
182 | */ |
183 | struct uclogic_raw_event_hook { |
184 | struct hid_device *hdev; |
185 | __u8 *event; |
186 | size_t size; |
187 | struct work_struct work; |
188 | struct list_head list; |
189 | }; |
190 | |
191 | /* |
192 | * Tablet interface report parameters. |
193 | * |
194 | * Must use declarative (descriptive) language, not imperative, to simplify |
195 | * understanding and maintain consistency. |
196 | * |
197 | * When filled with zeros represents a "noop" configuration - passes all |
198 | * reports unchanged and lets the generic HID driver handle everything. |
199 | * |
200 | * The resulting device report descriptor is assembled from all the report |
201 | * descriptor parts referenced by the structure. No order of assembly should |
202 | * be assumed. The structure represents original device report descriptor if |
203 | * all the parts are NULL. |
204 | */ |
205 | struct uclogic_params { |
206 | /* |
207 | * True if the whole interface is invalid, false otherwise. |
208 | */ |
209 | bool invalid; |
210 | /* |
211 | * Pointer to the common part of the replacement report descriptor, |
212 | * allocated with kmalloc. NULL if no common part is needed. |
213 | * Only valid, if "invalid" is false. |
214 | */ |
215 | __u8 *desc_ptr; |
216 | /* |
217 | * Size of the common part of the replacement report descriptor. |
218 | * Only valid, if "desc_ptr" is valid and not NULL. |
219 | */ |
220 | unsigned int desc_size; |
221 | /* |
222 | * Pen parameters and optional report descriptor part. |
223 | * Only valid, if "invalid" is false. |
224 | */ |
225 | struct uclogic_params_pen pen; |
226 | /* |
227 | * The list of frame control parameters and optional report descriptor |
228 | * parts. Only valid, if "invalid" is false. |
229 | */ |
230 | struct uclogic_params_frame frame_list[3]; |
231 | /* |
232 | * List of event hooks. |
233 | */ |
234 | struct uclogic_raw_event_hook *event_hooks; |
235 | }; |
236 | |
237 | /* Driver data */ |
238 | struct uclogic_drvdata { |
239 | /* Interface parameters */ |
240 | struct uclogic_params params; |
241 | /* Pointer to the replacement report descriptor. NULL if none. */ |
242 | __u8 *desc_ptr; |
243 | /* |
244 | * Size of the replacement report descriptor. |
245 | * Only valid if desc_ptr is not NULL |
246 | */ |
247 | unsigned int desc_size; |
248 | /* Pen input device */ |
249 | struct input_dev *pen_input; |
250 | /* In-range timer */ |
251 | struct timer_list inrange_timer; |
252 | /* Last rotary encoder state, or U8_MAX for none */ |
253 | u8 re_state; |
254 | /* Device quirks */ |
255 | unsigned long quirks; |
256 | }; |
257 | |
258 | /* Initialize a tablet interface and discover its parameters */ |
259 | extern int uclogic_params_init(struct uclogic_params *params, |
260 | struct hid_device *hdev); |
261 | |
262 | /* Get a replacement report descriptor for a tablet's interface. */ |
263 | extern int uclogic_params_get_desc(const struct uclogic_params *params, |
264 | __u8 **pdesc, |
265 | unsigned int *psize); |
266 | |
267 | /* Free resources used by tablet interface's parameters */ |
268 | extern void uclogic_params_cleanup(struct uclogic_params *params); |
269 | |
270 | /* Dump tablet interface parameters with hid_dbg() */ |
271 | extern void uclogic_params_hid_dbg(const struct hid_device *hdev, |
272 | const struct uclogic_params *params); |
273 | |
274 | #endif /* _HID_UCLOGIC_PARAMS_H */ |
275 | |