xen/kbdif: add multi-touch support

From: Oleksandr Andrushchenko <[email protected]>

Signed-off-by Oleksandr Andrushchenko <[email protected]>

---
 xen/include/public/io/kbdif.h | 249 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 222 insertions(+), 27 deletions(-)

xen/include/public/io/kbdif.h +0 -0

index 2d2aebd..0e19a40 100644

xen/include/public/io/kbdif.h +8 -0

+ * XenStore to communicate capabilities and to negotiate operating parameters.
+ * This section enumerates these nodes which reside in the respective front and
+ * backend portions of the XenStore, following the XenBus convention.
+ *
+ * All data in the XenStore is stored as strings.  Nodes specifying numeric
+ * values are encoded in decimal. Integer value ranges listed below are
+ * expressed as fixed sized integer types capable of storing the conversion
+ * of a properly formated node string, without loss of information.

xen/include/public/io/kbdif.h +47 -0

+ *
+ * feature-abs-pointer
+ *      Values:         <uint>
+ *
+ *      Backends, which support reporting of absolute coordinates for pointer
+ *      device should set this to 1.
+ *
+ *------------------------- Pointer Device Parameters ------------------------
+ *
+ * width
+ *      Values:         <uint>
+ *
+ *      Maximum X coordinate (width) to be used by the frontend
+ *      while reporting input events, pixels, [0; UINT32_MAX].
+ *
+ * height
+ *      Values:         <uint>
+ *
+ *      Maximum Y coordinate (height) to be used by the frontend
+ *      while reporting input events, pixels, [0; UINT32_MAX].
+ *
+ *****************************************************************************
+ *                            Frontend XenBus Nodes
+ *****************************************************************************
+ *
+ *------------------------------ Feature request -----------------------------
+ *
+ * Capable frontend requests features from backend via setting corresponding
+ * entries to 1 in XenStore. Requests for features not advertised as supported
+ * by the backend have no effect.
+ *
+ * request-abs-pointer
+ *      Values:         <uint>
+ *
+ *      Request from backend to report absolute pointer coordinates
+ *      (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).
+ *
+ *----------------------- Request Transport Parameters -----------------------
+ *
+ * event-channel
+ *      Values:         <uint>
+ *
+ *      The identifier of the Xen event channel used to signal activity
+ *      in the ring buffer.
+ *
+ * page-gref
+ *      Values:         <uint>

xen/include/public/io/kbdif.h +20 -10

+ */
 
 /*
- * Frontends should ignore unknown in events.
+ * EVENT CODES.
  */
 
-/* Pointer movement event */
-#define XENKBD_TYPE_MOTION  1
-/* Event type 2 currently not used */
-/* Key event (includes pointer buttons) */
-#define XENKBD_TYPE_KEY     3
+#define XENKBD_TYPE_MOTION             1
+#define XENKBD_TYPE_RESERVED           2
+#define XENKBD_TYPE_KEY                3
+#define XENKBD_TYPE_POS                4
+
 /*
- * Pointer position event
- * Capable backend sets feature-abs-pointer in xenstore.
- * Frontend requests ot instead of XENKBD_TYPE_MOTION by setting
- * request-abs-update in xenstore.
+ * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS.
+ */
+
+#define XENKBD_DRIVER_NAME             "vkbd"
+
+#define XENKBD_FIELD_FEAT_ABS_POINTER  "feature-abs-pointer"
+#define XENKBD_FIELD_REQ_ABS_POINTER   "request-abs-pointer"
+#define XENKBD_FIELD_RING_GREF         "page-gref"
+#define XENKBD_FIELD_EVT_CHANNEL       "event-channel"
+#define XENKBD_FIELD_WIDTH             "width"
+#define XENKBD_FIELD_HEIGHT            "height"
+
+/* OBSOLETE, not recommended for use */

xen/include/public/io/kbdif.h +22 -0

+ * All reserved fields in the structures below must be 0.
+ *
+ *****************************************************************************
+ *                           Backend to frontend events
+ *****************************************************************************
+ *
+ * Frontends should ignore unknown in events.
+ * All event packets have the same length (40 octets)
+ * All event packets have common header:
+ *
+ *          0         octet
+ * +-----------------+
+ * |       type      |
+ * +-----------------+
+ * type - uint8_t, event code, XENKBD_TYPE_???
+ *
+ *
+ * Pointer relative movement event
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |   _TYPE_MOTION  |                       reserved                      |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h +12 -5

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * rel_x - int32_t, relative X motion
+ * rel_y - int32_t, relative Y motion
+ * rel_z - int32_t, relative Z motion (wheel)
  */
-#define XENKBD_TYPE_POS     4
 
 struct xenkbd_motion
 {
-    uint8_t type;        /* XENKBD_TYPE_MOTION */
-    int32_t rel_x;       /* relative X motion */
-    int32_t rel_y;       /* relative Y motion */
-    int32_t rel_z;       /* relative Z motion (wheel) */
+    uint8_t type;
+    int32_t rel_x;
+    int32_t rel_y;
+    int32_t rel_z;
 };
 
+/*
+ * Key event (includes pointer buttons)

xen/include/public/io/kbdif.h +16 -3

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * pressed - uint8_t, 1 if pressed; 0 otherwise
+ * keycode - uint32_t, KEY_* from linux/input.h
+ */
+
 struct xenkbd_key
 {
-    uint8_t type;         /* XENKBD_TYPE_KEY */
-    uint8_t pressed;      /* 1 if pressed; 0 otherwise */
-    uint32_t keycode;     /* KEY_* from linux/input.h */
+    uint8_t type;
+    uint8_t pressed;
+    uint32_t keycode;
 };
 
+/*
+ * Pointer absolute position event
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |   _TYPE_POS     |                      reserved                       |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h +30 -8

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * abs_x - int32_t, absolute X position (in FB pixels)
+ * abs_y - int32_t, absolute Y position (in FB pixels)
+ * rel_z - int32_t, relative Z motion (wheel)
+ */
+
 struct xenkbd_position
 {
-    uint8_t type;        /* XENKBD_TYPE_POS */
-    int32_t abs_x;       /* absolute X position (in FB pixels) */
-    int32_t abs_y;       /* absolute Y position (in FB pixels) */
-    int32_t rel_z;       /* relative Z motion (wheel) */
+    uint8_t type;
+    int32_t abs_x;
+    int32_t abs_y;
+    int32_t rel_z;
 };
 
 #define XENKBD_IN_EVENT_SIZE 40

@@ -79,12 +260,22 @@ union xenkbd_in_event
     char pad[XENKBD_IN_EVENT_SIZE];
 };
 
-/* Out events (frontend -> backend) */
-
 /*
+ *****************************************************************************
+ *                            Frontend to backend events
+ *****************************************************************************
+ *
  * Out events may be sent only when requested by backend, and receipt
  * of an unknown out event is an error.
  * No out events currently defined.
+
+ * All event packets have the same length (40 octets)
+ * All event packets have common header:
+ *          0         octet
+ * +-----------------+
+ * |       type      |
+ * +-----------------+
+ * type - uint8_t, event code
  */
 
 #define XENKBD_OUT_EVENT_SIZE 40

@@ -95,7 +286,11 @@ union xenkbd_out_event
     char pad[XENKBD_OUT_EVENT_SIZE];
 };
 
