include/xen/interface/io/kbdif.h

   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__ */