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, 289614219eSNikolai Kondrashov }; 299614219eSNikolai Kondrashov 309614219eSNikolai Kondrashov /* Convert a pen in-range reporting type to a string */ 319614219eSNikolai Kondrashov extern const char *uclogic_params_pen_inrange_to_str( 329614219eSNikolai Kondrashov enum uclogic_params_pen_inrange inrange); 339614219eSNikolai Kondrashov 349614219eSNikolai Kondrashov /* 359614219eSNikolai Kondrashov * Tablet interface's pen input parameters. 369614219eSNikolai Kondrashov * 379614219eSNikolai Kondrashov * Must use declarative (descriptive) language, not imperative, to simplify 389614219eSNikolai Kondrashov * understanding and maintain consistency. 399614219eSNikolai Kondrashov * 409614219eSNikolai Kondrashov * Noop (preserving functionality) when filled with zeroes. 419614219eSNikolai Kondrashov */ 429614219eSNikolai Kondrashov struct uclogic_params_pen { 439614219eSNikolai Kondrashov /* 449614219eSNikolai Kondrashov * Pointer to report descriptor describing the inputs. 459614219eSNikolai Kondrashov * Allocated with kmalloc. 469614219eSNikolai Kondrashov */ 479614219eSNikolai Kondrashov __u8 *desc_ptr; 489614219eSNikolai Kondrashov /* 499614219eSNikolai Kondrashov * Size of the report descriptor. 509614219eSNikolai Kondrashov * Only valid, if "desc_ptr" is not NULL. 519614219eSNikolai Kondrashov */ 529614219eSNikolai Kondrashov unsigned int desc_size; 539614219eSNikolai Kondrashov /* Report ID, if reports should be tweaked, zero if not */ 549614219eSNikolai Kondrashov unsigned int id; 559614219eSNikolai Kondrashov /* Type of in-range reporting, only valid if "id" is not zero */ 569614219eSNikolai Kondrashov enum uclogic_params_pen_inrange inrange; 579614219eSNikolai Kondrashov }; 589614219eSNikolai Kondrashov 599614219eSNikolai Kondrashov /* 609614219eSNikolai Kondrashov * Parameters of frame control inputs of a tablet interface. 619614219eSNikolai Kondrashov * 629614219eSNikolai Kondrashov * Must use declarative (descriptive) language, not imperative, to simplify 639614219eSNikolai Kondrashov * understanding and maintain consistency. 649614219eSNikolai Kondrashov * 659614219eSNikolai Kondrashov * Noop (preserving functionality) when filled with zeroes. 669614219eSNikolai Kondrashov */ 679614219eSNikolai Kondrashov struct uclogic_params_frame { 689614219eSNikolai Kondrashov /* 699614219eSNikolai Kondrashov * Pointer to report descriptor describing the inputs. 709614219eSNikolai Kondrashov * Allocated with kmalloc. 719614219eSNikolai Kondrashov */ 729614219eSNikolai Kondrashov __u8 *desc_ptr; 739614219eSNikolai Kondrashov /* 749614219eSNikolai Kondrashov * Size of the report descriptor. 759614219eSNikolai Kondrashov * Only valid, if "desc_ptr" is not NULL. 769614219eSNikolai Kondrashov */ 779614219eSNikolai Kondrashov unsigned int desc_size; 789614219eSNikolai Kondrashov /* 799614219eSNikolai Kondrashov * Report ID, if reports should be tweaked, zero if not. 809614219eSNikolai Kondrashov */ 819614219eSNikolai Kondrashov unsigned int id; 829614219eSNikolai Kondrashov }; 839614219eSNikolai Kondrashov 849614219eSNikolai Kondrashov /* 859614219eSNikolai Kondrashov * Tablet interface report parameters. 869614219eSNikolai Kondrashov * 879614219eSNikolai Kondrashov * Must use declarative (descriptive) language, not imperative, to simplify 889614219eSNikolai Kondrashov * understanding and maintain consistency. 899614219eSNikolai Kondrashov * 909614219eSNikolai Kondrashov * When filled with zeros represents a "noop" configuration - passes all 919614219eSNikolai Kondrashov * reports unchanged and lets the generic HID driver handle everything. 929614219eSNikolai Kondrashov * 939614219eSNikolai Kondrashov * The resulting device report descriptor is assembled from all the report 949614219eSNikolai Kondrashov * descriptor parts referenced by the structure. No order of assembly should 959614219eSNikolai Kondrashov * be assumed. The structure represents original device report descriptor if 969614219eSNikolai Kondrashov * all the parts are NULL. 979614219eSNikolai Kondrashov */ 989614219eSNikolai Kondrashov struct uclogic_params { 999614219eSNikolai Kondrashov /* 1009614219eSNikolai Kondrashov * True if the whole interface is invalid, false otherwise. 1019614219eSNikolai Kondrashov */ 1029614219eSNikolai Kondrashov bool invalid; 1039614219eSNikolai Kondrashov /* 1049614219eSNikolai Kondrashov * Pointer to the common part of the replacement report descriptor, 1059614219eSNikolai Kondrashov * allocated with kmalloc. NULL if no common part is needed. 1069614219eSNikolai Kondrashov * Only valid, if "invalid" is false. 1079614219eSNikolai Kondrashov */ 1089614219eSNikolai Kondrashov __u8 *desc_ptr; 1099614219eSNikolai Kondrashov /* 1109614219eSNikolai Kondrashov * Size of the common part of the replacement report descriptor. 1119614219eSNikolai Kondrashov * Only valid, if "desc_ptr" is not NULL. 1129614219eSNikolai Kondrashov */ 1139614219eSNikolai Kondrashov unsigned int desc_size; 1149614219eSNikolai Kondrashov /* 1159614219eSNikolai Kondrashov * True, if pen usage in report descriptor is invalid, when present. 1169614219eSNikolai Kondrashov * Only valid, if "invalid" is false. 1179614219eSNikolai Kondrashov */ 1189614219eSNikolai Kondrashov bool pen_unused; 1199614219eSNikolai Kondrashov /* 1209614219eSNikolai Kondrashov * Pen parameters and optional report descriptor part. 1219614219eSNikolai Kondrashov * Only valid if "pen_unused" is valid and false. 1229614219eSNikolai Kondrashov */ 1239614219eSNikolai Kondrashov struct uclogic_params_pen pen; 1249614219eSNikolai Kondrashov /* 1259614219eSNikolai Kondrashov * Frame control parameters and optional report descriptor part. 1269614219eSNikolai Kondrashov * Only valid, if "invalid" is false. 1279614219eSNikolai Kondrashov */ 1289614219eSNikolai Kondrashov struct uclogic_params_frame frame; 1299614219eSNikolai Kondrashov /* 1309614219eSNikolai Kondrashov * Bitmask matching frame controls "sub-report" flag in the second 1319614219eSNikolai Kondrashov * byte of the pen report, or zero if it's not expected. 1329614219eSNikolai Kondrashov * Only valid if both "pen" and "frame" are valid, and "frame.id" is 1339614219eSNikolai Kondrashov * not zero. 1349614219eSNikolai Kondrashov */ 1359614219eSNikolai Kondrashov __u8 pen_frame_flag; 1369614219eSNikolai Kondrashov }; 1379614219eSNikolai Kondrashov 1389614219eSNikolai Kondrashov /* Initialize a tablet interface and discover its parameters */ 1399614219eSNikolai Kondrashov extern int uclogic_params_init(struct uclogic_params *params, 1409614219eSNikolai Kondrashov struct hid_device *hdev); 1419614219eSNikolai Kondrashov 1429614219eSNikolai Kondrashov /* Tablet interface parameters *printf format string */ 1439614219eSNikolai Kondrashov #define UCLOGIC_PARAMS_FMT_STR \ 1449614219eSNikolai Kondrashov ".invalid = %s\n" \ 1459614219eSNikolai Kondrashov ".desc_ptr = %p\n" \ 1469614219eSNikolai Kondrashov ".desc_size = %u\n" \ 1479614219eSNikolai Kondrashov ".pen_unused = %s\n" \ 1489614219eSNikolai Kondrashov ".pen.desc_ptr = %p\n" \ 1499614219eSNikolai Kondrashov ".pen.desc_size = %u\n" \ 1509614219eSNikolai Kondrashov ".pen.id = %u\n" \ 1519614219eSNikolai Kondrashov ".pen.inrange = %s\n" \ 1529614219eSNikolai Kondrashov ".frame.desc_ptr = %p\n" \ 1539614219eSNikolai Kondrashov ".frame.desc_size = %u\n" \ 1549614219eSNikolai Kondrashov ".frame.id = %u\n" \ 1559614219eSNikolai Kondrashov ".pen_frame_flag = 0x%02x\n" 1569614219eSNikolai Kondrashov 1579614219eSNikolai Kondrashov /* Tablet interface parameters *printf format arguments */ 1589614219eSNikolai Kondrashov #define UCLOGIC_PARAMS_FMT_ARGS(_params) \ 1599614219eSNikolai Kondrashov ((_params)->invalid ? "true" : "false"), \ 1609614219eSNikolai Kondrashov (_params)->desc_ptr, \ 1619614219eSNikolai Kondrashov (_params)->desc_size, \ 1629614219eSNikolai Kondrashov ((_params)->pen_unused ? "true" : "false"), \ 1639614219eSNikolai Kondrashov (_params)->pen.desc_ptr, \ 1649614219eSNikolai Kondrashov (_params)->pen.desc_size, \ 1659614219eSNikolai Kondrashov (_params)->pen.id, \ 1669614219eSNikolai Kondrashov uclogic_params_pen_inrange_to_str((_params)->pen.inrange), \ 1679614219eSNikolai Kondrashov (_params)->frame.desc_ptr, \ 1689614219eSNikolai Kondrashov (_params)->frame.desc_size, \ 1699614219eSNikolai Kondrashov (_params)->frame.id, \ 1709614219eSNikolai Kondrashov (_params)->pen_frame_flag 1719614219eSNikolai Kondrashov 1729614219eSNikolai Kondrashov /* Get a replacement report descriptor for a tablet's interface. */ 1739614219eSNikolai Kondrashov extern int uclogic_params_get_desc(const struct uclogic_params *params, 1749614219eSNikolai Kondrashov __u8 **pdesc, 1759614219eSNikolai Kondrashov unsigned int *psize); 1769614219eSNikolai Kondrashov 1779614219eSNikolai Kondrashov /* Free resources used by tablet interface's parameters */ 1789614219eSNikolai Kondrashov extern void uclogic_params_cleanup(struct uclogic_params *params); 1799614219eSNikolai Kondrashov 1809614219eSNikolai Kondrashov #endif /* _HID_UCLOGIC_PARAMS_H */ 181