-/* shared page */
+/*
+ *****************************************************************************
+ *                            Shared page
+ *****************************************************************************
+ */
 
 #define XENKBD_IN_RING_SIZE 2048
 #define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE)

@@ -119,7 +314,7 @@ struct xenkbd_page
     uint32_t out_cons, out_prod;
 };
 
-#endif
+#endif /* __XEN_PUBLIC_IO_KBDIF_H__ */
 
 /*
  * Local variables:

Signature · 1 line

2.7.4

Quoted 15 lines · Oleksandr Andrushchenko

From: Oleksandr Andrushchenko <[email protected]>

Signed-off-by Oleksandr Andrushchenko <[email protected]>

---
  xen/include/public/io/kbdif.h | 249 +++++++++++++++++++++++++++++++++++++-----
  1 file changed, 222 insertions(+), 27 deletions(-)

xen/include/public/io/kbdif.h +0 -0

index 2d2aebd..0e19a40 100644
@@ -26,46 +26,227 @@
  #ifndef __XEN_PUBLIC_IO_KBDIF_H__
  #define __XEN_PUBLIC_IO_KBDIF_H__
 

xen/include/public/io/kbdif.h line 34

Quoted 7 lines

xen/include/public/io/kbdif.h +6 -1

-/* In events (backend -> frontend) */
+/*
+ *****************************************************************************
+ *                     Feature and Parameter Negotiation
+ *****************************************************************************
+ *
+ * The two halves of a para-virtual driver utilize nodes within the

It's just "XenStore", not "the XenStore", all across the doc.

Quoted 10 lines

xen/include/public/io/kbdif.h +8 -0

+ * XenStore to communicate capabilities and to negotiate operating parameters.
+ * This section enumerates these nodes which reside in the respective front and
+ * backend portions of the XenStore, following the XenBus convention.
+ *
+ * All data in the XenStore is stored as strings.  Nodes specifying numeric
+ * values are encoded in decimal. Integer value ranges listed below are
+ * expressed as fixed sized integer types capable of storing the conversion
+ * of a properly formated node string, without loss of information.

xen/include/public/io/kbdif.h line 52

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ *
+ *****************************************************************************
+ *                            Backend XenBus Nodes
+ *****************************************************************************
+ *
+ *---------------------------- Features supported ----------------------------
+ *
+ * Capable backend advertises supported features by publishing
+ * corresponding entries in XenStore and puts 1 as the value of the entry.
+ * If feature is not supported then 0 must be set or feature entry omitted.

^ a feature

Quoted 47 lines

xen/include/public/io/kbdif.h +47 -0

+ *
+ * feature-abs-pointer
+ *      Values:         <uint>
+ *
+ *      Backends, which support reporting of absolute coordinates for pointer
+ *      device should set this to 1.
+ *
+ *------------------------- Pointer Device Parameters ------------------------
+ *
+ * width
+ *      Values:         <uint>
+ *
+ *      Maximum X coordinate (width) to be used by the frontend
+ *      while reporting input events, pixels, [0; UINT32_MAX].
+ *
+ * height
+ *      Values:         <uint>
+ *
+ *      Maximum Y coordinate (height) to be used by the frontend
+ *      while reporting input events, pixels, [0; UINT32_MAX].
+ *
+ *****************************************************************************
+ *                            Frontend XenBus Nodes
+ *****************************************************************************
+ *
+ *------------------------------ Feature request -----------------------------
+ *
+ * Capable frontend requests features from backend via setting corresponding
+ * entries to 1 in XenStore. Requests for features not advertised as supported
+ * by the backend have no effect.
+ *
+ * request-abs-pointer
+ *      Values:         <uint>
+ *
+ *      Request from backend to report absolute pointer coordinates
+ *      (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).
+ *
+ *----------------------- Request Transport Parameters -----------------------
+ *
+ * event-channel
+ *      Values:         <uint>
+ *
+ *      The identifier of the Xen event channel used to signal activity
+ *      in the ring buffer.
+ *
+ * page-gref
+ *      Values:         <uint>

xen/include/public/io/kbdif.h line 109

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ *
+ *      The Xen grant reference granting permission for the backend to map
+ *      a sole page in a single page sized event ring buffer.
+ *
+ * page-ref
+ *      Values:         <uint>
+ *
+ *      OBSOLETE, not recommended for use.
+ *      A unique (within the guest domain given) value identifying event
+ *      channel and page reference pair.

Actually page-ref is just the pfn of the page, it doesn't have any event channel info.

Quoted 39 lines

xen/include/public/io/kbdif.h +23 -10

+ */
 
  /*
- * Frontends should ignore unknown in events.
+ * EVENT CODES.
   */
 
-/* Pointer movement event */
-#define XENKBD_TYPE_MOTION  1
-/* Event type 2 currently not used */
-/* Key event (includes pointer buttons) */
-#define XENKBD_TYPE_KEY     3
+#define XENKBD_TYPE_MOTION             1
+#define XENKBD_TYPE_RESERVED           2
+#define XENKBD_TYPE_KEY                3
+#define XENKBD_TYPE_POS                4
+
  /*
- * Pointer position event
- * Capable backend sets feature-abs-pointer in xenstore.
- * Frontend requests ot instead of XENKBD_TYPE_MOTION by setting
- * request-abs-update in xenstore.
+ * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS.
+ */
+
+#define XENKBD_DRIVER_NAME             "vkbd"
+
+#define XENKBD_FIELD_FEAT_ABS_POINTER  "feature-abs-pointer"
+#define XENKBD_FIELD_REQ_ABS_POINTER   "request-abs-pointer"
+#define XENKBD_FIELD_RING_GREF         "page-gref"
+#define XENKBD_FIELD_EVT_CHANNEL       "event-channel"
+#define XENKBD_FIELD_WIDTH             "width"
+#define XENKBD_FIELD_HEIGHT            "height"
+
+/* OBSOLETE, not recommended for use */
+#define XENKBD_FIELD_RING_REF          "page-ref"
+
+/*

xen/include/public/io/kbdif.h line 144

Quoted 7 lines

xen/include/public/io/kbdif.h +7 -0

+ *****************************************************************************
+ * Description of the protocol between frontend and backend driver.
+ *****************************************************************************
+ *
+ * The two halves of a Para-virtual driver communicate with
+ * each other using a shared page and an event channel.
+ * Shared page contains a ring with event packets.

^ I would call them "event structures"

Quoted 23 lines

xen/include/public/io/kbdif.h +22 -0

+ * All reserved fields in the structures below must be 0.
+ *
+ *****************************************************************************
+ *                           Backend to frontend events
+ *****************************************************************************
+ *
+ * Frontends should ignore unknown in events.
+ * All event packets have the same length (40 octets)
+ * All event packets have common header:
+ *
+ *          0         octet
+ * +-----------------+
+ * |       type      |
+ * +-----------------+
+ * type - uint8_t, event code, XENKBD_TYPE_???
+ *
+ *
+ * Pointer relative movement event
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |   _TYPE_MOTION  |                       reserved                      |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h line 177

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ * |                                 rel_x                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 rel_y                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 rel_z                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

I guess this means that we are skipping some bytes because they are all reserved, right? If so, it would be useful to write the byte count at this point. What's the total size of the event struct?

Quoted 23 lines

xen/include/public/io/kbdif.h +12 -5

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * rel_x - int32_t, relative X motion
+ * rel_y - int32_t, relative Y motion
+ * rel_z - int32_t, relative Z motion (wheel)
   */
