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
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``.
244