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.

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

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

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_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.