-#define XENKBD_TYPE_POS     4
 
  struct xenkbd_motion
  {
-    uint8_t type;        /* XENKBD_TYPE_MOTION */
-    int32_t rel_x;       /* relative X motion */
-    int32_t rel_y;       /* relative Y motion */
-    int32_t rel_z;       /* relative Z motion (wheel) */
+    uint8_t type;
+    int32_t rel_x;
+    int32_t rel_y;
+    int32_t rel_z;
  };
 
+/*
+ * Key event (includes pointer buttons)

xen/include/public/io/kbdif.h line 205

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |   _TYPE_KEY     |      pressed    |              reserved             |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                keycode                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

same here

Quoted 23 lines

xen/include/public/io/kbdif.h +16 -3

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * pressed - uint8_t, 1 if pressed; 0 otherwise
+ * keycode - uint32_t, KEY_* from linux/input.h
+ */
+
  struct xenkbd_key
  {
-    uint8_t type;         /* XENKBD_TYPE_KEY */
-    uint8_t pressed;      /* 1 if pressed; 0 otherwise */
-    uint32_t keycode;     /* KEY_* from linux/input.h */
+    uint8_t type;
+    uint8_t pressed;
+    uint32_t keycode;
  };
 
+/*
+ * Pointer absolute position event
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |   _TYPE_POS     |                      reserved                       |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h line 235

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ * |                                 abs_x                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 abs_y                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 rel_z                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

same here

Quoted 63 lines

xen/include/public/io/kbdif.h +29 -7

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * abs_x - int32_t, absolute X position (in FB pixels)
+ * abs_y - int32_t, absolute Y position (in FB pixels)
+ * rel_z - int32_t, relative Z motion (wheel)
+ */
+
  struct xenkbd_position
  {
-    uint8_t type;        /* XENKBD_TYPE_POS */
-    int32_t abs_x;       /* absolute X position (in FB pixels) */
-    int32_t abs_y;       /* absolute Y position (in FB pixels) */
-    int32_t rel_z;       /* relative Z motion (wheel) */
+    uint8_t type;
+    int32_t abs_x;
+    int32_t abs_y;
+    int32_t rel_z;
  };
 
  #define XENKBD_IN_EVENT_SIZE 40

@@ -79,12 +260,22 @@ union xenkbd_in_event
      char pad[XENKBD_IN_EVENT_SIZE];
  };
 
-/* Out events (frontend -> backend) */
-
  /*
+ *****************************************************************************
+ *                            Frontend to backend events
+ *****************************************************************************
+ *
   * Out events may be sent only when requested by backend, and receipt
   * of an unknown out event is an error.
   * No out events currently defined.
+
+ * All event packets have the same length (40 octets)
+ * All event packets have common header:
+ *          0         octet
+ * +-----------------+
+ * |       type      |
+ * +-----------------+
+ * type - uint8_t, event code
   */
 
  #define XENKBD_OUT_EVENT_SIZE 40

@@ -95,7 +286,11 @@ union xenkbd_out_event
      char pad[XENKBD_OUT_EVENT_SIZE];
  };
 
-/* shared page */
+/*
+ *****************************************************************************
+ *                            Shared page
+ *****************************************************************************
+ */
 
  #define XENKBD_IN_RING_SIZE 2048
  #define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE)

@@ -119,7 +314,7 @@ struct xenkbd_page
      uint32_t out_cons, out_prod;
  };
 

Quoted 8 lines

xen/include/public/io/kbdif.h +1 -1

