1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */ 2 3 #ifndef _TOUCH_OFFLOAD_H 4 #define _TOUCH_OFFLOAD_H 5 6 #define TOUCH_OFFLOAD_INTERFACE_MAJOR_VERSION 2 7 #define TOUCH_OFFLOAD_INTERFACE_MINOR_VERSION 0 8 9 #define TOUCH_OFFLOAD_MAGIC '7' 10 11 /* Bus interface type */ 12 #define BUS_TYPE_I2C 0 13 #define BUS_TYPE_SPI 1 14 #define BUS_TYPE_I3C 2 15 16 /* Indicates full heatmap frame vs. partial */ 17 #define HEATMAP_SIZE_PARTIAL 0 18 #define HEATMAP_SIZE_FULL 1 19 20 /* Touch channel data types */ 21 #define TOUCH_DATA_TYPE_COORD 0x0001 22 #define TOUCH_DATA_TYPE_RAW 0x0002 23 #define TOUCH_DATA_TYPE_FILTERED 0x0004 24 #define TOUCH_DATA_TYPE_BASELINE 0x0008 25 #define TOUCH_DATA_TYPE_STRENGTH 0x0010 26 27 /* Touch channel scan types */ 28 #define TOUCH_SCAN_TYPE_MUTUAL 0x0040 29 #define TOUCH_SCAN_TYPE_SELF 0x0080 30 31 /* "Context" channel types */ 32 #define CONTEXT_CHANNEL_TYPE_DRIVER_STATUS 0x0100 33 #define CONTEXT_CHANNEL_TYPE_STYLUS_STATUS 0x0200 34 /* Inclusive range of valid context channels */ 35 #define CONTEXT_CHANNEL_BIT_START 0x0100 36 #define CONTEXT_CHANNEL_BIT_END 0x0200 37 38 ////////////////////////////////////////////////////////////// 39 40 /* TouchOffloadCaps 41 * 42 * touch_offload_major_version - Major version for breaking changes 43 * touch_offload_minor_version - Minor version for small, compatible changes 44 * device_id - device-specific identifier 45 * display_width - width of device display in pixels 46 * display_height - height of device display in pixels 47 * tx_size - number of TX channels 48 * rx_size - number of RX channels 49 * bus_type - bus interface type 50 * bus_speed_hz - bus frequency 51 * heatmap_size - partial or full heatmap 52 * touch_data_scan_types - channel data types available 53 * touch_scan_types - channel scan types available 54 * context_channel_types - bitfield of additional supported channels 55 * continuous_reporting - driver supports continuous touch reports 56 * noise_reporting - driver supports noise status messages 57 * cancel_reporting - driver supports sending cancel events 58 * size_reporting - driver supports size information 59 * rotation_reporting - driver supports rotation information 60 * filter_grip - driver supports disabling underlying grip suppression 61 * filter_palm - driver supports disabling underlying palm rejection 62 * num_sensitivity_settings - number of sensitivity options provided 63 * auto_reporting - report heatmap when screen is not touched 64 * coord_filter - driver supports disabling underlying coordinate filter 65 */ 66 struct TouchOffloadCaps { 67 /* Version info */ 68 __u32 touch_offload_major_version; 69 __u32 touch_offload_minor_version; 70 __u8 reserved1[8]; 71 72 /* Device info */ 73 __u32 device_id; 74 __u16 display_width; 75 __u16 display_height; 76 __u16 tx_size; 77 __u16 rx_size; 78 __u8 bus_type; 79 __u32 bus_speed_hz; 80 __u8 reserved2[16]; 81 82 /* Algorithm info */ 83 __u8 heatmap_size; 84 __u16 touch_data_types; 85 __u16 touch_scan_types; 86 __u16 context_channel_types; 87 __u8 reserved3[16]; 88 89 /* Feature flags */ 90 __u8 continuous_reporting; 91 __u8 noise_reporting; 92 __u8 cancel_reporting; 93 __u8 size_reporting; 94 __u8 rotation_reporting; 95 __u8 filter_grip; 96 __u8 filter_palm; 97 __u8 num_sensitivity_settings; 98 __u8 auto_reporting; 99 __u8 coord_filter; 100 __u8 reserved4[31]; 101 } __attribute__((packed)); 102 103 /* TouchOffloadConfig 104 * 105 * continuous_reporting - enable continuous touch reports 106 * noise_reporting - enable noise status messages 107 * cancel_reporting - enable cancel events 108 * filter_grip - enable underlying grip suppression 109 * filter_palm - enable underlying palm rejection 110 * sensitivity_setting - selected sensitivity 111 * auto_reporting - enable reporting when screen is not touched 112 * coord_filter - enable underlying coordinate filter 113 * read_coords - allocate a channel to coordinate data 114 * mutual_data_types - bitfield of mutual data types to collect 115 * self_data_types - bitfield of self data types to collect 116 * context_channel_types - bitfield of context channels to collect - overlays 117 * on channel type bit mask 118 */ 119 struct TouchOffloadConfig { 120 /* Feature flags */ 121 __u8 continuous_reporting; 122 __u8 noise_reporting; 123 __u8 cancel_reporting; 124 __u8 filter_grip; 125 __u8 filter_palm; 126 __u8 sensitivity_setting; 127 __u8 auto_reporting; 128 __u8 coord_filter; 129 __u8 reserved1[15]; 130 131 /* Data to read */ 132 __u8 read_coords; 133 __u16 mutual_data_types; 134 __u16 self_data_types; 135 __u16 context_channel_types; 136 __u8 reserved2[16]; 137 } __attribute__((packed)); 138 139 /* TouchOffloadFrameHeader 140 * 141 * frame_size - number of bytes in the frame 142 * index - unique, sequential frame index 143 * timestamp - frame timestamp in nanoseconds 144 * num_channels - number of channels included in the frame 145 */ 146 struct TouchOffloadFrameHeader { 147 __u32 frame_size; 148 __u64 index; 149 __u64 timestamp; 150 __u8 num_channels; 151 } __attribute__((packed)); 152 153 /* TouchOffloadChannelHeader 154 * 155 * channel_type - touch type stored in the channel 156 * channel_size - size in bytes of the channel sample 157 */ 158 struct TouchOffloadChannelHeader { 159 __u32 channel_type; 160 __u32 channel_size; 161 } __attribute__((packed)); 162 163 /* CoordStatus 164 * 165 * COORD_STATUS_INACTIVE - slot is unused 166 * COORD_STATUS_FINGER - normal finger touch 167 * COORD_STATUS_EDGE - edge touch 168 * COORD_STATUS_PALM - palm touch 169 * COORD_STATUS_CANCEL - canceled touch 170 * COORD_STATUS_PEN - stylus pen touch 171 */ 172 enum CoordStatus { 173 COORD_STATUS_INACTIVE = 0x00, 174 COORD_STATUS_FINGER = 0x01, 175 COORD_STATUS_EDGE = 0x02, 176 COORD_STATUS_PALM = 0x03, 177 COORD_STATUS_CANCEL = 0x04, 178 COORD_STATUS_PEN = 0x05 179 }; 180 181 /* Maximum number of touches that are tracked simultaneously */ 182 #define MAX_COORDS 10 183 184 /* TouchOffloadCoord 185 * 186 * x - x component of touch location 187 * y - y component of touch location 188 * status - type of touch 189 * major - size of the larger axis of the touch blob 190 * minor - size of the smaller axis of the touch blob 191 * pressure - z-axis or force exerted on touch touch point 192 * rotation - signed rotation of major axis from y-axis, where -16384 is a 193 * full rotation to the left and 16384 is a rotation to the right. 194 */ 195 struct TouchOffloadCoord { 196 __u16 x; 197 __u16 y; 198 enum CoordStatus status; 199 __u32 major; 200 __u32 minor; 201 __u32 pressure; 202 __s16 rotation; 203 __u8 reserved1[16]; 204 } __attribute__((packed)); 205 206 /* TouchOffloadDataCoord 207 * 208 * header - header shared by all channels in a frame 209 * coords - array of MAX_COORD coordinates 210 */ 211 struct TouchOffloadDataCoord { 212 struct TouchOffloadChannelHeader header; 213 struct TouchOffloadCoord coords[MAX_COORDS]; 214 __u8 reserved1[16]; 215 } __attribute__((packed)); 216 #define TOUCH_OFFLOAD_FRAME_SIZE_COORD (sizeof(struct TouchOffloadDataCoord)) 217 218 /* TouchOffloadData2d 219 * 220 * header - header shared by all channels in a frame 221 * tx_size - number of tx channels 222 * rx_size - number of rx channels 223 * data - pointer to raw touch data buffer 224 */ 225 struct TouchOffloadData2d { 226 struct TouchOffloadChannelHeader header; 227 __u16 tx_size; 228 __u16 rx_size; 229 __u8 reserved1[16]; 230 __u8 data[1]; 231 } __attribute__((packed)); 232 #define TOUCH_OFFLOAD_DATA_SIZE_2D(rx, tx) (sizeof(__u16)*(rx)*(tx)) 233 #define TOUCH_OFFLOAD_FRAME_SIZE_2D(rx, tx) \ 234 (sizeof(struct TouchOffloadData2d) - 1 + \ 235 TOUCH_OFFLOAD_DATA_SIZE_2D((rx), (tx))) 236 237 /* TouchOffloadData1d 238 * 239 * header - header shared by all channels in a frame 240 * tx_size - number of tx channels 241 * rx_size - number of rx channels 242 * data - pointer to raw touch data buffer 243 */ 244 struct TouchOffloadData1d { 245 struct TouchOffloadChannelHeader header; 246 __u16 tx_size; 247 __u16 rx_size; 248 __u8 reserved1[16]; 249 __u8 data[1]; 250 } __attribute__((packed)); 251 #define TOUCH_OFFLOAD_DATA_SIZE_1D(rx, tx) (sizeof(__u16)*((rx)+(tx))) 252 #define TOUCH_OFFLOAD_FRAME_SIZE_1D(rx, tx) \ 253 (sizeof(struct TouchOffloadData1d) - 1 + \ 254 TOUCH_OFFLOAD_DATA_SIZE_1D((rx), (tx))) 255 256 /* TouchOffloadDriverStatus 257 * 258 * header - header shared by all channels in a frame 259 * contents - bitfield indicating the corresponding data field is valid 260 * screen_state - 0 = off, 1 = on 261 * display_refresh_rate - display refresh rate in hz 262 * touch_report_rate - touch report rate in hz 263 * noise_state - 0 = no noise, 1 = noise present 264 * water_mode - 0 = normal mode, 1 = water mode 265 * charger_state - 0 = no charger, 1 = charger connected 266 * hinge_angle - angle in range [0=closed, 32767=open 360 degrees] 267 * offload_timestamp - recorded when touch offload frame was generated 268 */ 269 struct TouchOffloadDriverStatus { 270 struct TouchOffloadChannelHeader header; 271 272 struct { 273 __u32 screen_state : 1; 274 __u32 display_refresh_rate : 1; 275 __u32 touch_report_rate : 1; 276 __u32 noise_state : 1; 277 __u32 water_mode : 1; 278 __u32 charger_state : 1; 279 __u32 hinge_angle : 1; 280 __u32 offload_timestamp : 1; 281 } contents; 282 __u8 reserved1[8]; 283 284 __u8 screen_state; 285 __u8 display_refresh_rate; 286 __u8 touch_report_rate; 287 __u8 noise_state; 288 __u8 water_mode; 289 __u8 charger_state; 290 __s16 hinge_angle; 291 292 __u64 offload_timestamp; 293 294 __u8 reserved2[32]; 295 } __attribute__((packed)); 296 #define TOUCH_OFFLOAD_FRAME_SIZE_DRIVER_STATUS \ 297 (sizeof(struct TouchOffloadDriverStatus)) 298 299 /* TouchOffloadStylusStatus 300 * 301 * header - header shared by all channels in a frame 302 * contents - bitfield indicating the corresponding data field is valid 303 * coords - Up to MAX_COORDS active stylus touch points 304 * coords_timestamp - timestamp at which stylus coordinates were received 305 * pen_paired - 0 = no pen paired, 1 = a pen paired 306 * pen_active - 0 = no activity, 1 = a pen is actively communicating 307 */ 308 struct TouchOffloadStylusStatus { 309 struct TouchOffloadChannelHeader header; 310 311 struct { 312 __u32 coords : 1; 313 __u32 coords_timestamp : 1; 314 __u32 pen_paired : 1; 315 __u32 pen_active : 1; 316 } contents; 317 __u8 reserved1[8]; 318 319 struct TouchOffloadCoord coords[MAX_COORDS]; 320 __u64 coords_timestamp; 321 __u8 reserved2[16]; 322 323 __u8 pen_paired; 324 __u8 pen_active; 325 __u8 reserved3[16]; 326 } __attribute__((packed)); 327 #define TOUCH_OFFLOAD_FRAME_SIZE_STYLUS_STATUS \ 328 (sizeof(struct TouchOffloadStylusStatus)) 329 330 //////////////////////////////////////////////////////////// 331 332 /* TouchOffloadIocGetCaps 333 * 334 * caps - capabilities provided by the touch driver 335 */ 336 struct TouchOffloadIocGetCaps { 337 struct TouchOffloadCaps caps; 338 __u8 reserved1[16]; 339 } __attribute__((packed)); 340 341 /* TouchOffloadIocConfigure 342 * 343 * config - features to be used by the touch_offload client 344 */ 345 struct TouchOffloadIocConfigure { 346 struct TouchOffloadConfig config; 347 __u8 reserved1[16]; 348 } __attribute__((packed)); 349 350 /* TouchOffloadIocReport 351 * 352 * index - unique, sequential frame index 353 * timestamp - frame timestamp in nanoseconds 354 * num_coords - number of coordinates contained in "coords" 355 * coords - array of coordinates to be reported to the driver 356 */ 357 struct TouchOffloadIocReport { 358 __u64 index; 359 __u64 timestamp; 360 __u8 num_coords; 361 __u8 reserved1[16]; 362 struct TouchOffloadCoord coords[MAX_COORDS]; 363 } __attribute__((packed)); 364 365 /* Ioctl to retrieve the capabilities of the touch driver */ 366 #define TOUCH_OFFLOAD_IOC_RD_GETCAPS \ 367 _IOR(TOUCH_OFFLOAD_MAGIC, 0, struct TouchOffloadIocGetCaps) 368 369 /* Ioctl to set the configuration of the touch driver */ 370 #define TOUCH_OFFLOAD_IOC_WR_CONFIGURE \ 371 _IOW(TOUCH_OFFLOAD_MAGIC, 1, struct TouchOffloadIocConfigure) 372 373 /* Ioctl to start the touch_offload pipeline */ 374 #define TOUCH_OFFLOAD_IOC_START _IOC(TOUCH_OFFLOAD_MAGIC, 2) 375 376 /* Ioctl to report coordinates to the driver */ 377 #define TOUCH_OFFLOAD_IOC_WR_REPORT \ 378 _IOW(TOUCH_OFFLOAD_MAGIC, 3, struct TouchOffloadIocReport) 379 380 /* Ioctl to stop the touch_offload pipeline */ 381 #define TOUCH_OFFLOAD_IOC_STOP _IOC(TOUCH_OFFLOAD_MAGIC, 4) 382 383 #endif /* _TOUCH_OFFLOAD_H */ 384