# -*- Mode: Python -*-
# vim: filetype=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
# @fs: virtio fs (since 4.2)
#
# Since: 4.0
##
{
  'enum': 'VHostUserBackendType',
  'data': [
      '9p',
      'balloon',
      'block',
      'caif',
      'console',
      'crypto',
      'gpu',
      'input',
      'net',
      'rng',
      'rpmsg',
      'rproc-serial',
      'scsi',
      'vsock',
      'fs'
  ]
}

##
# @VHostUserBackendBlockFeature:
#
# List of vhost user "block" features.
#
# @read-only: The --read-only command line option is supported.
# @blk-file: The --blk-file command line option is supported.
#
# Since: 5.0
##
{
  'enum': 'VHostUserBackendBlockFeature',
  'data': [ 'read-only', 'blk-file' ]
}

##
# @VHostUserBackendCapabilitiesBlock:
#
# Capabilities reported by vhost user "block" backends
#
# @features: list of supported features.
#
# Since: 5.0
##
{
  'struct': 'VHostUserBackendCapabilitiesBlock',
  'data': {
    'features': [ 'VHostUserBackendBlockFeature' ]
  }
}

##
# @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 GPU being used at all with
#
#   $ touch /etc/qemu/vhost-user/50-qemu-gpu.json
#
# The sysadmin can replace/alter the distro default QEMU GPU 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 QEMU GPU 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' ]
  }
}