-#endif
+#endif /* __XEN_PUBLIC_IO_KBDIF_H__ */
 
  /*
   * Local variables:

Signature · 1 line

2.7.4

Quoted 10 lines · Stefano Stabellini

Quoted 9 lines · Oleksandr Andrushchenko

|                               reserved
       |
+ * +-----------------+-----------------+-----------------+----
-------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
/\/\/\/|
+ * +-----------------+-----------------+-----------------+----
-------------+

Quoted 6 lines

I guess this means that we are skipping some bytes because they are all
reserved, right?  If so, it would be useful to write the byte count at this
point. What's the total size of the event struct?

IMO, we shouldn't put any sizes here because:
1. Above we say "All event packets have the same length (40 octets)"
2. All the event structures are part of the union xenkbd_in_event, which has
char pad[XENKBD_IN_EVENT_SIZE];
which effectively regulates the size of the event.

Quoted 17 lines · Oleksandr Andrushchenko

Quoted 10 lines · Stefano Stabellini

Quoted 9 lines · Oleksandr Andrushchenko

| reserved

        |

+ * +-----------------+-----------------+-----------------+----
-------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
/\/\/\/|
+ * +-----------------+-----------------+-----------------+----
-------------+

Quoted 6 lines

I guess this means that we are skipping some bytes because they are all
reserved, right? If so, it would be useful to write the byte count at this
point. What's the total size of the event struct?

Quoted 8 lines

IMO, we shouldn't put any sizes here because:
1. Above we say "All event packets have the same

     length (40 octets)"

2. All the event structures are part of the union xenkbd_in_event, which has
char pad[XENKBD_IN_EVENT_SIZE];
which effectively regulates the size of the event.

In which case, you can use either 40 or XENKBD_IN_EVENT_SIZE (probably the latter).

It's indeed a repetition, but a good one, IMO: it helps the reader, as she won't have to go back to figure out how big the struct was, how the macro was call and to what value it was defined).

Regards,
Dario

Quoted 6 lines · Dario Faggioli

It's indeed a repetition, but a good one, IMO: it helps the reader, as
she won't have to go back to figure out how big the struct was, how the
macro was call and to what value it was defined).

I am still not convinced that we should put it.
Probably we can go the way other RFCs do, like TCP [1], 802.11 [2] etc:
those do not define any reserved fields at the bottom of structures, (which are effectively padding?) but are limited to only those fields which are defined.

Quoted 7 lines · Oleksandr Andrushchenko

Quoted 6 lines · Dario Faggioli

It's indeed a repetition, but a good one, IMO: it helps the reader, as
she won't have to go back to figure out how big the struct was, how the
macro was call and to what value it was defined).

Quoted 7 lines

I am still not convinced that we should put it.
Probably we can go the way other RFCs do, like TCP [1], 802.11 [2] etc:
those do not define any reserved fields at the bottom of structures, (which are effectively padding?) but are limited to only those fields which are defined.

In principle, I like the idea of following the example of those RFCs. However, I'd say that what we should value most is consistency within our own source tree.

But, TBH, there aren't many binary diagram already committed in include/public/io, so it's hard to tell.

FWIW, I still think that providing a clue to the reader about the size --even if already specified somewhere else-- would be beneficial, but it's a rather minor thing, and I certainly can leave with whatever you and the maintainer(s) agree upon.

Regards,
Dario

Quoted 18 lines · Dario Faggioli

Quoted 6 lines · Oleksandr Andrushchenko

Quoted 5 lines · Dario Faggioli

It's indeed a repetition, but a good one, IMO: it helps the reader,
as
she won't have to go back to figure out how big the struct was, how the
macro was call and to what value it was defined).

Quoted 7 lines

I am still not convinced that we should put it.
Probably we can go the way other RFCs do, like TCP [1], 802.11 [2] etc:
those do not define any reserved fields at the bottom of structures, (which are effectively padding?) but are limited to only those fields which are defined.

In principle, I like the idea of following the example of those RFCs. However, I'd say that what we should value most is consistency within our own source tree.

Quoted 7 lines

But, TBH, there aren't many binary diagram already committed in include/public/io, so it's hard to tell.

FWIW, I still think that providing a clue to the reader about the size --even if already specified somewhere else-- would be beneficial, but it's a rather minor thing, and I certainly can leave with whatever you and the maintainer(s) agree upon.

fair enough

Quoted 2 lines

Regards,
Dario

Konrad, could you please define what that ASCII box notation should look like?

Thank you,
Oleksandr

Quoted 29 lines · Oleksandr Andrushchenko

Quoted 18 lines · Dario Faggioli

Quoted 6 lines · Oleksandr Andrushchenko

Quoted 5 lines · Dario Faggioli

It's indeed a repetition, but a good one, IMO: it helps the reader,
as
she won't have to go back to figure out how big the struct was, how the
macro was call and to what value it was defined).

Quoted 7 lines

I am still not convinced that we should put it.
Probably we can go the way other RFCs do, like TCP [1], 802.11 [2] etc:
those do not define any reserved fields at the bottom of structures, (which are effectively padding?) but are limited to only those fields which are defined.

In principle, I like the idea of following the example of those RFCs. However, I'd say that what we should value most is consistency within our own source tree.

Quoted 7 lines

But, TBH, there aren't many binary diagram already committed in include/public/io, so it's hard to tell.

FWIW, I still think that providing a clue to the reader about the size --even if already specified somewhere else-- would be beneficial, but it's a rather minor thing, and I certainly can leave with whatever you and the maintainer(s) agree upon.

fair enough

Quoted 2 lines

Regards,
Dario

Quoted 3 lines

Konrad, could you please define what that ASCII box notation should look like?

Stefano, Konrad
As per my understanding this is the only thing blocking multi-touch and updated kbdif protocol from being upgraded/extended ) Could you please make some decision on this any time soon?

From: Oleksandr Andrushchenko <[email protected]>

Signed-off-by Oleksandr Andrushchenko <[email protected]>

---
 xen/include/public/io/kbdif.h | 228 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 228 insertions(+)

xen/include/public/io/kbdif.h +6 -0

index 0e19a40..1b446f9 100644
@@ -57,6 +57,12 @@
  *      Backends, which support reporting of absolute coordinates for pointer
  *      device should set this to 1.
  *
+ * feature-multi-touch
+ *      Values:         <uint>
+ *
+ *      Backends, which support reporting of multi-touch events
+ *      should set this to 1.
+ *
  *------------------------- Pointer Device Parameters ------------------------
  *
  * width

xen/include/public/io/kbdif.h +8 -0

+ * The values below are per emulated multi-touch input device:
+ *
+ * num-contacts
+ *      Values:         <uint>
+ *
+ *      Number of simultaneous touches reported.
+ *
+ * width

xen/include/public/io/kbdif.h +4 -0

+ *----------------------- Multi-touch Transport Parameters --------------------
+ *
+ * event-channel
+ *      Values:         <uint>

xen/include/public/io/kbdif.h +17 -0

 /*

@@ -117,6 +165,16 @@
 #define XENKBD_TYPE_RESERVED           2
 #define XENKBD_TYPE_KEY                3
 #define XENKBD_TYPE_POS                4
+#define XENKBD_TYPE_MTOUCH             5
+
+/* Multi-touch event sub-codes */
+
+#define XENKBD_MT_EV_DOWN              0
+#define XENKBD_MT_EV_UP                1
+#define XENKBD_MT_EV_MOTION            2
+#define XENKBD_MT_EV_SYN               3
+#define XENKBD_MT_EV_SHAPE             4
+#define XENKBD_MT_EV_ORIENT            5
 
 /*
  * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS.

@@ -125,11 +183,17 @@
 #define XENKBD_DRIVER_NAME             "vkbd"
 
 #define XENKBD_FIELD_FEAT_ABS_POINTER  "feature-abs-pointer"
+#define XENKBD_FIELD_FEAT_MTOUCH       "feature-multi-touch"
 #define XENKBD_FIELD_REQ_ABS_POINTER   "request-abs-pointer"
+#define XENKBD_FIELD_REQ_MTOUCH        "request-multi-touch"
 #define XENKBD_FIELD_RING_GREF         "page-gref"
 #define XENKBD_FIELD_EVT_CHANNEL       "event-channel"
 #define XENKBD_FIELD_WIDTH             "width"
 #define XENKBD_FIELD_HEIGHT            "height"
+#define XENKBD_FIELD_NUM_CONTACTS      "num-contacts"
+
+/* Path entries */
+#define XENKBD_PATH_MTOUCH             "mtouch"
 
 /* OBSOLETE, not recommended for use */
 #define XENKBD_FIELD_RING_REF          "page-ref"

@@ -249,6 +313,170 @@ struct xenkbd_position
     int32_t rel_z;
 };
 
+/*

xen/include/public/io/kbdif.h +26 -0

+ * event_type - unt8_t, multi-touch event sub-type, XENKBD_MT_EV_???
+ * contact_id - unt8_t, ID of the contact
+ *
+ * Touch interactions can consist of one or more contacts.
+ * For each contact, a series of events is generated, starting
+ * with a down event, followed by zero or more motion events,
+ * and ending with an up event. Events relating to the same
+ * contact point can be identified by the ID of the sequence: contact ID.
+ * Contact ID may be reused after XENKBD_MT_EV_UP event and
+ * is in the [0; XENKBD_FIELD_NUM_CONTACTS - 1] range.
+ *
+ * For further information please refer to documentation on Wayland [1],
+ * Linux [2] and Windows [3] multi-touch support.
+ *
+ * [1] https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml
+ * [2] https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt
+ * [3] https://msdn.microsoft.com/en-us/library/jj151564(v=vs.85).aspx
+ *
+ *
+ * Multi-touch down event - sent when a new touch is made: touch is assigned
+ * a unique contact ID, sent with this and consequent events related
+ * to this touch.
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |   _MT_EV_DOWN   |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h +5 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * abs_x - int32_t, absolute X position, in pixels
+ * abs_y - int32_t, absolute Y position, in pixels

xen/include/public/io/kbdif.h +8 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * Multi-touch motion event
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |  _MT_EV_MOTION  |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h +6 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * abs_x - int32_t, absolute X position, in pixels,
+ * abs_y - int32_t, absolute Y position, in pixels,
+ *

xen/include/public/io/kbdif.h +12 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * Multi-touch shape event - touch point's shape has changed its shape.
+ * Shape is approximated by an ellipse through the major and minor axis
+ * lengths: major is the longer diameter of the ellipse and minor is the
+ * shorter one. Center of the ellipse is reported via
+ * XENKBD_MT_EV_DOWN/XENKBD_MT_EV_MOTION events.
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |  _MT_EV_SHAPE   |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h +11 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * major - unt32_t, length of the major axis, pixels
+ * minor - unt32_t, length of the minor axis, pixels
+ *
+ * Multi-touch orientation event - touch point's shape has changed
+ * its orientation: calculated as a clockwise angle between the major axis
+ * of the ellipse and positive Y axis in degrees, [-180; +180].
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h +24 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * orientation - int16_t, clockwise angle of the major axis
+ */
+
+struct xenkbd_mtouch {
+    uint8_t type;             /* XENKBD_TYPE_MTOUCH */
+    uint8_t event_type;       /* XENKBD_MT_EV_??? */
+    uint8_t contact_id;
+    uint8_t reserved[5];      /* reserved for the future use */
+    union {
+        struct {
+            int32_t abs_x;    /* absolute X position, pixels */
+            int32_t abs_y;    /* absolute Y position, pixels */
+        } pos;
+        struct {
+            uint32_t major;   /* length of the major axis, pixels */
+            uint32_t minor;   /* length of the minor axis, pixels */
+        } shape;
+        int16_t orientation;  /* clockwise angle of the major axis */
+    } u;
+};
+
 #define XENKBD_IN_EVENT_SIZE 40
 
 union xenkbd_in_event

