Vhost-user-gpu Protocol¶
| Licence: | This work is licensed under the terms of the GNU GPL, version 2 or later. See the COPYING file in the top-level directory. |
|---|
Table of Contents
Introduction¶
The vhost-user-gpu protocol is aiming at sharing the rendering result of a virtio-gpu, done from a vhost-user slave process to a vhost-user master process (such as QEMU). It bears a resemblance to a display server protocol, if you consider QEMU as the display server and the slave as the client, but in a very limited way. Typically, it will work by setting a scanout/display configuration, before sending flush events for the display updates. It will also update the cursor shape and position.
The protocol is sent over a UNIX domain stream socket, since it uses
socket ancillary data to share opened file descriptors (DMABUF fds or
shared memory). The socket is usually obtained via
VHOST_USER_GPU_SET_SOCKET.
Requests are sent by the slave, and the optional replies by the master.
Wire format¶
Unless specified differently, numbers are in the machine native byte order.
A vhost-user-gpu message (request and reply) consists of 3 header fields and a payload.
| request | flags | size | payload |
Header¶
| request: |
|
|---|---|
| flags: |
|
| size: |
|
Payload types¶
Depending on the request type, payload can be:
VhostUserGpuCursorPos¶
| scanout-id | x | y |
| scanout-id: | u32, the scanout where the cursor is located |
|---|---|
| x/y: | u32, the cursor postion |
VhostUserGpuCursorUpdate¶
| pos | hot_x | hot_y | cursor |
| pos: | a VhostUserGpuCursorPos, the cursor location |
|---|---|
| hot_x/hot_y: | u32, the cursor hot location |
| cursor: | [u32; 64 * 64], 64x64 RGBA cursor data (PIXMAN_a8r8g8b8 format) |
VhostUserGpuScanout¶
| scanout-id | w | h |
| scanout-id: | u32, the scanout configuration to set |
|---|---|
| w/h: | u32, the scanout width/height size |
VhostUserGpuUpdate¶
| scanout-id | x | y | w | h | data |
| scanout-id: | u32, the scanout content to update |
|---|---|
| x/y/w/h: | u32, region of the update |
| data: | RGB data (PIXMAN_x8r8g8b8 format) |
VhostUserGpuDMABUFScanout¶
| scanout-id | x | y | w | h | fdw | fwh | stride | flags | fourcc |
| scanout-id: | u32, the scanout configuration to set |
|---|---|
| x/y: | u32, the location of the scanout within the DMABUF |
| w/h: | u32, the scanout width/height size |
| fdw/fdh/stride/flags: | |
u32, the DMABUF width/height/stride/flags |
|
| fourcc: | i32, the DMABUF fourcc |
C structure¶
In QEMU the vhost-user-gpu message is implemented with the following struct:
typedef struct VhostUserGpuMsg {
uint32_t request; /* VhostUserGpuRequest */
uint32_t flags;
uint32_t size; /* the following payload size */
union {
VhostUserGpuCursorPos cursor_pos;
VhostUserGpuCursorUpdate cursor_update;
VhostUserGpuScanout scanout;
VhostUserGpuUpdate update;
VhostUserGpuDMABUFScanout dmabuf_scanout;
struct virtio_gpu_resp_display_info display_info;
uint64_t u64;
} payload;
} QEMU_PACKED VhostUserGpuMsg;
Protocol features¶
None yet.
As the protocol may need to evolve, new messages and communication
changes are negotiated thanks to preliminary
VHOST_USER_GPU_GET_PROTOCOL_FEATURES and
VHOST_USER_GPU_SET_PROTOCOL_FEATURES requests.
Communication¶
Message types¶
VHOST_USER_GPU_GET_PROTOCOL_FEATURESid: 1 request payload: N/A reply payload: u64Get the supported protocol features bitmask.
VHOST_USER_GPU_SET_PROTOCOL_FEATURESid: 2 request payload: u64reply payload: N/A Enable protocol features using a bitmask.
VHOST_USER_GPU_GET_DISPLAY_INFOid: 3 request payload: N/A reply payload: struct virtio_gpu_resp_display_info(from virtio specification)Get the preferred display configuration.
VHOST_USER_GPU_CURSOR_POSid: 4 request payload: VhostUserGpuCursorPosreply payload: N/A Set/show the cursor position.
VHOST_USER_GPU_CURSOR_POS_HIDEid: 5 request payload: VhostUserGpuCursorPosreply payload: N/A Set/hide the cursor.
VHOST_USER_GPU_CURSOR_UPDATEid: 6 request payload: VhostUserGpuCursorUpdatereply payload: N/A Update the cursor shape and location.
VHOST_USER_GPU_SCANOUTid: 7 request payload: VhostUserGpuScanoutreply payload: N/A Set the scanout resolution. To disable a scanout, the dimensions width/height are set to 0.
VHOST_USER_GPU_UPDATEid: 8 request payload: VhostUserGpuUpdatereply payload: N/A Update the scanout content. The data payload contains the graphical bits. The display should be flushed and presented.
VHOST_USER_GPU_DMABUF_SCANOUTid: 9 request payload: VhostUserGpuDMABUFScanoutreply payload: N/A Set the scanout resolution/configuration, and share a DMABUF file descriptor for the scanout content, which is passed as ancillary data. To disable a scanout, the dimensions width/height are set to 0, there is no file descriptor passed.
VHOST_USER_GPU_DMABUF_UPDATEid: 10 request payload: VhostUserGpuUpdatereply payload: empty payload The display should be flushed and presented according to updated region from
VhostUserGpuUpdate.Note: there is no data payload, since the scanout is shared thanks to DMABUF, that must have been set previously with
VHOST_USER_GPU_DMABUF_SCANOUT.