docs/interop/vhost-user-gpu.rst

   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 VhostUserGpuEdidRequest
 128 ^^^^^^^^^^^^^^^^^^^^^^^
 129
 130 +------------+
 131 | scanout-id |
 132 +------------+
 133
 134 :scanout-id: ``u32``, the scanout to get edid from
 135
 136
 137 VhostUserGpuDMABUFScanout2
 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
 150 C structure
 151 -----------
 152
 153 In 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
 174 Protocol 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
 182 New 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
 186 Communication
 187 =============
 188
 189 Message 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.