xref: /qemu/docs/interop/vhost-user-gpu.rst (revision abff1abf) 
1=======================
2Vhost-user-gpu Protocol
3=======================
4
5:Licence: This work is licensed under the terms of the GNU GPL,
6          version 2 or later. See the COPYING file in the top-level
7          directory.
8
9.. contents:: Table of Contents
10
11Introduction
12============
13
14The vhost-user-gpu protocol is aiming at sharing the rendering result
15of a virtio-gpu, done from a vhost-user slave process to a vhost-user
16master process (such as QEMU). It bears a resemblance to a display
17server protocol, if you consider QEMU as the display server and the
18slave as the client, but in a very limited way. Typically, it will
19work by setting a scanout/display configuration, before sending flush
20events for the display updates. It will also update the cursor shape
21and position.
22
23The protocol is sent over a UNIX domain stream socket, since it uses
24socket ancillary data to share opened file descriptors (DMABUF fds or
25shared memory). The socket is usually obtained via
26``VHOST_USER_GPU_SET_SOCKET``.
27
28Requests are sent by the *slave*, and the optional replies by the
29*master*.
30
31Wire format
32===========
33
34Unless specified differently, numbers are in the machine native byte
35order.
36
37A vhost-user-gpu message (request and reply) consists of 3 header
38fields and a payload.
39
40+---------+-------+------+---------+
41| request | flags | size | payload |
42+---------+-------+------+---------+
43
44Header
45------
46
47:request: ``u32``, type of the request
48
49:flags: ``u32``, 32-bit bit field:
50
51 - Bit 2 is the reply flag - needs to be set on each reply
52
53:size: ``u32``, size of the payload
54
55Payload types
56-------------
57
58Depending on the request type, **payload** can be:
59
60VhostUserGpuCursorPos
61^^^^^^^^^^^^^^^^^^^^^
62
63+------------+---+---+
64| scanout-id | x | y |
65+------------+---+---+
66
67:scanout-id: ``u32``, the scanout where the cursor is located
68
69:x/y: ``u32``, the cursor postion
70
71VhostUserGpuCursorUpdate
72^^^^^^^^^^^^^^^^^^^^^^^^
73
74+-----+-------+-------+--------+
75| pos | hot_x | hot_y | cursor |
76+-----+-------+-------+--------+
77
78:pos: a ``VhostUserGpuCursorPos``, the cursor location
79
80:hot_x/hot_y: ``u32``, the cursor hot location
81
82:cursor: ``[u32; 64 * 64]``, 64x64 RGBA cursor data (PIXMAN_a8r8g8b8 format)
83
84VhostUserGpuScanout
85^^^^^^^^^^^^^^^^^^^
86
87+------------+---+---+
88| scanout-id | w | h |
89+------------+---+---+
90
91:scanout-id: ``u32``, the scanout configuration to set
92
93:w/h: ``u32``, the scanout width/height size
94
95VhostUserGpuUpdate
96^^^^^^^^^^^^^^^^^^
97
98+------------+---+---+---+---+------+
99| scanout-id | x | y | w | h | data |
100+------------+---+---+---+---+------+
101
102:scanout-id: ``u32``, the scanout content to update
103
104:x/y/w/h: ``u32``, region of the update
105
106:data: RGB data (PIXMAN_x8r8g8b8 format)
107
108VhostUserGpuDMABUFScanout
109^^^^^^^^^^^^^^^^^^^^^^^^^
110
111+------------+---+---+---+---+-----+-----+--------+-------+--------+
112| scanout-id | x | y | w | h | fdw | fwh | stride | flags | fourcc |
113+------------+---+---+---+---+-----+-----+--------+-------+--------+
114
115:scanout-id: ``u32``, the scanout configuration to set
116
117:x/y: ``u32``, the location of the scanout within the DMABUF
118
119:w/h: ``u32``, the scanout width/height size
120
121:fdw/fdh/stride/flags: ``u32``, the DMABUF width/height/stride/flags
122
123:fourcc: ``i32``, the DMABUF fourcc
124
125
126C structure
127-----------
128
129In QEMU the vhost-user-gpu message is implemented with the following struct:
130
131.. code:: c
132
133  typedef struct VhostUserGpuMsg {
134      uint32_t request; /* VhostUserGpuRequest */
135      uint32_t flags;
136      uint32_t size; /* the following payload size */
137      union {
138          VhostUserGpuCursorPos cursor_pos;
139          VhostUserGpuCursorUpdate cursor_update;
140          VhostUserGpuScanout scanout;
141          VhostUserGpuUpdate update;
142          VhostUserGpuDMABUFScanout dmabuf_scanout;
143          struct virtio_gpu_resp_display_info display_info;
144          uint64_t u64;
145      } payload;
146  } QEMU_PACKED VhostUserGpuMsg;
147
148Protocol features
149-----------------
150
151None yet.
152
153As the protocol may need to evolve, new messages and communication
154changes are negotiated thanks to preliminary
155``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and
156``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests.
157
158Communication
159=============
160
161Message types
162-------------
163
164``VHOST_USER_GPU_GET_PROTOCOL_FEATURES``
165  :id: 1
166  :request payload: N/A
167  :reply payload: ``u64``
168
169  Get the supported protocol features bitmask.
170
171``VHOST_USER_GPU_SET_PROTOCOL_FEATURES``
172  :id: 2
173  :request payload: ``u64``
174  :reply payload: N/A
175
176  Enable protocol features using a bitmask.
177
178``VHOST_USER_GPU_GET_DISPLAY_INFO``
179  :id: 3
180  :request payload: N/A
181  :reply payload: ``struct virtio_gpu_resp_display_info`` (from virtio specification)
182
183  Get the preferred display configuration.
184
185``VHOST_USER_GPU_CURSOR_POS``
186  :id: 4
187  :request payload: ``VhostUserGpuCursorPos``
188  :reply payload: N/A
189
190  Set/show the cursor position.
191
192``VHOST_USER_GPU_CURSOR_POS_HIDE``
193  :id: 5
194  :request payload: ``VhostUserGpuCursorPos``
195  :reply payload: N/A
196
197  Set/hide the cursor.
198
199``VHOST_USER_GPU_CURSOR_UPDATE``
200  :id: 6
201  :request payload: ``VhostUserGpuCursorUpdate``
202  :reply payload: N/A
203
204  Update the cursor shape and location.
205
206``VHOST_USER_GPU_SCANOUT``
207  :id: 7
208  :request payload: ``VhostUserGpuScanout``
209  :reply payload: N/A
210
211  Set the scanout resolution. To disable a scanout, the dimensions
212  width/height are set to 0.
213
214``VHOST_USER_GPU_UPDATE``
215  :id: 8
216  :request payload: ``VhostUserGpuUpdate``
217  :reply payload: N/A
218
219  Update the scanout content. The data payload contains the graphical bits.
220  The display should be flushed and presented.
221
222``VHOST_USER_GPU_DMABUF_SCANOUT``
223  :id: 9
224  :request payload: ``VhostUserGpuDMABUFScanout``
225  :reply payload: N/A
226
227  Set the scanout resolution/configuration, and share a DMABUF file
228  descriptor for the scanout content, which is passed as ancillary
229  data. To disable a scanout, the dimensions width/height are set
230  to 0, there is no file descriptor passed.
231
232``VHOST_USER_GPU_DMABUF_UPDATE``
233  :id: 10
234  :request payload: ``VhostUserGpuUpdate``
235  :reply payload: empty payload
236
237  The display should be flushed and presented according to updated
238  region from ``VhostUserGpuUpdate``.
239
240  Note: there is no data payload, since the scanout is shared thanks
241  to DMABUF, that must have been set previously with
242  ``VHOST_USER_GPU_DMABUF_SCANOUT``.
243