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