19614219eSNikolai Kondrashov /* SPDX-License-Identifier: GPL-2.0+ */ 29614219eSNikolai Kondrashov /* 39614219eSNikolai Kondrashov * HID driver for UC-Logic devices not fully compliant with HID standard 49614219eSNikolai Kondrashov * - tablet initialization and parameter retrieval 59614219eSNikolai Kondrashov * 69614219eSNikolai Kondrashov * Copyright (c) 2018 Nikolai Kondrashov 79614219eSNikolai Kondrashov */ 89614219eSNikolai Kondrashov 99614219eSNikolai Kondrashov /* 109614219eSNikolai Kondrashov * This program is free software; you can redistribute it and/or modify it 119614219eSNikolai Kondrashov * under the terms of the GNU General Public License as published by the Free 129614219eSNikolai Kondrashov * Software Foundation; either version 2 of the License, or (at your option) 139614219eSNikolai Kondrashov * any later version. 149614219eSNikolai Kondrashov */ 159614219eSNikolai Kondrashov 169614219eSNikolai Kondrashov #ifndef _HID_UCLOGIC_PARAMS_H 179614219eSNikolai Kondrashov #define _HID_UCLOGIC_PARAMS_H 189614219eSNikolai Kondrashov 199614219eSNikolai Kondrashov #include <linux/usb.h> 209614219eSNikolai Kondrashov #include <linux/hid.h> 219614219eSNikolai Kondrashov 229614219eSNikolai Kondrashov /* Types of pen in-range reporting */ 239614219eSNikolai Kondrashov enum uclogic_params_pen_inrange { 249614219eSNikolai Kondrashov /* Normal reports: zero - out of proximity, one - in proximity */ 259614219eSNikolai Kondrashov UCLOGIC_PARAMS_PEN_INRANGE_NORMAL = 0, 269614219eSNikolai Kondrashov /* Inverted reports: zero - in proximity, one - out of proximity */ 279614219eSNikolai Kondrashov UCLOGIC_PARAMS_PEN_INRANGE_INVERTED, 2801309e29SNikolai Kondrashov /* No reports */ 2901309e29SNikolai Kondrashov UCLOGIC_PARAMS_PEN_INRANGE_NONE, 309614219eSNikolai Kondrashov }; 319614219eSNikolai Kondrashov 329614219eSNikolai Kondrashov /* Convert a pen in-range reporting type to a string */ 339614219eSNikolai Kondrashov extern const char *uclogic_params_pen_inrange_to_str( 349614219eSNikolai Kondrashov enum uclogic_params_pen_inrange inrange); 359614219eSNikolai Kondrashov 369614219eSNikolai Kondrashov /* 379614219eSNikolai Kondrashov * Tablet interface's pen input parameters. 389614219eSNikolai Kondrashov * 399614219eSNikolai Kondrashov * Must use declarative (descriptive) language, not imperative, to simplify 409614219eSNikolai Kondrashov * understanding and maintain consistency. 419614219eSNikolai Kondrashov * 429614219eSNikolai Kondrashov * Noop (preserving functionality) when filled with zeroes. 439614219eSNikolai Kondrashov */ 449614219eSNikolai Kondrashov struct uclogic_params_pen { 459614219eSNikolai Kondrashov /* 469614219eSNikolai Kondrashov * Pointer to report descriptor describing the inputs. 479614219eSNikolai Kondrashov * Allocated with kmalloc. 489614219eSNikolai Kondrashov */ 499614219eSNikolai Kondrashov __u8 *desc_ptr; 509614219eSNikolai Kondrashov /* 519614219eSNikolai Kondrashov * Size of the report descriptor. 529614219eSNikolai Kondrashov * Only valid, if "desc_ptr" is not NULL. 539614219eSNikolai Kondrashov */ 549614219eSNikolai Kondrashov unsigned int desc_size; 559614219eSNikolai Kondrashov /* Report ID, if reports should be tweaked, zero if not */ 569614219eSNikolai Kondrashov unsigned int id; 579614219eSNikolai Kondrashov /* Type of in-range reporting, only valid if "id" is not zero */ 589614219eSNikolai Kondrashov enum uclogic_params_pen_inrange inrange; 5959f2e0fcSNikolai Kondrashov /* 6059f2e0fcSNikolai Kondrashov * True, if reports include fragmented high resolution coords, with 6159f2e0fcSNikolai Kondrashov * high-order X and then Y bytes following the pressure field. 6259f2e0fcSNikolai Kondrashov * Only valid if "id" is not zero. 6359f2e0fcSNikolai Kondrashov */ 6459f2e0fcSNikolai Kondrashov bool fragmented_hires; 659614219eSNikolai Kondrashov }; 669614219eSNikolai Kondrashov 679614219eSNikolai Kondrashov /* 689614219eSNikolai Kondrashov * Parameters of frame control inputs of a tablet interface. 699614219eSNikolai Kondrashov * 709614219eSNikolai Kondrashov * Must use declarative (descriptive) language, not imperative, to simplify 719614219eSNikolai Kondrashov * understanding and maintain consistency. 729614219eSNikolai Kondrashov * 739614219eSNikolai Kondrashov * Noop (preserving functionality) when filled with zeroes. 749614219eSNikolai Kondrashov */ 759614219eSNikolai Kondrashov struct uclogic_params_frame { 769614219eSNikolai Kondrashov /* 779614219eSNikolai Kondrashov * Pointer to report descriptor describing the inputs. 789614219eSNikolai Kondrashov * Allocated with kmalloc. 799614219eSNikolai Kondrashov */ 809614219eSNikolai Kondrashov __u8 *desc_ptr; 819614219eSNikolai Kondrashov /* 829614219eSNikolai Kondrashov * Size of the report descriptor. 839614219eSNikolai Kondrashov * Only valid, if "desc_ptr" is not NULL. 849614219eSNikolai Kondrashov */ 859614219eSNikolai Kondrashov unsigned int desc_size; 869614219eSNikolai Kondrashov /* 879614219eSNikolai Kondrashov * Report ID, if reports should be tweaked, zero if not. 889614219eSNikolai Kondrashov */ 899614219eSNikolai Kondrashov unsigned int id; 909614219eSNikolai Kondrashov }; 919614219eSNikolai Kondrashov 929614219eSNikolai Kondrashov /* 939614219eSNikolai Kondrashov * Tablet interface report parameters. 949614219eSNikolai Kondrashov * 959614219eSNikolai Kondrashov * Must use declarative (descriptive) language, not imperative, to simplify 969614219eSNikolai Kondrashov * understanding and maintain consistency. 979614219eSNikolai Kondrashov * 989614219eSNikolai Kondrashov * When filled with zeros represents a "noop" configuration - passes all 999614219eSNikolai Kondrashov * reports unchanged and lets the generic HID driver handle everything. 1009614219eSNikolai Kondrashov * 1019614219eSNikolai Kondrashov * The resulting device report descriptor is assembled from all the report 1029614219eSNikolai Kondrashov * descriptor parts referenced by the structure. No order of assembly should 1039614219eSNikolai Kondrashov * be assumed. The structure represents original device report descriptor if 1049614219eSNikolai Kondrashov * all the parts are NULL. 1059614219eSNikolai Kondrashov */ 1069614219eSNikolai Kondrashov struct uclogic_params { 1079614219eSNikolai Kondrashov /* 1089614219eSNikolai Kondrashov * True if the whole interface is invalid, false otherwise. 1099614219eSNikolai Kondrashov */ 1109614219eSNikolai Kondrashov bool invalid; 1119614219eSNikolai Kondrashov /* 1129614219eSNikolai Kondrashov * Pointer to the common part of the replacement report descriptor, 1139614219eSNikolai Kondrashov * allocated with kmalloc. NULL if no common part is needed. 1149614219eSNikolai Kondrashov * Only valid, if "invalid" is false. 1159614219eSNikolai Kondrashov */ 1169614219eSNikolai Kondrashov __u8 *desc_ptr; 1179614219eSNikolai Kondrashov /* 1189614219eSNikolai Kondrashov * Size of the common part of the replacement report descriptor. 1199614219eSNikolai Kondrashov * Only valid, if "desc_ptr" is not NULL. 1209614219eSNikolai Kondrashov */ 1219614219eSNikolai Kondrashov unsigned int desc_size; 1229614219eSNikolai Kondrashov /* 1239614219eSNikolai Kondrashov * True, if pen usage in report descriptor is invalid, when present. 1249614219eSNikolai Kondrashov * Only valid, if "invalid" is false. 1259614219eSNikolai Kondrashov */ 1269614219eSNikolai Kondrashov bool pen_unused; 1279614219eSNikolai Kondrashov /* 1289614219eSNikolai Kondrashov * Pen parameters and optional report descriptor part. 1299614219eSNikolai Kondrashov * Only valid if "pen_unused" is valid and false. 1309614219eSNikolai Kondrashov */ 1319614219eSNikolai Kondrashov struct uclogic_params_pen pen; 1329614219eSNikolai Kondrashov /* 1339614219eSNikolai Kondrashov * Frame control parameters and optional report descriptor part. 1349614219eSNikolai Kondrashov * Only valid, if "invalid" is false. 1359614219eSNikolai Kondrashov */ 1369614219eSNikolai Kondrashov struct uclogic_params_frame frame; 1379614219eSNikolai Kondrashov /* 1389614219eSNikolai Kondrashov * Bitmask matching frame controls "sub-report" flag in the second 1399614219eSNikolai Kondrashov * byte of the pen report, or zero if it's not expected. 1409614219eSNikolai Kondrashov * Only valid if both "pen" and "frame" are valid, and "frame.id" is 1419614219eSNikolai Kondrashov * not zero. 1429614219eSNikolai Kondrashov */ 1439614219eSNikolai Kondrashov __u8 pen_frame_flag; 1449614219eSNikolai Kondrashov }; 1459614219eSNikolai Kondrashov 1469614219eSNikolai Kondrashov /* Initialize a tablet interface and discover its parameters */ 1479614219eSNikolai Kondrashov extern int uclogic_params_init(struct uclogic_params *params, 1489614219eSNikolai Kondrashov struct hid_device *hdev); 1499614219eSNikolai Kondrashov 1509614219eSNikolai Kondrashov /* Tablet interface parameters *printf format string */ 1519614219eSNikolai Kondrashov #define UCLOGIC_PARAMS_FMT_STR \ 1529614219eSNikolai Kondrashov ".invalid = %s\n" \ 1539614219eSNikolai Kondrashov ".desc_ptr = %p\n" \ 1549614219eSNikolai Kondrashov ".desc_size = %u\n" \ 1559614219eSNikolai Kondrashov ".pen_unused = %s\n" \ 1569614219eSNikolai Kondrashov ".pen.desc_ptr = %p\n" \ 1579614219eSNikolai Kondrashov ".pen.desc_size = %u\n" \ 1589614219eSNikolai Kondrashov ".pen.id = %u\n" \ 1599614219eSNikolai Kondrashov ".pen.inrange = %s\n" \ 16059f2e0fcSNikolai Kondrashov ".pen.fragmented_hires = %s\n" \ 1619614219eSNikolai Kondrashov ".frame.desc_ptr = %p\n" \ 1629614219eSNikolai Kondrashov ".frame.desc_size = %u\n" \ 1639614219eSNikolai Kondrashov ".frame.id = %u\n" \ 1649614219eSNikolai Kondrashov ".pen_frame_flag = 0x%02x\n" 1659614219eSNikolai Kondrashov 1669614219eSNikolai Kondrashov /* Tablet interface parameters *printf format arguments */ 1679614219eSNikolai Kondrashov #define UCLOGIC_PARAMS_FMT_ARGS(_params) \ 1689614219eSNikolai Kondrashov ((_params)->invalid ? "true" : "false"), \ 1699614219eSNikolai Kondrashov (_params)->desc_ptr, \ 1709614219eSNikolai Kondrashov (_params)->desc_size, \ 1719614219eSNikolai Kondrashov ((_params)->pen_unused ? "true" : "false"), \ 1729614219eSNikolai Kondrashov (_params)->pen.desc_ptr, \ 1739614219eSNikolai Kondrashov (_params)->pen.desc_size, \ 1749614219eSNikolai Kondrashov (_params)->pen.id, \ 1759614219eSNikolai Kondrashov uclogic_params_pen_inrange_to_str((_params)->pen.inrange), \ 17659f2e0fcSNikolai Kondrashov ((_params)->pen.fragmented_hires ? "true" : "false"), \ 1779614219eSNikolai Kondrashov (_params)->frame.desc_ptr, \ 1789614219eSNikolai Kondrashov (_params)->frame.desc_size, \ 1799614219eSNikolai Kondrashov (_params)->frame.id, \ 1809614219eSNikolai Kondrashov (_params)->pen_frame_flag 1819614219eSNikolai Kondrashov 1829614219eSNikolai Kondrashov /* Get a replacement report descriptor for a tablet's interface. */ 1839614219eSNikolai Kondrashov extern int uclogic_params_get_desc(const struct uclogic_params *params, 1849614219eSNikolai Kondrashov __u8 **pdesc, 1859614219eSNikolai Kondrashov unsigned int *psize); 1869614219eSNikolai Kondrashov 1879614219eSNikolai Kondrashov /* Free resources used by tablet interface's parameters */ 1889614219eSNikolai Kondrashov extern void uclogic_params_cleanup(struct uclogic_params *params); 1899614219eSNikolai Kondrashov 1909614219eSNikolai Kondrashov #endif /* _HID_UCLOGIC_PARAMS_H */ 191