include/hw/xen/interface/io/kbdif.h

   1 /* SPDX-License-Identifier: MIT */
   2 /*
   3  * kbdif.h -- Xen virtual keyboard/mouse
   4  *
   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 Negotiation
  15  *****************************************************************************
  16  *
  17  * The two halves of a para-virtual driver utilize nodes within
  18  * XenStore to communicate capabilities and to negotiate operating parameters.
  19  * This section enumerates these nodes which reside in the respective front and
  20  * backend portions of XenStore, following XenBus convention.
  21  *
  22  * All data in XenStore is stored as strings.  Nodes specifying numeric
  23  * values are encoded in decimal. Integer value ranges listed below are
  24  * expressed as fixed sized integer types capable of storing the conversion
  25  * of a properly formated node string, without loss of information.
  26  *
  27  *****************************************************************************
  28  *                            Backend XenBus Nodes
  29  *****************************************************************************
  30  *
  31  *---------------------------- Features supported ----------------------------
  32  *
  33  * Capable backend advertises supported features by publishing
  34  * 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-keyboard
  38  *      Values:         <uint>
  39  *
  40  *      If there is no need to expose a virtual keyboard device by the
  41  *      frontend then this must be set to 1.
  42  *
  43  * feature-disable-pointer
  44  *      Values:         <uint>
  45  *
  46  *      If there is no need to expose a virtual pointer device by the
  47  *      frontend then this must be set to 1.
  48  *
  49  * feature-abs-pointer
  50  *      Values:         <uint>
  51  *
  52  *      Backends, which support reporting of absolute coordinates for pointer
  53  *      device should set this to 1.
  54  *
  55  * feature-multi-touch
  56  *      Values:         <uint>
  57  *
  58  *      Backends, which support reporting of multi-touch events
  59  *      should set this to 1.
  60  *
  61  * feature-raw-pointer
  62  *      Values:        <uint>
  63  *
  64  *      Backends, which support reporting raw (unscaled) absolute coordinates
  65  *      for pointer devices should set this to 1. Raw (unscaled) values have
  66  *      a range of [0, 0x7fff].
  67  *
  68  *-----------------------  Device Instance Parameters ------------------------
  69  *
  70  * unique-id
  71  *      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 backend
  75  *      by this ID. This can be UUID or such.
  76  *
  77  *------------------------- Pointer Device Parameters ------------------------
  78  *
  79  * width
  80  *      Values:         <uint>
  81  *
  82  *      Maximum X coordinate (width) to be used by the frontend
  83  *      while reporting input events, pixels, [0; UINT32_MAX].
  84  *
  85  * height
  86  *      Values:         <uint>
  87  *
  88  *      Maximum Y coordinate (height) to be used by the frontend
  89  *      while reporting input events, pixels, [0; UINT32_MAX].
  90  *
  91  *----------------------- Multi-touch Device Parameters ----------------------
  92  *
  93  * multi-touch-num-contacts
  94  *      Values:         <uint>
  95  *
  96  *      Number of simultaneous touches reported.
  97  *
  98  * multi-touch-width
  99  *      Values:         <uint>
 100  *
 101  *      Width of the touch area to be used by the frontend
 102  *      while reporting input events, pixels, [0; UINT32_MAX].
 103  *
 104  * multi-touch-height
 105  *      Values:         <uint>
 106  *
 107  *      Height of the touch area to be used by the frontend
 108  *      while reporting input events, pixels, [0; UINT32_MAX].
 109  *
 110  *****************************************************************************
 111  *                            Frontend XenBus Nodes
 112  *****************************************************************************
 113  *
 114  *------------------------------ Feature request -----------------------------
 115  *
 116  * Capable frontend requests features from backend via setting corresponding
 117  * entries to 1 in XenStore. Requests for features not advertised as supported
 118  * by the backend have no effect.
 119  *
 120  * request-abs-pointer
 121  *      Values:         <uint>
 122  *
 123  *      Request backend to report absolute pointer coordinates
 124  *      (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).
 125  *
 126  * request-multi-touch
 127  *      Values:         <uint>
 128  *
 129  *      Request backend to report multi-touch events.
 130  *
 131  * request-raw-pointer
 132  *      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-channel
 141  *      Values:         <uint>
 142  *
 143  *      The identifier of the Xen event channel used to signal activity
 144  *      in the ring buffer.
 145  *
 146  * page-gref
 147  *      Values:         <uint>
 148  *
 149  *      The Xen grant reference granting permission for the backend to map
 150  *      a sole page in a single page sized event ring buffer.
 151  *
 152  * page-ref
 153  *      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             1
 164 #define XENKBD_TYPE_RESERVED           2
 165 #define XENKBD_TYPE_KEY                3
 166 #define XENKBD_TYPE_POS                4
 167 #define XENKBD_TYPE_MTOUCH             5
 168
 169 /* Multi-touch event sub-codes */
 170
 171 #define XENKBD_MT_EV_DOWN              0
 172 #define XENKBD_MT_EV_UP                1
 173 #define XENKBD_MT_EV_MOTION            2
 174 #define XENKBD_MT_EV_SYN               3
 175 #define XENKBD_MT_EV_SHAPE             4
 176 #define XENKBD_MT_EV_ORIENT            5
 177
 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 with
 210  * 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 events
 217  *****************************************************************************
 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         octet
 224  * +-----------------+
 225  * |       type      |
 226  * +-----------------+
 227  * type - uint8_t, event code, XENKBD_TYPE_???
 228  *
 229  *
 230  * Pointer relative movement event
 231  *         0                1                 2               3        octet
 232  * +----------------+----------------+----------------+----------------+
 233  * |  _TYPE_MOTION  |                     reserved                     | 4
 234  * +----------------+----------------+----------------+----------------+
 235  * |                               rel_x                               | 8
 236  * +----------------+----------------+----------------+----------------+
 237  * |                               rel_y                               | 12
 238  * +----------------+----------------+----------------+----------------+
 239  * |                               rel_z                               | 16
 240  * +----------------+----------------+----------------+----------------+
 241  * |                             reserved                              | 20
 242  * +----------------+----------------+----------------+----------------+
 243  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 244  * +----------------+----------------+----------------+----------------+
 245  * |                             reserved                              | 40
 246  * +----------------+----------------+----------------+----------------+
 247  *
 248  * rel_x - int32_t, relative X motion
 249  * rel_y - int32_t, relative Y motion
 250  * rel_z - int32_t, relative Z motion (wheel)
 251  */
 252
 253 struct xenkbd_motion
 254 {
 255     uint8_t type;
 256     int32_t rel_x;
 257     int32_t rel_y;
 258     int32_t rel_z;
 259 };
 260
 261 /*
 262  * Key event (includes pointer buttons)
 263  *         0                1                 2               3        octet
 264  * +----------------+----------------+----------------+----------------+
 265  * |  _TYPE_KEY     |     pressed    |            reserved             | 4
 266  * +----------------+----------------+----------------+----------------+
 267  * |                              keycode                              | 8
 268  * +----------------+----------------+----------------+----------------+
 269  * |                             reserved                              | 12
 270  * +----------------+----------------+----------------+----------------+
 271  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 272  * +----------------+----------------+----------------+----------------+
 273  * |                             reserved                              | 40
 274  * +----------------+----------------+----------------+----------------+
 275  *
 276  * pressed - uint8_t, 1 if pressed; 0 otherwise
 277  * keycode - uint32_t, KEY_* from linux/input.h
 278  */
 279
 280 struct xenkbd_key
 281 {
 282     uint8_t type;
 283     uint8_t pressed;
 284     uint32_t keycode;
 285 };
 286
 287 /*
 288  * Pointer absolute position event
 289  *         0                1                 2               3        octet
 290  * +----------------+----------------+----------------+----------------+
 291  * |  _TYPE_POS     |                     reserved                     | 4
 292  * +----------------+----------------+----------------+----------------+
 293  * |                               abs_x                               | 8
 294  * +----------------+----------------+----------------+----------------+
 295  * |                               abs_y                               | 12
 296  * +----------------+----------------+----------------+----------------+
 297  * |                               rel_z                               | 16
 298  * +----------------+----------------+----------------+----------------+
 299  * |                             reserved                              | 20
 300  * +----------------+----------------+----------------+----------------+
 301  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 302  * +----------------+----------------+----------------+----------------+
 303  * |                             reserved                              | 40
 304  * +----------------+----------------+----------------+----------------+
 305  *
 306  * abs_x - int32_t, absolute X position (in FB pixels)
 307  * abs_y - int32_t, absolute Y position (in FB pixels)
 308  * rel_z - int32_t, relative Z motion (wheel)
 309  */
 310
 311 struct xenkbd_position
 312 {
 313     uint8_t type;
 314     int32_t abs_x;
 315     int32_t abs_y;
 316     int32_t rel_z;
 317 };
 318
 319 /*
 320  * Multi-touch event and its sub-types
 321  *
 322  * All multi-touch event packets have common header:
 323  *
 324  *         0                1                 2               3        octet
 325  * +----------------+----------------+----------------+----------------+
 326  * |  _TYPE_MTOUCH  |   event_type   |   contact_id   |    reserved    | 4
 327  * +----------------+----------------+----------------+----------------+
 328  * |                             reserved                              | 8
 329  * +----------------+----------------+----------------+----------------+
 330  *
 331  * event_type - unt8_t, multi-touch event sub-type, XENKBD_MT_EV_???
 332  * contact_id - unt8_t, ID of the contact
 333  *
 334  * Touch interactions can consist of one or more contacts.
 335  * For each contact, a series of events is generated, starting
 336  * with a down event, followed by zero or more motion events,
 337  * and ending with an up event. Events relating to the same
 338  * contact point can be identified by the ID of the sequence: contact ID.
 339  * Contact ID may be reused after XENKBD_MT_EV_UP event and
 340  * is in the [0; XENKBD_FIELD_NUM_CONTACTS - 1] range.
 341  *
 342  * For further information please refer to documentation on Wayland [1],
 343  * Linux [2] and Windows [3] multi-touch support.
 344  *
 345  * [1] https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml
 346  * [2] https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt
 347  * [3] https://msdn.microsoft.com/en-us/library/jj151564(v=vs.85).aspx
 348  *
 349  *
 350  * Multi-touch down event - sent when a new touch is made: touch is assigned
 351  * a unique contact ID, sent with this and consequent events related
 352  * to this touch.
 353  *         0                1                 2               3        octet
 354  * +----------------+----------------+----------------+----------------+
 355  * |  _TYPE_MTOUCH  |   _MT_EV_DOWN  |   contact_id   |    reserved    | 4
 356  * +----------------+----------------+----------------+----------------+
 357  * |                             reserved                              | 8
 358  * +----------------+----------------+----------------+----------------+
 359  * |                               abs_x                               | 12
 360  * +----------------+----------------+----------------+----------------+
 361  * |                               abs_y                               | 16
 362  * +----------------+----------------+----------------+----------------+
 363  * |                             reserved                              | 20
 364  * +----------------+----------------+----------------+----------------+
 365  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 366  * +----------------+----------------+----------------+----------------+
 367  * |                             reserved                              | 40
 368  * +----------------+----------------+----------------+----------------+
 369  *
 370  * abs_x - int32_t, absolute X position, in pixels
 371  * abs_y - int32_t, absolute Y position, in pixels
 372  *
 373  * Multi-touch contact release event
 374  *         0                1                 2               3        octet
 375  * +----------------+----------------+----------------+----------------+
 376  * |  _TYPE_MTOUCH  |  _MT_EV_UP     |   contact_id   |    reserved    | 4
 377  * +----------------+----------------+----------------+----------------+
 378  * |                             reserved                              | 8
 379  * +----------------+----------------+----------------+----------------+
 380  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 381  * +----------------+----------------+----------------+----------------+
 382  * |                             reserved                              | 40
 383  * +----------------+----------------+----------------+----------------+
 384  *
 385  * Multi-touch motion event
 386  *         0                1                 2               3        octet
 387  * +----------------+----------------+----------------+----------------+
 388  * |  _TYPE_MTOUCH  |  _MT_EV_MOTION |   contact_id   |    reserved    | 4
 389  * +----------------+----------------+----------------+----------------+
 390  * |                             reserved                              | 8
 391  * +----------------+----------------+----------------+----------------+
 392  * |                               abs_x                               | 12
 393  * +----------------+----------------+----------------+----------------+
 394  * |                               abs_y                               | 16
 395  * +----------------+----------------+----------------+----------------+
 396  * |                             reserved                              | 20
 397  * +----------------+----------------+----------------+----------------+
 398  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 399  * +----------------+----------------+----------------+----------------+
 400  * |                             reserved                              | 40
 401  * +----------------+----------------+----------------+----------------+
 402  *
 403  * abs_x - int32_t, absolute X position, in pixels,
 404  * abs_y - int32_t, absolute Y position, in pixels,
 405  *
 406  * Multi-touch input synchronization event - shows end of a set of events
 407  * which logically belong together.
 408  *         0                1                 2               3        octet
 409  * +----------------+----------------+----------------+----------------+
 410  * |  _TYPE_MTOUCH  |  _MT_EV_SYN    |   contact_id   |    reserved    | 4
 411  * +----------------+----------------+----------------+----------------+
 412  * |                             reserved                              | 8
 413  * +----------------+----------------+----------------+----------------+
 414  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 415  * +----------------+----------------+----------------+----------------+
 416  * |                             reserved                              | 40
 417  * +----------------+----------------+----------------+----------------+
 418  *
 419  * Multi-touch shape event - touch point's shape has changed its shape.
 420  * Shape is approximated by an ellipse through the major and minor axis
 421  * lengths: major is the longer diameter of the ellipse and minor is the
 422  * shorter one. Center of the ellipse is reported via
 423  * XENKBD_MT_EV_DOWN/XENKBD_MT_EV_MOTION events.
 424  *         0                1                 2               3        octet
 425  * +----------------+----------------+----------------+----------------+
 426  * |  _TYPE_MTOUCH  |  _MT_EV_SHAPE  |   contact_id   |    reserved    | 4
 427  * +----------------+----------------+----------------+----------------+
 428  * |                             reserved                              | 8
 429  * +----------------+----------------+----------------+----------------+
 430  * |                               major                               | 12
 431  * +----------------+----------------+----------------+----------------+
 432  * |                               minor                               | 16
 433  * +----------------+----------------+----------------+----------------+
 434  * |                             reserved                              | 20
 435  * +----------------+----------------+----------------+----------------+
 436  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 437  * +----------------+----------------+----------------+----------------+
 438  * |                             reserved                              | 40
 439  * +----------------+----------------+----------------+----------------+
 440  *
 441  * major - unt32_t, length of the major axis, pixels
 442  * minor - unt32_t, length of the minor axis, pixels
 443  *
 444  * Multi-touch orientation event - touch point's shape has changed
 445  * its orientation: calculated as a clockwise angle between the major axis
 446  * of the ellipse and positive Y axis in degrees, [-180; +180].
 447  *         0                1                 2               3        octet
 448  * +----------------+----------------+----------------+----------------+
 449  * |  _TYPE_MTOUCH  |  _MT_EV_ORIENT |   contact_id   |    reserved    | 4
 450  * +----------------+----------------+----------------+----------------+
 451  * |                             reserved                              | 8
 452  * +----------------+----------------+----------------+----------------+
 453  * |           orientation           |            reserved             | 12
 454  * +----------------+----------------+----------------+----------------+
 455  * |                             reserved                              | 16
 456  * +----------------+----------------+----------------+----------------+
 457  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
 458  * +----------------+----------------+----------------+----------------+
 459  * |                             reserved                              | 40
 460  * +----------------+----------------+----------------+----------------+
 461  *
 462  * orientation - int16_t, clockwise angle of the major axis
 463  */
 464
 465 struct xenkbd_mtouch {
 466     uint8_t type;            /* XENKBD_TYPE_MTOUCH */
 467     uint8_t event_type;      /* XENKBD_MT_EV_??? */
 468     uint8_t contact_id;
 469     uint8_t reserved[5];     /* reserved for the future use */
 470     union {
 471         struct {
 472             int32_t abs_x;   /* absolute X position, pixels */
 473             int32_t abs_y;   /* absolute Y position, pixels */
 474         } pos;
 475         struct {
 476             uint32_t major;  /* length of the major axis, pixels */
 477             uint32_t minor;  /* length of the minor axis, pixels */
 478         } shape;
 479         int16_t orientation; /* clockwise angle of the major axis */
 480     } u;
 481 };
 482
 483 #define XENKBD_IN_EVENT_SIZE 40
 484
 485 union xenkbd_in_event
 486 {
 487     uint8_t type;
 488     struct xenkbd_motion motion;
 489     struct xenkbd_key key;
 490     struct xenkbd_position pos;
 491     struct xenkbd_mtouch mtouch;
 492     char pad[XENKBD_IN_EVENT_SIZE];
 493 };
 494
 495 /*
 496  *****************************************************************************
 497  *                            Frontend to backend events
 498  *****************************************************************************
 499  *
 500  * Out events may be sent only when requested by backend, and receipt
 501  * of an unknown out event is an error.
 502  * No out events currently defined.
 503
 504  * All event packets have the same length (40 octets)
 505  * All event packets have common header:
 506  *          0         octet
 507  * +-----------------+
 508  * |       type      |
 509  * +-----------------+
 510  * type - uint8_t, event code
 511  */
 512
 513 #define XENKBD_OUT_EVENT_SIZE 40
 514
 515 union xenkbd_out_event
 516 {
 517     uint8_t type;
 518     char pad[XENKBD_OUT_EVENT_SIZE];
 519 };
 520
 521 /*
 522  *****************************************************************************
 523  *                            Shared page
 524  *****************************************************************************
 525  */
 526
 527 #define XENKBD_IN_RING_SIZE 2048
 528 #define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE)
 529 #define XENKBD_IN_RING_OFFS 1024
 530 #define XENKBD_IN_RING(page) \
 531     ((union xenkbd_in_event *)((char *)(page) + XENKBD_IN_RING_OFFS))
 532 #define XENKBD_IN_RING_REF(page, idx) \
 533     (XENKBD_IN_RING((page))[(idx) % XENKBD_IN_RING_LEN])
 534
 535 #define XENKBD_OUT_RING_SIZE 1024
 536 #define XENKBD_OUT_RING_LEN (XENKBD_OUT_RING_SIZE / XENKBD_OUT_EVENT_SIZE)
 537 #define XENKBD_OUT_RING_OFFS (XENKBD_IN_RING_OFFS + XENKBD_IN_RING_SIZE)
 538 #define XENKBD_OUT_RING(page) \
 539     ((union xenkbd_out_event *)((char *)(page) + XENKBD_OUT_RING_OFFS))
 540 #define XENKBD_OUT_RING_REF(page, idx) \
 541     (XENKBD_OUT_RING((page))[(idx) % XENKBD_OUT_RING_LEN])
 542
 543 struct xenkbd_page
 544 {
 545     uint32_t in_cons, in_prod;
 546     uint32_t out_cons, out_prod;
 547 };
 548
 549 #endif /* __XEN_PUBLIC_IO_KBDIF_H__ */
 550
 551 /*
 552  * Local variables:
 553  * mode: C
 554  * c-file-style: "BSD"
 555  * c-basic-offset: 4
 556  * tab-width: 4
 557  * indent-tabs-mode: nil
 558  * End:
 559  */