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