qapi: Restrict 'query-kvm' command to machine code
[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.0
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.0
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.0
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.0
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.0
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.0
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 # @change:
243 #
244 # This command is multiple commands multiplexed together.
245 #
246 # @device: This is normally the name of a block device but it may also be 'vnc'.
247 #          when it's 'vnc', then sub command depends on @target
248 #
249 # @target: If @device is a block device, then this is the new filename.
250 #          If @device is 'vnc', then if the value 'password' selects the vnc
251 #          change password command.   Otherwise, this specifies a new server URI
252 #          address to listen to for VNC connections.
253 #
254 # @arg: If @device is a block device, then this is an optional format to open
255 #       the device with.
256 #       If @device is 'vnc' and @target is 'password', this is the new VNC
257 #       password to set.  See change-vnc-password for additional notes.
258 #
259 # Features:
260 # @deprecated: This command is deprecated.  For changing block
261 #              devices, use 'blockdev-change-medium' instead; for changing VNC
262 #              parameters, use 'change-vnc-password' instead.
263 #
264 # Returns: - Nothing on success.
265 #          - If @device is not a valid block device, DeviceNotFound
266 #
267 # Since: 0.14.0
268 #
269 # Example:
270 #
271 # 1. Change a removable medium
272 #
273 # -> { "execute": "change",
274 #      "arguments": { "device": "ide1-cd0",
275 #                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
276 # <- { "return": {} }
277 #
278 # 2. Change VNC password
279 #
280 # -> { "execute": "change",
281 #      "arguments": { "device": "vnc", "target": "password",
282 #                     "arg": "foobar1" } }
283 # <- { "return": {} }
284 #
285 ##
286 { 'command': 'change',
287   'data': {'device': 'str', 'target': 'str', '*arg': 'str'},
288   'features': [ 'deprecated' ] }
289
290 ##
291 # @xen-set-global-dirty-log:
292 #
293 # Enable or disable the global dirty log mode.
294 #
295 # @enable: true to enable, false to disable.
296 #
297 # Returns: nothing
298 #
299 # Since: 1.3
300 #
301 # Example:
302 #
303 # -> { "execute": "xen-set-global-dirty-log",
304 #      "arguments": { "enable": true } }
305 # <- { "return": {} }
306 #
307 ##
308 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
309
310 ##
311 # @getfd:
312 #
313 # Receive a file descriptor via SCM rights and assign it a name
314 #
315 # @fdname: file descriptor name
316 #
317 # Returns: Nothing on success
318 #
319 # Since: 0.14.0
320 #
321 # Notes: If @fdname already exists, the file descriptor assigned to
322 #        it will be closed and replaced by the received file
323 #        descriptor.
324 #
325 #        The 'closefd' command can be used to explicitly close the
326 #        file descriptor when it is no longer needed.
327 #
328 # Example:
329 #
330 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
331 # <- { "return": {} }
332 #
333 ##
334 { 'command': 'getfd', 'data': {'fdname': 'str'} }
335
336 ##
337 # @closefd:
338 #
339 # Close a file descriptor previously passed via SCM rights
340 #
341 # @fdname: file descriptor name
342 #
343 # Returns: Nothing on success
344 #
345 # Since: 0.14.0
346 #
347 # Example:
348 #
349 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
350 # <- { "return": {} }
351 #
352 ##
353 { 'command': 'closefd', 'data': {'fdname': 'str'} }
354
355 ##
356 # @AddfdInfo:
357 #
358 # Information about a file descriptor that was added to an fd set.
359 #
360 # @fdset-id: The ID of the fd set that @fd was added to.
361 #
362 # @fd: The file descriptor that was received via SCM rights and
363 #      added to the fd set.
364 #
365 # Since: 1.2.0
366 ##
367 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
368
369 ##
370 # @add-fd:
371 #
372 # Add a file descriptor, that was passed via SCM rights, to an fd set.
373 #
374 # @fdset-id: The ID of the fd set to add the file descriptor to.
375 #
376 # @opaque: A free-form string that can be used to describe the fd.
377 #
378 # Returns: - @AddfdInfo on success
379 #          - If file descriptor was not received, FdNotSupplied
380 #          - If @fdset-id is a negative value, InvalidParameterValue
381 #
382 # Notes: The list of fd sets is shared by all monitor connections.
383 #
384 #        If @fdset-id is not specified, a new fd set will be created.
385 #
386 # Since: 1.2.0
387 #
388 # Example:
389 #
390 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
391 # <- { "return": { "fdset-id": 1, "fd": 3 } }
392 #
393 ##
394 { 'command': 'add-fd',
395   'data': { '*fdset-id': 'int',
396             '*opaque': 'str' },
397   'returns': 'AddfdInfo' }
398
399 ##
400 # @remove-fd:
401 #
402 # Remove a file descriptor from an fd set.
403 #
404 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
405 #
406 # @fd: The file descriptor that is to be removed.
407 #
408 # Returns: - Nothing on success
409 #          - If @fdset-id or @fd is not found, FdNotFound
410 #
411 # Since: 1.2.0
412 #
413 # Notes: The list of fd sets is shared by all monitor connections.
414 #
415 #        If @fd is not specified, all file descriptors in @fdset-id
416 #        will be removed.
417 #
418 # Example:
419 #
420 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
421 # <- { "return": {} }
422 #
423 ##
424 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
425
426 ##
427 # @FdsetFdInfo:
428 #
429 # Information about a file descriptor that belongs to an fd set.
430 #
431 # @fd: The file descriptor value.
432 #
433 # @opaque: A free-form string that can be used to describe the fd.
434 #
435 # Since: 1.2.0
436 ##
437 { 'struct': 'FdsetFdInfo',
438   'data': {'fd': 'int', '*opaque': 'str'} }
439
440 ##
441 # @FdsetInfo:
442 #
443 # Information about an fd set.
444 #
445 # @fdset-id: The ID of the fd set.
446 #
447 # @fds: A list of file descriptors that belong to this fd set.
448 #
449 # Since: 1.2.0
450 ##
451 { 'struct': 'FdsetInfo',
452   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
453
454 ##
455 # @query-fdsets:
456 #
457 # Return information describing all fd sets.
458 #
459 # Returns: A list of @FdsetInfo
460 #
461 # Since: 1.2.0
462 #
463 # Note: The list of fd sets is shared by all monitor connections.
464 #
465 # Example:
466 #
467 # -> { "execute": "query-fdsets" }
468 # <- { "return": [
469 #        {
470 #          "fds": [
471 #            {
472 #              "fd": 30,
473 #              "opaque": "rdonly:/path/to/file"
474 #            },
475 #            {
476 #              "fd": 24,
477 #              "opaque": "rdwr:/path/to/file"
478 #            }
479 #          ],
480 #          "fdset-id": 1
481 #        },
482 #        {
483 #          "fds": [
484 #            {
485 #              "fd": 28
486 #            },
487 #            {
488 #              "fd": 29
489 #            }
490 #          ],
491 #          "fdset-id": 0
492 #        }
493 #      ]
494 #    }
495 #
496 ##
497 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
498
499 ##
500 # @CommandLineParameterType:
501 #
502 # Possible types for an option parameter.
503 #
504 # @string: accepts a character string
505 #
506 # @boolean: accepts "on" or "off"
507 #
508 # @number: accepts a number
509 #
510 # @size: accepts a number followed by an optional suffix (K)ilo,
511 #        (M)ega, (G)iga, (T)era
512 #
513 # Since: 1.5
514 ##
515 { 'enum': 'CommandLineParameterType',
516   'data': ['string', 'boolean', 'number', 'size'] }
517
518 ##
519 # @CommandLineParameterInfo:
520 #
521 # Details about a single parameter of a command line option.
522 #
523 # @name: parameter name
524 #
525 # @type: parameter @CommandLineParameterType
526 #
527 # @help: human readable text string, not suitable for parsing.
528 #
529 # @default: default value string (since 2.1)
530 #
531 # Since: 1.5
532 ##
533 { 'struct': 'CommandLineParameterInfo',
534   'data': { 'name': 'str',
535             'type': 'CommandLineParameterType',
536             '*help': 'str',
537             '*default': 'str' } }
538
539 ##
540 # @CommandLineOptionInfo:
541 #
542 # Details about a command line option, including its list of parameter details
543 #
544 # @option: option name
545 #
546 # @parameters: an array of @CommandLineParameterInfo
547 #
548 # Since: 1.5
549 ##
550 { 'struct': 'CommandLineOptionInfo',
551   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
552
553 ##
554 # @query-command-line-options:
555 #
556 # Query command line option schema.
557 #
558 # @option: option name
559 #
560 # Returns: list of @CommandLineOptionInfo for all options (or for the given
561 #          @option).  Returns an error if the given @option doesn't exist.
562 #
563 # Since: 1.5
564 #
565 # Example:
566 #
567 # -> { "execute": "query-command-line-options",
568 #      "arguments": { "option": "option-rom" } }
569 # <- { "return": [
570 #         {
571 #             "parameters": [
572 #                 {
573 #                     "name": "romfile",
574 #                     "type": "string"
575 #                 },
576 #                 {
577 #                     "name": "bootindex",
578 #                     "type": "number"
579 #                 }
580 #             ],
581 #             "option": "option-rom"
582 #         }
583 #      ]
584 #    }
585 #
586 ##
587 {'command': 'query-command-line-options',
588  'data': { '*option': 'str' },
589  'returns': ['CommandLineOptionInfo'],
590  'allow-preconfig': true }
591
592 ##
593 # @xen-load-devices-state:
594 #
595 # Load the state of all devices from file. The RAM and the block devices
596 # of the VM are not loaded by this command.
597 #
598 # @filename: the file to load the state of the devices from as binary
599 #            data. See xen-save-devices-state.txt for a description of the binary
600 #            format.
601 #
602 # Since: 2.7
603 #
604 # Example:
605 #
606 # -> { "execute": "xen-load-devices-state",
607 #      "arguments": { "filename": "/tmp/resume" } }
608 # <- { "return": {} }
609 #
610 ##
611 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }