vhost-user-gpu.rst (6320B)
1 ======================= 2 Vhost-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 12 Introduction 13 ============ 14 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 22 and position. 23 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``. 28 29 Requests are sent by the *back-end*, and the optional replies by the 30 *front-end*. 31 32 Wire format 33 =========== 34 35 Unless specified differently, numbers are in the machine native byte 36 order. 37 38 A vhost-user-gpu message (request and reply) consists of 3 header 39 fields and a payload. 40 41 +---------+-------+------+---------+ 42 | request | flags | size | payload | 43 +---------+-------+------+---------+ 44 45 Header 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 56 Payload types 57 ------------- 58 59 Depending on the request type, **payload** can be: 60 61 VhostUserGpuCursorPos 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 72 VhostUserGpuCursorUpdate 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 85 VhostUserGpuScanout 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 96 VhostUserGpuUpdate 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 109 VhostUserGpuDMABUFScanout 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 127 C structure 128 ----------- 129 130 In 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 149 Protocol features 150 ----------------- 151 152 None yet. 153 154 As the protocol may need to evolve, new messages and communication 155 changes are negotiated thanks to preliminary 156 ``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and 157 ``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests. 158 159 Communication 160 ============= 161 162 Message 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``.