vhost-user: define conventions for vhost-user backends

M: Michael S. Tsirkin <mst@redhat.com>

S: Supported

F: hw/*/*vhost*

F: docs/interop/vhost-user.json

F: docs/interop/vhost-user.txt

F: contrib/vhost-user-*/

# -*- Mode: Python -*-

#

# Copyright (C) 2018 Red Hat, Inc.

#

# Authors:

#  Marc-André Lureau <marcandre.lureau@redhat.com>

#

# This work is licensed under the terms of the GNU GPL, version 2 or

# later. See the COPYING file in the top-level directory.

##

# = vhost user backend discovery & capabilities

##

##

# @VHostUserBackendType:

#

# List the various vhost user backend types.

#

# @9p: 9p virtio console

# @balloon: virtio balloon

# @block: virtio block

# @caif: virtio caif

# @console: virtio console

# @crypto: virtio crypto

# @gpu: virtio gpu

# @input: virtio input

# @net: virtio net

# @rng: virtio rng

# @rpmsg: virtio remote processor messaging

# @rproc-serial: virtio remoteproc serial link

# @scsi: virtio scsi

# @vsock: virtio vsock transport

#

# Since: 4.0

##

{

  'enum': 'VHostUserBackendType',

  'data': [

      '9p',

      'balloon',

      'block',

      'caif',

      'console',

      'crypto',

      'gpu',

      'input',

      'net',

      'rng',

      'rpmsg',

      'rproc-serial',

      'scsi',

      'vsock'

  ]

}

##

# @VHostUserBackendInputFeature:

#

# List of vhost user "input" features.

#

# @evdev-path: The --evdev-path command line option is supported.

# @no-grab: The --no-grab command line option is supported.

#

# Since: 4.0

##

{

  'enum': 'VHostUserBackendInputFeature',

  'data': [ 'evdev-path', 'no-grab' ]

}

##

# @VHostUserBackendCapabilitiesInput:

#

# Capabilities reported by vhost user "input" backends

#

# @features: list of supported features.

#

# Since: 4.0

##

{

  'struct': 'VHostUserBackendCapabilitiesInput',

  'data': {

    'features': [ 'VHostUserBackendInputFeature' ]

  }

}

##

# @VHostUserBackendGPUFeature:

#

# List of vhost user "gpu" features.

#

# @render-node: The --render-node command line option is supported.

# @virgl: The --virgl command line option is supported.

#

# Since: 4.0

##

{

  'enum': 'VHostUserBackendGPUFeature',

  'data': [ 'render-node', 'virgl' ]

}

##

# @VHostUserBackendCapabilitiesGPU:

#

# Capabilities reported by vhost user "gpu" backends.

#

# @features: list of supported features.

#

# Since: 4.0

##

{

  'struct': 'VHostUserBackendCapabilitiesGPU',

  'data': {

    'features': [ 'VHostUserBackendGPUFeature' ]

  }

}

##

# @VHostUserBackendCapabilities:

#

# Capabilities reported by vhost user backends.

#

# @type: The vhost user backend type.

#

# Since: 4.0

##

{

  'union': 'VHostUserBackendCapabilities',

  'base': { 'type': 'VHostUserBackendType' },

  'discriminator': 'type',

  'data': {

    'input': 'VHostUserBackendCapabilitiesInput',

    'gpu': 'VHostUserBackendCapabilitiesGPU'

  }

}

##

# @VhostUserBackend:

#

# Describes a vhost user backend to management software.

#

# It is possible for multiple @VhostUserBackend elements to match the

# search criteria of management software. Applications thus need rules

# to pick one of the many matches, and users need the ability to

# override distro defaults.

#

# It is recommended to create vhost user backend JSON files (each

# containing a single @VhostUserBackend root element) with a

# double-digit prefix, for example "50-qemu-gpu.json",

# "50-crosvm-gpu.json", etc, so they can be sorted in predictable

# order. The backend JSON files should be searched for in three

# directories:

#

#   - /usr/share/qemu/vhost-user -- populated by distro-provided

#                                   packages (XDG_DATA_DIRS covers

#                                   /usr/share by default),

#

#   - /etc/qemu/vhost-user -- exclusively for sysadmins' local additions,

#

#   - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user local

#                                         additions (XDG_CONFIG_HOME

#                                         defaults to $HOME/.config).

#

# Top-down, the list of directories goes from general to specific.

#

# Management software should build a list of files from all three

# locations, then sort the list by filename (i.e., basename

# component). Management software should choose the first JSON file on

# the sorted list that matches the search criteria. If a more specific

# directory has a file with same name as a less specific directory,

# then the file in the more specific directory takes effect. If the

# more specific file is zero length, it hides the less specific one.

#

# For example, if a distro ships

#

#   - /usr/share/qemu/vhost-user/50-qemu-gpu.json

#

