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