@@ -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