Lines Matching +full:display +full:- +full:backend
4 * Unified display device I/O interface for Xen guest OSes.
24 * Copyright (C) 2016-2017 EPAM Systems Inc.
49 * sophisticated use-cases than a framebuffer device can handle. At the
54 * o better configuration options including multiple display support
59 * Note: display resolution (XenStore's "resolution" property) defines
60 * visible area of the virtual display. At the same time resolution of
61 * the display and frame buffers may differ: buffers can be smaller, equal
62 * or bigger than the visible area. This is to enable use-cases, where backend
63 * may do some post-processing of the display and frame buffers supplied,
70 * o display/connector cloning
71 * o allocation of objects other than display buffers
80 * Front->back notifications: when enqueuing a new request, sending a
82 * hold-off mechanism provided by the ring macros). Backends must set
85 * Back->front notifications: when enqueuing a new response, sending a
87 * hold-off mechanism provided by the ring macros). Frontends must set
90 * The two halves of a para-virtual display driver utilize nodes within
93 * backend portions of XenStore, following the XenBus convention.
104 * Note: depending on the use-case backend can expose more display connectors
107 * This is an example of backend and frontend configuration:
109 *--------------------------------- Backend -----------------------------------
111 * /local/domain/0/backend/vdispl/1/0/frontend-id = "1"
112 * /local/domain/0/backend/vdispl/1/0/frontend = "/local/domain/1/device/vdispl/0"
113 * /local/domain/0/backend/vdispl/1/0/state = "4"
114 * /local/domain/0/backend/vdispl/1/0/versions = "1,2"
116 *--------------------------------- Frontend ----------------------------------
118 * /local/domain/1/device/vdispl/0/backend-id = "0"
119 * /local/domain/1/device/vdispl/0/backend = "/local/domain/0/backend/vdispl/1/0"
122 * /local/domain/1/device/vdispl/0/be-alloc = "1"
124 *-------------------------- Connector 0 configuration ------------------------
127 * /local/domain/1/device/vdispl/0/0/req-ring-ref = "2832"
128 * /local/domain/1/device/vdispl/0/0/req-event-channel = "15"
129 * /local/domain/1/device/vdispl/0/0/evt-ring-ref = "387"
130 * /local/domain/1/device/vdispl/0/0/evt-event-channel = "16"
132 *-------------------------- Connector 1 configuration ------------------------
135 * /local/domain/1/device/vdispl/0/1/req-ring-ref = "2833"
136 * /local/domain/1/device/vdispl/0/1/req-event-channel = "17"
137 * /local/domain/1/device/vdispl/0/1/evt-ring-ref = "388"
138 * /local/domain/1/device/vdispl/0/1/evt-event-channel = "18"
141 * Backend XenBus Nodes
144 *----------------------------- Protocol version ------------------------------
150 * by the backend. For example "1,2,3".
156 *-------------------------------- Addressing ---------------------------------
158 * dom-id
163 * dev-id
168 * conn-idx
172 * /local/domain/<dom-id>/device/vdispl/<dev-id>/<conn-idx>/...
174 *----------------------------- Protocol version ------------------------------
179 * Protocol version, chosen among the ones supported by the backend.
181 *------------------------- Backend buffer allocation -------------------------
183 * be-alloc
186 * If value is set to "1", then backend can be a buffer provider/allocator
191 *----------------------------- Connector settings ----------------------------
193 * unique-id
197 * unique ID, so it can be identified by the backend by this ID.
205 * display.
206 * If backend provides extended display identification data (EDID) with
210 *------------------ Connector Request Transport Parameters -------------------
212 * This communication path is used to deliver requests from frontend to backend
213 * and get the corresponding responses from backend to frontend,
216 * req-event-channel
222 * req-ring-ref
225 * The Xen grant reference granting permission for the backend to map
228 *------------------- Connector Event Transport Parameters --------------------
230 * This communication path is used to deliver asynchronous events from backend
233 * evt-event-channel
239 * evt-ring-ref
242 * The Xen grant reference granting permission for the backend to map
253 * Tool stack creates and sets up frontend display configuration
256 *-------------------------------- Normal flow --------------------------------
261 * o Query backend device identification
263 * o Open and validate backend device.
289 * virtual display connectors
299 * o Remove virtual display device
306 *------------------------------- Recovery flow -------------------------------
308 * In case of frontend unrecoverable errors backend handles that as
311 * In case of backend unrecoverable errors frontend tries removing
314 * new connection with backend. If the virtualized device is still in use and
316 * until either the virtualized device is removed or backend initiates a new
320 * Note on XenbusStateReconfiguring state of the frontend: if backend has
321 * unrecoverable errors then frontend cannot send requests to the backend
323 * After backend is back to normal the virtualized device may still hold some
332 * backend that a new connection can be made.
340 * to periodically check if this is the right time to re-try removal of
378 #define XENDISPL_FIELD_REQ_RING_REF "req-ring-ref"
379 #define XENDISPL_FIELD_REQ_CHANNEL "req-event-channel"
380 #define XENDISPL_FIELD_EVT_RING_REF "evt-ring-ref"
381 #define XENDISPL_FIELD_EVT_CHANNEL "evt-event-channel"
383 #define XENDISPL_FIELD_BE_ALLOC "be-alloc"
384 #define XENDISPL_FIELD_UNIQUE_ID "unique-id"
395 * Status return code is zero on success and -XEN_EXX on failure.
407 * Description of the protocol between frontend and backend driver
410 * The two halves of a Para-virtual display driver communicate with
415 * Display buffers's cookie of value 0 is treated as invalid.
419 * dbuf_cookie - uint64_t, unique to guest domain value used by the backend
420 * to map remote display buffer to its local one
421 * fb_cookie - uint64_t, unique to guest domain value used by the backend
424 *---------------------------------- Requests ---------------------------------
428 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
433 * +----------------+----------------+----------------+----------------+
435 * +----------------+----------------+----------------+----------------+
437 * +----------------+----------------+----------------+----------------+
438 * id - uint16_t, private guest value, echoed in response
439 * operation - uint8_t, operation code, XENDISPL_OP_???
441 * Request dbuf creation - request creation of a display buffer.
443 * +----------------+----------------+----------------+----------------+
445 * +----------------+----------------+----------------+----------------+
447 * +----------------+----------------+----------------+----------------+
448 * | dbuf_cookie low 32-bit | 12
449 * +----------------+----------------+----------------+----------------+
450 * | dbuf_cookie high 32-bit | 16
451 * +----------------+----------------+----------------+----------------+
453 * +----------------+----------------+----------------+----------------+
455 * +----------------+----------------+----------------+----------------+
457 * +----------------+----------------+----------------+----------------+
459 * +----------------+----------------+----------------+----------------+
461 * +----------------+----------------+----------------+----------------+
463 * +----------------+----------------+----------------+----------------+
465 * +----------------+----------------+----------------+----------------+
467 * +----------------+----------------+----------------+----------------+
469 * +----------------+----------------+----------------+----------------+
471 * +----------------+----------------+----------------+----------------+
475 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
478 * An attempt to create multiple display buffers with the same dbuf_cookie is
479 * an error. dbuf_cookie can be re-used after destroying the corresponding
480 * display buffer.
482 * Width and height of the display buffers can be smaller, equal or bigger
486 * width - uint32_t, width in pixels
487 * height - uint32_t, height in pixels
488 * bpp - uint32_t, bits per pixel
489 * buffer_sz - uint32_t, buffer size to be allocated, octets
490 * flags - uint32_t, flags of the operation
491 * o XENDISPL_DBUF_FLG_REQ_ALLOC - if set, then backend is requested
497 * o grants permissions for the pages of the directory to the backend
499 * Backend on response:
504 * gref_directory - grant_ref_t, a reference to the first shared page
509 * data_ofs - uint32_t, offset of the data in the buffer, octets
530 * +----------------+----------------+----------------+----------------+
532 * +----------------+----------------+----------------+----------------+
534 * +----------------+----------------+----------------+----------------+
536 * +----------------+----------------+----------------+----------------+
538 * +----------------+----------------+----------------+----------------+
540 * +----------------+----------------+----------------+----------------+
541 * | gref[N - 1] | N*4+8
542 * +----------------+----------------+----------------+----------------+
544 * gref_dir_next_page - grant_ref_t, reference to the next page describing
546 * gref[i] - grant_ref_t, reference to a shared page of the buffer
551 * num_grefs_total = (XENDISPL_OP_DBUF_CREATE.buffer_sz + XEN_PAGE_SIZE - 1) /
561 * Request dbuf destruction - destroy a previously allocated display buffer:
563 * +----------------+----------------+----------------+----------------+
565 * +----------------+----------------+----------------+----------------+
567 * +----------------+----------------+----------------+----------------+
568 * | dbuf_cookie low 32-bit | 12
569 * +----------------+----------------+----------------+----------------+
570 * | dbuf_cookie high 32-bit | 16
571 * +----------------+----------------+----------------+----------------+
573 * +----------------+----------------+----------------+----------------+
575 * +----------------+----------------+----------------+----------------+
577 * +----------------+----------------+----------------+----------------+
581 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
589 * Request framebuffer attachment - request attachment of a framebuffer to
590 * previously created display buffer.
592 * +----------------+----------------+----------------+----------------+
594 * +----------------+----------------+----------------+----------------+
596 * +----------------+----------------+----------------+----------------+
597 * | dbuf_cookie low 32-bit | 12
598 * +----------------+----------------+----------------+----------------+
599 * | dbuf_cookie high 32-bit | 16
600 * +----------------+----------------+----------------+----------------+
601 * | fb_cookie low 32-bit | 20
602 * +----------------+----------------+----------------+----------------+
603 * | fb_cookie high 32-bit | 24
604 * +----------------+----------------+----------------+----------------+
606 * +----------------+----------------+----------------+----------------+
608 * +----------------+----------------+----------------+----------------+
610 * +----------------+----------------+----------------+----------------+
612 * +----------------+----------------+----------------+----------------+
614 * +----------------+----------------+----------------+----------------+
616 * +----------------+----------------+----------------+----------------+
620 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
625 * an error. fb_cookie can be re-used after destroying the corresponding
628 * width - uint32_t, width in pixels
629 * height - uint32_t, height in pixels
630 * pixel_format - uint32_t, pixel format of the framebuffer, FOURCC code
642 * Request framebuffer detach - detach a previously
643 * attached framebuffer from the display buffer in request:
645 * +----------------+----------------+----------------+----------------+
647 * +----------------+----------------+----------------+----------------+
649 * +----------------+----------------+----------------+----------------+
650 * | fb_cookie low 32-bit | 12
651 * +----------------+----------------+----------------+----------------+
652 * | fb_cookie high 32-bit | 16
653 * +----------------+----------------+----------------+----------------+
655 * +----------------+----------------+----------------+----------------+
657 * +----------------+----------------+----------------+----------------+
659 * +----------------+----------------+----------------+----------------+
663 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
671 * Request configuration set/reset - request to set or reset
672 * the configuration/mode of the display:
674 * +----------------+----------------+----------------+----------------+
676 * +----------------+----------------+----------------+----------------+
678 * +----------------+----------------+----------------+----------------+
679 * | fb_cookie low 32-bit | 12
680 * +----------------+----------------+----------------+----------------+
681 * | fb_cookie high 32-bit | 16
682 * +----------------+----------------+----------------+----------------+
684 * +----------------+----------------+----------------+----------------+
686 * +----------------+----------------+----------------+----------------+
688 * +----------------+----------------+----------------+----------------+
690 * +----------------+----------------+----------------+----------------+
692 * +----------------+----------------+----------------+----------------+
694 * +----------------+----------------+----------------+----------------+
696 * +----------------+----------------+----------------+----------------+
698 * +----------------+----------------+----------------+----------------+
703 * displayed while enabling display (applying configuration).
707 * x - uint32_t, starting position in pixels by X axis
708 * y - uint32_t, starting position in pixels by Y axis
709 * width - uint32_t, width in pixels
710 * height - uint32_t, height in pixels
711 * bpp - uint32_t, bits per pixel
724 * Request page flip - request to flip a page identified by the framebuffer
727 * +----------------+----------------+----------------+----------------+
729 * +----------------+----------------+----------------+----------------+
731 * +----------------+----------------+----------------+----------------+
732 * | fb_cookie low 32-bit | 12
733 * +----------------+----------------+----------------+----------------+
734 * | fb_cookie high 32-bit | 16
735 * +----------------+----------------+----------------+----------------+
737 * +----------------+----------------+----------------+----------------+
739 * +----------------+----------------+----------------+----------------+
741 * +----------------+----------------+----------------+----------------+
749 * Request EDID - request EDID describing current connector:
751 * +----------------+----------------+----------------+----------------+
753 * +----------------+----------------+----------------+----------------+
755 * +----------------+----------------+----------------+----------------+
757 * +----------------+----------------+----------------+----------------+
759 * +----------------+----------------+----------------+----------------+
761 * +----------------+----------------+----------------+----------------+
763 * +----------------+----------------+----------------+----------------+
766 * - This command is not available in protocol version 1 and should be
768 * - This request is optional and if not supported then visible area
770 * - Shared buffer, allocated for EDID storage, must not be less then
773 * buffer_sz - uint32_t, buffer size to be allocated, octets
774 * gref_directory - grant_ref_t, a reference to the first shared page
787 *---------------------------------- Responses --------------------------------
793 * +----------------+----------------+----------------+----------------+
795 * +----------------+----------------+----------------+----------------+
797 * +----------------+----------------+----------------+----------------+
799 * +----------------+----------------+----------------+----------------+
801 * +----------------+----------------+----------------+----------------+
803 * +----------------+----------------+----------------+----------------+
805 * id - uint16_t, private guest value, echoed from request
806 * status - int32_t, response status, zero on success and -XEN_EXX on failure
809 * Get EDID response - response for XENDISPL_OP_GET_EDID:
811 * +----------------+----------------+----------------+----------------+
813 * +----------------+----------------+----------------+----------------+
815 * +----------------+----------------+----------------+----------------+
817 * +----------------+----------------+----------------+----------------+
819 * +----------------+----------------+----------------+----------------+
821 * +----------------+----------------+----------------+----------------+
823 * +----------------+----------------+----------------+----------------+
826 * - This response is not available in protocol version 1 and should be
829 * edid_sz - uint32_t, size of the EDID, octets
837 *----------------------------------- Events ----------------------------------
840 * evt-event-channel/evt-ring-ref XenStore entries
844 * +----------------+----------------+----------------+----------------+
846 * +----------------+----------------+----------------+----------------+
848 * +----------------+----------------+----------------+----------------+
850 * id - uint16_t, event id, may be used by front
851 * type - uint8_t, type of the event
854 * Page flip complete event - event from back to front on page flip completed:
856 * +----------------+----------------+----------------+----------------+
858 * +----------------+----------------+----------------+----------------+
860 * +----------------+----------------+----------------+----------------+
861 * | fb_cookie low 32-bit | 12
862 * +----------------+----------------+----------------+----------------+
863 * | fb_cookie high 32-bit | 16
864 * +----------------+----------------+----------------+----------------+
866 * +----------------+----------------+----------------+----------------+
868 * +----------------+----------------+----------------+----------------+
870 * +----------------+----------------+----------------+----------------+
922 * XenStore entries (evt-ring-ref/evt-event-channel).
940 #define XENDISPL_IN_RING_SIZE (XENDISPL_EVENT_PAGE_SIZE - XENDISPL_IN_RING_OFFS)