1 /* 2 * kbdif.h -- Xen virtual keyboard/mouse 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining a copy 5 * of this software and associated documentation files (the "Software"), to 6 * deal in the Software without restriction, including without limitation the 7 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 8 * sell copies of the Software, and to permit persons to whom the Software is 9 * furnished to do so, subject to the following conditions: 10 * 11 * The above copyright notice and this permission notice shall be included in 12 * all copies or substantial portions of the Software. 13 * 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 19 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 20 * DEALINGS IN THE SOFTWARE. 21 * 22 * Copyright (C) 2005 Anthony Liguori <aliguori@us.ibm.com> 23 * Copyright (C) 2006 Red Hat, Inc., Markus Armbruster <armbru@redhat.com> 24 */ 25 26 #ifndef __XEN_PUBLIC_IO_KBDIF_H__ 27 #define __XEN_PUBLIC_IO_KBDIF_H__ 28 29 /* 30 ***************************************************************************** 31 * Feature and Parameter Negotiation 32 ***************************************************************************** 33 * 34 * The two halves of a para-virtual driver utilize nodes within 35 * XenStore to communicate capabilities and to negotiate operating parameters. 36 * This section enumerates these nodes which reside in the respective front and 37 * backend portions of XenStore, following XenBus convention. 38 * 39 * All data in XenStore is stored as strings. Nodes specifying numeric 40 * values are encoded in decimal. Integer value ranges listed below are 41 * expressed as fixed sized integer types capable of storing the conversion 42 * of a properly formated node string, without loss of information. 43 * 44 ***************************************************************************** 45 * Backend XenBus Nodes 46 ***************************************************************************** 47 * 48 *---------------------------- Features supported ---------------------------- 49 * 50 * Capable backend advertises supported features by publishing 51 * corresponding entries in XenStore and puts 1 as the value of the entry. 52 * If a feature is not supported then 0 must be set or feature entry omitted. 53 * 54 * feature-abs-pointer 55 * Values: <uint> 56 * 57 * Backends, which support reporting of absolute coordinates for pointer 58 * device should set this to 1. 59 * 60 * feature-multi-touch 61 * Values: <uint> 62 * 63 * Backends, which support reporting of multi-touch events 64 * should set this to 1. 65 * 66 *------------------------- Pointer Device Parameters ------------------------ 67 * 68 * width 69 * Values: <uint> 70 * 71 * Maximum X coordinate (width) to be used by the frontend 72 * while reporting input events, pixels, [0; UINT32_MAX]. 73 * 74 * height 75 * Values: <uint> 76 * 77 * Maximum Y coordinate (height) to be used by the frontend 78 * while reporting input events, pixels, [0; UINT32_MAX]. 79 * 80 ***************************************************************************** 81 * Frontend XenBus Nodes 82 ***************************************************************************** 83 * 84 *------------------------------ Feature request ----------------------------- 85 * 86 * Capable frontend requests features from backend via setting corresponding 87 * entries to 1 in XenStore. Requests for features not advertised as supported 88 * by the backend have no effect. 89 * 90 * request-abs-pointer 91 * Values: <uint> 92 * 93 * Request backend to report absolute pointer coordinates 94 * (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION). 95 * 96 * request-multi-touch 97 * Values: <uint> 98 * 99 * Request backend to report multi-touch events. 100 * 101 *----------------------- Request Transport Parameters ----------------------- 102 * 103 * event-channel 104 * Values: <uint> 105 * 106 * The identifier of the Xen event channel used to signal activity 107 * in the ring buffer. 108 * 109 * page-gref 110 * Values: <uint> 111 * 112 * The Xen grant reference granting permission for the backend to map 113 * a sole page in a single page sized event ring buffer. 114 * 115 * page-ref 116 * Values: <uint> 117 * 118 * OBSOLETE, not recommended for use. 119 * PFN of the shared page. 120 * 121 *----------------------- Multi-touch Device Parameters ----------------------- 122 * 123 * multi-touch-num-contacts 124 * Values: <uint> 125 * 126 * Number of simultaneous touches reported. 127 * 128 * multi-touch-width 129 * Values: <uint> 130 * 131 * Width of the touch area to be used by the frontend 132 * while reporting input events, pixels, [0; UINT32_MAX]. 133 * 134 * multi-touch-height 135 * Values: <uint> 136 * 137 * Height of the touch area to be used by the frontend 138 * while reporting input events, pixels, [0; UINT32_MAX]. 139 */ 140 141 /* 142 * EVENT CODES. 143 */ 144 145 #define XENKBD_TYPE_MOTION 1 146 #define XENKBD_TYPE_RESERVED 2 147 #define XENKBD_TYPE_KEY 3 148 #define XENKBD_TYPE_POS 4 149 #define XENKBD_TYPE_MTOUCH 5 150 151 /* Multi-touch event sub-codes */ 152 153 #define XENKBD_MT_EV_DOWN 0 154 #define XENKBD_MT_EV_UP 1 155 #define XENKBD_MT_EV_MOTION 2 156 #define XENKBD_MT_EV_SYN 3 157 #define XENKBD_MT_EV_SHAPE 4 158 #define XENKBD_MT_EV_ORIENT 5 159 160 /* 161 * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS. 162 */ 163 164 #define XENKBD_DRIVER_NAME "vkbd" 165 166 #define XENKBD_FIELD_FEAT_ABS_POINTER "feature-abs-pointer" 167 #define XENKBD_FIELD_FEAT_MTOUCH "feature-multi-touch" 168 #define XENKBD_FIELD_REQ_ABS_POINTER "request-abs-pointer" 169 #define XENKBD_FIELD_REQ_MTOUCH "request-multi-touch" 170 #define XENKBD_FIELD_RING_GREF "page-gref" 171 #define XENKBD_FIELD_EVT_CHANNEL "event-channel" 172 #define XENKBD_FIELD_WIDTH "width" 173 #define XENKBD_FIELD_HEIGHT "height" 174 #define XENKBD_FIELD_MT_WIDTH "multi-touch-width" 175 #define XENKBD_FIELD_MT_HEIGHT "multi-touch-height" 176 #define XENKBD_FIELD_MT_NUM_CONTACTS "multi-touch-num-contacts" 177 178 /* OBSOLETE, not recommended for use */ 179 #define XENKBD_FIELD_RING_REF "page-ref" 180 181 /* 182 ***************************************************************************** 183 * Description of the protocol between frontend and backend driver. 184 ***************************************************************************** 185 * 186 * The two halves of a Para-virtual driver communicate with 187 * each other using a shared page and an event channel. 188 * Shared page contains a ring with event structures. 189 * 190 * All reserved fields in the structures below must be 0. 191 * 192 ***************************************************************************** 193 * Backend to frontend events 194 ***************************************************************************** 195 * 196 * Frontends should ignore unknown in events. 197 * All event packets have the same length (40 octets) 198 * All event packets have common header: 199 * 200 * 0 octet 201 * +-----------------+ 202 * | type | 203 * +-----------------+ 204 * type - uint8_t, event code, XENKBD_TYPE_??? 205 * 206 * 207 * Pointer relative movement event 208 * 0 1 2 3 octet 209 * +----------------+----------------+----------------+----------------+ 210 * | _TYPE_MOTION | reserved | 4 211 * +----------------+----------------+----------------+----------------+ 212 * | rel_x | 8 213 * +----------------+----------------+----------------+----------------+ 214 * | rel_y | 12 215 * +----------------+----------------+----------------+----------------+ 216 * | rel_z | 16 217 * +----------------+----------------+----------------+----------------+ 218 * | reserved | 20 219 * +----------------+----------------+----------------+----------------+ 220 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 221 * +----------------+----------------+----------------+----------------+ 222 * | reserved | 40 223 * +----------------+----------------+----------------+----------------+ 224 * 225 * rel_x - int32_t, relative X motion 226 * rel_y - int32_t, relative Y motion 227 * rel_z - int32_t, relative Z motion (wheel) 228 */ 229 230 struct xenkbd_motion { 231 uint8_t type; 232 int32_t rel_x; 233 int32_t rel_y; 234 int32_t rel_z; 235 }; 236 237 /* 238 * Key event (includes pointer buttons) 239 * 0 1 2 3 octet 240 * +----------------+----------------+----------------+----------------+ 241 * | _TYPE_KEY | pressed | reserved | 4 242 * +----------------+----------------+----------------+----------------+ 243 * | keycode | 8 244 * +----------------+----------------+----------------+----------------+ 245 * | reserved | 12 246 * +----------------+----------------+----------------+----------------+ 247 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 248 * +----------------+----------------+----------------+----------------+ 249 * | reserved | 40 250 * +----------------+----------------+----------------+----------------+ 251 * 252 * pressed - uint8_t, 1 if pressed; 0 otherwise 253 * keycode - uint32_t, KEY_* from linux/input.h 254 */ 255 256 struct xenkbd_key { 257 uint8_t type; 258 uint8_t pressed; 259 uint32_t keycode; 260 }; 261 262 /* 263 * Pointer absolute position event 264 * 0 1 2 3 octet 265 * +----------------+----------------+----------------+----------------+ 266 * | _TYPE_POS | reserved | 4 267 * +----------------+----------------+----------------+----------------+ 268 * | abs_x | 8 269 * +----------------+----------------+----------------+----------------+ 270 * | abs_y | 12 271 * +----------------+----------------+----------------+----------------+ 272 * | rel_z | 16 273 * +----------------+----------------+----------------+----------------+ 274 * | reserved | 20 275 * +----------------+----------------+----------------+----------------+ 276 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 277 * +----------------+----------------+----------------+----------------+ 278 * | reserved | 40 279 * +----------------+----------------+----------------+----------------+ 280 * 281 * abs_x - int32_t, absolute X position (in FB pixels) 282 * abs_y - int32_t, absolute Y position (in FB pixels) 283 * rel_z - int32_t, relative Z motion (wheel) 284 */ 285 286 struct xenkbd_position { 287 uint8_t type; 288 int32_t abs_x; 289 int32_t abs_y; 290 int32_t rel_z; 291 }; 292 293 /* 294 * Multi-touch event and its sub-types 295 * 296 * All multi-touch event packets have common header: 297 * 298 * 0 1 2 3 octet 299 * +----------------+----------------+----------------+----------------+ 300 * | _TYPE_MTOUCH | event_type | contact_id | reserved | 4 301 * +----------------+----------------+----------------+----------------+ 302 * | reserved | 8 303 * +----------------+----------------+----------------+----------------+ 304 * 305 * event_type - unt8_t, multi-touch event sub-type, XENKBD_MT_EV_??? 306 * contact_id - unt8_t, ID of the contact 307 * 308 * Touch interactions can consist of one or more contacts. 309 * For each contact, a series of events is generated, starting 310 * with a down event, followed by zero or more motion events, 311 * and ending with an up event. Events relating to the same 312 * contact point can be identified by the ID of the sequence: contact ID. 313 * Contact ID may be reused after XENKBD_MT_EV_UP event and 314 * is in the [0; XENKBD_FIELD_NUM_CONTACTS - 1] range. 315 * 316 * For further information please refer to documentation on Wayland [1], 317 * Linux [2] and Windows [3] multi-touch support. 318 * 319 * [1] https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml 320 * [2] https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt 321 * [3] https://msdn.microsoft.com/en-us/library/jj151564(v=vs.85).aspx 322 * 323 * 324 * Multi-touch down event - sent when a new touch is made: touch is assigned 325 * a unique contact ID, sent with this and consequent events related 326 * to this touch. 327 * 0 1 2 3 octet 328 * +----------------+----------------+----------------+----------------+ 329 * | _TYPE_MTOUCH | _MT_EV_DOWN | contact_id | reserved | 4 330 * +----------------+----------------+----------------+----------------+ 331 * | reserved | 8 332 * +----------------+----------------+----------------+----------------+ 333 * | abs_x | 12 334 * +----------------+----------------+----------------+----------------+ 335 * | abs_y | 16 336 * +----------------+----------------+----------------+----------------+ 337 * | reserved | 20 338 * +----------------+----------------+----------------+----------------+ 339 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 340 * +----------------+----------------+----------------+----------------+ 341 * | reserved | 40 342 * +----------------+----------------+----------------+----------------+ 343 * 344 * abs_x - int32_t, absolute X position, in pixels 345 * abs_y - int32_t, absolute Y position, in pixels 346 * 347 * Multi-touch contact release event 348 * 0 1 2 3 octet 349 * +----------------+----------------+----------------+----------------+ 350 * | _TYPE_MTOUCH | _MT_EV_UP | contact_id | reserved | 4 351 * +----------------+----------------+----------------+----------------+ 352 * | reserved | 8 353 * +----------------+----------------+----------------+----------------+ 354 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 355 * +----------------+----------------+----------------+----------------+ 356 * | reserved | 40 357 * +----------------+----------------+----------------+----------------+ 358 * 359 * Multi-touch motion event 360 * 0 1 2 3 octet 361 * +----------------+----------------+----------------+----------------+ 362 * | _TYPE_MTOUCH | _MT_EV_MOTION | contact_id | reserved | 4 363 * +----------------+----------------+----------------+----------------+ 364 * | reserved | 8 365 * +----------------+----------------+----------------+----------------+ 366 * | abs_x | 12 367 * +----------------+----------------+----------------+----------------+ 368 * | abs_y | 16 369 * +----------------+----------------+----------------+----------------+ 370 * | reserved | 20 371 * +----------------+----------------+----------------+----------------+ 372 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 373 * +----------------+----------------+----------------+----------------+ 374 * | reserved | 40 375 * +----------------+----------------+----------------+----------------+ 376 * 377 * abs_x - int32_t, absolute X position, in pixels, 378 * abs_y - int32_t, absolute Y position, in pixels, 379 * 380 * Multi-touch input synchronization event - shows end of a set of events 381 * which logically belong together. 382 * 0 1 2 3 octet 383 * +----------------+----------------+----------------+----------------+ 384 * | _TYPE_MTOUCH | _MT_EV_SYN | contact_id | reserved | 4 385 * +----------------+----------------+----------------+----------------+ 386 * | reserved | 8 387 * +----------------+----------------+----------------+----------------+ 388 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 389 * +----------------+----------------+----------------+----------------+ 390 * | reserved | 40 391 * +----------------+----------------+----------------+----------------+ 392 * 393 * Multi-touch shape event - touch point's shape has changed its shape. 394 * Shape is approximated by an ellipse through the major and minor axis 395 * lengths: major is the longer diameter of the ellipse and minor is the 396 * shorter one. Center of the ellipse is reported via 397 * XENKBD_MT_EV_DOWN/XENKBD_MT_EV_MOTION events. 398 * 0 1 2 3 octet 399 * +----------------+----------------+----------------+----------------+ 400 * | _TYPE_MTOUCH | _MT_EV_SHAPE | contact_id | reserved | 4 401 * +----------------+----------------+----------------+----------------+ 402 * | reserved | 8 403 * +----------------+----------------+----------------+----------------+ 404 * | major | 12 405 * +----------------+----------------+----------------+----------------+ 406 * | minor | 16 407 * +----------------+----------------+----------------+----------------+ 408 * | reserved | 20 409 * +----------------+----------------+----------------+----------------+ 410 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 411 * +----------------+----------------+----------------+----------------+ 412 * | reserved | 40 413 * +----------------+----------------+----------------+----------------+ 414 * 415 * major - unt32_t, length of the major axis, pixels 416 * minor - unt32_t, length of the minor axis, pixels 417 * 418 * Multi-touch orientation event - touch point's shape has changed 419 * its orientation: calculated as a clockwise angle between the major axis 420 * of the ellipse and positive Y axis in degrees, [-180; +180]. 421 * 0 1 2 3 octet 422 * +----------------+----------------+----------------+----------------+ 423 * | _TYPE_MTOUCH | _MT_EV_ORIENT | contact_id | reserved | 4 424 * +----------------+----------------+----------------+----------------+ 425 * | reserved | 8 426 * +----------------+----------------+----------------+----------------+ 427 * | orientation | reserved | 12 428 * +----------------+----------------+----------------+----------------+ 429 * | reserved | 16 430 * +----------------+----------------+----------------+----------------+ 431 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 432 * +----------------+----------------+----------------+----------------+ 433 * | reserved | 40 434 * +----------------+----------------+----------------+----------------+ 435 * 436 * orientation - int16_t, clockwise angle of the major axis 437 */ 438 439 struct xenkbd_mtouch { 440 uint8_t type; /* XENKBD_TYPE_MTOUCH */ 441 uint8_t event_type; /* XENKBD_MT_EV_??? */ 442 uint8_t contact_id; 443 uint8_t reserved[5]; /* reserved for the future use */ 444 union { 445 struct { 446 int32_t abs_x; /* absolute X position, pixels */ 447 int32_t abs_y; /* absolute Y position, pixels */ 448 } pos; 449 struct { 450 uint32_t major; /* length of the major axis, pixels */ 451 uint32_t minor; /* length of the minor axis, pixels */ 452 } shape; 453 int16_t orientation; /* clockwise angle of the major axis */ 454 } u; 455 }; 456 457 #define XENKBD_IN_EVENT_SIZE 40 458 459 union xenkbd_in_event { 460 uint8_t type; 461 struct xenkbd_motion motion; 462 struct xenkbd_key key; 463 struct xenkbd_position pos; 464 struct xenkbd_mtouch mtouch; 465 char pad[XENKBD_IN_EVENT_SIZE]; 466 }; 467 468 /* 469 ***************************************************************************** 470 * Frontend to backend events 471 ***************************************************************************** 472 * 473 * Out events may be sent only when requested by backend, and receipt 474 * of an unknown out event is an error. 475 * No out events currently defined. 476 477 * All event packets have the same length (40 octets) 478 * All event packets have common header: 479 * 0 octet 480 * +-----------------+ 481 * | type | 482 * +-----------------+ 483 * type - uint8_t, event code 484 */ 485 486 #define XENKBD_OUT_EVENT_SIZE 40 487 488 union xenkbd_out_event { 489 uint8_t type; 490 char pad[XENKBD_OUT_EVENT_SIZE]; 491 }; 492 493 /* 494 ***************************************************************************** 495 * Shared page 496 ***************************************************************************** 497 */ 498 499 #define XENKBD_IN_RING_SIZE 2048 500 #define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE) 501 #define XENKBD_IN_RING_OFFS 1024 502 #define XENKBD_IN_RING(page) \ 503 ((union xenkbd_in_event *)((char *)(page) + XENKBD_IN_RING_OFFS)) 504 #define XENKBD_IN_RING_REF(page, idx) \ 505 (XENKBD_IN_RING((page))[(idx) % XENKBD_IN_RING_LEN]) 506 507 #define XENKBD_OUT_RING_SIZE 1024 508 #define XENKBD_OUT_RING_LEN (XENKBD_OUT_RING_SIZE / XENKBD_OUT_EVENT_SIZE) 509 #define XENKBD_OUT_RING_OFFS (XENKBD_IN_RING_OFFS + XENKBD_IN_RING_SIZE) 510 #define XENKBD_OUT_RING(page) \ 511 ((union xenkbd_out_event *)((char *)(page) + XENKBD_OUT_RING_OFFS)) 512 #define XENKBD_OUT_RING_REF(page, idx) \ 513 (XENKBD_OUT_RING((page))[(idx) % XENKBD_OUT_RING_LEN]) 514 515 struct xenkbd_page { 516 uint32_t in_cons, in_prod; 517 uint32_t out_cons, out_prod; 518 }; 519 520 #endif /* __XEN_PUBLIC_IO_KBDIF_H__ */ 521