xen/kbdif: add multi-touch support
v3 cover xen/kbdif: add multi-touch support
From: Oleksandr Andrushchenko <[email protected]>
Hi, all!
This series updates existing kbdif protocol documentation and adds multi-touch support
Thank you,
Oleksandr Andrushchenko
---
Changes since v2:
* changed names of Xen store entries from
mt-xxx to multi-touch-xxx
Changes since v1:
* removed mtouch folder
* changed mtouch xenstore parameters' names
* single multi-touch device per driver, if more needed multiple instances of the driver should be configured via xenstore entries
Oleksandr Andrushchenko (2):
xen/kbdif: update protocol documentation
xen/kbdif: add multi-touch support
xen/include/public/io/kbdif.h | 458 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 431 insertions(+), 27 deletions(-)
Signature · 7 lines
2.7.4 _______________________________________________ Xen-devel mailing list [email protected] https://lists.xen.org/xen-devel
PATCH v3 1/2 xen/kbdif: update protocol documentation
From: Oleksandr Andrushchenko <[email protected]>
Update protocol documentation with better description and ASCII box notation of the structures. Add description for Xen store entries, introduce helper string constants.
--- xen/include/public/io/kbdif.h | 248 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 221 insertions(+), 27 deletions(-)
xen/include/public/io/kbdif.h +221 -27
@@ -26,46 +26,226 @@#ifndef __XEN_PUBLIC_IO_KBDIF_H__#define __XEN_PUBLIC_IO_KBDIF_H__ -/* In events (backend -> frontend) */ +/* +***************************************************************************** +* Feature and Parameter Negotiation +***************************************************************************** +* +* The two halves of a para-virtual driver utilize nodes within +* XenStore to communicate capabilities and to negotiate operating parameters. +* This section enumerates these nodes which reside in the respective front and +* backend portions of XenStore, following XenBus convention. +* +* All data in 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. +* +***************************************************************************** +* 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 a feature is not supported then 0 must be set or feature entry omitted. +* +* 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 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> +* +* 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. +* PFN of the shared page. +*/ /* -* 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" + +/* +***************************************************************************** +* 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 structures. +* +* 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 | 4 +* +----------------+----------------+----------------+----------------+ +* | rel_x | 8 +* +----------------+----------------+----------------+----------------+ +* | rel_y | 12 +* +----------------+----------------+----------------+----------------+ +* | rel_z | 16 +* +----------------+----------------+----------------+----------------+ +* | reserved | 20 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* 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 4struct 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) +* 0 1 2 3 octet +* +----------------+----------------+----------------+----------------+ +* | _TYPE_KEY | pressed | reserved | 4 +* +----------------+----------------+----------------+----------------+ +* | keycode | 8 +* +----------------+----------------+----------------+----------------+ +* | reserved | 12 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* 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 | 4 +* +----------------+----------------+----------------+----------------+ +* | abs_x | 8 +* +----------------+----------------+----------------+----------------+ +* | abs_y | 12 +* +----------------+----------------+----------------+----------------+ +* | rel_z | 16 +* +----------------+----------------+----------------+----------------+ +* | reserved | 20 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* 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 +259,22 @@ union xenkbd_in_eventchar 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 +285,11 @@ union xenkbd_out_eventchar 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 +313,7 @@ struct xenkbd_page uint32_t out_cons, out_prod; }; -#endif +#endif /* __XEN_PUBLIC_IO_KBDIF_H__ */ /* * Local variables:
Signature · 7 lines
2.7.4 _______________________________________________ Xen-devel mailing list [email protected] https://lists.xen.org/xen-devel
PATCH v3 2/2 xen/kbdif: add multi-touch support
In reply to Oleksandr AndrushchenkoFrom: Oleksandr Andrushchenko <[email protected]>
Multi-touch fields re-use the page that is used by the other features which means that you can interleave multi-touch, motion, and key events.
--- xen/include/public/io/kbdif.h | 210 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+)
xen/include/public/io/kbdif.h +210 -0
@@ -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 backend to report absolute pointer coordinates * (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION). * +* request-multi-touch +* Values: <uint> +* +* Request backend to report multi-touch events. +* *----------------------- Request Transport Parameters ----------------------- * * event-channel
@@ -106,6 +117,25 @@* * OBSOLETE, not recommended for use. * PFN of the shared page. +* +*----------------------- Multi-touch Device Parameters ----------------------- +* +* multi-touch-num-contacts +* Values: <uint> +* +* Number of simultaneous touches reported. +* +* multi-touch-width +* Values: <uint> +* +* Width of the touch area to be used by the frontend +* while reporting input events, pixels, [0; UINT32_MAX]. +* +* multi-touch-height +* Values: <uint> +* +* Height of the touch area to be used by the frontend +* while reporting input events, pixels, [0; UINT32_MAX]. */ /*
@@ -116,6 +146,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.
@@ -124,11 +164,16 @@#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_MT_WIDTH "multi-touch-width" +#define XENKBD_FIELD_MT_HEIGHT "multi-touch-height" +#define XENKBD_FIELD_MT_NUM_CONTACTS "multi-touch-num-contacts"/* OBSOLETE, not recommended for use */ #define XENKBD_FIELD_RING_REF "page-ref"
@@ -248,6 +293,170 @@ struct xenkbd_positionint32_t rel_z; }; +/* +* 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 | 4 +* +----------------+----------------+----------------+----------------+ +* | reserved | 8 +* +----------------+----------------+----------------+----------------+ +* +* 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 | 4 +* +----------------+----------------+----------------+----------------+ +* | reserved | 8 +* +----------------+----------------+----------------+----------------+ +* | abs_x | 12 +* +----------------+----------------+----------------+----------------+ +* | abs_y | 16 +* +----------------+----------------+----------------+----------------+ +* | reserved | 20 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* abs_x - int32_t, absolute X position, in pixels +* abs_y - int32_t, absolute Y position, in pixels +* +* Multi-touch contact release event +* 0 1 2 3 octet +* +----------------+----------------+----------------+----------------+ +* | _TYPE_MTOUCH | _MT_EV_UP | contact_id | reserved | 4 +* +----------------+----------------+----------------+----------------+ +* | reserved | 8 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* Multi-touch motion event +* 0 1 2 3 octet +* +----------------+----------------+----------------+----------------+ +* | _TYPE_MTOUCH | _MT_EV_MOTION | contact_id | reserved | 4 +* +----------------+----------------+----------------+----------------+ +* | reserved | 8 +* +----------------+----------------+----------------+----------------+ +* | abs_x | 12 +* +----------------+----------------+----------------+----------------+ +* | abs_y | 16 +* +----------------+----------------+----------------+----------------+ +* | reserved | 20 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* abs_x - int32_t, absolute X position, in pixels, +* abs_y - int32_t, absolute Y position, in pixels, +* +* 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 | 4 +* +----------------+----------------+----------------+----------------+ +* | reserved | 8 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* 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 | 4 +* +----------------+----------------+----------------+----------------+ +* | reserved | 8 +* +----------------+----------------+----------------+----------------+ +* | major | 12 +* +----------------+----------------+----------------+----------------+ +* | minor | 16 +* +----------------+----------------+----------------+----------------+ +* | reserved | 20 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* 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 +* +----------------+----------------+----------------+----------------+ +* | _TYPE_MTOUCH | _MT_EV_ORIENT | contact_id | reserved | 4 +* +----------------+----------------+----------------+----------------+ +* | reserved | 8 +* +----------------+----------------+----------------+----------------+ +* | orientation | reserved | 12 +* +----------------+----------------+----------------+----------------+ +* | reserved | 16 +* +----------------+----------------+----------------+----------------+ +* |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| +* +----------------+----------------+----------------+----------------+ +* | reserved | 40 +* +----------------+----------------+----------------+----------------+ +* +* 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 40union xenkbd_in_event
@@ -256,6 +465,7 @@ union xenkbd_in_eventstruct xenkbd_motion motion;struct xenkbd_key key;struct xenkbd_position pos; +struct xenkbd_mtouch mtouch;char pad[XENKBD_IN_EVENT_SIZE ]; };
Signature · 7 lines
2.7.4 _______________________________________________ Xen-devel mailing list [email protected] https://lists.xen.org/xen-devel
Quoted 7 lines · Oleksandr Andrushchenko
From: Oleksandr Andrushchenko <[email protected]>
Multi-touch fields re-use the page that is used by the other features which means that you can interleave multi-touch, motion, and key events.
Reviewed-by Stefano Stabellini <[email protected]>
Quoted 1 line
Signed-off-by Oleksandr Andrushchenko <[email protected]>
If nobody objects by a week timeframe I will commit this in.
Thanks!
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xen.org/xen-devel
ping
Quoted 7 lines · Konrad Rzeszutek Wilk
Quoted 6 lines · Oleksandr Andrushchenko
From: Oleksandr Andrushchenko <[email protected]>
Multi-touch fields re-use the page that is used by the other features which means that you can interleave multi-touch, motion, and key events.
Quoted 7 lines
Quoted 1 line
Reviewed-by Stefano Stabellini <[email protected]>Reviewed-by Konrad Rzeszutek Wilk <[email protected]>Quoted 1 line
Signed-off-by Oleksandr Andrushchenko <[email protected]>If nobody objects by a week timeframe I will commit this in.
Thanks!
_______________________________________________
Xen-devel mailing list
[email protected]
https://lists.xen.org/xen-devel