Signature · 1 line

2.7.4

Quoted 26 lines · Oleksandr Andrushchenko

From: Oleksandr Andrushchenko <[email protected]>

Signed-off-by Oleksandr Andrushchenko <[email protected]>

---
  xen/include/public/io/kbdif.h | 228 ++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 228 insertions(+)

xen/include/public/io/kbdif.h +6 -0

index 0e19a40..1b446f9 100644
@@ -57,6 +57,12 @@
   *      Backends, which support reporting of absolute coordinates for pointer
   *      device should set this to 1.
   *
+ * feature-multi-touch
+ *      Values:         <uint>
+ *
+ *      Backends, which support reporting of multi-touch events
+ *      should set this to 1.
+ *
   *------------------------- Pointer Device Parameters ------------------------
   *
   * width

@@ -87,6 +93,11 @@
   *      Request from backend to report absolute pointer coordinates

xen/include/public/io/kbdif.h line 99

Quoted 6 lines

xen/include/public/io/kbdif.h +4 -0

   *      (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).
   *
+ * request-multi-touch
+ *      Values:         <uint>
+ *
+ *      Request from backend to report multi-touch events.

I think in English should be "request backend to report multi-touch events". Same above.

xen/include/public/io/kbdif.h line 124

Quoted 13 lines

xen/include/public/io/kbdif.h +5 -0

+ *
   *----------------------- Request Transport Parameters -----------------------
   *
   * event-channel

@@ -107,6 +118,43 @@
   *      OBSOLETE, not recommended for use.
   *      A unique (within the guest domain given) value identifying event
   *      channel and page reference pair.
+ *
+ *----------------------- Multi-touch Device Parameters -----------------------
+ *
+ * Every multi-touch input device uses a dedicated event ring and is

For clarity I would say "Every multi-touch input device uses a dedicated frontend/backend connection". That includes a ring, an event channel, and xenstore entries.

xen/include/public/io/kbdif.h line 125

Quoted 1 line

xen/include/public/io/kbdif.h +1 -0

+ * configured via XenStore properties under XENKBD_PATH_MTOUCH folder.

I don't understand why we need a new xenstore folder. Why do we need XENKBD_PATH_MTOUCH?

Quoted 9 lines

xen/include/public/io/kbdif.h +8 -0

+ * The values below are per emulated multi-touch input device:
+ *
+ * num-contacts
+ *      Values:         <uint>
+ *
+ *      Number of simultaneous touches reported.
+ *
+ * width

xen/include/public/io/kbdif.h line 143

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ *      Values:         <uint>
+ *
+ *      Width of the touch area to be used by the frontend
+ *      while reporting input events, pixels, [0; UINT32_MAX].
+ *
+ * height
+ *      Values:         <uint>
+ *
+ *      Height of the touch area to be used by the frontend
+ *      while reporting input events, pixels, [0; UINT32_MAX].

This is OK.

Quoted 4 lines

xen/include/public/io/kbdif.h +4 -0

+ *----------------------- Multi-touch Transport Parameters --------------------
+ *
+ * event-channel
+ *      Values:         <uint>

xen/include/public/io/kbdif.h line 158

Quoted 10 lines

xen/include/public/io/kbdif.h +9 -0

+ *
+ *      The identifier of the Xen event channel used to signal activity
+ *      in the ring buffer.
+ *
+ * page-gref
+ *      Values:         <uint>
+ *
+ *      The Xen grant reference granting permission for the backend to map
+ *      a sole page in a single page sized event ring buffer.
   */

No need for this. If request-multi-touch, the usual xenkbd ring will be used for multi touch events. We can use the event-channel and page-gref already specified under "Request Transport Parameters".

Quoted 43 lines

xen/include/public/io/kbdif.h +16 -0

  /*

@@ -117,6 +165,16 @@
  #define XENKBD_TYPE_RESERVED           2
  #define XENKBD_TYPE_KEY                3
  #define XENKBD_TYPE_POS                4
+#define XENKBD_TYPE_MTOUCH             5
+
+/* Multi-touch event sub-codes */
+
+#define XENKBD_MT_EV_DOWN              0
+#define XENKBD_MT_EV_UP                1
+#define XENKBD_MT_EV_MOTION            2
+#define XENKBD_MT_EV_SYN               3
+#define XENKBD_MT_EV_SHAPE             4
+#define XENKBD_MT_EV_ORIENT            5
 
  /*
   * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS.

@@ -125,11 +183,17 @@
  #define XENKBD_DRIVER_NAME             "vkbd"
 
  #define XENKBD_FIELD_FEAT_ABS_POINTER  "feature-abs-pointer"
+#define XENKBD_FIELD_FEAT_MTOUCH       "feature-multi-touch"
  #define XENKBD_FIELD_REQ_ABS_POINTER   "request-abs-pointer"
+#define XENKBD_FIELD_REQ_MTOUCH        "request-multi-touch"
  #define XENKBD_FIELD_RING_GREF         "page-gref"
  #define XENKBD_FIELD_EVT_CHANNEL       "event-channel"
  #define XENKBD_FIELD_WIDTH             "width"
  #define XENKBD_FIELD_HEIGHT            "height"
+#define XENKBD_FIELD_NUM_CONTACTS      "num-contacts"
+
+/* Path entries */
+#define XENKBD_PATH_MTOUCH             "mtouch"
 
  /* OBSOLETE, not recommended for use */
  #define XENKBD_FIELD_RING_REF          "page-ref"

@@ -249,6 +313,170 @@ struct xenkbd_position
      int32_t rel_z;
  };
 

xen/include/public/io/kbdif.h struct xenkbd_position · line 326

Quoted 11 lines

xen/include/public/io/kbdif.h +11 -0

