123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267 |
- # -*- 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=y",
- # "CONFIG_GBM=y"
- # ]
- # }
- #
- ##
- {
- 'struct' : 'VhostUserBackend',
- 'data' : {
- 'description': 'str',
- 'type': 'VHostUserBackendType',
- 'binary': 'str',
- '*tags': [ 'str' ]
- }
- }
|