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 */
27enum 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 */
37enum 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 */
49struct 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 */
72struct 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 */
116struct 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 */
183struct 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 */
205struct 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 */
238struct 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 */
259extern 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. */
263extern 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 */
268extern void uclogic_params_cleanup(struct uclogic_params *params);
269
270/* Dump tablet interface parameters with hid_dbg() */
271extern void uclogic_params_hid_dbg(const struct hid_device *hdev,
272					const struct uclogic_params *params);
273
274#endif /* _HID_UCLOGIC_PARAMS_H */
275