+/*
+ * Multi-touch event and its sub-types
+ *
+ * All multi-touch event packets have common header:
+ *
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |    event_type   |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+

Given that the structs are all of the same size, shouldn't there be more reserved bytes here?

Quoted 27 lines

xen/include/public/io/kbdif.h +26 -0

+ * event_type - unt8_t, multi-touch event sub-type, XENKBD_MT_EV_???
+ * contact_id - unt8_t, ID of the contact
+ *
+ * Touch interactions can consist of one or more contacts.
+ * For each contact, a series of events is generated, starting
+ * with a down event, followed by zero or more motion events,
+ * and ending with an up event. Events relating to the same
+ * contact point can be identified by the ID of the sequence: contact ID.
+ * Contact ID may be reused after XENKBD_MT_EV_UP event and
+ * is in the [0; XENKBD_FIELD_NUM_CONTACTS - 1] range.
+ *
+ * For further information please refer to documentation on Wayland [1],
+ * Linux [2] and Windows [3] multi-touch support.
+ *
+ * [1] https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml
+ * [2] https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt
+ * [3] https://msdn.microsoft.com/en-us/library/jj151564(v=vs.85).aspx
+ *
+ *
+ * Multi-touch down event - sent when a new touch is made: touch is assigned
+ * a unique contact ID, sent with this and consequent events related
+ * to this touch.
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |   _MT_EV_DOWN   |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h struct xenkbd_position · line 363

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 abs_x                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 abs_y                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

Please write the byte count to specify how many bytes have been skipped.

Quoted 5 lines

xen/include/public/io/kbdif.h +5 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * abs_x - int32_t, absolute X position, in pixels
+ * abs_y - int32_t, absolute Y position, in pixels

xen/include/public/io/kbdif.h struct xenkbd_position · line 378

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ *
+ * Multi-touch contact release event
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |   _MT_EV_UP     |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

Please write the byte count to specify how many bytes have been skipped.

Quoted 8 lines

xen/include/public/io/kbdif.h +8 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * Multi-touch motion event
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |  _MT_EV_MOTION  |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h struct xenkbd_position · line 396

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 abs_x                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 abs_y                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

Please write the byte count to specify how many bytes have been skipped.

Quoted 6 lines

xen/include/public/io/kbdif.h +6 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * abs_x - int32_t, absolute X position, in pixels,
+ * abs_y - int32_t, absolute Y position, in pixels,
+ *

xen/include/public/io/kbdif.h struct xenkbd_position · line 412

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ * Multi-touch input synchronization event - shows end of a set of events
+ * which logically belong together.
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |   _MT_EV_SYN    |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

Please write the byte count to specify how many bytes have been skipped.

Quoted 12 lines

xen/include/public/io/kbdif.h +12 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * Multi-touch shape event - touch point's shape has changed its shape.
+ * Shape is approximated by an ellipse through the major and minor axis
+ * lengths: major is the longer diameter of the ellipse and minor is the
+ * shorter one. Center of the ellipse is reported via
+ * XENKBD_MT_EV_DOWN/XENKBD_MT_EV_MOTION events.
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |  _TYPE_MTOUCH   |  _MT_EV_SHAPE   |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h struct xenkbd_position · line 434

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 major                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                                 minor                                 |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

Please write the byte count to specify how many bytes have been skipped.

Quoted 11 lines

xen/include/public/io/kbdif.h +11 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * major - unt32_t, length of the major axis, pixels
+ * minor - unt32_t, length of the minor axis, pixels
+ *
+ * Multi-touch orientation event - touch point's shape has changed
+ * its orientation: calculated as a clockwise angle between the major axis
+ * of the ellipse and positive Y axis in degrees, [-180; +180].
+ *          0                 1                  2                3        octet
+ * +-----------------+-----------------+-----------------+-----------------+

xen/include/public/io/kbdif.h struct xenkbd_position · line 455

Quoted 10 lines

xen/include/public/io/kbdif.h +10 -0

+ * |  _TYPE_MTOUCH   |  _MT_EV_ORIENT  |    contact_id   |     reserved    |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |            orientation            |             reserved              |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
+ * +-----------------+-----------------+-----------------+-----------------+

Please write the byte count to specify how many bytes have been skipped.

Quoted 26 lines

xen/include/public/io/kbdif.h +24 -0

+ * |                               reserved                                |
+ * +-----------------+-----------------+-----------------+-----------------+
+ *
+ * orientation - int16_t, clockwise angle of the major axis
+ */
+
+struct xenkbd_mtouch {
+    uint8_t type;             /* XENKBD_TYPE_MTOUCH */
+    uint8_t event_type;       /* XENKBD_MT_EV_??? */
+    uint8_t contact_id;
+    uint8_t reserved[5];      /* reserved for the future use */
+    union {
+        struct {
+            int32_t abs_x;    /* absolute X position, pixels */
+            int32_t abs_y;    /* absolute Y position, pixels */
+        } pos;
+        struct {
+            uint32_t major;   /* length of the major axis, pixels */
+            uint32_t minor;   /* length of the minor axis, pixels */
+        } shape;
+        int16_t orientation;  /* clockwise angle of the major axis */
+    } u;
+};
+
  #define XENKBD_IN_EVENT_SIZE 40
 

Quoted 4 lines

xen/include/public/io/kbdif.h +0 -0

  union xenkbd_in_event

Signature · 1 line

2.7.4

Quoted 30 lines · Stefano Stabellini

Quoted 29 lines · Oleksandr Andrushchenko

From: Oleksandr Andrushchenko <[email protected]>

Signed-off-by Oleksandr Andrushchenko <[email protected]>

---
  xen/include/public/io/kbdif.h | 228
++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 228 insertions(+)

xen/include/public/io/kbdif.h +0 -0

index 0e19a40..1b446f9 100644
@@ -57,6 +57,12 @@
   *      Backends, which support reporting of absolute coordinates for

pointer
* device should set this to 1.
*
+ * feature-multi-touch
+ * Values: <uint>
+ *
+ * Backends, which support reporting of multi-touch events
+ * should set this to 1.
+ *
*------------------------- Pointer Device Parameters
------------------------
*
* width

xen/include/public/io/kbdif.h +0 -0

@@ -87,6 +93,11 @@
   *      Request from backend to report absolute pointer coordinates

Quoted 8 lines

xen/include/public/io/kbdif.h line 99

Quoted 6 lines

xen/include/public/io/kbdif.h +4 -0

   *      (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).
   *
+ * request-multi-touch
+ *      Values:         <uint>
+ *
+ *      Request from backend to report multi-touch events.

I think in English should be "request backend to report multi-touch events". Same above.

Done

Quoted 10 lines

Quoted 10 lines

xen/include/public/io/kbdif.h +1 -1

+ *
   *----------------------- Request Transport Parameters
-----------------------
   *
   * event-channel

@@ -107,6 +118,43 @@
   *      OBSOLETE, not recommended for use.
   *      A unique (within the guest domain given) value identifying event
   *      channel and page reference pair.

Quoted 9 lines

xen/include/public/io/kbdif.h line 124

Quoted 5 lines

xen/include/public/io/kbdif.h +4 -1

+ *
+ *----------------------- Multi-touch Device Parameters
-----------------------
+ *
+ * Every multi-touch input device uses a dedicated event ring and is

For clarity I would say "Every multi-touch input device uses a dedicated frontend/backend connection". That includes a ring, an event channel, and xenstore entries.

Done

Quoted 3 lines

xen/include/public/io/kbdif.h line 125

Quoted 1 line

