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