vhost-user-gpu.rst (6305B)
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 slave process to a vhost-user 17master process (such as QEMU). It bears a resemblance to a display 18server protocol, if you consider QEMU as the display server and the 19slave 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 *slave*, and the optional replies by the 30*master*. 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 127C structure 128----------- 129 130In QEMU the vhost-user-gpu message is implemented with the following struct: 131 132.. code:: c 133 134 typedef struct VhostUserGpuMsg { 135 uint32_t request; /* VhostUserGpuRequest */ 136 uint32_t flags; 137 uint32_t size; /* the following payload size */ 138 union { 139 VhostUserGpuCursorPos cursor_pos; 140 VhostUserGpuCursorUpdate cursor_update; 141 VhostUserGpuScanout scanout; 142 VhostUserGpuUpdate update; 143 VhostUserGpuDMABUFScanout dmabuf_scanout; 144 struct virtio_gpu_resp_display_info display_info; 145 uint64_t u64; 146 } payload; 147 } QEMU_PACKED VhostUserGpuMsg; 148 149Protocol features 150----------------- 151 152None yet. 153 154As the protocol may need to evolve, new messages and communication 155changes are negotiated thanks to preliminary 156``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and 157``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests. 158 159Communication 160============= 161 162Message types 163------------- 164 165``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` 166 :id: 1 167 :request payload: N/A 168 :reply payload: ``u64`` 169 170 Get the supported protocol features bitmask. 171 172``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` 173 :id: 2 174 :request payload: ``u64`` 175 :reply payload: N/A 176 177 Enable protocol features using a bitmask. 178 179``VHOST_USER_GPU_GET_DISPLAY_INFO`` 180 :id: 3 181 :request payload: N/A 182 :reply payload: ``struct virtio_gpu_resp_display_info`` (from virtio specification) 183 184 Get the preferred display configuration. 185 186``VHOST_USER_GPU_CURSOR_POS`` 187 :id: 4 188 :request payload: ``VhostUserGpuCursorPos`` 189 :reply payload: N/A 190 191 Set/show the cursor position. 192 193``VHOST_USER_GPU_CURSOR_POS_HIDE`` 194 :id: 5 195 :request payload: ``VhostUserGpuCursorPos`` 196 :reply payload: N/A 197 198 Set/hide the cursor. 199 200``VHOST_USER_GPU_CURSOR_UPDATE`` 201 :id: 6 202 :request payload: ``VhostUserGpuCursorUpdate`` 203 :reply payload: N/A 204 205 Update the cursor shape and location. 206 207``VHOST_USER_GPU_SCANOUT`` 208 :id: 7 209 :request payload: ``VhostUserGpuScanout`` 210 :reply payload: N/A 211 212 Set the scanout resolution. To disable a scanout, the dimensions 213 width/height are set to 0. 214 215``VHOST_USER_GPU_UPDATE`` 216 :id: 8 217 :request payload: ``VhostUserGpuUpdate`` 218 :reply payload: N/A 219 220 Update the scanout content. The data payload contains the graphical bits. 221 The display should be flushed and presented. 222 223``VHOST_USER_GPU_DMABUF_SCANOUT`` 224 :id: 9 225 :request payload: ``VhostUserGpuDMABUFScanout`` 226 :reply payload: N/A 227 228 Set the scanout resolution/configuration, and share a DMABUF file 229 descriptor for the scanout content, which is passed as ancillary 230 data. To disable a scanout, the dimensions width/height are set 231 to 0, there is no file descriptor passed. 232 233``VHOST_USER_GPU_DMABUF_UPDATE`` 234 :id: 10 235 :request payload: ``VhostUserGpuUpdate`` 236 :reply payload: empty payload 237 238 The display should be flushed and presented according to updated 239 region from ``VhostUserGpuUpdate``. 240 241 Note: there is no data payload, since the scanout is shared thanks 242 to DMABUF, that must have been set previously with 243 ``VHOST_USER_GPU_DMABUF_SCANOUT``.