From patchwork Thu Dec 22 08:12:48 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Oleksandr Andrushchenko X-Patchwork-Id: 9484385 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 75041601C0 for ; Thu, 22 Dec 2016 08:15:58 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 5F407281AA for ; Thu, 22 Dec 2016 08:15:58 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 5247E28305; Thu, 22 Dec 2016 08:15:58 +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 C7516281AA for ; Thu, 22 Dec 2016 08:15:56 +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 1cJyUn-0003WA-Hn; Thu, 22 Dec 2016 08:13:01 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cJyUm-0003Uy-2d; Thu, 22 Dec 2016 08:13:00 +0000 Received: from [193.109.254.147] by server-4.bemta-6.messagelabs.com id 53/E6-25093-B0B8B585; Thu, 22 Dec 2016 08:12:59 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFtrMIsWRWlGSWpSXmKPExsVyMfTSEV2u7ug Ig9f3uSxW9lxktvi+ZTKTA5PH4Q9XWAIYo1gz85LyKxJYM/ZdechW8HgSU8XFeV+ZGhi/HWLs YuTkEBIoknj+6S5rFyMXB4vASxaJ+R9nsoAkJAT6WSV2/C2DsGMk+v/9gorXSPzeNIkFollR4 uuz6UwgzUICK5kktkz8ygySYBMwklh+4wdYkYiAksS9VZPBipgF3jNJ3LnWD7ZaWMBT4uGNdW wgNouAqkTLo71MIDavgJPE9zO7GSG2yUncPNcJNpRTwFniyM19rBCbnSRWvX7GPoFRYAEjwyp GjeLUorLUIl0jI72kosz0jJLcxMwcXUMDM73c1OLixPTUnMSkYr3k/NxNjMBAYwCCHYxr5gce YpTkYFIS5dUojI4Q4kvKT6nMSCzOiC8qzUktPsQow8GhJMH7oRMoJ1iUmp5akZaZAwx5mLQEB 4+SCK9AB1Cat7ggMbc4Mx0idYrRkuPYrMVPmTimPQORuzrXPGUSYsnLz0uVEufdBTJPAKQhoz QPbhwsLi8xykoJ8zICHSjEU5BalJtZgir/ilGcg1FJmHc+yBSezLwSuK2vgA5iAjrIthnsoJJ EhJRUA2P1hdXM6+wV5p+W6rc/Jsvt71j8rSYqVGe/K0cDx2Ib115272szLmmcEkjgqPlx9O58 pzKep5Wzd8ybFvHdec+CyW/f5j6p3x/z+1YY+1r59S//+V45u/rln3jlZMYHPz0L93e4iWXz9 ofPWVrLrKi94sbq+LN3fpzdvVXsfBzrlIZm0z0f42SVWIozEg21mIuKEwFaLks2xgIAAA== X-Env-Sender: andr2000@gmail.com X-Msg-Ref: server-8.tower-27.messagelabs.com!1482394378!68378295!1 X-Originating-IP: [209.85.210.196] 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 40534 invoked from network); 22 Dec 2016 08:12:58 -0000 Received: from mail-wj0-f196.google.com (HELO mail-wj0-f196.google.com) (209.85.210.196) by server-8.tower-27.messagelabs.com with AES128-GCM-SHA256 encrypted SMTP; 22 Dec 2016 08:12:58 -0000 Received: by mail-wj0-f196.google.com with SMTP id ez4so593512wjd.1; Thu, 22 Dec 2016 00:12:58 -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=izVwYlIqWG7f+EVCW8a65mB1We4k9eZ0Yq5RnVyPtHs=; b=HE+rSeL60NPDnAtwuotKexiXqeL77hIC2lqVlJQYQMwqXsJMxlfzi/0YAyH/+u7NG9 fBDmPiwfhNbc8qDMzxXyl8QQ/y85iL1UKnKhsjsoCHHZ0A4n/4ErFfUgqdzA4wHZJhde 1yPnWEQ6ARKMFki8fPaLUidx7MC18MtMuxvoW466Mn2FvyEP8Krs3pWSeCCqm6Klvtcr aC8pAXr072gz5952VFIKJojXUsMCtarCott85wrQUsbpm9cBbwU4VxvAL6wMK2nwfawd bIiLV/IG4cWd4eHm8ocBbwQWnxJxNrfHbtFA9Qipar/0TPKHCjKUpH10+DkyeNL8etdP PDqQ== 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=izVwYlIqWG7f+EVCW8a65mB1We4k9eZ0Yq5RnVyPtHs=; b=CSymfBctDhdQzSEfcw/hW2pp95Or+2i2OCEPIy0cYO7vUlHe+oiqBULfMvKD2uJ782 Pv3a2e3yIOHQWV8mK3unWHa3QtCIqIHYlC6WPvA3iFDmRak88GN84XHx1D/cK5aFTPgF Lqo5esxmu1F5bblPW+J9nbjRcUXgKqY8Bd5qExkSXOcDwaO6SJs/1D1cmwD+YDgzhJlw 5hicZU9WjWkBbLNUeTCzxDNbz+GVN8P6UrCtpthjCHtg5BbD+BE2dZWJkuZx1j1rhJbE DWjY5PBVhWzYW5j2aLLwCtY3b/mLK5q2pTd40ugOiDBVH+qN1ZkDOPDijuBUVAqyWkFB a4Uw== X-Gm-Message-State: AIkVDXIK1Y6nJ0Not8NE3y68HEclU70r87L8XwV98FPY3vq47FN4L1/asJVmQnGdDWKS7A== X-Received: by 10.194.112.170 with SMTP id ir10mr7569581wjb.190.1482394377155; Thu, 22 Dec 2016 00:12:57 -0800 (PST) Received: from a2k-HP-ProDesk-600-G2-SFF.kyiv.epam.com (ll-74.141.223.85.sovam.net.ua. [85.223.141.74]) by smtp.gmail.com with ESMTPSA id o3sm34304946wjx.39.2016.12.22.00.12.55 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 22 Dec 2016 00:12:56 -0800 (PST) From: Oleksandr Andrushchenko To: xen-devel@lists.xenproject.org Date: Thu, 22 Dec 2016 10:12:48 +0200 Message-Id: <1482394368-19391-2-git-send-email-andr2000@gmail.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1482394368-19391-1-git-send-email-andr2000@gmail.com> References: <1482394368-19391-1-git-send-email-andr2000@gmail.com> Cc: embedded-pv-devel@lists.xenproject.org, lars.kurth@citrix.com, sstabellini@kernel.org, vlad.babchuk@gmail.com, ian.jackson@eu.citrix.com, dario.faggioli@citrix.com, tim@xen.org, andrii.anisov@gmail.com, olekstysh@gmail.com, andr2000@gmail.com, al1img@gmail.com, david.vrabel@citrix.com, JBeulich@suse.com, joculator@gmail.com Subject: [Xen-devel] [PATCH v1] displif: add ABI for para-virtual display 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 This is the ABI for the two halves of a para-virtualized display driver. Changes since initial: * DRM changed to DISPL, protocol made generic * major re-work addressing issues raised for sndif Signed-off-by: Oleksandr Andrushchenko Signed-off-by: Oleksandr Grytsov --- xen/include/public/io/displif.h | 730 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 730 insertions(+) create mode 100644 xen/include/public/io/displif.h diff --git a/xen/include/public/io/displif.h b/xen/include/public/io/displif.h new file mode 100644 index 0000000..ea4e42b --- /dev/null +++ b/xen/include/public/io/displif.h @@ -0,0 +1,730 @@ +/****************************************************************************** + * displif.h + * + * Unified display device I/O interface for Xen guest OSes. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to + * deal in the Software without restriction, including without limitation the + * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or + * sell copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + * DEALINGS IN THE SOFTWARE. + * + * Copyright (C) 2016 EPAM Systems Inc. + * + * Authors: Oleksandr Andrushchenko + * Oleksandr Grytsov + */ + +#ifndef __XEN_PUBLIC_IO_DISPLIF_H__ +#define __XEN_PUBLIC_IO_DISPLIF_H__ + +#include "ring.h" +#include "../grant_table.h" + +/****************************************************************************** + * Main features provided by the protocol + ****************************************************************************** + * This protocol aims to provide a unified protocol which fits more + * sophisticated use-cases than a framebuffer device can handle. At the + * moment basic functionality is supported with the intention to extend: + * o multiple dynamically allocated/destroyed framebuffers + * o buffers of arbitrary sizes + * o better configuration options including multiple display support + * + ****************************************************************************** + * Direction of improvements + ****************************************************************************** + * o allow display/connector cloning + * o allow allocating objects other than frambeffers + * o add planes/overlays support + * o support scaling + * o support rotation + */ + +/* + * Front->back notifications: When enqueuing a new request, sending a + * notification can be made conditional on req_event (i.e., the generic + * hold-off mechanism provided by the ring macros). Backends must set + * req_event appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()). + * + * Back->front notifications: When enqueuing a new response, sending a + * notification can be made conditional on rsp_event (i.e., the generic + * hold-off mechanism provided by the ring macros). Frontends must set + * rsp_event appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()). + */ + +/* + * Feature and Parameter Negotiation + * ================================= + * The two halves of a para-virtual display driver utilize nodes within the + * 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 + ***************************************************************************** + * + *-------------------------------- Addressing --------------------------------- + * + * Indices used to address frontends, driver instances, + * devices and connectors. + * + * frontend_id + * Values: + * + * Domain ID of the display frontend. + * + * drv_idx + * Values: + * + * Zero based contiguous index of the virtualized display driver + * instance in this domain. Multiple PV drivers are allowed in the domain + * at the same time. + * + * conn_id + * Values: + * + * Zero based contiguous index of the connector within the card. + * + *------------------------------ Driver settings ------------------------------- + * features + * Values: + * + * XENDISPL_LIST_SEPARATOR separated list of features that frontend + * driver is requested to support. These are not mandatory and may not + * be implemented by the frontend: + * + * be_alloc + * Backend can be a buffer provider/allocator during + * XENDISPL_OP_DBUF_CREATE operation (see below for negotiation). + * + *----------------------------- Connector settings ----------------------------- + * resolution + * Values: x + * + * Width and height for the connector in pixels separated by + * XENDISPL_RESOLUTION_SEPARATOR. For example, + * vdispl/0/connector/0/resolution = "800x600" + * + * + ***************************************************************************** + * Frontend XenBus Nodes + ***************************************************************************** + * + *----------------------- Request Transport Parameters ----------------------- + * + * These are per connector. + * + * ctrl-channel + * Values: + * + * The identifier of the Xen connector's control event channel + * used to signal activity in the ring buffer. + * + * ctrl-ring-ref + * Values: + * + * The Xen grant reference granting permission for the backend to map + * a sole page in a single page sized connector's control ring buffer. + * + * event-channel + * Values: + * + * The identifier of the Xen connector's event channel + * used to signal activity in the ring buffer. + * + * event-ring-ref + * Values: + * + * The Xen grant reference granting permission for the backend to map + * a sole page in a single page sized connector's event ring buffer. + */ + +/* + * STATE DIAGRAMS + * + ***************************************************************************** + * Startup * + ***************************************************************************** + * + * Tool stack creates front and back state nodes with initial state + * XenbusStateInitialising. + * Tool stack creates and sets up frontend display configuration + * nodes per domain. + * + * Front Back + * ================================= ===================================== + * XenbusStateInitialising XenbusStateInitialising + * o Query backend device identification + * data. + * o Open and validate backend device. + * | + * | + * V + * XenbusStateInitWait + * + * o Query frontend configuration + * o Allocate and initialize + * event channels and buffers + * o Publish transport parameters + * that will be in effect during + * this connection. + * | + * | + * V + * XenbusStateInitialised + * + * o Query frontend transport parameters. + * o Connect to the event channels. + * | + * | + * V + * XenbusStateConnected + * + * o Create and initialize OS + * virtual DISPL as per configuration. + * | + * | + * V + * XenbusStateConnected + * + * XenbusStateUnknown + * XenbusStateClosed + * XenbusStateClosing + * o Remove virtual display device + * o Remove event channels + * | + * | + * V + * XenbusStateClosed + * + */ + +/* + * REQUEST CODES. + */ +#define XENDISPL_OP_DBUF_CREATE 0 +#define XENDISPL_OP_DBUF_DESTROY 1 +#define XENDISPL_OP_FB_ATTACH 2 +#define XENDISPL_OP_FB_DETACH 3 +#define XENDISPL_OP_SET_CONFIG 4 +#define XENDISPL_OP_PG_FLIP 5 + +/* + * EVENT CODES. + */ +#define XENDISPL_EVT_PG_FLIP 0 + +/* + * XENSTORE FIELD AND PATH NAME STRINGS, HELPERS. + */ +#define XENDISPL_DRIVER_NAME "vdispl" + +#define XENDISPL_LIST_SEPARATOR ";" +#define XENDISPL_RESOLUTION_SEPARATOR "x" +/* Field names */ +#define XENDISPL_FIELD_FEATURES "features" +#define XENDISPL_FIELD_CTRL_RING_REF "ctrl-ring-ref" +#define XENDISPL_FIELD_CTRL_CHANNEL "ctrl-channel" +#define XENDISPL_FIELD_EVT_RING_REF "event-ring-ref" +#define XENDISPL_FIELD_EVT_CHANNEL "event-channel" +#define XENDISPL_FIELD_RESOLUTION "resolution" + +#define XENDISPL_FEATURE_BE_ALLOC "be_alloc" + +/* + * STATUS RETURN CODES. + */ +/* Operation parameters are invalid */ +#define XENDISPL_RSP_INVAL (-4) +/* Operation cannot be completed because of memory constraints */ +#define XENDISPL_RSP_NOMEM (-3) +/* Operation is not supported */ +#define XENDISPL_RSP_NOTSUPP (-2) +/* Operation failed for some unspecified reason (e. g. -EIO) */ +#define XENDISPL_RSP_ERROR (-1) +/* Operation completed successfully */ +#define XENDISPL_RSP_OKAY 0 + +/* Path entries */ +#define XENDISPL_PATH_CONNECTOR "connector" + +/* + * Assumptions: + * o usage of grant reference 0 as invalid grant reference: + * grant reference 0 is valid, but never exposed to a PV driver, + * because of the fact it is already in use/reserved by the PV console. + * o all references in this document to page sizes must be treated + * as pages of size XEN_PAGE_SIZE (XC_PAGE_SIZE) unless otherwise noted. + * + * Description of the protocol between frontend and backend driver. + * + * The two halves of a Para-virtual display driver communicate with + * each other using a shared page and an event channel. + * Shared page contains a ring with request/response packets. + * + * All reserved fields in the structures below must be 0. + * Display buffers's cookie of value 0 treated as invalid. + * Framebuffer's cookie of value 0 treated as invalid. + * + * All requests/responses, which are not connector specific, must be sent over + * control ring of the connector with index 0. + * + ***************************************************************************** + * Frontend to backend requests + ***************************************************************************** + * + * All request packets have the same length (64 octets) + * All request packets have common header: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | operation | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * id - uint16_t, private guest value, echoed in response + * operation - uint8_t, operation code + * + * + * Request dbuf creation - request creation of a display buffer. + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | _OP_DBUF_CREATE | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | dbuf_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | dbuf_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | width | + * +-----------------+-----------------+-----------------+-----------------+ + * | height | + * +-----------------+-----------------+-----------------+-----------------+ + * | bpp | + * +-----------------+-----------------+-----------------+-----------------+ + * | buffer_sz | + * +-----------------+-----------------+-----------------+-----------------+ + * | flags | + * +-----------------+-----------------+-----------------+-----------------+ + * | gref_directory_start | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * Must be sent over control ring of the connector with index 0. + * + * dbuf_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote display buffer to local in requests + * width - uint32_t, width in pixels + * height - uint32_t, height in pixels + * bpp - uint32_t, bits per pixel + * buffer_sz - uint32_t, buffer size to be allocated in octets + * flags - uint32_t, flags of the operation + * o XENDISPL_DBUF_FLG_REQ_ALLOC - if set, then backend is requested + * to allocate the buffer with the parameters provided in this request. + * Page directory is handled as follows: + * Frontend on request: + * o allocates pages for the directory + * o grants permissions for the pages of the directory + * o sets gref_dir_next_page fields + * Backend on response: + * o grants permissions for the pages of the buffer allocated + * o fills in page directory with grant references + * gref_directory_start - grant_ref_t, a reference to the first shared page + * describing shared buffer references. At least one page exists. If shared + * buffer size exceeds what can be addressed by this single page, then + * reference to the next page must be supplied (see gref_dir_next_page below) + */ + +#define XENDISPL_DBUF_FLG_REQ_ALLOC 0x0001 + +struct xendispl_dbuf_create_req { + uint64_t dbuf_cookie; + uint32_t width; + uint32_t height; + uint32_t bpp; + uint32_t buffer_sz; + uint32_t flags; + grant_ref_t gref_directory_start; +}; + +/* + * Shared page for XENDISPL_OP_DBUF_CREATE buffer descriptor (gref_directory in + * the request) employs a list of pages, describing all pages of the shared + * data buffer: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | gref_dir_next_page | + * +-----------------+-----------------+-----------------+-----------------+ + * | gref[0] | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | gref[i] | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | gref[N-1] | + * +-----------------+-----------------+-----------------+-----------------+ + * + * gref_dir_next_page - grant_ref_t, reference to the next page describing + * page directory. Must be 0 if no more pages in the list. + * gref[i] - grant_ref_t, reference to a shared page of the display buffer + * allocated at XENDISPL_OP_DBUF_CREATE + * + * Number of grant_ref_t entries in the whole page directory is not + * passed, but instead can be calculated as: + * num_grefs_total = (XENDISPL_OP_DBUF_CREATE.buffer_sz + XEN_PAGE_SIZE - 1) / + * XEN_PAGE_SIZE + */ + +struct xendispl_page_directory { + grant_ref_t gref_dir_next_page; + grant_ref_t gref[1]; /* Variable length */ +}; + +/* + * Request dbuf destruction - destroy a previously allocated display buffer: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | _OP_DBUF_DESTROY| reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | dbuf_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | dbuf_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * Must be sent over control ring of the connector with index 0. + * + * dbuf_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote display buffer to local in requests + */ + +struct xendispl_dbuf_destroy_req { + uint64_t dbuf_cookie; +}; + +/* + * Request framebuffer attachment - request attachment of a framebuffer to + * previously created display buffer. + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | _OP_FB_ATTACH | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | dbuf_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | dbuf_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | width | + * +-----------------+-----------------+-----------------+-----------------+ + * | height | + * +-----------------+-----------------+-----------------+-----------------+ + * | pixel_format | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * Must be sent over control ring of the connector with index 0. + * + * dbuf_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote display buffer to local in requests + * fb_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote framebuffer to local in requests + * width - uint32_t, width in pixels + * height - uint32_t, height in pixels + * pixel_format - uint32_t, pixel format of the framebuffer, FOURCC code + */ + +struct xendispl_fb_attach_req { + uint64_t dbuf_cookie; + uint64_t fb_cookie; + uint32_t width; + uint32_t height; + uint32_t pixel_format; +}; + +/* + * Request framebuffer detach - detach a previously + * attached framebuffer from the display buffer in request: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | _OP_FB_DETACH | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * Must be sent over control ring of the connector with index 0. + * + * fb_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote framebuffer to local in requests + */ + +struct xendispl_fb_detach_req { + uint64_t fb_cookie; +}; + +/* + * Request configuration set/reset - request to set or reset + * the configuration/mode of the display: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | _OP_SET_CONFIG | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | x | + * +-----------------+-----------------+-----------------+-----------------+ + * | y | + * +-----------------+-----------------+-----------------+-----------------+ + * | width | + * +-----------------+-----------------+-----------------+-----------------+ + * | height | + * +-----------------+-----------------+-----------------+-----------------+ + * | bpp | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * Pass all zeros to reset, otherwise command is treated as + * configuration set. + * If this is a set configuration request then framebuffer's cookie tells + * the display which framebuffer/dbuf must be shown while enabling display + * (applying configuration). + * + * fb_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote framebuffer to local in requests + * x - uint32_t, starting position in pixels by X axis + * y - uint32_t, starting position in pixels by Y axis + * width - uint32_t, width in pixels + * height - uint32_t, height in pixels + * bpp - uint32_t, bits per pixel + */ + +struct xendispl_set_config_req { + uint64_t fb_cookie; + uint32_t x; + uint32_t y; + uint32_t width; + uint32_t height; + uint32_t bpp; +}; + +/* + * Request page flip - request to flip a page identified by the framebuffer + * cookie: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | _OP_PG_FLIP | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * fb_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote framebuffer to local in requests + */ + +struct xendispl_page_flip_req { + uint64_t fb_cookie; +}; + +/* + * All response packets have the same length (64 octets) + * + * Response for all requests: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | status | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * id - uint16_t, private guest value, echoed from request + * status - int8_t, response status + */ + +/***************************************************************************** + * Backend to frontend events + ***************************************************************************** + * + * All event packets have the same length (64 octets) + * Events are sent via a shared page allocated by the front and propagated by + * event-channel/event-ring-ref XenStore entries + * + * All event packets have common header: + * + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | type | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * id - uint16_t, event id, may be used by front + * type - uint8_t, type of the event + * + * + * Page flip complete event - event from back to front on page flip completed: + * 0 1 2 3 octet + * +-----------------+-----------------+-----------------+-----------------+ + * | id | _EVT_PG_FLIP | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie low 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | fb_cookie high 32-bit | + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| + * +-----------------+-----------------+-----------------+-----------------+ + * | reserved | + * +-----------------+-----------------+-----------------+-----------------+ + * + * fb_cookie - uint64_t, unique to guest domain value used by the backend + * to map remote framebuffer to local in requests + * + */ + +struct xendispl_pg_flip_evt { + uint64_t fb_cookie; +}; + +struct xendispl_req { + uint16_t id; + uint8_t operation; + uint8_t reserved[5]; + union { + struct xendispl_dbuf_create_req dbuf_create; + struct xendispl_dbuf_destroy_req dbuf_destroy; + struct xendispl_fb_attach_req fb_attach; + struct xendispl_fb_detach_req fb_detach; + struct xendispl_set_config_req set_config; + struct xendispl_page_flip_req pg_flip; + uint8_t reserved[56]; + } op; +}; + +struct xendispl_resp { + uint16_t id; + uint8_t operation; + int8_t status; + uint8_t reserved[60]; +}; + +struct xendispl_evt { + uint16_t id; + uint8_t type; + uint8_t reserved[5]; + union { + struct xendispl_pg_flip_evt pg_flip; + uint8_t reserved[56]; + } op; +}; + +DEFINE_RING_TYPES(xen_displif, struct xendispl_req, struct xendispl_resp); + +/****************************************************************************** + * Back to front events + ****************************************************************************** + * In order to deliver asynchronous events from back to front a shared page is + * allocated by front and its grefs propagated to back via XenStore entries + * (event-XXX). + * This page has a common header used by both front and back to synchronize + * access and control event's ring buffer, while back being a producer of the + * events and front being a consumer. The rest of the page after the header + * is used for event packets. + * + * Upon reception of an event(s) front may confirm its reception + * for either each event, group of events or none. + */ + +struct xendispl_event_page { + uint32_t in_cons; + uint32_t in_prod; + uint8_t reserved[60]; +}; + +#define XENDISPL_EVENT_PAGE_SIZE 4096 +#define XENDISPL_IN_RING_OFFS (sizeof(struct xendispl_event_page)) +#define XENDISPL_IN_RING_SIZE (XENDISPL_EVENT_PAGE_SIZE - XENDISPL_IN_RING_OFFS) +#define XENDISPL_IN_RING_LEN (XENDISPL_IN_RING_SIZE / sizeof(struct xendispl_evt)) +#define XENDISPL_IN_RING(page) \ + ((struct xendispl_evt *)((char *)(page) + XENDISPL_IN_RING_OFFS)) +#define XENDISPL_IN_RING_REF(page, idx) \ + (XENDISPL_IN_RING((page))[(idx) % XENDISPL_IN_RING_LEN]) + +#endif /* __XEN_PUBLIC_IO_DISPLIF_H__ */