capstone: Update to upstream "next" branch
[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 # @KvmInfo:
73 #
74 # Information about support for KVM acceleration
75 #
76 # @enabled: true if KVM acceleration is active
77 #
78 # @present: true if KVM acceleration is built into this executable
79 #
80 # Since: 0.14.0
81 ##
82 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
83
84 ##
85 # @query-kvm:
86 #
87 # Returns information about KVM acceleration
88 #
89 # Returns: @KvmInfo
90 #
91 # Since: 0.14.0
92 #
93 # Example:
94 #
95 # -> { "execute": "query-kvm" }
96 # <- { "return": { "enabled": true, "present": true } }
97 #
98 ##
99 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
100
101 ##
102 # @IOThreadInfo:
103 #
104 # Information about an iothread
105 #
106 # @id: the identifier of the iothread
107 #
108 # @thread-id: ID of the underlying host thread
109 #
110 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
111 #               (since 2.9)
112 #
113 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
114 #             configured (since 2.9)
115 #
116 # @poll-shrink: how many ns will be removed from polling time, 0 means that
117 #               it's not configured (since 2.9)
118 #
119 # Since: 2.0
120 ##
121 { 'struct': 'IOThreadInfo',
122   'data': {'id': 'str',
123            'thread-id': 'int',
124            'poll-max-ns': 'int',
125            'poll-grow': 'int',
126            'poll-shrink': 'int' } }
127
128 ##
129 # @query-iothreads:
130 #
131 # Returns a list of information about each iothread.
132 #
133 # Note: this list excludes the QEMU main loop thread, which is not declared
134 #       using the -object iothread command-line option.  It is always the main thread
135 #       of the process.
136 #
137 # Returns: a list of @IOThreadInfo for each iothread
138 #
139 # Since: 2.0
140 #
141 # Example:
142 #
143 # -> { "execute": "query-iothreads" }
144 # <- { "return": [
145 #          {
146 #             "id":"iothread0",
147 #             "thread-id":3134
148 #          },
149 #          {
150 #             "id":"iothread1",
151 #             "thread-id":3135
152 #          }
153 #       ]
154 #    }
155 #
156 ##
157 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
158   'allow-preconfig': true }
159
160 ##
161 # @stop:
162 #
163 # Stop all guest VCPU execution.
164 #
165 # Since:  0.14.0
166 #
167 # Notes: This function will succeed even if the guest is already in the stopped
168 #        state.  In "inmigrate" state, it will ensure that the guest
169 #        remains paused once migration finishes, as if the -S option was
170 #        passed on the command line.
171 #
172 # Example:
173 #
174 # -> { "execute": "stop" }
175 # <- { "return": {} }
176 #
177 ##
178 { 'command': 'stop' }
179
180 ##
181 # @system_reset:
182 #
183 # Performs a hard reset of a guest.
184 #
185 # Since: 0.14.0
186 #
187 # Example:
188 #
189 # -> { "execute": "system_reset" }
190 # <- { "return": {} }
191 #
192 ##
193 { 'command': 'system_reset' }
194
195 ##
196 # @system_powerdown:
197 #
198 # Requests that a guest perform a powerdown operation.
199 #
200 # Since: 0.14.0
201 #
202 # Notes: A guest may or may not respond to this command.  This command
203 #        returning does not indicate that a guest has accepted the request or
204 #        that it has shut down.  Many guests will respond to this command by
205 #        prompting the user in some way.
206 # Example:
207 #
208 # -> { "execute": "system_powerdown" }
209 # <- { "return": {} }
210 #
211 ##
212 { 'command': 'system_powerdown' }
213
214 ##
215 # @memsave:
216 #
217 # Save a portion of guest memory to a file.
218 #
219 # @val: the virtual address of the guest to start from
220 #
221 # @size: the size of memory region to save
222 #
223 # @filename: the file to save the memory to as binary data
224 #
225 # @cpu-index: the index of the virtual CPU to use for translating the
226 #             virtual address (defaults to CPU 0)
227 #
228 # Returns: Nothing on success
229 #
230 # Since: 0.14.0
231 #
232 # Notes: Errors were not reliably returned until 1.1
233 #
234 # Example:
235 #
236 # -> { "execute": "memsave",
237 #      "arguments": { "val": 10,
238 #                     "size": 100,
239 #                     "filename": "/tmp/virtual-mem-dump" } }
240 # <- { "return": {} }
241 #
242 ##
243 { 'command': 'memsave',
244   'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
245
246 ##
247 # @pmemsave:
248 #
249 # Save a portion of guest physical memory to a file.
250 #
251 # @val: the physical address of the guest to start from
252 #
253 # @size: the size of memory region to save
254 #
255 # @filename: the file to save the memory to as binary data
256 #
257 # Returns: Nothing on success
258 #
259 # Since: 0.14.0
260 #
261 # Notes: Errors were not reliably returned until 1.1
262 #
263 # Example:
264 #
265 # -> { "execute": "pmemsave",
266 #      "arguments": { "val": 10,
267 #                     "size": 100,
268 #                     "filename": "/tmp/physical-mem-dump" } }
269 # <- { "return": {} }
270 #
271 ##
272 { 'command': 'pmemsave',
273   'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
274
275 ##
276 # @cont:
277 #
278 # Resume guest VCPU execution.
279 #
280 # Since:  0.14.0
281 #
282 # Returns:  If successful, nothing
283 #
284 # Notes: This command will succeed if the guest is currently running.  It
285 #        will also succeed if the guest is in the "inmigrate" state; in
286 #        this case, the effect of the command is to make sure the guest
287 #        starts once migration finishes, removing the effect of the -S
288 #        command line option if it was passed.
289 #
290 # Example:
291 #
292 # -> { "execute": "cont" }
293 # <- { "return": {} }
294 #
295 ##
296 { 'command': 'cont' }
297
298 ##
299 # @x-exit-preconfig:
300 #
301 # Exit from "preconfig" state
302 #
303 # This command makes QEMU exit the preconfig state and proceed with
304 # VM initialization using configuration data provided on the command line
305 # and via the QMP monitor during the preconfig state. The command is only
306 # available during the preconfig state (i.e. when the --preconfig command
307 # line option was in use).
308 #
309 # Since 3.0
310 #
311 # Returns: nothing
312 #
313 # Example:
314 #
315 # -> { "execute": "x-exit-preconfig" }
316 # <- { "return": {} }
317 #
318 ##
319 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }
320
321 ##
322 # @system_wakeup:
323 #
324 # Wake up guest from suspend. If the guest has wake-up from suspend
325 # support enabled (wakeup-suspend-support flag from
326 # query-current-machine), wake-up guest from suspend if the guest is
327 # in SUSPENDED state. Return an error otherwise.
328 #
329 # Since:  1.1
330 #
331 # Returns:  nothing.
332 #
333 # Note: prior to 4.0, this command does nothing in case the guest
334 #       isn't suspended.
335 #
336 # Example:
337 #
338 # -> { "execute": "system_wakeup" }
339 # <- { "return": {} }
340 #
341 ##
342 { 'command': 'system_wakeup' }
343
344 ##
345 # @inject-nmi:
346 #
347 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
348 # The command fails when the guest doesn't support injecting.
349 #
350 # Returns:  If successful, nothing
351 #
352 # Since:  0.14.0
353 #
354 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
355 #
356 # Example:
357 #
358 # -> { "execute": "inject-nmi" }
359 # <- { "return": {} }
360 #
361 ##
362 { 'command': 'inject-nmi' }
363
364 ##
365 # @human-monitor-command:
366 #
367 # Execute a command on the human monitor and return the output.
368 #
369 # @command-line: the command to execute in the human monitor
370 #
371 # @cpu-index: The CPU to use for commands that require an implicit CPU
372 #
373 # Features:
374 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
375 #                        monitor-owned nodes if they have no parents.
376 #                        This allows the use of 'savevm' with
377 #                        -blockdev. (since 4.2)
378 #
379 # Returns: the output of the command as a string
380 #
381 # Since: 0.14.0
382 #
383 # Notes: This command only exists as a stop-gap.  Its use is highly
384 #        discouraged.  The semantics of this command are not
385 #        guaranteed: this means that command names, arguments and
386 #        responses can change or be removed at ANY time.  Applications
387 #        that rely on long term stability guarantees should NOT
388 #        use this command.
389 #
390 #        Known limitations:
391 #
392 #        * This command is stateless, this means that commands that depend
393 #          on state information (such as getfd) might not work
394 #
395 #        * Commands that prompt the user for data don't currently work
396 #
397 # Example:
398 #
399 # -> { "execute": "human-monitor-command",
400 #      "arguments": { "command-line": "info kvm" } }
401 # <- { "return": "kvm support: enabled\r\n" }
402 #
403 ##
404 { 'command': 'human-monitor-command',
405   'data': {'command-line': 'str', '*cpu-index': 'int'},
406   'returns': 'str',
407   'features': [ 'savevm-monitor-nodes' ] }
408
409 ##
410 # @change:
411 #
412 # This command is multiple commands multiplexed together.
413 #
414 # @device: This is normally the name of a block device but it may also be 'vnc'.
415 #          when it's 'vnc', then sub command depends on @target
416 #
417 # @target: If @device is a block device, then this is the new filename.
418 #          If @device is 'vnc', then if the value 'password' selects the vnc
419 #          change password command.   Otherwise, this specifies a new server URI
420 #          address to listen to for VNC connections.
421 #
422 # @arg: If @device is a block device, then this is an optional format to open
423 #       the device with.
424 #       If @device is 'vnc' and @target is 'password', this is the new VNC
425 #       password to set.  See change-vnc-password for additional notes.
426 #
427 # Features:
428 # @deprecated: This command is deprecated.  For changing block
429 #              devices, use 'blockdev-change-medium' instead; for changing VNC
430 #              parameters, use 'change-vnc-password' instead.
431 #
432 # Returns: - Nothing on success.
433 #          - If @device is not a valid block device, DeviceNotFound
434 #
435 # Since: 0.14.0
436 #
437 # Example:
438 #
439 # 1. Change a removable medium
440 #
441 # -> { "execute": "change",
442 #      "arguments": { "device": "ide1-cd0",
443 #                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
444 # <- { "return": {} }
445 #
446 # 2. Change VNC password
447 #
448 # -> { "execute": "change",
449 #      "arguments": { "device": "vnc", "target": "password",
450 #                     "arg": "foobar1" } }
451 # <- { "return": {} }
452 #
453 ##
454 { 'command': 'change',
455   'data': {'device': 'str', 'target': 'str', '*arg': 'str'},
456   'features': [ 'deprecated' ] }
457
458 ##
459 # @xen-set-global-dirty-log:
460 #
461 # Enable or disable the global dirty log mode.
462 #
463 # @enable: true to enable, false to disable.
464 #
465 # Returns: nothing
466 #
467 # Since: 1.3
468 #
469 # Example:
470 #
471 # -> { "execute": "xen-set-global-dirty-log",
472 #      "arguments": { "enable": true } }
473 # <- { "return": {} }
474 #
475 ##
476 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
477
478 ##
479 # @getfd:
480 #
481 # Receive a file descriptor via SCM rights and assign it a name
482 #
483 # @fdname: file descriptor name
484 #
485 # Returns: Nothing on success
486 #
487 # Since: 0.14.0
488 #
489 # Notes: If @fdname already exists, the file descriptor assigned to
490 #        it will be closed and replaced by the received file
491 #        descriptor.
492 #
493 #        The 'closefd' command can be used to explicitly close the
494 #        file descriptor when it is no longer needed.
495 #
496 # Example:
497 #
498 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
499 # <- { "return": {} }
500 #
501 ##
502 { 'command': 'getfd', 'data': {'fdname': 'str'} }
503
504 ##
505 # @closefd:
506 #
507 # Close a file descriptor previously passed via SCM rights
508 #
509 # @fdname: file descriptor name
510 #
511 # Returns: Nothing on success
512 #
513 # Since: 0.14.0
514 #
515 # Example:
516 #
517 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
518 # <- { "return": {} }
519 #
520 ##
521 { 'command': 'closefd', 'data': {'fdname': 'str'} }
522
523 ##
524 # @AddfdInfo:
525 #
526 # Information about a file descriptor that was added to an fd set.
527 #
528 # @fdset-id: The ID of the fd set that @fd was added to.
529 #
530 # @fd: The file descriptor that was received via SCM rights and
531 #      added to the fd set.
532 #
533 # Since: 1.2.0
534 ##
535 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
536
537 ##
538 # @add-fd:
539 #
540 # Add a file descriptor, that was passed via SCM rights, to an fd set.
541 #
542 # @fdset-id: The ID of the fd set to add the file descriptor to.
543 #
544 # @opaque: A free-form string that can be used to describe the fd.
545 #
546 # Returns: - @AddfdInfo on success
547 #          - If file descriptor was not received, FdNotSupplied
548 #          - If @fdset-id is a negative value, InvalidParameterValue
549 #
550 # Notes: The list of fd sets is shared by all monitor connections.
551 #
552 #        If @fdset-id is not specified, a new fd set will be created.
553 #
554 # Since: 1.2.0
555 #
556 # Example:
557 #
558 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
559 # <- { "return": { "fdset-id": 1, "fd": 3 } }
560 #
561 ##
562 { 'command': 'add-fd',
563   'data': { '*fdset-id': 'int',
564             '*opaque': 'str' },
565   'returns': 'AddfdInfo' }
566
567 ##
568 # @remove-fd:
569 #
570 # Remove a file descriptor from an fd set.
571 #
572 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
573 #
574 # @fd: The file descriptor that is to be removed.
575 #
576 # Returns: - Nothing on success
577 #          - If @fdset-id or @fd is not found, FdNotFound
578 #
579 # Since: 1.2.0
580 #
581 # Notes: The list of fd sets is shared by all monitor connections.
582 #
583 #        If @fd is not specified, all file descriptors in @fdset-id
584 #        will be removed.
585 #
586 # Example:
587 #
588 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
589 # <- { "return": {} }
590 #
591 ##
592 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
593
594 ##
595 # @FdsetFdInfo:
596 #
597 # Information about a file descriptor that belongs to an fd set.
598 #
599 # @fd: The file descriptor value.
600 #
601 # @opaque: A free-form string that can be used to describe the fd.
602 #
603 # Since: 1.2.0
604 ##
605 { 'struct': 'FdsetFdInfo',
606   'data': {'fd': 'int', '*opaque': 'str'} }
607
608 ##
609 # @FdsetInfo:
610 #
611 # Information about an fd set.
612 #
613 # @fdset-id: The ID of the fd set.
614 #
615 # @fds: A list of file descriptors that belong to this fd set.
616 #
617 # Since: 1.2.0
618 ##
619 { 'struct': 'FdsetInfo',
620   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
621
622 ##
623 # @query-fdsets:
624 #
625 # Return information describing all fd sets.
626 #
627 # Returns: A list of @FdsetInfo
628 #
629 # Since: 1.2.0
630 #
631 # Note: The list of fd sets is shared by all monitor connections.
632 #
633 # Example:
634 #
635 # -> { "execute": "query-fdsets" }
636 # <- { "return": [
637 #        {
638 #          "fds": [
639 #            {
640 #              "fd": 30,
641 #              "opaque": "rdonly:/path/to/file"
642 #            },
643 #            {
644 #              "fd": 24,
645 #              "opaque": "rdwr:/path/to/file"
646 #            }
647 #          ],
648 #          "fdset-id": 1
649 #        },
650 #        {
651 #          "fds": [
652 #            {
653 #              "fd": 28
654 #            },
655 #            {
656 #              "fd": 29
657 #            }
658 #          ],
659 #          "fdset-id": 0
660 #        }
661 #      ]
662 #    }
663 #
664 ##
665 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
666
667 ##
668 # @CommandLineParameterType:
669 #
670 # Possible types for an option parameter.
671 #
672 # @string: accepts a character string
673 #
674 # @boolean: accepts "on" or "off"
675 #
676 # @number: accepts a number
677 #
678 # @size: accepts a number followed by an optional suffix (K)ilo,
679 #        (M)ega, (G)iga, (T)era
680 #
681 # Since: 1.5
682 ##
683 { 'enum': 'CommandLineParameterType',
684   'data': ['string', 'boolean', 'number', 'size'] }
685
686 ##
687 # @CommandLineParameterInfo:
688 #
689 # Details about a single parameter of a command line option.
690 #
691 # @name: parameter name
692 #
693 # @type: parameter @CommandLineParameterType
694 #
695 # @help: human readable text string, not suitable for parsing.
696 #
697 # @default: default value string (since 2.1)
698 #
699 # Since: 1.5
700 ##
701 { 'struct': 'CommandLineParameterInfo',
702   'data': { 'name': 'str',
703             'type': 'CommandLineParameterType',
704             '*help': 'str',
705             '*default': 'str' } }
706
707 ##
708 # @CommandLineOptionInfo:
709 #
710 # Details about a command line option, including its list of parameter details
711 #
712 # @option: option name
713 #
714 # @parameters: an array of @CommandLineParameterInfo
715 #
716 # Since: 1.5
717 ##
718 { 'struct': 'CommandLineOptionInfo',
719   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
720
721 ##
722 # @query-command-line-options:
723 #
724 # Query command line option schema.
725 #
726 # @option: option name
727 #
728 # Returns: list of @CommandLineOptionInfo for all options (or for the given
729 #          @option).  Returns an error if the given @option doesn't exist.
730 #
731 # Since: 1.5
732 #
733 # Example:
734 #
735 # -> { "execute": "query-command-line-options",
736 #      "arguments": { "option": "option-rom" } }
737 # <- { "return": [
738 #         {
739 #             "parameters": [
740 #                 {
741 #                     "name": "romfile",
742 #                     "type": "string"
743 #                 },
744 #                 {
745 #                     "name": "bootindex",
746 #                     "type": "number"
747 #                 }
748 #             ],
749 #             "option": "option-rom"
750 #         }
751 #      ]
752 #    }
753 #
754 ##
755 {'command': 'query-command-line-options',
756  'data': { '*option': 'str' },
757  'returns': ['CommandLineOptionInfo'],
758  'allow-preconfig': true }
759
760 ##
761 # @ReplayMode:
762 #
763 # Mode of the replay subsystem.
764 #
765 # @none: normal execution mode. Replay or record are not enabled.
766 #
767 # @record: record mode. All non-deterministic data is written into the
768 #          replay log.
769 #
770 # @play: replay mode. Non-deterministic data required for system execution
771 #        is read from the log.
772 #
773 # Since: 2.5
774 ##
775 { 'enum': 'ReplayMode',
776   'data': [ 'none', 'record', 'play' ] }
777
778 ##
779 # @xen-load-devices-state:
780 #
781 # Load the state of all devices from file. The RAM and the block devices
782 # of the VM are not loaded by this command.
783 #
784 # @filename: the file to load the state of the devices from as binary
785 #            data. See xen-save-devices-state.txt for a description of the binary
786 #            format.
787 #
788 # Since: 2.7
789 #
790 # Example:
791 #
792 # -> { "execute": "xen-load-devices-state",
793 #      "arguments": { "filename": "/tmp/resume" } }
794 # <- { "return": {} }
795 #
796 ##
797 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }