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