xen/include/public/io/kbdif.h +1 -0

+ * configured via XenStore properties under XENKBD_PATH_MTOUCH folder.

I don't understand why we need a new xenstore folder. Why do we need XENKBD_PATH_MTOUCH?

This is just another (IMO, cleaner) approach to define properties in XenStore for multiple instances. Let's see what vif does on my PC:
/local/domain/11/device/vif/0/queue-0/tx-ring-ref = "2304"
...
/local/domain/11/device/vif/0/queue-1/tx-ring-ref = "2306"
...
/local/domain/11/device/vif/0/queue-2/tx-ring-ref = "2308"
...
/local/domain/11/device/vif/0/queue-3/tx-ring-ref = "2310"
...
/local/domain/11/device/vif/0/request-rx-copy = "1"

We have folders "queue-%d" per queue which in my case are

under XENKBD_PATH_MTOUCH.

/local/domain/11/device/vkbd/0/mtouch/0/width = "3200" /local/domain/11/device/vkbd/0/mtouch/0/height = "3200" /local/domain/11/device/vkbd/0/mtouch/0/num-contacts = "5" /local/domain/11/device/vkbd/0/mtouch/1/width = "6400" /local/domain/11/device/vkbd/0/mtouch/1/height = "6400" /local/domain/11/device/vkbd/0/mtouch/1/num-contacts = "10"

Namely, instead of "mtouch-%d" I use "mtouch/%d/. This is just like using "/local/domain/%d" but not "/local/domain-%d", so "mtouch/%d" seem to be more consistent.

It is useful to distinguish mouse events from keyboard events, from multitouch events more easily, but I don't think we should support multiple keyboards or multiple mice on the same xenkbd ring. If we need two mice, we can setup two xenkdb rings.

Quoted 86 lines · Oleksandr Andrushchenko

Quoted 30 lines · Stefano Stabellini

Quoted 29 lines · Oleksandr Andrushchenko

From: Oleksandr Andrushchenko <[email protected]>

Signed-off-by Oleksandr Andrushchenko <[email protected]>

---
   xen/include/public/io/kbdif.h | 228
++++++++++++++++++++++++++++++++++++++++++
   1 file changed, 228 insertions(+)

xen/include/public/io/kbdif.h +0 -0

index 0e19a40..1b446f9 100644
@@ -57,6 +57,12 @@
    *      Backends, which support reporting of absolute coordinates for

pointer
* device should set this to 1.
*
+ * feature-multi-touch
+ * Values: <uint>
+ *
+ * Backends, which support reporting of multi-touch events
+ * should set this to 1.
+ *

    *------------------------- Pointer Device Parameters

------------------------
*
* width

xen/include/public/io/kbdif.h +0 -0

@@ -87,6 +93,11 @@
    *      Request from backend to report absolute pointer coordinates

Quoted 8 lines

xen/include/public/io/kbdif.h line 99

Quoted 6 lines

xen/include/public/io/kbdif.h +4 -0

    *      (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).
    *
+ * request-multi-touch
+ *      Values:         <uint>
+ *
+ *      Request from backend to report multi-touch events.

I think in English should be "request backend to report multi-touch events". Same above.

Done

Quoted 9 lines

Quoted 9 lines

xen/include/public/io/kbdif.h +1 -1

+ *
    *----------------------- Request Transport Parameters
-----------------------
    *
    * event-channel

@@ -107,6 +118,43 @@
    *      OBSOLETE, not recommended for use.
    *      A unique (within the guest domain given) value identifying event
    *      channel and page reference pair.

Quoted 9 lines

xen/include/public/io/kbdif.h line 124

Quoted 5 lines

xen/include/public/io/kbdif.h +4 -1

+ *
+ *----------------------- Multi-touch Device Parameters
-----------------------
+ *
+ * Every multi-touch input device uses a dedicated event ring and is

For clarity I would say "Every multi-touch input device uses a dedicated frontend/backend connection". That includes a ring, an event channel, and xenstore entries.

Done

Quoted 3 lines

xen/include/public/io/kbdif.h line 125

Quoted 1 line

xen/include/public/io/kbdif.h +1 -0

+ * configured via XenStore properties under XENKBD_PATH_MTOUCH folder.

I don't understand why we need a new xenstore folder. Why do we need XENKBD_PATH_MTOUCH?

This is just another (IMO, cleaner) approach to define properties in XenStore for multiple instances. Let's see what vif does on my PC:
/local/domain/11/device/vif/0/queue-0/tx-ring-ref = "2304"
...
/local/domain/11/device/vif/0/queue-1/tx-ring-ref = "2306"
...
/local/domain/11/device/vif/0/queue-2/tx-ring-ref = "2308"
...
/local/domain/11/device/vif/0/queue-3/tx-ring-ref = "2310"
...
/local/domain/11/device/vif/0/request-rx-copy = "1"

We have folders "queue-%d" per queue which in my case are

under XENKBD_PATH_MTOUCH.

/local/domain/11/device/vkbd/0/mtouch/0/width = "3200" /local/domain/11/device/vkbd/0/mtouch/0/height = "3200" /local/domain/11/device/vkbd/0/mtouch/0/num-contacts = "5" /local/domain/11/device/vkbd/0/mtouch/1/width = "6400" /local/domain/11/device/vkbd/0/mtouch/1/height = "6400" /local/domain/11/device/vkbd/0/mtouch/1/num-contacts = "10"

Quoted 4 lines

Namely, instead of "mtouch-%d" I use "mtouch/%d/. This is just like using "/local/domain/%d" but not "/local/domain-%d", so "mtouch/%d" seem to be more consistent.

I agree that mtouch/%d is better than mtouch-%d, but it's only necessary if we have more than one mtouch per vkbd. I would configure it so that one can only have one mtouch per vkbd:

   /local/domain/11/device/vkbd/0/mtouch/width = "3200"
   /local/domain/11/device/vkbd/0/mtouch/height = "3200"
   /local/domain/11/device/vkbd/1/mtouch/width = "6400"
   /local/domain/11/device/vkbd/1/mtouch/height = "6400"

Quoted 4 lines · This is also what I was referring to when I

It is useful to distinguish mouse events from keyboard events, from multitouch events more easily, but I don't think we should support multiple keyboards or multiple mice on the same xenkbd ring. If we need two mice, we can setup two xenkdb rings.

The same applies to multitouch devices, I think.

But maybe you have good reasons for supporting multiple multitouch devices on a single vkbd connection? How many do you expect to have on a single VM?

Quoted 97 lines · Stefano Stabellini

Quoted 92 lines · Oleksandr Andrushchenko

Quoted 34 lines · Stefano Stabellini

Quoted 33 lines · Oleksandr Andrushchenko

From: Oleksandr Andrushchenko <[email protected]>

Signed-off-by: Oleksandr Andrushchenko
<[email protected]>

---
   xen/include/public/io/kbdif.h | 228
++++++++++++++++++++++++++++++++++++++++++
   1 file changed, 228 insertions(+)

xen/include/public/io/kbdif.h +0 -0

index 0e19a40..1b446f9 100644
@@ -57,6 +57,12 @@
    *      Backends, which support reporting of absolute coordinates

