Re: [PATCH v5] xen/displif: add ABI for para-virtual display

[Oleksandr Andrushchenko <andr2000@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1354 bytes --]

For your convenience, PFA diff between v4..v5

Thank you,
Oleksandr
On 04/05/2017 09:09 AM, Oleksandr Andrushchenko wrote:
> From: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>
>
> This is the ABI for the two halves of a para-virtualized
> display driver.
>
> 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
>
> Note: existing fbif can be used together with displif running at the
> same time, e.g. on Linux one provides framebuffer and another DRM/KMS
>
> Future extensions to the existing protocol may include:
>    o allow display/connector cloning
>    o allow allocating objects other than display buffers
>    o add planes/overlays support
>    o support scaling
>    o support rotation
>
> Thank you,
> Oleksandr Andrushchenko
> Oleksandr Grytsov
>
> Oleksandr Andrushchenko (1):
>    displif: add ABI for para-virtual display
>
>   xen/include/public/io/displif.h | 864 ++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 864 insertions(+)
>   create mode 100644 xen/include/public/io/displif.h
>


[-- Attachment #2: displif-v5.diff --]
[-- Type: text/x-patch, Size: 8193 bytes --]

diff --git a/xen/include/public/io/displif.h b/xen/include/public/io/displif.h
index ac55c4fe8bbe..8a94f1f9b9d0 100644
--- a/xen/include/public/io/displif.h
+++ b/xen/include/public/io/displif.h
@@ -35,6 +35,13 @@
 
 /*
  ******************************************************************************
+ *                           Protocol version
+ ******************************************************************************
+ */
+#define XENDISPL_PROTOCOL_VERSION     "1"
+
+/*
+ ******************************************************************************
  *                  Main features provided by the protocol
  ******************************************************************************
  * This protocol aims to provide a unified protocol which fits more
@@ -111,7 +118,7 @@
  * /local/domain/1/device/vdispl/0/backend = "/local/domain/0/backend/vdispl/1/0"
  * /local/domain/1/device/vdispl/0/state = "4"
  * /local/domain/1/device/vdispl/0/version = "1"
- * /local/domain/1/device/vdispl/0/be_alloc = "1"
+ * /local/domain/1/device/vdispl/0/be-alloc = "1"
  *
  *-------------------------- Connector 0 configuration ------------------------
  *
@@ -172,7 +179,7 @@
  *
  *------------------------- Backend buffer allocation -------------------------
  *
- * be_alloc
+ * be-alloc
  *      Values:         "0", "1"
  *
  *      If value is set to "1", then backend can be a buffer provider/allocator
@@ -205,7 +212,7 @@
  *      Values:         <uint32_t>
  *
  *      The Xen grant reference granting permission for the backend to map
- *      a sole page in a single page sized connector's control ring buffer.
+ *      a sole page of connector's control ring buffer.
  *
  *------------------- Connector Event Transport Parameters --------------------
  *
@@ -222,7 +229,7 @@
  *      Values:         <uint32_t>
  *
  *      The Xen grant reference granting permission for the backend to map
- *      a sole page in a single page sized connector's event ring buffer.
+ *      a sole page of connector's event ring buffer.
  */
 
 /*
@@ -295,7 +302,7 @@
  * then frontend goes into the XenbusStateInitialising state and is ready for
  * new connection with backend. If the virtualized device is still in use and
  * cannot be removed, then frontend goes into the XenbusStateReconfiguring state
- * until either the virtualized device removed or backend initiates a new
+ * until either the virtualized device is removed or backend initiates a new
  * connection. On the virtualized device removal frontend goes into the
  * XenbusStateInitialising state.
  *
@@ -304,7 +311,7 @@
  * and thus cannot provide functionality of the virtualized device anymore.
  * After backend is back to normal the virtualized device may still hold some
  * state: configuration in use, allocated buffers, client application state etc.
- * So, in most cases, this will require frontend to implement complex recovery
+ * In most cases, this will require frontend to implement complex recovery
  * reconnect logic. Instead, by going into XenbusStateReconfiguring state,
  * frontend will make sure no new clients of the virtualized device are
  * accepted, allow existing client(s) to exit gracefully by signaling error
@@ -360,7 +367,7 @@
 #define XENDISPL_FIELD_EVT_RING_REF   "evt-ring-ref"
 #define XENDISPL_FIELD_EVT_CHANNEL    "evt-event-channel"
 #define XENDISPL_FIELD_RESOLUTION     "resolution"
-#define XENDISPL_FIELD_BE_ALLOC       "be_alloc"
+#define XENDISPL_FIELD_BE_ALLOC       "be-alloc"
 
 /*
  ******************************************************************************
@@ -387,8 +394,8 @@
  * 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.
+ * Display buffers's cookie of value 0 is treated as invalid.
+ * Framebuffer's cookie of value 0 is treated as invalid.
  *
  * For all request/response/event packets that use cookies:
  *   dbuf_cookie - uint64_t, unique to guest domain value used by the backend
@@ -399,7 +406,8 @@
  *---------------------------------- Requests ---------------------------------
  *
  * All requests/responses, which are not connector specific, must be sent over
- * control ring of the connector with index 0.
+ * control ring of the connector which has the index value of 0:
+ *   /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
  *
  * All request packets have the same length (64 octets)
  * All request packets have common header:
@@ -442,7 +450,9 @@
  * |                             reserved                              | 64
  * +----------------+----------------+----------------+----------------+
  *
- * Must be sent over control ring of the connector with index 0.
+ * Must be sent over control ring of the connector which has the index
+ * value of 0:
+ *   /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
  * All unused bits in flags field must be set to 0.
  *
  * An attempt to create multiple display buffers with the same dbuf_cookie is
@@ -464,12 +474,13 @@
  *       Frontend on request:
  *         o allocates pages for the directory (gref_directory,
  *           gref_dir_next_page(s)
- *         o grants permissions for the pages of the directory
+ *         o grants permissions for the pages of the directory to the backend
  *         o sets gref_dir_next_page fields
  *       Backend on response:
- *         o grants permissions for the pages of the buffer allocated
+ *         o grants permissions for the pages of the buffer allocated to
+ *           the frontend
  *         o fills in page directory with grant references
- *           (gref[] in struct xendispl_page_directorygref)
+ *           (gref[] in struct xendispl_page_directory)
  * gref_directory - grant_ref_t, a reference to the first shared page
  *   describing shared buffer references. At least one page exists. If shared
  *   buffer size (buffer_sz) exceeds what can be addressed by this single page,
@@ -543,7 +554,9 @@ struct xendispl_page_directory {
  * |                             reserved                              | 64
  * +----------------+----------------+----------------+----------------+
  *
- * Must be sent over control ring of the connector with index 0.
+ * Must be sent over control ring of the connector which has the index
+ * value of 0:
+ *   /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
  */
 
 struct xendispl_dbuf_destroy_req {
@@ -580,7 +593,9 @@ struct xendispl_dbuf_destroy_req {
  * |                             reserved                              | 64
  * +----------------+----------------+----------------+----------------+
  *
- * Must be sent over control ring of the connector with index 0.
+ * Must be sent over control ring of the connector which has the index
+ * value of 0:
+ *   /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
  * Width and height can be smaller, equal or bigger than the connector's
  * resolution.
  *
@@ -621,7 +636,9 @@ struct xendispl_fb_attach_req {
  * |                             reserved                              | 64
  * +----------------+----------------+----------------+----------------+
  *
- * Must be sent over control ring of the connector with index 0.
+ * Must be sent over control ring of the connector which has the index
+ * value of 0:
+ *   /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
  */
 
 struct xendispl_fb_detach_req {
@@ -809,7 +826,7 @@ DEFINE_RING_TYPES(xen_displif, struct xendispl_req, struct xendispl_resp);
  ******************************************************************************
  * In order to deliver asynchronous events from back to front a shared page is
  * allocated by front and its granted reference propagated to back via
- * XenStore entries (event-XXX).
+ * XenStore entries (evt-ring-ref/evt-event-channel).
  * 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

[-- Attachment #3: Type: text/plain, Size: 127 bytes --]

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel