Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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> |
José Expósito | a251d65 | 2022-12-26 13:54:52 +0100 | [diff] [blame] | 21 | #include <linux/list.h> |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 22 | |
José Expósito | 14b71e6 | 2022-12-26 13:54:49 +0100 | [diff] [blame] | 23 | #define UCLOGIC_MOUSE_FRAME_QUIRK BIT(0) |
José Expósito | f60c377 | 2022-12-26 13:54:50 +0100 | [diff] [blame] | 24 | #define UCLOGIC_BATTERY_QUIRK BIT(1) |
José Expósito | 14b71e6 | 2022-12-26 13:54:49 +0100 | [diff] [blame] | 25 | |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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, |
Nikolai Kondrashov | 01309e2 | 2019-02-10 12:13:54 +0200 | [diff] [blame] | 32 | /* No reports */ |
| 33 | UCLOGIC_PARAMS_PEN_INRANGE_NONE, |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 34 | }; |
| 35 | |
José Expósito | a092986 | 2022-08-15 16:29:52 +0200 | [diff] [blame] | 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 | |
Nikolai Kondrashov | 8b01309 | 2022-02-19 11:01:50 +0100 | [diff] [blame] | 46 | /* |
| 47 | * Pen report's subreport data. |
| 48 | */ |
| 49 | struct uclogic_params_pen_subreport { |
| 50 | /* |
Nikolai Kondrashov | e6be956 | 2022-02-19 11:01:51 +0100 | [diff] [blame] | 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. |
Nikolai Kondrashov | 8b01309 | 2022-02-19 11:01:50 +0100 | [diff] [blame] | 54 | */ |
Nikolai Kondrashov | e6be956 | 2022-02-19 11:01:51 +0100 | [diff] [blame] | 55 | __u8 value; |
Nikolai Kondrashov | 8b01309 | 2022-02-19 11:01:50 +0100 | [diff] [blame] | 56 | |
| 57 | /* |
Nikolai Kondrashov | e6be956 | 2022-02-19 11:01:51 +0100 | [diff] [blame] | 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. |
Nikolai Kondrashov | 8b01309 | 2022-02-19 11:01:50 +0100 | [diff] [blame] | 60 | */ |
| 61 | __u8 id; |
| 62 | }; |
| 63 | |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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 | /* |
Nikolai Kondrashov | f592797 | 2022-04-21 19:50:51 +0200 | [diff] [blame] | 74 | * True if pen usage is invalid for this interface and should be |
| 75 | * ignored, false otherwise. |
| 76 | */ |
| 77 | bool usage_invalid; |
| 78 | /* |
Nikolai Kondrashov | 4933a72 | 2022-04-21 19:50:49 +0200 | [diff] [blame] | 79 | * Pointer to report descriptor part describing the pen inputs. |
| 80 | * Allocated with kmalloc. NULL if the part is not specified. |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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; |
Nikolai Kondrashov | 3e200d6 | 2022-03-03 08:47:33 +0100 | [diff] [blame] | 90 | /* The list of subreports, only valid if "id" is not zero */ |
| 91 | struct uclogic_params_pen_subreport subreport_list[3]; |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 92 | /* Type of in-range reporting, only valid if "id" is not zero */ |
| 93 | enum uclogic_params_pen_inrange inrange; |
Nikolai Kondrashov | 59f2e0f | 2019-02-10 12:13:55 +0200 | [diff] [blame] | 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; |
Nikolai Kondrashov | 1324c5a | 2022-02-10 20:04:31 +0100 | [diff] [blame] | 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; |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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 | /* |
Nikolai Kondrashov | 4933a72 | 2022-04-21 19:50:49 +0200 | [diff] [blame] | 118 | * Pointer to report descriptor part describing the frame inputs. |
| 119 | * Allocated with kmalloc. NULL if the part is not specified. |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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; |
Nikolai Kondrashov | fde44ac | 2019-02-10 12:14:03 +0200 | [diff] [blame] | 131 | /* |
Nikolai Kondrashov | ee00703 | 2022-03-03 08:47:32 +0100 | [diff] [blame] | 132 | * The suffix to add to the input device name, if not NULL. |
| 133 | */ |
| 134 | const char *suffix; |
| 135 | /* |
Nikolai Kondrashov | 8a47670 | 2019-02-10 12:14:04 +0200 | [diff] [blame] | 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 | /* |
Nikolai Kondrashov | fde44ac | 2019-02-10 12:14:03 +0200 | [diff] [blame] | 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 |
Nikolai Kondrashov | d170e8e | 2022-03-03 08:47:31 +0100 | [diff] [blame] | 144 | * if no changes to the report should be made. The ID byte will be set |
Nikolai Kondrashov | caf7e93 | 2022-05-08 18:01:42 +0200 | [diff] [blame] | 145 | * to zero whenever the byte pointed by "touch_byte" is zero, if |
Nikolai Kondrashov | d170e8e | 2022-03-03 08:47:31 +0100 | [diff] [blame] | 146 | * the latter is valid. Only valid if "id" is not zero. |
Nikolai Kondrashov | fde44ac | 2019-02-10 12:14:03 +0200 | [diff] [blame] | 147 | */ |
| 148 | unsigned int dev_id_byte; |
Nikolai Kondrashov | d170e8e | 2022-03-03 08:47:31 +0100 | [diff] [blame] | 149 | /* |
Nikolai Kondrashov | caf7e93 | 2022-05-08 18:01:42 +0200 | [diff] [blame] | 150 | * Offset of the touch ring/strip state byte, in the report. |
Nikolai Kondrashov | d170e8e | 2022-03-03 08:47:31 +0100 | [diff] [blame] | 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 | */ |
Nikolai Kondrashov | caf7e93 | 2022-05-08 18:01:42 +0200 | [diff] [blame] | 155 | unsigned int touch_byte; |
Nikolai Kondrashov | d170e8e | 2022-03-03 08:47:31 +0100 | [diff] [blame] | 156 | /* |
Nikolai Kondrashov | caf7e93 | 2022-05-08 18:01:42 +0200 | [diff] [blame] | 157 | * The value to anchor the reversed touch ring/strip reports at. |
Nikolai Kondrashov | d170e8e | 2022-03-03 08:47:31 +0100 | [diff] [blame] | 158 | * I.e. one, if the reports should be flipped without offset. |
| 159 | * Zero if no reversal should be done. |
Nikolai Kondrashov | caf7e93 | 2022-05-08 18:01:42 +0200 | [diff] [blame] | 160 | * Only valid if "touch_byte" is valid and not zero. |
Nikolai Kondrashov | d170e8e | 2022-03-03 08:47:31 +0100 | [diff] [blame] | 161 | */ |
Nikolai Kondrashov | caf7e93 | 2022-05-08 18:01:42 +0200 | [diff] [blame] | 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; |
Nikolai Kondrashov | 2112b49 | 2022-04-14 13:09:35 +0200 | [diff] [blame] | 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; |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 178 | }; |
| 179 | |
| 180 | /* |
José Expósito | a251d65 | 2022-12-26 13:54:52 +0100 | [diff] [blame] | 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 | /* |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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. |
Nikolai Kondrashov | 87dc28e | 2022-04-21 19:50:48 +0200 | [diff] [blame] | 218 | * Only valid, if "desc_ptr" is valid and not NULL. |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 219 | */ |
| 220 | unsigned int desc_size; |
| 221 | /* |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 222 | * Pen parameters and optional report descriptor part. |
Nikolai Kondrashov | 606dadc | 2022-02-19 11:01:49 +0100 | [diff] [blame] | 223 | * Only valid, if "invalid" is false. |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 224 | */ |
| 225 | struct uclogic_params_pen pen; |
| 226 | /* |
Nikolai Kondrashov | 337fa05 | 2022-02-19 11:01:57 +0100 | [diff] [blame] | 227 | * The list of frame control parameters and optional report descriptor |
| 228 | * parts. Only valid, if "invalid" is false. |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 229 | */ |
Nikolai Kondrashov | 3e200d6 | 2022-03-03 08:47:33 +0100 | [diff] [blame] | 230 | struct uclogic_params_frame frame_list[3]; |
José Expósito | a251d65 | 2022-12-26 13:54:52 +0100 | [diff] [blame] | 231 | /* |
| 232 | * List of event hooks. |
| 233 | */ |
| 234 | struct uclogic_raw_event_hook *event_hooks; |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 235 | }; |
| 236 | |
José Expósito | 14b71e6 | 2022-12-26 13:54:49 +0100 | [diff] [blame] | 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 | |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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 | |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 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 | |
Nikolai Kondrashov | a228809 | 2022-05-08 18:01:40 +0200 | [diff] [blame] | 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 | |
Nikolai Kondrashov | 9614219 | 2019-02-10 12:13:51 +0200 | [diff] [blame] | 274 | #endif /* _HID_UCLOGIC_PARAMS_H */ |