|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Xen-devel] [PATCH v1 1/2] xen/kbdif: update protocol documentation
On Thu, 19 Jan 2017, Oleksandr Andrushchenko wrote:
> From: Oleksandr Andrushchenko <Oleksandr_Andrushchenko@xxxxxxxx>
>
> Signed-off-by: Oleksandr Andrushchenko <Oleksandr_Andrushchenko@xxxxxxxx>
> ---
> xen/include/public/io/kbdif.h | 248
> +++++++++++++++++++++++++++++++++++++-----
> 1 file changed, 221 insertions(+), 27 deletions(-)
>
> diff --git a/xen/include/public/io/kbdif.h b/xen/include/public/io/kbdif.h
> index 2d2aebdd3f28..c00faa3af5d2 100644
> --- a/xen/include/public/io/kbdif.h
> +++ b/xen/include/public/io/kbdif.h
> @@ -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 the
within "XenStore", drop "the"
Aside from this minor this:
Reviewed-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
> + * 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 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)
> + * 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_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 +285,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 +313,7 @@ struct xenkbd_page
> uint32_t out_cons, out_prod;
> };
>
> -#endif
> +#endif /* __XEN_PUBLIC_IO_KBDIF_H__ */
>
> /*
> * Local variables:
> --
> 2.7.4
>
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |