uninorth: convert to trace-events
[qemu/rayw.git] / qapi-schema.json
blob5c06745c7927f9fecdfcbad04c84336e0d8f357a
1 # -*- Mode: Python -*-
2 ##
3 # = Introduction
5 # This document describes all commands currently supported by QMP.
7 # Most of the time their usage is exactly the same as in the user Monitor, this
8 # means that any other document which also describe commands (the manpage,
9 # QEMU's manual, etc) can and should be consulted.
11 # QMP has two types of commands: regular and query commands. Regular commands
12 # usually change the Virtual Machine's state someway, while query commands just
13 # return information. The sections below are divided accordingly.
15 # It's important to observe that all communication examples are formatted in
16 # a reader-friendly way, so that they're easier to understand. However, in real
17 # protocol usage, they're emitted as a single line.
19 # Also, the following notation is used to denote data flow:
21 # Example:
23 # | -> data issued by the Client
24 # | <- Server data response
26 # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
27 # detailed information on the Server command and response formats.
29 # = Stability Considerations
31 # The current QMP command set (described in this file) may be useful for a
32 # number of use cases, however it's limited and several commands have bad
33 # defined semantics, specially with regard to command completion.
35 # These problems are going to be solved incrementally in the next QEMU releases
36 # and we're going to establish a deprecation policy for badly defined commands.
38 # If you're planning to adopt QMP, please observe the following:
40 #     1. The deprecation policy will take effect and be documented soon, please
41 #        check the documentation of each used command as soon as a new release of
42 #        QEMU is available
44 #     2. DO NOT rely on anything which is not explicit documented
46 #     3. Errors, in special, are not documented. Applications should NOT check
47 #        for specific errors classes or data (it's strongly recommended to only
48 #        check for the "error" key)
52 { 'pragma': { 'doc-required': true } }
54 # Whitelists to permit QAPI rule violations; think twice before you
55 # add to them!
56 { 'pragma': {
57     # Commands allowed to return a non-dictionary:
58     'returns-whitelist': [
59         'human-monitor-command',
60         'qom-get',
61         'query-migrate-cache-size',
62         'query-tpm-models',
63         'query-tpm-types',
64         'ringbuf-read' ],
65     'name-case-whitelist': [
66         'ACPISlotType',         # DIMM, visible through query-acpi-ospm-status
67         'CpuInfoMIPS',          # PC, visible through query-cpu
68         'CpuInfoTricore',       # PC, visible through query-cpu
69         'QapiErrorClass',       # all members, visible through errors
70         'UuidInfo',             # UUID, visible through query-uuid
71         'X86CPURegister32',     # all members, visible indirectly through qom-get
72         'q_obj_CpuInfo-base'    # CPU, visible through query-cpu
73     ] } }
75 # Documentation generated with qapi2texi.py is in source order, with
76 # included sub-schemas inserted at the first include directive
77 # (subsequent include directives have no effect).  To get a sane and
78 # stable order, it's best to include each sub-schema just once, or
79 # include it first in qapi-schema.json.
81 { 'include': 'qapi/common.json' }
82 { 'include': 'qapi/sockets.json' }
83 { 'include': 'qapi/run-state.json' }
84 { 'include': 'qapi/crypto.json' }
85 { 'include': 'qapi/block.json' }
86 { 'include': 'qapi/char.json' }
87 { 'include': 'qapi/net.json' }
88 { 'include': 'qapi/rocker.json' }
89 { 'include': 'qapi/tpm.json' }
90 { 'include': 'qapi/ui.json' }
91 { 'include': 'qapi/migration.json' }
92 { 'include': 'qapi/transaction.json' }
93 { 'include': 'qapi/trace.json' }
94 { 'include': 'qapi/introspect.json' }
97 # = Miscellanea
101 # @qmp_capabilities:
103 # Enable QMP capabilities.
105 # Arguments: None.
107 # Example:
109 # -> { "execute": "qmp_capabilities" }
110 # <- { "return": {} }
112 # Notes: This command is valid exactly when first connecting: it must be
113 # issued before any other command will be accepted, and will fail once the
114 # monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
116 # Since: 0.13
119 { 'command': 'qmp_capabilities' }
122 # @VersionTriple:
124 # A three-part version number.
126 # @major:  The major version number.
128 # @minor:  The minor version number.
130 # @micro:  The micro version number.
132 # Since: 2.4
134 { 'struct': 'VersionTriple',
135   'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
139 # @VersionInfo:
141 # A description of QEMU's version.
143 # @qemu:        The version of QEMU.  By current convention, a micro
144 #               version of 50 signifies a development branch.  A micro version
145 #               greater than or equal to 90 signifies a release candidate for
146 #               the next minor version.  A micro version of less than 50
147 #               signifies a stable release.
149 # @package:     QEMU will always set this field to an empty string.  Downstream
150 #               versions of QEMU should set this to a non-empty string.  The
151 #               exact format depends on the downstream however it highly
152 #               recommended that a unique name is used.
154 # Since: 0.14.0
156 { 'struct': 'VersionInfo',
157   'data': {'qemu': 'VersionTriple', 'package': 'str'} }
160 # @query-version:
162 # Returns the current version of QEMU.
164 # Returns:  A @VersionInfo object describing the current version of QEMU.
166 # Since: 0.14.0
168 # Example:
170 # -> { "execute": "query-version" }
171 # <- {
172 #       "return":{
173 #          "qemu":{
174 #             "major":0,
175 #             "minor":11,
176 #             "micro":5
177 #          },
178 #          "package":""
179 #       }
180 #    }
183 { 'command': 'query-version', 'returns': 'VersionInfo' }
186 # @CommandInfo:
188 # Information about a QMP command
190 # @name: The command name
192 # Since: 0.14.0
194 { 'struct': 'CommandInfo', 'data': {'name': 'str'} }
197 # @query-commands:
199 # Return a list of supported QMP commands by this server
201 # Returns: A list of @CommandInfo for all supported commands
203 # Since: 0.14.0
205 # Example:
207 # -> { "execute": "query-commands" }
208 # <- {
209 #      "return":[
210 #         {
211 #            "name":"query-balloon"
212 #         },
213 #         {
214 #            "name":"system_powerdown"
215 #         }
216 #      ]
217 #    }
219 # Note: This example has been shortened as the real response is too long.
222 { 'command': 'query-commands', 'returns': ['CommandInfo'] }
225 # @LostTickPolicy:
227 # Policy for handling lost ticks in timer devices.
229 # @discard: throw away the missed tick(s) and continue with future injection
230 #           normally.  Guest time may be delayed, unless the OS has explicit
231 #           handling of lost ticks
233 # @delay: continue to deliver ticks at the normal rate.  Guest time will be
234 #         delayed due to the late tick
236 # @merge: merge the missed tick(s) into one tick and inject.  Guest time
237 #         may be delayed, depending on how the OS reacts to the merging
238 #         of ticks
240 # @slew: deliver ticks at a higher rate to catch up with the missed tick. The
241 #        guest time should not be delayed once catchup is complete.
243 # Since: 2.0
245 { 'enum': 'LostTickPolicy',
246   'data': ['discard', 'delay', 'merge', 'slew' ] }
249 # @add_client:
251 # Allow client connections for VNC, Spice and socket based
252 # character devices to be passed in to QEMU via SCM_RIGHTS.
254 # @protocol: protocol name. Valid names are "vnc", "spice" or the
255 #            name of a character device (eg. from -chardev id=XXXX)
257 # @fdname: file descriptor name previously passed via 'getfd' command
259 # @skipauth: whether to skip authentication. Only applies
260 #            to "vnc" and "spice" protocols
262 # @tls: whether to perform TLS. Only applies to the "spice"
263 #       protocol
265 # Returns: nothing on success.
267 # Since: 0.14.0
269 # Example:
271 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
272 #                                              "fdname": "myclient" } }
273 # <- { "return": {} }
276 { 'command': 'add_client',
277   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
278             '*tls': 'bool' } }
281 # @NameInfo:
283 # Guest name information.
285 # @name: The name of the guest
287 # Since: 0.14.0
289 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
292 # @query-name:
294 # Return the name information of a guest.
296 # Returns: @NameInfo of the guest
298 # Since: 0.14.0
300 # Example:
302 # -> { "execute": "query-name" }
303 # <- { "return": { "name": "qemu-name" } }
306 { 'command': 'query-name', 'returns': 'NameInfo' }
309 # @KvmInfo:
311 # Information about support for KVM acceleration
313 # @enabled: true if KVM acceleration is active
315 # @present: true if KVM acceleration is built into this executable
317 # Since: 0.14.0
319 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
322 # @query-kvm:
324 # Returns information about KVM acceleration
326 # Returns: @KvmInfo
328 # Since: 0.14.0
330 # Example:
332 # -> { "execute": "query-kvm" }
333 # <- { "return": { "enabled": true, "present": true } }
336 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
339 # @UuidInfo:
341 # Guest UUID information (Universally Unique Identifier).
343 # @UUID: the UUID of the guest
345 # Since: 0.14.0
347 # Notes: If no UUID was specified for the guest, a null UUID is returned.
349 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
352 # @query-uuid:
354 # Query the guest UUID information.
356 # Returns: The @UuidInfo for the guest
358 # Since: 0.14.0
360 # Example:
362 # -> { "execute": "query-uuid" }
363 # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
366 { 'command': 'query-uuid', 'returns': 'UuidInfo' }
369 # @EventInfo:
371 # Information about a QMP event
373 # @name: The event name
375 # Since: 1.2.0
377 { 'struct': 'EventInfo', 'data': {'name': 'str'} }
380 # @query-events:
382 # Return a list of supported QMP events by this server
384 # Returns: A list of @EventInfo for all supported events
386 # Since: 1.2.0
388 # Example:
390 # -> { "execute": "query-events" }
391 # <- {
392 #      "return": [
393 #          {
394 #             "name":"SHUTDOWN"
395 #          },
396 #          {
397 #             "name":"RESET"
398 #          }
399 #       ]
400 #    }
402 # Note: This example has been shortened as the real response is too long.
405 { 'command': 'query-events', 'returns': ['EventInfo'] }
408 # @CpuInfoArch:
410 # An enumeration of cpu types that enable additional information during
411 # @query-cpus.
413 # Since: 2.6
415 { 'enum': 'CpuInfoArch',
416   'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 'other' ] }
419 # @CpuInfo:
421 # Information about a virtual CPU
423 # @CPU: the index of the virtual CPU
425 # @current: this only exists for backwards compatibility and should be ignored
427 # @halted: true if the virtual CPU is in the halt state.  Halt usually refers
428 #          to a processor specific low power mode.
430 # @qom_path: path to the CPU object in the QOM tree (since 2.4)
432 # @thread_id: ID of the underlying host thread
434 # @props: properties describing to which node/socket/core/thread
435 #         virtual CPU belongs to, provided if supported by board (since 2.10)
437 # @arch: architecture of the cpu, which determines which additional fields
438 #        will be listed (since 2.6)
440 # Since: 0.14.0
442 # Notes: @halted is a transient state that changes frequently.  By the time the
443 #        data is sent to the client, the guest may no longer be halted.
445 { 'union': 'CpuInfo',
446   'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool',
447            'qom_path': 'str', 'thread_id': 'int',
448            '*props': 'CpuInstanceProperties', 'arch': 'CpuInfoArch' },
449   'discriminator': 'arch',
450   'data': { 'x86': 'CpuInfoX86',
451             'sparc': 'CpuInfoSPARC',
452             'ppc': 'CpuInfoPPC',
453             'mips': 'CpuInfoMIPS',
454             'tricore': 'CpuInfoTricore',
455             'other': 'CpuInfoOther' } }
458 # @CpuInfoX86:
460 # Additional information about a virtual i386 or x86_64 CPU
462 # @pc: the 64-bit instruction pointer
464 # Since: 2.6
466 { 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } }
469 # @CpuInfoSPARC:
471 # Additional information about a virtual SPARC CPU
473 # @pc: the PC component of the instruction pointer
475 # @npc: the NPC component of the instruction pointer
477 # Since: 2.6
479 { 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } }
482 # @CpuInfoPPC:
484 # Additional information about a virtual PPC CPU
486 # @nip: the instruction pointer
488 # Since: 2.6
490 { 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } }
493 # @CpuInfoMIPS:
495 # Additional information about a virtual MIPS CPU
497 # @PC: the instruction pointer
499 # Since: 2.6
501 { 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } }
504 # @CpuInfoTricore:
506 # Additional information about a virtual Tricore CPU
508 # @PC: the instruction pointer
510 # Since: 2.6
512 { 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } }
515 # @CpuInfoOther:
517 # No additional information is available about the virtual CPU
519 # Since: 2.6
522 { 'struct': 'CpuInfoOther', 'data': { } }
525 # @query-cpus:
527 # Returns a list of information about each virtual CPU.
529 # Returns: a list of @CpuInfo for each virtual CPU
531 # Since: 0.14.0
533 # Example:
535 # -> { "execute": "query-cpus" }
536 # <- { "return": [
537 #          {
538 #             "CPU":0,
539 #             "current":true,
540 #             "halted":false,
541 #             "qom_path":"/machine/unattached/device[0]",
542 #             "arch":"x86",
543 #             "pc":3227107138,
544 #             "thread_id":3134
545 #          },
546 #          {
547 #             "CPU":1,
548 #             "current":false,
549 #             "halted":true,
550 #             "qom_path":"/machine/unattached/device[2]",
551 #             "arch":"x86",
552 #             "pc":7108165,
553 #             "thread_id":3135
554 #          }
555 #       ]
556 #    }
559 { 'command': 'query-cpus', 'returns': ['CpuInfo'] }
562 # @IOThreadInfo:
564 # Information about an iothread
566 # @id: the identifier of the iothread
568 # @thread-id: ID of the underlying host thread
570 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
571 #               (since 2.9)
573 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
574 #             configured (since 2.9)
576 # @poll-shrink: how many ns will be removed from polling time, 0 means that
577 #               it's not configured (since 2.9)
579 # Since: 2.0
581 { 'struct': 'IOThreadInfo',
582   'data': {'id': 'str',
583            'thread-id': 'int',
584            'poll-max-ns': 'int',
585            'poll-grow': 'int',
586            'poll-shrink': 'int' } }
589 # @query-iothreads:
591 # Returns a list of information about each iothread.
593 # Note: this list excludes the QEMU main loop thread, which is not declared
594 # using the -object iothread command-line option.  It is always the main thread
595 # of the process.
597 # Returns: a list of @IOThreadInfo for each iothread
599 # Since: 2.0
601 # Example:
603 # -> { "execute": "query-iothreads" }
604 # <- { "return": [
605 #          {
606 #             "id":"iothread0",
607 #             "thread-id":3134
608 #          },
609 #          {
610 #             "id":"iothread1",
611 #             "thread-id":3135
612 #          }
613 #       ]
614 #    }
617 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'] }
620 # @BalloonInfo:
622 # Information about the guest balloon device.
624 # @actual: the number of bytes the balloon currently contains
626 # Since: 0.14.0
629 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
632 # @query-balloon:
634 # Return information about the balloon device.
636 # Returns: @BalloonInfo on success
638 #          If the balloon driver is enabled but not functional because the KVM
639 #          kernel module cannot support it, KvmMissingCap
641 #          If no balloon device is present, DeviceNotActive
643 # Since: 0.14.0
645 # Example:
647 # -> { "execute": "query-balloon" }
648 # <- { "return": {
649 #          "actual": 1073741824,
650 #       }
651 #    }
654 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
657 # @BALLOON_CHANGE:
659 # Emitted when the guest changes the actual BALLOON level. This value is
660 # equivalent to the @actual field return by the 'query-balloon' command
662 # @actual: actual level of the guest memory balloon in bytes
664 # Note: this event is rate-limited.
666 # Since: 1.2
668 # Example:
670 # <- { "event": "BALLOON_CHANGE",
671 #      "data": { "actual": 944766976 },
672 #      "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
675 { 'event': 'BALLOON_CHANGE',
676   'data': { 'actual': 'int' } }
679 # @PciMemoryRange:
681 # A PCI device memory region
683 # @base: the starting address (guest physical)
685 # @limit: the ending address (guest physical)
687 # Since: 0.14.0
689 { 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
692 # @PciMemoryRegion:
694 # Information about a PCI device I/O region.
696 # @bar: the index of the Base Address Register for this region
698 # @type: 'io' if the region is a PIO region
699 #        'memory' if the region is a MMIO region
701 # @size: memory size
703 # @prefetch: if @type is 'memory', true if the memory is prefetchable
705 # @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
707 # Since: 0.14.0
709 { 'struct': 'PciMemoryRegion',
710   'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
711            '*prefetch': 'bool', '*mem_type_64': 'bool' } }
714 # @PciBusInfo:
716 # Information about a bus of a PCI Bridge device
718 # @number: primary bus interface number.  This should be the number of the
719 #          bus the device resides on.
721 # @secondary: secondary bus interface number.  This is the number of the
722 #             main bus for the bridge
724 # @subordinate: This is the highest number bus that resides below the
725 #               bridge.
727 # @io_range: The PIO range for all devices on this bridge
729 # @memory_range: The MMIO range for all devices on this bridge
731 # @prefetchable_range: The range of prefetchable MMIO for all devices on
732 #                      this bridge
734 # Since: 2.4
736 { 'struct': 'PciBusInfo',
737   'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
738            'io_range': 'PciMemoryRange',
739            'memory_range': 'PciMemoryRange',
740            'prefetchable_range': 'PciMemoryRange' } }
743 # @PciBridgeInfo:
745 # Information about a PCI Bridge device
747 # @bus: information about the bus the device resides on
749 # @devices: a list of @PciDeviceInfo for each device on this bridge
751 # Since: 0.14.0
753 { 'struct': 'PciBridgeInfo',
754   'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }
757 # @PciDeviceClass:
759 # Information about the Class of a PCI device
761 # @desc: a string description of the device's class
763 # @class: the class code of the device
765 # Since: 2.4
767 { 'struct': 'PciDeviceClass',
768   'data': {'*desc': 'str', 'class': 'int'} }
771 # @PciDeviceId:
773 # Information about the Id of a PCI device
775 # @device: the PCI device id
777 # @vendor: the PCI vendor id
779 # Since: 2.4
781 { 'struct': 'PciDeviceId',
782   'data': {'device': 'int', 'vendor': 'int'} }
785 # @PciDeviceInfo:
787 # Information about a PCI device
789 # @bus: the bus number of the device
791 # @slot: the slot the device is located in
793 # @function: the function of the slot used by the device
795 # @class_info: the class of the device
797 # @id: the PCI device id
799 # @irq: if an IRQ is assigned to the device, the IRQ number
801 # @qdev_id: the device name of the PCI device
803 # @pci_bridge: if the device is a PCI bridge, the bridge information
805 # @regions: a list of the PCI I/O regions associated with the device
807 # Notes: the contents of @class_info.desc are not stable and should only be
808 #        treated as informational.
810 # Since: 0.14.0
812 { 'struct': 'PciDeviceInfo',
813   'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
814            'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
815            '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo',
816            'regions': ['PciMemoryRegion']} }
819 # @PciInfo:
821 # Information about a PCI bus
823 # @bus: the bus index
825 # @devices: a list of devices on this bus
827 # Since: 0.14.0
829 { 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
832 # @query-pci:
834 # Return information about the PCI bus topology of the guest.
836 # Returns: a list of @PciInfo for each PCI bus. Each bus is
837 # represented by a json-object, which has a key with a json-array of
838 # all PCI devices attached to it. Each device is represented by a
839 # json-object.
841 # Since: 0.14.0
843 # Example:
845 # -> { "execute": "query-pci" }
846 # <- { "return": [
847 #          {
848 #             "bus": 0,
849 #             "devices": [
850 #                {
851 #                   "bus": 0,
852 #                   "qdev_id": "",
853 #                   "slot": 0,
854 #                   "class_info": {
855 #                      "class": 1536,
856 #                      "desc": "Host bridge"
857 #                   },
858 #                   "id": {
859 #                      "device": 32902,
860 #                      "vendor": 4663
861 #                   },
862 #                   "function": 0,
863 #                   "regions": [
864 #                   ]
865 #                },
866 #                {
867 #                   "bus": 0,
868 #                   "qdev_id": "",
869 #                   "slot": 1,
870 #                   "class_info": {
871 #                      "class": 1537,
872 #                      "desc": "ISA bridge"
873 #                   },
874 #                   "id": {
875 #                      "device": 32902,
876 #                      "vendor": 28672
877 #                   },
878 #                   "function": 0,
879 #                   "regions": [
880 #                   ]
881 #                },
882 #                {
883 #                   "bus": 0,
884 #                   "qdev_id": "",
885 #                   "slot": 1,
886 #                   "class_info": {
887 #                      "class": 257,
888 #                      "desc": "IDE controller"
889 #                   },
890 #                   "id": {
891 #                      "device": 32902,
892 #                      "vendor": 28688
893 #                   },
894 #                   "function": 1,
895 #                   "regions": [
896 #                      {
897 #                         "bar": 4,
898 #                         "size": 16,
899 #                         "address": 49152,
900 #                         "type": "io"
901 #                      }
902 #                   ]
903 #                },
904 #                {
905 #                   "bus": 0,
906 #                   "qdev_id": "",
907 #                   "slot": 2,
908 #                   "class_info": {
909 #                      "class": 768,
910 #                      "desc": "VGA controller"
911 #                   },
912 #                   "id": {
913 #                      "device": 4115,
914 #                      "vendor": 184
915 #                   },
916 #                   "function": 0,
917 #                   "regions": [
918 #                      {
919 #                         "prefetch": true,
920 #                         "mem_type_64": false,
921 #                         "bar": 0,
922 #                         "size": 33554432,
923 #                         "address": 4026531840,
924 #                         "type": "memory"
925 #                      },
926 #                      {
927 #                         "prefetch": false,
928 #                         "mem_type_64": false,
929 #                         "bar": 1,
930 #                         "size": 4096,
931 #                         "address": 4060086272,
932 #                         "type": "memory"
933 #                      },
934 #                      {
935 #                         "prefetch": false,
936 #                         "mem_type_64": false,
937 #                         "bar": 6,
938 #                         "size": 65536,
939 #                         "address": -1,
940 #                         "type": "memory"
941 #                      }
942 #                   ]
943 #                },
944 #                {
945 #                   "bus": 0,
946 #                   "qdev_id": "",
947 #                   "irq": 11,
948 #                   "slot": 4,
949 #                   "class_info": {
950 #                      "class": 1280,
951 #                      "desc": "RAM controller"
952 #                   },
953 #                   "id": {
954 #                      "device": 6900,
955 #                      "vendor": 4098
956 #                   },
957 #                   "function": 0,
958 #                   "regions": [
959 #                      {
960 #                         "bar": 0,
961 #                         "size": 32,
962 #                         "address": 49280,
963 #                         "type": "io"
964 #                      }
965 #                   ]
966 #                }
967 #             ]
968 #          }
969 #       ]
970 #    }
972 # Note: This example has been shortened as the real response is too long.
975 { 'command': 'query-pci', 'returns': ['PciInfo'] }
978 # @quit:
980 # This command will cause the QEMU process to exit gracefully.  While every
981 # attempt is made to send the QMP response before terminating, this is not
982 # guaranteed.  When using this interface, a premature EOF would not be
983 # unexpected.
985 # Since: 0.14.0
987 # Example:
989 # -> { "execute": "quit" }
990 # <- { "return": {} }
992 { 'command': 'quit' }
995 # @stop:
997 # Stop all guest VCPU execution.
999 # Since:  0.14.0
1001 # Notes:  This function will succeed even if the guest is already in the stopped
1002 #         state.  In "inmigrate" state, it will ensure that the guest
1003 #         remains paused once migration finishes, as if the -S option was
1004 #         passed on the command line.
1006 # Example:
1008 # -> { "execute": "stop" }
1009 # <- { "return": {} }
1012 { 'command': 'stop' }
1015 # @system_reset:
1017 # Performs a hard reset of a guest.
1019 # Since: 0.14.0
1021 # Example:
1023 # -> { "execute": "system_reset" }
1024 # <- { "return": {} }
1027 { 'command': 'system_reset' }
1030 # @system_powerdown:
1032 # Requests that a guest perform a powerdown operation.
1034 # Since: 0.14.0
1036 # Notes: A guest may or may not respond to this command.  This command
1037 #        returning does not indicate that a guest has accepted the request or
1038 #        that it has shut down.  Many guests will respond to this command by
1039 #        prompting the user in some way.
1040 # Example:
1042 # -> { "execute": "system_powerdown" }
1043 # <- { "return": {} }
1046 { 'command': 'system_powerdown' }
1049 # @cpu-add:
1051 # Adds CPU with specified ID
1053 # @id: ID of CPU to be created, valid values [0..max_cpus)
1055 # Returns: Nothing on success
1057 # Since: 1.5
1059 # Example:
1061 # -> { "execute": "cpu-add", "arguments": { "id": 2 } }
1062 # <- { "return": {} }
1065 { 'command': 'cpu-add', 'data': {'id': 'int'} }
1068 # @memsave:
1070 # Save a portion of guest memory to a file.
1072 # @val: the virtual address of the guest to start from
1074 # @size: the size of memory region to save
1076 # @filename: the file to save the memory to as binary data
1078 # @cpu-index: the index of the virtual CPU to use for translating the
1079 #                       virtual address (defaults to CPU 0)
1081 # Returns: Nothing on success
1083 # Since: 0.14.0
1085 # Notes: Errors were not reliably returned until 1.1
1087 # Example:
1089 # -> { "execute": "memsave",
1090 #      "arguments": { "val": 10,
1091 #                     "size": 100,
1092 #                     "filename": "/tmp/virtual-mem-dump" } }
1093 # <- { "return": {} }
1096 { 'command': 'memsave',
1097   'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
1100 # @pmemsave:
1102 # Save a portion of guest physical memory to a file.
1104 # @val: the physical address of the guest to start from
1106 # @size: the size of memory region to save
1108 # @filename: the file to save the memory to as binary data
1110 # Returns: Nothing on success
1112 # Since: 0.14.0
1114 # Notes: Errors were not reliably returned until 1.1
1116 # Example:
1118 # -> { "execute": "pmemsave",
1119 #      "arguments": { "val": 10,
1120 #                     "size": 100,
1121 #                     "filename": "/tmp/physical-mem-dump" } }
1122 # <- { "return": {} }
1125 { 'command': 'pmemsave',
1126   'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
1129 # @cont:
1131 # Resume guest VCPU execution.
1133 # Since:  0.14.0
1135 # Returns:  If successful, nothing
1137 # Notes:  This command will succeed if the guest is currently running.  It
1138 #         will also succeed if the guest is in the "inmigrate" state; in
1139 #         this case, the effect of the command is to make sure the guest
1140 #         starts once migration finishes, removing the effect of the -S
1141 #         command line option if it was passed.
1143 # Example:
1145 # -> { "execute": "cont" }
1146 # <- { "return": {} }
1149 { 'command': 'cont' }
1152 # @system_wakeup:
1154 # Wakeup guest from suspend.  Does nothing in case the guest isn't suspended.
1156 # Since:  1.1
1158 # Returns:  nothing.
1160 # Example:
1162 # -> { "execute": "system_wakeup" }
1163 # <- { "return": {} }
1166 { 'command': 'system_wakeup' }
1169 # @inject-nmi:
1171 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
1172 # The command fails when the guest doesn't support injecting.
1174 # Returns:  If successful, nothing
1176 # Since:  0.14.0
1178 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
1180 # Example:
1182 # -> { "execute": "inject-nmi" }
1183 # <- { "return": {} }
1186 { 'command': 'inject-nmi' }
1189 # @balloon:
1191 # Request the balloon driver to change its balloon size.
1193 # @value: the target size of the balloon in bytes
1195 # Returns: Nothing on success
1196 #          If the balloon driver is enabled but not functional because the KVM
1197 #            kernel module cannot support it, KvmMissingCap
1198 #          If no balloon device is present, DeviceNotActive
1200 # Notes: This command just issues a request to the guest.  When it returns,
1201 #        the balloon size may not have changed.  A guest can change the balloon
1202 #        size independent of this command.
1204 # Since: 0.14.0
1206 # Example:
1208 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1209 # <- { "return": {} }
1212 { 'command': 'balloon', 'data': {'value': 'int'} }
1215 # @human-monitor-command:
1217 # Execute a command on the human monitor and return the output.
1219 # @command-line: the command to execute in the human monitor
1221 # @cpu-index: The CPU to use for commands that require an implicit CPU
1223 # Returns: the output of the command as a string
1225 # Since: 0.14.0
1227 # Notes: This command only exists as a stop-gap.  Its use is highly
1228 #        discouraged.  The semantics of this command are not
1229 #        guaranteed: this means that command names, arguments and
1230 #        responses can change or be removed at ANY time.  Applications
1231 #        that rely on long term stability guarantees should NOT
1232 #        use this command.
1234 #        Known limitations:
1236 #        * This command is stateless, this means that commands that depend
1237 #          on state information (such as getfd) might not work
1239 #        * Commands that prompt the user for data don't currently work
1241 # Example:
1243 # -> { "execute": "human-monitor-command",
1244 #      "arguments": { "command-line": "info kvm" } }
1245 # <- { "return": "kvm support: enabled\r\n" }
1248 { 'command': 'human-monitor-command',
1249   'data': {'command-line': 'str', '*cpu-index': 'int'},
1250   'returns': 'str' }
1253 # @ObjectPropertyInfo:
1255 # @name: the name of the property
1257 # @type: the type of the property.  This will typically come in one of four
1258 #        forms:
1260 #        1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
1261 #           These types are mapped to the appropriate JSON type.
1263 #        2) A child type in the form 'child<subtype>' where subtype is a qdev
1264 #           device type name.  Child properties create the composition tree.
1266 #        3) A link type in the form 'link<subtype>' where subtype is a qdev
1267 #           device type name.  Link properties form the device model graph.
1269 # Since: 1.2
1271 { 'struct': 'ObjectPropertyInfo',
1272   'data': { 'name': 'str', 'type': 'str' } }
1275 # @qom-list:
1277 # This command will list any properties of a object given a path in the object
1278 # model.
1280 # @path: the path within the object model.  See @qom-get for a description of
1281 #        this parameter.
1283 # Returns: a list of @ObjectPropertyInfo that describe the properties of the
1284 #          object.
1286 # Since: 1.2
1288 { 'command': 'qom-list',
1289   'data': { 'path': 'str' },
1290   'returns': [ 'ObjectPropertyInfo' ] }
1293 # @qom-get:
1295 # This command will get a property from a object model path and return the
1296 # value.
1298 # @path: The path within the object model.  There are two forms of supported
1299 #        paths--absolute and partial paths.
1301 #        Absolute paths are derived from the root object and can follow child<>
1302 #        or link<> properties.  Since they can follow link<> properties, they
1303 #        can be arbitrarily long.  Absolute paths look like absolute filenames
1304 #        and are prefixed  with a leading slash.
1306 #        Partial paths look like relative filenames.  They do not begin
1307 #        with a prefix.  The matching rules for partial paths are subtle but
1308 #        designed to make specifying objects easy.  At each level of the
1309 #        composition tree, the partial path is matched as an absolute path.
1310 #        The first match is not returned.  At least two matches are searched
1311 #        for.  A successful result is only returned if only one match is
1312 #        found.  If more than one match is found, a flag is return to
1313 #        indicate that the match was ambiguous.
1315 # @property: The property name to read
1317 # Returns: The property value.  The type depends on the property
1318 #          type. child<> and link<> properties are returned as #str
1319 #          pathnames.  All integer property types (u8, u16, etc) are
1320 #          returned as #int.
1322 # Since: 1.2
1324 { 'command': 'qom-get',
1325   'data': { 'path': 'str', 'property': 'str' },
1326   'returns': 'any' }
1329 # @qom-set:
1331 # This command will set a property from a object model path.
1333 # @path: see @qom-get for a description of this parameter
1335 # @property: the property name to set
1337 # @value: a value who's type is appropriate for the property type.  See @qom-get
1338 #         for a description of type mapping.
1340 # Since: 1.2
1342 { 'command': 'qom-set',
1343   'data': { 'path': 'str', 'property': 'str', 'value': 'any' } }
1346 # @change:
1348 # This command is multiple commands multiplexed together.
1350 # @device: This is normally the name of a block device but it may also be 'vnc'.
1351 #          when it's 'vnc', then sub command depends on @target
1353 # @target: If @device is a block device, then this is the new filename.
1354 #          If @device is 'vnc', then if the value 'password' selects the vnc
1355 #          change password command.   Otherwise, this specifies a new server URI
1356 #          address to listen to for VNC connections.
1358 # @arg:    If @device is a block device, then this is an optional format to open
1359 #          the device with.
1360 #          If @device is 'vnc' and @target is 'password', this is the new VNC
1361 #          password to set.  See change-vnc-password for additional notes.
1363 # Returns: Nothing on success.
1364 #          If @device is not a valid block device, DeviceNotFound
1366 # Notes:  This interface is deprecated, and it is strongly recommended that you
1367 #         avoid using it.  For changing block devices, use
1368 #         blockdev-change-medium; for changing VNC parameters, use
1369 #         change-vnc-password.
1371 # Since: 0.14.0
1373 # Example:
1375 # 1. Change a removable medium
1377 # -> { "execute": "change",
1378 #      "arguments": { "device": "ide1-cd0",
1379 #                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
1380 # <- { "return": {} }
1382 # 2. Change VNC password
1384 # -> { "execute": "change",
1385 #      "arguments": { "device": "vnc", "target": "password",
1386 #                     "arg": "foobar1" } }
1387 # <- { "return": {} }
1390 { 'command': 'change',
1391   'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
1394 # @ObjectTypeInfo:
1396 # This structure describes a search result from @qom-list-types
1398 # @name: the type name found in the search
1400 # @abstract: the type is abstract and can't be directly instantiated.
1401 #            Omitted if false. (since 2.10)
1403 # @parent: Name of parent type, if any (since 2.10)
1405 # Since: 1.1
1407 { 'struct': 'ObjectTypeInfo',
1408   'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } }
1411 # @qom-list-types:
1413 # This command will return a list of types given search parameters
1415 # @implements: if specified, only return types that implement this type name
1417 # @abstract: if true, include abstract types in the results
1419 # Returns: a list of @ObjectTypeInfo or an empty list if no results are found
1421 # Since: 1.1
1423 { 'command': 'qom-list-types',
1424   'data': { '*implements': 'str', '*abstract': 'bool' },
1425   'returns': [ 'ObjectTypeInfo' ] }
1428 # @DevicePropertyInfo:
1430 # Information about device properties.
1432 # @name: the name of the property
1433 # @type: the typename of the property
1434 # @description: if specified, the description of the property.
1435 #               (since 2.2)
1437 # Since: 1.2
1439 { 'struct': 'DevicePropertyInfo',
1440   'data': { 'name': 'str', 'type': 'str', '*description': 'str' } }
1443 # @device-list-properties:
1445 # List properties associated with a device.
1447 # @typename: the type name of a device
1449 # Returns: a list of DevicePropertyInfo describing a devices properties
1451 # Since: 1.2
1453 { 'command': 'device-list-properties',
1454   'data': { 'typename': 'str'},
1455   'returns': [ 'DevicePropertyInfo' ] }
1458 # @xen-set-global-dirty-log:
1460 # Enable or disable the global dirty log mode.
1462 # @enable: true to enable, false to disable.
1464 # Returns: nothing
1466 # Since: 1.3
1468 # Example:
1470 # -> { "execute": "xen-set-global-dirty-log",
1471 #      "arguments": { "enable": true } }
1472 # <- { "return": {} }
1475 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
1478 # @device_add:
1480 # @driver: the name of the new device's driver
1482 # @bus: the device's parent bus (device tree path)
1484 # @id: the device's ID, must be unique
1486 # Additional arguments depend on the type.
1488 # Add a device.
1490 # Notes:
1491 # 1. For detailed information about this command, please refer to the
1492 #    'docs/qdev-device-use.txt' file.
1494 # 2. It's possible to list device properties by running QEMU with the
1495 #    "-device DEVICE,help" command-line argument, where DEVICE is the
1496 #    device's name
1498 # Example:
1500 # -> { "execute": "device_add",
1501 #      "arguments": { "driver": "e1000", "id": "net1",
1502 #                     "bus": "pci.0",
1503 #                     "mac": "52:54:00:12:34:56" } }
1504 # <- { "return": {} }
1506 # TODO: This command effectively bypasses QAPI completely due to its
1507 # "additional arguments" business.  It shouldn't have been added to
1508 # the schema in this form.  It should be qapified properly, or
1509 # replaced by a properly qapified command.
1511 # Since: 0.13
1513 { 'command': 'device_add',
1514   'data': {'driver': 'str', '*bus': 'str', '*id': 'str'},
1515   'gen': false } # so we can get the additional arguments
1518 # @device_del:
1520 # Remove a device from a guest
1522 # @id: the device's ID or QOM path
1524 # Returns: Nothing on success
1525 #          If @id is not a valid device, DeviceNotFound
1527 # Notes: When this command completes, the device may not be removed from the
1528 #        guest.  Hot removal is an operation that requires guest cooperation.
1529 #        This command merely requests that the guest begin the hot removal
1530 #        process.  Completion of the device removal process is signaled with a
1531 #        DEVICE_DELETED event. Guest reset will automatically complete removal
1532 #        for all devices.
1534 # Since: 0.14.0
1536 # Example:
1538 # -> { "execute": "device_del",
1539 #      "arguments": { "id": "net1" } }
1540 # <- { "return": {} }
1542 # -> { "execute": "device_del",
1543 #      "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
1544 # <- { "return": {} }
1547 { 'command': 'device_del', 'data': {'id': 'str'} }
1550 # @DEVICE_DELETED:
1552 # Emitted whenever the device removal completion is acknowledged by the guest.
1553 # At this point, it's safe to reuse the specified device ID. Device removal can
1554 # be initiated by the guest or by HMP/QMP commands.
1556 # @device: device name
1558 # @path: device path
1560 # Since: 1.5
1562 # Example:
1564 # <- { "event": "DEVICE_DELETED",
1565 #      "data": { "device": "virtio-net-pci-0",
1566 #                "path": "/machine/peripheral/virtio-net-pci-0" },
1567 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
1570 { 'event': 'DEVICE_DELETED',
1571   'data': { '*device': 'str', 'path': 'str' } }
1574 # @DumpGuestMemoryFormat:
1576 # An enumeration of guest-memory-dump's format.
1578 # @elf: elf format
1580 # @kdump-zlib: kdump-compressed format with zlib-compressed
1582 # @kdump-lzo: kdump-compressed format with lzo-compressed
1584 # @kdump-snappy: kdump-compressed format with snappy-compressed
1586 # Since: 2.0
1588 { 'enum': 'DumpGuestMemoryFormat',
1589   'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy' ] }
1592 # @dump-guest-memory:
1594 # Dump guest's memory to vmcore. It is a synchronous operation that can take
1595 # very long depending on the amount of guest memory.
1597 # @paging: if true, do paging to get guest's memory mapping. This allows
1598 #          using gdb to process the core file.
1600 #          IMPORTANT: this option can make QEMU allocate several gigabytes
1601 #                     of RAM. This can happen for a large guest, or a
1602 #                     malicious guest pretending to be large.
1604 #          Also, paging=true has the following limitations:
1606 #             1. The guest may be in a catastrophic state or can have corrupted
1607 #                memory, which cannot be trusted
1608 #             2. The guest can be in real-mode even if paging is enabled. For
1609 #                example, the guest uses ACPI to sleep, and ACPI sleep state
1610 #                goes in real-mode
1611 #             3. Currently only supported on i386 and x86_64.
1613 # @protocol: the filename or file descriptor of the vmcore. The supported
1614 #            protocols are:
1616 #            1. file: the protocol starts with "file:", and the following
1617 #               string is the file's path.
1618 #            2. fd: the protocol starts with "fd:", and the following string
1619 #               is the fd's name.
1621 # @detach: if true, QMP will return immediately rather than
1622 #          waiting for the dump to finish. The user can track progress
1623 #          using "query-dump". (since 2.6).
1625 # @begin: if specified, the starting physical address.
1627 # @length: if specified, the memory size, in bytes. If you don't
1628 #          want to dump all guest's memory, please specify the start @begin
1629 #          and @length
1631 # @format: if specified, the format of guest memory dump. But non-elf
1632 #          format is conflict with paging and filter, ie. @paging, @begin and
1633 #          @length is not allowed to be specified with non-elf @format at the
1634 #          same time (since 2.0)
1636 # Note: All boolean arguments default to false
1638 # Returns: nothing on success
1640 # Since: 1.2
1642 # Example:
1644 # -> { "execute": "dump-guest-memory",
1645 #      "arguments": { "protocol": "fd:dump" } }
1646 # <- { "return": {} }
1649 { 'command': 'dump-guest-memory',
1650   'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
1651             '*begin': 'int', '*length': 'int',
1652             '*format': 'DumpGuestMemoryFormat'} }
1655 # @DumpStatus:
1657 # Describe the status of a long-running background guest memory dump.
1659 # @none: no dump-guest-memory has started yet.
1661 # @active: there is one dump running in background.
1663 # @completed: the last dump has finished successfully.
1665 # @failed: the last dump has failed.
1667 # Since: 2.6
1669 { 'enum': 'DumpStatus',
1670   'data': [ 'none', 'active', 'completed', 'failed' ] }
1673 # @DumpQueryResult:
1675 # The result format for 'query-dump'.
1677 # @status: enum of @DumpStatus, which shows current dump status
1679 # @completed: bytes written in latest dump (uncompressed)
1681 # @total: total bytes to be written in latest dump (uncompressed)
1683 # Since: 2.6
1685 { 'struct': 'DumpQueryResult',
1686   'data': { 'status': 'DumpStatus',
1687             'completed': 'int',
1688             'total': 'int' } }
1691 # @query-dump:
1693 # Query latest dump status.
1695 # Returns: A @DumpStatus object showing the dump status.
1697 # Since: 2.6
1699 # Example:
1701 # -> { "execute": "query-dump" }
1702 # <- { "return": { "status": "active", "completed": 1024000,
1703 #                  "total": 2048000 } }
1706 { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
1709 # @DUMP_COMPLETED:
1711 # Emitted when background dump has completed
1713 # @result: DumpQueryResult type described in qapi-schema.json.
1715 # @error: human-readable error string that provides
1716 #         hint on why dump failed. Only presents on failure. The
1717 #         user should not try to interpret the error string.
1719 # Since: 2.6
1721 # Example:
1723 # { "event": "DUMP_COMPLETED",
1724 #   "data": {"result": {"total": 1090650112, "status": "completed",
1725 #                       "completed": 1090650112} } }
1728 { 'event': 'DUMP_COMPLETED' ,
1729   'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
1732 # @DumpGuestMemoryCapability:
1734 # A list of the available formats for dump-guest-memory
1736 # Since: 2.0
1738 { 'struct': 'DumpGuestMemoryCapability',
1739   'data': {
1740       'formats': ['DumpGuestMemoryFormat'] } }
1743 # @query-dump-guest-memory-capability:
1745 # Returns the available formats for dump-guest-memory
1747 # Returns:  A @DumpGuestMemoryCapability object listing available formats for
1748 #           dump-guest-memory
1750 # Since: 2.0
1752 # Example:
1754 # -> { "execute": "query-dump-guest-memory-capability" }
1755 # <- { "return": { "formats":
1756 #                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
1759 { 'command': 'query-dump-guest-memory-capability',
1760   'returns': 'DumpGuestMemoryCapability' }
1763 # @dump-skeys:
1765 # Dump guest's storage keys
1767 # @filename: the path to the file to dump to
1769 # This command is only supported on s390 architecture.
1771 # Since: 2.5
1773 # Example:
1775 # -> { "execute": "dump-skeys",
1776 #      "arguments": { "filename": "/tmp/skeys" } }
1777 # <- { "return": {} }
1780 { 'command': 'dump-skeys',
1781   'data': { 'filename': 'str' } }
1784 # @object-add:
1786 # Create a QOM object.
1788 # @qom-type: the class name for the object to be created
1790 # @id: the name of the new object
1792 # @props: a dictionary of properties to be passed to the backend
1794 # Returns: Nothing on success
1795 #          Error if @qom-type is not a valid class name
1797 # Since: 2.0
1799 # Example:
1801 # -> { "execute": "object-add",
1802 #      "arguments": { "qom-type": "rng-random", "id": "rng1",
1803 #                     "props": { "filename": "/dev/hwrng" } } }
1804 # <- { "return": {} }
1807 { 'command': 'object-add',
1808   'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'} }
1811 # @object-del:
1813 # Remove a QOM object.
1815 # @id: the name of the QOM object to remove
1817 # Returns: Nothing on success
1818 #          Error if @id is not a valid id for a QOM object
1820 # Since: 2.0
1822 # Example:
1824 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
1825 # <- { "return": {} }
1828 { 'command': 'object-del', 'data': {'id': 'str'} }
1831 # @getfd:
1833 # Receive a file descriptor via SCM rights and assign it a name
1835 # @fdname: file descriptor name
1837 # Returns: Nothing on success
1839 # Since: 0.14.0
1841 # Notes: If @fdname already exists, the file descriptor assigned to
1842 #        it will be closed and replaced by the received file
1843 #        descriptor.
1845 #        The 'closefd' command can be used to explicitly close the
1846 #        file descriptor when it is no longer needed.
1848 # Example:
1850 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1851 # <- { "return": {} }
1854 { 'command': 'getfd', 'data': {'fdname': 'str'} }
1857 # @closefd:
1859 # Close a file descriptor previously passed via SCM rights
1861 # @fdname: file descriptor name
1863 # Returns: Nothing on success
1865 # Since: 0.14.0
1867 # Example:
1869 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1870 # <- { "return": {} }
1873 { 'command': 'closefd', 'data': {'fdname': 'str'} }
1876 # @MachineInfo:
1878 # Information describing a machine.
1880 # @name: the name of the machine
1882 # @alias: an alias for the machine name
1884 # @is-default: whether the machine is default
1886 # @cpu-max: maximum number of CPUs supported by the machine type
1887 #           (since 1.5.0)
1889 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
1891 # Since: 1.2.0
1893 { 'struct': 'MachineInfo',
1894   'data': { 'name': 'str', '*alias': 'str',
1895             '*is-default': 'bool', 'cpu-max': 'int',
1896             'hotpluggable-cpus': 'bool'} }
1899 # @query-machines:
1901 # Return a list of supported machines
1903 # Returns: a list of MachineInfo
1905 # Since: 1.2.0
1907 { 'command': 'query-machines', 'returns': ['MachineInfo'] }
1910 # @CpuDefinitionInfo:
1912 # Virtual CPU definition.
1914 # @name: the name of the CPU definition
1916 # @migration-safe: whether a CPU definition can be safely used for
1917 #                  migration in combination with a QEMU compatibility machine
1918 #                  when migrating between different QMU versions and between
1919 #                  hosts with different sets of (hardware or software)
1920 #                  capabilities. If not provided, information is not available
1921 #                  and callers should not assume the CPU definition to be
1922 #                  migration-safe. (since 2.8)
1924 # @static: whether a CPU definition is static and will not change depending on
1925 #          QEMU version, machine type, machine options and accelerator options.
1926 #          A static model is always migration-safe. (since 2.8)
1928 # @unavailable-features: List of properties that prevent
1929 #                        the CPU model from running in the current
1930 #                        host. (since 2.8)
1931 # @typename: Type name that can be used as argument to @device-list-properties,
1932 #            to introspect properties configurable using -cpu or -global.
1933 #            (since 2.9)
1935 # @unavailable-features is a list of QOM property names that
1936 # represent CPU model attributes that prevent the CPU from running.
1937 # If the QOM property is read-only, that means there's no known
1938 # way to make the CPU model run in the current host. Implementations
1939 # that choose not to provide specific information return the
1940 # property name "type".
1941 # If the property is read-write, it means that it MAY be possible
1942 # to run the CPU model in the current host if that property is
1943 # changed. Management software can use it as hints to suggest or
1944 # choose an alternative for the user, or just to generate meaningful
1945 # error messages explaining why the CPU model can't be used.
1946 # If @unavailable-features is an empty list, the CPU model is
1947 # runnable using the current host and machine-type.
1948 # If @unavailable-features is not present, runnability
1949 # information for the CPU is not available.
1951 # Since: 1.2.0
1953 { 'struct': 'CpuDefinitionInfo',
1954   'data': { 'name': 'str', '*migration-safe': 'bool', 'static': 'bool',
1955             '*unavailable-features': [ 'str' ], 'typename': 'str' } }
1958 # @MemoryInfo:
1960 # Actual memory information in bytes.
1962 # @base-memory: size of "base" memory specified with command line
1963 #               option -m.
1965 # @plugged-memory: size of memory that can be hot-unplugged. This field
1966 #                  is omitted if target doesn't support memory hotplug
1967 #                  (i.e. CONFIG_MEM_HOTPLUG not defined on build time).
1969 # Since: 2.11.0
1971 { 'struct': 'MemoryInfo',
1972   'data'  : { 'base-memory': 'size', '*plugged-memory': 'size' } }
1975 # @query-memory-size-summary:
1977 # Return the amount of initially allocated and present hotpluggable (if
1978 # enabled) memory in bytes.
1980 # Example:
1982 # -> { "execute": "query-memory-size-summary" }
1983 # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
1985 # Since: 2.11.0
1987 { 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
1990 # @query-cpu-definitions:
1992 # Return a list of supported virtual CPU definitions
1994 # Returns: a list of CpuDefInfo
1996 # Since: 1.2.0
1998 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }
2001 # @CpuModelInfo:
2003 # Virtual CPU model.
2005 # A CPU model consists of the name of a CPU definition, to which
2006 # delta changes are applied (e.g. features added/removed). Most magic values
2007 # that an architecture might require should be hidden behind the name.
2008 # However, if required, architectures can expose relevant properties.
2010 # @name: the name of the CPU definition the model is based on
2011 # @props: a dictionary of QOM properties to be applied
2013 # Since: 2.8.0
2015 { 'struct': 'CpuModelInfo',
2016   'data': { 'name': 'str',
2017             '*props': 'any' } }
2020 # @CpuModelExpansionType:
2022 # An enumeration of CPU model expansion types.
2024 # @static: Expand to a static CPU model, a combination of a static base
2025 #          model name and property delta changes. As the static base model will
2026 #          never change, the expanded CPU model will be the same, independant of
2027 #          independent of QEMU version, machine type, machine options, and
2028 #          accelerator options. Therefore, the resulting model can be used by
2029 #          tooling without having to specify a compatibility machine - e.g. when
2030 #          displaying the "host" model. static CPU models are migration-safe.
2032 # @full: Expand all properties. The produced model is not guaranteed to be
2033 #        migration-safe, but allows tooling to get an insight and work with
2034 #        model details.
2036 # Note: When a non-migration-safe CPU model is expanded in static mode, some
2037 # features enabled by the CPU model may be omitted, because they can't be
2038 # implemented by a static CPU model definition (e.g. cache info passthrough and
2039 # PMU passthrough in x86). If you need an accurate representation of the
2040 # features enabled by a non-migration-safe CPU model, use @full. If you need a
2041 # static representation that will keep ABI compatibility even when changing QEMU
2042 # version or machine-type, use @static (but keep in mind that some features may
2043 # be omitted).
2045 # Since: 2.8.0
2047 { 'enum': 'CpuModelExpansionType',
2048   'data': [ 'static', 'full' ] }
2052 # @CpuModelExpansionInfo:
2054 # The result of a cpu model expansion.
2056 # @model: the expanded CpuModelInfo.
2058 # Since: 2.8.0
2060 { 'struct': 'CpuModelExpansionInfo',
2061   'data': { 'model': 'CpuModelInfo' } }
2065 # @query-cpu-model-expansion:
2067 # Expands a given CPU model (or a combination of CPU model + additional options)
2068 # to different granularities, allowing tooling to get an understanding what a
2069 # specific CPU model looks like in QEMU under a certain configuration.
2071 # This interface can be used to query the "host" CPU model.
2073 # The data returned by this command may be affected by:
2075 # * QEMU version: CPU models may look different depending on the QEMU version.
2076 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
2077 # * machine-type: CPU model  may look different depending on the machine-type.
2078 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
2079 # * machine options (including accelerator): in some architectures, CPU models
2080 #   may look different depending on machine and accelerator options. (Except for
2081 #   CPU models reported as "static" in query-cpu-definitions.)
2082 # * "-cpu" arguments and global properties: arguments to the -cpu option and
2083 #   global properties may affect expansion of CPU models. Using
2084 #   query-cpu-model-expansion while using these is not advised.
2086 # Some architectures may not support all expansion types. s390x supports
2087 # "full" and "static".
2089 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
2090 #          not supported, if the model cannot be expanded, if the model contains
2091 #          an unknown CPU definition name, unknown properties or properties
2092 #          with a wrong type. Also returns an error if an expansion type is
2093 #          not supported.
2095 # Since: 2.8.0
2097 { 'command': 'query-cpu-model-expansion',
2098   'data': { 'type': 'CpuModelExpansionType',
2099             'model': 'CpuModelInfo' },
2100   'returns': 'CpuModelExpansionInfo' }
2103 # @CpuModelCompareResult:
2105 # An enumeration of CPU model comparation results. The result is usually
2106 # calculated using e.g. CPU features or CPU generations.
2108 # @incompatible: If model A is incompatible to model B, model A is not
2109 #                guaranteed to run where model B runs and the other way around.
2111 # @identical: If model A is identical to model B, model A is guaranteed to run
2112 #             where model B runs and the other way around.
2114 # @superset: If model A is a superset of model B, model B is guaranteed to run
2115 #            where model A runs. There are no guarantees about the other way.
2117 # @subset: If model A is a subset of model B, model A is guaranteed to run
2118 #          where model B runs. There are no guarantees about the other way.
2120 # Since: 2.8.0
2122 { 'enum': 'CpuModelCompareResult',
2123   'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
2126 # @CpuModelCompareInfo:
2128 # The result of a CPU model comparison.
2130 # @result: The result of the compare operation.
2131 # @responsible-properties: List of properties that led to the comparison result
2132 #                          not being identical.
2134 # @responsible-properties is a list of QOM property names that led to
2135 # both CPUs not being detected as identical. For identical models, this
2136 # list is empty.
2137 # If a QOM property is read-only, that means there's no known way to make the
2138 # CPU models identical. If the special property name "type" is included, the
2139 # models are by definition not identical and cannot be made identical.
2141 # Since: 2.8.0
2143 { 'struct': 'CpuModelCompareInfo',
2144   'data': {'result': 'CpuModelCompareResult',
2145            'responsible-properties': ['str']
2146           }
2150 # @query-cpu-model-comparison:
2152 # Compares two CPU models, returning how they compare in a specific
2153 # configuration. The results indicates how both models compare regarding
2154 # runnability. This result can be used by tooling to make decisions if a
2155 # certain CPU model will run in a certain configuration or if a compatible
2156 # CPU model has to be created by baselining.
2158 # Usually, a CPU model is compared against the maximum possible CPU model
2159 # of a certain configuration (e.g. the "host" model for KVM). If that CPU
2160 # model is identical or a subset, it will run in that configuration.
2162 # The result returned by this command may be affected by:
2164 # * QEMU version: CPU models may look different depending on the QEMU version.
2165 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
2166 # * machine-type: CPU model may look different depending on the machine-type.
2167 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
2168 # * machine options (including accelerator): in some architectures, CPU models
2169 #   may look different depending on machine and accelerator options. (Except for
2170 #   CPU models reported as "static" in query-cpu-definitions.)
2171 # * "-cpu" arguments and global properties: arguments to the -cpu option and
2172 #   global properties may affect expansion of CPU models. Using
2173 #   query-cpu-model-expansion while using these is not advised.
2175 # Some architectures may not support comparing CPU models. s390x supports
2176 # comparing CPU models.
2178 # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
2179 #          not supported, if a model cannot be used, if a model contains
2180 #          an unknown cpu definition name, unknown properties or properties
2181 #          with wrong types.
2183 # Since: 2.8.0
2185 { 'command': 'query-cpu-model-comparison',
2186   'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
2187   'returns': 'CpuModelCompareInfo' }
2190 # @CpuModelBaselineInfo:
2192 # The result of a CPU model baseline.
2194 # @model: the baselined CpuModelInfo.
2196 # Since: 2.8.0
2198 { 'struct': 'CpuModelBaselineInfo',
2199   'data': { 'model': 'CpuModelInfo' } }
2202 # @query-cpu-model-baseline:
2204 # Baseline two CPU models, creating a compatible third model. The created
2205 # model will always be a static, migration-safe CPU model (see "static"
2206 # CPU model expansion for details).
2208 # This interface can be used by tooling to create a compatible CPU model out
2209 # two CPU models. The created CPU model will be identical to or a subset of
2210 # both CPU models when comparing them. Therefore, the created CPU model is
2211 # guaranteed to run where the given CPU models run.
2213 # The result returned by this command may be affected by:
2215 # * QEMU version: CPU models may look different depending on the QEMU version.
2216 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
2217 # * machine-type: CPU model may look different depending on the machine-type.
2218 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
2219 # * machine options (including accelerator): in some architectures, CPU models
2220 #   may look different depending on machine and accelerator options. (Except for
2221 #   CPU models reported as "static" in query-cpu-definitions.)
2222 # * "-cpu" arguments and global properties: arguments to the -cpu option and
2223 #   global properties may affect expansion of CPU models. Using
2224 #   query-cpu-model-expansion while using these is not advised.
2226 # Some architectures may not support baselining CPU models. s390x supports
2227 # baselining CPU models.
2229 # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
2230 #          not supported, if a model cannot be used, if a model contains
2231 #          an unknown cpu definition name, unknown properties or properties
2232 #          with wrong types.
2234 # Since: 2.8.0
2236 { 'command': 'query-cpu-model-baseline',
2237   'data': { 'modela': 'CpuModelInfo',
2238             'modelb': 'CpuModelInfo' },
2239   'returns': 'CpuModelBaselineInfo' }
2242 # @AddfdInfo:
2244 # Information about a file descriptor that was added to an fd set.
2246 # @fdset-id: The ID of the fd set that @fd was added to.
2248 # @fd: The file descriptor that was received via SCM rights and
2249 #      added to the fd set.
2251 # Since: 1.2.0
2253 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
2256 # @add-fd:
2258 # Add a file descriptor, that was passed via SCM rights, to an fd set.
2260 # @fdset-id: The ID of the fd set to add the file descriptor to.
2262 # @opaque: A free-form string that can be used to describe the fd.
2264 # Returns: @AddfdInfo on success
2266 #          If file descriptor was not received, FdNotSupplied
2268 #          If @fdset-id is a negative value, InvalidParameterValue
2270 # Notes: The list of fd sets is shared by all monitor connections.
2272 #        If @fdset-id is not specified, a new fd set will be created.
2274 # Since: 1.2.0
2276 # Example:
2278 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
2279 # <- { "return": { "fdset-id": 1, "fd": 3 } }
2282 { 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'},
2283   'returns': 'AddfdInfo' }
2286 # @remove-fd:
2288 # Remove a file descriptor from an fd set.
2290 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
2292 # @fd: The file descriptor that is to be removed.
2294 # Returns: Nothing on success
2295 #          If @fdset-id or @fd is not found, FdNotFound
2297 # Since: 1.2.0
2299 # Notes: The list of fd sets is shared by all monitor connections.
2301 #        If @fd is not specified, all file descriptors in @fdset-id
2302 #        will be removed.
2304 # Example:
2306 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
2307 # <- { "return": {} }
2310 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
2313 # @FdsetFdInfo:
2315 # Information about a file descriptor that belongs to an fd set.
2317 # @fd: The file descriptor value.
2319 # @opaque: A free-form string that can be used to describe the fd.
2321 # Since: 1.2.0
2323 { 'struct': 'FdsetFdInfo',
2324   'data': {'fd': 'int', '*opaque': 'str'} }
2327 # @FdsetInfo:
2329 # Information about an fd set.
2331 # @fdset-id: The ID of the fd set.
2333 # @fds: A list of file descriptors that belong to this fd set.
2335 # Since: 1.2.0
2337 { 'struct': 'FdsetInfo',
2338   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
2341 # @query-fdsets:
2343 # Return information describing all fd sets.
2345 # Returns: A list of @FdsetInfo
2347 # Since: 1.2.0
2349 # Note: The list of fd sets is shared by all monitor connections.
2351 # Example:
2353 # -> { "execute": "query-fdsets" }
2354 # <- { "return": [
2355 #        {
2356 #          "fds": [
2357 #            {
2358 #              "fd": 30,
2359 #              "opaque": "rdonly:/path/to/file"
2360 #            },
2361 #            {
2362 #              "fd": 24,
2363 #              "opaque": "rdwr:/path/to/file"
2364 #            }
2365 #          ],
2366 #          "fdset-id": 1
2367 #        },
2368 #        {
2369 #          "fds": [
2370 #            {
2371 #              "fd": 28
2372 #            },
2373 #            {
2374 #              "fd": 29
2375 #            }
2376 #          ],
2377 #          "fdset-id": 0
2378 #        }
2379 #      ]
2380 #    }
2383 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
2386 # @TargetInfo:
2388 # Information describing the QEMU target.
2390 # @arch: the target architecture (eg "x86_64", "i386", etc)
2392 # Since: 1.2.0
2394 { 'struct': 'TargetInfo',
2395   'data': { 'arch': 'str' } }
2398 # @query-target:
2400 # Return information about the target for this QEMU
2402 # Returns: TargetInfo
2404 # Since: 1.2.0
2406 { 'command': 'query-target', 'returns': 'TargetInfo' }
2409 # @AcpiTableOptions:
2411 # Specify an ACPI table on the command line to load.
2413 # At most one of @file and @data can be specified. The list of files specified
2414 # by any one of them is loaded and concatenated in order. If both are omitted,
2415 # @data is implied.
2417 # Other fields / optargs can be used to override fields of the generic ACPI
2418 # table header; refer to the ACPI specification 5.0, section 5.2.6 System
2419 # Description Table Header. If a header field is not overridden, then the
2420 # corresponding value from the concatenated blob is used (in case of @file), or
2421 # it is filled in with a hard-coded value (in case of @data).
2423 # String fields are copied into the matching ACPI member from lowest address
2424 # upwards, and silently truncated / NUL-padded to length.
2426 # @sig: table signature / identifier (4 bytes)
2428 # @rev: table revision number (dependent on signature, 1 byte)
2430 # @oem_id: OEM identifier (6 bytes)
2432 # @oem_table_id: OEM table identifier (8 bytes)
2434 # @oem_rev: OEM-supplied revision number (4 bytes)
2436 # @asl_compiler_id: identifier of the utility that created the table
2437 #                   (4 bytes)
2439 # @asl_compiler_rev: revision number of the utility that created the
2440 #                    table (4 bytes)
2442 # @file: colon (:) separated list of pathnames to load and
2443 #        concatenate as table data. The resultant binary blob is expected to
2444 #        have an ACPI table header. At least one file is required. This field
2445 #        excludes @data.
2447 # @data: colon (:) separated list of pathnames to load and
2448 #        concatenate as table data. The resultant binary blob must not have an
2449 #        ACPI table header. At least one file is required. This field excludes
2450 #        @file.
2452 # Since: 1.5
2454 { 'struct': 'AcpiTableOptions',
2455   'data': {
2456     '*sig':               'str',
2457     '*rev':               'uint8',
2458     '*oem_id':            'str',
2459     '*oem_table_id':      'str',
2460     '*oem_rev':           'uint32',
2461     '*asl_compiler_id':   'str',
2462     '*asl_compiler_rev':  'uint32',
2463     '*file':              'str',
2464     '*data':              'str' }}
2467 # @CommandLineParameterType:
2469 # Possible types for an option parameter.
2471 # @string: accepts a character string
2473 # @boolean: accepts "on" or "off"
2475 # @number: accepts a number
2477 # @size: accepts a number followed by an optional suffix (K)ilo,
2478 #        (M)ega, (G)iga, (T)era
2480 # Since: 1.5
2482 { 'enum': 'CommandLineParameterType',
2483   'data': ['string', 'boolean', 'number', 'size'] }
2486 # @CommandLineParameterInfo:
2488 # Details about a single parameter of a command line option.
2490 # @name: parameter name
2492 # @type: parameter @CommandLineParameterType
2494 # @help: human readable text string, not suitable for parsing.
2496 # @default: default value string (since 2.1)
2498 # Since: 1.5
2500 { 'struct': 'CommandLineParameterInfo',
2501   'data': { 'name': 'str',
2502             'type': 'CommandLineParameterType',
2503             '*help': 'str',
2504             '*default': 'str' } }
2507 # @CommandLineOptionInfo:
2509 # Details about a command line option, including its list of parameter details
2511 # @option: option name
2513 # @parameters: an array of @CommandLineParameterInfo
2515 # Since: 1.5
2517 { 'struct': 'CommandLineOptionInfo',
2518   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
2521 # @query-command-line-options:
2523 # Query command line option schema.
2525 # @option: option name
2527 # Returns: list of @CommandLineOptionInfo for all options (or for the given
2528 #          @option).  Returns an error if the given @option doesn't exist.
2530 # Since: 1.5
2532 # Example:
2534 # -> { "execute": "query-command-line-options",
2535 #      "arguments": { "option": "option-rom" } }
2536 # <- { "return": [
2537 #         {
2538 #             "parameters": [
2539 #                 {
2540 #                     "name": "romfile",
2541 #                     "type": "string"
2542 #                 },
2543 #                 {
2544 #                     "name": "bootindex",
2545 #                     "type": "number"
2546 #                 }
2547 #             ],
2548 #             "option": "option-rom"
2549 #         }
2550 #      ]
2551 #    }
2554 {'command': 'query-command-line-options', 'data': { '*option': 'str' },
2555  'returns': ['CommandLineOptionInfo'] }
2558 # @X86CPURegister32:
2560 # A X86 32-bit register
2562 # Since: 1.5
2564 { 'enum': 'X86CPURegister32',
2565   'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
2568 # @X86CPUFeatureWordInfo:
2570 # Information about a X86 CPU feature word
2572 # @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
2574 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
2575 #                   feature word
2577 # @cpuid-register: Output register containing the feature bits
2579 # @features: value of output register, containing the feature bits
2581 # Since: 1.5
2583 { 'struct': 'X86CPUFeatureWordInfo',
2584   'data': { 'cpuid-input-eax': 'int',
2585             '*cpuid-input-ecx': 'int',
2586             'cpuid-register': 'X86CPURegister32',
2587             'features': 'int' } }
2590 # @DummyForceArrays:
2592 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
2594 # Since: 2.5
2596 { 'struct': 'DummyForceArrays',
2597   'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
2601 # @NumaOptionsType:
2603 # @node: NUMA nodes configuration
2605 # @dist: NUMA distance configuration (since 2.10)
2607 # @cpu: property based CPU(s) to node mapping (Since: 2.10)
2609 # Since: 2.1
2611 { 'enum': 'NumaOptionsType',
2612   'data': [ 'node', 'dist', 'cpu' ] }
2615 # @NumaOptions:
2617 # A discriminated record of NUMA options. (for OptsVisitor)
2619 # Since: 2.1
2621 { 'union': 'NumaOptions',
2622   'base': { 'type': 'NumaOptionsType' },
2623   'discriminator': 'type',
2624   'data': {
2625     'node': 'NumaNodeOptions',
2626     'dist': 'NumaDistOptions',
2627     'cpu': 'NumaCpuOptions' }}
2630 # @NumaNodeOptions:
2632 # Create a guest NUMA node. (for OptsVisitor)
2634 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
2636 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin
2637 #         if omitted)
2639 # @mem: memory size of this node; mutually exclusive with @memdev.
2640 #       Equally divide total memory among nodes if both @mem and @memdev are
2641 #       omitted.
2643 # @memdev: memory backend object.  If specified for one node,
2644 #          it must be specified for all nodes.
2646 # Since: 2.1
2648 { 'struct': 'NumaNodeOptions',
2649   'data': {
2650    '*nodeid': 'uint16',
2651    '*cpus':   ['uint16'],
2652    '*mem':    'size',
2653    '*memdev': 'str' }}
2656 # @NumaDistOptions:
2658 # Set the distance between 2 NUMA nodes.
2660 # @src: source NUMA node.
2662 # @dst: destination NUMA node.
2664 # @val: NUMA distance from source node to destination node.
2665 #       When a node is unreachable from another node, set the distance
2666 #       between them to 255.
2668 # Since: 2.10
2670 { 'struct': 'NumaDistOptions',
2671   'data': {
2672    'src': 'uint16',
2673    'dst': 'uint16',
2674    'val': 'uint8' }}
2677 # @NumaCpuOptions:
2679 # Option "-numa cpu" overrides default cpu to node mapping.
2680 # It accepts the same set of cpu properties as returned by
2681 # query-hotpluggable-cpus[].props, where node-id could be used to
2682 # override default node mapping.
2684 # Since: 2.10
2686 { 'struct': 'NumaCpuOptions',
2687    'base': 'CpuInstanceProperties',
2688    'data' : {} }
2691 # @HostMemPolicy:
2693 # Host memory policy types
2695 # @default: restore default policy, remove any nondefault policy
2697 # @preferred: set the preferred host nodes for allocation
2699 # @bind: a strict policy that restricts memory allocation to the
2700 #        host nodes specified
2702 # @interleave: memory allocations are interleaved across the set
2703 #              of host nodes specified
2705 # Since: 2.1
2707 { 'enum': 'HostMemPolicy',
2708   'data': [ 'default', 'preferred', 'bind', 'interleave' ] }
2711 # @Memdev:
2713 # Information about memory backend
2715 # @id: backend's ID if backend has 'id' property (since 2.9)
2717 # @size: memory backend size
2719 # @merge: enables or disables memory merge support
2721 # @dump: includes memory backend's memory in a core dump or not
2723 # @prealloc: enables or disables memory preallocation
2725 # @host-nodes: host nodes for its memory policy
2727 # @policy: memory policy of memory backend
2729 # Since: 2.1
2731 { 'struct': 'Memdev',
2732   'data': {
2733     '*id':        'str',
2734     'size':       'size',
2735     'merge':      'bool',
2736     'dump':       'bool',
2737     'prealloc':   'bool',
2738     'host-nodes': ['uint16'],
2739     'policy':     'HostMemPolicy' }}
2742 # @query-memdev:
2744 # Returns information for all memory backends.
2746 # Returns: a list of @Memdev.
2748 # Since: 2.1
2750 # Example:
2752 # -> { "execute": "query-memdev" }
2753 # <- { "return": [
2754 #        {
2755 #          "id": "mem1",
2756 #          "size": 536870912,
2757 #          "merge": false,
2758 #          "dump": true,
2759 #          "prealloc": false,
2760 #          "host-nodes": [0, 1],
2761 #          "policy": "bind"
2762 #        },
2763 #        {
2764 #          "size": 536870912,
2765 #          "merge": false,
2766 #          "dump": true,
2767 #          "prealloc": true,
2768 #          "host-nodes": [2, 3],
2769 #          "policy": "preferred"
2770 #        }
2771 #      ]
2772 #    }
2775 { 'command': 'query-memdev', 'returns': ['Memdev'] }
2778 # @PCDIMMDeviceInfo:
2780 # PCDIMMDevice state information
2782 # @id: device's ID
2784 # @addr: physical address, where device is mapped
2786 # @size: size of memory that the device provides
2788 # @slot: slot number at which device is plugged in
2790 # @node: NUMA node number where device is plugged in
2792 # @memdev: memory backend linked with device
2794 # @hotplugged: true if device was hotplugged
2796 # @hotpluggable: true if device if could be added/removed while machine is running
2798 # Since: 2.1
2800 { 'struct': 'PCDIMMDeviceInfo',
2801   'data': { '*id': 'str',
2802             'addr': 'int',
2803             'size': 'int',
2804             'slot': 'int',
2805             'node': 'int',
2806             'memdev': 'str',
2807             'hotplugged': 'bool',
2808             'hotpluggable': 'bool'
2809           }
2813 # @MemoryDeviceInfo:
2815 # Union containing information about a memory device
2817 # Since: 2.1
2819 { 'union': 'MemoryDeviceInfo', 'data': {'dimm': 'PCDIMMDeviceInfo'} }
2822 # @query-memory-devices:
2824 # Lists available memory devices and their state
2826 # Since: 2.1
2828 # Example:
2830 # -> { "execute": "query-memory-devices" }
2831 # <- { "return": [ { "data":
2832 #                       { "addr": 5368709120,
2833 #                         "hotpluggable": true,
2834 #                         "hotplugged": true,
2835 #                         "id": "d1",
2836 #                         "memdev": "/objects/memX",
2837 #                         "node": 0,
2838 #                         "size": 1073741824,
2839 #                         "slot": 0},
2840 #                    "type": "dimm"
2841 #                  } ] }
2844 { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
2847 # @MEM_UNPLUG_ERROR:
2849 # Emitted when memory hot unplug error occurs.
2851 # @device: device name
2853 # @msg: Informative message
2855 # Since: 2.4
2857 # Example:
2859 # <- { "event": "MEM_UNPLUG_ERROR"
2860 #      "data": { "device": "dimm1",
2861 #                "msg": "acpi: device unplug for unsupported device"
2862 #      },
2863 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
2866 { 'event': 'MEM_UNPLUG_ERROR',
2867   'data': { 'device': 'str', 'msg': 'str' } }
2870 # @ACPISlotType:
2872 # @DIMM: memory slot
2873 # @CPU: logical CPU slot (since 2.7)
2875 { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
2878 # @ACPIOSTInfo:
2880 # OSPM Status Indication for a device
2881 # For description of possible values of @source and @status fields
2882 # see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
2884 # @device: device ID associated with slot
2886 # @slot: slot ID, unique per slot of a given @slot-type
2888 # @slot-type: type of the slot
2890 # @source: an integer containing the source event
2892 # @status: an integer containing the status code
2894 # Since: 2.1
2896 { 'struct': 'ACPIOSTInfo',
2897   'data'  : { '*device': 'str',
2898               'slot': 'str',
2899               'slot-type': 'ACPISlotType',
2900               'source': 'int',
2901               'status': 'int' } }
2904 # @query-acpi-ospm-status:
2906 # Return a list of ACPIOSTInfo for devices that support status
2907 # reporting via ACPI _OST method.
2909 # Since: 2.1
2911 # Example:
2913 # -> { "execute": "query-acpi-ospm-status" }
2914 # <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
2915 #                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
2916 #                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
2917 #                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
2918 #    ]}
2921 { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
2924 # @ACPI_DEVICE_OST:
2926 # Emitted when guest executes ACPI _OST method.
2928 # @info: ACPIOSTInfo type as described in qapi-schema.json
2930 # Since: 2.1
2932 # Example:
2934 # <- { "event": "ACPI_DEVICE_OST",
2935 #      "data": { "device": "d1", "slot": "0",
2936 #                "slot-type": "DIMM", "source": 1, "status": 0 } }
2939 { 'event': 'ACPI_DEVICE_OST',
2940      'data': { 'info': 'ACPIOSTInfo' } }
2943 # @rtc-reset-reinjection:
2945 # This command will reset the RTC interrupt reinjection backlog.
2946 # Can be used if another mechanism to synchronize guest time
2947 # is in effect, for example QEMU guest agent's guest-set-time
2948 # command.
2950 # Since: 2.1
2952 # Example:
2954 # -> { "execute": "rtc-reset-reinjection" }
2955 # <- { "return": {} }
2958 { 'command': 'rtc-reset-reinjection' }
2961 # @RTC_CHANGE:
2963 # Emitted when the guest changes the RTC time.
2965 # @offset: offset between base RTC clock (as specified by -rtc base), and
2966 #          new RTC clock value
2968 # Note: This event is rate-limited.
2970 # Since: 0.13.0
2972 # Example:
2974 # <-   { "event": "RTC_CHANGE",
2975 #        "data": { "offset": 78 },
2976 #        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
2979 { 'event': 'RTC_CHANGE',
2980   'data': { 'offset': 'int' } }
2983 # @ReplayMode:
2985 # Mode of the replay subsystem.
2987 # @none: normal execution mode. Replay or record are not enabled.
2989 # @record: record mode. All non-deterministic data is written into the
2990 #          replay log.
2992 # @play: replay mode. Non-deterministic data required for system execution
2993 #        is read from the log.
2995 # Since: 2.5
2997 { 'enum': 'ReplayMode',
2998   'data': [ 'none', 'record', 'play' ] }
3001 # @xen-load-devices-state:
3003 # Load the state of all devices from file. The RAM and the block devices
3004 # of the VM are not loaded by this command.
3006 # @filename: the file to load the state of the devices from as binary
3007 # data. See xen-save-devices-state.txt for a description of the binary
3008 # format.
3010 # Since: 2.7
3012 # Example:
3014 # -> { "execute": "xen-load-devices-state",
3015 #      "arguments": { "filename": "/tmp/resume" } }
3016 # <- { "return": {} }
3019 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }
3022 # @GICCapability:
3024 # The struct describes capability for a specific GIC (Generic
3025 # Interrupt Controller) version. These bits are not only decided by
3026 # QEMU/KVM software version, but also decided by the hardware that
3027 # the program is running upon.
3029 # @version:  version of GIC to be described. Currently, only 2 and 3
3030 #            are supported.
3032 # @emulated: whether current QEMU/hardware supports emulated GIC
3033 #            device in user space.
3035 # @kernel:   whether current QEMU/hardware supports hardware
3036 #            accelerated GIC device in kernel.
3038 # Since: 2.6
3040 { 'struct': 'GICCapability',
3041   'data': { 'version': 'int',
3042             'emulated': 'bool',
3043             'kernel': 'bool' } }
3046 # @query-gic-capabilities:
3048 # This command is ARM-only. It will return a list of GICCapability
3049 # objects that describe its capability bits.
3051 # Returns: a list of GICCapability objects.
3053 # Since: 2.6
3055 # Example:
3057 # -> { "execute": "query-gic-capabilities" }
3058 # <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
3059 #                 { "version": 3, "emulated": false, "kernel": true } ] }
3062 { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] }
3065 # @CpuInstanceProperties:
3067 # List of properties to be used for hotplugging a CPU instance,
3068 # it should be passed by management with device_add command when
3069 # a CPU is being hotplugged.
3071 # @node-id: NUMA node ID the CPU belongs to
3072 # @socket-id: socket number within node/board the CPU belongs to
3073 # @core-id: core number within socket the CPU belongs to
3074 # @thread-id: thread number within core the CPU belongs to
3076 # Note: currently there are 4 properties that could be present
3077 # but management should be prepared to pass through other
3078 # properties with device_add command to allow for future
3079 # interface extension. This also requires the filed names to be kept in
3080 # sync with the properties passed to -device/device_add.
3082 # Since: 2.7
3084 { 'struct': 'CpuInstanceProperties',
3085   'data': { '*node-id': 'int',
3086             '*socket-id': 'int',
3087             '*core-id': 'int',
3088             '*thread-id': 'int'
3089   }
3093 # @HotpluggableCPU:
3095 # @type: CPU object type for usage with device_add command
3096 # @props: list of properties to be used for hotplugging CPU
3097 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
3098 # @qom-path: link to existing CPU object if CPU is present or
3099 #            omitted if CPU is not present.
3101 # Since: 2.7
3103 { 'struct': 'HotpluggableCPU',
3104   'data': { 'type': 'str',
3105             'vcpus-count': 'int',
3106             'props': 'CpuInstanceProperties',
3107             '*qom-path': 'str'
3108           }
3112 # @query-hotpluggable-cpus:
3114 # Returns: a list of HotpluggableCPU objects.
3116 # Since: 2.7
3118 # Example:
3120 # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
3122 # -> { "execute": "query-hotpluggable-cpus" }
3123 # <- {"return": [
3124 #      { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
3125 #        "vcpus-count": 1 },
3126 #      { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
3127 #        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
3128 #    ]}'
3130 # For pc machine type started with -smp 1,maxcpus=2:
3132 # -> { "execute": "query-hotpluggable-cpus" }
3133 # <- {"return": [
3134 #      {
3135 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3136 #         "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
3137 #      },
3138 #      {
3139 #         "qom-path": "/machine/unattached/device[0]",
3140 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3141 #         "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
3142 #      }
3143 #    ]}
3145 # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
3146 # (Since: 2.11):
3148 # -> { "execute": "query-hotpluggable-cpus" }
3149 # <- {"return": [
3150 #      {
3151 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
3152 #         "props": { "core-id": 1 }
3153 #      },
3154 #      {
3155 #         "qom-path": "/machine/unattached/device[0]",
3156 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
3157 #         "props": { "core-id": 0 }
3158 #      }
3159 #    ]}
3162 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'] }
3165 # @GuidInfo:
3167 # GUID information.
3169 # @guid: the globally unique identifier
3171 # Since: 2.9
3173 { 'struct': 'GuidInfo', 'data': {'guid': 'str'} }
3176 # @query-vm-generation-id:
3178 # Show Virtual Machine Generation ID
3180 # Since: 2.9
3182 { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' }
3185 # @watchdog-set-action:
3187 # Set watchdog action
3189 # Since: 2.11
3191 { 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }