drivers/hid/hid-uclogic-params.h

0001 /* SPDX-License-Identifier: GPL-2.0+ */
0002 /*
0003  *  HID driver for UC-Logic devices not fully compliant with HID standard
0004  *  - tablet initialization and parameter retrieval
0005  *
0006  *  Copyright (c) 2018 Nikolai Kondrashov
0007  */
0008
0009 /*
0010  * This program is free software; you can redistribute it and/or modify it
0011  * under the terms of the GNU General Public License as published by the Free
0012  * Software Foundation; either version 2 of the License, or (at your option)
0013  * any later version.
0014  */
0015
0016 #ifndef _HID_UCLOGIC_PARAMS_H
0017 #define _HID_UCLOGIC_PARAMS_H
0018
0019 #include <linux/usb.h>
0020 #include <linux/hid.h>
0021
0022 /* Types of pen in-range reporting */
0023 enum uclogic_params_pen_inrange {
0024     /* Normal reports: zero - out of proximity, one - in proximity */
0025     UCLOGIC_PARAMS_PEN_INRANGE_NORMAL = 0,
0026     /* Inverted reports: zero - in proximity, one - out of proximity */
0027     UCLOGIC_PARAMS_PEN_INRANGE_INVERTED,
0028     /* No reports */
0029     UCLOGIC_PARAMS_PEN_INRANGE_NONE,
0030 };
0031
0032 /*
0033  * Pen report's subreport data.
0034  */
0035 struct uclogic_params_pen_subreport {
0036     /*
0037      * The value of the second byte of the pen report indicating this
0038      * subreport. If zero, the subreport should be considered invalid and
0039      * not matched.
0040      */
0041     __u8 value;
0042
0043     /*
0044      * The ID to be assigned to the report, if the second byte of the pen
0045      * report is equal to "value". Only valid if "value" is not zero.
0046      */
0047     __u8 id;
0048 };
0049
0050 /*
0051  * Tablet interface's pen input parameters.
0052  *
0053  * Must use declarative (descriptive) language, not imperative, to simplify
0054  * understanding and maintain consistency.
0055  *
0056  * Noop (preserving functionality) when filled with zeroes.
0057  */
0058 struct uclogic_params_pen {
0059     /*
0060      * True if pen usage is invalid for this interface and should be
0061      * ignored, false otherwise.
0062      */
0063     bool usage_invalid;
0064     /*
0065      * Pointer to report descriptor part describing the pen inputs.
0066      * Allocated with kmalloc. NULL if the part is not specified.
0067      */
0068     __u8 *desc_ptr;
0069     /*
0070      * Size of the report descriptor.
0071      * Only valid, if "desc_ptr" is not NULL.
0072      */
0073     unsigned int desc_size;
0074     /* Report ID, if reports should be tweaked, zero if not */
0075     unsigned int id;
0076     /* The list of subreports, only valid if "id" is not zero */
0077     struct uclogic_params_pen_subreport subreport_list[3];
0078     /* Type of in-range reporting, only valid if "id" is not zero */
0079     enum uclogic_params_pen_inrange inrange;
0080     /*
0081      * True, if reports include fragmented high resolution coords, with
0082      * high-order X and then Y bytes following the pressure field.
0083      * Only valid if "id" is not zero.
0084      */
0085     bool fragmented_hires;
0086     /*
0087      * True if the pen reports tilt in bytes at offset 10 (X) and 11 (Y),
0088      * and the Y tilt direction is flipped.
0089      * Only valid if "id" is not zero.
0090      */
0091     bool tilt_y_flipped;
0092 };
0093
0094 /*
0095  * Parameters of frame control inputs of a tablet interface.
0096  *
0097  * Must use declarative (descriptive) language, not imperative, to simplify
0098  * understanding and maintain consistency.
0099  *
0100  * Noop (preserving functionality) when filled with zeroes.
0101  */
0102 struct uclogic_params_frame {
0103     /*
0104      * Pointer to report descriptor part describing the frame inputs.
0105      * Allocated with kmalloc. NULL if the part is not specified.
0106      */
0107     __u8 *desc_ptr;
0108     /*
0109      * Size of the report descriptor.
0110      * Only valid, if "desc_ptr" is not NULL.
0111      */
0112     unsigned int desc_size;
0113     /*
0114      * Report ID, if reports should be tweaked, zero if not.
0115      */
0116     unsigned int id;
0117     /*
0118      * The suffix to add to the input device name, if not NULL.
0119      */
0120     const char *suffix;
0121     /*
0122      * Number of the least-significant bit of the 2-bit state of a rotary
0123      * encoder, in the report. Cannot point to a 2-bit field crossing a
0124      * byte boundary. Zero if not present. Only valid if "id" is not zero.
0125      */
0126     unsigned int re_lsb;
0127     /*
0128      * Offset of the Wacom-style device ID byte in the report, to be set
0129      * to pad device ID (0xf), for compatibility with Wacom drivers. Zero
0130      * if no changes to the report should be made. The ID byte will be set
0131      * to zero whenever the byte pointed by "touch_byte" is zero, if
0132      * the latter is valid. Only valid if "id" is not zero.
0133      */
0134     unsigned int dev_id_byte;
0135     /*
0136      * Offset of the touch ring/strip state byte, in the report.
0137      * Zero if not present. If dev_id_byte is also valid and non-zero,
0138      * then the device ID byte will be cleared when the byte pointed to by
0139      * this offset is zero. Only valid if "id" is not zero.
0140      */
0141     unsigned int touch_byte;
0142     /*
0143      * The value to anchor the reversed touch ring/strip reports at.
0144      * I.e. one, if the reports should be flipped without offset.
0145      * Zero if no reversal should be done.
0146      * Only valid if "touch_byte" is valid and not zero.
0147      */
0148     __s8 touch_flip_at;
0149     /*
0150      * Maximum value of the touch ring/strip report around which the value
0151      * should be wrapped when flipping according to "touch_flip_at".
0152      * The minimum valid value is considered to be one, with zero being
0153      * out-of-proximity (finger lift) value.
0154      * Only valid if "touch_flip_at" is valid and not zero.
0155      */
0156     __s8 touch_max;
0157     /*
0158      * Offset of the bitmap dial byte, in the report. Zero if not present.
0159      * Only valid if "id" is not zero. A bitmap dial sends reports with a
0160      * dedicated bit per direction: 1 means clockwise rotation, 2 means
0161      * counterclockwise, as opposed to the normal 1 and -1.
0162      */
0163     unsigned int bitmap_dial_byte;
0164 };
0165
0166 /*
0167  * Tablet interface report parameters.
0168  *
0169  * Must use declarative (descriptive) language, not imperative, to simplify
0170  * understanding and maintain consistency.
0171  *
0172  * When filled with zeros represents a "noop" configuration - passes all
0173  * reports unchanged and lets the generic HID driver handle everything.
0174  *
0175  * The resulting device report descriptor is assembled from all the report
0176  * descriptor parts referenced by the structure. No order of assembly should
0177  * be assumed. The structure represents original device report descriptor if
0178  * all the parts are NULL.
0179  */
0180 struct uclogic_params {
0181     /*
0182      * True if the whole interface is invalid, false otherwise.
0183      */
0184     bool invalid;
0185     /*
0186      * Pointer to the common part of the replacement report descriptor,
0187      * allocated with kmalloc. NULL if no common part is needed.
0188      * Only valid, if "invalid" is false.
0189      */
0190     __u8 *desc_ptr;
0191     /*
0192      * Size of the common part of the replacement report descriptor.
0193      * Only valid, if "desc_ptr" is valid and not NULL.
0194      */
0195     unsigned int desc_size;
0196     /*
0197      * Pen parameters and optional report descriptor part.
0198      * Only valid, if "invalid" is false.
0199      */
0200     struct uclogic_params_pen pen;
0201     /*
0202      * The list of frame control parameters and optional report descriptor
0203      * parts. Only valid, if "invalid" is false.
0204      */
0205     struct uclogic_params_frame frame_list[3];
0206 };
0207
0208 /* Initialize a tablet interface and discover its parameters */
0209 extern int uclogic_params_init(struct uclogic_params *params,
0210                 struct hid_device *hdev);
0211
0212 /* Get a replacement report descriptor for a tablet's interface. */
0213 extern int uclogic_params_get_desc(const struct uclogic_params *params,
0214                     __u8 **pdesc,
0215                     unsigned int *psize);
0216
0217 /* Free resources used by tablet interface's parameters */
0218 extern void uclogic_params_cleanup(struct uclogic_params *params);
0219
0220 /* Dump tablet interface parameters with hid_dbg() */
0221 extern void uclogic_params_hid_dbg(const struct hid_device *hdev,
0222                     const struct uclogic_params *params);
0223
0224 #endif /* _HID_UCLOGIC_PARAMS_H */