From patchwork Wed Feb 8 07:38:17 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Oleksandr Andrushchenko X-Patchwork-Id: 9561837 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id DEFB060236 for ; Wed, 8 Feb 2017 07:40:44 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id CF410284CD for ; Wed, 8 Feb 2017 07:40:44 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C4190284CE; Wed, 8 Feb 2017 07:40:44 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-3.6 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_MED, RCVD_IN_SORBS_SPAM, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id A3043284D2 for ; Wed, 8 Feb 2017 07:40:43 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cbMpl-0001yw-Ln; Wed, 08 Feb 2017 07:38:33 +0000 Received: from mail6.bemta3.messagelabs.com ([195.245.230.39]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cbMpj-0001yX-UL for xen-devel@lists.xenproject.org; Wed, 08 Feb 2017 07:38:32 +0000 Received: from [85.158.137.68] by server-8.bemta-3.messagelabs.com id 7D/3F-31649-7FACA985; Wed, 08 Feb 2017 07:38:31 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFlrDIsWRWlGSWpSXmKPExsVyMbThsO63U7M iDH59ELL4vmUykwOjx+EPV1gCGKNYM/OS8isSWDPedYQWHEis2Dp/HWMD42WPLkYuDiGB6YwS KybtYwFxWAReskgcb1/J3MXIySEh0M8q8e9CJIQdI/FxwkeoeK3E2fttTCC2kICixNdn05kgJ i1nkjj2/yc7SIJNwEhi+Y0fLCC2iICSxL1Vk8GKmAW+M0r8W3CHESQhLOAg8eHkFzCbRUBVYm rPRDCbFyj+7vBcdohtchI3z3WCbeYUcJRo37KFEWKzg8SrhgWsExgFFjAyrGLUKE4tKkst0jU y1UsqykzPKMlNzMzRNTQw1stNLS5OTE/NSUwq1kvOz93ECAytegYGxh2MrSf8DjFKcjApifIy AkNOiC8pP6UyI7E4I76oNCe1+BCjDAeHkgTv8pNAOcGi1PTUirTMHGCQw6QlOHiURHilQVp5i wsSc4sz0yFSpxgtOXq6Tr9k4jh1A0Tu2XX5JZMQS15+XqqUOK8fSIMASENGaR7cOFgkXmKUlR LmZWRgYBDiKUgtys0sQZV/xSjOwagkzKsGMoUnM68EbusroIOYgA7admUayEEliQgpqQZG/Rv GJ8ov3Juy0mLdUx+hoKoF6i/CDwh87RNQrFhyZHmLPpuLX6R0Rm7M43L/77ftDp2psrG6cGSp oK1ZXLPNj21nBaorPv34/mpNnPTWiYIupjseiAse/W542JC33U9mOvukxrU8v0KaXB884zPbP a2xJe52nXT+T+kTCZNCv39dlxyQOf+KEktxRqKhFnNRcSIA3FlhY78CAAA= X-Env-Sender: andr2000@gmail.com X-Msg-Ref: server-7.tower-31.messagelabs.com!1486539510!76965263!1 X-Originating-IP: [209.85.128.195] X-SpamReason: No, hits=0.5 required=7.0 tests=BODY_RANDOM_LONG X-StarScan-Received: X-StarScan-Version: 9.1.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 35999 invoked from network); 8 Feb 2017 07:38:30 -0000 Received: from mail-wr0-f195.google.com (HELO mail-wr0-f195.google.com) (209.85.128.195) by server-7.tower-31.messagelabs.com with AES128-GCM-SHA256 encrypted SMTP; 8 Feb 2017 07:38:30 -0000 Received: by mail-wr0-f195.google.com with SMTP id 89so7894539wrr.1 for ; Tue, 07 Feb 2017 23:38:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=0KccKZkBNx17kHLsgLWOE5HHkhVE4k5azsx7j6QGwIE=; b=qfUTg8EBwkU9agd1PTW0UUm7YYA+LCZ+KVaBK7vK7TvKpDQies5kAo04pHyCqfHyWD 2Ruc6RLlw4ZhcndIIay5hjRBMadRPOZSKPRVzfS/uygMlHqoEe+F6oRwNiqVcfvUztz+ IbIA2SvAPAKMbrA0k5SsgnHjem6W+AIPR8rfLkinGUS5Ycm+yBBdW7FqQ1NPAlMLluoY R4LYY+NYdsnvMhV9VRLxji6x47dmwaPi784ErjPRE8SOWnXXaOjyutskNlRu9GnNQKny uVtUwBR+E8JMsX/ehU9v5tNNTpeknVtZFoXDf0gyjl56vw4sorQOOVIqrrmYZD0Idd/j dzXg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=0KccKZkBNx17kHLsgLWOE5HHkhVE4k5azsx7j6QGwIE=; b=rrCiZd3glXgAHn9erPRVhAjL/ZVsYMpx/Ev4ZJeffkrjbAvV1G3PnXJHL1PEYCIA8E 3vym10GkP9LBhPPHULW5QGli6blUDl+gULK4yGRYQ5mMBF9kWlJNDQKoer2+SAPUBC6T 4UJCk3YxhmZkBLWFjI1kdfUy133D5BZCO5ZzgzH8S7bAkrQuPFKHBVflDyCXCkF9HNFA gRo9Xe4KgS82yCDf6XyYI2JVHkBbNgPSj/+z+DXJ1sDh6wwT5vpLpD6kQfGtUCqhv9yx ckZODPGXcqpAYDvC33JO7vm2y2hB7EMnjh0Yx/+AcS5JfRBeOinS0z9Zw9kUY6V3hWqr apKw== X-Gm-Message-State: AIkVDXKVYoSWaNJuPTSshJlhCF0rtzes7jZmmU6tjJOX/otRpDdPw/RbChPamfMirccj1A== X-Received: by 10.223.169.112 with SMTP id u103mr17332990wrc.166.1486539509681; Tue, 07 Feb 2017 23:38:29 -0800 (PST) Received: from a2k-HP-ProDesk-600-G2-SFF.kyiv.epam.com (ll-54.209.223.85.sovam.net.ua. [85.223.209.54]) by smtp.gmail.com with ESMTPSA id q1sm1804737wmd.6.2017.02.07.23.38.28 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 07 Feb 2017 23:38:29 -0800 (PST) From: Oleksandr Andrushchenko To: xen-devel@lists.xenproject.org Date: Wed, 8 Feb 2017 09:38:17 +0200 Message-Id: <1486539498-381-2-git-send-email-andr2000@gmail.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1486539498-381-1-git-send-email-andr2000@gmail.com> References: <1486539498-381-1-git-send-email-andr2000@gmail.com> Cc: sstabellini@kernel.org, vlad.babchuk@gmail.com, Oleksandr Andrushchenko , andrii.anisov@gmail.com, olekstysh@gmail.com, andr2000@gmail.com, al1img@gmail.com, joculator@gmail.com Subject: [Xen-devel] [PATCH v3 1/2] xen/kbdif: update protocol documentation X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP From: Oleksandr Andrushchenko Update protocol documentation with better description and ASCII box notation of the structures. Add description for Xen store entries, introduce helper string constants. Reviewed-by: Stefano Stabellini Reviewed-by: Konrad Rzeszutek Wilk Signed-off-by: Oleksandr Andrushchenko --- 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..446aed2478b5 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 + * 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: + * + * Backends, which support reporting of absolute coordinates for pointer + * device should set this to 1. + * + *------------------------- Pointer Device Parameters ------------------------ + * + * width + * Values: + * + * Maximum X coordinate (width) to be used by the frontend + * while reporting input events, pixels, [0; UINT32_MAX]. + * + * height + * Values: + * + * 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: + * + * Request backend to report absolute pointer coordinates + * (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION). + * + *----------------------- Request Transport Parameters ----------------------- + * + * event-channel + * Values: + * + * The identifier of the Xen event channel used to signal activity + * in the ring buffer. + * + * page-gref + * Values: + * + * 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: + * + * 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: