sd/milkymist-memcard: Fix format string
[qemu/armbru.git] / docs / interop / vhost-user-gpu.rst
blob688f8b425999c6528660c187c3e69becc6cb1d7a
1 =======================
2 Vhost-user-gpu Protocol
3 =======================
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.
9 .. contents:: Table of Contents
11 Introduction
12 ============
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.
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``.
28 Requests are sent by the *slave*, and the optional replies by the
29 *master*.
31 Wire format
32 ===========
34 Unless specified differently, numbers are in the machine native byte
35 order.
37 A vhost-user-gpu message (request and reply) consists of 3 header
38 fields and a payload.
40 +---------+-------+------+---------+
41 | request | flags | size | payload |
42 +---------+-------+------+---------+
44 Header
45 ------
47 :request: ``u32``, type of the request
49 :flags: ``u32``, 32-bit bit field:
51  - Bit 2 is the reply flag - needs to be set on each reply
53 :size: ``u32``, size of the payload
55 Payload types
56 -------------
58 Depending on the request type, **payload** can be:
60 VhostUserGpuCursorPos
61 ^^^^^^^^^^^^^^^^^^^^^
63 +------------+---+---+
64 | scanout-id | x | y |
65 +------------+---+---+
67 :scanout-id: ``u32``, the scanout where the cursor is located
69 :x/y: ``u32``, the cursor postion
71 VhostUserGpuCursorUpdate
72 ^^^^^^^^^^^^^^^^^^^^^^^^
74 +-----+-------+-------+--------+
75 | pos | hot_x | hot_y | cursor |
76 +-----+-------+-------+--------+
78 :pos: a ``VhostUserGpuCursorPos``, the cursor location
80 :hot_x/hot_y: ``u32``, the cursor hot location
82 :cursor: ``[u32; 64 * 64]``, 64x64 RGBA cursor data (PIXMAN_a8r8g8b8 format)
84 VhostUserGpuScanout
85 ^^^^^^^^^^^^^^^^^^^
87 +------------+---+---+
88 | scanout-id | w | h |
89 +------------+---+---+
91 :scanout-id: ``u32``, the scanout configuration to set
93 :w/h: ``u32``, the scanout width/height size
95 VhostUserGpuUpdate
96 ^^^^^^^^^^^^^^^^^^
98 +------------+---+---+---+---+------+
99 | scanout-id | x | y | w | h | data |
100 +------------+---+---+---+---+------+
102 :scanout-id: ``u32``, the scanout content to update
104 :x/y/w/h: ``u32``, region of the update
106 :data: RGB data (PIXMAN_x8r8g8b8 format)
108 VhostUserGpuDMABUFScanout
109 ^^^^^^^^^^^^^^^^^^^^^^^^^
111 +------------+---+---+---+---+-----+-----+--------+-------+--------+
112 | scanout-id | x | y | w | h | fdw | fwh | stride | flags | fourcc |
113 +------------+---+---+---+---+-----+-----+--------+-------+--------+
115 :scanout-id: ``u32``, the scanout configuration to set
117 :x/y: ``u32``, the location of the scanout within the DMABUF
119 :w/h: ``u32``, the scanout width/height size
121 :fdw/fdh/stride/flags: ``u32``, the DMABUF width/height/stride/flags
123 :fourcc: ``i32``, the DMABUF fourcc
126 C structure
127 -----------
129 In QEMU the vhost-user-gpu message is implemented with the following struct:
131 .. code:: c
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;
148 Protocol features
149 -----------------
151 None yet.
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.
158 Communication
159 =============
161 Message types
162 -------------
164 ``VHOST_USER_GPU_GET_PROTOCOL_FEATURES``
165   :id: 1
166   :request payload: N/A
167   :reply payload: ``u64``
169   Get the supported protocol features bitmask.
171 ``VHOST_USER_GPU_SET_PROTOCOL_FEATURES``
172   :id: 2
173   :request payload: ``u64``
174   :reply payload: N/A
176   Enable protocol features using a bitmask.
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)
183   Get the preferred display configuration.
185 ``VHOST_USER_GPU_CURSOR_POS``
186   :id: 4
187   :request payload: ``VhostUserGpuCursorPos``
188   :reply payload: N/A
190   Set/show the cursor position.
192 ``VHOST_USER_GPU_CURSOR_POS_HIDE``
193   :id: 5
194   :request payload: ``VhostUserGpuCursorPos``
195   :reply payload: N/A
197   Set/hide the cursor.
199 ``VHOST_USER_GPU_CURSOR_UPDATE``
200   :id: 6
201   :request payload: ``VhostUserGpuCursorUpdate``
202   :reply payload: N/A
204   Update the cursor shape and location.
206 ``VHOST_USER_GPU_SCANOUT``
207   :id: 7
208   :request payload: ``VhostUserGpuScanout``
209   :reply payload: N/A
211   Set the scanout resolution. To disable a scanout, the dimensions
212   width/height are set to 0.
214 ``VHOST_USER_GPU_UPDATE``
215   :id: 8
216   :request payload: ``VhostUserGpuUpdate``
217   :reply payload: N/A
219   Update the scanout content. The data payload contains the graphical bits.
220   The display should be flushed and presented.
222 ``VHOST_USER_GPU_DMABUF_SCANOUT``
223   :id: 9
224   :request payload: ``VhostUserGpuDMABUFScanout``
225   :reply payload: N/A
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.
232 ``VHOST_USER_GPU_DMABUF_UPDATE``
233   :id: 10
234   :request payload: ``VhostUserGpuUpdate``
235   :reply payload: empty payload
237   The display should be flushed and presented according to updated
238   region from ``VhostUserGpuUpdate``.
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``.