#   - /usr/share/qemu/vhost-user/50-crosvm-gpu.json

#

# then the sysadmin can prevent the default QEMU being used at all with

#

#   $ touch /etc/qemu/vhost-user/50-qemu-gpu.json

#

# The sysadmin can replace/alter the distro default OVMF with

#

#   $ vim /etc/qemu/vhost-user/50-qemu-gpu.json

#

# or they can provide a parallel QEMU GPU with higher priority

#

#   $ vim /etc/qemu/vhost-user/10-qemu-gpu.json

#

# or they can provide a parallel OVMF with lower priority

#

#   $ vim /etc/qemu/vhost-user/99-qemu-gpu.json

#

# @type: The vhost user backend type.

#

# @description: Provides a human-readable description of the backend.

#               Management software may or may not display @description.

#

# @binary: Absolute path to the backend binary.

#

# @tags: An optional list of auxiliary strings associated with the

#        backend for which @description is not appropriate, due to the

#        latter's possible exposure to the end-user. @tags serves

#        development and debugging purposes only, and management

#        software shall explicitly ignore it.

#

# Since: 4.0

#

# Example:

#

# {

#   "description": "QEMU vhost-user-gpu",

#   "type": "gpu",

#   "binary": "/usr/libexec/qemu/vhost-user-gpu",

#   "tags": [

#     "CONFIG_OPENGL_DMABUF=y"

#   ]

# }

#

##

{

  'struct' : 'VhostUserBackend',

  'data'   : {

    'description': 'str',

    'type': 'VHostUserBackendType',

    'binary': 'str',

    '*tags': [ 'str' ]

  }

}

the application that shares its virtqueues, in our case QEMU. Slave is the

consumer of the virtqueues.

In the current implementation QEMU is the Master, and the Slave is intended to

be a software Ethernet switch running in user space, such as Snabbswitch.

In the current implementation QEMU is the Master, and the Slave is the

external process consuming the virtio queues, for example a software

Ethernet switch running in user space, such as Snabbswitch, or a block

device backend processing read & write to a virtual disk. In order to

facilitate interoperability between various backend implementations,

it is recommended to follow the "Backend program conventions"

described in this document.

Master and slave can be either a client (i.e. connecting) or server (listening)

in the socket communication.

For the message types that already solicit a reply from the client, the

presence of VHOST_USER_PROTOCOL_F_REPLY_ACK or need_reply bit being set brings

no behavioural change. (See the 'Communication' section for details.)

Backend program conventions

---------------------------

vhost-user backends can provide various devices & services and may

need to be configured manually depending on the use case. However, it

is a good idea to follow the conventions listed here when

possible. Users, QEMU or libvirt, can then rely on some common

behaviour to avoid heterogenous configuration and management of the

backend programs and facilitate interoperability.

Each backend installed on a host system should come with at least one

JSON file that conforms to the vhost-user.json schema. Each file

informs the management applications about the backend type, and binary

location. In addition, it defines rules for management apps for

picking the highest priority backend when multiple match the search

criteria (see @VhostUserBackend documentation in the schema file).

If the backend is not capable of enabling a requested feature on the

host (such as 3D acceleration with virgl), or the initialization

failed, the backend should fail to start early and exit with a status

!= 0. It may also print a message to stderr for further details.

The backend program must not daemonize itself, but it may be

daemonized by the management layer. It may also have a restricted

access to the system.

File descriptors 0, 1 and 2 will exist, and have regular

stdin/stdout/stderr usage (they may have been redirected to /dev/null

by the management layer, or to a log handler).

The backend program must end (as quickly and cleanly as possible) when

the SIGTERM signal is received. Eventually, it may receive SIGKILL by

the management layer after a few seconds.

The following command line options have an expected behaviour. They

are mandatory, unless explicitly said differently:

* --socket-path=PATH

This option specify the location of the vhost-user Unix domain socket.

It is incompatible with --fd.

* --fd=FDNUM

When this argument is given, the backend program is started with the

vhost-user socket as file descriptor FDNUM. It is incompatible with

--socket-path.

* --print-capabilities

Output to stdout the backend capabilities in JSON format, and then

exit successfully. Other options and arguments should be ignored, and

the backend program should not perform its normal function.  The

capabilities can be reported dynamically depending on the host

capabilities.

The JSON output is described in the vhost-user.json schema, by

@VHostUserBackendCapabilities.  Example:

{

  "type": "foo",

  "features": [

    "feature-a",

    "feature-b"

  ]

}

vhost-user-input

----------------

Command line options:

* --evdev-path=PATH (optional)

Specify the linux input device.

* --no-grab (optional)

Do no request exclusive access to the input device.

vhost-user-gpu

--------------

Command line options:

* --render-node=PATH (optional)

Specify the GPU DRM render node.

* --virgl (optional)

Enable virgl rendering support.