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: * * 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: * * 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//device/vdispl//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//device/vdispl//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//device/vdispl//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//device/vdispl//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//device/vdispl//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