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