From patchwork Mon Apr 10 06:25:26 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Oleksandr Andrushchenko X-Patchwork-Id: 9672007 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 2A61360231 for ; Mon, 10 Apr 2017 06:28:01 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1B3CD27D29 for ; Mon, 10 Apr 2017 06:28:01 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 0F81227EED; Mon, 10 Apr 2017 06:28:01 +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 4983327FA8 for ; Mon, 10 Apr 2017 06:28:00 +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 1cxSlh-00087J-Qt; Mon, 10 Apr 2017 06:25:41 +0000 Received: from mail6.bemta5.messagelabs.com ([195.245.231.135]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cxSlg-000871-7T for xen-devel@lists.xenproject.org; Mon, 10 Apr 2017 06:25:40 +0000 Received: from [85.158.139.211] by server-15.bemta-5.messagelabs.com id BA/67-01711-3652BE85; Mon, 10 Apr 2017 06:25:39 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFlrBIsWRWlGSWpSXmKPExsXiVRvkrJuk+jr C4PBuA4vvWyYzOTB6HP5whSWAMYo1My8pvyKBNWPR3xfsBfPiKi6ePcLSwLjFvYuRi0NIYAaj xMZtW1hAHBaBlywSzx9tZQVxJAT6WSVePlrI3MXICeTESSzsa2SEsCskPt2/wQRiCwkoSnx9N p0JYtQqJolTXc/BEmwCRhLLb/xgAbFFBJQk7q2aDFbELHCdSaK74ztYkbCAk0Tr5W4wm0VAVe LNmV1g23iB4r8u3oPaLCdx81wnmM0p4CxxctJ1NojNThKdVx8wT2AUWMDIsIpRozi1qCy1SNf QQC+pKDM9oyQ3MTMHyDPVy00tLk5MT81JTCrWS87P3cQIDC8GINjBuGaq8yFGSQ4mJVFe1toX EUJ8SfkplRmJxRnxRaU5qcWHGGU4OJQkeFVVXkcICRalpqdWpGXmAAMdJi3BwaMkwvtbGSjNW 1yQmFucmQ6ROsVozPFu6Yf3TByPVv54zyTEkpeflyolzvsVpFQApDSjNA9uECwCLzHKSgnzMg KdJsRTkFqUm1mCKv+KUZyDUUmYVwbkHp7MvBK4fa+ATmECOuXMrpcgp5QkIqSkGhhzF6YueLH R6l2v3pNU26dFDppH2M7uZzF4ab9LUvkIT9UkzfmRTRfUCxqC/TP/XUiUOXvFN7rxxGPnZkGO h9sLMi4rbHKSON4vf3zKb56a89mK39y+nZ3zPykq88lVRpvl2301BLeuv+24KHqaX77YhW95p 37evFO8b1Xbz9NPphTskDvad+yQEktxRqKhFnNRcSIA63/jbbsCAAA= X-Env-Sender: andr2000@gmail.com X-Msg-Ref: server-2.tower-206.messagelabs.com!1491805537!72055384!1 X-Originating-IP: [74.125.82.67] X-SpamReason: No, hits=0.5 required=7.0 tests=BODY_RANDOM_LONG X-StarScan-Received: X-StarScan-Version: 9.4.12; banners=-,-,- X-VirusChecked: Checked Received: (qmail 61962 invoked from network); 10 Apr 2017 06:25:37 -0000 Received: from mail-wm0-f67.google.com (HELO mail-wm0-f67.google.com) (74.125.82.67) by server-2.tower-206.messagelabs.com with AES128-GCM-SHA256 encrypted SMTP; 10 Apr 2017 06:25:37 -0000 Received: by mail-wm0-f67.google.com with SMTP id q125so7794347wmd.3 for ; Sun, 09 Apr 2017 23:25:37 -0700 (PDT) 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=/yM0swfK2KXxazhOeLBTloCUoAKj8tne8KM1UTc7jRI=; b=SrCP1Lj9R6GLhjpDZWzP7mGjMNiB32Tt278JRxhctlWhDY8B5LLJrzPYSfFls3H1UC jFlGYVZ8MopbmPmcP2To4oYJBKTTY0er4EPOFWwXkFs9ip2GKoebcAWOd3rbBQLGFBme V6ShNjqMs7NuXz83N5x2KmW7kIHACKNAUiD7f0V606w/uzNS4n00963BIWjScIBSCgQ+ lKx59ByW/uvmzVlhhXTtVRZFTj42W2UCnCeHPh7kdRu2oZdjojQdLgzeiANQiFiOmgWZ KUNw6iaFP/9oC5ZGr/sxtPIyByXtFGx30+mjHBDfh1iDW81LiDjxDF9Zs4yq1+Cjm/JN S3rg== 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=/yM0swfK2KXxazhOeLBTloCUoAKj8tne8KM1UTc7jRI=; b=K4DaXKv1y3dPVfAIRRIS1GopQbDXUMbhapRCnJneAihssGDyb/nkAa72kiOinbQMNR UzB6GdF9QzrEDa6IoB4BM+4aQ101mDtYP54XWlSJo/xhM/hRoHgW2+WdCKIQJDnAHMO8 hjj8mTYg1hRp7f4d8JFgsG4Y4CBjs0Tdr+n4rhsLGT2mpW7PqJQXPSCzaS0/Crm/u0ls 3EhQK7N3iy3lnINxbWiwNNILURSNbZ0O2KxdjnuLNQtdnlpDLpY0k7nDitlKCIv13XWF PSVV5hYjjA+8iJr38lp705bYrgpXS2xHQnkyjepig68eSn2Ep/AnhnKNDwKupdRTr4wS /fKg== X-Gm-Message-State: AN3rC/4D53t63igTThKorBPqpcSn/TewW9SxiCo5uq6J3AkZ/Kv5CKZf nHPfyTOVABndXQ== X-Received: by 10.28.134.66 with SMTP id i63mr9256432wmd.84.1491805537207; Sun, 09 Apr 2017 23:25:37 -0700 (PDT) Received: from a2k-HP-ProDesk-600-G2-SFF.kyiv.epam.com (ll-55.209.223.85.sovam.net.ua. [85.223.209.55]) by smtp.gmail.com with ESMTPSA id m14sm16118556wrb.13.2017.04.09.23.25.35 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 09 Apr 2017 23:25:36 -0700 (PDT) From: Oleksandr Andrushchenko To: xen-devel@lists.xenproject.org Date: Mon, 10 Apr 2017 09:25:26 +0300 Message-Id: <1491805529-20603-2-git-send-email-andr2000@gmail.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1491805529-20603-1-git-send-email-andr2000@gmail.com> References: <1491805529-20603-1-git-send-email-andr2000@gmail.com> Cc: jgross@suse.com, lars.kurth@citrix.com, sstabellini@kernel.org, vlad.babchuk@gmail.com, linux-kernel@vger.kernel.org, Oleksandr Andrushchenko , julien.grall@arm.com, andrii.anisov@gmail.com, olekstysh@gmail.com, andr2000@gmail.com, al1img@gmail.com, joculator@gmail.com Subject: [Xen-devel] [For Linux v1 1/4] xen/kbdif: update protocol description 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 The patch clarifies the protocol that is used by the PV keyboard drivers. Acked-by: Juergen Gross Signed-off-by: Oleksandr Andrushchenko --- include/xen/interface/io/kbdif.h | 248 ++++++++++++++++++++++++++++++++++----- 1 file changed, 221 insertions(+), 27 deletions(-) diff --git a/include/xen/interface/io/kbdif.h b/include/xen/interface/io/kbdif.h index 8066c7849fbe..7adfb15fec9d 100644 --- a/include/xen/interface/io/kbdif.h +++ b/include/xen/interface/io/kbdif.h @@ -26,43 +26,223 @@ #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 @@ -75,12 +255,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 @@ -90,7 +280,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) @@ -113,4 +307,4 @@ struct xenkbd_page { uint32_t out_cons, out_prod; }; -#endif +#endif /* __XEN_PUBLIC_IO_KBDIF_H__ */