Commit | Line | Data |
---|---|---|
9614219e NK |
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 | ||
22 | /* Types of pen in-range reporting */ | |
23 | enum uclogic_params_pen_inrange { | |
24 | /* Normal reports: zero - out of proximity, one - in proximity */ | |
25 | UCLOGIC_PARAMS_PEN_INRANGE_NORMAL = 0, | |
26 | /* Inverted reports: zero - in proximity, one - out of proximity */ | |
27 | UCLOGIC_PARAMS_PEN_INRANGE_INVERTED, | |
28 | }; | |
29 | ||
30 | /* Convert a pen in-range reporting type to a string */ | |
31 | extern const char *uclogic_params_pen_inrange_to_str( | |
32 | enum uclogic_params_pen_inrange inrange); | |
33 | ||
34 | /* | |
35 | * Tablet interface's pen input parameters. | |
36 | * | |
37 | * Must use declarative (descriptive) language, not imperative, to simplify | |
38 | * understanding and maintain consistency. | |
39 | * | |
40 | * Noop (preserving functionality) when filled with zeroes. | |
41 | */ | |
42 | struct uclogic_params_pen { | |
43 | /* | |
44 | * Pointer to report descriptor describing the inputs. | |
45 | * Allocated with kmalloc. | |
46 | */ | |
47 | __u8 *desc_ptr; | |
48 | /* | |
49 | * Size of the report descriptor. | |
50 | * Only valid, if "desc_ptr" is not NULL. | |
51 | */ | |
52 | unsigned int desc_size; | |
53 | /* Report ID, if reports should be tweaked, zero if not */ | |
54 | unsigned int id; | |
55 | /* Type of in-range reporting, only valid if "id" is not zero */ | |
56 | enum uclogic_params_pen_inrange inrange; | |
57 | }; | |
58 | ||
59 | /* | |
60 | * Parameters of frame control inputs of a tablet interface. | |
61 | * | |
62 | * Must use declarative (descriptive) language, not imperative, to simplify | |
63 | * understanding and maintain consistency. | |
64 | * | |
65 | * Noop (preserving functionality) when filled with zeroes. | |
66 | */ | |
67 | struct uclogic_params_frame { | |
68 | /* | |
69 | * Pointer to report descriptor describing the inputs. | |
70 | * Allocated with kmalloc. | |
71 | */ | |
72 | __u8 *desc_ptr; | |
73 | /* | |
74 | * Size of the report descriptor. | |
75 | * Only valid, if "desc_ptr" is not NULL. | |
76 | */ | |
77 | unsigned int desc_size; | |
78 | /* | |
79 | * Report ID, if reports should be tweaked, zero if not. | |
80 | */ | |
81 | unsigned int id; | |
82 | }; | |
83 | ||
84 | /* | |
85 | * Tablet interface report parameters. | |
86 | * | |
87 | * Must use declarative (descriptive) language, not imperative, to simplify | |
88 | * understanding and maintain consistency. | |
89 | * | |
90 | * When filled with zeros represents a "noop" configuration - passes all | |
91 | * reports unchanged and lets the generic HID driver handle everything. | |
92 | * | |
93 | * The resulting device report descriptor is assembled from all the report | |
94 | * descriptor parts referenced by the structure. No order of assembly should | |
95 | * be assumed. The structure represents original device report descriptor if | |
96 | * all the parts are NULL. | |
97 | */ | |
98 | struct uclogic_params { | |
99 | /* | |
100 | * True if the whole interface is invalid, false otherwise. | |
101 | */ | |
102 | bool invalid; | |
103 | /* | |
104 | * Pointer to the common part of the replacement report descriptor, | |
105 | * allocated with kmalloc. NULL if no common part is needed. | |
106 | * Only valid, if "invalid" is false. | |
107 | */ | |
108 | __u8 *desc_ptr; | |
109 | /* | |
110 | * Size of the common part of the replacement report descriptor. | |
111 | * Only valid, if "desc_ptr" is not NULL. | |
112 | */ | |
113 | unsigned int desc_size; | |
114 | /* | |
115 | * True, if pen usage in report descriptor is invalid, when present. | |
116 | * Only valid, if "invalid" is false. | |
117 | */ | |
118 | bool pen_unused; | |
119 | /* | |
120 | * Pen parameters and optional report descriptor part. | |
121 | * Only valid if "pen_unused" is valid and false. | |
122 | */ | |
123 | struct uclogic_params_pen pen; | |
124 | /* | |
125 | * Frame control parameters and optional report descriptor part. | |
126 | * Only valid, if "invalid" is false. | |
127 | */ | |
128 | struct uclogic_params_frame frame; | |
129 | /* | |
130 | * Bitmask matching frame controls "sub-report" flag in the second | |
131 | * byte of the pen report, or zero if it's not expected. | |
132 | * Only valid if both "pen" and "frame" are valid, and "frame.id" is | |
133 | * not zero. | |
134 | */ | |
135 | __u8 pen_frame_flag; | |
136 | }; | |
137 | ||
138 | /* Initialize a tablet interface and discover its parameters */ | |
139 | extern int uclogic_params_init(struct uclogic_params *params, | |
140 | struct hid_device *hdev); | |
141 | ||
142 | /* Tablet interface parameters *printf format string */ | |
143 | #define UCLOGIC_PARAMS_FMT_STR \ | |
144 | ".invalid = %s\n" \ | |
145 | ".desc_ptr = %p\n" \ | |
146 | ".desc_size = %u\n" \ | |
147 | ".pen_unused = %s\n" \ | |
148 | ".pen.desc_ptr = %p\n" \ | |
149 | ".pen.desc_size = %u\n" \ | |
150 | ".pen.id = %u\n" \ | |
151 | ".pen.inrange = %s\n" \ | |
152 | ".frame.desc_ptr = %p\n" \ | |
153 | ".frame.desc_size = %u\n" \ | |
154 | ".frame.id = %u\n" \ | |
155 | ".pen_frame_flag = 0x%02x\n" | |
156 | ||
157 | /* Tablet interface parameters *printf format arguments */ | |
158 | #define UCLOGIC_PARAMS_FMT_ARGS(_params) \ | |
159 | ((_params)->invalid ? "true" : "false"), \ | |
160 | (_params)->desc_ptr, \ | |
161 | (_params)->desc_size, \ | |
162 | ((_params)->pen_unused ? "true" : "false"), \ | |
163 | (_params)->pen.desc_ptr, \ | |
164 | (_params)->pen.desc_size, \ | |
165 | (_params)->pen.id, \ | |
166 | uclogic_params_pen_inrange_to_str((_params)->pen.inrange), \ | |
167 | (_params)->frame.desc_ptr, \ | |
168 | (_params)->frame.desc_size, \ | |
169 | (_params)->frame.id, \ | |
170 | (_params)->pen_frame_flag | |
171 | ||
172 | /* Get a replacement report descriptor for a tablet's interface. */ | |
173 | extern int uclogic_params_get_desc(const struct uclogic_params *params, | |
174 | __u8 **pdesc, | |
175 | unsigned int *psize); | |
176 | ||
177 | /* Free resources used by tablet interface's parameters */ | |
178 | extern void uclogic_params_cleanup(struct uclogic_params *params); | |
179 | ||
180 | #endif /* _HID_UCLOGIC_PARAMS_H */ |