1 /******************************************************************************
2 * displif.h
3 *
4 * Unified display device I/O interface for Xen guest OSes.
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 * DEALINGS IN THE SOFTWARE.
23 *
24 * Copyright (C) 2016-2017 EPAM Systems Inc.
25 *
26 * Authors: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>
27 * Oleksandr Grytsov <oleksandr_grytsov@epam.com>
28 */
29
30 #ifndef __XEN_PUBLIC_IO_DISPLIF_H__
31 #define __XEN_PUBLIC_IO_DISPLIF_H__
32
33 #include "ring.h"
34 #include "../grant_table.h"
35
36 /*
37 ******************************************************************************
38 * Protocol version
39 ******************************************************************************
40 */
41 #define XENDISPL_PROTOCOL_VERSION "1"
42
43 /*
44 ******************************************************************************
45 * Main features provided by the protocol
46 ******************************************************************************
47 * This protocol aims to provide a unified protocol which fits more
48 * sophisticated use-cases than a framebuffer device can handle. At the
49 * moment basic functionality is supported with the intention to be extended:
50 * o multiple dynamically allocated/destroyed framebuffers
51 * o buffers of arbitrary sizes
52 * o buffer allocation at either back or front end
53 * o better configuration options including multiple display support
54 *
55 * Note: existing fbif can be used together with displif running at the
56 * same time, e.g. on Linux one provides framebuffer and another DRM/KMS
57 *
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,
63 * e.g. those buffers can be just a part of the final composition.
64 *
65 ******************************************************************************
66 * Direction of improvements
67 ******************************************************************************
68 * Future extensions to the existing protocol may include:
69 * o display/connector cloning
70 * o allocation of objects other than display buffers
71 * o plane/overlay support
72 * o scaling support
73 * o rotation support
74 *
75 ******************************************************************************
76 * Feature and Parameter Negotiation
77 ******************************************************************************
78 *
79 * Front->back notifications: when enqueuing a new request, sending a
80 * notification can be made conditional on xendispl_req (i.e., the generic
81 * hold-off mechanism provided by the ring macros). Backends must set
82 * xendispl_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()).
83 *
84 * Back->front notifications: when enqueuing a new response, sending a
85 * notification can be made conditional on xendispl_resp (i.e., the generic
86 * hold-off mechanism provided by the ring macros). Frontends must set
87 * xendispl_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()).
88 *
89 * The two halves of a para-virtual display driver utilize nodes within
90 * XenStore to communicate capabilities and to negotiate operating parameters.
91 * This section enumerates these nodes which reside in the respective front and
92 * backend portions of XenStore, following the XenBus convention.
93 *
94 * All data in XenStore is stored as strings. Nodes specifying numeric
95 * values are encoded in decimal. Integer value ranges listed below are
96 * expressed as fixed sized integer types capable of storing the conversion
97 * of a properly formated node string, without loss of information.
98 *
99 ******************************************************************************
100 * Example configuration
101 ******************************************************************************
102 *
103 * Note: depending on the use-case backend can expose more display connectors
104 * than the underlying HW physically has by employing SW graphics compositors
105 *
106 * This is an example of backend and frontend configuration:
107 *
108 *--------------------------------- Backend -----------------------------------
109 *
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"
114 *
115 *--------------------------------- Frontend ----------------------------------
116 *
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"
119 * /local/domain/1/device/vdispl/0/state = "4"
120 * /local/domain/1/device/vdispl/0/version = "1"
121 * /local/domain/1/device/vdispl/0/be-alloc = "1"
122 *
123 *-------------------------- Connector 0 configuration ------------------------
124 *
125 * /local/domain/1/device/vdispl/0/0/resolution = "1920x1080"
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"
130 *
131 *-------------------------- Connector 1 configuration ------------------------
132 *
133 * /local/domain/1/device/vdispl/0/1/resolution = "800x600"
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"
138 *
139 ******************************************************************************
140 * Backend XenBus Nodes
141 ******************************************************************************
142 *
143 *----------------------------- Protocol version ------------------------------
144 *
145 * versions
146 * Values: <string>
147 *
148 * List of XENDISPL_LIST_SEPARATOR separated protocol versions supported
149 * by the backend. For example "1,2,3".
150 *
151 ******************************************************************************
152 * Frontend XenBus Nodes
153 ******************************************************************************
154 *
155 *-------------------------------- Addressing ---------------------------------
156 *
157 * dom-id
158 * Values: <uint16_t>
159 *
160 * Domain identifier.
161 *
162 * dev-id
163 * Values: <uint16_t>
164 *
165 * Device identifier.
166 *
167 * conn-idx
168 * Values: <uint8_t>
169 *
170 * Zero based contigous index of the connector.
171 * /local/domain/<dom-id>/device/vdispl/<dev-id>/<conn-idx>/...
172 *
173 *----------------------------- Protocol version ------------------------------
174 *
175 * version
176 * Values: <string>
177 *
178 * Protocol version, chosen among the ones supported by the backend.
179 *
180 *------------------------- Backend buffer allocation -------------------------
181 *
182 * be-alloc
183 * Values: "0", "1"
184 *
185 * If value is set to "1", then backend can be a buffer provider/allocator
186 * for this domain during XENDISPL_OP_DBUF_CREATE operation (see below
187 * for negotiation).
188 * If value is not "1" or omitted frontend must allocate buffers itself.
189 *
190 *----------------------------- Connector settings ----------------------------
191 *
192 * unique-id
193 * Values: <string>
194 *
195 * After device instance initialization each connector is assigned a
196 * unique ID, so it can be identified by the backend by this ID.
197 * This can be UUID or such.
198 *
199 * resolution
200 * Values: <width, uint32_t>x<height, uint32_t>
201 *
202 * Width and height of the connector in pixels separated by
203 * XENDISPL_RESOLUTION_SEPARATOR. This defines visible area of the
204 * display.
205 *
206 *------------------ Connector Request Transport Parameters -------------------
207 *
208 * This communication path is used to deliver requests from frontend to backend
209 * and get the corresponding responses from backend to frontend,
210 * set up per connector.
211 *
212 * req-event-channel
213 * Values: <uint32_t>
214 *
215 * The identifier of the Xen connector's control event channel
216 * used to signal activity in the ring buffer.
217 *
218 * req-ring-ref
219 * Values: <uint32_t>
220 *
221 * The Xen grant reference granting permission for the backend to map
222 * a sole page of connector's control ring buffer.
223 *
224 *------------------- Connector Event Transport Parameters --------------------
225 *
226 * This communication path is used to deliver asynchronous events from backend
227 * to frontend, set up per connector.
228 *
229 * evt-event-channel
230 * Values: <uint32_t>
231 *
232 * The identifier of the Xen connector's event channel
233 * used to signal activity in the ring buffer.
234 *
235 * evt-ring-ref
236 * Values: <uint32_t>
237 *
238 * The Xen grant reference granting permission for the backend to map
239 * a sole page of connector's event ring buffer.
240 */
241
242 /*
243 ******************************************************************************
244 * STATE DIAGRAMS
245 ******************************************************************************
246 *
247 * Tool stack creates front and back state nodes with initial state
248 * XenbusStateInitialising.
249 * Tool stack creates and sets up frontend display configuration
250 * nodes per domain.
251 *
252 *-------------------------------- Normal flow --------------------------------
253 *
254 * Front Back
255 * ================================= =====================================
256 * XenbusStateInitialising XenbusStateInitialising
257 * o Query backend device identification
258 * data.
259 * o Open and validate backend device.
260 * |
261 * |
262 * V
263 * XenbusStateInitWait
264 *
265 * o Query frontend configuration
266 * o Allocate and initialize
267 * event channels per configured
268 * connector.
269 * o Publish transport parameters
270 * that will be in effect during
271 * this connection.
272 * |
273 * |
274 * V
275 * XenbusStateInitialised
276 *
277 * o Query frontend transport parameters.
278 * o Connect to the event channels.
279 * |
280 * |
281 * V
282 * XenbusStateConnected
283 *
284 * o Create and initialize OS
285 * virtual display connectors
286 * as per configuration.
287 * |
288 * |
289 * V
290 * XenbusStateConnected
291 *
292 * XenbusStateUnknown
293 * XenbusStateClosed
294 * XenbusStateClosing
295 * o Remove virtual display device
296 * o Remove event channels
297 * |
298 * |
299 * V
300 * XenbusStateClosed
301 *
302 *------------------------------- Recovery flow -------------------------------
303 *
304 * In case of frontend unrecoverable errors backend handles that as
305 * if frontend goes into the XenbusStateClosed state.
306 *
307 * In case of backend unrecoverable errors frontend tries removing
308 * the virtualized device. If this is possible at the moment of error,
309 * then frontend goes into the XenbusStateInitialising state and is ready for
310 * new connection with backend. If the virtualized device is still in use and
311 * cannot be removed, then frontend goes into the XenbusStateReconfiguring state
312 * until either the virtualized device is removed or backend initiates a new
313 * connection. On the virtualized device removal frontend goes into the
314 * XenbusStateInitialising state.
315 *
316 * Note on XenbusStateReconfiguring state of the frontend: if backend has
317 * unrecoverable errors then frontend cannot send requests to the backend
318 * and thus cannot provide functionality of the virtualized device anymore.
319 * After backend is back to normal the virtualized device may still hold some
320 * state: configuration in use, allocated buffers, client application state etc.
321 * In most cases, this will require frontend to implement complex recovery
322 * reconnect logic. Instead, by going into XenbusStateReconfiguring state,
323 * frontend will make sure no new clients of the virtualized device are
324 * accepted, allow existing client(s) to exit gracefully by signaling error
325 * state etc.
326 * Once all the clients are gone frontend can reinitialize the virtualized
327 * device and get into XenbusStateInitialising state again signaling the
328 * backend that a new connection can be made.
329 *
330 * There are multiple conditions possible under which frontend will go from
331 * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS
332 * specific. For example:
333 * 1. The underlying OS framework may provide callbacks to signal that the last
334 * client of the virtualized device has gone and the device can be removed
335 * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue)
336 * to periodically check if this is the right time to re-try removal of
337 * the virtualized device.
338 * 3. By any other means.
339 *
340 ******************************************************************************
341 * REQUEST CODES
342 ******************************************************************************
343 * Request codes [0; 15] are reserved and must not be used
344 */
345
346 #define XENDISPL_OP_DBUF_CREATE 0x10
347 #define XENDISPL_OP_DBUF_DESTROY 0x11
348 #define XENDISPL_OP_FB_ATTACH 0x12
349 #define XENDISPL_OP_FB_DETACH 0x13
350 #define XENDISPL_OP_SET_CONFIG 0x14
351 #define XENDISPL_OP_PG_FLIP 0x15
352
353 /*
354 ******************************************************************************
355 * EVENT CODES
356 ******************************************************************************
357 */
358 #define XENDISPL_EVT_PG_FLIP 0x00
359
360 /*
361 ******************************************************************************
362 * XENSTORE FIELD AND PATH NAME STRINGS, HELPERS
363 ******************************************************************************
364 */
365 #define XENDISPL_DRIVER_NAME "vdispl"
366
367 #define XENDISPL_LIST_SEPARATOR ","
368 #define XENDISPL_RESOLUTION_SEPARATOR "x"
369
370 #define XENDISPL_FIELD_BE_VERSIONS "versions"
371 #define XENDISPL_FIELD_FE_VERSION "version"
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"
376 #define XENDISPL_FIELD_RESOLUTION "resolution"
377 #define XENDISPL_FIELD_BE_ALLOC "be-alloc"
378 #define XENDISPL_FIELD_UNIQUE_ID "unique-id"
379
380 /*
381 ******************************************************************************
382 * STATUS RETURN CODES
383 ******************************************************************************
384 *
385 * Status return code is zero on success and -XEN_EXX on failure.
386 *
387 ******************************************************************************
388 * Assumptions
389 ******************************************************************************
390 * o usage of grant reference 0 as invalid grant reference:
391 * grant reference 0 is valid, but never exposed to a PV driver,
392 * because of the fact it is already in use/reserved by the PV console.
393 * o all references in this document to page sizes must be treated
394 * as pages of size XEN_PAGE_SIZE unless otherwise noted.
395 *
396 ******************************************************************************
397 * Description of the protocol between frontend and backend driver
398 ******************************************************************************
399 *
400 * The two halves of a Para-virtual display driver communicate with
401 * each other using shared pages and event channels.
402 * Shared page contains a ring with request/response packets.
403 *
404 * All reserved fields in the structures below must be 0.
405 * Display buffers's cookie of value 0 is treated as invalid.
406 * Framebuffer's cookie of value 0 is treated as invalid.
407 *
408 * For all request/response/event packets that use cookies:
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
412 * to map remote framebuffer to its local one
413 *
414 *---------------------------------- Requests ---------------------------------
415 *
416 * All requests/responses, which are not connector specific, must be sent over
417 * control ring of the connector which has the index value of 0:
418 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
419 *
420 * All request packets have the same length (64 octets)
421 * All request packets have common header:
422 * 0 1 2 3 octet
423 * +----------------+----------------+----------------+----------------+
424 * | id | operation | reserved | 4
425 * +----------------+----------------+----------------+----------------+
426 * | reserved | 8
427 * +----------------+----------------+----------------+----------------+
428 * id - uint16_t, private guest value, echoed in response
429 * operation - uint8_t, operation code, XENDISPL_OP_???
430 *
431 * Request dbuf creation - request creation of a display buffer.
432 * 0 1 2 3 octet
433 * +----------------+----------------+----------------+----------------+
434 * | id |_OP_DBUF_CREATE | reserved | 4
435 * +----------------+----------------+----------------+----------------+
436 * | reserved | 8
437 * +----------------+----------------+----------------+----------------+
438 * | dbuf_cookie low 32-bit | 12
439 * +----------------+----------------+----------------+----------------+
440 * | dbuf_cookie high 32-bit | 16
441 * +----------------+----------------+----------------+----------------+
442 * | width | 20
443 * +----------------+----------------+----------------+----------------+
444 * | height | 24
445 * +----------------+----------------+----------------+----------------+
446 * | bpp | 28
447 * +----------------+----------------+----------------+----------------+
448 * | buffer_sz | 32
449 * +----------------+----------------+----------------+----------------+
450 * | flags | 36
451 * +----------------+----------------+----------------+----------------+
452 * | gref_directory | 40
453 * +----------------+----------------+----------------+----------------+
454 * | reserved | 44
455 * +----------------+----------------+----------------+----------------+
456 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
457 * +----------------+----------------+----------------+----------------+
458 * | reserved | 64
459 * +----------------+----------------+----------------+----------------+
460 *
461 * Must be sent over control ring of the connector which has the index
462 * value of 0:
463 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
464 * All unused bits in flags field must be set to 0.
465 *
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.
469 *
470 * Width and height of the display buffers can be smaller, equal or bigger
471 * than the connector's resolution. Depth/pixel format of the individual
472 * buffers can differ as well.
473 *
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
480 * to allocate the buffer with the parameters provided in this request.
481 * Page directory is handled as follows:
482 * Frontend on request:
483 * o allocates pages for the directory (gref_directory,
484 * gref_dir_next_page(s)
485 * o grants permissions for the pages of the directory to the backend
486 * o sets gref_dir_next_page fields
487 * Backend on response:
488 * o grants permissions for the pages of the buffer allocated to
489 * the frontend
490 * o fills in page directory with grant references
491 * (gref[] in struct xendispl_page_directory)
492 * gref_directory - grant_ref_t, a reference to the first shared page
493 * describing shared buffer references. At least one page exists. If shared
494 * buffer size (buffer_sz) exceeds what can be addressed by this single page,
495 * then reference to the next page must be supplied (see gref_dir_next_page
496 * below)
497 */
498
499 #define XENDISPL_DBUF_FLG_REQ_ALLOC (1 << 0)
500
501 struct xendispl_dbuf_create_req {
502 uint64_t dbuf_cookie;
503 uint32_t width;
504 uint32_t height;
505 uint32_t bpp;
506 uint32_t buffer_sz;
507 uint32_t flags;
508 grant_ref_t gref_directory;
509 };
510
511 /*
512 * Shared page for XENDISPL_OP_DBUF_CREATE buffer descriptor (gref_directory in
513 * the request) employs a list of pages, describing all pages of the shared
514 * data buffer:
515 * 0 1 2 3 octet
516 * +----------------+----------------+----------------+----------------+
517 * | gref_dir_next_page | 4
518 * +----------------+----------------+----------------+----------------+
519 * | gref[0] | 8
520 * +----------------+----------------+----------------+----------------+
521 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
522 * +----------------+----------------+----------------+----------------+
523 * | gref[i] | i*4+8
524 * +----------------+----------------+----------------+----------------+
525 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
526 * +----------------+----------------+----------------+----------------+
527 * | gref[N - 1] | N*4+8
528 * +----------------+----------------+----------------+----------------+
529 *
530 * gref_dir_next_page - grant_ref_t, reference to the next page describing
531 * page directory. Must be 0 if there are no more pages in the list.
532 * gref[i] - grant_ref_t, reference to a shared page of the buffer
533 * allocated at XENDISPL_OP_DBUF_CREATE
534 *
535 * Number of grant_ref_t entries in the whole page directory is not
536 * passed, but instead can be calculated as:
537 * num_grefs_total = (XENDISPL_OP_DBUF_CREATE.buffer_sz + XEN_PAGE_SIZE - 1) /
538 * XEN_PAGE_SIZE
539 */
540
541 struct xendispl_page_directory {
542 grant_ref_t gref_dir_next_page;
543 grant_ref_t gref[1]; /* Variable length */
544 };
545
546 /*
547 * Request dbuf destruction - destroy a previously allocated display buffer:
548 * 0 1 2 3 octet
549 * +----------------+----------------+----------------+----------------+
550 * | id |_OP_DBUF_DESTROY| reserved | 4
551 * +----------------+----------------+----------------+----------------+
552 * | reserved | 8
553 * +----------------+----------------+----------------+----------------+
554 * | dbuf_cookie low 32-bit | 12
555 * +----------------+----------------+----------------+----------------+
556 * | dbuf_cookie high 32-bit | 16
557 * +----------------+----------------+----------------+----------------+
558 * | reserved | 20
559 * +----------------+----------------+----------------+----------------+
560 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
561 * +----------------+----------------+----------------+----------------+
562 * | reserved | 64
563 * +----------------+----------------+----------------+----------------+
564 *
565 * Must be sent over control ring of the connector which has the index
566 * value of 0:
567 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
568 */
569
570 struct xendispl_dbuf_destroy_req {
571 uint64_t dbuf_cookie;
572 };
573
574 /*
575 * Request framebuffer attachment - request attachment of a framebuffer to
576 * previously created display buffer.
577 * 0 1 2 3 octet
578 * +----------------+----------------+----------------+----------------+
579 * | id | _OP_FB_ATTACH | reserved | 4
580 * +----------------+----------------+----------------+----------------+
581 * | reserved | 8
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 * +----------------+----------------+----------------+----------------+
591 * | width | 28
592 * +----------------+----------------+----------------+----------------+
593 * | height | 32
594 * +----------------+----------------+----------------+----------------+
595 * | pixel_format | 36
596 * +----------------+----------------+----------------+----------------+
597 * | reserved | 40
598 * +----------------+----------------+----------------+----------------+
599 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
600 * +----------------+----------------+----------------+----------------+
601 * | reserved | 64
602 * +----------------+----------------+----------------+----------------+
603 *
604 * Must be sent over control ring of the connector which has the index
605 * value of 0:
606 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
607 * Width and height can be smaller, equal or bigger than the connector's
608 * resolution.
609 *
610 * An attempt to create multiple frame buffers with the same fb_cookie is
611 * an error. fb_cookie can be re-used after destroying the corresponding
612 * frame buffer.
613 *
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
617 */
618
619 struct xendispl_fb_attach_req {
620 uint64_t dbuf_cookie;
621 uint64_t fb_cookie;
622 uint32_t width;
623 uint32_t height;
624 uint32_t pixel_format;
625 };
626
627 /*
628 * Request framebuffer detach - detach a previously
629 * attached framebuffer from the display buffer in request:
630 * 0 1 2 3 octet
631 * +----------------+----------------+----------------+----------------+
632 * | id | _OP_FB_DETACH | reserved | 4
633 * +----------------+----------------+----------------+----------------+
634 * | reserved | 8
635 * +----------------+----------------+----------------+----------------+
636 * | fb_cookie low 32-bit | 12
637 * +----------------+----------------+----------------+----------------+
638 * | fb_cookie high 32-bit | 16
639 * +----------------+----------------+----------------+----------------+
640 * | reserved | 20
641 * +----------------+----------------+----------------+----------------+
642 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
643 * +----------------+----------------+----------------+----------------+
644 * | reserved | 64
645 * +----------------+----------------+----------------+----------------+
646 *
647 * Must be sent over control ring of the connector which has the index
648 * value of 0:
649 * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref
650 */
651
652 struct xendispl_fb_detach_req {
653 uint64_t fb_cookie;
654 };
655
656 /*
657 * Request configuration set/reset - request to set or reset
658 * the configuration/mode of the display:
659 * 0 1 2 3 octet
660 * +----------------+----------------+----------------+----------------+
661 * | id | _OP_SET_CONFIG | reserved | 4
662 * +----------------+----------------+----------------+----------------+
663 * | reserved | 8
664 * +----------------+----------------+----------------+----------------+
665 * | fb_cookie low 32-bit | 12
666 * +----------------+----------------+----------------+----------------+
667 * | fb_cookie high 32-bit | 16
668 * +----------------+----------------+----------------+----------------+
669 * | x | 20
670 * +----------------+----------------+----------------+----------------+
671 * | y | 24
672 * +----------------+----------------+----------------+----------------+
673 * | width | 28
674 * +----------------+----------------+----------------+----------------+
675 * | height | 32
676 * +----------------+----------------+----------------+----------------+
677 * | bpp | 40
678 * +----------------+----------------+----------------+----------------+
679 * | reserved | 44
680 * +----------------+----------------+----------------+----------------+
681 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
682 * +----------------+----------------+----------------+----------------+
683 * | reserved | 64
684 * +----------------+----------------+----------------+----------------+
685 *
686 * Pass all zeros to reset, otherwise command is treated as
687 * configuration set.
688 * Framebuffer's cookie defines which framebuffer/dbuf must be
689 * displayed while enabling display (applying configuration).
690 * x, y, width and height are bound by the connector's resolution and must not
691 * exceed it.
692 *
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
698 */
699
700 struct xendispl_set_config_req {
701 uint64_t fb_cookie;
702 uint32_t x;
703 uint32_t y;
704 uint32_t width;
705 uint32_t height;
706 uint32_t bpp;
707 };
708
709 /*
710 * Request page flip - request to flip a page identified by the framebuffer
711 * cookie:
712 * 0 1 2 3 octet
713 * +----------------+----------------+----------------+----------------+
714 * | id | _OP_PG_FLIP | reserved | 4
715 * +----------------+----------------+----------------+----------------+
716 * | reserved | 8
717 * +----------------+----------------+----------------+----------------+
718 * | fb_cookie low 32-bit | 12
719 * +----------------+----------------+----------------+----------------+
720 * | fb_cookie high 32-bit | 16
721 * +----------------+----------------+----------------+----------------+
722 * | reserved | 20
723 * +----------------+----------------+----------------+----------------+
724 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
725 * +----------------+----------------+----------------+----------------+
726 * | reserved | 64
727 * +----------------+----------------+----------------+----------------+
728 */
729
730 struct xendispl_page_flip_req {
731 uint64_t fb_cookie;
732 };
733
734 /*
735 *---------------------------------- Responses --------------------------------
736 *
737 * All response packets have the same length (64 octets)
738 *
739 * All response packets have common header:
740 * 0 1 2 3 octet
741 * +----------------+----------------+----------------+----------------+
742 * | id | reserved | 4
743 * +----------------+----------------+----------------+----------------+
744 * | status | 8
745 * +----------------+----------------+----------------+----------------+
746 * | reserved | 12
747 * +----------------+----------------+----------------+----------------+
748 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
749 * +----------------+----------------+----------------+----------------+
750 * | reserved | 64
751 * +----------------+----------------+----------------+----------------+
752 *
753 * id - uint16_t, private guest value, echoed from request
754 * status - int32_t, response status, zero on success and -XEN_EXX on failure
755 *
756 *----------------------------------- Events ----------------------------------
757 *
758 * Events are sent via a shared page allocated by the front and propagated by
759 * evt-event-channel/evt-ring-ref XenStore entries
760 * All event packets have the same length (64 octets)
761 * All event packets have common header:
762 * 0 1 2 3 octet
763 * +----------------+----------------+----------------+----------------+
764 * | id | type | reserved | 4
765 * +----------------+----------------+----------------+----------------+
766 * | reserved | 8
767 * +----------------+----------------+----------------+----------------+
768 *
769 * id - uint16_t, event id, may be used by front
770 * type - uint8_t, type of the event
771 *
772 *
773 * Page flip complete event - event from back to front on page flip completed:
774 * 0 1 2 3 octet
775 * +----------------+----------------+----------------+----------------+
776 * | id | _EVT_PG_FLIP | reserved | 4
777 * +----------------+----------------+----------------+----------------+
778 * | reserved | 8
779 * +----------------+----------------+----------------+----------------+
780 * | fb_cookie low 32-bit | 12
781 * +----------------+----------------+----------------+----------------+
782 * | fb_cookie high 32-bit | 16
783 * +----------------+----------------+----------------+----------------+
784 * | reserved | 20
785 * +----------------+----------------+----------------+----------------+
786 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
787 * +----------------+----------------+----------------+----------------+
788 * | reserved | 64
789 * +----------------+----------------+----------------+----------------+
790 */
791
792 struct xendispl_pg_flip_evt {
793 uint64_t fb_cookie;
794 };
795
796 struct xendispl_req {
797 uint16_t id;
798 uint8_t operation;
799 uint8_t reserved[5];
800 union {
801 struct xendispl_dbuf_create_req dbuf_create;
802 struct xendispl_dbuf_destroy_req dbuf_destroy;
803 struct xendispl_fb_attach_req fb_attach;
804 struct xendispl_fb_detach_req fb_detach;
805 struct xendispl_set_config_req set_config;
806 struct xendispl_page_flip_req pg_flip;
807 uint8_t reserved[56];
808 } op;
809 };
810
811 struct xendispl_resp {
812 uint16_t id;
813 uint8_t operation;
814 uint8_t reserved;
815 int32_t status;
816 uint8_t reserved1[56];
817 };
818
819 struct xendispl_evt {
820 uint16_t id;
821 uint8_t type;
822 uint8_t reserved[5];
823 union {
824 struct xendispl_pg_flip_evt pg_flip;
825 uint8_t reserved[56];
826 } op;
827 };
828
829 DEFINE_RING_TYPES(xen_displif, struct xendispl_req, struct xendispl_resp);
830
831 /*
832 ******************************************************************************
833 * Back to front events delivery
834 ******************************************************************************
835 * In order to deliver asynchronous events from back to front a shared page is
836 * allocated by front and its granted reference propagated to back via
837 * XenStore entries (evt-ring-ref/evt-event-channel).
838 * This page has a common header used by both front and back to synchronize
839 * access and control event's ring buffer, while back being a producer of the
840 * events and front being a consumer. The rest of the page after the header
841 * is used for event packets.
842 *
843 * Upon reception of an event(s) front may confirm its reception
844 * for either each event, group of events or none.
845 */
846
847 struct xendispl_event_page {
848 uint32_t in_cons;
849 uint32_t in_prod;
850 uint8_t reserved[56];
851 };
852
853 #define XENDISPL_EVENT_PAGE_SIZE XEN_PAGE_SIZE
854 #define XENDISPL_IN_RING_OFFS (sizeof(struct xendispl_event_page))
855 #define XENDISPL_IN_RING_SIZE (XENDISPL_EVENT_PAGE_SIZE - XENDISPL_IN_RING_OFFS)
856 #define XENDISPL_IN_RING_LEN (XENDISPL_IN_RING_SIZE / sizeof(struct xendispl_evt))
857 #define XENDISPL_IN_RING(page) \
858 ((struct xendispl_evt *)((char *)(page) + XENDISPL_IN_RING_OFFS))
859 #define XENDISPL_IN_RING_REF(page, idx) \
860 (XENDISPL_IN_RING((page))[(idx) % XENDISPL_IN_RING_LEN])
861
862 #endif /* __XEN_PUBLIC_IO_DISPLIF_H__ */