docs/interop/vhost-user.json

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