Merge remote-tracking branch 'remotes/alistair/tags/pull-riscv-to-apply-20220121...
[qemu.git] / docs / interop / vhost-user-gpu.rst
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 slave process to a vhost-user
17 master 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 slave 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 *slave*, and the optional replies by the
30 *master*.
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 C structure
128 -----------
129
130 In 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
149 Protocol features
150 -----------------
151
152 None yet.
153
154 As the protocol may need to evolve, new messages and communication
155 changes are negotiated thanks to preliminary
156 ``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and
157 ``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests.
158
159 Communication
160 =============
161
162 Message 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``.