Vhost-user-gpu Protocol

Introduction

The vhost-user-gpu protocol is aiming at sharing the rendering result of a virtio-gpu, done from a vhost-user back-end process to a vhost-user front-end process (such as QEMU). It bears a resemblance to a display server protocol, if you consider QEMU as the display server and the back-end 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 back-end, and the optional replies by the front-end.

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

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 position

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

VhostUserGpuEdidRequest

scanout-id
scanout-id:u32, the scanout to get edid from

VhostUserGpuDMABUFScanout2

dmabuf_scanout modifier
dmabuf_scanout:VhostUserGpuDMABUFScanout, filled as described in the VhostUserGpuDMABUFScanout structure.
modifier:u64, the DMABUF modifiers

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;
        VhostUserGpuEdidRequest edid_req;
        struct virtio_gpu_resp_edid resp_edid;
        struct virtio_gpu_resp_display_info display_info;
        uint64_t u64;
    } payload;
} QEMU_PACKED VhostUserGpuMsg;

Protocol features

#define VHOST_USER_GPU_PROTOCOL_F_EDID    0
#define VHOST_USER_GPU_PROTOCOL_F_DMABUF2 1

New messages and communication changes are negotiated thanks to the VHOST_USER_GPU_GET_PROTOCOL_FEATURES and VHOST_USER_GPU_SET_PROTOCOL_FEATURES requests.

Communication

Message types

VHOST_USER_GPU_GET_PROTOCOL_FEATURES
id:1
request payload:
 N/A
reply payload:u64

Get the supported protocol features bitmask.

VHOST_USER_GPU_SET_PROTOCOL_FEATURES
id:2
request payload:
 u64
reply payload:N/A

Enable protocol features using a bitmask.

VHOST_USER_GPU_GET_DISPLAY_INFO
id: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_POS
id:4
request payload:
 VhostUserGpuCursorPos
reply payload:N/A

Set/show the cursor position.

VHOST_USER_GPU_CURSOR_POS_HIDE
id:5
request payload:
 VhostUserGpuCursorPos
reply payload:N/A

Set/hide the cursor.

VHOST_USER_GPU_CURSOR_UPDATE
id:6
request payload:
 VhostUserGpuCursorUpdate
reply payload:N/A

Update the cursor shape and location.

VHOST_USER_GPU_SCANOUT
id:7
request payload:
 VhostUserGpuScanout
reply payload:N/A

Set the scanout resolution. To disable a scanout, the dimensions width/height are set to 0.

VHOST_USER_GPU_UPDATE
id:8
request payload:
 VhostUserGpuUpdate
reply 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_SCANOUT
id:9
request payload:
 VhostUserGpuDMABUFScanout
reply 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_UPDATE
id:10
request payload:
 VhostUserGpuUpdate
reply 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.

VHOST_USER_GPU_GET_EDID
id:11
request payload:
 struct VhostUserGpuEdidRequest
reply payload:struct virtio_gpu_resp_edid (from virtio specification)

Retrieve the EDID data for a given scanout. This message requires the VHOST_USER_GPU_PROTOCOL_F_EDID protocol feature to be supported.

VHOST_USER_GPU_DMABUF_SCANOUT2
id:12
request payload:
 VhostUserGpuDMABUFScanout2
reply payload:N/A

Same as VHOST_USER_GPU_DMABUF_SCANOUT, but also sends the dmabuf modifiers appended to the message, which were not provided in the other message. This message requires the VHOST_USER_GPU_PROTOCOL_F_DMABUF2 protocol feature to be supported.