docs/interop/vhost-user.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4 # Copyright (C) 2018 Red Hat, Inc.
   5 #
   6 # Authors:
   7 #  Marc-André Lureau <marcandre.lureau@redhat.com>
   8 #
   9 # This work is licensed under the terms of the GNU GPL, version 2 or
  10 # later. See the COPYING file in the top-level directory.
  11
  12 ##
  13 # = vhost user backend discovery & capabilities
  14 ##
  15
  16 ##
  17 # @VHostUserBackendType:
  18 #
  19 # List the various vhost user backend types.
  20 #
  21 # @9p: 9p virtio console
  22 # @balloon: virtio balloon
  23 # @block: virtio block
  24 # @caif: virtio caif
  25 # @console: virtio console
  26 # @crypto: virtio crypto
  27 # @gpu: virtio gpu
  28 # @input: virtio input
  29 # @net: virtio net
  30 # @rng: virtio rng
  31 # @rpmsg: virtio remote processor messaging
  32 # @rproc-serial: virtio remoteproc serial link
  33 # @scsi: virtio scsi
  34 # @vsock: virtio vsock transport
  35 # @fs: virtio fs (since 4.2)
  36 #
  37 # Since: 4.0
  38 ##
  39 {
  40   'enum': 'VHostUserBackendType',
  41   'data': [
  42       '9p',
  43       'balloon',
  44       'block',
  45       'caif',
  46       'console',
  47       'crypto',
  48       'gpu',
  49       'input',
  50       'net',
  51       'rng',
  52       'rpmsg',
  53       'rproc-serial',
  54       'scsi',
  55       'vsock',
  56       'fs'
  57   ]
  58 }
  59
  60 ##
  61 # @VHostUserBackendBlockFeature:
  62 #
  63 # List of vhost user "block" features.
  64 #
  65 # @read-only: The --read-only command line option is supported.
  66 # @blk-file: The --blk-file command line option is supported.
  67 #
  68 # Since: 5.0
  69 ##
  70 {
  71   'enum': 'VHostUserBackendBlockFeature',
  72   'data': [ 'read-only', 'blk-file' ]
  73 }
  74
  75 ##
  76 # @VHostUserBackendCapabilitiesBlock:
  77 #
  78 # Capabilities reported by vhost user "block" backends
  79 #
  80 # @features: list of supported features.
  81 #
  82 # Since: 5.0
  83 ##
  84 {
  85   'struct': 'VHostUserBackendCapabilitiesBlock',
  86   'data': {
  87     'features': [ 'VHostUserBackendBlockFeature' ]
  88   }
  89 }
  90
  91 ##
  92 # @VHostUserBackendInputFeature:
  93 #
  94 # List of vhost user "input" features.
  95 #
  96 # @evdev-path: The --evdev-path command line option is supported.
  97 # @no-grab: The --no-grab command line option is supported.
  98 #
  99 # Since: 4.0
 100 ##
 101 {
 102   'enum': 'VHostUserBackendInputFeature',
 103   'data': [ 'evdev-path', 'no-grab' ]
 104 }
 105
 106 ##
 107 # @VHostUserBackendCapabilitiesInput:
 108 #
 109 # Capabilities reported by vhost user "input" backends
 110 #
 111 # @features: list of supported features.
 112 #
 113 # Since: 4.0
 114 ##
 115 {
 116   'struct': 'VHostUserBackendCapabilitiesInput',
 117   'data': {
 118     'features': [ 'VHostUserBackendInputFeature' ]
 119   }
 120 }
 121
 122 ##
 123 # @VHostUserBackendGPUFeature:
 124 #
 125 # List of vhost user "gpu" features.
 126 #
 127 # @render-node: The --render-node command line option is supported.
 128 # @virgl: The --virgl command line option is supported.
 129 #
 130 # Since: 4.0
 131 ##
 132 {
 133   'enum': 'VHostUserBackendGPUFeature',
 134   'data': [ 'render-node', 'virgl' ]
 135 }
 136
 137 ##
 138 # @VHostUserBackendCapabilitiesGPU:
 139 #
 140 # Capabilities reported by vhost user "gpu" backends.
 141 #
 142 # @features: list of supported features.
 143 #
 144 # Since: 4.0
 145 ##
 146 {
 147   'struct': 'VHostUserBackendCapabilitiesGPU',
 148   'data': {
 149     'features': [ 'VHostUserBackendGPUFeature' ]
 150   }
 151 }
 152
 153 ##
 154 # @VHostUserBackendCapabilities:
 155 #
 156 # Capabilities reported by vhost user backends.
 157 #
 158 # @type: The vhost user backend type.
 159 #
 160 # Since: 4.0
 161 ##
 162 {
 163   'union': 'VHostUserBackendCapabilities',
 164   'base': { 'type': 'VHostUserBackendType' },
 165   'discriminator': 'type',
 166   'data': {
 167     'input': 'VHostUserBackendCapabilitiesInput',
 168     'gpu': 'VHostUserBackendCapabilitiesGPU'
 169   }
 170 }
 171
 172 ##
 173 # @VhostUserBackend:
 174 #
 175 # Describes a vhost user backend to management software.
 176 #
 177 # It is possible for multiple @VhostUserBackend elements to match the
 178 # search criteria of management software. Applications thus need rules
 179 # to pick one of the many matches, and users need the ability to
 180 # override distro defaults.
 181 #
 182 # It is recommended to create vhost user backend JSON files (each
 183 # containing a single @VhostUserBackend root element) with a
 184 # double-digit prefix, for example "50-qemu-gpu.json",
 185 # "50-crosvm-gpu.json", etc, so they can be sorted in predictable
 186 # order. The backend JSON files should be searched for in three
 187 # directories:
 188 #
 189 #   - /usr/share/qemu/vhost-user -- populated by distro-provided
 190 #                                   packages (XDG_DATA_DIRS covers
 191 #                                   /usr/share by default),
 192 #
 193 #   - /etc/qemu/vhost-user -- exclusively for sysadmins' local additions,
 194 #
 195 #   - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user local
 196 #                                         additions (XDG_CONFIG_HOME
 197 #                                         defaults to $HOME/.config).
 198 #
 199 # Top-down, the list of directories goes from general to specific.
 200 #
 201 # Management software should build a list of files from all three
 202 # locations, then sort the list by filename (i.e., basename
 203 # component). Management software should choose the first JSON file on
 204 # the sorted list that matches the search criteria. If a more specific
 205 # directory has a file with same name as a less specific directory,
 206 # then the file in the more specific directory takes effect. If the
 207 # more specific file is zero length, it hides the less specific one.
 208 #
 209 # For example, if a distro ships
 210 #
 211 #   - /usr/share/qemu/vhost-user/50-qemu-gpu.json
 212 #
 213 #   - /usr/share/qemu/vhost-user/50-crosvm-gpu.json
 214 #
 215 # then the sysadmin can prevent the default QEMU GPU being used at all with
 216 #
 217 #   $ touch /etc/qemu/vhost-user/50-qemu-gpu.json
 218 #
 219 # The sysadmin can replace/alter the distro default QEMU GPU with
 220 #
 221 #   $ vim /etc/qemu/vhost-user/50-qemu-gpu.json
 222 #
 223 # or they can provide a parallel QEMU GPU with higher priority
 224 #
 225 #   $ vim /etc/qemu/vhost-user/10-qemu-gpu.json
 226 #
 227 # or they can provide a parallel QEMU GPU with lower priority
 228 #
 229 #   $ vim /etc/qemu/vhost-user/99-qemu-gpu.json
 230 #
 231 # @type: The vhost user backend type.
 232 #
 233 # @description: Provides a human-readable description of the backend.
 234 #               Management software may or may not display @description.
 235 #
 236 # @binary: Absolute path to the backend binary.
 237 #
 238 # @tags: An optional list of auxiliary strings associated with the
 239 #        backend for which @description is not appropriate, due to the
 240 #        latter's possible exposure to the end-user. @tags serves
 241 #        development and debugging purposes only, and management
 242 #        software shall explicitly ignore it.
 243 #
 244 # Since: 4.0
 245 #
 246 # Example:
 247 #
 248 # {
 249 #   "description": "QEMU vhost-user-gpu",
 250 #   "type": "gpu",
 251 #   "binary": "/usr/libexec/qemu/vhost-user-gpu",
 252 #   "tags": [
 253 #     "CONFIG_OPENGL=y",
 254 #     "CONFIG_GBM=y"
 255 #   ]
 256 # }
 257 #
 258 ##
 259 {
 260   'struct' : 'VhostUserBackend',
 261   'data'   : {
 262     'description': 'str',
 263     'type': 'VHostUserBackendType',
 264     'binary': 'str',
 265     '*tags': [ 'str' ]
 266   }
 267 }