|
[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 Fri, 20 Jan 2017, Oleksandr Andrushchenko wrote:
> On 01/19/2017 08:56 PM, Stefano Stabellini wrote:
> > 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>
> Thanks,
> with this change done, can I put your Reviewed-by
> into the next version of this patch?
Of course. Thanks,
Stefano
> > > + * 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 |