meson: convert hw/vfio
[qemu.git] / 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_DMABUF=y"
254 #   ]
255 # }
256 #
257 ##
258 {
259   'struct' : 'VhostUserBackend',
260   'data'   : {
261     'description': 'str',
262     'type': 'VHostUserBackendType',
263     'binary': 'str',
264     '*tags': [ 'str' ]
265   }
266 }