for
pointer
* device should set this to 1.
*
+ * feature-multi-touch
+ * Values: <uint>
+ *
+ * Backends, which support reporting of multi-touch events
+ * should set this to 1.
+ *

    *------------------------- Pointer Device Parameters

------------------------
*
* width

xen/include/public/io/kbdif.h +0 -0

@@ -87,6 +93,11 @@
    *      Request from backend to report absolute pointer coordinates
    *      (XENKBD_TYPE_POS) instead of relative ones

Quoted 8 lines

Quoted 6 lines

(XENKBD_TYPE_MOTION).

    *

+ * request-multi-touch
+ * Values: <uint>
+ *
+ * Request from backend to report multi-touch events.

I think in English should be "request backend to report multi-touch events". Same above.

Done

Quoted 10 lines

Quoted 10 lines

+ *

    *----------------------- Request Transport Parameters

-----------------------
*
* event-channel

xen/include/public/io/kbdif.h +0 -0

@@ -107,6 +118,43 @@
    *      OBSOLETE, not recommended for use.
    *      A unique (within the guest domain given) value identifying

event
* channel and page reference pair.

Quoted 9 lines

Quoted 5 lines

+ *
+ *----------------------- Multi-touch Device Parameters
-----------------------
+ *
+ * Every multi-touch input device uses a dedicated event ring and is

For clarity I would say "Every multi-touch input device uses a dedicated frontend/backend connection". That includes a ring, an event channel, and xenstore entries.

Done

Quoted 4 lines

Quoted 2 lines

+ * configured via XenStore properties under XENKBD_PATH_MTOUCH folder.

I don't understand why we need a new xenstore folder. Why do we need XENKBD_PATH_MTOUCH?

This is just another (IMO, cleaner) approach to define properties in XenStore for multiple instances. Let's see what vif does on my PC:
/local/domain/11/device/vif/0/queue-0/tx-ring-ref = "2304"
...
/local/domain/11/device/vif/0/queue-1/tx-ring-ref = "2306"
...
/local/domain/11/device/vif/0/queue-2/tx-ring-ref = "2308"
...
/local/domain/11/device/vif/0/queue-3/tx-ring-ref = "2310"
...
/local/domain/11/device/vif/0/request-rx-copy = "1"

We have folders "queue-%d" per queue which in my case are

under XENKBD_PATH_MTOUCH.

/local/domain/11/device/vkbd/0/mtouch/0/width = "3200" /local/domain/11/device/vkbd/0/mtouch/0/height = "3200" /local/domain/11/device/vkbd/0/mtouch/0/num-contacts = "5" /local/domain/11/device/vkbd/0/mtouch/1/width = "6400" /local/domain/11/device/vkbd/0/mtouch/1/height = "6400" /local/domain/11/device/vkbd/0/mtouch/1/num-contacts = "10"

Quoted 4 lines

Namely, instead of "mtouch-%d" I use "mtouch/%d/. This is just like using "/local/domain/%d" but not "/local/domain-%d", so "mtouch/%d" seem to be more consistent.

Quoted 8 lines

I agree that mtouch/%d is better than mtouch-%d, but it's only necessary if we have more than one mtouch per vkbd. I would configure it so that one can only have one mtouch per vkbd:

   /local/domain/11/device/vkbd/0/mtouch/width = "3200"
   /local/domain/11/device/vkbd/0/mtouch/height = "3200"
   /local/domain/11/device/vkbd/1/mtouch/width = "6400"
   /local/domain/11/device/vkbd/1/mtouch/height = "6400"

correct me if I'm wrong, but this notation implies multiple drivers support, not a single driver with multiple devices.
If so, *DISCLAIMER* *Linux* I see no simple solution to do that in the front driver.
Could you please clarify?

Quoted 11 lines

Quoted 4 lines · This is also what I was referring to when I

It is useful to distinguish mouse events from keyboard events, from multitouch events more easily, but I don't think we should support multiple keyboards or multiple mice on the same xenkbd ring. If we need two mice, we can setup two xenkdb rings.

The same applies to multitouch devices, I think.

But maybe you have good reasons for supporting multiple multitouch devices on a single vkbd connection? How many do you expect to have on a single VM?

well, let me put the whole tree from xenstore:

/local/domain/0/backend/vkbd/2/0/frontend-id = "2" /local/domain/0/backend/vkbd/2/0/frontend = "/local/domain/2/device/vkbd/0" /local/domain/0/backend/vkbd/2/0/dev_id = "0" /local/domain/0/backend/vkbd/2/0/state = "6" /local/domain/0/backend/vkbd/2/0/feature-abs-pointer = "1" /local/domain/0/backend/vkbd/2/0/width = "2048" /local/domain/0/backend/vkbd/2/0/height = "2048" /local/domain/0/backend/vkbd/2/0/feature-multi-touch = "1"

/local/domain/2/device/vkbd/0/backend-id = "0" /local/domain/2/device/vkbd/0/backend = "/local/domain/0/backend/vkbd/2/0" /local/domain/2/device/vkbd/0/state = "6" /local/domain/2/device/vkbd/0/request-abs-pointer = "1" /local/domain/2/device/vkbd/0/page-ref = "1248025" /local/domain/2/device/vkbd/0/page-gref = "336" /local/domain/2/device/vkbd/0/event-channel = "43"

/local/domain/2/device/vkbd/0/request-multi-touch = "1"

/local/domain/2/device/vkbd/0/mtouch/0/width = "3200" /local/domain/2/device/vkbd/0/mtouch/0/height = "3200" /local/domain/2/device/vkbd/0/mtouch/0/num-contacts = "5" /local/domain/2/device/vkbd/0/mtouch/0/page-ref = "1252386" /local/domain/2/device/vkbd/0/mtouch/0/page-gref = "335" /local/domain/2/device/vkbd/0/mtouch/0/event-channel = "44"

/local/domain/2/device/vkbd/0/mtouch/1/width = "6400" /local/domain/2/device/vkbd/0/mtouch/1/height = "6400" /local/domain/2/device/vkbd/0/mtouch/1/num-contacts = "10" /local/domain/2/device/vkbd/0/mtouch/1/page-ref = "2376038" /local/domain/2/device/vkbd/0/mtouch/1/page-gref = "337" /local/domain/2/device/vkbd/0/mtouch/1/event-channel = "45"

From the above:
1. No change to the existing kbd+ptr:
1.1. They still share a dedicated (single) connection channel as they did before multi-touch.
1.2. No multi-touch events via that connection 1.3. Old backends/frontends will see no difference
2. Each multi-touch device has its own:
2.1. Configuration (width x height, num-contacts) 2.2. Own connection channel (page-ref, event-channel)

So, for the example above: 1 kbd + 1 ptr + 2 mt devices within a single driver, 3 connections

Note: this doesn't allow multiple kbd and ptr devices.

Hope this answers your questions,
Oleksandr

From: Oleksandr Andrushchenko <[email protected]>

Hi, all!

This series updates existing kbdif protocol documentation and adds multi-touch support

Thank you,
Oleksandr Andrushchenko

Oleksandr Andrushchenko (2):
xen/kbdif: update protocol documentation
xen/kbdif: add multi-touch support

  xen/include/public/io/kbdif.h | 477 +++++++++++++++++++++++++++++++++++++++---
  1 file changed, 450 insertions(+), 27 deletions(-)