544 lines · c
1/* SPDX-License-Identifier: MIT */2/*3 * kbdif.h -- Xen virtual keyboard/mouse4 *5 * Copyright (C) 2005 Anthony Liguori <aliguori@us.ibm.com>6 * Copyright (C) 2006 Red Hat, Inc., Markus Armbruster <armbru@redhat.com>7 */8 9#ifndef __XEN_PUBLIC_IO_KBDIF_H__10#define __XEN_PUBLIC_IO_KBDIF_H__11 12/*13 *****************************************************************************14 * Feature and Parameter Negotiation15 *****************************************************************************16 *17 * The two halves of a para-virtual driver utilize nodes within18 * XenStore to communicate capabilities and to negotiate operating parameters.19 * This section enumerates these nodes which reside in the respective front and20 * backend portions of XenStore, following XenBus convention.21 *22 * All data in XenStore is stored as strings. Nodes specifying numeric23 * values are encoded in decimal. Integer value ranges listed below are24 * expressed as fixed sized integer types capable of storing the conversion25 * of a properly formated node string, without loss of information.26 *27 *****************************************************************************28 * Backend XenBus Nodes29 *****************************************************************************30 *31 *---------------------------- Features supported ----------------------------32 *33 * Capable backend advertises supported features by publishing34 * corresponding entries in XenStore and puts 1 as the value of the entry.35 * If a feature is not supported then 0 must be set or feature entry omitted.36 *37 * feature-disable-keyboard38 * Values: <uint>39 *40 * If there is no need to expose a virtual keyboard device by the41 * frontend then this must be set to 1.42 *43 * feature-disable-pointer44 * Values: <uint>45 *46 * If there is no need to expose a virtual pointer device by the47 * frontend then this must be set to 1.48 *49 * feature-abs-pointer50 * Values: <uint>51 *52 * Backends, which support reporting of absolute coordinates for pointer53 * device should set this to 1.54 *55 * feature-multi-touch56 * Values: <uint>57 *58 * Backends, which support reporting of multi-touch events59 * should set this to 1.60 *61 * feature-raw-pointer62 * Values: <uint>63 *64 * Backends, which support reporting raw (unscaled) absolute coordinates65 * for pointer devices should set this to 1. Raw (unscaled) values have66 * a range of [0, 0x7fff].67 *68 *----------------------- Device Instance Parameters ------------------------69 *70 * unique-id71 * Values: <string>72 *73 * After device instance initialization it is assigned a unique ID,74 * so every instance of the frontend can be identified by the backend75 * by this ID. This can be UUID or such.76 *77 *------------------------- Pointer Device Parameters ------------------------78 *79 * width80 * Values: <uint>81 *82 * Maximum X coordinate (width) to be used by the frontend83 * while reporting input events, pixels, [0; UINT32_MAX].84 *85 * height86 * Values: <uint>87 *88 * Maximum Y coordinate (height) to be used by the frontend89 * while reporting input events, pixels, [0; UINT32_MAX].90 *91 *----------------------- Multi-touch Device Parameters ----------------------92 *93 * multi-touch-num-contacts94 * Values: <uint>95 *96 * Number of simultaneous touches reported.97 *98 * multi-touch-width99 * Values: <uint>100 *101 * Width of the touch area to be used by the frontend102 * while reporting input events, pixels, [0; UINT32_MAX].103 *104 * multi-touch-height105 * Values: <uint>106 *107 * Height of the touch area to be used by the frontend108 * while reporting input events, pixels, [0; UINT32_MAX].109 *110 *****************************************************************************111 * Frontend XenBus Nodes112 *****************************************************************************113 *114 *------------------------------ Feature request -----------------------------115 *116 * Capable frontend requests features from backend via setting corresponding117 * entries to 1 in XenStore. Requests for features not advertised as supported118 * by the backend have no effect.119 *120 * request-abs-pointer121 * Values: <uint>122 *123 * Request backend to report absolute pointer coordinates124 * (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).125 *126 * request-multi-touch127 * Values: <uint>128 *129 * Request backend to report multi-touch events.130 *131 * request-raw-pointer132 * Values: <uint>133 *134 * Request backend to report raw unscaled absolute pointer coordinates.135 * This option is only valid if request-abs-pointer is also set.136 * Raw unscaled coordinates have the range [0, 0x7fff]137 *138 *----------------------- Request Transport Parameters -----------------------139 *140 * event-channel141 * Values: <uint>142 *143 * The identifier of the Xen event channel used to signal activity144 * in the ring buffer.145 *146 * page-gref147 * Values: <uint>148 *149 * The Xen grant reference granting permission for the backend to map150 * a sole page in a single page sized event ring buffer.151 *152 * page-ref153 * Values: <uint>154 *155 * OBSOLETE, not recommended for use.156 * PFN of the shared page.157 */158 159/*160 * EVENT CODES.161 */162 163#define XENKBD_TYPE_MOTION 1164#define XENKBD_TYPE_RESERVED 2165#define XENKBD_TYPE_KEY 3166#define XENKBD_TYPE_POS 4167#define XENKBD_TYPE_MTOUCH 5168 169/* Multi-touch event sub-codes */170 171#define XENKBD_MT_EV_DOWN 0172#define XENKBD_MT_EV_UP 1173#define XENKBD_MT_EV_MOTION 2174#define XENKBD_MT_EV_SYN 3175#define XENKBD_MT_EV_SHAPE 4176#define XENKBD_MT_EV_ORIENT 5177 178/*179 * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS.180 */181 182#define XENKBD_DRIVER_NAME "vkbd"183 184#define XENKBD_FIELD_FEAT_DSBL_KEYBRD "feature-disable-keyboard"185#define XENKBD_FIELD_FEAT_DSBL_POINTER "feature-disable-pointer"186#define XENKBD_FIELD_FEAT_ABS_POINTER "feature-abs-pointer"187#define XENKBD_FIELD_FEAT_RAW_POINTER "feature-raw-pointer"188#define XENKBD_FIELD_FEAT_MTOUCH "feature-multi-touch"189#define XENKBD_FIELD_REQ_ABS_POINTER "request-abs-pointer"190#define XENKBD_FIELD_REQ_RAW_POINTER "request-raw-pointer"191#define XENKBD_FIELD_REQ_MTOUCH "request-multi-touch"192#define XENKBD_FIELD_RING_GREF "page-gref"193#define XENKBD_FIELD_EVT_CHANNEL "event-channel"194#define XENKBD_FIELD_WIDTH "width"195#define XENKBD_FIELD_HEIGHT "height"196#define XENKBD_FIELD_MT_WIDTH "multi-touch-width"197#define XENKBD_FIELD_MT_HEIGHT "multi-touch-height"198#define XENKBD_FIELD_MT_NUM_CONTACTS "multi-touch-num-contacts"199#define XENKBD_FIELD_UNIQUE_ID "unique-id"200 201/* OBSOLETE, not recommended for use */202#define XENKBD_FIELD_RING_REF "page-ref"203 204/*205 *****************************************************************************206 * Description of the protocol between frontend and backend driver.207 *****************************************************************************208 *209 * The two halves of a Para-virtual driver communicate with210 * each other using a shared page and an event channel.211 * Shared page contains a ring with event structures.212 *213 * All reserved fields in the structures below must be 0.214 *215 *****************************************************************************216 * Backend to frontend events217 *****************************************************************************218 *219 * Frontends should ignore unknown in events.220 * All event packets have the same length (40 octets)221 * All event packets have common header:222 *223 * 0 octet224 * +-----------------+225 * | type |226 * +-----------------+227 * type - uint8_t, event code, XENKBD_TYPE_???228 *229 *230 * Pointer relative movement event231 * 0 1 2 3 octet232 * +----------------+----------------+----------------+----------------+233 * | _TYPE_MOTION | reserved | 4234 * +----------------+----------------+----------------+----------------+235 * | rel_x | 8236 * +----------------+----------------+----------------+----------------+237 * | rel_y | 12238 * +----------------+----------------+----------------+----------------+239 * | rel_z | 16240 * +----------------+----------------+----------------+----------------+241 * | reserved | 20242 * +----------------+----------------+----------------+----------------+243 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|244 * +----------------+----------------+----------------+----------------+245 * | reserved | 40246 * +----------------+----------------+----------------+----------------+247 *248 * rel_x - int32_t, relative X motion249 * rel_y - int32_t, relative Y motion250 * rel_z - int32_t, relative Z motion (wheel)251 */252 253struct xenkbd_motion {254 uint8_t type;255 int32_t rel_x;256 int32_t rel_y;257 int32_t rel_z;258};259 260/*261 * Key event (includes pointer buttons)262 * 0 1 2 3 octet263 * +----------------+----------------+----------------+----------------+264 * | _TYPE_KEY | pressed | reserved | 4265 * +----------------+----------------+----------------+----------------+266 * | keycode | 8267 * +----------------+----------------+----------------+----------------+268 * | reserved | 12269 * +----------------+----------------+----------------+----------------+270 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|271 * +----------------+----------------+----------------+----------------+272 * | reserved | 40273 * +----------------+----------------+----------------+----------------+274 *275 * pressed - uint8_t, 1 if pressed; 0 otherwise276 * keycode - uint32_t, KEY_* from linux/input.h277 */278 279struct xenkbd_key {280 uint8_t type;281 uint8_t pressed;282 uint32_t keycode;283};284 285/*286 * Pointer absolute position event287 * 0 1 2 3 octet288 * +----------------+----------------+----------------+----------------+289 * | _TYPE_POS | reserved | 4290 * +----------------+----------------+----------------+----------------+291 * | abs_x | 8292 * +----------------+----------------+----------------+----------------+293 * | abs_y | 12294 * +----------------+----------------+----------------+----------------+295 * | rel_z | 16296 * +----------------+----------------+----------------+----------------+297 * | reserved | 20298 * +----------------+----------------+----------------+----------------+299 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|300 * +----------------+----------------+----------------+----------------+301 * | reserved | 40302 * +----------------+----------------+----------------+----------------+303 *304 * abs_x - int32_t, absolute X position (in FB pixels)305 * abs_y - int32_t, absolute Y position (in FB pixels)306 * rel_z - int32_t, relative Z motion (wheel)307 */308 309struct xenkbd_position {310 uint8_t type;311 int32_t abs_x;312 int32_t abs_y;313 int32_t rel_z;314};315 316/*317 * Multi-touch event and its sub-types318 *319 * All multi-touch event packets have common header:320 *321 * 0 1 2 3 octet322 * +----------------+----------------+----------------+----------------+323 * | _TYPE_MTOUCH | event_type | contact_id | reserved | 4324 * +----------------+----------------+----------------+----------------+325 * | reserved | 8326 * +----------------+----------------+----------------+----------------+327 *328 * event_type - unt8_t, multi-touch event sub-type, XENKBD_MT_EV_???329 * contact_id - unt8_t, ID of the contact330 *331 * Touch interactions can consist of one or more contacts.332 * For each contact, a series of events is generated, starting333 * with a down event, followed by zero or more motion events,334 * and ending with an up event. Events relating to the same335 * contact point can be identified by the ID of the sequence: contact ID.336 * Contact ID may be reused after XENKBD_MT_EV_UP event and337 * is in the [0; XENKBD_FIELD_NUM_CONTACTS - 1] range.338 *339 * For further information please refer to documentation on Wayland [1],340 * Linux [2] and Windows [3] multi-touch support.341 *342 * [1] https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml343 * [2] https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.rst344 * [3] https://msdn.microsoft.com/en-us/library/jj151564(v=vs.85).aspx345 *346 *347 * Multi-touch down event - sent when a new touch is made: touch is assigned348 * a unique contact ID, sent with this and consequent events related349 * to this touch.350 * 0 1 2 3 octet351 * +----------------+----------------+----------------+----------------+352 * | _TYPE_MTOUCH | _MT_EV_DOWN | contact_id | reserved | 4353 * +----------------+----------------+----------------+----------------+354 * | reserved | 8355 * +----------------+----------------+----------------+----------------+356 * | abs_x | 12357 * +----------------+----------------+----------------+----------------+358 * | abs_y | 16359 * +----------------+----------------+----------------+----------------+360 * | reserved | 20361 * +----------------+----------------+----------------+----------------+362 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|363 * +----------------+----------------+----------------+----------------+364 * | reserved | 40365 * +----------------+----------------+----------------+----------------+366 *367 * abs_x - int32_t, absolute X position, in pixels368 * abs_y - int32_t, absolute Y position, in pixels369 *370 * Multi-touch contact release event371 * 0 1 2 3 octet372 * +----------------+----------------+----------------+----------------+373 * | _TYPE_MTOUCH | _MT_EV_UP | contact_id | reserved | 4374 * +----------------+----------------+----------------+----------------+375 * | reserved | 8376 * +----------------+----------------+----------------+----------------+377 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|378 * +----------------+----------------+----------------+----------------+379 * | reserved | 40380 * +----------------+----------------+----------------+----------------+381 *382 * Multi-touch motion event383 * 0 1 2 3 octet384 * +----------------+----------------+----------------+----------------+385 * | _TYPE_MTOUCH | _MT_EV_MOTION | contact_id | reserved | 4386 * +----------------+----------------+----------------+----------------+387 * | reserved | 8388 * +----------------+----------------+----------------+----------------+389 * | abs_x | 12390 * +----------------+----------------+----------------+----------------+391 * | abs_y | 16392 * +----------------+----------------+----------------+----------------+393 * | reserved | 20394 * +----------------+----------------+----------------+----------------+395 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|396 * +----------------+----------------+----------------+----------------+397 * | reserved | 40398 * +----------------+----------------+----------------+----------------+399 *400 * abs_x - int32_t, absolute X position, in pixels,401 * abs_y - int32_t, absolute Y position, in pixels,402 *403 * Multi-touch input synchronization event - shows end of a set of events404 * which logically belong together.405 * 0 1 2 3 octet406 * +----------------+----------------+----------------+----------------+407 * | _TYPE_MTOUCH | _MT_EV_SYN | contact_id | reserved | 4408 * +----------------+----------------+----------------+----------------+409 * | reserved | 8410 * +----------------+----------------+----------------+----------------+411 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|412 * +----------------+----------------+----------------+----------------+413 * | reserved | 40414 * +----------------+----------------+----------------+----------------+415 *416 * Multi-touch shape event - touch point's shape has changed its shape.417 * Shape is approximated by an ellipse through the major and minor axis418 * lengths: major is the longer diameter of the ellipse and minor is the419 * shorter one. Center of the ellipse is reported via420 * XENKBD_MT_EV_DOWN/XENKBD_MT_EV_MOTION events.421 * 0 1 2 3 octet422 * +----------------+----------------+----------------+----------------+423 * | _TYPE_MTOUCH | _MT_EV_SHAPE | contact_id | reserved | 4424 * +----------------+----------------+----------------+----------------+425 * | reserved | 8426 * +----------------+----------------+----------------+----------------+427 * | major | 12428 * +----------------+----------------+----------------+----------------+429 * | minor | 16430 * +----------------+----------------+----------------+----------------+431 * | reserved | 20432 * +----------------+----------------+----------------+----------------+433 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|434 * +----------------+----------------+----------------+----------------+435 * | reserved | 40436 * +----------------+----------------+----------------+----------------+437 *438 * major - unt32_t, length of the major axis, pixels439 * minor - unt32_t, length of the minor axis, pixels440 *441 * Multi-touch orientation event - touch point's shape has changed442 * its orientation: calculated as a clockwise angle between the major axis443 * of the ellipse and positive Y axis in degrees, [-180; +180].444 * 0 1 2 3 octet445 * +----------------+----------------+----------------+----------------+446 * | _TYPE_MTOUCH | _MT_EV_ORIENT | contact_id | reserved | 4447 * +----------------+----------------+----------------+----------------+448 * | reserved | 8449 * +----------------+----------------+----------------+----------------+450 * | orientation | reserved | 12451 * +----------------+----------------+----------------+----------------+452 * | reserved | 16453 * +----------------+----------------+----------------+----------------+454 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|455 * +----------------+----------------+----------------+----------------+456 * | reserved | 40457 * +----------------+----------------+----------------+----------------+458 *459 * orientation - int16_t, clockwise angle of the major axis460 */461 462struct xenkbd_mtouch {463 uint8_t type; /* XENKBD_TYPE_MTOUCH */464 uint8_t event_type; /* XENKBD_MT_EV_??? */465 uint8_t contact_id;466 uint8_t reserved[5]; /* reserved for the future use */467 union {468 struct {469 int32_t abs_x; /* absolute X position, pixels */470 int32_t abs_y; /* absolute Y position, pixels */471 } pos;472 struct {473 uint32_t major; /* length of the major axis, pixels */474 uint32_t minor; /* length of the minor axis, pixels */475 } shape;476 int16_t orientation; /* clockwise angle of the major axis */477 } u;478};479 480#define XENKBD_IN_EVENT_SIZE 40481 482union xenkbd_in_event {483 uint8_t type;484 struct xenkbd_motion motion;485 struct xenkbd_key key;486 struct xenkbd_position pos;487 struct xenkbd_mtouch mtouch;488 char pad[XENKBD_IN_EVENT_SIZE];489};490 491/*492 *****************************************************************************493 * Frontend to backend events494 *****************************************************************************495 *496 * Out events may be sent only when requested by backend, and receipt497 * of an unknown out event is an error.498 * No out events currently defined.499 500 * All event packets have the same length (40 octets)501 * All event packets have common header:502 * 0 octet503 * +-----------------+504 * | type |505 * +-----------------+506 * type - uint8_t, event code507 */508 509#define XENKBD_OUT_EVENT_SIZE 40510 511union xenkbd_out_event {512 uint8_t type;513 char pad[XENKBD_OUT_EVENT_SIZE];514};515 516/*517 *****************************************************************************518 * Shared page519 *****************************************************************************520 */521 522#define XENKBD_IN_RING_SIZE 2048523#define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE)524#define XENKBD_IN_RING_OFFS 1024525#define XENKBD_IN_RING(page) \526 ((union xenkbd_in_event *)((char *)(page) + XENKBD_IN_RING_OFFS))527#define XENKBD_IN_RING_REF(page, idx) \528 (XENKBD_IN_RING((page))[(idx) % XENKBD_IN_RING_LEN])529 530#define XENKBD_OUT_RING_SIZE 1024531#define XENKBD_OUT_RING_LEN (XENKBD_OUT_RING_SIZE / XENKBD_OUT_EVENT_SIZE)532#define XENKBD_OUT_RING_OFFS (XENKBD_IN_RING_OFFS + XENKBD_IN_RING_SIZE)533#define XENKBD_OUT_RING(page) \534 ((union xenkbd_out_event *)((char *)(page) + XENKBD_OUT_RING_OFFS))535#define XENKBD_OUT_RING_REF(page, idx) \536 (XENKBD_OUT_RING((page))[(idx) % XENKBD_OUT_RING_LEN])537 538struct xenkbd_page {539 uint32_t in_cons, in_prod;540 uint32_t out_cons, out_prod;541};542 543#endif /* __XEN_PUBLIC_IO_KBDIF_H__ */544