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