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.
48 * sophisticated use-cases than a framebuffer device can handle. At the
53 * o better configuration options including multiple display support
58 * Note: display resolution (XenStore's "resolution" property) defines
59 * visible area of the virtual display. At the same time resolution of
60 * the display and frame buffers may differ: buffers can be smaller, equal
61 * or bigger than the visible area. This is to enable use-cases, where backend
62 * may do some post-processing of the display and frame buffers supplied,
69 * o display/connector cloning
70 * o allocation of objects other than display buffers
79 * Front->back notifications: when enqueuing a new request, sending a
81 * hold-off mechanism provided by the ring macros). Backends must set
84 * Back->front notifications: when enqueuing a new response, sending a
86 * hold-off mechanism provided by the ring macros). Frontends must set
89 * The two halves of a para-virtual display driver utilize nodes within
92 * backend portions of XenStore, following the XenBus convention.
103 * Note: depending on the use-case backend can expose more display connectors
106 * This is an example of backend and frontend configuration:
108 *--------------------------------- Backend -----------------------------------
110 * /local/domain/0/backend/vdispl/1/0/frontend-id = "1"
111 * /local/domain/0/backend/vdispl/1/0/frontend = "/local/domain/1/device/vdispl/0"
112 * /local/domain/0/backend/vdispl/1/0/state = "4"
113 * /local/domain/0/backend/vdispl/1/0/versions = "1,2"
115 *--------------------------------- Frontend ----------------------------------
117 * /local/domain/1/device/vdispl/0/backend-id = "0"
118 * /local/domain/1/device/vdispl/0/backend = "/local/domain/0/backend/vdispl/1/0"
121 * /local/domain/1/device/vdispl/0/be-alloc = "1"
123 *-------------------------- Connector 0 configuration ------------------------
126 * /local/domain/1/device/vdispl/0/0/req-ring-ref = "2832"
127 * /local/domain/1/device/vdispl/0/0/req-event-channel = "15"
128 * /local/domain/1/device/vdispl/0/0/evt-ring-ref = "387"
129 * /local/domain/1/device/vdispl/0/0/evt-event-channel = "16"
131 *-------------------------- Connector 1 configuration ------------------------
134 * /local/domain/1/device/vdispl/0/1/req-ring-ref = "2833"
135 * /local/domain/1/device/vdispl/0/1/req-event-channel = "17"
136 * /local/domain/1/device/vdispl/0/1/evt-ring-ref = "388"
137 * /local/domain/1/device/vdispl/0/1/evt-event-channel = "18"
140 * Backend XenBus Nodes
143 *----------------------------- Protocol version ------------------------------
149 * by the backend. For example "1,2,3".
155 *-------------------------------- Addressing ---------------------------------
157 * dom-id
162 * dev-id
167 * conn-idx
171 * /local/domain/<dom-id>/device/vdispl/<dev-id>/<conn-idx>/...
173 *----------------------------- Protocol version ------------------------------
178 * Protocol version, chosen among the ones supported by the backend.
180 *------------------------- Backend buffer allocation -------------------------
182 * be-alloc
185 * If value is set to "1", then backend can be a buffer provider/allocator
190 *----------------------------- Connector settings ----------------------------
192 * unique-id
196 * unique ID, so it can be identified by the backend by this ID.
204 * display.
206 *------------------ Connector Request Transport Parameters -------------------
208 * This communication path is used to deliver requests from frontend to backend
209 * and get the corresponding responses from backend to frontend,
212 * req-event-channel
218 * req-ring-ref
221 * The Xen grant reference granting permission for the backend to map
224 *------------------- Connector Event Transport Parameters --------------------
226 * This communication path is used to deliver asynchronous events from backend
229 * evt-event-channel
235 * evt-ring-ref
238 * The Xen grant reference granting permission for the backend to map
249 * Tool stack creates and sets up frontend display configuration
252 *-------------------------------- Normal flow --------------------------------
257 * o Query backend device identification
259 * o Open and validate backend device.
285 * virtual display connectors
295 * o Remove virtual display device
302 *------------------------------- Recovery flow -------------------------------
304 * In case of frontend unrecoverable errors backend handles that as
307 * In case of backend unrecoverable errors frontend tries removing
310 * new connection with backend. If the virtualized device is still in use and
312 * until either the virtualized device is removed or backend initiates a new
316 * Note on XenbusStateReconfiguring state of the frontend: if backend has
317 * unrecoverable errors then frontend cannot send requests to the backend
319 * After backend is back to normal the virtualized device may still hold some
328 * backend that a new connection can be made.
336 * to periodically check if this is the right time to re-try removal of
372 #define XENDISPL_FIELD_REQ_RING_REF "req-ring-ref"
373 #define XENDISPL_FIELD_REQ_CHANNEL "req-event-channel"
374 #define XENDISPL_FIELD_EVT_RING_REF "evt-ring-ref"
375 #define XENDISPL_FIELD_EVT_CHANNEL "evt-event-channel"
377 #define XENDISPL_FIELD_BE_ALLOC "be-alloc"
378 #define XENDISPL_FIELD_UNIQUE_ID "unique-id"
385 * Status return code is zero on success and -XEN_EXX on failure.
397 * Description of the protocol between frontend and backend driver
400 * The two halves of a Para-virtual display driver communicate with
405 * Display buffers's cookie of value 0 is treated as invalid.
409 * dbuf_cookie - uint64_t, unique to guest domain value used by the backend
410 * to map remote display buffer to its local one
411 * fb_cookie - uint64_t, unique to guest domain value used by the backend
414 *---------------------------------- Requests ---------------------------------
418 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
423 * +----------------+----------------+----------------+----------------+
425 * +----------------+----------------+----------------+----------------+
427 * +----------------+----------------+----------------+----------------+
428 * id - uint16_t, private guest value, echoed in response
429 * operation - uint8_t, operation code, XENDISPL_OP_???
431 * Request dbuf creation - request creation of a display buffer.
433 * +----------------+----------------+----------------+----------------+
435 * +----------------+----------------+----------------+----------------+
437 * +----------------+----------------+----------------+----------------+
438 * | dbuf_cookie low 32-bit | 12
439 * +----------------+----------------+----------------+----------------+
440 * | dbuf_cookie high 32-bit | 16
441 * +----------------+----------------+----------------+----------------+
443 * +----------------+----------------+----------------+----------------+
445 * +----------------+----------------+----------------+----------------+
447 * +----------------+----------------+----------------+----------------+
449 * +----------------+----------------+----------------+----------------+
451 * +----------------+----------------+----------------+----------------+
453 * +----------------+----------------+----------------+----------------+
455 * +----------------+----------------+----------------+----------------+
457 * +----------------+----------------+----------------+----------------+
459 * +----------------+----------------+----------------+----------------+
463 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
466 * An attempt to create multiple display buffers with the same dbuf_cookie is
467 * an error. dbuf_cookie can be re-used after destroying the corresponding
468 * display buffer.
470 * Width and height of the display buffers can be smaller, equal or bigger
474 * width - uint32_t, width in pixels
475 * height - uint32_t, height in pixels
476 * bpp - uint32_t, bits per pixel
477 * buffer_sz - uint32_t, buffer size to be allocated, octets
478 * flags - uint32_t, flags of the operation
479 * o XENDISPL_DBUF_FLG_REQ_ALLOC - if set, then backend is requested
485 * o grants permissions for the pages of the directory to the backend
487 * Backend on response:
492 * gref_directory - grant_ref_t, a reference to the first shared page
516 * +----------------+----------------+----------------+----------------+
518 * +----------------+----------------+----------------+----------------+
520 * +----------------+----------------+----------------+----------------+
522 * +----------------+----------------+----------------+----------------+
524 * +----------------+----------------+----------------+----------------+
526 * +----------------+----------------+----------------+----------------+
527 * | gref[N - 1] | N*4+8
528 * +----------------+----------------+----------------+----------------+
530 * gref_dir_next_page - grant_ref_t, reference to the next page describing
532 * gref[i] - grant_ref_t, reference to a shared page of the buffer
537 * num_grefs_total = (XENDISPL_OP_DBUF_CREATE.buffer_sz + XEN_PAGE_SIZE - 1) /
547 * Request dbuf destruction - destroy a previously allocated display buffer:
549 * +----------------+----------------+----------------+----------------+
551 * +----------------+----------------+----------------+----------------+
553 * +----------------+----------------+----------------+----------------+
554 * | dbuf_cookie low 32-bit | 12
555 * +----------------+----------------+----------------+----------------+
556 * | dbuf_cookie high 32-bit | 16
557 * +----------------+----------------+----------------+----------------+
559 * +----------------+----------------+----------------+----------------+
561 * +----------------+----------------+----------------+----------------+
563 * +----------------+----------------+----------------+----------------+
567 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
575 * Request framebuffer attachment - request attachment of a framebuffer to
576 * previously created display buffer.
578 * +----------------+----------------+----------------+----------------+
580 * +----------------+----------------+----------------+----------------+
582 * +----------------+----------------+----------------+----------------+
583 * | dbuf_cookie low 32-bit | 12
584 * +----------------+----------------+----------------+----------------+
585 * | dbuf_cookie high 32-bit | 16
586 * +----------------+----------------+----------------+----------------+
587 * | fb_cookie low 32-bit | 20
588 * +----------------+----------------+----------------+----------------+
589 * | fb_cookie high 32-bit | 24
590 * +----------------+----------------+----------------+----------------+
592 * +----------------+----------------+----------------+----------------+
594 * +----------------+----------------+----------------+----------------+
596 * +----------------+----------------+----------------+----------------+
598 * +----------------+----------------+----------------+----------------+
600 * +----------------+----------------+----------------+----------------+
602 * +----------------+----------------+----------------+----------------+
606 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
611 * an error. fb_cookie can be re-used after destroying the corresponding
614 * width - uint32_t, width in pixels
615 * height - uint32_t, height in pixels
616 * pixel_format - uint32_t, pixel format of the framebuffer, FOURCC code
628 * Request framebuffer detach - detach a previously
629 * attached framebuffer from the display buffer in request:
631 * +----------------+----------------+----------------+----------------+
633 * +----------------+----------------+----------------+----------------+
635 * +----------------+----------------+----------------+----------------+
636 * | fb_cookie low 32-bit | 12
637 * +----------------+----------------+----------------+----------------+
638 * | fb_cookie high 32-bit | 16
639 * +----------------+----------------+----------------+----------------+
641 * +----------------+----------------+----------------+----------------+
643 * +----------------+----------------+----------------+----------------+
645 * +----------------+----------------+----------------+----------------+
649 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
657 * Request configuration set/reset - request to set or reset
658 * the configuration/mode of the display:
660 * +----------------+----------------+----------------+----------------+
662 * +----------------+----------------+----------------+----------------+
664 * +----------------+----------------+----------------+----------------+
665 * | fb_cookie low 32-bit | 12
666 * +----------------+----------------+----------------+----------------+
667 * | fb_cookie high 32-bit | 16
668 * +----------------+----------------+----------------+----------------+
670 * +----------------+----------------+----------------+----------------+
672 * +----------------+----------------+----------------+----------------+
674 * +----------------+----------------+----------------+----------------+
676 * +----------------+----------------+----------------+----------------+
678 * +----------------+----------------+----------------+----------------+
680 * +----------------+----------------+----------------+----------------+
682 * +----------------+----------------+----------------+----------------+
684 * +----------------+----------------+----------------+----------------+
689 * displayed while enabling display (applying configuration).
693 * x - uint32_t, starting position in pixels by X axis
694 * y - uint32_t, starting position in pixels by Y axis
695 * width - uint32_t, width in pixels
696 * height - uint32_t, height in pixels
697 * bpp - uint32_t, bits per pixel
710 * Request page flip - request to flip a page identified by the framebuffer
713 * +----------------+----------------+----------------+----------------+
715 * +----------------+----------------+----------------+----------------+
717 * +----------------+----------------+----------------+----------------+
718 * | fb_cookie low 32-bit | 12
719 * +----------------+----------------+----------------+----------------+
720 * | fb_cookie high 32-bit | 16
721 * +----------------+----------------+----------------+----------------+
723 * +----------------+----------------+----------------+----------------+
725 * +----------------+----------------+----------------+----------------+
727 * +----------------+----------------+----------------+----------------+
735 *---------------------------------- Responses --------------------------------
741 * +----------------+----------------+----------------+----------------+
743 * +----------------+----------------+----------------+----------------+
745 * +----------------+----------------+----------------+----------------+
747 * +----------------+----------------+----------------+----------------+
749 * +----------------+----------------+----------------+----------------+
751 * +----------------+----------------+----------------+----------------+
753 * id - uint16_t, private guest value, echoed from request
754 * status - int32_t, response status, zero on success and -XEN_EXX on failure
756 *----------------------------------- Events ----------------------------------
759 * evt-event-channel/evt-ring-ref XenStore entries
763 * +----------------+----------------+----------------+----------------+
765 * +----------------+----------------+----------------+----------------+
767 * +----------------+----------------+----------------+----------------+
769 * id - uint16_t, event id, may be used by front
770 * type - uint8_t, type of the event
773 * Page flip complete event - event from back to front on page flip completed:
775 * +----------------+----------------+----------------+----------------+
777 * +----------------+----------------+----------------+----------------+
779 * +----------------+----------------+----------------+----------------+
780 * | fb_cookie low 32-bit | 12
781 * +----------------+----------------+----------------+----------------+
782 * | fb_cookie high 32-bit | 16
783 * +----------------+----------------+----------------+----------------+
785 * +----------------+----------------+----------------+----------------+
787 * +----------------+----------------+----------------+----------------+
789 * +----------------+----------------+----------------+----------------+
837 * XenStore entries (evt-ring-ref/evt-event-channel).
855 #define XENDISPL_IN_RING_SIZE (XENDISPL_EVENT_PAGE_SIZE - XENDISPL_IN_RING_OFFS)