# 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

- Vhost-user-gpu Protocol
  - Introduction
  - Wire format
    - Header
    - Payload types
      - VhostUserGpuCursorPos
      - VhostUserGpuCursorUpdate
      - VhostUserGpuScanout
      - VhostUserGpuUpdate
      - VhostUserGpuDMABUFScanout
    - C structure
    - Protocol features
  - Communication
    - Message types

## 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: | `u32`, type of the request
flags: | `u32`, 32-bit bit field: Bit 2 is the reply flag - needs to be set on each reply
size: | `u32`, size of the 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 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_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`.