|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Xen-devel] [PATCH 1/2] xen/kbdif: update protocol documentation
On Fri, 6 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 | 249
> +++++++++++++++++++++++++++++++++++++-----
> 1 file changed, 222 insertions(+), 27 deletions(-)
>
> diff --git a/xen/include/public/io/kbdif.h b/xen/include/public/io/kbdif.h
> index 2d2aebd..0e19a40 100644
> --- a/xen/include/public/io/kbdif.h
> +++ b/xen/include/public/io/kbdif.h
> @@ -26,46 +26,227 @@
> #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
It's just "XenStore", not "the XenStore", all across the doc.
> + * 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.
> + *
> +
> *****************************************************************************
> + * 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
> + *
> + * 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>
> + *
> + * 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.
> + */
>
> /*
> - * 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 packets.
^ I would call them "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 |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | 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?
> + * | 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)
> + * 0 1 2 3
> octet
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | _TYPE_KEY | pressed | reserved |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | keycode |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | reserved |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
> + * +-----------------+-----------------+-----------------+-----------------+
same here
> + * | 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 |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | abs_x |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | abs_y |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | rel_z |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * | reserved |
> + * +-----------------+-----------------+-----------------+-----------------+
> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
> + * +-----------------+-----------------+-----------------+-----------------+
same here
> + * | 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:
> --
> 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 |