1======================= 2Vhost-user-gpu Protocol 3======================= 4 5.. 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 8 directory. 9 10.. contents:: Table of Contents 11 12Introduction 13============ 14 15The vhost-user-gpu protocol is aiming at sharing the rendering result 16of a virtio-gpu, done from a vhost-user back-end process to a vhost-user 17front-end process (such as QEMU). It bears a resemblance to a display 18server protocol, if you consider QEMU as the display server and the 19back-end as the client, but in a very limited way. Typically, it will 20work by setting a scanout/display configuration, before sending flush 21events for the display updates. It will also update the cursor shape 22and position. 23 24The protocol is sent over a UNIX domain stream socket, since it uses 25socket ancillary data to share opened file descriptors (DMABUF fds or 26shared memory). The socket is usually obtained via 27``VHOST_USER_GPU_SET_SOCKET``. 28 29Requests are sent by the *back-end*, and the optional replies by the 30*front-end*. 31 32Wire format 33=========== 34 35Unless specified differently, numbers are in the machine native byte 36order. 37 38A vhost-user-gpu message (request and reply) consists of 3 header 39fields and a payload. 40 41+---------+-------+------+---------+ 42| request | flags | size | payload | 43+---------+-------+------+---------+ 44 45Header 46------ 47 48:request: ``u32``, type of the request 49 50:flags: ``u32``, 32-bit bit field: 51 52 - Bit 2 is the reply flag - needs to be set on each reply 53 54:size: ``u32``, size of the payload 55 56Payload types 57------------- 58 59Depending on the request type, **payload** can be: 60 61VhostUserGpuCursorPos 62^^^^^^^^^^^^^^^^^^^^^ 63 64+------------+---+---+ 65| scanout-id | x | y | 66+------------+---+---+ 67 68:scanout-id: ``u32``, the scanout where the cursor is located 69 70:x/y: ``u32``, the cursor position 71 72VhostUserGpuCursorUpdate 73^^^^^^^^^^^^^^^^^^^^^^^^ 74 75+-----+-------+-------+--------+ 76| pos | hot_x | hot_y | cursor | 77+-----+-------+-------+--------+ 78 79:pos: a ``VhostUserGpuCursorPos``, the cursor location 80 81:hot_x/hot_y: ``u32``, the cursor hot location 82 83:cursor: ``[u32; 64 * 64]``, 64x64 RGBA cursor data (PIXMAN_a8r8g8b8 format) 84 85VhostUserGpuScanout 86^^^^^^^^^^^^^^^^^^^ 87 88+------------+---+---+ 89| scanout-id | w | h | 90+------------+---+---+ 91 92:scanout-id: ``u32``, the scanout configuration to set 93 94:w/h: ``u32``, the scanout width/height size 95 96VhostUserGpuUpdate 97^^^^^^^^^^^^^^^^^^ 98 99+------------+---+---+---+---+------+ 100| scanout-id | x | y | w | h | data | 101+------------+---+---+---+---+------+ 102 103:scanout-id: ``u32``, the scanout content to update 104 105:x/y/w/h: ``u32``, region of the update 106 107:data: RGB data (PIXMAN_x8r8g8b8 format) 108 109VhostUserGpuDMABUFScanout 110^^^^^^^^^^^^^^^^^^^^^^^^^ 111 112+------------+---+---+---+---+-----+-----+--------+-------+--------+ 113| scanout-id | x | y | w | h | fdw | fwh | stride | flags | fourcc | 114+------------+---+---+---+---+-----+-----+--------+-------+--------+ 115 116:scanout-id: ``u32``, the scanout configuration to set 117 118:x/y: ``u32``, the location of the scanout within the DMABUF 119 120:w/h: ``u32``, the scanout width/height size 121 122:fdw/fdh/stride/flags: ``u32``, the DMABUF width/height/stride/flags 123 124:fourcc: ``i32``, the DMABUF fourcc 125 126 127VhostUserGpuEdidRequest 128^^^^^^^^^^^^^^^^^^^^^^^ 129 130+------------+ 131| scanout-id | 132+------------+ 133 134:scanout-id: ``u32``, the scanout to get edid from 135 136 137VhostUserGpuDMABUFScanout2 138^^^^^^^^^^^^^^^^^^^^^^^^^^ 139 140+----------------+----------+ 141| dmabuf_scanout | modifier | 142+----------------+----------+ 143 144:dmabuf_scanout: ``VhostUserGpuDMABUFScanout``, filled as described in the 145 VhostUserGpuDMABUFScanout structure. 146 147:modifier: ``u64``, the DMABUF modifiers 148 149 150C structure 151----------- 152 153In QEMU the vhost-user-gpu message is implemented with the following struct: 154 155.. code:: c 156 157 typedef struct VhostUserGpuMsg { 158 uint32_t request; /* VhostUserGpuRequest */ 159 uint32_t flags; 160 uint32_t size; /* the following payload size */ 161 union { 162 VhostUserGpuCursorPos cursor_pos; 163 VhostUserGpuCursorUpdate cursor_update; 164 VhostUserGpuScanout scanout; 165 VhostUserGpuUpdate update; 166 VhostUserGpuDMABUFScanout dmabuf_scanout; 167 VhostUserGpuEdidRequest edid_req; 168 struct virtio_gpu_resp_edid resp_edid; 169 struct virtio_gpu_resp_display_info display_info; 170 uint64_t u64; 171 } payload; 172 } QEMU_PACKED VhostUserGpuMsg; 173 174Protocol features 175----------------- 176 177.. code:: c 178 179 #define VHOST_USER_GPU_PROTOCOL_F_EDID 0 180 #define VHOST_USER_GPU_PROTOCOL_F_DMABUF2 1 181 182New messages and communication changes are negotiated thanks to the 183``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and 184``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests. 185 186Communication 187============= 188 189Message types 190------------- 191 192``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` 193 :id: 1 194 :request payload: N/A 195 :reply payload: ``u64`` 196 197 Get the supported protocol features bitmask. 198 199``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` 200 :id: 2 201 :request payload: ``u64`` 202 :reply payload: N/A 203 204 Enable protocol features using a bitmask. 205 206``VHOST_USER_GPU_GET_DISPLAY_INFO`` 207 :id: 3 208 :request payload: N/A 209 :reply payload: ``struct virtio_gpu_resp_display_info`` (from virtio specification) 210 211 Get the preferred display configuration. 212 213``VHOST_USER_GPU_CURSOR_POS`` 214 :id: 4 215 :request payload: ``VhostUserGpuCursorPos`` 216 :reply payload: N/A 217 218 Set/show the cursor position. 219 220``VHOST_USER_GPU_CURSOR_POS_HIDE`` 221 :id: 5 222 :request payload: ``VhostUserGpuCursorPos`` 223 :reply payload: N/A 224 225 Set/hide the cursor. 226 227``VHOST_USER_GPU_CURSOR_UPDATE`` 228 :id: 6 229 :request payload: ``VhostUserGpuCursorUpdate`` 230 :reply payload: N/A 231 232 Update the cursor shape and location. 233 234``VHOST_USER_GPU_SCANOUT`` 235 :id: 7 236 :request payload: ``VhostUserGpuScanout`` 237 :reply payload: N/A 238 239 Set the scanout resolution. To disable a scanout, the dimensions 240 width/height are set to 0. 241 242``VHOST_USER_GPU_UPDATE`` 243 :id: 8 244 :request payload: ``VhostUserGpuUpdate`` 245 :reply payload: N/A 246 247 Update the scanout content. The data payload contains the graphical bits. 248 The display should be flushed and presented. 249 250``VHOST_USER_GPU_DMABUF_SCANOUT`` 251 :id: 9 252 :request payload: ``VhostUserGpuDMABUFScanout`` 253 :reply payload: N/A 254 255 Set the scanout resolution/configuration, and share a DMABUF file 256 descriptor for the scanout content, which is passed as ancillary 257 data. To disable a scanout, the dimensions width/height are set 258 to 0, there is no file descriptor passed. 259 260``VHOST_USER_GPU_DMABUF_UPDATE`` 261 :id: 10 262 :request payload: ``VhostUserGpuUpdate`` 263 :reply payload: empty payload 264 265 The display should be flushed and presented according to updated 266 region from ``VhostUserGpuUpdate``. 267 268 Note: there is no data payload, since the scanout is shared thanks 269 to DMABUF, that must have been set previously with 270 ``VHOST_USER_GPU_DMABUF_SCANOUT``. 271 272``VHOST_USER_GPU_GET_EDID`` 273 :id: 11 274 :request payload: ``struct VhostUserGpuEdidRequest`` 275 :reply payload: ``struct virtio_gpu_resp_edid`` (from virtio specification) 276 277 Retrieve the EDID data for a given scanout. 278 This message requires the ``VHOST_USER_GPU_PROTOCOL_F_EDID`` protocol 279 feature to be supported. 280 281``VHOST_USER_GPU_DMABUF_SCANOUT2`` 282 :id: 12 283 :request payload: ``VhostUserGpuDMABUFScanout2`` 284 :reply payload: N/A 285 286 Same as VHOST_USER_GPU_DMABUF_SCANOUT, but also sends the dmabuf modifiers 287 appended to the message, which were not provided in the other message. 288 This message requires the ``VHOST_USER_GPU_PROTOCOL_F_DMABUF2`` protocol 289 feature to be supported. 290