xref: /qemu/docs/interop/vhost-user-gpu.rst (revision c01196bd) 
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
137C structure
138-----------
139
140In QEMU the vhost-user-gpu message is implemented with the following struct:
141
142.. code:: c
143
144  typedef struct VhostUserGpuMsg {
145      uint32_t request; /* VhostUserGpuRequest */
146      uint32_t flags;
147      uint32_t size; /* the following payload size */
148      union {
149          VhostUserGpuCursorPos cursor_pos;
150          VhostUserGpuCursorUpdate cursor_update;
151          VhostUserGpuScanout scanout;
152          VhostUserGpuUpdate update;
153          VhostUserGpuDMABUFScanout dmabuf_scanout;
154          VhostUserGpuEdidRequest edid_req;
155          struct virtio_gpu_resp_edid resp_edid;
156          struct virtio_gpu_resp_display_info display_info;
157          uint64_t u64;
158      } payload;
159  } QEMU_PACKED VhostUserGpuMsg;
160
161Protocol features
162-----------------
163
164.. code:: c
165
166  #define VHOST_USER_GPU_PROTOCOL_F_EDID 0
167
168New messages and communication changes are negotiated thanks to the
169``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and
170``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests.
171
172Communication
173=============
174
175Message types
176-------------
177
178``VHOST_USER_GPU_GET_PROTOCOL_FEATURES``
179  :id: 1
180  :request payload: N/A
181  :reply payload: ``u64``
182
183  Get the supported protocol features bitmask.
184
185``VHOST_USER_GPU_SET_PROTOCOL_FEATURES``
186  :id: 2
187  :request payload: ``u64``
188  :reply payload: N/A
189
190  Enable protocol features using a bitmask.
191
192``VHOST_USER_GPU_GET_DISPLAY_INFO``
193  :id: 3
194  :request payload: N/A
195  :reply payload: ``struct virtio_gpu_resp_display_info`` (from virtio specification)
196
197  Get the preferred display configuration.
198
199``VHOST_USER_GPU_CURSOR_POS``
200  :id: 4
201  :request payload: ``VhostUserGpuCursorPos``
202  :reply payload: N/A
203
204  Set/show the cursor position.
205
206``VHOST_USER_GPU_CURSOR_POS_HIDE``
207  :id: 5
208  :request payload: ``VhostUserGpuCursorPos``
209  :reply payload: N/A
210
211  Set/hide the cursor.
212
213``VHOST_USER_GPU_CURSOR_UPDATE``
214  :id: 6
215  :request payload: ``VhostUserGpuCursorUpdate``
216  :reply payload: N/A
217
218  Update the cursor shape and location.
219
220``VHOST_USER_GPU_SCANOUT``
221  :id: 7
222  :request payload: ``VhostUserGpuScanout``
223  :reply payload: N/A
224
225  Set the scanout resolution. To disable a scanout, the dimensions
226  width/height are set to 0.
227
228``VHOST_USER_GPU_UPDATE``
229  :id: 8
230  :request payload: ``VhostUserGpuUpdate``
231  :reply payload: N/A
232
233  Update the scanout content. The data payload contains the graphical bits.
234  The display should be flushed and presented.
235
236``VHOST_USER_GPU_DMABUF_SCANOUT``
237  :id: 9
238  :request payload: ``VhostUserGpuDMABUFScanout``
239  :reply payload: N/A
240
241  Set the scanout resolution/configuration, and share a DMABUF file
242  descriptor for the scanout content, which is passed as ancillary
243  data. To disable a scanout, the dimensions width/height are set
244  to 0, there is no file descriptor passed.
245
246``VHOST_USER_GPU_DMABUF_UPDATE``
247  :id: 10
248  :request payload: ``VhostUserGpuUpdate``
249  :reply payload: empty payload
250
251  The display should be flushed and presented according to updated
252  region from ``VhostUserGpuUpdate``.
253
254  Note: there is no data payload, since the scanout is shared thanks
255  to DMABUF, that must have been set previously with
256  ``VHOST_USER_GPU_DMABUF_SCANOUT``.
257
258``VHOST_USER_GPU_GET_EDID``
259  :id: 11
260  :request payload: ``struct VhostUserGpuEdidRequest``
261  :reply payload: ``struct virtio_gpu_resp_edid`` (from virtio specification)
262
263  Retrieve the EDID data for a given scanout.
264  This message requires the ``VHOST_USER_GPU_PROTOCOL_F_EDID`` protocol
265  feature to be supported.
266