13a9fd824SRoger Pau Monné /****************************************************************************** 23a9fd824SRoger Pau Monné * displif.h 33a9fd824SRoger Pau Monné * 43a9fd824SRoger Pau Monné * Unified display device I/O interface for Xen guest OSes. 53a9fd824SRoger Pau Monné * 63a9fd824SRoger Pau Monné * Permission is hereby granted, free of charge, to any person obtaining a copy 73a9fd824SRoger Pau Monné * of this software and associated documentation files (the "Software"), to 83a9fd824SRoger Pau Monné * deal in the Software without restriction, including without limitation the 93a9fd824SRoger Pau Monné * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 103a9fd824SRoger Pau Monné * sell copies of the Software, and to permit persons to whom the Software is 113a9fd824SRoger Pau Monné * furnished to do so, subject to the following conditions: 123a9fd824SRoger Pau Monné * 133a9fd824SRoger Pau Monné * The above copyright notice and this permission notice shall be included in 143a9fd824SRoger Pau Monné * all copies or substantial portions of the Software. 153a9fd824SRoger Pau Monné * 163a9fd824SRoger Pau Monné * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 173a9fd824SRoger Pau Monné * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 183a9fd824SRoger Pau Monné * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 193a9fd824SRoger Pau Monné * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 203a9fd824SRoger Pau Monné * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 213a9fd824SRoger Pau Monné * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 223a9fd824SRoger Pau Monné * DEALINGS IN THE SOFTWARE. 233a9fd824SRoger Pau Monné * 243a9fd824SRoger Pau Monné * Copyright (C) 2016-2017 EPAM Systems Inc. 253a9fd824SRoger Pau Monné * 263a9fd824SRoger Pau Monné * Authors: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com> 273a9fd824SRoger Pau Monné * Oleksandr Grytsov <oleksandr_grytsov@epam.com> 283a9fd824SRoger Pau Monné */ 293a9fd824SRoger Pau Monné 303a9fd824SRoger Pau Monné #ifndef __XEN_PUBLIC_IO_DISPLIF_H__ 313a9fd824SRoger Pau Monné #define __XEN_PUBLIC_IO_DISPLIF_H__ 323a9fd824SRoger Pau Monné 333a9fd824SRoger Pau Monné #include "ring.h" 343a9fd824SRoger Pau Monné #include "../grant_table.h" 353a9fd824SRoger Pau Monné 363a9fd824SRoger Pau Monné /* 373a9fd824SRoger Pau Monné ****************************************************************************** 383a9fd824SRoger Pau Monné * Protocol version 393a9fd824SRoger Pau Monné ****************************************************************************** 403a9fd824SRoger Pau Monné */ 413a9fd824SRoger Pau Monné #define XENDISPL_PROTOCOL_VERSION "2" 423a9fd824SRoger Pau Monné #define XENDISPL_PROTOCOL_VERSION_INT 2 433a9fd824SRoger Pau Monné 443a9fd824SRoger Pau Monné /* 453a9fd824SRoger Pau Monné ****************************************************************************** 463a9fd824SRoger Pau Monné * Main features provided by the protocol 473a9fd824SRoger Pau Monné ****************************************************************************** 483a9fd824SRoger Pau Monné * This protocol aims to provide a unified protocol which fits more 493a9fd824SRoger Pau Monné * sophisticated use-cases than a framebuffer device can handle. At the 503a9fd824SRoger Pau Monné * moment basic functionality is supported with the intention to be extended: 513a9fd824SRoger Pau Monné * o multiple dynamically allocated/destroyed framebuffers 523a9fd824SRoger Pau Monné * o buffers of arbitrary sizes 533a9fd824SRoger Pau Monné * o buffer allocation at either back or front end 543a9fd824SRoger Pau Monné * o better configuration options including multiple display support 553a9fd824SRoger Pau Monné * 563a9fd824SRoger Pau Monné * Note: existing fbif can be used together with displif running at the 573a9fd824SRoger Pau Monné * same time, e.g. on Linux one provides framebuffer and another DRM/KMS 583a9fd824SRoger Pau Monné * 593a9fd824SRoger Pau Monné * Note: display resolution (XenStore's "resolution" property) defines 603a9fd824SRoger Pau Monné * visible area of the virtual display. At the same time resolution of 613a9fd824SRoger Pau Monné * the display and frame buffers may differ: buffers can be smaller, equal 623a9fd824SRoger Pau Monné * or bigger than the visible area. This is to enable use-cases, where backend 633a9fd824SRoger Pau Monné * may do some post-processing of the display and frame buffers supplied, 643a9fd824SRoger Pau Monné * e.g. those buffers can be just a part of the final composition. 653a9fd824SRoger Pau Monné * 663a9fd824SRoger Pau Monné ****************************************************************************** 673a9fd824SRoger Pau Monné * Direction of improvements 683a9fd824SRoger Pau Monné ****************************************************************************** 693a9fd824SRoger Pau Monné * Future extensions to the existing protocol may include: 703a9fd824SRoger Pau Monné * o display/connector cloning 713a9fd824SRoger Pau Monné * o allocation of objects other than display buffers 723a9fd824SRoger Pau Monné * o plane/overlay support 733a9fd824SRoger Pau Monné * o scaling support 743a9fd824SRoger Pau Monné * o rotation support 753a9fd824SRoger Pau Monné * 763a9fd824SRoger Pau Monné ****************************************************************************** 773a9fd824SRoger Pau Monné * Feature and Parameter Negotiation 783a9fd824SRoger Pau Monné ****************************************************************************** 793a9fd824SRoger Pau Monné * 803a9fd824SRoger Pau Monné * Front->back notifications: when enqueuing a new request, sending a 813a9fd824SRoger Pau Monné * notification can be made conditional on xendispl_req (i.e., the generic 823a9fd824SRoger Pau Monné * hold-off mechanism provided by the ring macros). Backends must set 833a9fd824SRoger Pau Monné * xendispl_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()). 843a9fd824SRoger Pau Monné * 853a9fd824SRoger Pau Monné * Back->front notifications: when enqueuing a new response, sending a 863a9fd824SRoger Pau Monné * notification can be made conditional on xendispl_resp (i.e., the generic 873a9fd824SRoger Pau Monné * hold-off mechanism provided by the ring macros). Frontends must set 883a9fd824SRoger Pau Monné * xendispl_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()). 893a9fd824SRoger Pau Monné * 903a9fd824SRoger Pau Monné * The two halves of a para-virtual display driver utilize nodes within 913a9fd824SRoger Pau Monné * XenStore to communicate capabilities and to negotiate operating parameters. 923a9fd824SRoger Pau Monné * This section enumerates these nodes which reside in the respective front and 933a9fd824SRoger Pau Monné * backend portions of XenStore, following the XenBus convention. 943a9fd824SRoger Pau Monné * 953a9fd824SRoger Pau Monné * All data in XenStore is stored as strings. Nodes specifying numeric 963a9fd824SRoger Pau Monné * values are encoded in decimal. Integer value ranges listed below are 973a9fd824SRoger Pau Monné * expressed as fixed sized integer types capable of storing the conversion 983a9fd824SRoger Pau Monné * of a properly formated node string, without loss of information. 993a9fd824SRoger Pau Monné * 1003a9fd824SRoger Pau Monné ****************************************************************************** 1013a9fd824SRoger Pau Monné * Example configuration 1023a9fd824SRoger Pau Monné ****************************************************************************** 1033a9fd824SRoger Pau Monné * 1043a9fd824SRoger Pau Monné * Note: depending on the use-case backend can expose more display connectors 1053a9fd824SRoger Pau Monné * than the underlying HW physically has by employing SW graphics compositors 1063a9fd824SRoger Pau Monné * 1073a9fd824SRoger Pau Monné * This is an example of backend and frontend configuration: 1083a9fd824SRoger Pau Monné * 1093a9fd824SRoger Pau Monné *--------------------------------- Backend ----------------------------------- 1103a9fd824SRoger Pau Monné * 1113a9fd824SRoger Pau Monné * /local/domain/0/backend/vdispl/1/0/frontend-id = "1" 1123a9fd824SRoger Pau Monné * /local/domain/0/backend/vdispl/1/0/frontend = "/local/domain/1/device/vdispl/0" 1133a9fd824SRoger Pau Monné * /local/domain/0/backend/vdispl/1/0/state = "4" 1143a9fd824SRoger Pau Monné * /local/domain/0/backend/vdispl/1/0/versions = "1,2" 1153a9fd824SRoger Pau Monné * 1163a9fd824SRoger Pau Monné *--------------------------------- Frontend ---------------------------------- 1173a9fd824SRoger Pau Monné * 1183a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/backend-id = "0" 1193a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/backend = "/local/domain/0/backend/vdispl/1/0" 1203a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/state = "4" 1213a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/version = "1" 1223a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/be-alloc = "1" 1233a9fd824SRoger Pau Monné * 1243a9fd824SRoger Pau Monné *-------------------------- Connector 0 configuration ------------------------ 1253a9fd824SRoger Pau Monné * 1263a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/0/resolution = "1920x1080" 1273a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/0/req-ring-ref = "2832" 1283a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/0/req-event-channel = "15" 1293a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/0/evt-ring-ref = "387" 1303a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/0/evt-event-channel = "16" 1313a9fd824SRoger Pau Monné * 1323a9fd824SRoger Pau Monné *-------------------------- Connector 1 configuration ------------------------ 1333a9fd824SRoger Pau Monné * 1343a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/1/resolution = "800x600" 1353a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/1/req-ring-ref = "2833" 1363a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/1/req-event-channel = "17" 1373a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/1/evt-ring-ref = "388" 1383a9fd824SRoger Pau Monné * /local/domain/1/device/vdispl/0/1/evt-event-channel = "18" 1393a9fd824SRoger Pau Monné * 1403a9fd824SRoger Pau Monné ****************************************************************************** 1413a9fd824SRoger Pau Monné * Backend XenBus Nodes 1423a9fd824SRoger Pau Monné ****************************************************************************** 1433a9fd824SRoger Pau Monné * 1443a9fd824SRoger Pau Monné *----------------------------- Protocol version ------------------------------ 1453a9fd824SRoger Pau Monné * 1463a9fd824SRoger Pau Monné * versions 1473a9fd824SRoger Pau Monné * Values: <string> 1483a9fd824SRoger Pau Monné * 1493a9fd824SRoger Pau Monné * List of XENDISPL_LIST_SEPARATOR separated protocol versions supported 1503a9fd824SRoger Pau Monné * by the backend. For example "1,2,3". 1513a9fd824SRoger Pau Monné * 1523a9fd824SRoger Pau Monné ****************************************************************************** 1533a9fd824SRoger Pau Monné * Frontend XenBus Nodes 1543a9fd824SRoger Pau Monné ****************************************************************************** 1553a9fd824SRoger Pau Monné * 1563a9fd824SRoger Pau Monné *-------------------------------- Addressing --------------------------------- 1573a9fd824SRoger Pau Monné * 1583a9fd824SRoger Pau Monné * dom-id 1593a9fd824SRoger Pau Monné * Values: <uint16_t> 1603a9fd824SRoger Pau Monné * 1613a9fd824SRoger Pau Monné * Domain identifier. 1623a9fd824SRoger Pau Monné * 1633a9fd824SRoger Pau Monné * dev-id 1643a9fd824SRoger Pau Monné * Values: <uint16_t> 1653a9fd824SRoger Pau Monné * 1663a9fd824SRoger Pau Monné * Device identifier. 1673a9fd824SRoger Pau Monné * 1683a9fd824SRoger Pau Monné * conn-idx 1693a9fd824SRoger Pau Monné * Values: <uint8_t> 1703a9fd824SRoger Pau Monné * 1713a9fd824SRoger Pau Monné * Zero based contigous index of the connector. 1723a9fd824SRoger Pau Monné * /local/domain/<dom-id>/device/vdispl/<dev-id>/<conn-idx>/... 1733a9fd824SRoger Pau Monné * 1743a9fd824SRoger Pau Monné *----------------------------- Protocol version ------------------------------ 1753a9fd824SRoger Pau Monné * 1763a9fd824SRoger Pau Monné * version 1773a9fd824SRoger Pau Monné * Values: <string> 1783a9fd824SRoger Pau Monné * 1793a9fd824SRoger Pau Monné * Protocol version, chosen among the ones supported by the backend. 1803a9fd824SRoger Pau Monné * 1813a9fd824SRoger Pau Monné *------------------------- Backend buffer allocation ------------------------- 1823a9fd824SRoger Pau Monné * 1833a9fd824SRoger Pau Monné * be-alloc 1843a9fd824SRoger Pau Monné * Values: "0", "1" 1853a9fd824SRoger Pau Monné * 1863a9fd824SRoger Pau Monné * If value is set to "1", then backend can be a buffer provider/allocator 1873a9fd824SRoger Pau Monné * for this domain during XENDISPL_OP_DBUF_CREATE operation (see below 1883a9fd824SRoger Pau Monné * for negotiation). 1893a9fd824SRoger Pau Monné * If value is not "1" or omitted frontend must allocate buffers itself. 1903a9fd824SRoger Pau Monné * 1913a9fd824SRoger Pau Monné *----------------------------- Connector settings ---------------------------- 1923a9fd824SRoger Pau Monné * 1933a9fd824SRoger Pau Monné * unique-id 1943a9fd824SRoger Pau Monné * Values: <string> 1953a9fd824SRoger Pau Monné * 1963a9fd824SRoger Pau Monné * After device instance initialization each connector is assigned a 1973a9fd824SRoger Pau Monné * unique ID, so it can be identified by the backend by this ID. 1983a9fd824SRoger Pau Monné * This can be UUID or such. 1993a9fd824SRoger Pau Monné * 2003a9fd824SRoger Pau Monné * resolution 2013a9fd824SRoger Pau Monné * Values: <width, uint32_t>x<height, uint32_t> 2023a9fd824SRoger Pau Monné * 2033a9fd824SRoger Pau Monné * Width and height of the connector in pixels separated by 2043a9fd824SRoger Pau Monné * XENDISPL_RESOLUTION_SEPARATOR. This defines visible area of the 2053a9fd824SRoger Pau Monné * display. 2063a9fd824SRoger Pau Monné * If backend provides extended display identification data (EDID) with 2073a9fd824SRoger Pau Monné * XENDISPL_OP_GET_EDID request then EDID values must take precedence 2083a9fd824SRoger Pau Monné * over the resolutions defined here. 2093a9fd824SRoger Pau Monné * 2103a9fd824SRoger Pau Monné *------------------ Connector Request Transport Parameters ------------------- 2113a9fd824SRoger Pau Monné * 2123a9fd824SRoger Pau Monné * This communication path is used to deliver requests from frontend to backend 2133a9fd824SRoger Pau Monné * and get the corresponding responses from backend to frontend, 2143a9fd824SRoger Pau Monné * set up per connector. 2153a9fd824SRoger Pau Monné * 2163a9fd824SRoger Pau Monné * req-event-channel 2173a9fd824SRoger Pau Monné * Values: <uint32_t> 2183a9fd824SRoger Pau Monné * 2193a9fd824SRoger Pau Monné * The identifier of the Xen connector's control event channel 2203a9fd824SRoger Pau Monné * used to signal activity in the ring buffer. 2213a9fd824SRoger Pau Monné * 2223a9fd824SRoger Pau Monné * req-ring-ref 2233a9fd824SRoger Pau Monné * Values: <uint32_t> 2243a9fd824SRoger Pau Monné * 2253a9fd824SRoger Pau Monné * The Xen grant reference granting permission for the backend to map 2263a9fd824SRoger Pau Monné * a sole page of connector's control ring buffer. 2273a9fd824SRoger Pau Monné * 2283a9fd824SRoger Pau Monné *------------------- Connector Event Transport Parameters -------------------- 2293a9fd824SRoger Pau Monné * 2303a9fd824SRoger Pau Monné * This communication path is used to deliver asynchronous events from backend 2313a9fd824SRoger Pau Monné * to frontend, set up per connector. 2323a9fd824SRoger Pau Monné * 2333a9fd824SRoger Pau Monné * evt-event-channel 2343a9fd824SRoger Pau Monné * Values: <uint32_t> 2353a9fd824SRoger Pau Monné * 2363a9fd824SRoger Pau Monné * The identifier of the Xen connector's event channel 2373a9fd824SRoger Pau Monné * used to signal activity in the ring buffer. 2383a9fd824SRoger Pau Monné * 2393a9fd824SRoger Pau Monné * evt-ring-ref 2403a9fd824SRoger Pau Monné * Values: <uint32_t> 2413a9fd824SRoger Pau Monné * 2423a9fd824SRoger Pau Monné * The Xen grant reference granting permission for the backend to map 2433a9fd824SRoger Pau Monné * a sole page of connector's event ring buffer. 2443a9fd824SRoger Pau Monné */ 2453a9fd824SRoger Pau Monné 2463a9fd824SRoger Pau Monné /* 2473a9fd824SRoger Pau Monné ****************************************************************************** 2483a9fd824SRoger Pau Monné * STATE DIAGRAMS 2493a9fd824SRoger Pau Monné ****************************************************************************** 2503a9fd824SRoger Pau Monné * 2513a9fd824SRoger Pau Monné * Tool stack creates front and back state nodes with initial state 2523a9fd824SRoger Pau Monné * XenbusStateInitialising. 2533a9fd824SRoger Pau Monné * Tool stack creates and sets up frontend display configuration 2543a9fd824SRoger Pau Monné * nodes per domain. 2553a9fd824SRoger Pau Monné * 2563a9fd824SRoger Pau Monné *-------------------------------- Normal flow -------------------------------- 2573a9fd824SRoger Pau Monné * 2583a9fd824SRoger Pau Monné * Front Back 2593a9fd824SRoger Pau Monné * ================================= ===================================== 2603a9fd824SRoger Pau Monné * XenbusStateInitialising XenbusStateInitialising 2613a9fd824SRoger Pau Monné * o Query backend device identification 2623a9fd824SRoger Pau Monné * data. 2633a9fd824SRoger Pau Monné * o Open and validate backend device. 2643a9fd824SRoger Pau Monné * | 2653a9fd824SRoger Pau Monné * | 2663a9fd824SRoger Pau Monné * V 2673a9fd824SRoger Pau Monné * XenbusStateInitWait 2683a9fd824SRoger Pau Monné * 2693a9fd824SRoger Pau Monné * o Query frontend configuration 2703a9fd824SRoger Pau Monné * o Allocate and initialize 2713a9fd824SRoger Pau Monné * event channels per configured 2723a9fd824SRoger Pau Monné * connector. 2733a9fd824SRoger Pau Monné * o Publish transport parameters 2743a9fd824SRoger Pau Monné * that will be in effect during 2753a9fd824SRoger Pau Monné * this connection. 2763a9fd824SRoger Pau Monné * | 2773a9fd824SRoger Pau Monné * | 2783a9fd824SRoger Pau Monné * V 2793a9fd824SRoger Pau Monné * XenbusStateInitialised 2803a9fd824SRoger Pau Monné * 2813a9fd824SRoger Pau Monné * o Query frontend transport parameters. 2823a9fd824SRoger Pau Monné * o Connect to the event channels. 2833a9fd824SRoger Pau Monné * | 2843a9fd824SRoger Pau Monné * | 2853a9fd824SRoger Pau Monné * V 2863a9fd824SRoger Pau Monné * XenbusStateConnected 2873a9fd824SRoger Pau Monné * 2883a9fd824SRoger Pau Monné * o Create and initialize OS 2893a9fd824SRoger Pau Monné * virtual display connectors 2903a9fd824SRoger Pau Monné * as per configuration. 2913a9fd824SRoger Pau Monné * | 2923a9fd824SRoger Pau Monné * | 2933a9fd824SRoger Pau Monné * V 2943a9fd824SRoger Pau Monné * XenbusStateConnected 2953a9fd824SRoger Pau Monné * 2963a9fd824SRoger Pau Monné * XenbusStateUnknown 2973a9fd824SRoger Pau Monné * XenbusStateClosed 2983a9fd824SRoger Pau Monné * XenbusStateClosing 2993a9fd824SRoger Pau Monné * o Remove virtual display device 3003a9fd824SRoger Pau Monné * o Remove event channels 3013a9fd824SRoger Pau Monné * | 3023a9fd824SRoger Pau Monné * | 3033a9fd824SRoger Pau Monné * V 3043a9fd824SRoger Pau Monné * XenbusStateClosed 3053a9fd824SRoger Pau Monné * 3063a9fd824SRoger Pau Monné *------------------------------- Recovery flow ------------------------------- 3073a9fd824SRoger Pau Monné * 3083a9fd824SRoger Pau Monné * In case of frontend unrecoverable errors backend handles that as 3093a9fd824SRoger Pau Monné * if frontend goes into the XenbusStateClosed state. 3103a9fd824SRoger Pau Monné * 3113a9fd824SRoger Pau Monné * In case of backend unrecoverable errors frontend tries removing 3123a9fd824SRoger Pau Monné * the virtualized device. If this is possible at the moment of error, 3133a9fd824SRoger Pau Monné * then frontend goes into the XenbusStateInitialising state and is ready for 3143a9fd824SRoger Pau Monné * new connection with backend. If the virtualized device is still in use and 3153a9fd824SRoger Pau Monné * cannot be removed, then frontend goes into the XenbusStateReconfiguring state 3163a9fd824SRoger Pau Monné * until either the virtualized device is removed or backend initiates a new 3173a9fd824SRoger Pau Monné * connection. On the virtualized device removal frontend goes into the 3183a9fd824SRoger Pau Monné * XenbusStateInitialising state. 3193a9fd824SRoger Pau Monné * 3203a9fd824SRoger Pau Monné * Note on XenbusStateReconfiguring state of the frontend: if backend has 3213a9fd824SRoger Pau Monné * unrecoverable errors then frontend cannot send requests to the backend 3223a9fd824SRoger Pau Monné * and thus cannot provide functionality of the virtualized device anymore. 3233a9fd824SRoger Pau Monné * After backend is back to normal the virtualized device may still hold some 3243a9fd824SRoger Pau Monné * state: configuration in use, allocated buffers, client application state etc. 3253a9fd824SRoger Pau Monné * In most cases, this will require frontend to implement complex recovery 3263a9fd824SRoger Pau Monné * reconnect logic. Instead, by going into XenbusStateReconfiguring state, 3273a9fd824SRoger Pau Monné * frontend will make sure no new clients of the virtualized device are 3283a9fd824SRoger Pau Monné * accepted, allow existing client(s) to exit gracefully by signaling error 3293a9fd824SRoger Pau Monné * state etc. 3303a9fd824SRoger Pau Monné * Once all the clients are gone frontend can reinitialize the virtualized 3313a9fd824SRoger Pau Monné * device and get into XenbusStateInitialising state again signaling the 3323a9fd824SRoger Pau Monné * backend that a new connection can be made. 3333a9fd824SRoger Pau Monné * 3343a9fd824SRoger Pau Monné * There are multiple conditions possible under which frontend will go from 3353a9fd824SRoger Pau Monné * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS 3363a9fd824SRoger Pau Monné * specific. For example: 3373a9fd824SRoger Pau Monné * 1. The underlying OS framework may provide callbacks to signal that the last 3383a9fd824SRoger Pau Monné * client of the virtualized device has gone and the device can be removed 3393a9fd824SRoger Pau Monné * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue) 3403a9fd824SRoger Pau Monné * to periodically check if this is the right time to re-try removal of 3413a9fd824SRoger Pau Monné * the virtualized device. 3423a9fd824SRoger Pau Monné * 3. By any other means. 3433a9fd824SRoger Pau Monné * 3443a9fd824SRoger Pau Monné ****************************************************************************** 3453a9fd824SRoger Pau Monné * REQUEST CODES 3463a9fd824SRoger Pau Monné ****************************************************************************** 3473a9fd824SRoger Pau Monné * Request codes [0; 15] are reserved and must not be used 3483a9fd824SRoger Pau Monné */ 3493a9fd824SRoger Pau Monné 3503a9fd824SRoger Pau Monné #define XENDISPL_OP_DBUF_CREATE 0x10 3513a9fd824SRoger Pau Monné #define XENDISPL_OP_DBUF_DESTROY 0x11 3523a9fd824SRoger Pau Monné #define XENDISPL_OP_FB_ATTACH 0x12 3533a9fd824SRoger Pau Monné #define XENDISPL_OP_FB_DETACH 0x13 3543a9fd824SRoger Pau Monné #define XENDISPL_OP_SET_CONFIG 0x14 3553a9fd824SRoger Pau Monné #define XENDISPL_OP_PG_FLIP 0x15 3563a9fd824SRoger Pau Monné /* The below command is available in protocol version 2 and above. */ 3573a9fd824SRoger Pau Monné #define XENDISPL_OP_GET_EDID 0x16 3583a9fd824SRoger Pau Monné 3593a9fd824SRoger Pau Monné /* 3603a9fd824SRoger Pau Monné ****************************************************************************** 3613a9fd824SRoger Pau Monné * EVENT CODES 3623a9fd824SRoger Pau Monné ****************************************************************************** 3633a9fd824SRoger Pau Monné */ 3643a9fd824SRoger Pau Monné #define XENDISPL_EVT_PG_FLIP 0x00 3653a9fd824SRoger Pau Monné 3663a9fd824SRoger Pau Monné /* 3673a9fd824SRoger Pau Monné ****************************************************************************** 3683a9fd824SRoger Pau Monné * XENSTORE FIELD AND PATH NAME STRINGS, HELPERS 3693a9fd824SRoger Pau Monné ****************************************************************************** 3703a9fd824SRoger Pau Monné */ 3713a9fd824SRoger Pau Monné #define XENDISPL_DRIVER_NAME "vdispl" 3723a9fd824SRoger Pau Monné 3733a9fd824SRoger Pau Monné #define XENDISPL_LIST_SEPARATOR "," 3743a9fd824SRoger Pau Monné #define XENDISPL_RESOLUTION_SEPARATOR "x" 3753a9fd824SRoger Pau Monné 3763a9fd824SRoger Pau Monné #define XENDISPL_FIELD_BE_VERSIONS "versions" 3773a9fd824SRoger Pau Monné #define XENDISPL_FIELD_FE_VERSION "version" 3783a9fd824SRoger Pau Monné #define XENDISPL_FIELD_REQ_RING_REF "req-ring-ref" 3793a9fd824SRoger Pau Monné #define XENDISPL_FIELD_REQ_CHANNEL "req-event-channel" 3803a9fd824SRoger Pau Monné #define XENDISPL_FIELD_EVT_RING_REF "evt-ring-ref" 3813a9fd824SRoger Pau Monné #define XENDISPL_FIELD_EVT_CHANNEL "evt-event-channel" 3823a9fd824SRoger Pau Monné #define XENDISPL_FIELD_RESOLUTION "resolution" 3833a9fd824SRoger Pau Monné #define XENDISPL_FIELD_BE_ALLOC "be-alloc" 3843a9fd824SRoger Pau Monné #define XENDISPL_FIELD_UNIQUE_ID "unique-id" 3853a9fd824SRoger Pau Monné 3863a9fd824SRoger Pau Monné #define XENDISPL_EDID_BLOCK_SIZE 128 3873a9fd824SRoger Pau Monné #define XENDISPL_EDID_BLOCK_COUNT 256 3883a9fd824SRoger Pau Monné #define XENDISPL_EDID_MAX_SIZE (XENDISPL_EDID_BLOCK_SIZE * XENDISPL_EDID_BLOCK_COUNT) 3893a9fd824SRoger Pau Monné 3903a9fd824SRoger Pau Monné /* 3913a9fd824SRoger Pau Monné ****************************************************************************** 3923a9fd824SRoger Pau Monné * STATUS RETURN CODES 3933a9fd824SRoger Pau Monné ****************************************************************************** 3943a9fd824SRoger Pau Monné * 3953a9fd824SRoger Pau Monné * Status return code is zero on success and -XEN_EXX on failure. 3963a9fd824SRoger Pau Monné * 3973a9fd824SRoger Pau Monné ****************************************************************************** 3983a9fd824SRoger Pau Monné * Assumptions 3993a9fd824SRoger Pau Monné ****************************************************************************** 4003a9fd824SRoger Pau Monné * o usage of grant reference 0 as invalid grant reference: 4013a9fd824SRoger Pau Monné * grant reference 0 is valid, but never exposed to a PV driver, 4023a9fd824SRoger Pau Monné * because of the fact it is already in use/reserved by the PV console. 4033a9fd824SRoger Pau Monné * o all references in this document to page sizes must be treated 4043a9fd824SRoger Pau Monné * as pages of size XEN_PAGE_SIZE unless otherwise noted. 4053a9fd824SRoger Pau Monné * 4063a9fd824SRoger Pau Monné ****************************************************************************** 4073a9fd824SRoger Pau Monné * Description of the protocol between frontend and backend driver 4083a9fd824SRoger Pau Monné ****************************************************************************** 4093a9fd824SRoger Pau Monné * 4103a9fd824SRoger Pau Monné * The two halves of a Para-virtual display driver communicate with 4113a9fd824SRoger Pau Monné * each other using shared pages and event channels. 4123a9fd824SRoger Pau Monné * Shared page contains a ring with request/response packets. 4133a9fd824SRoger Pau Monné * 4143a9fd824SRoger Pau Monné * All reserved fields in the structures below must be 0. 4153a9fd824SRoger Pau Monné * Display buffers's cookie of value 0 is treated as invalid. 4163a9fd824SRoger Pau Monné * Framebuffer's cookie of value 0 is treated as invalid. 4173a9fd824SRoger Pau Monné * 4183a9fd824SRoger Pau Monné * For all request/response/event packets that use cookies: 4193a9fd824SRoger Pau Monné * dbuf_cookie - uint64_t, unique to guest domain value used by the backend 4203a9fd824SRoger Pau Monné * to map remote display buffer to its local one 4213a9fd824SRoger Pau Monné * fb_cookie - uint64_t, unique to guest domain value used by the backend 4223a9fd824SRoger Pau Monné * to map remote framebuffer to its local one 4233a9fd824SRoger Pau Monné * 4243a9fd824SRoger Pau Monné *---------------------------------- Requests --------------------------------- 4253a9fd824SRoger Pau Monné * 4263a9fd824SRoger Pau Monné * All requests/responses, which are not connector specific, must be sent over 4273a9fd824SRoger Pau Monné * control ring of the connector which has the index value of 0: 4283a9fd824SRoger Pau Monné * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref 4293a9fd824SRoger Pau Monné * 4303a9fd824SRoger Pau Monné * All request packets have the same length (64 octets) 4313a9fd824SRoger Pau Monné * All request packets have common header: 4323a9fd824SRoger Pau Monné * 0 1 2 3 octet 4333a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4343a9fd824SRoger Pau Monné * | id | operation | reserved | 4 4353a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4363a9fd824SRoger Pau Monné * | reserved | 8 4373a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4383a9fd824SRoger Pau Monné * id - uint16_t, private guest value, echoed in response 4393a9fd824SRoger Pau Monné * operation - uint8_t, operation code, XENDISPL_OP_??? 4403a9fd824SRoger Pau Monné * 4413a9fd824SRoger Pau Monné * Request dbuf creation - request creation of a display buffer. 4423a9fd824SRoger Pau Monné * 0 1 2 3 octet 4433a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4443a9fd824SRoger Pau Monné * | id |_OP_DBUF_CREATE | reserved | 4 4453a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4463a9fd824SRoger Pau Monné * | reserved | 8 4473a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4483a9fd824SRoger Pau Monné * | dbuf_cookie low 32-bit | 12 4493a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4503a9fd824SRoger Pau Monné * | dbuf_cookie high 32-bit | 16 4513a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4523a9fd824SRoger Pau Monné * | width | 20 4533a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4543a9fd824SRoger Pau Monné * | height | 24 4553a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4563a9fd824SRoger Pau Monné * | bpp | 28 4573a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4583a9fd824SRoger Pau Monné * | buffer_sz | 32 4593a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4603a9fd824SRoger Pau Monné * | flags | 36 4613a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4623a9fd824SRoger Pau Monné * | gref_directory | 40 4633a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4643a9fd824SRoger Pau Monné * | data_ofs | 44 4653a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4663a9fd824SRoger Pau Monné * | reserved | 48 4673a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4683a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 4693a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4703a9fd824SRoger Pau Monné * | reserved | 64 4713a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 4723a9fd824SRoger Pau Monné * 4733a9fd824SRoger Pau Monné * Must be sent over control ring of the connector which has the index 4743a9fd824SRoger Pau Monné * value of 0: 4753a9fd824SRoger Pau Monné * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref 4763a9fd824SRoger Pau Monné * All unused bits in flags field must be set to 0. 4773a9fd824SRoger Pau Monné * 4783a9fd824SRoger Pau Monné * An attempt to create multiple display buffers with the same dbuf_cookie is 4793a9fd824SRoger Pau Monné * an error. dbuf_cookie can be re-used after destroying the corresponding 4803a9fd824SRoger Pau Monné * display buffer. 4813a9fd824SRoger Pau Monné * 4823a9fd824SRoger Pau Monné * Width and height of the display buffers can be smaller, equal or bigger 4833a9fd824SRoger Pau Monné * than the connector's resolution. Depth/pixel format of the individual 4843a9fd824SRoger Pau Monné * buffers can differ as well. 4853a9fd824SRoger Pau Monné * 4863a9fd824SRoger Pau Monné * width - uint32_t, width in pixels 4873a9fd824SRoger Pau Monné * height - uint32_t, height in pixels 4883a9fd824SRoger Pau Monné * bpp - uint32_t, bits per pixel 4893a9fd824SRoger Pau Monné * buffer_sz - uint32_t, buffer size to be allocated, octets 4903a9fd824SRoger Pau Monné * flags - uint32_t, flags of the operation 4913a9fd824SRoger Pau Monné * o XENDISPL_DBUF_FLG_REQ_ALLOC - if set, then backend is requested 4923a9fd824SRoger Pau Monné * to allocate the buffer with the parameters provided in this request. 4933a9fd824SRoger Pau Monné * Page directory is handled as follows: 4943a9fd824SRoger Pau Monné * Frontend on request: 4953a9fd824SRoger Pau Monné * o allocates pages for the directory (gref_directory, 4963a9fd824SRoger Pau Monné * gref_dir_next_page(s) 4973a9fd824SRoger Pau Monné * o grants permissions for the pages of the directory to the backend 4983a9fd824SRoger Pau Monné * o sets gref_dir_next_page fields 4993a9fd824SRoger Pau Monné * Backend on response: 5003a9fd824SRoger Pau Monné * o grants permissions for the pages of the buffer allocated to 5013a9fd824SRoger Pau Monné * the frontend 5023a9fd824SRoger Pau Monné * o fills in page directory with grant references 5033a9fd824SRoger Pau Monné * (gref[] in struct xendispl_page_directory) 5043a9fd824SRoger Pau Monné * gref_directory - grant_ref_t, a reference to the first shared page 5053a9fd824SRoger Pau Monné * describing shared buffer references. At least one page exists. If shared 5063a9fd824SRoger Pau Monné * buffer size (buffer_sz) exceeds what can be addressed by this single page, 5073a9fd824SRoger Pau Monné * then reference to the next page must be supplied (see gref_dir_next_page 5083a9fd824SRoger Pau Monné * below) 5093a9fd824SRoger Pau Monné * data_ofs - uint32_t, offset of the data in the buffer, octets 5103a9fd824SRoger Pau Monné */ 5113a9fd824SRoger Pau Monné 5123a9fd824SRoger Pau Monné #define XENDISPL_DBUF_FLG_REQ_ALLOC (1 << 0) 5133a9fd824SRoger Pau Monné 5143a9fd824SRoger Pau Monné struct xendispl_dbuf_create_req { 5153a9fd824SRoger Pau Monné uint64_t dbuf_cookie; 5163a9fd824SRoger Pau Monné uint32_t width; 5173a9fd824SRoger Pau Monné uint32_t height; 5183a9fd824SRoger Pau Monné uint32_t bpp; 5193a9fd824SRoger Pau Monné uint32_t buffer_sz; 5203a9fd824SRoger Pau Monné uint32_t flags; 5213a9fd824SRoger Pau Monné grant_ref_t gref_directory; 5223a9fd824SRoger Pau Monné uint32_t data_ofs; 5233a9fd824SRoger Pau Monné }; 5243a9fd824SRoger Pau Monné 5253a9fd824SRoger Pau Monné /* 5263a9fd824SRoger Pau Monné * Shared page for XENDISPL_OP_DBUF_CREATE buffer descriptor (gref_directory in 5273a9fd824SRoger Pau Monné * the request) employs a list of pages, describing all pages of the shared 5283a9fd824SRoger Pau Monné * data buffer: 5293a9fd824SRoger Pau Monné * 0 1 2 3 octet 5303a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5313a9fd824SRoger Pau Monné * | gref_dir_next_page | 4 5323a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5333a9fd824SRoger Pau Monné * | gref[0] | 8 5343a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5353a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 5363a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5373a9fd824SRoger Pau Monné * | gref[i] | i*4+8 5383a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5393a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 5403a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5413a9fd824SRoger Pau Monné * | gref[N - 1] | N*4+8 5423a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5433a9fd824SRoger Pau Monné * 5443a9fd824SRoger Pau Monné * gref_dir_next_page - grant_ref_t, reference to the next page describing 5453a9fd824SRoger Pau Monné * page directory. Must be 0 if there are no more pages in the list. 5463a9fd824SRoger Pau Monné * gref[i] - grant_ref_t, reference to a shared page of the buffer 5473a9fd824SRoger Pau Monné * allocated at XENDISPL_OP_DBUF_CREATE 5483a9fd824SRoger Pau Monné * 5493a9fd824SRoger Pau Monné * Number of grant_ref_t entries in the whole page directory is not 5503a9fd824SRoger Pau Monné * passed, but instead can be calculated as: 5513a9fd824SRoger Pau Monné * num_grefs_total = (XENDISPL_OP_DBUF_CREATE.buffer_sz + XEN_PAGE_SIZE - 1) / 5523a9fd824SRoger Pau Monné * XEN_PAGE_SIZE 5533a9fd824SRoger Pau Monné */ 5543a9fd824SRoger Pau Monné 5553a9fd824SRoger Pau Monné struct xendispl_page_directory { 5563a9fd824SRoger Pau Monné grant_ref_t gref_dir_next_page; 5573a9fd824SRoger Pau Monné grant_ref_t gref[1]; /* Variable length */ 5583a9fd824SRoger Pau Monné }; 5593a9fd824SRoger Pau Monné 5603a9fd824SRoger Pau Monné /* 5613a9fd824SRoger Pau Monné * Request dbuf destruction - destroy a previously allocated display buffer: 5623a9fd824SRoger Pau Monné * 0 1 2 3 octet 5633a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5643a9fd824SRoger Pau Monné * | id |_OP_DBUF_DESTROY| reserved | 4 5653a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5663a9fd824SRoger Pau Monné * | reserved | 8 5673a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5683a9fd824SRoger Pau Monné * | dbuf_cookie low 32-bit | 12 5693a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5703a9fd824SRoger Pau Monné * | dbuf_cookie high 32-bit | 16 5713a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5723a9fd824SRoger Pau Monné * | reserved | 20 5733a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5743a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 5753a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5763a9fd824SRoger Pau Monné * | reserved | 64 5773a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5783a9fd824SRoger Pau Monné * 5793a9fd824SRoger Pau Monné * Must be sent over control ring of the connector which has the index 5803a9fd824SRoger Pau Monné * value of 0: 5813a9fd824SRoger Pau Monné * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref 5823a9fd824SRoger Pau Monné */ 5833a9fd824SRoger Pau Monné 5843a9fd824SRoger Pau Monné struct xendispl_dbuf_destroy_req { 5853a9fd824SRoger Pau Monné uint64_t dbuf_cookie; 5863a9fd824SRoger Pau Monné }; 5873a9fd824SRoger Pau Monné 5883a9fd824SRoger Pau Monné /* 5893a9fd824SRoger Pau Monné * Request framebuffer attachment - request attachment of a framebuffer to 5903a9fd824SRoger Pau Monné * previously created display buffer. 5913a9fd824SRoger Pau Monné * 0 1 2 3 octet 5923a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5933a9fd824SRoger Pau Monné * | id | _OP_FB_ATTACH | reserved | 4 5943a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5953a9fd824SRoger Pau Monné * | reserved | 8 5963a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5973a9fd824SRoger Pau Monné * | dbuf_cookie low 32-bit | 12 5983a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 5993a9fd824SRoger Pau Monné * | dbuf_cookie high 32-bit | 16 6003a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6013a9fd824SRoger Pau Monné * | fb_cookie low 32-bit | 20 6023a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6033a9fd824SRoger Pau Monné * | fb_cookie high 32-bit | 24 6043a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6053a9fd824SRoger Pau Monné * | width | 28 6063a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6073a9fd824SRoger Pau Monné * | height | 32 6083a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6093a9fd824SRoger Pau Monné * | pixel_format | 36 6103a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6113a9fd824SRoger Pau Monné * | reserved | 40 6123a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6133a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 6143a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6153a9fd824SRoger Pau Monné * | reserved | 64 6163a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6173a9fd824SRoger Pau Monné * 6183a9fd824SRoger Pau Monné * Must be sent over control ring of the connector which has the index 6193a9fd824SRoger Pau Monné * value of 0: 6203a9fd824SRoger Pau Monné * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref 6213a9fd824SRoger Pau Monné * Width and height can be smaller, equal or bigger than the connector's 6223a9fd824SRoger Pau Monné * resolution. 6233a9fd824SRoger Pau Monné * 6243a9fd824SRoger Pau Monné * An attempt to create multiple frame buffers with the same fb_cookie is 6253a9fd824SRoger Pau Monné * an error. fb_cookie can be re-used after destroying the corresponding 6263a9fd824SRoger Pau Monné * frame buffer. 6273a9fd824SRoger Pau Monné * 6283a9fd824SRoger Pau Monné * width - uint32_t, width in pixels 6293a9fd824SRoger Pau Monné * height - uint32_t, height in pixels 6303a9fd824SRoger Pau Monné * pixel_format - uint32_t, pixel format of the framebuffer, FOURCC code 6313a9fd824SRoger Pau Monné */ 6323a9fd824SRoger Pau Monné 6333a9fd824SRoger Pau Monné struct xendispl_fb_attach_req { 6343a9fd824SRoger Pau Monné uint64_t dbuf_cookie; 6353a9fd824SRoger Pau Monné uint64_t fb_cookie; 6363a9fd824SRoger Pau Monné uint32_t width; 6373a9fd824SRoger Pau Monné uint32_t height; 6383a9fd824SRoger Pau Monné uint32_t pixel_format; 6393a9fd824SRoger Pau Monné }; 6403a9fd824SRoger Pau Monné 6413a9fd824SRoger Pau Monné /* 6423a9fd824SRoger Pau Monné * Request framebuffer detach - detach a previously 6433a9fd824SRoger Pau Monné * attached framebuffer from the display buffer in request: 6443a9fd824SRoger Pau Monné * 0 1 2 3 octet 6453a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6463a9fd824SRoger Pau Monné * | id | _OP_FB_DETACH | reserved | 4 6473a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6483a9fd824SRoger Pau Monné * | reserved | 8 6493a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6503a9fd824SRoger Pau Monné * | fb_cookie low 32-bit | 12 6513a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6523a9fd824SRoger Pau Monné * | fb_cookie high 32-bit | 16 6533a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6543a9fd824SRoger Pau Monné * | reserved | 20 6553a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6563a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 6573a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6583a9fd824SRoger Pau Monné * | reserved | 64 6593a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6603a9fd824SRoger Pau Monné * 6613a9fd824SRoger Pau Monné * Must be sent over control ring of the connector which has the index 6623a9fd824SRoger Pau Monné * value of 0: 6633a9fd824SRoger Pau Monné * /local/domain/<dom-id>/device/vdispl/<dev-id>/0/req-ring-ref 6643a9fd824SRoger Pau Monné */ 6653a9fd824SRoger Pau Monné 6663a9fd824SRoger Pau Monné struct xendispl_fb_detach_req { 6673a9fd824SRoger Pau Monné uint64_t fb_cookie; 6683a9fd824SRoger Pau Monné }; 6693a9fd824SRoger Pau Monné 6703a9fd824SRoger Pau Monné /* 6713a9fd824SRoger Pau Monné * Request configuration set/reset - request to set or reset 6723a9fd824SRoger Pau Monné * the configuration/mode of the display: 6733a9fd824SRoger Pau Monné * 0 1 2 3 octet 6743a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6753a9fd824SRoger Pau Monné * | id | _OP_SET_CONFIG | reserved | 4 6763a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6773a9fd824SRoger Pau Monné * | reserved | 8 6783a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6793a9fd824SRoger Pau Monné * | fb_cookie low 32-bit | 12 6803a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6813a9fd824SRoger Pau Monné * | fb_cookie high 32-bit | 16 6823a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6833a9fd824SRoger Pau Monné * | x | 20 6843a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6853a9fd824SRoger Pau Monné * | y | 24 6863a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6873a9fd824SRoger Pau Monné * | width | 28 6883a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6893a9fd824SRoger Pau Monné * | height | 32 6903a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6913a9fd824SRoger Pau Monné * | bpp | 40 6923a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6933a9fd824SRoger Pau Monné * | reserved | 44 6943a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6953a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 6963a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6973a9fd824SRoger Pau Monné * | reserved | 64 6983a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 6993a9fd824SRoger Pau Monné * 7003a9fd824SRoger Pau Monné * Pass all zeros to reset, otherwise command is treated as 7013a9fd824SRoger Pau Monné * configuration set. 7023a9fd824SRoger Pau Monné * Framebuffer's cookie defines which framebuffer/dbuf must be 7033a9fd824SRoger Pau Monné * displayed while enabling display (applying configuration). 7043a9fd824SRoger Pau Monné * x, y, width and height are bound by the connector's resolution and must not 7053a9fd824SRoger Pau Monné * exceed it. 7063a9fd824SRoger Pau Monné * 7073a9fd824SRoger Pau Monné * x - uint32_t, starting position in pixels by X axis 7083a9fd824SRoger Pau Monné * y - uint32_t, starting position in pixels by Y axis 7093a9fd824SRoger Pau Monné * width - uint32_t, width in pixels 7103a9fd824SRoger Pau Monné * height - uint32_t, height in pixels 7113a9fd824SRoger Pau Monné * bpp - uint32_t, bits per pixel 7123a9fd824SRoger Pau Monné */ 7133a9fd824SRoger Pau Monné 7143a9fd824SRoger Pau Monné struct xendispl_set_config_req { 7153a9fd824SRoger Pau Monné uint64_t fb_cookie; 7163a9fd824SRoger Pau Monné uint32_t x; 7173a9fd824SRoger Pau Monné uint32_t y; 7183a9fd824SRoger Pau Monné uint32_t width; 7193a9fd824SRoger Pau Monné uint32_t height; 7203a9fd824SRoger Pau Monné uint32_t bpp; 7213a9fd824SRoger Pau Monné }; 7223a9fd824SRoger Pau Monné 7233a9fd824SRoger Pau Monné /* 7243a9fd824SRoger Pau Monné * Request page flip - request to flip a page identified by the framebuffer 7253a9fd824SRoger Pau Monné * cookie: 7263a9fd824SRoger Pau Monné * 0 1 2 3 octet 7273a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7283a9fd824SRoger Pau Monné * | id | _OP_PG_FLIP | reserved | 4 7293a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7303a9fd824SRoger Pau Monné * | reserved | 8 7313a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7323a9fd824SRoger Pau Monné * | fb_cookie low 32-bit | 12 7333a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7343a9fd824SRoger Pau Monné * | fb_cookie high 32-bit | 16 7353a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7363a9fd824SRoger Pau Monné * | reserved | 20 7373a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7383a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7393a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7403a9fd824SRoger Pau Monné * | reserved | 64 7413a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7423a9fd824SRoger Pau Monné */ 7433a9fd824SRoger Pau Monné 7443a9fd824SRoger Pau Monné struct xendispl_page_flip_req { 7453a9fd824SRoger Pau Monné uint64_t fb_cookie; 7463a9fd824SRoger Pau Monné }; 7473a9fd824SRoger Pau Monné 7483a9fd824SRoger Pau Monné /* 7493a9fd824SRoger Pau Monné * Request EDID - request EDID describing current connector: 7503a9fd824SRoger Pau Monné * 0 1 2 3 octet 7513a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7523a9fd824SRoger Pau Monné * | id | _OP_GET_EDID | reserved | 4 7533a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7543a9fd824SRoger Pau Monné * | buffer_sz | 8 7553a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7563a9fd824SRoger Pau Monné * | gref_directory | 12 7573a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7583a9fd824SRoger Pau Monné * | reserved | 16 7593a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7603a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 7613a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7623a9fd824SRoger Pau Monné * | reserved | 64 7633a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7643a9fd824SRoger Pau Monné * 7653a9fd824SRoger Pau Monné * Notes: 7663a9fd824SRoger Pau Monné * - This command is not available in protocol version 1 and should be 7673a9fd824SRoger Pau Monné * ignored. 7683a9fd824SRoger Pau Monné * - This request is optional and if not supported then visible area 7693a9fd824SRoger Pau Monné * is defined by the relevant XenStore's "resolution" property. 7703a9fd824SRoger Pau Monné * - Shared buffer, allocated for EDID storage, must not be less then 7713a9fd824SRoger Pau Monné * XENDISPL_EDID_MAX_SIZE octets. 7723a9fd824SRoger Pau Monné * 7733a9fd824SRoger Pau Monné * buffer_sz - uint32_t, buffer size to be allocated, octets 7743a9fd824SRoger Pau Monné * gref_directory - grant_ref_t, a reference to the first shared page 7753a9fd824SRoger Pau Monné * describing EDID buffer references. See XENDISPL_OP_DBUF_CREATE for 7763a9fd824SRoger Pau Monné * grant page directory structure (struct xendispl_page_directory). 7773a9fd824SRoger Pau Monné * 7783a9fd824SRoger Pau Monné * See response format for this request. 7793a9fd824SRoger Pau Monné */ 7803a9fd824SRoger Pau Monné 7813a9fd824SRoger Pau Monné struct xendispl_get_edid_req { 7823a9fd824SRoger Pau Monné uint32_t buffer_sz; 7833a9fd824SRoger Pau Monné grant_ref_t gref_directory; 7843a9fd824SRoger Pau Monné }; 7853a9fd824SRoger Pau Monné 7863a9fd824SRoger Pau Monné /* 7873a9fd824SRoger Pau Monné *---------------------------------- Responses -------------------------------- 7883a9fd824SRoger Pau Monné * 7893a9fd824SRoger Pau Monné * All response packets have the same length (64 octets) 7903a9fd824SRoger Pau Monné * 7913a9fd824SRoger Pau Monné * All response packets have common header: 7923a9fd824SRoger Pau Monné * 0 1 2 3 octet 7933a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7943a9fd824SRoger Pau Monné * | id | reserved | 4 7953a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7963a9fd824SRoger Pau Monné * | status | 8 7973a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 7983a9fd824SRoger Pau Monné * | reserved | 12 7993a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8003a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 8013a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8023a9fd824SRoger Pau Monné * | reserved | 64 8033a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8043a9fd824SRoger Pau Monné * 8053a9fd824SRoger Pau Monné * id - uint16_t, private guest value, echoed from request 8063a9fd824SRoger Pau Monné * status - int32_t, response status, zero on success and -XEN_EXX on failure 8073a9fd824SRoger Pau Monné * 8083a9fd824SRoger Pau Monné * 8093a9fd824SRoger Pau Monné * Get EDID response - response for XENDISPL_OP_GET_EDID: 8103a9fd824SRoger Pau Monné * 0 1 2 3 octet 8113a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8123a9fd824SRoger Pau Monné * | id | operation | reserved | 4 8133a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8143a9fd824SRoger Pau Monné * | status | 8 8153a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8163a9fd824SRoger Pau Monné * | edid_sz | 12 8173a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8183a9fd824SRoger Pau Monné * | reserved | 16 8193a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8203a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 8213a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8223a9fd824SRoger Pau Monné * | reserved | 64 8233a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8243a9fd824SRoger Pau Monné * 8253a9fd824SRoger Pau Monné * Notes: 8263a9fd824SRoger Pau Monné * - This response is not available in protocol version 1 and should be 8273a9fd824SRoger Pau Monné * ignored. 8283a9fd824SRoger Pau Monné * 8293a9fd824SRoger Pau Monné * edid_sz - uint32_t, size of the EDID, octets 8303a9fd824SRoger Pau Monné */ 8313a9fd824SRoger Pau Monné 8323a9fd824SRoger Pau Monné struct xendispl_get_edid_resp { 8333a9fd824SRoger Pau Monné uint32_t edid_sz; 8343a9fd824SRoger Pau Monné }; 8353a9fd824SRoger Pau Monné 8363a9fd824SRoger Pau Monné /* 8373a9fd824SRoger Pau Monné *----------------------------------- Events ---------------------------------- 8383a9fd824SRoger Pau Monné * 8393a9fd824SRoger Pau Monné * Events are sent via a shared page allocated by the front and propagated by 8403a9fd824SRoger Pau Monné * evt-event-channel/evt-ring-ref XenStore entries 8413a9fd824SRoger Pau Monné * All event packets have the same length (64 octets) 8423a9fd824SRoger Pau Monné * All event packets have common header: 8433a9fd824SRoger Pau Monné * 0 1 2 3 octet 8443a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8453a9fd824SRoger Pau Monné * | id | type | reserved | 4 8463a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8473a9fd824SRoger Pau Monné * | reserved | 8 8483a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8493a9fd824SRoger Pau Monné * 8503a9fd824SRoger Pau Monné * id - uint16_t, event id, may be used by front 8513a9fd824SRoger Pau Monné * type - uint8_t, type of the event 8523a9fd824SRoger Pau Monné * 8533a9fd824SRoger Pau Monné * 8543a9fd824SRoger Pau Monné * Page flip complete event - event from back to front on page flip completed: 8553a9fd824SRoger Pau Monné * 0 1 2 3 octet 8563a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8573a9fd824SRoger Pau Monné * | id | _EVT_PG_FLIP | reserved | 4 8583a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8593a9fd824SRoger Pau Monné * | reserved | 8 8603a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8613a9fd824SRoger Pau Monné * | fb_cookie low 32-bit | 12 8623a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8633a9fd824SRoger Pau Monné * | fb_cookie high 32-bit | 16 8643a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8653a9fd824SRoger Pau Monné * | reserved | 20 8663a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8673a9fd824SRoger Pau Monné * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| 8683a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8693a9fd824SRoger Pau Monné * | reserved | 64 8703a9fd824SRoger Pau Monné * +----------------+----------------+----------------+----------------+ 8713a9fd824SRoger Pau Monné */ 8723a9fd824SRoger Pau Monné 8733a9fd824SRoger Pau Monné struct xendispl_pg_flip_evt { 8743a9fd824SRoger Pau Monné uint64_t fb_cookie; 8753a9fd824SRoger Pau Monné }; 8763a9fd824SRoger Pau Monné 8773a9fd824SRoger Pau Monné struct xendispl_req { 8783a9fd824SRoger Pau Monné uint16_t id; 8793a9fd824SRoger Pau Monné uint8_t operation; 8803a9fd824SRoger Pau Monné uint8_t reserved[5]; 8813a9fd824SRoger Pau Monné union { 8823a9fd824SRoger Pau Monné struct xendispl_dbuf_create_req dbuf_create; 8833a9fd824SRoger Pau Monné struct xendispl_dbuf_destroy_req dbuf_destroy; 8843a9fd824SRoger Pau Monné struct xendispl_fb_attach_req fb_attach; 8853a9fd824SRoger Pau Monné struct xendispl_fb_detach_req fb_detach; 8863a9fd824SRoger Pau Monné struct xendispl_set_config_req set_config; 8873a9fd824SRoger Pau Monné struct xendispl_page_flip_req pg_flip; 8883a9fd824SRoger Pau Monné struct xendispl_get_edid_req get_edid; 8893a9fd824SRoger Pau Monné uint8_t reserved[56]; 8903a9fd824SRoger Pau Monné } op; 8913a9fd824SRoger Pau Monné }; 8923a9fd824SRoger Pau Monné 8933a9fd824SRoger Pau Monné struct xendispl_resp { 8943a9fd824SRoger Pau Monné uint16_t id; 8953a9fd824SRoger Pau Monné uint8_t operation; 8963a9fd824SRoger Pau Monné uint8_t reserved; 8973a9fd824SRoger Pau Monné int32_t status; 8983a9fd824SRoger Pau Monné union { 8993a9fd824SRoger Pau Monné struct xendispl_get_edid_resp get_edid; 9003a9fd824SRoger Pau Monné uint8_t reserved1[56]; 9013a9fd824SRoger Pau Monné } op; 9023a9fd824SRoger Pau Monné }; 9033a9fd824SRoger Pau Monné 9043a9fd824SRoger Pau Monné struct xendispl_evt { 9053a9fd824SRoger Pau Monné uint16_t id; 9063a9fd824SRoger Pau Monné uint8_t type; 9073a9fd824SRoger Pau Monné uint8_t reserved[5]; 9083a9fd824SRoger Pau Monné union { 9093a9fd824SRoger Pau Monné struct xendispl_pg_flip_evt pg_flip; 9103a9fd824SRoger Pau Monné uint8_t reserved[56]; 9113a9fd824SRoger Pau Monné } op; 9123a9fd824SRoger Pau Monné }; 9133a9fd824SRoger Pau Monné 9143a9fd824SRoger Pau Monné DEFINE_RING_TYPES(xen_displif, struct xendispl_req, struct xendispl_resp); 9153a9fd824SRoger Pau Monné 9163a9fd824SRoger Pau Monné /* 9173a9fd824SRoger Pau Monné ****************************************************************************** 9183a9fd824SRoger Pau Monné * Back to front events delivery 9193a9fd824SRoger Pau Monné ****************************************************************************** 9203a9fd824SRoger Pau Monné * In order to deliver asynchronous events from back to front a shared page is 9213a9fd824SRoger Pau Monné * allocated by front and its granted reference propagated to back via 9223a9fd824SRoger Pau Monné * XenStore entries (evt-ring-ref/evt-event-channel). 9233a9fd824SRoger Pau Monné * This page has a common header used by both front and back to synchronize 9243a9fd824SRoger Pau Monné * access and control event's ring buffer, while back being a producer of the 9253a9fd824SRoger Pau Monné * events and front being a consumer. The rest of the page after the header 9263a9fd824SRoger Pau Monné * is used for event packets. 9273a9fd824SRoger Pau Monné * 9283a9fd824SRoger Pau Monné * Upon reception of an event(s) front may confirm its reception 9293a9fd824SRoger Pau Monné * for either each event, group of events or none. 9303a9fd824SRoger Pau Monné */ 9313a9fd824SRoger Pau Monné 9323a9fd824SRoger Pau Monné struct xendispl_event_page { 9333a9fd824SRoger Pau Monné uint32_t in_cons; 9343a9fd824SRoger Pau Monné uint32_t in_prod; 9353a9fd824SRoger Pau Monné uint8_t reserved[56]; 9363a9fd824SRoger Pau Monné }; 9373a9fd824SRoger Pau Monné 9383a9fd824SRoger Pau Monné #define XENDISPL_EVENT_PAGE_SIZE 4096 9393a9fd824SRoger Pau Monné #define XENDISPL_IN_RING_OFFS (sizeof(struct xendispl_event_page)) 9403a9fd824SRoger Pau Monné #define XENDISPL_IN_RING_SIZE (XENDISPL_EVENT_PAGE_SIZE - XENDISPL_IN_RING_OFFS) 9413a9fd824SRoger Pau Monné #define XENDISPL_IN_RING_LEN (XENDISPL_IN_RING_SIZE / sizeof(struct xendispl_evt)) 9423a9fd824SRoger Pau Monné #define XENDISPL_IN_RING(page) \ 9433a9fd824SRoger Pau Monné ((struct xendispl_evt *)((char *)(page) + XENDISPL_IN_RING_OFFS)) 9443a9fd824SRoger Pau Monné #define XENDISPL_IN_RING_REF(page, idx) \ 9453a9fd824SRoger Pau Monné (XENDISPL_IN_RING((page))[(idx) % XENDISPL_IN_RING_LEN]) 9463a9fd824SRoger Pau Monné 9473a9fd824SRoger Pau Monné #endif /* __XEN_PUBLIC_IO_DISPLIF_H__ */ 9483a9fd824SRoger Pau Monné 9493a9fd824SRoger Pau Monné /* 9503a9fd824SRoger Pau Monné * Local variables: 9513a9fd824SRoger Pau Monné * mode: C 9523a9fd824SRoger Pau Monné * c-file-style: "BSD" 9533a9fd824SRoger Pau Monné * c-basic-offset: 4 9543a9fd824SRoger Pau Monné * tab-width: 4 9553a9fd824SRoger Pau Monné * indent-tabs-mode: nil 9563a9fd824SRoger Pau Monné * End: 9573a9fd824SRoger Pau Monné */ 958