target/riscv: vmfirst find-first-set mask bit
[qemu.git] / qapi / misc.json
1 # -*- Mode: Python -*-
2 #
3
4 ##
5 # = Miscellanea
6 ##
7
8 { 'include': 'common.json' }
9
10 ##
11 # @LostTickPolicy:
12 #
13 # Policy for handling lost ticks in timer devices.  Ticks end up getting
14 # lost when, for example, the guest is paused.
15 #
16 # @discard: throw away the missed ticks and continue with future injection
17 #           normally.  The guest OS will see the timer jump ahead by a
18 #           potentially quite significant amount all at once, as if the
19 #           intervening chunk of time had simply not existed; needless to
20 #           say, such a sudden jump can easily confuse a guest OS which is
21 #           not specifically prepared to deal with it.  Assuming the guest
22 #           OS can deal correctly with the time jump, the time in the guest
23 #           and in the host should now match.
24 #
25 # @delay: continue to deliver ticks at the normal rate.  The guest OS will
26 #         not notice anything is amiss, as from its point of view time will
27 #         have continued to flow normally.  The time in the guest should now
28 #         be behind the time in the host by exactly the amount of time during
29 #         which ticks have been missed.
30 #
31 # @slew: deliver ticks at a higher rate to catch up with the missed ticks.
32 #        The guest OS will not notice anything is amiss, as from its point
33 #        of view time will have continued to flow normally.  Once the timer
34 #        has managed to catch up with all the missing ticks, the time in
35 #        the guest and in the host should match.
36 #
37 # Since: 2.0
38 ##
39 { 'enum': 'LostTickPolicy',
40   'data': ['discard', 'delay', 'slew' ] }
41
42 ##
43 # @add_client:
44 #
45 # Allow client connections for VNC, Spice and socket based
46 # character devices to be passed in to QEMU via SCM_RIGHTS.
47 #
48 # @protocol: protocol name. Valid names are "vnc", "spice" or the
49 #            name of a character device (eg. from -chardev id=XXXX)
50 #
51 # @fdname: file descriptor name previously passed via 'getfd' command
52 #
53 # @skipauth: whether to skip authentication. Only applies
54 #            to "vnc" and "spice" protocols
55 #
56 # @tls: whether to perform TLS. Only applies to the "spice"
57 #       protocol
58 #
59 # Returns: nothing on success.
60 #
61 # Since: 0.14.0
62 #
63 # Example:
64 #
65 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
66 #                                              "fdname": "myclient" } }
67 # <- { "return": {} }
68 #
69 ##
70 { 'command': 'add_client',
71   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
72             '*tls': 'bool' } }
73
74 ##
75 # @NameInfo:
76 #
77 # Guest name information.
78 #
79 # @name: The name of the guest
80 #
81 # Since: 0.14.0
82 ##
83 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
84
85 ##
86 # @query-name:
87 #
88 # Return the name information of a guest.
89 #
90 # Returns: @NameInfo of the guest
91 #
92 # Since: 0.14.0
93 #
94 # Example:
95 #
96 # -> { "execute": "query-name" }
97 # <- { "return": { "name": "qemu-name" } }
98 #
99 ##
100 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
101
102 ##
103 # @KvmInfo:
104 #
105 # Information about support for KVM acceleration
106 #
107 # @enabled: true if KVM acceleration is active
108 #
109 # @present: true if KVM acceleration is built into this executable
110 #
111 # Since: 0.14.0
112 ##
113 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
114
115 ##
116 # @query-kvm:
117 #
118 # Returns information about KVM acceleration
119 #
120 # Returns: @KvmInfo
121 #
122 # Since: 0.14.0
123 #
124 # Example:
125 #
126 # -> { "execute": "query-kvm" }
127 # <- { "return": { "enabled": true, "present": true } }
128 #
129 ##
130 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
131
132 ##
133 # @UuidInfo:
134 #
135 # Guest UUID information (Universally Unique Identifier).
136 #
137 # @UUID: the UUID of the guest
138 #
139 # Since: 0.14.0
140 #
141 # Notes: If no UUID was specified for the guest, a null UUID is returned.
142 ##
143 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
144
145 ##
146 # @query-uuid:
147 #
148 # Query the guest UUID information.
149 #
150 # Returns: The @UuidInfo for the guest
151 #
152 # Since: 0.14.0
153 #
154 # Example:
155 #
156 # -> { "execute": "query-uuid" }
157 # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
158 #
159 ##
160 { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
161
162 ##
163 # @IOThreadInfo:
164 #
165 # Information about an iothread
166 #
167 # @id: the identifier of the iothread
168 #
169 # @thread-id: ID of the underlying host thread
170 #
171 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
172 #               (since 2.9)
173 #
174 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
175 #             configured (since 2.9)
176 #
177 # @poll-shrink: how many ns will be removed from polling time, 0 means that
178 #               it's not configured (since 2.9)
179 #
180 # Since: 2.0
181 ##
182 { 'struct': 'IOThreadInfo',
183   'data': {'id': 'str',
184            'thread-id': 'int',
185            'poll-max-ns': 'int',
186            'poll-grow': 'int',
187            'poll-shrink': 'int' } }
188
189 ##
190 # @query-iothreads:
191 #
192 # Returns a list of information about each iothread.
193 #
194 # Note: this list excludes the QEMU main loop thread, which is not declared
195 #       using the -object iothread command-line option.  It is always the main thread
196 #       of the process.
197 #
198 # Returns: a list of @IOThreadInfo for each iothread
199 #
200 # Since: 2.0
201 #
202 # Example:
203 #
204 # -> { "execute": "query-iothreads" }
205 # <- { "return": [
206 #          {
207 #             "id":"iothread0",
208 #             "thread-id":3134
209 #          },
210 #          {
211 #             "id":"iothread1",
212 #             "thread-id":3135
213 #          }
214 #       ]
215 #    }
216 #
217 ##
218 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
219   'allow-preconfig': true }
220
221 ##
222 # @BalloonInfo:
223 #
224 # Information about the guest balloon device.
225 #
226 # @actual: the number of bytes the balloon currently contains
227 #
228 # Since: 0.14.0
229 #
230 ##
231 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
232
233 ##
234 # @query-balloon:
235 #
236 # Return information about the balloon device.
237 #
238 # Returns: - @BalloonInfo on success
239 #          - If the balloon driver is enabled but not functional because the KVM
240 #            kernel module cannot support it, KvmMissingCap
241 #          - If no balloon device is present, DeviceNotActive
242 #
243 # Since: 0.14.0
244 #
245 # Example:
246 #
247 # -> { "execute": "query-balloon" }
248 # <- { "return": {
249 #          "actual": 1073741824,
250 #       }
251 #    }
252 #
253 ##
254 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
255
256 ##
257 # @BALLOON_CHANGE:
258 #
259 # Emitted when the guest changes the actual BALLOON level. This value is
260 # equivalent to the @actual field return by the 'query-balloon' command
261 #
262 # @actual: actual level of the guest memory balloon in bytes
263 #
264 # Note: this event is rate-limited.
265 #
266 # Since: 1.2
267 #
268 # Example:
269 #
270 # <- { "event": "BALLOON_CHANGE",
271 #      "data": { "actual": 944766976 },
272 #      "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
273 #
274 ##
275 { 'event': 'BALLOON_CHANGE',
276   'data': { 'actual': 'int' } }
277
278 ##
279 # @PciMemoryRange:
280 #
281 # A PCI device memory region
282 #
283 # @base: the starting address (guest physical)
284 #
285 # @limit: the ending address (guest physical)
286 #
287 # Since: 0.14.0
288 ##
289 { 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
290
291 ##
292 # @PciMemoryRegion:
293 #
294 # Information about a PCI device I/O region.
295 #
296 # @bar: the index of the Base Address Register for this region
297 #
298 # @type: - 'io' if the region is a PIO region
299 #        - 'memory' if the region is a MMIO region
300 #
301 # @size: memory size
302 #
303 # @prefetch: if @type is 'memory', true if the memory is prefetchable
304 #
305 # @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
306 #
307 # Since: 0.14.0
308 ##
309 { 'struct': 'PciMemoryRegion',
310   'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
311            '*prefetch': 'bool', '*mem_type_64': 'bool' } }
312
313 ##
314 # @PciBusInfo:
315 #
316 # Information about a bus of a PCI Bridge device
317 #
318 # @number: primary bus interface number.  This should be the number of the
319 #          bus the device resides on.
320 #
321 # @secondary: secondary bus interface number.  This is the number of the
322 #             main bus for the bridge
323 #
324 # @subordinate: This is the highest number bus that resides below the
325 #               bridge.
326 #
327 # @io_range: The PIO range for all devices on this bridge
328 #
329 # @memory_range: The MMIO range for all devices on this bridge
330 #
331 # @prefetchable_range: The range of prefetchable MMIO for all devices on
332 #                      this bridge
333 #
334 # Since: 2.4
335 ##
336 { 'struct': 'PciBusInfo',
337   'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
338            'io_range': 'PciMemoryRange',
339            'memory_range': 'PciMemoryRange',
340            'prefetchable_range': 'PciMemoryRange' } }
341
342 ##
343 # @PciBridgeInfo:
344 #
345 # Information about a PCI Bridge device
346 #
347 # @bus: information about the bus the device resides on
348 #
349 # @devices: a list of @PciDeviceInfo for each device on this bridge
350 #
351 # Since: 0.14.0
352 ##
353 { 'struct': 'PciBridgeInfo',
354   'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }
355
356 ##
357 # @PciDeviceClass:
358 #
359 # Information about the Class of a PCI device
360 #
361 # @desc: a string description of the device's class
362 #
363 # @class: the class code of the device
364 #
365 # Since: 2.4
366 ##
367 { 'struct': 'PciDeviceClass',
368   'data': {'*desc': 'str', 'class': 'int'} }
369
370 ##
371 # @PciDeviceId:
372 #
373 # Information about the Id of a PCI device
374 #
375 # @device: the PCI device id
376 #
377 # @vendor: the PCI vendor id
378 #
379 # @subsystem: the PCI subsystem id (since 3.1)
380 #
381 # @subsystem-vendor: the PCI subsystem vendor id (since 3.1)
382 #
383 # Since: 2.4
384 ##
385 { 'struct': 'PciDeviceId',
386   'data': {'device': 'int', 'vendor': 'int', '*subsystem': 'int',
387             '*subsystem-vendor': 'int'} }
388
389 ##
390 # @PciDeviceInfo:
391 #
392 # Information about a PCI device
393 #
394 # @bus: the bus number of the device
395 #
396 # @slot: the slot the device is located in
397 #
398 # @function: the function of the slot used by the device
399 #
400 # @class_info: the class of the device
401 #
402 # @id: the PCI device id
403 #
404 # @irq: if an IRQ is assigned to the device, the IRQ number
405 #
406 # @irq_pin: the IRQ pin, zero means no IRQ (since 5.1)
407 #
408 # @qdev_id: the device name of the PCI device
409 #
410 # @pci_bridge: if the device is a PCI bridge, the bridge information
411 #
412 # @regions: a list of the PCI I/O regions associated with the device
413 #
414 # Notes: the contents of @class_info.desc are not stable and should only be
415 #        treated as informational.
416 #
417 # Since: 0.14.0
418 ##
419 { 'struct': 'PciDeviceInfo',
420   'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
421            'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
422            '*irq': 'int', 'irq_pin': 'int', 'qdev_id': 'str',
423            '*pci_bridge': 'PciBridgeInfo', 'regions': ['PciMemoryRegion'] }}
424
425 ##
426 # @PciInfo:
427 #
428 # Information about a PCI bus
429 #
430 # @bus: the bus index
431 #
432 # @devices: a list of devices on this bus
433 #
434 # Since: 0.14.0
435 ##
436 { 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
437
438 ##
439 # @query-pci:
440 #
441 # Return information about the PCI bus topology of the guest.
442 #
443 # Returns: a list of @PciInfo for each PCI bus. Each bus is
444 #          represented by a json-object, which has a key with a json-array of
445 #          all PCI devices attached to it. Each device is represented by a
446 #          json-object.
447 #
448 # Since: 0.14.0
449 #
450 # Example:
451 #
452 # -> { "execute": "query-pci" }
453 # <- { "return": [
454 #          {
455 #             "bus": 0,
456 #             "devices": [
457 #                {
458 #                   "bus": 0,
459 #                   "qdev_id": "",
460 #                   "slot": 0,
461 #                   "class_info": {
462 #                      "class": 1536,
463 #                      "desc": "Host bridge"
464 #                   },
465 #                   "id": {
466 #                      "device": 32902,
467 #                      "vendor": 4663
468 #                   },
469 #                   "function": 0,
470 #                   "regions": [
471 #                   ]
472 #                },
473 #                {
474 #                   "bus": 0,
475 #                   "qdev_id": "",
476 #                   "slot": 1,
477 #                   "class_info": {
478 #                      "class": 1537,
479 #                      "desc": "ISA bridge"
480 #                   },
481 #                   "id": {
482 #                      "device": 32902,
483 #                      "vendor": 28672
484 #                   },
485 #                   "function": 0,
486 #                   "regions": [
487 #                   ]
488 #                },
489 #                {
490 #                   "bus": 0,
491 #                   "qdev_id": "",
492 #                   "slot": 1,
493 #                   "class_info": {
494 #                      "class": 257,
495 #                      "desc": "IDE controller"
496 #                   },
497 #                   "id": {
498 #                      "device": 32902,
499 #                      "vendor": 28688
500 #                   },
501 #                   "function": 1,
502 #                   "regions": [
503 #                      {
504 #                         "bar": 4,
505 #                         "size": 16,
506 #                         "address": 49152,
507 #                         "type": "io"
508 #                      }
509 #                   ]
510 #                },
511 #                {
512 #                   "bus": 0,
513 #                   "qdev_id": "",
514 #                   "slot": 2,
515 #                   "class_info": {
516 #                      "class": 768,
517 #                      "desc": "VGA controller"
518 #                   },
519 #                   "id": {
520 #                      "device": 4115,
521 #                      "vendor": 184
522 #                   },
523 #                   "function": 0,
524 #                   "regions": [
525 #                      {
526 #                         "prefetch": true,
527 #                         "mem_type_64": false,
528 #                         "bar": 0,
529 #                         "size": 33554432,
530 #                         "address": 4026531840,
531 #                         "type": "memory"
532 #                      },
533 #                      {
534 #                         "prefetch": false,
535 #                         "mem_type_64": false,
536 #                         "bar": 1,
537 #                         "size": 4096,
538 #                         "address": 4060086272,
539 #                         "type": "memory"
540 #                      },
541 #                      {
542 #                         "prefetch": false,
543 #                         "mem_type_64": false,
544 #                         "bar": 6,
545 #                         "size": 65536,
546 #                         "address": -1,
547 #                         "type": "memory"
548 #                      }
549 #                   ]
550 #                },
551 #                {
552 #                   "bus": 0,
553 #                   "qdev_id": "",
554 #                   "irq": 11,
555 #                   "slot": 4,
556 #                   "class_info": {
557 #                      "class": 1280,
558 #                      "desc": "RAM controller"
559 #                   },
560 #                   "id": {
561 #                      "device": 6900,
562 #                      "vendor": 4098
563 #                   },
564 #                   "function": 0,
565 #                   "regions": [
566 #                      {
567 #                         "bar": 0,
568 #                         "size": 32,
569 #                         "address": 49280,
570 #                         "type": "io"
571 #                      }
572 #                   ]
573 #                }
574 #             ]
575 #          }
576 #       ]
577 #    }
578 #
579 # Note: This example has been shortened as the real response is too long.
580 #
581 ##
582 { 'command': 'query-pci', 'returns': ['PciInfo'] }
583
584 ##
585 # @stop:
586 #
587 # Stop all guest VCPU execution.
588 #
589 # Since:  0.14.0
590 #
591 # Notes: This function will succeed even if the guest is already in the stopped
592 #        state.  In "inmigrate" state, it will ensure that the guest
593 #        remains paused once migration finishes, as if the -S option was
594 #        passed on the command line.
595 #
596 # Example:
597 #
598 # -> { "execute": "stop" }
599 # <- { "return": {} }
600 #
601 ##
602 { 'command': 'stop' }
603
604 ##
605 # @system_reset:
606 #
607 # Performs a hard reset of a guest.
608 #
609 # Since: 0.14.0
610 #
611 # Example:
612 #
613 # -> { "execute": "system_reset" }
614 # <- { "return": {} }
615 #
616 ##
617 { 'command': 'system_reset' }
618
619 ##
620 # @system_powerdown:
621 #
622 # Requests that a guest perform a powerdown operation.
623 #
624 # Since: 0.14.0
625 #
626 # Notes: A guest may or may not respond to this command.  This command
627 #        returning does not indicate that a guest has accepted the request or
628 #        that it has shut down.  Many guests will respond to this command by
629 #        prompting the user in some way.
630 # Example:
631 #
632 # -> { "execute": "system_powerdown" }
633 # <- { "return": {} }
634 #
635 ##
636 { 'command': 'system_powerdown' }
637
638 ##
639 # @memsave:
640 #
641 # Save a portion of guest memory to a file.
642 #
643 # @val: the virtual address of the guest to start from
644 #
645 # @size: the size of memory region to save
646 #
647 # @filename: the file to save the memory to as binary data
648 #
649 # @cpu-index: the index of the virtual CPU to use for translating the
650 #             virtual address (defaults to CPU 0)
651 #
652 # Returns: Nothing on success
653 #
654 # Since: 0.14.0
655 #
656 # Notes: Errors were not reliably returned until 1.1
657 #
658 # Example:
659 #
660 # -> { "execute": "memsave",
661 #      "arguments": { "val": 10,
662 #                     "size": 100,
663 #                     "filename": "/tmp/virtual-mem-dump" } }
664 # <- { "return": {} }
665 #
666 ##
667 { 'command': 'memsave',
668   'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
669
670 ##
671 # @pmemsave:
672 #
673 # Save a portion of guest physical memory to a file.
674 #
675 # @val: the physical address of the guest to start from
676 #
677 # @size: the size of memory region to save
678 #
679 # @filename: the file to save the memory to as binary data
680 #
681 # Returns: Nothing on success
682 #
683 # Since: 0.14.0
684 #
685 # Notes: Errors were not reliably returned until 1.1
686 #
687 # Example:
688 #
689 # -> { "execute": "pmemsave",
690 #      "arguments": { "val": 10,
691 #                     "size": 100,
692 #                     "filename": "/tmp/physical-mem-dump" } }
693 # <- { "return": {} }
694 #
695 ##
696 { 'command': 'pmemsave',
697   'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
698
699 ##
700 # @cont:
701 #
702 # Resume guest VCPU execution.
703 #
704 # Since:  0.14.0
705 #
706 # Returns:  If successful, nothing
707 #
708 # Notes: This command will succeed if the guest is currently running.  It
709 #        will also succeed if the guest is in the "inmigrate" state; in
710 #        this case, the effect of the command is to make sure the guest
711 #        starts once migration finishes, removing the effect of the -S
712 #        command line option if it was passed.
713 #
714 # Example:
715 #
716 # -> { "execute": "cont" }
717 # <- { "return": {} }
718 #
719 ##
720 { 'command': 'cont' }
721
722 ##
723 # @x-exit-preconfig:
724 #
725 # Exit from "preconfig" state
726 #
727 # This command makes QEMU exit the preconfig state and proceed with
728 # VM initialization using configuration data provided on the command line
729 # and via the QMP monitor during the preconfig state. The command is only
730 # available during the preconfig state (i.e. when the --preconfig command
731 # line option was in use).
732 #
733 # Since 3.0
734 #
735 # Returns: nothing
736 #
737 # Example:
738 #
739 # -> { "execute": "x-exit-preconfig" }
740 # <- { "return": {} }
741 #
742 ##
743 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }
744
745 ##
746 # @system_wakeup:
747 #
748 # Wake up guest from suspend. If the guest has wake-up from suspend
749 # support enabled (wakeup-suspend-support flag from
750 # query-current-machine), wake-up guest from suspend if the guest is
751 # in SUSPENDED state. Return an error otherwise.
752 #
753 # Since:  1.1
754 #
755 # Returns:  nothing.
756 #
757 # Note: prior to 4.0, this command does nothing in case the guest
758 #       isn't suspended.
759 #
760 # Example:
761 #
762 # -> { "execute": "system_wakeup" }
763 # <- { "return": {} }
764 #
765 ##
766 { 'command': 'system_wakeup' }
767
768 ##
769 # @inject-nmi:
770 #
771 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
772 # The command fails when the guest doesn't support injecting.
773 #
774 # Returns:  If successful, nothing
775 #
776 # Since:  0.14.0
777 #
778 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
779 #
780 # Example:
781 #
782 # -> { "execute": "inject-nmi" }
783 # <- { "return": {} }
784 #
785 ##
786 { 'command': 'inject-nmi' }
787
788 ##
789 # @balloon:
790 #
791 # Request the balloon driver to change its balloon size.
792 #
793 # @value: the target size of the balloon in bytes
794 #
795 # Returns: - Nothing on success
796 #          - If the balloon driver is enabled but not functional because the KVM
797 #            kernel module cannot support it, KvmMissingCap
798 #          - If no balloon device is present, DeviceNotActive
799 #
800 # Notes: This command just issues a request to the guest.  When it returns,
801 #        the balloon size may not have changed.  A guest can change the balloon
802 #        size independent of this command.
803 #
804 # Since: 0.14.0
805 #
806 # Example:
807 #
808 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
809 # <- { "return": {} }
810 #
811 ##
812 { 'command': 'balloon', 'data': {'value': 'int'} }
813
814 ##
815 # @human-monitor-command:
816 #
817 # Execute a command on the human monitor and return the output.
818 #
819 # @command-line: the command to execute in the human monitor
820 #
821 # @cpu-index: The CPU to use for commands that require an implicit CPU
822 #
823 # Features:
824 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
825 #                        monitor-owned nodes if they have no parents.
826 #                        This allows the use of 'savevm' with
827 #                        -blockdev. (since 4.2)
828 #
829 # Returns: the output of the command as a string
830 #
831 # Since: 0.14.0
832 #
833 # Notes: This command only exists as a stop-gap.  Its use is highly
834 #        discouraged.  The semantics of this command are not
835 #        guaranteed: this means that command names, arguments and
836 #        responses can change or be removed at ANY time.  Applications
837 #        that rely on long term stability guarantees should NOT
838 #        use this command.
839 #
840 #        Known limitations:
841 #
842 #        * This command is stateless, this means that commands that depend
843 #          on state information (such as getfd) might not work
844 #
845 #        * Commands that prompt the user for data don't currently work
846 #
847 # Example:
848 #
849 # -> { "execute": "human-monitor-command",
850 #      "arguments": { "command-line": "info kvm" } }
851 # <- { "return": "kvm support: enabled\r\n" }
852 #
853 ##
854 { 'command': 'human-monitor-command',
855   'data': {'command-line': 'str', '*cpu-index': 'int'},
856   'returns': 'str',
857   'features': [ 'savevm-monitor-nodes' ] }
858
859 ##
860 # @change:
861 #
862 # This command is multiple commands multiplexed together.
863 #
864 # @device: This is normally the name of a block device but it may also be 'vnc'.
865 #          when it's 'vnc', then sub command depends on @target
866 #
867 # @target: If @device is a block device, then this is the new filename.
868 #          If @device is 'vnc', then if the value 'password' selects the vnc
869 #          change password command.   Otherwise, this specifies a new server URI
870 #          address to listen to for VNC connections.
871 #
872 # @arg: If @device is a block device, then this is an optional format to open
873 #       the device with.
874 #       If @device is 'vnc' and @target is 'password', this is the new VNC
875 #       password to set.  See change-vnc-password for additional notes.
876 #
877 # Features:
878 # @deprecated: This command is deprecated.  For changing block
879 #     devices, use 'blockdev-change-medium' instead; for changing VNC
880 #     parameters, use 'change-vnc-password' instead.
881 #
882 # Returns: - Nothing on success.
883 #          - If @device is not a valid block device, DeviceNotFound
884 #
885 # Since: 0.14.0
886 #
887 # Example:
888 #
889 # 1. Change a removable medium
890 #
891 # -> { "execute": "change",
892 #      "arguments": { "device": "ide1-cd0",
893 #                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
894 # <- { "return": {} }
895 #
896 # 2. Change VNC password
897 #
898 # -> { "execute": "change",
899 #      "arguments": { "device": "vnc", "target": "password",
900 #                     "arg": "foobar1" } }
901 # <- { "return": {} }
902 #
903 ##
904 { 'command': 'change',
905   'data': {'device': 'str', 'target': 'str', '*arg': 'str'},
906   'features': [ 'deprecated' ] }
907
908 ##
909 # @xen-set-global-dirty-log:
910 #
911 # Enable or disable the global dirty log mode.
912 #
913 # @enable: true to enable, false to disable.
914 #
915 # Returns: nothing
916 #
917 # Since: 1.3
918 #
919 # Example:
920 #
921 # -> { "execute": "xen-set-global-dirty-log",
922 #      "arguments": { "enable": true } }
923 # <- { "return": {} }
924 #
925 ##
926 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
927
928 ##
929 # @getfd:
930 #
931 # Receive a file descriptor via SCM rights and assign it a name
932 #
933 # @fdname: file descriptor name
934 #
935 # Returns: Nothing on success
936 #
937 # Since: 0.14.0
938 #
939 # Notes: If @fdname already exists, the file descriptor assigned to
940 #        it will be closed and replaced by the received file
941 #        descriptor.
942 #
943 #        The 'closefd' command can be used to explicitly close the
944 #        file descriptor when it is no longer needed.
945 #
946 # Example:
947 #
948 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
949 # <- { "return": {} }
950 #
951 ##
952 { 'command': 'getfd', 'data': {'fdname': 'str'} }
953
954 ##
955 # @closefd:
956 #
957 # Close a file descriptor previously passed via SCM rights
958 #
959 # @fdname: file descriptor name
960 #
961 # Returns: Nothing on success
962 #
963 # Since: 0.14.0
964 #
965 # Example:
966 #
967 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
968 # <- { "return": {} }
969 #
970 ##
971 { 'command': 'closefd', 'data': {'fdname': 'str'} }
972
973 ##
974 # @MemoryInfo:
975 #
976 # Actual memory information in bytes.
977 #
978 # @base-memory: size of "base" memory specified with command line
979 #               option -m.
980 #
981 # @plugged-memory: size of memory that can be hot-unplugged. This field
982 #                  is omitted if target doesn't support memory hotplug
983 #                  (i.e. CONFIG_MEM_DEVICE not defined at build time).
984 #
985 # Since: 2.11.0
986 ##
987 { 'struct': 'MemoryInfo',
988   'data'  : { 'base-memory': 'size', '*plugged-memory': 'size' } }
989
990 ##
991 # @query-memory-size-summary:
992 #
993 # Return the amount of initially allocated and present hotpluggable (if
994 # enabled) memory in bytes.
995 #
996 # Example:
997 #
998 # -> { "execute": "query-memory-size-summary" }
999 # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
1000 #
1001 # Since: 2.11.0
1002 ##
1003 { 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
1004
1005
1006 ##
1007 # @AddfdInfo:
1008 #
1009 # Information about a file descriptor that was added to an fd set.
1010 #
1011 # @fdset-id: The ID of the fd set that @fd was added to.
1012 #
1013 # @fd: The file descriptor that was received via SCM rights and
1014 #      added to the fd set.
1015 #
1016 # Since: 1.2.0
1017 ##
1018 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
1019
1020 ##
1021 # @add-fd:
1022 #
1023 # Add a file descriptor, that was passed via SCM rights, to an fd set.
1024 #
1025 # @fdset-id: The ID of the fd set to add the file descriptor to.
1026 #
1027 # @opaque: A free-form string that can be used to describe the fd.
1028 #
1029 # Returns: - @AddfdInfo on success
1030 #          - If file descriptor was not received, FdNotSupplied
1031 #          - If @fdset-id is a negative value, InvalidParameterValue
1032 #
1033 # Notes: The list of fd sets is shared by all monitor connections.
1034 #
1035 #        If @fdset-id is not specified, a new fd set will be created.
1036 #
1037 # Since: 1.2.0
1038 #
1039 # Example:
1040 #
1041 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1042 # <- { "return": { "fdset-id": 1, "fd": 3 } }
1043 #
1044 ##
1045 { 'command': 'add-fd',
1046   'data': { '*fdset-id': 'int',
1047             '*opaque': 'str' },
1048   'returns': 'AddfdInfo' }
1049
1050 ##
1051 # @remove-fd:
1052 #
1053 # Remove a file descriptor from an fd set.
1054 #
1055 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
1056 #
1057 # @fd: The file descriptor that is to be removed.
1058 #
1059 # Returns: - Nothing on success
1060 #          - If @fdset-id or @fd is not found, FdNotFound
1061 #
1062 # Since: 1.2.0
1063 #
1064 # Notes: The list of fd sets is shared by all monitor connections.
1065 #
1066 #        If @fd is not specified, all file descriptors in @fdset-id
1067 #        will be removed.
1068 #
1069 # Example:
1070 #
1071 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1072 # <- { "return": {} }
1073 #
1074 ##
1075 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
1076
1077 ##
1078 # @FdsetFdInfo:
1079 #
1080 # Information about a file descriptor that belongs to an fd set.
1081 #
1082 # @fd: The file descriptor value.
1083 #
1084 # @opaque: A free-form string that can be used to describe the fd.
1085 #
1086 # Since: 1.2.0
1087 ##
1088 { 'struct': 'FdsetFdInfo',
1089   'data': {'fd': 'int', '*opaque': 'str'} }
1090
1091 ##
1092 # @FdsetInfo:
1093 #
1094 # Information about an fd set.
1095 #
1096 # @fdset-id: The ID of the fd set.
1097 #
1098 # @fds: A list of file descriptors that belong to this fd set.
1099 #
1100 # Since: 1.2.0
1101 ##
1102 { 'struct': 'FdsetInfo',
1103   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
1104
1105 ##
1106 # @query-fdsets:
1107 #
1108 # Return information describing all fd sets.
1109 #
1110 # Returns: A list of @FdsetInfo
1111 #
1112 # Since: 1.2.0
1113 #
1114 # Note: The list of fd sets is shared by all monitor connections.
1115 #
1116 # Example:
1117 #
1118 # -> { "execute": "query-fdsets" }
1119 # <- { "return": [
1120 #        {
1121 #          "fds": [
1122 #            {
1123 #              "fd": 30,
1124 #              "opaque": "rdonly:/path/to/file"
1125 #            },
1126 #            {
1127 #              "fd": 24,
1128 #              "opaque": "rdwr:/path/to/file"
1129 #            }
1130 #          ],
1131 #          "fdset-id": 1
1132 #        },
1133 #        {
1134 #          "fds": [
1135 #            {
1136 #              "fd": 28
1137 #            },
1138 #            {
1139 #              "fd": 29
1140 #            }
1141 #          ],
1142 #          "fdset-id": 0
1143 #        }
1144 #      ]
1145 #    }
1146 #
1147 ##
1148 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
1149
1150 ##
1151 # @AcpiTableOptions:
1152 #
1153 # Specify an ACPI table on the command line to load.
1154 #
1155 # At most one of @file and @data can be specified. The list of files specified
1156 # by any one of them is loaded and concatenated in order. If both are omitted,
1157 # @data is implied.
1158 #
1159 # Other fields / optargs can be used to override fields of the generic ACPI
1160 # table header; refer to the ACPI specification 5.0, section 5.2.6 System
1161 # Description Table Header. If a header field is not overridden, then the
1162 # corresponding value from the concatenated blob is used (in case of @file), or
1163 # it is filled in with a hard-coded value (in case of @data).
1164 #
1165 # String fields are copied into the matching ACPI member from lowest address
1166 # upwards, and silently truncated / NUL-padded to length.
1167 #
1168 # @sig: table signature / identifier (4 bytes)
1169 #
1170 # @rev: table revision number (dependent on signature, 1 byte)
1171 #
1172 # @oem_id: OEM identifier (6 bytes)
1173 #
1174 # @oem_table_id: OEM table identifier (8 bytes)
1175 #
1176 # @oem_rev: OEM-supplied revision number (4 bytes)
1177 #
1178 # @asl_compiler_id: identifier of the utility that created the table
1179 #                   (4 bytes)
1180 #
1181 # @asl_compiler_rev: revision number of the utility that created the
1182 #                    table (4 bytes)
1183 #
1184 # @file: colon (:) separated list of pathnames to load and
1185 #        concatenate as table data. The resultant binary blob is expected to
1186 #        have an ACPI table header. At least one file is required. This field
1187 #        excludes @data.
1188 #
1189 # @data: colon (:) separated list of pathnames to load and
1190 #        concatenate as table data. The resultant binary blob must not have an
1191 #        ACPI table header. At least one file is required. This field excludes
1192 #        @file.
1193 #
1194 # Since: 1.5
1195 ##
1196 { 'struct': 'AcpiTableOptions',
1197   'data': {
1198     '*sig':               'str',
1199     '*rev':               'uint8',
1200     '*oem_id':            'str',
1201     '*oem_table_id':      'str',
1202     '*oem_rev':           'uint32',
1203     '*asl_compiler_id':   'str',
1204     '*asl_compiler_rev':  'uint32',
1205     '*file':              'str',
1206     '*data':              'str' }}
1207
1208 ##
1209 # @CommandLineParameterType:
1210 #
1211 # Possible types for an option parameter.
1212 #
1213 # @string: accepts a character string
1214 #
1215 # @boolean: accepts "on" or "off"
1216 #
1217 # @number: accepts a number
1218 #
1219 # @size: accepts a number followed by an optional suffix (K)ilo,
1220 #        (M)ega, (G)iga, (T)era
1221 #
1222 # Since: 1.5
1223 ##
1224 { 'enum': 'CommandLineParameterType',
1225   'data': ['string', 'boolean', 'number', 'size'] }
1226
1227 ##
1228 # @CommandLineParameterInfo:
1229 #
1230 # Details about a single parameter of a command line option.
1231 #
1232 # @name: parameter name
1233 #
1234 # @type: parameter @CommandLineParameterType
1235 #
1236 # @help: human readable text string, not suitable for parsing.
1237 #
1238 # @default: default value string (since 2.1)
1239 #
1240 # Since: 1.5
1241 ##
1242 { 'struct': 'CommandLineParameterInfo',
1243   'data': { 'name': 'str',
1244             'type': 'CommandLineParameterType',
1245             '*help': 'str',
1246             '*default': 'str' } }
1247
1248 ##
1249 # @CommandLineOptionInfo:
1250 #
1251 # Details about a command line option, including its list of parameter details
1252 #
1253 # @option: option name
1254 #
1255 # @parameters: an array of @CommandLineParameterInfo
1256 #
1257 # Since: 1.5
1258 ##
1259 { 'struct': 'CommandLineOptionInfo',
1260   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
1261
1262 ##
1263 # @query-command-line-options:
1264 #
1265 # Query command line option schema.
1266 #
1267 # @option: option name
1268 #
1269 # Returns: list of @CommandLineOptionInfo for all options (or for the given
1270 #          @option).  Returns an error if the given @option doesn't exist.
1271 #
1272 # Since: 1.5
1273 #
1274 # Example:
1275 #
1276 # -> { "execute": "query-command-line-options",
1277 #      "arguments": { "option": "option-rom" } }
1278 # <- { "return": [
1279 #         {
1280 #             "parameters": [
1281 #                 {
1282 #                     "name": "romfile",
1283 #                     "type": "string"
1284 #                 },
1285 #                 {
1286 #                     "name": "bootindex",
1287 #                     "type": "number"
1288 #                 }
1289 #             ],
1290 #             "option": "option-rom"
1291 #         }
1292 #      ]
1293 #    }
1294 #
1295 ##
1296 {'command': 'query-command-line-options',
1297  'data': { '*option': 'str' },
1298  'returns': ['CommandLineOptionInfo'],
1299  'allow-preconfig': true }
1300
1301 ##
1302 # @PCDIMMDeviceInfo:
1303 #
1304 # PCDIMMDevice state information
1305 #
1306 # @id: device's ID
1307 #
1308 # @addr: physical address, where device is mapped
1309 #
1310 # @size: size of memory that the device provides
1311 #
1312 # @slot: slot number at which device is plugged in
1313 #
1314 # @node: NUMA node number where device is plugged in
1315 #
1316 # @memdev: memory backend linked with device
1317 #
1318 # @hotplugged: true if device was hotplugged
1319 #
1320 # @hotpluggable: true if device if could be added/removed while machine is running
1321 #
1322 # Since: 2.1
1323 ##
1324 { 'struct': 'PCDIMMDeviceInfo',
1325   'data': { '*id': 'str',
1326             'addr': 'int',
1327             'size': 'int',
1328             'slot': 'int',
1329             'node': 'int',
1330             'memdev': 'str',
1331             'hotplugged': 'bool',
1332             'hotpluggable': 'bool'
1333           }
1334 }
1335
1336 ##
1337 # @VirtioPMEMDeviceInfo:
1338 #
1339 # VirtioPMEM state information
1340 #
1341 # @id: device's ID
1342 #
1343 # @memaddr: physical address in memory, where device is mapped
1344 #
1345 # @size: size of memory that the device provides
1346 #
1347 # @memdev: memory backend linked with device
1348 #
1349 # Since: 4.1
1350 ##
1351 { 'struct': 'VirtioPMEMDeviceInfo',
1352   'data': { '*id': 'str',
1353             'memaddr': 'size',
1354             'size': 'size',
1355             'memdev': 'str'
1356           }
1357 }
1358
1359 ##
1360 # @MemoryDeviceInfo:
1361 #
1362 # Union containing information about a memory device
1363 #
1364 # nvdimm is included since 2.12. virtio-pmem is included since 4.1.
1365 #
1366 # Since: 2.1
1367 ##
1368 { 'union': 'MemoryDeviceInfo',
1369   'data': { 'dimm': 'PCDIMMDeviceInfo',
1370             'nvdimm': 'PCDIMMDeviceInfo',
1371             'virtio-pmem': 'VirtioPMEMDeviceInfo'
1372           }
1373 }
1374
1375 ##
1376 # @query-memory-devices:
1377 #
1378 # Lists available memory devices and their state
1379 #
1380 # Since: 2.1
1381 #
1382 # Example:
1383 #
1384 # -> { "execute": "query-memory-devices" }
1385 # <- { "return": [ { "data":
1386 #                       { "addr": 5368709120,
1387 #                         "hotpluggable": true,
1388 #                         "hotplugged": true,
1389 #                         "id": "d1",
1390 #                         "memdev": "/objects/memX",
1391 #                         "node": 0,
1392 #                         "size": 1073741824,
1393 #                         "slot": 0},
1394 #                    "type": "dimm"
1395 #                  } ] }
1396 #
1397 ##
1398 { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
1399
1400 ##
1401 # @MEM_UNPLUG_ERROR:
1402 #
1403 # Emitted when memory hot unplug error occurs.
1404 #
1405 # @device: device name
1406 #
1407 # @msg: Informative message
1408 #
1409 # Since: 2.4
1410 #
1411 # Example:
1412 #
1413 # <- { "event": "MEM_UNPLUG_ERROR"
1414 #      "data": { "device": "dimm1",
1415 #                "msg": "acpi: device unplug for unsupported device"
1416 #      },
1417 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
1418 #
1419 ##
1420 { 'event': 'MEM_UNPLUG_ERROR',
1421   'data': { 'device': 'str', 'msg': 'str' } }
1422
1423 ##
1424 # @ACPISlotType:
1425 #
1426 # @DIMM: memory slot
1427 # @CPU: logical CPU slot (since 2.7)
1428 ##
1429 { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
1430
1431 ##
1432 # @ACPIOSTInfo:
1433 #
1434 # OSPM Status Indication for a device
1435 # For description of possible values of @source and @status fields
1436 # see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
1437 #
1438 # @device: device ID associated with slot
1439 #
1440 # @slot: slot ID, unique per slot of a given @slot-type
1441 #
1442 # @slot-type: type of the slot
1443 #
1444 # @source: an integer containing the source event
1445 #
1446 # @status: an integer containing the status code
1447 #
1448 # Since: 2.1
1449 ##
1450 { 'struct': 'ACPIOSTInfo',
1451   'data'  : { '*device': 'str',
1452               'slot': 'str',
1453               'slot-type': 'ACPISlotType',
1454               'source': 'int',
1455               'status': 'int' } }
1456
1457 ##
1458 # @query-acpi-ospm-status:
1459 #
1460 # Return a list of ACPIOSTInfo for devices that support status
1461 # reporting via ACPI _OST method.
1462 #
1463 # Since: 2.1
1464 #
1465 # Example:
1466 #
1467 # -> { "execute": "query-acpi-ospm-status" }
1468 # <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
1469 #                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
1470 #                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
1471 #                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
1472 #    ]}
1473 #
1474 ##
1475 { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
1476
1477 ##
1478 # @ACPI_DEVICE_OST:
1479 #
1480 # Emitted when guest executes ACPI _OST method.
1481 #
1482 # @info: OSPM Status Indication
1483 #
1484 # Since: 2.1
1485 #
1486 # Example:
1487 #
1488 # <- { "event": "ACPI_DEVICE_OST",
1489 #      "data": { "device": "d1", "slot": "0",
1490 #                "slot-type": "DIMM", "source": 1, "status": 0 } }
1491 #
1492 ##
1493 { 'event': 'ACPI_DEVICE_OST',
1494      'data': { 'info': 'ACPIOSTInfo' } }
1495
1496 ##
1497 # @ReplayMode:
1498 #
1499 # Mode of the replay subsystem.
1500 #
1501 # @none: normal execution mode. Replay or record are not enabled.
1502 #
1503 # @record: record mode. All non-deterministic data is written into the
1504 #          replay log.
1505 #
1506 # @play: replay mode. Non-deterministic data required for system execution
1507 #        is read from the log.
1508 #
1509 # Since: 2.5
1510 ##
1511 { 'enum': 'ReplayMode',
1512   'data': [ 'none', 'record', 'play' ] }
1513
1514 ##
1515 # @xen-load-devices-state:
1516 #
1517 # Load the state of all devices from file. The RAM and the block devices
1518 # of the VM are not loaded by this command.
1519 #
1520 # @filename: the file to load the state of the devices from as binary
1521 #            data. See xen-save-devices-state.txt for a description of the binary
1522 #            format.
1523 #
1524 # Since: 2.7
1525 #
1526 # Example:
1527 #
1528 # -> { "execute": "xen-load-devices-state",
1529 #      "arguments": { "filename": "/tmp/resume" } }
1530 # <- { "return": {} }
1531 #
1532 ##
1533 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }
1534
1535 ##
1536 # @GuidInfo:
1537 #
1538 # GUID information.
1539 #
1540 # @guid: the globally unique identifier
1541 #
1542 # Since: 2.9
1543 ##
1544 { 'struct': 'GuidInfo', 'data': {'guid': 'str'} }
1545
1546 ##
1547 # @query-vm-generation-id:
1548 #
1549 # Show Virtual Machine Generation ID
1550 #
1551 # Since: 2.9
1552 ##
1553 { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' }
1554