Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20210921' into staging
[qemu.git] / qapi / misc.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
4
5 ##
6 # = Miscellanea
7 ##
8
9 { 'include': 'common.json' }
10
11 ##
12 # @add_client:
13 #
14 # Allow client connections for VNC, Spice and socket based
15 # character devices to be passed in to QEMU via SCM_RIGHTS.
16 #
17 # @protocol: protocol name. Valid names are "vnc", "spice" or the
18 #            name of a character device (eg. from -chardev id=XXXX)
19 #
20 # @fdname: file descriptor name previously passed via 'getfd' command
21 #
22 # @skipauth: whether to skip authentication. Only applies
23 #            to "vnc" and "spice" protocols
24 #
25 # @tls: whether to perform TLS. Only applies to the "spice"
26 #       protocol
27 #
28 # Returns: nothing on success.
29 #
30 # Since: 0.14
31 #
32 # Example:
33 #
34 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
35 #                                              "fdname": "myclient" } }
36 # <- { "return": {} }
37 #
38 ##
39 { 'command': 'add_client',
40   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
41             '*tls': 'bool' } }
42
43 ##
44 # @NameInfo:
45 #
46 # Guest name information.
47 #
48 # @name: The name of the guest
49 #
50 # Since: 0.14
51 ##
52 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
53
54 ##
55 # @query-name:
56 #
57 # Return the name information of a guest.
58 #
59 # Returns: @NameInfo of the guest
60 #
61 # Since: 0.14
62 #
63 # Example:
64 #
65 # -> { "execute": "query-name" }
66 # <- { "return": { "name": "qemu-name" } }
67 #
68 ##
69 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
70
71 ##
72 # @IOThreadInfo:
73 #
74 # Information about an iothread
75 #
76 # @id: the identifier of the iothread
77 #
78 # @thread-id: ID of the underlying host thread
79 #
80 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
81 #               (since 2.9)
82 #
83 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
84 #             configured (since 2.9)
85 #
86 # @poll-shrink: how many ns will be removed from polling time, 0 means that
87 #               it's not configured (since 2.9)
88 #
89 # Since: 2.0
90 ##
91 { 'struct': 'IOThreadInfo',
92   'data': {'id': 'str',
93            'thread-id': 'int',
94            'poll-max-ns': 'int',
95            'poll-grow': 'int',
96            'poll-shrink': 'int' } }
97
98 ##
99 # @query-iothreads:
100 #
101 # Returns a list of information about each iothread.
102 #
103 # Note: this list excludes the QEMU main loop thread, which is not declared
104 #       using the -object iothread command-line option.  It is always the main thread
105 #       of the process.
106 #
107 # Returns: a list of @IOThreadInfo for each iothread
108 #
109 # Since: 2.0
110 #
111 # Example:
112 #
113 # -> { "execute": "query-iothreads" }
114 # <- { "return": [
115 #          {
116 #             "id":"iothread0",
117 #             "thread-id":3134
118 #          },
119 #          {
120 #             "id":"iothread1",
121 #             "thread-id":3135
122 #          }
123 #       ]
124 #    }
125 #
126 ##
127 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
128   'allow-preconfig': true }
129
130 ##
131 # @stop:
132 #
133 # Stop all guest VCPU execution.
134 #
135 # Since:  0.14
136 #
137 # Notes: This function will succeed even if the guest is already in the stopped
138 #        state.  In "inmigrate" state, it will ensure that the guest
139 #        remains paused once migration finishes, as if the -S option was
140 #        passed on the command line.
141 #
142 # Example:
143 #
144 # -> { "execute": "stop" }
145 # <- { "return": {} }
146 #
147 ##
148 { 'command': 'stop' }
149
150 ##
151 # @cont:
152 #
153 # Resume guest VCPU execution.
154 #
155 # Since:  0.14
156 #
157 # Returns:  If successful, nothing
158 #
159 # Notes: This command will succeed if the guest is currently running.  It
160 #        will also succeed if the guest is in the "inmigrate" state; in
161 #        this case, the effect of the command is to make sure the guest
162 #        starts once migration finishes, removing the effect of the -S
163 #        command line option if it was passed.
164 #
165 # Example:
166 #
167 # -> { "execute": "cont" }
168 # <- { "return": {} }
169 #
170 ##
171 { 'command': 'cont' }
172
173 ##
174 # @x-exit-preconfig:
175 #
176 # Exit from "preconfig" state
177 #
178 # This command makes QEMU exit the preconfig state and proceed with
179 # VM initialization using configuration data provided on the command line
180 # and via the QMP monitor during the preconfig state. The command is only
181 # available during the preconfig state (i.e. when the --preconfig command
182 # line option was in use).
183 #
184 # Since 3.0
185 #
186 # Returns: nothing
187 #
188 # Example:
189 #
190 # -> { "execute": "x-exit-preconfig" }
191 # <- { "return": {} }
192 #
193 ##
194 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }
195
196 ##
197 # @human-monitor-command:
198 #
199 # Execute a command on the human monitor and return the output.
200 #
201 # @command-line: the command to execute in the human monitor
202 #
203 # @cpu-index: The CPU to use for commands that require an implicit CPU
204 #
205 # Features:
206 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
207 #                        monitor-owned nodes if they have no parents.
208 #                        This allows the use of 'savevm' with
209 #                        -blockdev. (since 4.2)
210 #
211 # Returns: the output of the command as a string
212 #
213 # Since: 0.14
214 #
215 # Notes: This command only exists as a stop-gap.  Its use is highly
216 #        discouraged.  The semantics of this command are not
217 #        guaranteed: this means that command names, arguments and
218 #        responses can change or be removed at ANY time.  Applications
219 #        that rely on long term stability guarantees should NOT
220 #        use this command.
221 #
222 #        Known limitations:
223 #
224 #        * This command is stateless, this means that commands that depend
225 #          on state information (such as getfd) might not work
226 #
227 #        * Commands that prompt the user for data don't currently work
228 #
229 # Example:
230 #
231 # -> { "execute": "human-monitor-command",
232 #      "arguments": { "command-line": "info kvm" } }
233 # <- { "return": "kvm support: enabled\r\n" }
234 #
235 ##
236 { 'command': 'human-monitor-command',
237   'data': {'command-line': 'str', '*cpu-index': 'int'},
238   'returns': 'str',
239   'features': [ 'savevm-monitor-nodes' ] }
240
241 ##
242 # @getfd:
243 #
244 # Receive a file descriptor via SCM rights and assign it a name
245 #
246 # @fdname: file descriptor name
247 #
248 # Returns: Nothing on success
249 #
250 # Since: 0.14
251 #
252 # Notes: If @fdname already exists, the file descriptor assigned to
253 #        it will be closed and replaced by the received file
254 #        descriptor.
255 #
256 #        The 'closefd' command can be used to explicitly close the
257 #        file descriptor when it is no longer needed.
258 #
259 # Example:
260 #
261 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
262 # <- { "return": {} }
263 #
264 ##
265 { 'command': 'getfd', 'data': {'fdname': 'str'} }
266
267 ##
268 # @closefd:
269 #
270 # Close a file descriptor previously passed via SCM rights
271 #
272 # @fdname: file descriptor name
273 #
274 # Returns: Nothing on success
275 #
276 # Since: 0.14
277 #
278 # Example:
279 #
280 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
281 # <- { "return": {} }
282 #
283 ##
284 { 'command': 'closefd', 'data': {'fdname': 'str'} }
285
286 ##
287 # @AddfdInfo:
288 #
289 # Information about a file descriptor that was added to an fd set.
290 #
291 # @fdset-id: The ID of the fd set that @fd was added to.
292 #
293 # @fd: The file descriptor that was received via SCM rights and
294 #      added to the fd set.
295 #
296 # Since: 1.2
297 ##
298 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
299
300 ##
301 # @add-fd:
302 #
303 # Add a file descriptor, that was passed via SCM rights, to an fd set.
304 #
305 # @fdset-id: The ID of the fd set to add the file descriptor to.
306 #
307 # @opaque: A free-form string that can be used to describe the fd.
308 #
309 # Returns: - @AddfdInfo on success
310 #          - If file descriptor was not received, FdNotSupplied
311 #          - If @fdset-id is a negative value, InvalidParameterValue
312 #
313 # Notes: The list of fd sets is shared by all monitor connections.
314 #
315 #        If @fdset-id is not specified, a new fd set will be created.
316 #
317 # Since: 1.2
318 #
319 # Example:
320 #
321 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
322 # <- { "return": { "fdset-id": 1, "fd": 3 } }
323 #
324 ##
325 { 'command': 'add-fd',
326   'data': { '*fdset-id': 'int',
327             '*opaque': 'str' },
328   'returns': 'AddfdInfo' }
329
330 ##
331 # @remove-fd:
332 #
333 # Remove a file descriptor from an fd set.
334 #
335 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
336 #
337 # @fd: The file descriptor that is to be removed.
338 #
339 # Returns: - Nothing on success
340 #          - If @fdset-id or @fd is not found, FdNotFound
341 #
342 # Since: 1.2
343 #
344 # Notes: The list of fd sets is shared by all monitor connections.
345 #
346 #        If @fd is not specified, all file descriptors in @fdset-id
347 #        will be removed.
348 #
349 # Example:
350 #
351 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
352 # <- { "return": {} }
353 #
354 ##
355 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
356
357 ##
358 # @FdsetFdInfo:
359 #
360 # Information about a file descriptor that belongs to an fd set.
361 #
362 # @fd: The file descriptor value.
363 #
364 # @opaque: A free-form string that can be used to describe the fd.
365 #
366 # Since: 1.2
367 ##
368 { 'struct': 'FdsetFdInfo',
369   'data': {'fd': 'int', '*opaque': 'str'} }
370
371 ##
372 # @FdsetInfo:
373 #
374 # Information about an fd set.
375 #
376 # @fdset-id: The ID of the fd set.
377 #
378 # @fds: A list of file descriptors that belong to this fd set.
379 #
380 # Since: 1.2
381 ##
382 { 'struct': 'FdsetInfo',
383   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
384
385 ##
386 # @query-fdsets:
387 #
388 # Return information describing all fd sets.
389 #
390 # Returns: A list of @FdsetInfo
391 #
392 # Since: 1.2
393 #
394 # Note: The list of fd sets is shared by all monitor connections.
395 #
396 # Example:
397 #
398 # -> { "execute": "query-fdsets" }
399 # <- { "return": [
400 #        {
401 #          "fds": [
402 #            {
403 #              "fd": 30,
404 #              "opaque": "rdonly:/path/to/file"
405 #            },
406 #            {
407 #              "fd": 24,
408 #              "opaque": "rdwr:/path/to/file"
409 #            }
410 #          ],
411 #          "fdset-id": 1
412 #        },
413 #        {
414 #          "fds": [
415 #            {
416 #              "fd": 28
417 #            },
418 #            {
419 #              "fd": 29
420 #            }
421 #          ],
422 #          "fdset-id": 0
423 #        }
424 #      ]
425 #    }
426 #
427 ##
428 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
429
430 ##
431 # @CommandLineParameterType:
432 #
433 # Possible types for an option parameter.
434 #
435 # @string: accepts a character string
436 #
437 # @boolean: accepts "on" or "off"
438 #
439 # @number: accepts a number
440 #
441 # @size: accepts a number followed by an optional suffix (K)ilo,
442 #        (M)ega, (G)iga, (T)era
443 #
444 # Since: 1.5
445 ##
446 { 'enum': 'CommandLineParameterType',
447   'data': ['string', 'boolean', 'number', 'size'] }
448
449 ##
450 # @CommandLineParameterInfo:
451 #
452 # Details about a single parameter of a command line option.
453 #
454 # @name: parameter name
455 #
456 # @type: parameter @CommandLineParameterType
457 #
458 # @help: human readable text string, not suitable for parsing.
459 #
460 # @default: default value string (since 2.1)
461 #
462 # Since: 1.5
463 ##
464 { 'struct': 'CommandLineParameterInfo',
465   'data': { 'name': 'str',
466             'type': 'CommandLineParameterType',
467             '*help': 'str',
468             '*default': 'str' } }
469
470 ##
471 # @CommandLineOptionInfo:
472 #
473 # Details about a command line option, including its list of parameter details
474 #
475 # @option: option name
476 #
477 # @parameters: an array of @CommandLineParameterInfo
478 #
479 # Since: 1.5
480 ##
481 { 'struct': 'CommandLineOptionInfo',
482   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
483
484 ##
485 # @query-command-line-options:
486 #
487 # Query command line option schema.
488 #
489 # @option: option name
490 #
491 # Returns: list of @CommandLineOptionInfo for all options (or for the given
492 #          @option).  Returns an error if the given @option doesn't exist.
493 #
494 # Since: 1.5
495 #
496 # Example:
497 #
498 # -> { "execute": "query-command-line-options",
499 #      "arguments": { "option": "option-rom" } }
500 # <- { "return": [
501 #         {
502 #             "parameters": [
503 #                 {
504 #                     "name": "romfile",
505 #                     "type": "string"
506 #                 },
507 #                 {
508 #                     "name": "bootindex",
509 #                     "type": "number"
510 #                 }
511 #             ],
512 #             "option": "option-rom"
513 #         }
514 #      ]
515 #    }
516 #
517 ##
518 {'command': 'query-command-line-options',
519  'data': { '*option': 'str' },
520  'returns': ['CommandLineOptionInfo'],
521  'allow-preconfig': true }