931 lines · c
1/* SPDX-License-Identifier: MIT */2/******************************************************************************3 * displif.h4 *5 * Unified display device I/O interface for Xen guest OSes.6 *7 * Copyright (C) 2016-2017 EPAM Systems Inc.8 *9 * Authors: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>10 * Oleksandr Grytsov <oleksandr_grytsov@epam.com>11 */12 13#ifndef __XEN_PUBLIC_IO_DISPLIF_H__14#define __XEN_PUBLIC_IO_DISPLIF_H__15 16#include "ring.h"17#include "../grant_table.h"18 19/*20 ******************************************************************************21 * Protocol version22 ******************************************************************************23 */24#define XENDISPL_PROTOCOL_VERSION "2"25#define XENDISPL_PROTOCOL_VERSION_INT 226 27/*28 ******************************************************************************29 * Main features provided by the protocol30 ******************************************************************************31 * This protocol aims to provide a unified protocol which fits more32 * sophisticated use-cases than a framebuffer device can handle. At the33 * moment basic functionality is supported with the intention to be extended:34 * o multiple dynamically allocated/destroyed framebuffers35 * o buffers of arbitrary sizes36 * o buffer allocation at either back or front end37 * o better configuration options including multiple display support38 *39 * Note: existing fbif can be used together with displif running at the40 * same time, e.g. on Linux one provides framebuffer and another DRM/KMS41 *42 * Note: display resolution (XenStore's "resolution" property) defines43 * visible area of the virtual display. At the same time resolution of44 * the display and frame buffers may differ: buffers can be smaller, equal45 * or bigger than the visible area. This is to enable use-cases, where backend46 * may do some post-processing of the display and frame buffers supplied,47 * e.g. those buffers can be just a part of the final composition.48 *49 ******************************************************************************50 * Direction of improvements51 ******************************************************************************52 * Future extensions to the existing protocol may include:53 * o display/connector cloning54 * o allocation of objects other than display buffers55 * o plane/overlay support56 * o scaling support57 * o rotation support58 *59 ******************************************************************************60 * Feature and Parameter Negotiation61 ******************************************************************************62 *63 * Front->back notifications: when enqueuing a new request, sending a64 * notification can be made conditional on xendispl_req (i.e., the generic65 * hold-off mechanism provided by the ring macros). Backends must set66 * xendispl_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()).67 *68 * Back->front notifications: when enqueuing a new response, sending a69 * notification can be made conditional on xendispl_resp (i.e., the generic70 * hold-off mechanism provided by the ring macros). Frontends must set71 * xendispl_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()).72 *73 * The two halves of a para-virtual display driver utilize nodes within74 * XenStore to communicate capabilities and to negotiate operating parameters.75 * This section enumerates these nodes which reside in the respective front and76 * backend portions of XenStore, following the XenBus convention.77 *78 * All data in XenStore is stored as strings. Nodes specifying numeric79 * values are encoded in decimal. Integer value ranges listed below are80 * expressed as fixed sized integer types capable of storing the conversion81 * of a properly formated node string, without loss of information.82 *83 ******************************************************************************84 * Example configuration85 ******************************************************************************86 *87 * Note: depending on the use-case backend can expose more display connectors88 * than the underlying HW physically has by employing SW graphics compositors89 *90 * This is an example of backend and frontend configuration:91 *92 *--------------------------------- Backend -----------------------------------93 *94 * /local/domain/0/backend/vdispl/1/0/frontend-id = "1"95 * /local/domain/0/backend/vdispl/1/0/frontend = "/local/domain/1/device/vdispl/0"96 * /local/domain/0/backend/vdispl/1/0/state = "4"97 * /local/domain/0/backend/vdispl/1/0/versions = "1,2"98 *99 *--------------------------------- Frontend ----------------------------------100 *101 * /local/domain/1/device/vdispl/0/backend-id = "0"102 * /local/domain/1/device/vdispl/0/backend = "/local/domain/0/backend/vdispl/1/0"103 * /local/domain/1/device/vdispl/0/state = "4"104 * /local/domain/1/device/vdispl/0/version = "1"105 * /local/domain/1/device/vdispl/0/be-alloc = "1"106 *107 *-------------------------- Connector 0 configuration ------------------------108 *109 * /local/domain/1/device/vdispl/0/0/resolution = "1920x1080"110 * /local/domain/1/device/vdispl/0/0/req-ring-ref = "2832"111 * /local/domain/1/device/vdispl/0/0/req-event-channel = "15"112 * /local/domain/1/device/vdispl/0/0/evt-ring-ref = "387"113 * /local/domain/1/device/vdispl/0/0/evt-event-channel = "16"114 *115 *-------------------------- Connector 1 configuration ------------------------116 *117 * /local/domain/1/device/vdispl/0/1/resolution = "800x600"118 * /local/domain/1/device/vdispl/0/1/req-ring-ref = "2833"119 * /local/domain/1/device/vdispl/0/1/req-event-channel = "17"120 * /local/domain/1/device/vdispl/0/1/evt-ring-ref = "388"121 * /local/domain/1/device/vdispl/0/1/evt-event-channel = "18"122 *123 ******************************************************************************124 * Backend XenBus Nodes125 ******************************************************************************126 *127 *----------------------------- Protocol version ------------------------------128 *129 * versions130 * Values: <string>131 *132 * List of XENDISPL_LIST_SEPARATOR separated protocol versions supported133 * by the backend. For example "1,2,3".134 *135 ******************************************************************************136 * Frontend XenBus Nodes137 ******************************************************************************138 *139 *-------------------------------- Addressing ---------------------------------140 *141 * dom-id142 * Values: <uint16_t>143 *144 * Domain identifier.145 *146 * dev-id147 * Values: <uint16_t>148 *149 * Device identifier.150 *151 * conn-idx152 * Values: <uint8_t>153 *154 * Zero based contigous index of the connector.155 * /local/domain/<dom-id>/device/vdispl/<dev-id>/<conn-idx>/...156 *157 *----------------------------- Protocol version ------------------------------158 *159 * version160 * Values: <string>161 *162 * Protocol version, chosen among the ones supported by the backend.163 *164 *------------------------- Backend buffer allocation -------------------------165 *166 * be-alloc167 * Values: "0", "1"168 *169 * If value is set to "1", then backend can be a buffer provider/allocator170 * for this domain during XENDISPL_OP_DBUF_CREATE operation (see below171 * for negotiation).172 * If value is not "1" or omitted frontend must allocate buffers itself.173 *174 *----------------------------- Connector settings ----------------------------175 *176 * unique-id177 * Values: <string>178 *179 * After device instance initialization each connector is assigned a180 * unique ID, so it can be identified by the backend by this ID.181 * This can be UUID or such.182 *183 * resolution184 * Values: <width, uint32_t>x<height, uint32_t>185 *186 * Width and height of the connector in pixels separated by187 * XENDISPL_RESOLUTION_SEPARATOR. This defines visible area of the188 * display.189 * If backend provides extended display identification data (EDID) with190 * XENDISPL_OP_GET_EDID request then EDID values must take precedence191 * over the resolutions defined here.192 *193 *------------------ Connector Request Transport Parameters -------------------194 *195 * This communication path is used to deliver requests from frontend to backend196 * and get the corresponding responses from backend to frontend,197 * set up per connector.198 *199 * req-event-channel200 * Values: <uint32_t>201 *202 * The identifier of the Xen connector's control event channel203 * used to signal activity in the ring buffer.204 *205 * req-ring-ref206 * Values: <uint32_t>207 *208 * The Xen grant reference granting permission for the backend to map209 * a sole page of connector's control ring buffer.210 *211 *------------------- Connector Event Transport Parameters --------------------212 *213 * This communication path is used to deliver asynchronous events from backend214 * to frontend, set up per connector.215 *216 * evt-event-channel217 * Values: <uint32_t>218 *219 * The identifier of the Xen connector's event channel220 * used to signal activity in the ring buffer.221 *222 * evt-ring-ref223 * Values: <uint32_t>224 *225 * The Xen grant reference granting permission for the backend to map226 * a sole page of connector's event ring buffer.227 */228 229/*230 ******************************************************************************231 * STATE DIAGRAMS232 ******************************************************************************233 *234 * Tool stack creates front and back state nodes with initial state235 * XenbusStateInitialising.236 * Tool stack creates and sets up frontend display configuration237 * nodes per domain.238 *239 *-------------------------------- Normal flow --------------------------------240 *241 * Front Back242 * ================================= =====================================243 * XenbusStateInitialising XenbusStateInitialising244 * o Query backend device identification245 * data.246 * o Open and validate backend device.247 * |248 * |249 * V250 * XenbusStateInitWait251 *252 * o Query frontend configuration253 * o Allocate and initialize254 * event channels per configured255 * connector.256 * o Publish transport parameters257 * that will be in effect during258 * this connection.259 * |260 * |261 * V262 * XenbusStateInitialised263 *264 * o Query frontend transport parameters.265 * o Connect to the event channels.266 * |267 * |268 * V269 * XenbusStateConnected270 *271 * o Create and initialize OS272 * virtual display connectors273 * as per configuration.274 * |275 * |276 * V277 * XenbusStateConnected278 *279 * XenbusStateUnknown280 * XenbusStateClosed281 * XenbusStateClosing282 * o Remove virtual display device283 * o Remove event channels284 * |285 * |286 * V287 * XenbusStateClosed288 *289 *------------------------------- Recovery flow -------------------------------290 *291 * In case of frontend unrecoverable errors backend handles that as292 * if frontend goes into the XenbusStateClosed state.293 *294 * In case of backend unrecoverable errors frontend tries removing295 * the virtualized device. If this is possible at the moment of error,296 * then frontend goes into the XenbusStateInitialising state and is ready for297 * new connection with backend. If the virtualized device is still in use and298 * cannot be removed, then frontend goes into the XenbusStateReconfiguring state299 * until either the virtualized device is removed or backend initiates a new300 * connection. On the virtualized device removal frontend goes into the301 * XenbusStateInitialising state.302 *303 * Note on XenbusStateReconfiguring state of the frontend: if backend has304 * unrecoverable errors then frontend cannot send requests to the backend305 * and thus cannot provide functionality of the virtualized device anymore.306 * After backend is back to normal the virtualized device may still hold some307 * state: configuration in use, allocated buffers, client application state etc.308 * In most cases, this will require frontend to implement complex recovery309 * reconnect logic. Instead, by going into XenbusStateReconfiguring state,310 * frontend will make sure no new clients of the virtualized device are311 * accepted, allow existing client(s) to exit gracefully by signaling error312 * state etc.313 * Once all the clients are gone frontend can reinitialize the virtualized314 * device and get into XenbusStateInitialising state again signaling the315 * backend that a new connection can be made.316 *317 * There are multiple conditions possible under which frontend will go from318 * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS319 * specific. For example:320 * 1. The underlying OS framework may provide callbacks to signal that the last321 * client of the virtualized device has gone and the device can be removed322 * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue)323 * to periodically check if this is the right time to re-try removal of324 * the virtualized device.325 * 3. By any other means.326 *327 ******************************************************************************328 * REQUEST CODES329 ******************************************************************************330 * Request codes [0; 15] are reserved and must not be used331 */332 333#define XENDISPL_OP_DBUF_CREATE 0x10334#define XENDISPL_OP_DBUF_DESTROY 0x11335#define XENDISPL_OP_FB_ATTACH 0x12336#define XENDISPL_OP_FB_DETACH 0x13337#define XENDISPL_OP_SET_CONFIG 0x14338#define XENDISPL_OP_PG_FLIP 0x15339/* The below command is available in protocol version 2 and above. */340#define XENDISPL_OP_GET_EDID 0x16341 342/*343 ******************************************************************************344 * EVENT CODES345 ******************************************************************************346 */347#define XENDISPL_EVT_PG_FLIP 0x00348 349/*350 ******************************************************************************351 * XENSTORE FIELD AND PATH NAME STRINGS, HELPERS352 ******************************************************************************353 */354#define XENDISPL_DRIVER_NAME "vdispl"355 356#define XENDISPL_LIST_SEPARATOR ","357#define XENDISPL_RESOLUTION_SEPARATOR "x"358 359#define XENDISPL_FIELD_BE_VERSIONS "versions"360#define XENDISPL_FIELD_FE_VERSION "version"361#define XENDISPL_FIELD_REQ_RING_REF "req-ring-ref"362#define XENDISPL_FIELD_REQ_CHANNEL "req-event-channel"363#define XENDISPL_FIELD_EVT_RING_REF "evt-ring-ref"364#define XENDISPL_FIELD_EVT_CHANNEL "evt-event-channel"365#define XENDISPL_FIELD_RESOLUTION "resolution"366#define XENDISPL_FIELD_BE_ALLOC "be-alloc"367#define XENDISPL_FIELD_UNIQUE_ID "unique-id"368 369#define XENDISPL_EDID_BLOCK_SIZE 128370#define XENDISPL_EDID_BLOCK_COUNT 256371#define XENDISPL_EDID_MAX_SIZE (XENDISPL_EDID_BLOCK_SIZE * XENDISPL_EDID_BLOCK_COUNT)372 373/*374 ******************************************************************************375 * STATUS RETURN CODES376 ******************************************************************************377 *378 * Status return code is zero on success and -XEN_EXX on failure.379 *380 ******************************************************************************381 * Assumptions382 ******************************************************************************383 * o usage of grant reference 0 as invalid grant reference:384 * grant reference 0 is valid, but never exposed to a PV driver,385 * because of the fact it is already in use/reserved by the PV console.386 * o all references in this document to page sizes must be treated387 * as pages of size XEN_PAGE_SIZE unless otherwise noted.388 *389 ******************************************************************************390 * Description of the protocol between frontend and backend driver391 ******************************************************************************392 *393 * The two halves of a Para-virtual display driver communicate with394 * each other using shared pages and event channels.395 * Shared page contains a ring with request/response packets.396 *397 * All reserved fields in the structures below must be 0.398 * Display buffers's cookie of value 0 is treated as invalid.399 * Framebuffer's cookie of value 0 is treated as invalid.400 *401 * For all request/response/event packets that use cookies:402 * dbuf_cookie - uint64_t, unique to guest domain value used by the backend403 * to map remote display buffer to its local one404 * fb_cookie - uint64_t, unique to guest domain value used by the backend405 * to map remote framebuffer to its local one406 *407 *---------------------------------- Requests ---------------------------------408 *409 * All requests/responses, which are not connector specific, must be sent over410 * control ring of the connector which has the index value of 0:411 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref412 *413 * All request packets have the same length (64 octets)414 * All request packets have common header:415 * 0 1 2 3 octet416 * +----------------+----------------+----------------+----------------+417 * | id | operation | reserved | 4418 * +----------------+----------------+----------------+----------------+419 * | reserved | 8420 * +----------------+----------------+----------------+----------------+421 * id - uint16_t, private guest value, echoed in response422 * operation - uint8_t, operation code, XENDISPL_OP_???423 *424 * Request dbuf creation - request creation of a display buffer.425 * 0 1 2 3 octet426 * +----------------+----------------+----------------+----------------+427 * | id |_OP_DBUF_CREATE | reserved | 4428 * +----------------+----------------+----------------+----------------+429 * | reserved | 8430 * +----------------+----------------+----------------+----------------+431 * | dbuf_cookie low 32-bit | 12432 * +----------------+----------------+----------------+----------------+433 * | dbuf_cookie high 32-bit | 16434 * +----------------+----------------+----------------+----------------+435 * | width | 20436 * +----------------+----------------+----------------+----------------+437 * | height | 24438 * +----------------+----------------+----------------+----------------+439 * | bpp | 28440 * +----------------+----------------+----------------+----------------+441 * | buffer_sz | 32442 * +----------------+----------------+----------------+----------------+443 * | flags | 36444 * +----------------+----------------+----------------+----------------+445 * | gref_directory | 40446 * +----------------+----------------+----------------+----------------+447 * | data_ofs | 44448 * +----------------+----------------+----------------+----------------+449 * | reserved | 48450 * +----------------+----------------+----------------+----------------+451 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|452 * +----------------+----------------+----------------+----------------+453 * | reserved | 64454 * +----------------+----------------+----------------+----------------+455 *456 * Must be sent over control ring of the connector which has the index457 * value of 0:458 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref459 * All unused bits in flags field must be set to 0.460 *461 * An attempt to create multiple display buffers with the same dbuf_cookie is462 * an error. dbuf_cookie can be re-used after destroying the corresponding463 * display buffer.464 *465 * Width and height of the display buffers can be smaller, equal or bigger466 * than the connector's resolution. Depth/pixel format of the individual467 * buffers can differ as well.468 *469 * width - uint32_t, width in pixels470 * height - uint32_t, height in pixels471 * bpp - uint32_t, bits per pixel472 * buffer_sz - uint32_t, buffer size to be allocated, octets473 * flags - uint32_t, flags of the operation474 * o XENDISPL_DBUF_FLG_REQ_ALLOC - if set, then backend is requested475 * to allocate the buffer with the parameters provided in this request.476 * Page directory is handled as follows:477 * Frontend on request:478 * o allocates pages for the directory (gref_directory,479 * gref_dir_next_page(s)480 * o grants permissions for the pages of the directory to the backend481 * o sets gref_dir_next_page fields482 * Backend on response:483 * o grants permissions for the pages of the buffer allocated to484 * the frontend485 * o fills in page directory with grant references486 * (gref[] in struct xendispl_page_directory)487 * gref_directory - grant_ref_t, a reference to the first shared page488 * describing shared buffer references. At least one page exists. If shared489 * buffer size (buffer_sz) exceeds what can be addressed by this single page,490 * then reference to the next page must be supplied (see gref_dir_next_page491 * below)492 * data_ofs - uint32_t, offset of the data in the buffer, octets493 */494 495#define XENDISPL_DBUF_FLG_REQ_ALLOC (1 << 0)496 497struct xendispl_dbuf_create_req {498 uint64_t dbuf_cookie;499 uint32_t width;500 uint32_t height;501 uint32_t bpp;502 uint32_t buffer_sz;503 uint32_t flags;504 grant_ref_t gref_directory;505 uint32_t data_ofs;506};507 508/*509 * Shared page for XENDISPL_OP_DBUF_CREATE buffer descriptor (gref_directory in510 * the request) employs a list of pages, describing all pages of the shared511 * data buffer:512 * 0 1 2 3 octet513 * +----------------+----------------+----------------+----------------+514 * | gref_dir_next_page | 4515 * +----------------+----------------+----------------+----------------+516 * | gref[0] | 8517 * +----------------+----------------+----------------+----------------+518 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|519 * +----------------+----------------+----------------+----------------+520 * | gref[i] | i*4+8521 * +----------------+----------------+----------------+----------------+522 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|523 * +----------------+----------------+----------------+----------------+524 * | gref[N - 1] | N*4+8525 * +----------------+----------------+----------------+----------------+526 *527 * gref_dir_next_page - grant_ref_t, reference to the next page describing528 * page directory. Must be 0 if there are no more pages in the list.529 * gref[i] - grant_ref_t, reference to a shared page of the buffer530 * allocated at XENDISPL_OP_DBUF_CREATE531 *532 * Number of grant_ref_t entries in the whole page directory is not533 * passed, but instead can be calculated as:534 * num_grefs_total = (XENDISPL_OP_DBUF_CREATE.buffer_sz + XEN_PAGE_SIZE - 1) /535 * XEN_PAGE_SIZE536 */537 538struct xendispl_page_directory {539 grant_ref_t gref_dir_next_page;540 grant_ref_t gref[];541};542 543/*544 * Request dbuf destruction - destroy a previously allocated display buffer:545 * 0 1 2 3 octet546 * +----------------+----------------+----------------+----------------+547 * | id |_OP_DBUF_DESTROY| reserved | 4548 * +----------------+----------------+----------------+----------------+549 * | reserved | 8550 * +----------------+----------------+----------------+----------------+551 * | dbuf_cookie low 32-bit | 12552 * +----------------+----------------+----------------+----------------+553 * | dbuf_cookie high 32-bit | 16554 * +----------------+----------------+----------------+----------------+555 * | reserved | 20556 * +----------------+----------------+----------------+----------------+557 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|558 * +----------------+----------------+----------------+----------------+559 * | reserved | 64560 * +----------------+----------------+----------------+----------------+561 *562 * Must be sent over control ring of the connector which has the index563 * value of 0:564 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref565 */566 567struct xendispl_dbuf_destroy_req {568 uint64_t dbuf_cookie;569};570 571/*572 * Request framebuffer attachment - request attachment of a framebuffer to573 * previously created display buffer.574 * 0 1 2 3 octet575 * +----------------+----------------+----------------+----------------+576 * | id | _OP_FB_ATTACH | reserved | 4577 * +----------------+----------------+----------------+----------------+578 * | reserved | 8579 * +----------------+----------------+----------------+----------------+580 * | dbuf_cookie low 32-bit | 12581 * +----------------+----------------+----------------+----------------+582 * | dbuf_cookie high 32-bit | 16583 * +----------------+----------------+----------------+----------------+584 * | fb_cookie low 32-bit | 20585 * +----------------+----------------+----------------+----------------+586 * | fb_cookie high 32-bit | 24587 * +----------------+----------------+----------------+----------------+588 * | width | 28589 * +----------------+----------------+----------------+----------------+590 * | height | 32591 * +----------------+----------------+----------------+----------------+592 * | pixel_format | 36593 * +----------------+----------------+----------------+----------------+594 * | reserved | 40595 * +----------------+----------------+----------------+----------------+596 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|597 * +----------------+----------------+----------------+----------------+598 * | reserved | 64599 * +----------------+----------------+----------------+----------------+600 *601 * Must be sent over control ring of the connector which has the index602 * value of 0:603 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref604 * Width and height can be smaller, equal or bigger than the connector's605 * resolution.606 *607 * An attempt to create multiple frame buffers with the same fb_cookie is608 * an error. fb_cookie can be re-used after destroying the corresponding609 * frame buffer.610 *611 * width - uint32_t, width in pixels612 * height - uint32_t, height in pixels613 * pixel_format - uint32_t, pixel format of the framebuffer, FOURCC code614 */615 616struct xendispl_fb_attach_req {617 uint64_t dbuf_cookie;618 uint64_t fb_cookie;619 uint32_t width;620 uint32_t height;621 uint32_t pixel_format;622};623 624/*625 * Request framebuffer detach - detach a previously626 * attached framebuffer from the display buffer in request:627 * 0 1 2 3 octet628 * +----------------+----------------+----------------+----------------+629 * | id | _OP_FB_DETACH | reserved | 4630 * +----------------+----------------+----------------+----------------+631 * | reserved | 8632 * +----------------+----------------+----------------+----------------+633 * | fb_cookie low 32-bit | 12634 * +----------------+----------------+----------------+----------------+635 * | fb_cookie high 32-bit | 16636 * +----------------+----------------+----------------+----------------+637 * | reserved | 20638 * +----------------+----------------+----------------+----------------+639 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|640 * +----------------+----------------+----------------+----------------+641 * | reserved | 64642 * +----------------+----------------+----------------+----------------+643 *644 * Must be sent over control ring of the connector which has the index645 * value of 0:646 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref647 */648 649struct xendispl_fb_detach_req {650 uint64_t fb_cookie;651};652 653/*654 * Request configuration set/reset - request to set or reset655 * the configuration/mode of the display:656 * 0 1 2 3 octet657 * +----------------+----------------+----------------+----------------+658 * | id | _OP_SET_CONFIG | reserved | 4659 * +----------------+----------------+----------------+----------------+660 * | reserved | 8661 * +----------------+----------------+----------------+----------------+662 * | fb_cookie low 32-bit | 12663 * +----------------+----------------+----------------+----------------+664 * | fb_cookie high 32-bit | 16665 * +----------------+----------------+----------------+----------------+666 * | x | 20667 * +----------------+----------------+----------------+----------------+668 * | y | 24669 * +----------------+----------------+----------------+----------------+670 * | width | 28671 * +----------------+----------------+----------------+----------------+672 * | height | 32673 * +----------------+----------------+----------------+----------------+674 * | bpp | 40675 * +----------------+----------------+----------------+----------------+676 * | reserved | 44677 * +----------------+----------------+----------------+----------------+678 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|679 * +----------------+----------------+----------------+----------------+680 * | reserved | 64681 * +----------------+----------------+----------------+----------------+682 *683 * Pass all zeros to reset, otherwise command is treated as684 * configuration set.685 * Framebuffer's cookie defines which framebuffer/dbuf must be686 * displayed while enabling display (applying configuration).687 * x, y, width and height are bound by the connector's resolution and must not688 * exceed it.689 *690 * x - uint32_t, starting position in pixels by X axis691 * y - uint32_t, starting position in pixels by Y axis692 * width - uint32_t, width in pixels693 * height - uint32_t, height in pixels694 * bpp - uint32_t, bits per pixel695 */696 697struct xendispl_set_config_req {698 uint64_t fb_cookie;699 uint32_t x;700 uint32_t y;701 uint32_t width;702 uint32_t height;703 uint32_t bpp;704};705 706/*707 * Request page flip - request to flip a page identified by the framebuffer708 * cookie:709 * 0 1 2 3 octet710 * +----------------+----------------+----------------+----------------+711 * | id | _OP_PG_FLIP | reserved | 4712 * +----------------+----------------+----------------+----------------+713 * | reserved | 8714 * +----------------+----------------+----------------+----------------+715 * | fb_cookie low 32-bit | 12716 * +----------------+----------------+----------------+----------------+717 * | fb_cookie high 32-bit | 16718 * +----------------+----------------+----------------+----------------+719 * | reserved | 20720 * +----------------+----------------+----------------+----------------+721 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|722 * +----------------+----------------+----------------+----------------+723 * | reserved | 64724 * +----------------+----------------+----------------+----------------+725 */726 727struct xendispl_page_flip_req {728 uint64_t fb_cookie;729};730 731/*732 * Request EDID - request EDID describing current connector:733 * 0 1 2 3 octet734 * +----------------+----------------+----------------+----------------+735 * | id | _OP_GET_EDID | reserved | 4736 * +----------------+----------------+----------------+----------------+737 * | buffer_sz | 8738 * +----------------+----------------+----------------+----------------+739 * | gref_directory | 12740 * +----------------+----------------+----------------+----------------+741 * | reserved | 16742 * +----------------+----------------+----------------+----------------+743 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|744 * +----------------+----------------+----------------+----------------+745 * | reserved | 64746 * +----------------+----------------+----------------+----------------+747 *748 * Notes:749 * - This command is not available in protocol version 1 and should be750 * ignored.751 * - This request is optional and if not supported then visible area752 * is defined by the relevant XenStore's "resolution" property.753 * - Shared buffer, allocated for EDID storage, must not be less then754 * XENDISPL_EDID_MAX_SIZE octets.755 *756 * buffer_sz - uint32_t, buffer size to be allocated, octets757 * gref_directory - grant_ref_t, a reference to the first shared page758 * describing EDID buffer references. See XENDISPL_OP_DBUF_CREATE for759 * grant page directory structure (struct xendispl_page_directory).760 *761 * See response format for this request.762 */763 764struct xendispl_get_edid_req {765 uint32_t buffer_sz;766 grant_ref_t gref_directory;767};768 769/*770 *---------------------------------- Responses --------------------------------771 *772 * All response packets have the same length (64 octets)773 *774 * All response packets have common header:775 * 0 1 2 3 octet776 * +----------------+----------------+----------------+----------------+777 * | id | reserved | 4778 * +----------------+----------------+----------------+----------------+779 * | status | 8780 * +----------------+----------------+----------------+----------------+781 * | reserved | 12782 * +----------------+----------------+----------------+----------------+783 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|784 * +----------------+----------------+----------------+----------------+785 * | reserved | 64786 * +----------------+----------------+----------------+----------------+787 *788 * id - uint16_t, private guest value, echoed from request789 * status - int32_t, response status, zero on success and -XEN_EXX on failure790 *791 *792 * Get EDID response - response for XENDISPL_OP_GET_EDID:793 * 0 1 2 3 octet794 * +----------------+----------------+----------------+----------------+795 * | id | operation | reserved | 4796 * +----------------+----------------+----------------+----------------+797 * | status | 8798 * +----------------+----------------+----------------+----------------+799 * | edid_sz | 12800 * +----------------+----------------+----------------+----------------+801 * | reserved | 16802 * +----------------+----------------+----------------+----------------+803 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|804 * +----------------+----------------+----------------+----------------+805 * | reserved | 64806 * +----------------+----------------+----------------+----------------+807 *808 * Notes:809 * - This response is not available in protocol version 1 and should be810 * ignored.811 *812 * edid_sz - uint32_t, size of the EDID, octets813 */814 815struct xendispl_get_edid_resp {816 uint32_t edid_sz;817};818 819/*820 *----------------------------------- Events ----------------------------------821 *822 * Events are sent via a shared page allocated by the front and propagated by823 * evt-event-channel/evt-ring-ref XenStore entries824 * All event packets have the same length (64 octets)825 * All event packets have common header:826 * 0 1 2 3 octet827 * +----------------+----------------+----------------+----------------+828 * | id | type | reserved | 4829 * +----------------+----------------+----------------+----------------+830 * | reserved | 8831 * +----------------+----------------+----------------+----------------+832 *833 * id - uint16_t, event id, may be used by front834 * type - uint8_t, type of the event835 *836 *837 * Page flip complete event - event from back to front on page flip completed:838 * 0 1 2 3 octet839 * +----------------+----------------+----------------+----------------+840 * | id | _EVT_PG_FLIP | reserved | 4841 * +----------------+----------------+----------------+----------------+842 * | reserved | 8843 * +----------------+----------------+----------------+----------------+844 * | fb_cookie low 32-bit | 12845 * +----------------+----------------+----------------+----------------+846 * | fb_cookie high 32-bit | 16847 * +----------------+----------------+----------------+----------------+848 * | reserved | 20849 * +----------------+----------------+----------------+----------------+850 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|851 * +----------------+----------------+----------------+----------------+852 * | reserved | 64853 * +----------------+----------------+----------------+----------------+854 */855 856struct xendispl_pg_flip_evt {857 uint64_t fb_cookie;858};859 860struct xendispl_req {861 uint16_t id;862 uint8_t operation;863 uint8_t reserved[5];864 union {865 struct xendispl_dbuf_create_req dbuf_create;866 struct xendispl_dbuf_destroy_req dbuf_destroy;867 struct xendispl_fb_attach_req fb_attach;868 struct xendispl_fb_detach_req fb_detach;869 struct xendispl_set_config_req set_config;870 struct xendispl_page_flip_req pg_flip;871 struct xendispl_get_edid_req get_edid;872 uint8_t reserved[56];873 } op;874};875 876struct xendispl_resp {877 uint16_t id;878 uint8_t operation;879 uint8_t reserved;880 int32_t status;881 union {882 struct xendispl_get_edid_resp get_edid;883 uint8_t reserved1[56];884 } op;885};886 887struct xendispl_evt {888 uint16_t id;889 uint8_t type;890 uint8_t reserved[5];891 union {892 struct xendispl_pg_flip_evt pg_flip;893 uint8_t reserved[56];894 } op;895};896 897DEFINE_RING_TYPES(xen_displif, struct xendispl_req, struct xendispl_resp);898 899/*900 ******************************************************************************901 * Back to front events delivery902 ******************************************************************************903 * In order to deliver asynchronous events from back to front a shared page is904 * allocated by front and its granted reference propagated to back via905 * XenStore entries (evt-ring-ref/evt-event-channel).906 * This page has a common header used by both front and back to synchronize907 * access and control event's ring buffer, while back being a producer of the908 * events and front being a consumer. The rest of the page after the header909 * is used for event packets.910 *911 * Upon reception of an event(s) front may confirm its reception912 * for either each event, group of events or none.913 */914 915struct xendispl_event_page {916 uint32_t in_cons;917 uint32_t in_prod;918 uint8_t reserved[56];919};920 921#define XENDISPL_EVENT_PAGE_SIZE XEN_PAGE_SIZE922#define XENDISPL_IN_RING_OFFS (sizeof(struct xendispl_event_page))923#define XENDISPL_IN_RING_SIZE (XENDISPL_EVENT_PAGE_SIZE - XENDISPL_IN_RING_OFFS)924#define XENDISPL_IN_RING_LEN (XENDISPL_IN_RING_SIZE / sizeof(struct xendispl_evt))925#define XENDISPL_IN_RING(page) \926 ((struct xendispl_evt *)((char *)(page) + XENDISPL_IN_RING_OFFS))927#define XENDISPL_IN_RING_REF(page, idx) \928 (XENDISPL_IN_RING((page))[(idx) % XENDISPL_IN_RING_LEN])929 930#endif /* __XEN_PUBLIC_IO_DISPLIF_H__ */931