target/ppc: Fix slbia TLB invalidation gap
[qemu.git] / 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 }