1 =======================
2 Vhost-user-gpu Protocol
3 =======================
6 Licence: This work is licensed under the terms of the GNU GPL,
7 version 2 or later. See the COPYING file in the top-level
10 .. contents:: Table of Contents
15 The vhost-user-gpu protocol is aiming at sharing the rendering result
16 of a virtio-gpu, done from a vhost-user back-end process to a vhost-user
17 front-end process (such as QEMU). It bears a resemblance to a display
18 server protocol, if you consider QEMU as the display server and the
19 back-end as the client, but in a very limited way. Typically, it will
20 work by setting a scanout/display configuration, before sending flush
21 events for the display updates. It will also update the cursor shape
24 The protocol is sent over a UNIX domain stream socket, since it uses
25 socket ancillary data to share opened file descriptors (DMABUF fds or
26 shared memory). The socket is usually obtained via
27 ``VHOST_USER_GPU_SET_SOCKET``.
29 Requests are sent by the *back-end*, and the optional replies by the
35 Unless specified differently, numbers are in the machine native byte
38 A vhost-user-gpu message (request and reply) consists of 3 header
41 +---------+-------+------+---------+
42 | request | flags | size | payload |
43 +---------+-------+------+---------+
48 :request: ``u32``, type of the request
50 :flags: ``u32``, 32-bit bit field:
52 - Bit 2 is the reply flag - needs to be set on each reply
54 :size: ``u32``, size of the payload
59 Depending on the request type, **payload** can be:
64 +------------+---+---+
65 | scanout-id | x | y |
66 +------------+---+---+
68 :scanout-id: ``u32``, the scanout where the cursor is located
70 :x/y: ``u32``, the cursor position
72 VhostUserGpuCursorUpdate
73 ^^^^^^^^^^^^^^^^^^^^^^^^
75 +-----+-------+-------+--------+
76 | pos | hot_x | hot_y | cursor |
77 +-----+-------+-------+--------+
79 :pos: a ``VhostUserGpuCursorPos``, the cursor location
81 :hot_x/hot_y: ``u32``, the cursor hot location
83 :cursor: ``[u32; 64 * 64]``, 64x64 RGBA cursor data (PIXMAN_a8r8g8b8 format)
88 +------------+---+---+
89 | scanout-id | w | h |
90 +------------+---+---+
92 :scanout-id: ``u32``, the scanout configuration to set
94 :w/h: ``u32``, the scanout width/height size
99 +------------+---+---+---+---+------+
100 | scanout-id | x | y | w | h | data |
101 +------------+---+---+---+---+------+
103 :scanout-id: ``u32``, the scanout content to update
105 :x/y/w/h: ``u32``, region of the update
107 :data: RGB data (PIXMAN_x8r8g8b8 format)
109 VhostUserGpuDMABUFScanout
110 ^^^^^^^^^^^^^^^^^^^^^^^^^
112 +------------+---+---+---+---+-----+-----+--------+-------+--------+
113 | scanout-id | x | y | w | h | fdw | fwh | stride | flags | fourcc |
114 +------------+---+---+---+---+-----+-----+--------+-------+--------+
116 :scanout-id: ``u32``, the scanout configuration to set
118 :x/y: ``u32``, the location of the scanout within the DMABUF
120 :w/h: ``u32``, the scanout width/height size
122 :fdw/fdh/stride/flags: ``u32``, the DMABUF width/height/stride/flags
124 :fourcc: ``i32``, the DMABUF fourcc
127 VhostUserGpuEdidRequest
128 ^^^^^^^^^^^^^^^^^^^^^^^
134 :scanout-id: ``u32``, the scanout to get edid from
140 In QEMU the vhost-user-gpu message is implemented with the following struct:
144 typedef struct VhostUserGpuMsg {
145 uint32_t request; /* VhostUserGpuRequest */
147 uint32_t size; /* the following payload size */
149 VhostUserGpuCursorPos cursor_pos;
150 VhostUserGpuCursorUpdate cursor_update;
151 VhostUserGpuScanout scanout;
152 VhostUserGpuUpdate update;
153 VhostUserGpuDMABUFScanout dmabuf_scanout;
154 VhostUserGpuEdidRequest edid_req;
155 struct virtio_gpu_resp_edid resp_edid;
156 struct virtio_gpu_resp_display_info display_info;
159 } QEMU_PACKED VhostUserGpuMsg;
166 #define VHOST_USER_GPU_PROTOCOL_F_EDID 0
168 New messages and communication changes are negotiated thanks to the
169 ``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and
170 ``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests.
178 ``VHOST_USER_GPU_GET_PROTOCOL_FEATURES``
180 :request payload: N/A
181 :reply payload: ``u64``
183 Get the supported protocol features bitmask.
185 ``VHOST_USER_GPU_SET_PROTOCOL_FEATURES``
187 :request payload: ``u64``
190 Enable protocol features using a bitmask.
192 ``VHOST_USER_GPU_GET_DISPLAY_INFO``
194 :request payload: N/A
195 :reply payload: ``struct virtio_gpu_resp_display_info`` (from virtio specification)
197 Get the preferred display configuration.
199 ``VHOST_USER_GPU_CURSOR_POS``
201 :request payload: ``VhostUserGpuCursorPos``
204 Set/show the cursor position.
206 ``VHOST_USER_GPU_CURSOR_POS_HIDE``
208 :request payload: ``VhostUserGpuCursorPos``
213 ``VHOST_USER_GPU_CURSOR_UPDATE``
215 :request payload: ``VhostUserGpuCursorUpdate``
218 Update the cursor shape and location.
220 ``VHOST_USER_GPU_SCANOUT``
222 :request payload: ``VhostUserGpuScanout``
225 Set the scanout resolution. To disable a scanout, the dimensions
226 width/height are set to 0.
228 ``VHOST_USER_GPU_UPDATE``
230 :request payload: ``VhostUserGpuUpdate``
233 Update the scanout content. The data payload contains the graphical bits.
234 The display should be flushed and presented.
236 ``VHOST_USER_GPU_DMABUF_SCANOUT``
238 :request payload: ``VhostUserGpuDMABUFScanout``
241 Set the scanout resolution/configuration, and share a DMABUF file
242 descriptor for the scanout content, which is passed as ancillary
243 data. To disable a scanout, the dimensions width/height are set
244 to 0, there is no file descriptor passed.
246 ``VHOST_USER_GPU_DMABUF_UPDATE``
248 :request payload: ``VhostUserGpuUpdate``
249 :reply payload: empty payload
251 The display should be flushed and presented according to updated
252 region from ``VhostUserGpuUpdate``.
254 Note: there is no data payload, since the scanout is shared thanks
255 to DMABUF, that must have been set previously with
256 ``VHOST_USER_GPU_DMABUF_SCANOUT``.
258 ``VHOST_USER_GPU_GET_EDID``
260 :request payload: ``struct VhostUserGpuEdidRequest``
261 :reply payload: ``struct virtio_gpu_resp_edid`` (from virtio specification)
263 Retrieve the EDID data for a given scanout.
264 This message requires the ``VHOST_USER_GPU_PROTOCOL_F_EDID`` protocol
265 feature to be supported.