meson: convert hw/vfio
[qemu.git] / docs / interop / vhost-user-gpu.rst
1 =======================
2 Vhost-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
11 Introduction
12 ============
13
14 The vhost-user-gpu protocol is aiming at sharing the rendering result
15 of a virtio-gpu, done from a vhost-user slave process to a vhost-user
16 master process (such as QEMU). It bears a resemblance to a display
17 server protocol, if you consider QEMU as the display server and the
18 slave as the client, but in a very limited way. Typically, it will
19 work by setting a scanout/display configuration, before sending flush
20 events for the display updates. It will also update the cursor shape
21 and position.
22
23 The protocol is sent over a UNIX domain stream socket, since it uses
24 socket ancillary data to share opened file descriptors (DMABUF fds or
25 shared memory). The socket is usually obtained via
26 ``VHOST_USER_GPU_SET_SOCKET``.
27
28 Requests are sent by the *slave*, and the optional replies by the
29 *master*.
30
31 Wire format
32 ===========
33
34 Unless specified differently, numbers are in the machine native byte
35 order.
36
37 A vhost-user-gpu message (request and reply) consists of 3 header
38 fields and a payload.
39
40 +---------+-------+------+---------+
41 | request | flags | size | payload |
42 +---------+-------+------+---------+
43
44 Header
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
55 Payload types
56 -------------
57
58 Depending on the request type, **payload** can be:
59
60 VhostUserGpuCursorPos
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
71 VhostUserGpuCursorUpdate
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
84 VhostUserGpuScanout
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
95 VhostUserGpuUpdate
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
108 VhostUserGpuDMABUFScanout
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
126 C structure
127 -----------
128
129 In 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
148 Protocol features
149 -----------------
150
151 None yet.
152
153 As the protocol may need to evolve, new messages and communication
154 changes are negotiated thanks to preliminary
155 ``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and
156 ``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests.
157
158 Communication
159 =============
160
161 Message 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``.