@samitouri / QOSamiQemu
Code Commits Issues Pulls Sessions CI/CD
master
master
rst 289 lines 7.44 KB
Raw
1 =======================
2 Vhost-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
12 Introduction
13 ============
14
15 The vhost-user-gpu protocol is aiming at sharing the rendering result
16 of a virtio-gpu, done from a vhost-user back-end process to a vhost-user
17 front-end process (such as QEMU). It bears a resemblance to a display
18 server protocol, if you consider QEMU as the display server and the
19 back-end as the client, but in a very limited way. Typically, it will
20 work by setting a scanout/display configuration, before sending flush
21 events for the display updates. It will also update the cursor shape
22 and position.
23
24 The protocol is sent over a UNIX domain stream socket, since it uses
25 socket ancillary data to share opened file descriptors (DMABUF fds or
26 shared memory). The socket is usually obtained via
27 ``VHOST_USER_GPU_SET_SOCKET``.
28
29 Requests are sent by the *back-end*, and the optional replies by the
30 *front-end*.
31
32 Wire format
33 ===========
34
35 Unless specified differently, numbers are in the machine native byte
36 order.
37
38 A vhost-user-gpu message (request and reply) consists of 3 header
39 fields and a payload.
40
41 +---------+-------+------+---------+
42 | request | flags | size | payload |
43 +---------+-------+------+---------+
44
45 Header
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
56 Payload types
57 -------------
58
59 Depending on the request type, **payload** can be:
60
61 VhostUserGpuCursorPos
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
72 VhostUserGpuCursorUpdate
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
85 VhostUserGpuScanout
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
96 VhostUserGpuUpdate
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
109 VhostUserGpuDMABUFScanout
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
127 VhostUserGpuEdidRequest
128 ^^^^^^^^^^^^^^^^^^^^^^^
129
130 +------------+
131 | scanout-id |
132 +------------+
133
134 :scanout-id: ``u32``, the scanout to get edid from
135
136
137 VhostUserGpuDMABUFScanout2
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
150 C structure
151 -----------
152
153 In 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
174 Protocol 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
182 New 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
186 Communication
187 =============
188
189 Message 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.