8 { 'include': 'common.json' }
13 # Enable QMP capabilities.
17 # @enable: An optional list of QMPCapability values to enable. The
18 # client must not enable any capability that is not
19 # mentioned in the QMP greeting message. If the field is not
20 # provided, it means no QMP capabilities will be enabled.
25 # -> { "execute": "qmp_capabilities",
26 # "arguments": { "enable": [ "oob" ] } }
29 # Notes: This command is valid exactly when first connecting: it must be
30 # issued before any other command will be accepted, and will fail once the
31 # monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
33 # The QMP client needs to explicitly enable QMP capabilities, otherwise
34 # all the QMP capabilities will be turned off by default.
39 { 'command': 'qmp_capabilities',
40 'data': { '*enable': [ 'QMPCapability' ] },
41 'allow-preconfig': true }
46 # Enumeration of capabilities to be advertised during initial client
47 # connection, used for agreeing on particular QMP extension behaviors.
49 # @oob: QMP ability to support out-of-band requests.
50 # (Please refer to qmp-spec.txt for more information on OOB)
55 { 'enum': 'QMPCapability',
61 # A three-part version number.
63 # @major: The major version number.
65 # @minor: The minor version number.
67 # @micro: The micro version number.
71 { 'struct': 'VersionTriple',
72 'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
78 # A description of QEMU's version.
80 # @qemu: The version of QEMU. By current convention, a micro
81 # version of 50 signifies a development branch. A micro version
82 # greater than or equal to 90 signifies a release candidate for
83 # the next minor version. A micro version of less than 50
84 # signifies a stable release.
86 # @package: QEMU will always set this field to an empty string. Downstream
87 # versions of QEMU should set this to a non-empty string. The
88 # exact format depends on the downstream however it highly
89 # recommended that a unique name is used.
93 { 'struct': 'VersionInfo',
94 'data': {'qemu': 'VersionTriple', 'package': 'str'} }
99 # Returns the current version of QEMU.
101 # Returns: A @VersionInfo object describing the current version of QEMU.
107 # -> { "execute": "query-version" }
120 { 'command': 'query-version', 'returns': 'VersionInfo',
121 'allow-preconfig': true }
126 # Information about a QMP command
128 # @name: The command name
132 { 'struct': 'CommandInfo', 'data': {'name': 'str'} }
137 # Return a list of supported QMP commands by this server
139 # Returns: A list of @CommandInfo for all supported commands
145 # -> { "execute": "query-commands" }
149 # "name":"query-balloon"
152 # "name":"system_powerdown"
157 # Note: This example has been shortened as the real response is too long.
160 { 'command': 'query-commands', 'returns': ['CommandInfo'],
161 'allow-preconfig': true }
166 # Policy for handling lost ticks in timer devices.
168 # @discard: throw away the missed tick(s) and continue with future injection
169 # normally. Guest time may be delayed, unless the OS has explicit
170 # handling of lost ticks
172 # @delay: continue to deliver ticks at the normal rate. Guest time will be
173 # delayed due to the late tick
175 # @merge: merge the missed tick(s) into one tick and inject. Guest time
176 # may be delayed, depending on how the OS reacts to the merging
179 # @slew: deliver ticks at a higher rate to catch up with the missed tick. The
180 # guest time should not be delayed once catchup is complete.
184 { 'enum': 'LostTickPolicy',
185 'data': ['discard', 'delay', 'merge', 'slew' ] }
190 # Allow client connections for VNC, Spice and socket based
191 # character devices to be passed in to QEMU via SCM_RIGHTS.
193 # @protocol: protocol name. Valid names are "vnc", "spice" or the
194 # name of a character device (eg. from -chardev id=XXXX)
196 # @fdname: file descriptor name previously passed via 'getfd' command
198 # @skipauth: whether to skip authentication. Only applies
199 # to "vnc" and "spice" protocols
201 # @tls: whether to perform TLS. Only applies to the "spice"
204 # Returns: nothing on success.
210 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
211 # "fdname": "myclient" } }
212 # <- { "return": {} }
215 { 'command': 'add_client',
216 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
222 # Guest name information.
224 # @name: The name of the guest
228 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
233 # Return the name information of a guest.
235 # Returns: @NameInfo of the guest
241 # -> { "execute": "query-name" }
242 # <- { "return": { "name": "qemu-name" } }
245 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
250 # Information about support for KVM acceleration
252 # @enabled: true if KVM acceleration is active
254 # @present: true if KVM acceleration is built into this executable
258 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
263 # Returns information about KVM acceleration
271 # -> { "execute": "query-kvm" }
272 # <- { "return": { "enabled": true, "present": true } }
275 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
280 # Guest UUID information (Universally Unique Identifier).
282 # @UUID: the UUID of the guest
286 # Notes: If no UUID was specified for the guest, a null UUID is returned.
288 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
293 # Query the guest UUID information.
295 # Returns: The @UuidInfo for the guest
301 # -> { "execute": "query-uuid" }
302 # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
305 { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
310 # Information about a QMP event
312 # @name: The event name
316 { 'struct': 'EventInfo', 'data': {'name': 'str'} }
321 # Return a list of supported QMP events by this server
323 # Returns: A list of @EventInfo for all supported events
329 # -> { "execute": "query-events" }
341 # Note: This example has been shortened as the real response is too long.
344 { 'command': 'query-events', 'returns': ['EventInfo'] }
349 # An enumeration of cpu types that enable additional information during
350 # @query-cpus and @query-cpus-fast.
358 { 'enum': 'CpuInfoArch',
359 'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 's390', 'riscv', 'other' ] }
364 # Information about a virtual CPU
366 # @CPU: the index of the virtual CPU
368 # @current: this only exists for backwards compatibility and should be ignored
370 # @halted: true if the virtual CPU is in the halt state. Halt usually refers
371 # to a processor specific low power mode.
373 # @qom_path: path to the CPU object in the QOM tree (since 2.4)
375 # @thread_id: ID of the underlying host thread
377 # @props: properties describing to which node/socket/core/thread
378 # virtual CPU belongs to, provided if supported by board (since 2.10)
380 # @arch: architecture of the cpu, which determines which additional fields
381 # will be listed (since 2.6)
385 # Notes: @halted is a transient state that changes frequently. By the time the
386 # data is sent to the client, the guest may no longer be halted.
388 { 'union': 'CpuInfo',
389 'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool',
390 'qom_path': 'str', 'thread_id': 'int',
391 '*props': 'CpuInstanceProperties', 'arch': 'CpuInfoArch' },
392 'discriminator': 'arch',
393 'data': { 'x86': 'CpuInfoX86',
394 'sparc': 'CpuInfoSPARC',
396 'mips': 'CpuInfoMIPS',
397 'tricore': 'CpuInfoTricore',
398 's390': 'CpuInfoS390',
399 'riscv': 'CpuInfoRISCV' } }
404 # Additional information about a virtual i386 or x86_64 CPU
406 # @pc: the 64-bit instruction pointer
410 { 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } }
415 # Additional information about a virtual SPARC CPU
417 # @pc: the PC component of the instruction pointer
419 # @npc: the NPC component of the instruction pointer
423 { 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } }
428 # Additional information about a virtual PPC CPU
430 # @nip: the instruction pointer
434 { 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } }
439 # Additional information about a virtual MIPS CPU
441 # @PC: the instruction pointer
445 { 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } }
450 # Additional information about a virtual Tricore CPU
452 # @PC: the instruction pointer
456 { 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } }
461 # Additional information about a virtual RISCV CPU
463 # @pc: the instruction pointer
467 { 'struct': 'CpuInfoRISCV', 'data': { 'pc': 'int' } }
472 # An enumeration of cpu states that can be assumed by a virtual
477 { 'enum': 'CpuS390State',
478 'prefix': 'S390_CPU_STATE',
479 'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] }
484 # Additional information about a virtual S390 CPU
486 # @cpu-state: the virtual CPU's state
490 { 'struct': 'CpuInfoS390', 'data': { 'cpu-state': 'CpuS390State' } }
495 # Returns a list of information about each virtual CPU.
497 # This command causes vCPU threads to exit to userspace, which causes
498 # a small interruption to guest CPU execution. This will have a negative
499 # impact on realtime guests and other latency sensitive guest workloads.
500 # It is recommended to use @query-cpus-fast instead of this command to
501 # avoid the vCPU interruption.
503 # Returns: a list of @CpuInfo for each virtual CPU
509 # -> { "execute": "query-cpus" }
515 # "qom_path":"/machine/unattached/device[0]",
524 # "qom_path":"/machine/unattached/device[2]",
532 # Notes: This interface is deprecated (since 2.12.0), and it is strongly
533 # recommended that you avoid using it. Use @query-cpus-fast to
534 # obtain information about virtual CPUs.
537 { 'command': 'query-cpus', 'returns': ['CpuInfo'] }
542 # Information about a virtual CPU
544 # @cpu-index: index of the virtual CPU
546 # @qom-path: path to the CPU object in the QOM tree
548 # @thread-id: ID of the underlying host thread
550 # @props: properties describing to which node/socket/core/thread
551 # virtual CPU belongs to, provided if supported by board
553 # @arch: base architecture of the cpu; deprecated since 3.0.0 in favor
556 # @target: the QEMU system emulation target, which determines which
557 # additional fields will be listed (since 3.0)
562 { 'union' : 'CpuInfoFast',
563 'base' : { 'cpu-index' : 'int',
566 '*props' : 'CpuInstanceProperties',
567 'arch' : 'CpuInfoArch',
568 'target' : 'SysEmuTarget' },
569 'discriminator' : 'target',
570 'data' : { 's390x' : 'CpuInfoS390' } }
575 # Returns information about all virtual CPUs. This command does not
576 # incur a performance penalty and should be used in production
577 # instead of query-cpus.
579 # Returns: list of @CpuInfoFast
585 # -> { "execute": "query-cpus-fast" }
588 # "thread-id": 25627,
594 # "qom-path": "/machine/unattached/device[0]",
600 # "thread-id": 25628,
606 # "qom-path": "/machine/unattached/device[2]",
614 { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
619 # Information about an iothread
621 # @id: the identifier of the iothread
623 # @thread-id: ID of the underlying host thread
625 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
628 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
629 # configured (since 2.9)
631 # @poll-shrink: how many ns will be removed from polling time, 0 means that
632 # it's not configured (since 2.9)
636 { 'struct': 'IOThreadInfo',
637 'data': {'id': 'str',
639 'poll-max-ns': 'int',
641 'poll-shrink': 'int' } }
646 # Returns a list of information about each iothread.
648 # Note: this list excludes the QEMU main loop thread, which is not declared
649 # using the -object iothread command-line option. It is always the main thread
652 # Returns: a list of @IOThreadInfo for each iothread
658 # -> { "execute": "query-iothreads" }
672 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
673 'allow-preconfig': true }
678 # Information about the guest balloon device.
680 # @actual: the number of bytes the balloon currently contains
685 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
690 # Return information about the balloon device.
692 # Returns: @BalloonInfo on success
694 # If the balloon driver is enabled but not functional because the KVM
695 # kernel module cannot support it, KvmMissingCap
697 # If no balloon device is present, DeviceNotActive
703 # -> { "execute": "query-balloon" }
705 # "actual": 1073741824,
710 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
715 # Emitted when the guest changes the actual BALLOON level. This value is
716 # equivalent to the @actual field return by the 'query-balloon' command
718 # @actual: actual level of the guest memory balloon in bytes
720 # Note: this event is rate-limited.
726 # <- { "event": "BALLOON_CHANGE",
727 # "data": { "actual": 944766976 },
728 # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
731 { 'event': 'BALLOON_CHANGE',
732 'data': { 'actual': 'int' } }
737 # A PCI device memory region
739 # @base: the starting address (guest physical)
741 # @limit: the ending address (guest physical)
745 { 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
750 # Information about a PCI device I/O region.
752 # @bar: the index of the Base Address Register for this region
754 # @type: 'io' if the region is a PIO region
755 # 'memory' if the region is a MMIO region
759 # @prefetch: if @type is 'memory', true if the memory is prefetchable
761 # @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
765 { 'struct': 'PciMemoryRegion',
766 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
767 '*prefetch': 'bool', '*mem_type_64': 'bool' } }
772 # Information about a bus of a PCI Bridge device
774 # @number: primary bus interface number. This should be the number of the
775 # bus the device resides on.
777 # @secondary: secondary bus interface number. This is the number of the
778 # main bus for the bridge
780 # @subordinate: This is the highest number bus that resides below the
783 # @io_range: The PIO range for all devices on this bridge
785 # @memory_range: The MMIO range for all devices on this bridge
787 # @prefetchable_range: The range of prefetchable MMIO for all devices on
792 { 'struct': 'PciBusInfo',
793 'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
794 'io_range': 'PciMemoryRange',
795 'memory_range': 'PciMemoryRange',
796 'prefetchable_range': 'PciMemoryRange' } }
801 # Information about a PCI Bridge device
803 # @bus: information about the bus the device resides on
805 # @devices: a list of @PciDeviceInfo for each device on this bridge
809 { 'struct': 'PciBridgeInfo',
810 'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }
815 # Information about the Class of a PCI device
817 # @desc: a string description of the device's class
819 # @class: the class code of the device
823 { 'struct': 'PciDeviceClass',
824 'data': {'*desc': 'str', 'class': 'int'} }
829 # Information about the Id of a PCI device
831 # @device: the PCI device id
833 # @vendor: the PCI vendor id
835 # @subsystem: the PCI subsystem id (since 3.1)
837 # @subsystem-vendor: the PCI subsystem vendor id (since 3.1)
841 { 'struct': 'PciDeviceId',
842 'data': {'device': 'int', 'vendor': 'int', '*subsystem': 'int',
843 '*subsystem-vendor': 'int'} }
848 # Information about a PCI device
850 # @bus: the bus number of the device
852 # @slot: the slot the device is located in
854 # @function: the function of the slot used by the device
856 # @class_info: the class of the device
858 # @id: the PCI device id
860 # @irq: if an IRQ is assigned to the device, the IRQ number
862 # @qdev_id: the device name of the PCI device
864 # @pci_bridge: if the device is a PCI bridge, the bridge information
866 # @regions: a list of the PCI I/O regions associated with the device
868 # Notes: the contents of @class_info.desc are not stable and should only be
869 # treated as informational.
873 { 'struct': 'PciDeviceInfo',
874 'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
875 'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
876 '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo',
877 'regions': ['PciMemoryRegion']} }
882 # Information about a PCI bus
884 # @bus: the bus index
886 # @devices: a list of devices on this bus
890 { 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
895 # Return information about the PCI bus topology of the guest.
897 # Returns: a list of @PciInfo for each PCI bus. Each bus is
898 # represented by a json-object, which has a key with a json-array of
899 # all PCI devices attached to it. Each device is represented by a
906 # -> { "execute": "query-pci" }
917 # "desc": "Host bridge"
933 # "desc": "ISA bridge"
949 # "desc": "IDE controller"
971 # "desc": "VGA controller"
981 # "mem_type_64": false,
984 # "address": 4026531840,
989 # "mem_type_64": false,
992 # "address": 4060086272,
997 # "mem_type_64": false,
1012 # "desc": "RAM controller"
1033 # Note: This example has been shortened as the real response is too long.
1036 { 'command': 'query-pci', 'returns': ['PciInfo'] }
1041 # This command will cause the QEMU process to exit gracefully. While every
1042 # attempt is made to send the QMP response before terminating, this is not
1043 # guaranteed. When using this interface, a premature EOF would not be
1050 # -> { "execute": "quit" }
1051 # <- { "return": {} }
1053 { 'command': 'quit' }
1058 # Stop all guest VCPU execution.
1062 # Notes: This function will succeed even if the guest is already in the stopped
1063 # state. In "inmigrate" state, it will ensure that the guest
1064 # remains paused once migration finishes, as if the -S option was
1065 # passed on the command line.
1069 # -> { "execute": "stop" }
1070 # <- { "return": {} }
1073 { 'command': 'stop' }
1078 # Performs a hard reset of a guest.
1084 # -> { "execute": "system_reset" }
1085 # <- { "return": {} }
1088 { 'command': 'system_reset' }
1091 # @system_powerdown:
1093 # Requests that a guest perform a powerdown operation.
1097 # Notes: A guest may or may not respond to this command. This command
1098 # returning does not indicate that a guest has accepted the request or
1099 # that it has shut down. Many guests will respond to this command by
1100 # prompting the user in some way.
1103 # -> { "execute": "system_powerdown" }
1104 # <- { "return": {} }
1107 { 'command': 'system_powerdown' }
1112 # Adds CPU with specified ID.
1114 # @id: ID of CPU to be created, valid values [0..max_cpus)
1116 # Returns: Nothing on success
1120 # Note: This command is deprecated. The `device_add` command should be
1121 # used instead. See the `query-hotpluggable-cpus` command for
1126 # -> { "execute": "cpu-add", "arguments": { "id": 2 } }
1127 # <- { "return": {} }
1130 { 'command': 'cpu-add', 'data': {'id': 'int'} }
1135 # Save a portion of guest memory to a file.
1137 # @val: the virtual address of the guest to start from
1139 # @size: the size of memory region to save
1141 # @filename: the file to save the memory to as binary data
1143 # @cpu-index: the index of the virtual CPU to use for translating the
1144 # virtual address (defaults to CPU 0)
1146 # Returns: Nothing on success
1150 # Notes: Errors were not reliably returned until 1.1
1154 # -> { "execute": "memsave",
1155 # "arguments": { "val": 10,
1157 # "filename": "/tmp/virtual-mem-dump" } }
1158 # <- { "return": {} }
1161 { 'command': 'memsave',
1162 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
1167 # Save a portion of guest physical memory to a file.
1169 # @val: the physical address of the guest to start from
1171 # @size: the size of memory region to save
1173 # @filename: the file to save the memory to as binary data
1175 # Returns: Nothing on success
1179 # Notes: Errors were not reliably returned until 1.1
1183 # -> { "execute": "pmemsave",
1184 # "arguments": { "val": 10,
1186 # "filename": "/tmp/physical-mem-dump" } }
1187 # <- { "return": {} }
1190 { 'command': 'pmemsave',
1191 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
1196 # Resume guest VCPU execution.
1200 # Returns: If successful, nothing
1202 # Notes: This command will succeed if the guest is currently running. It
1203 # will also succeed if the guest is in the "inmigrate" state; in
1204 # this case, the effect of the command is to make sure the guest
1205 # starts once migration finishes, removing the effect of the -S
1206 # command line option if it was passed.
1210 # -> { "execute": "cont" }
1211 # <- { "return": {} }
1214 { 'command': 'cont' }
1217 # @x-exit-preconfig:
1219 # Exit from "preconfig" state
1221 # This command makes QEMU exit the preconfig state and proceed with
1222 # VM initialization using configuration data provided on the command line
1223 # and via the QMP monitor during the preconfig state. The command is only
1224 # available during the preconfig state (i.e. when the --preconfig command
1225 # line option was in use).
1233 # -> { "execute": "x-exit-preconfig" }
1234 # <- { "return": {} }
1237 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }
1242 # Wake up guest from suspend. If the guest has wake-up from suspend
1243 # support enabled (wakeup-suspend-support flag from
1244 # query-current-machine), wake-up guest from suspend if the guest is
1245 # in SUSPENDED state. Return an error otherwise.
1251 # Note: prior to 4.0, this command does nothing in case the guest
1256 # -> { "execute": "system_wakeup" }
1257 # <- { "return": {} }
1260 { 'command': 'system_wakeup' }
1265 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
1266 # The command fails when the guest doesn't support injecting.
1268 # Returns: If successful, nothing
1272 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
1276 # -> { "execute": "inject-nmi" }
1277 # <- { "return": {} }
1280 { 'command': 'inject-nmi' }
1285 # Request the balloon driver to change its balloon size.
1287 # @value: the target size of the balloon in bytes
1289 # Returns: Nothing on success
1290 # If the balloon driver is enabled but not functional because the KVM
1291 # kernel module cannot support it, KvmMissingCap
1292 # If no balloon device is present, DeviceNotActive
1294 # Notes: This command just issues a request to the guest. When it returns,
1295 # the balloon size may not have changed. A guest can change the balloon
1296 # size independent of this command.
1302 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1303 # <- { "return": {} }
1306 { 'command': 'balloon', 'data': {'value': 'int'} }
1309 # @human-monitor-command:
1311 # Execute a command on the human monitor and return the output.
1313 # @command-line: the command to execute in the human monitor
1315 # @cpu-index: The CPU to use for commands that require an implicit CPU
1317 # Returns: the output of the command as a string
1321 # Notes: This command only exists as a stop-gap. Its use is highly
1322 # discouraged. The semantics of this command are not
1323 # guaranteed: this means that command names, arguments and
1324 # responses can change or be removed at ANY time. Applications
1325 # that rely on long term stability guarantees should NOT
1328 # Known limitations:
1330 # * This command is stateless, this means that commands that depend
1331 # on state information (such as getfd) might not work
1333 # * Commands that prompt the user for data don't currently work
1337 # -> { "execute": "human-monitor-command",
1338 # "arguments": { "command-line": "info kvm" } }
1339 # <- { "return": "kvm support: enabled\r\n" }
1342 { 'command': 'human-monitor-command',
1343 'data': {'command-line': 'str', '*cpu-index': 'int'},
1347 # @ObjectPropertyInfo:
1349 # @name: the name of the property
1351 # @type: the type of the property. This will typically come in one of four
1354 # 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
1355 # These types are mapped to the appropriate JSON type.
1357 # 2) A child type in the form 'child<subtype>' where subtype is a qdev
1358 # device type name. Child properties create the composition tree.
1360 # 3) A link type in the form 'link<subtype>' where subtype is a qdev
1361 # device type name. Link properties form the device model graph.
1363 # @description: if specified, the description of the property.
1367 { 'struct': 'ObjectPropertyInfo',
1368 'data': { 'name': 'str', 'type': 'str', '*description': 'str' } }
1373 # This command will list any properties of a object given a path in the object
1376 # @path: the path within the object model. See @qom-get for a description of
1379 # Returns: a list of @ObjectPropertyInfo that describe the properties of the
1386 # -> { "execute": "qom-list",
1387 # "arguments": { "path": "/chardevs" } }
1388 # <- { "return": [ { "name": "type", "type": "string" },
1389 # { "name": "parallel0", "type": "child<chardev-vc>" },
1390 # { "name": "serial0", "type": "child<chardev-vc>" },
1391 # { "name": "mon0", "type": "child<chardev-stdio>" } ] }
1394 { 'command': 'qom-list',
1395 'data': { 'path': 'str' },
1396 'returns': [ 'ObjectPropertyInfo' ],
1397 'allow-preconfig': true }
1402 # This command will get a property from a object model path and return the
1405 # @path: The path within the object model. There are two forms of supported
1406 # paths--absolute and partial paths.
1408 # Absolute paths are derived from the root object and can follow child<>
1409 # or link<> properties. Since they can follow link<> properties, they
1410 # can be arbitrarily long. Absolute paths look like absolute filenames
1411 # and are prefixed with a leading slash.
1413 # Partial paths look like relative filenames. They do not begin
1414 # with a prefix. The matching rules for partial paths are subtle but
1415 # designed to make specifying objects easy. At each level of the
1416 # composition tree, the partial path is matched as an absolute path.
1417 # The first match is not returned. At least two matches are searched
1418 # for. A successful result is only returned if only one match is
1419 # found. If more than one match is found, a flag is return to
1420 # indicate that the match was ambiguous.
1422 # @property: The property name to read
1424 # Returns: The property value. The type depends on the property
1425 # type. child<> and link<> properties are returned as #str
1426 # pathnames. All integer property types (u8, u16, etc) are
1433 # 1. Use absolute path
1435 # -> { "execute": "qom-get",
1436 # "arguments": { "path": "/machine/unattached/device[0]",
1437 # "property": "hotplugged" } }
1438 # <- { "return": false }
1440 # 2. Use partial path
1442 # -> { "execute": "qom-get",
1443 # "arguments": { "path": "unattached/sysbus",
1444 # "property": "type" } }
1445 # <- { "return": "System" }
1448 { 'command': 'qom-get',
1449 'data': { 'path': 'str', 'property': 'str' },
1451 'allow-preconfig': true }
1456 # This command will set a property from a object model path.
1458 # @path: see @qom-get for a description of this parameter
1460 # @property: the property name to set
1462 # @value: a value who's type is appropriate for the property type. See @qom-get
1463 # for a description of type mapping.
1469 # -> { "execute": "qom-set",
1470 # "arguments": { "path": "/machine",
1471 # "property": "graphics",
1472 # "value": false } }
1473 # <- { "return": {} }
1476 { 'command': 'qom-set',
1477 'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
1478 'allow-preconfig': true }
1483 # This command is multiple commands multiplexed together.
1485 # @device: This is normally the name of a block device but it may also be 'vnc'.
1486 # when it's 'vnc', then sub command depends on @target
1488 # @target: If @device is a block device, then this is the new filename.
1489 # If @device is 'vnc', then if the value 'password' selects the vnc
1490 # change password command. Otherwise, this specifies a new server URI
1491 # address to listen to for VNC connections.
1493 # @arg: If @device is a block device, then this is an optional format to open
1495 # If @device is 'vnc' and @target is 'password', this is the new VNC
1496 # password to set. See change-vnc-password for additional notes.
1498 # Returns: Nothing on success.
1499 # If @device is not a valid block device, DeviceNotFound
1501 # Notes: This interface is deprecated, and it is strongly recommended that you
1502 # avoid using it. For changing block devices, use
1503 # blockdev-change-medium; for changing VNC parameters, use
1504 # change-vnc-password.
1510 # 1. Change a removable medium
1512 # -> { "execute": "change",
1513 # "arguments": { "device": "ide1-cd0",
1514 # "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
1515 # <- { "return": {} }
1517 # 2. Change VNC password
1519 # -> { "execute": "change",
1520 # "arguments": { "device": "vnc", "target": "password",
1521 # "arg": "foobar1" } }
1522 # <- { "return": {} }
1525 { 'command': 'change',
1526 'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
1531 # This structure describes a search result from @qom-list-types
1533 # @name: the type name found in the search
1535 # @abstract: the type is abstract and can't be directly instantiated.
1536 # Omitted if false. (since 2.10)
1538 # @parent: Name of parent type, if any (since 2.10)
1542 { 'struct': 'ObjectTypeInfo',
1543 'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } }
1548 # This command will return a list of types given search parameters
1550 # @implements: if specified, only return types that implement this type name
1552 # @abstract: if true, include abstract types in the results
1554 # Returns: a list of @ObjectTypeInfo or an empty list if no results are found
1558 { 'command': 'qom-list-types',
1559 'data': { '*implements': 'str', '*abstract': 'bool' },
1560 'returns': [ 'ObjectTypeInfo' ],
1561 'allow-preconfig': true }
1564 # @device-list-properties:
1566 # List properties associated with a device.
1568 # @typename: the type name of a device
1570 # Returns: a list of ObjectPropertyInfo describing a devices properties
1572 # Note: objects can create properties at runtime, for example to describe
1573 # links between different devices and/or objects. These properties
1574 # are not included in the output of this command.
1578 { 'command': 'device-list-properties',
1579 'data': { 'typename': 'str'},
1580 'returns': [ 'ObjectPropertyInfo' ] }
1583 # @qom-list-properties:
1585 # List properties associated with a QOM object.
1587 # @typename: the type name of an object
1589 # Note: objects can create properties at runtime, for example to describe
1590 # links between different devices and/or objects. These properties
1591 # are not included in the output of this command.
1593 # Returns: a list of ObjectPropertyInfo describing object properties
1597 { 'command': 'qom-list-properties',
1598 'data': { 'typename': 'str'},
1599 'returns': [ 'ObjectPropertyInfo' ],
1600 'allow-preconfig': true }
1603 # @xen-set-global-dirty-log:
1605 # Enable or disable the global dirty log mode.
1607 # @enable: true to enable, false to disable.
1615 # -> { "execute": "xen-set-global-dirty-log",
1616 # "arguments": { "enable": true } }
1617 # <- { "return": {} }
1620 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
1625 # @driver: the name of the new device's driver
1627 # @bus: the device's parent bus (device tree path)
1629 # @id: the device's ID, must be unique
1631 # Additional arguments depend on the type.
1636 # 1. For detailed information about this command, please refer to the
1637 # 'docs/qdev-device-use.txt' file.
1639 # 2. It's possible to list device properties by running QEMU with the
1640 # "-device DEVICE,help" command-line argument, where DEVICE is the
1645 # -> { "execute": "device_add",
1646 # "arguments": { "driver": "e1000", "id": "net1",
1648 # "mac": "52:54:00:12:34:56" } }
1649 # <- { "return": {} }
1651 # TODO: This command effectively bypasses QAPI completely due to its
1652 # "additional arguments" business. It shouldn't have been added to
1653 # the schema in this form. It should be qapified properly, or
1654 # replaced by a properly qapified command.
1658 { 'command': 'device_add',
1659 'data': {'driver': 'str', '*bus': 'str', '*id': 'str'},
1660 'gen': false } # so we can get the additional arguments
1665 # Remove a device from a guest
1667 # @id: the device's ID or QOM path
1669 # Returns: Nothing on success
1670 # If @id is not a valid device, DeviceNotFound
1672 # Notes: When this command completes, the device may not be removed from the
1673 # guest. Hot removal is an operation that requires guest cooperation.
1674 # This command merely requests that the guest begin the hot removal
1675 # process. Completion of the device removal process is signaled with a
1676 # DEVICE_DELETED event. Guest reset will automatically complete removal
1683 # -> { "execute": "device_del",
1684 # "arguments": { "id": "net1" } }
1685 # <- { "return": {} }
1687 # -> { "execute": "device_del",
1688 # "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
1689 # <- { "return": {} }
1692 { 'command': 'device_del', 'data': {'id': 'str'} }
1697 # Emitted whenever the device removal completion is acknowledged by the guest.
1698 # At this point, it's safe to reuse the specified device ID. Device removal can
1699 # be initiated by the guest or by HMP/QMP commands.
1701 # @device: device name
1703 # @path: device path
1709 # <- { "event": "DEVICE_DELETED",
1710 # "data": { "device": "virtio-net-pci-0",
1711 # "path": "/machine/peripheral/virtio-net-pci-0" },
1712 # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
1715 { 'event': 'DEVICE_DELETED',
1716 'data': { '*device': 'str', 'path': 'str' } }
1719 # @DumpGuestMemoryFormat:
1721 # An enumeration of guest-memory-dump's format.
1725 # @kdump-zlib: kdump-compressed format with zlib-compressed
1727 # @kdump-lzo: kdump-compressed format with lzo-compressed
1729 # @kdump-snappy: kdump-compressed format with snappy-compressed
1731 # @win-dmp: Windows full crashdump format,
1732 # can be used instead of ELF converting (since 2.13)
1736 { 'enum': 'DumpGuestMemoryFormat',
1737 'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy', 'win-dmp' ] }
1740 # @dump-guest-memory:
1742 # Dump guest's memory to vmcore. It is a synchronous operation that can take
1743 # very long depending on the amount of guest memory.
1745 # @paging: if true, do paging to get guest's memory mapping. This allows
1746 # using gdb to process the core file.
1748 # IMPORTANT: this option can make QEMU allocate several gigabytes
1749 # of RAM. This can happen for a large guest, or a
1750 # malicious guest pretending to be large.
1752 # Also, paging=true has the following limitations:
1754 # 1. The guest may be in a catastrophic state or can have corrupted
1755 # memory, which cannot be trusted
1756 # 2. The guest can be in real-mode even if paging is enabled. For
1757 # example, the guest uses ACPI to sleep, and ACPI sleep state
1759 # 3. Currently only supported on i386 and x86_64.
1761 # @protocol: the filename or file descriptor of the vmcore. The supported
1764 # 1. file: the protocol starts with "file:", and the following
1765 # string is the file's path.
1766 # 2. fd: the protocol starts with "fd:", and the following string
1769 # @detach: if true, QMP will return immediately rather than
1770 # waiting for the dump to finish. The user can track progress
1771 # using "query-dump". (since 2.6).
1773 # @begin: if specified, the starting physical address.
1775 # @length: if specified, the memory size, in bytes. If you don't
1776 # want to dump all guest's memory, please specify the start @begin
1779 # @format: if specified, the format of guest memory dump. But non-elf
1780 # format is conflict with paging and filter, ie. @paging, @begin and
1781 # @length is not allowed to be specified with non-elf @format at the
1782 # same time (since 2.0)
1784 # Note: All boolean arguments default to false
1786 # Returns: nothing on success
1792 # -> { "execute": "dump-guest-memory",
1793 # "arguments": { "protocol": "fd:dump" } }
1794 # <- { "return": {} }
1797 { 'command': 'dump-guest-memory',
1798 'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
1799 '*begin': 'int', '*length': 'int',
1800 '*format': 'DumpGuestMemoryFormat'} }
1805 # Describe the status of a long-running background guest memory dump.
1807 # @none: no dump-guest-memory has started yet.
1809 # @active: there is one dump running in background.
1811 # @completed: the last dump has finished successfully.
1813 # @failed: the last dump has failed.
1817 { 'enum': 'DumpStatus',
1818 'data': [ 'none', 'active', 'completed', 'failed' ] }
1823 # The result format for 'query-dump'.
1825 # @status: enum of @DumpStatus, which shows current dump status
1827 # @completed: bytes written in latest dump (uncompressed)
1829 # @total: total bytes to be written in latest dump (uncompressed)
1833 { 'struct': 'DumpQueryResult',
1834 'data': { 'status': 'DumpStatus',
1841 # Query latest dump status.
1843 # Returns: A @DumpStatus object showing the dump status.
1849 # -> { "execute": "query-dump" }
1850 # <- { "return": { "status": "active", "completed": 1024000,
1851 # "total": 2048000 } }
1854 { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
1859 # Emitted when background dump has completed
1861 # @result: final dump status
1863 # @error: human-readable error string that provides
1864 # hint on why dump failed. Only presents on failure. The
1865 # user should not try to interpret the error string.
1871 # { "event": "DUMP_COMPLETED",
1872 # "data": {"result": {"total": 1090650112, "status": "completed",
1873 # "completed": 1090650112} } }
1876 { 'event': 'DUMP_COMPLETED' ,
1877 'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
1880 # @DumpGuestMemoryCapability:
1882 # A list of the available formats for dump-guest-memory
1886 { 'struct': 'DumpGuestMemoryCapability',
1888 'formats': ['DumpGuestMemoryFormat'] } }
1891 # @query-dump-guest-memory-capability:
1893 # Returns the available formats for dump-guest-memory
1895 # Returns: A @DumpGuestMemoryCapability object listing available formats for
1902 # -> { "execute": "query-dump-guest-memory-capability" }
1903 # <- { "return": { "formats":
1904 # ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
1907 { 'command': 'query-dump-guest-memory-capability',
1908 'returns': 'DumpGuestMemoryCapability' }
1913 # Create a QOM object.
1915 # @qom-type: the class name for the object to be created
1917 # @id: the name of the new object
1919 # @props: a dictionary of properties to be passed to the backend
1921 # Returns: Nothing on success
1922 # Error if @qom-type is not a valid class name
1928 # -> { "execute": "object-add",
1929 # "arguments": { "qom-type": "rng-random", "id": "rng1",
1930 # "props": { "filename": "/dev/hwrng" } } }
1931 # <- { "return": {} }
1934 { 'command': 'object-add',
1935 'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'} }
1940 # Remove a QOM object.
1942 # @id: the name of the QOM object to remove
1944 # Returns: Nothing on success
1945 # Error if @id is not a valid id for a QOM object
1951 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
1952 # <- { "return": {} }
1955 { 'command': 'object-del', 'data': {'id': 'str'} }
1960 # Receive a file descriptor via SCM rights and assign it a name
1962 # @fdname: file descriptor name
1964 # Returns: Nothing on success
1968 # Notes: If @fdname already exists, the file descriptor assigned to
1969 # it will be closed and replaced by the received file
1972 # The 'closefd' command can be used to explicitly close the
1973 # file descriptor when it is no longer needed.
1977 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1978 # <- { "return": {} }
1981 { 'command': 'getfd', 'data': {'fdname': 'str'} }
1986 # Close a file descriptor previously passed via SCM rights
1988 # @fdname: file descriptor name
1990 # Returns: Nothing on success
1996 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1997 # <- { "return": {} }
2000 { 'command': 'closefd', 'data': {'fdname': 'str'} }
2005 # Information describing a machine.
2007 # @name: the name of the machine
2009 # @alias: an alias for the machine name
2011 # @is-default: whether the machine is default
2013 # @cpu-max: maximum number of CPUs supported by the machine type
2016 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
2020 { 'struct': 'MachineInfo',
2021 'data': { 'name': 'str', '*alias': 'str',
2022 '*is-default': 'bool', 'cpu-max': 'int',
2023 'hotpluggable-cpus': 'bool'} }
2028 # Return a list of supported machines
2030 # Returns: a list of MachineInfo
2034 { 'command': 'query-machines', 'returns': ['MachineInfo'] }
2037 # @CurrentMachineParams:
2039 # Information describing the running machine parameters.
2041 # @wakeup-suspend-support: true if the machine supports wake up from
2046 { 'struct': 'CurrentMachineParams',
2047 'data': { 'wakeup-suspend-support': 'bool'} }
2050 # @query-current-machine:
2052 # Return information on the current virtual machine.
2054 # Returns: CurrentMachineParams
2058 { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
2061 # @CpuDefinitionInfo:
2063 # Virtual CPU definition.
2065 # @name: the name of the CPU definition
2067 # @migration-safe: whether a CPU definition can be safely used for
2068 # migration in combination with a QEMU compatibility machine
2069 # when migrating between different QEMU versions and between
2070 # hosts with different sets of (hardware or software)
2071 # capabilities. If not provided, information is not available
2072 # and callers should not assume the CPU definition to be
2073 # migration-safe. (since 2.8)
2075 # @static: whether a CPU definition is static and will not change depending on
2076 # QEMU version, machine type, machine options and accelerator options.
2077 # A static model is always migration-safe. (since 2.8)
2079 # @unavailable-features: List of properties that prevent
2080 # the CPU model from running in the current
2082 # @typename: Type name that can be used as argument to @device-list-properties,
2083 # to introspect properties configurable using -cpu or -global.
2086 # @unavailable-features is a list of QOM property names that
2087 # represent CPU model attributes that prevent the CPU from running.
2088 # If the QOM property is read-only, that means there's no known
2089 # way to make the CPU model run in the current host. Implementations
2090 # that choose not to provide specific information return the
2091 # property name "type".
2092 # If the property is read-write, it means that it MAY be possible
2093 # to run the CPU model in the current host if that property is
2094 # changed. Management software can use it as hints to suggest or
2095 # choose an alternative for the user, or just to generate meaningful
2096 # error messages explaining why the CPU model can't be used.
2097 # If @unavailable-features is an empty list, the CPU model is
2098 # runnable using the current host and machine-type.
2099 # If @unavailable-features is not present, runnability
2100 # information for the CPU is not available.
2104 { 'struct': 'CpuDefinitionInfo',
2105 'data': { 'name': 'str', '*migration-safe': 'bool', 'static': 'bool',
2106 '*unavailable-features': [ 'str' ], 'typename': 'str' } }
2111 # Actual memory information in bytes.
2113 # @base-memory: size of "base" memory specified with command line
2116 # @plugged-memory: size of memory that can be hot-unplugged. This field
2117 # is omitted if target doesn't support memory hotplug
2118 # (i.e. CONFIG_MEM_DEVICE not defined at build time).
2122 { 'struct': 'MemoryInfo',
2123 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } }
2126 # @query-memory-size-summary:
2128 # Return the amount of initially allocated and present hotpluggable (if
2129 # enabled) memory in bytes.
2133 # -> { "execute": "query-memory-size-summary" }
2134 # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
2138 { 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
2141 # @query-cpu-definitions:
2143 # Return a list of supported virtual CPU definitions
2145 # Returns: a list of CpuDefInfo
2149 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }
2154 # Virtual CPU model.
2156 # A CPU model consists of the name of a CPU definition, to which
2157 # delta changes are applied (e.g. features added/removed). Most magic values
2158 # that an architecture might require should be hidden behind the name.
2159 # However, if required, architectures can expose relevant properties.
2161 # @name: the name of the CPU definition the model is based on
2162 # @props: a dictionary of QOM properties to be applied
2166 { 'struct': 'CpuModelInfo',
2167 'data': { 'name': 'str',
2171 # @CpuModelExpansionType:
2173 # An enumeration of CPU model expansion types.
2175 # @static: Expand to a static CPU model, a combination of a static base
2176 # model name and property delta changes. As the static base model will
2177 # never change, the expanded CPU model will be the same, independent of
2178 # QEMU version, machine type, machine options, and accelerator options.
2179 # Therefore, the resulting model can be used by tooling without having
2180 # to specify a compatibility machine - e.g. when displaying the "host"
2181 # model. The @static CPU models are migration-safe.
2183 # @full: Expand all properties. The produced model is not guaranteed to be
2184 # migration-safe, but allows tooling to get an insight and work with
2187 # Note: When a non-migration-safe CPU model is expanded in static mode, some
2188 # features enabled by the CPU model may be omitted, because they can't be
2189 # implemented by a static CPU model definition (e.g. cache info passthrough and
2190 # PMU passthrough in x86). If you need an accurate representation of the
2191 # features enabled by a non-migration-safe CPU model, use @full. If you need a
2192 # static representation that will keep ABI compatibility even when changing QEMU
2193 # version or machine-type, use @static (but keep in mind that some features may
2198 { 'enum': 'CpuModelExpansionType',
2199 'data': [ 'static', 'full' ] }
2203 # @CpuModelExpansionInfo:
2205 # The result of a cpu model expansion.
2207 # @model: the expanded CpuModelInfo.
2211 { 'struct': 'CpuModelExpansionInfo',
2212 'data': { 'model': 'CpuModelInfo' } }
2216 # @query-cpu-model-expansion:
2218 # Expands a given CPU model (or a combination of CPU model + additional options)
2219 # to different granularities, allowing tooling to get an understanding what a
2220 # specific CPU model looks like in QEMU under a certain configuration.
2222 # This interface can be used to query the "host" CPU model.
2224 # The data returned by this command may be affected by:
2226 # * QEMU version: CPU models may look different depending on the QEMU version.
2227 # (Except for CPU models reported as "static" in query-cpu-definitions.)
2228 # * machine-type: CPU model may look different depending on the machine-type.
2229 # (Except for CPU models reported as "static" in query-cpu-definitions.)
2230 # * machine options (including accelerator): in some architectures, CPU models
2231 # may look different depending on machine and accelerator options. (Except for
2232 # CPU models reported as "static" in query-cpu-definitions.)
2233 # * "-cpu" arguments and global properties: arguments to the -cpu option and
2234 # global properties may affect expansion of CPU models. Using
2235 # query-cpu-model-expansion while using these is not advised.
2237 # Some architectures may not support all expansion types. s390x supports
2238 # "full" and "static".
2240 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
2241 # not supported, if the model cannot be expanded, if the model contains
2242 # an unknown CPU definition name, unknown properties or properties
2243 # with a wrong type. Also returns an error if an expansion type is
2248 { 'command': 'query-cpu-model-expansion',
2249 'data': { 'type': 'CpuModelExpansionType',
2250 'model': 'CpuModelInfo' },
2251 'returns': 'CpuModelExpansionInfo' }
2254 # @CpuModelCompareResult:
2256 # An enumeration of CPU model comparison results. The result is usually
2257 # calculated using e.g. CPU features or CPU generations.
2259 # @incompatible: If model A is incompatible to model B, model A is not
2260 # guaranteed to run where model B runs and the other way around.
2262 # @identical: If model A is identical to model B, model A is guaranteed to run
2263 # where model B runs and the other way around.
2265 # @superset: If model A is a superset of model B, model B is guaranteed to run
2266 # where model A runs. There are no guarantees about the other way.
2268 # @subset: If model A is a subset of model B, model A is guaranteed to run
2269 # where model B runs. There are no guarantees about the other way.
2273 { 'enum': 'CpuModelCompareResult',
2274 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
2279 # Information about a file descriptor that was added to an fd set.
2281 # @fdset-id: The ID of the fd set that @fd was added to.
2283 # @fd: The file descriptor that was received via SCM rights and
2284 # added to the fd set.
2288 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
2293 # Add a file descriptor, that was passed via SCM rights, to an fd set.
2295 # @fdset-id: The ID of the fd set to add the file descriptor to.
2297 # @opaque: A free-form string that can be used to describe the fd.
2299 # Returns: @AddfdInfo on success
2301 # If file descriptor was not received, FdNotSupplied
2303 # If @fdset-id is a negative value, InvalidParameterValue
2305 # Notes: The list of fd sets is shared by all monitor connections.
2307 # If @fdset-id is not specified, a new fd set will be created.
2313 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
2314 # <- { "return": { "fdset-id": 1, "fd": 3 } }
2317 { 'command': 'add-fd',
2318 'data': { '*fdset-id': 'int',
2320 'returns': 'AddfdInfo' }
2325 # Remove a file descriptor from an fd set.
2327 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
2329 # @fd: The file descriptor that is to be removed.
2331 # Returns: Nothing on success
2332 # If @fdset-id or @fd is not found, FdNotFound
2336 # Notes: The list of fd sets is shared by all monitor connections.
2338 # If @fd is not specified, all file descriptors in @fdset-id
2343 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
2344 # <- { "return": {} }
2347 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
2352 # Information about a file descriptor that belongs to an fd set.
2354 # @fd: The file descriptor value.
2356 # @opaque: A free-form string that can be used to describe the fd.
2360 { 'struct': 'FdsetFdInfo',
2361 'data': {'fd': 'int', '*opaque': 'str'} }
2366 # Information about an fd set.
2368 # @fdset-id: The ID of the fd set.
2370 # @fds: A list of file descriptors that belong to this fd set.
2374 { 'struct': 'FdsetInfo',
2375 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
2380 # Return information describing all fd sets.
2382 # Returns: A list of @FdsetInfo
2386 # Note: The list of fd sets is shared by all monitor connections.
2390 # -> { "execute": "query-fdsets" }
2396 # "opaque": "rdonly:/path/to/file"
2400 # "opaque": "rdwr:/path/to/file"
2420 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
2425 # Information describing the QEMU target.
2427 # @arch: the target architecture
2431 { 'struct': 'TargetInfo',
2432 'data': { 'arch': 'SysEmuTarget' } }
2437 # Return information about the target for this QEMU
2439 # Returns: TargetInfo
2443 { 'command': 'query-target', 'returns': 'TargetInfo' }
2446 # @AcpiTableOptions:
2448 # Specify an ACPI table on the command line to load.
2450 # At most one of @file and @data can be specified. The list of files specified
2451 # by any one of them is loaded and concatenated in order. If both are omitted,
2454 # Other fields / optargs can be used to override fields of the generic ACPI
2455 # table header; refer to the ACPI specification 5.0, section 5.2.6 System
2456 # Description Table Header. If a header field is not overridden, then the
2457 # corresponding value from the concatenated blob is used (in case of @file), or
2458 # it is filled in with a hard-coded value (in case of @data).
2460 # String fields are copied into the matching ACPI member from lowest address
2461 # upwards, and silently truncated / NUL-padded to length.
2463 # @sig: table signature / identifier (4 bytes)
2465 # @rev: table revision number (dependent on signature, 1 byte)
2467 # @oem_id: OEM identifier (6 bytes)
2469 # @oem_table_id: OEM table identifier (8 bytes)
2471 # @oem_rev: OEM-supplied revision number (4 bytes)
2473 # @asl_compiler_id: identifier of the utility that created the table
2476 # @asl_compiler_rev: revision number of the utility that created the
2479 # @file: colon (:) separated list of pathnames to load and
2480 # concatenate as table data. The resultant binary blob is expected to
2481 # have an ACPI table header. At least one file is required. This field
2484 # @data: colon (:) separated list of pathnames to load and
2485 # concatenate as table data. The resultant binary blob must not have an
2486 # ACPI table header. At least one file is required. This field excludes
2491 { 'struct': 'AcpiTableOptions',
2496 '*oem_table_id': 'str',
2497 '*oem_rev': 'uint32',
2498 '*asl_compiler_id': 'str',
2499 '*asl_compiler_rev': 'uint32',
2504 # @CommandLineParameterType:
2506 # Possible types for an option parameter.
2508 # @string: accepts a character string
2510 # @boolean: accepts "on" or "off"
2512 # @number: accepts a number
2514 # @size: accepts a number followed by an optional suffix (K)ilo,
2515 # (M)ega, (G)iga, (T)era
2519 { 'enum': 'CommandLineParameterType',
2520 'data': ['string', 'boolean', 'number', 'size'] }
2523 # @CommandLineParameterInfo:
2525 # Details about a single parameter of a command line option.
2527 # @name: parameter name
2529 # @type: parameter @CommandLineParameterType
2531 # @help: human readable text string, not suitable for parsing.
2533 # @default: default value string (since 2.1)
2537 { 'struct': 'CommandLineParameterInfo',
2538 'data': { 'name': 'str',
2539 'type': 'CommandLineParameterType',
2541 '*default': 'str' } }
2544 # @CommandLineOptionInfo:
2546 # Details about a command line option, including its list of parameter details
2548 # @option: option name
2550 # @parameters: an array of @CommandLineParameterInfo
2554 { 'struct': 'CommandLineOptionInfo',
2555 'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
2558 # @query-command-line-options:
2560 # Query command line option schema.
2562 # @option: option name
2564 # Returns: list of @CommandLineOptionInfo for all options (or for the given
2565 # @option). Returns an error if the given @option doesn't exist.
2571 # -> { "execute": "query-command-line-options",
2572 # "arguments": { "option": "option-rom" } }
2577 # "name": "romfile",
2581 # "name": "bootindex",
2585 # "option": "option-rom"
2591 {'command': 'query-command-line-options',
2592 'data': { '*option': 'str' },
2593 'returns': ['CommandLineOptionInfo'],
2594 'allow-preconfig': true }
2597 # @X86CPURegister32:
2599 # A X86 32-bit register
2603 { 'enum': 'X86CPURegister32',
2604 'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
2607 # @X86CPUFeatureWordInfo:
2609 # Information about a X86 CPU feature word
2611 # @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
2613 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
2616 # @cpuid-register: Output register containing the feature bits
2618 # @features: value of output register, containing the feature bits
2622 { 'struct': 'X86CPUFeatureWordInfo',
2623 'data': { 'cpuid-input-eax': 'int',
2624 '*cpuid-input-ecx': 'int',
2625 'cpuid-register': 'X86CPURegister32',
2626 'features': 'int' } }
2629 # @DummyForceArrays:
2631 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
2635 { 'struct': 'DummyForceArrays',
2636 'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
2642 # @node: NUMA nodes configuration
2644 # @dist: NUMA distance configuration (since 2.10)
2646 # @cpu: property based CPU(s) to node mapping (Since: 2.10)
2650 { 'enum': 'NumaOptionsType',
2651 'data': [ 'node', 'dist', 'cpu' ] }
2656 # A discriminated record of NUMA options. (for OptsVisitor)
2660 { 'union': 'NumaOptions',
2661 'base': { 'type': 'NumaOptionsType' },
2662 'discriminator': 'type',
2664 'node': 'NumaNodeOptions',
2665 'dist': 'NumaDistOptions',
2666 'cpu': 'NumaCpuOptions' }}
2671 # Create a guest NUMA node. (for OptsVisitor)
2673 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
2675 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin
2678 # @mem: memory size of this node; mutually exclusive with @memdev.
2679 # Equally divide total memory among nodes if both @mem and @memdev are
2682 # @memdev: memory backend object. If specified for one node,
2683 # it must be specified for all nodes.
2687 { 'struct': 'NumaNodeOptions',
2689 '*nodeid': 'uint16',
2690 '*cpus': ['uint16'],
2697 # Set the distance between 2 NUMA nodes.
2699 # @src: source NUMA node.
2701 # @dst: destination NUMA node.
2703 # @val: NUMA distance from source node to destination node.
2704 # When a node is unreachable from another node, set the distance
2705 # between them to 255.
2709 { 'struct': 'NumaDistOptions',
2718 # Option "-numa cpu" overrides default cpu to node mapping.
2719 # It accepts the same set of cpu properties as returned by
2720 # query-hotpluggable-cpus[].props, where node-id could be used to
2721 # override default node mapping.
2725 { 'struct': 'NumaCpuOptions',
2726 'base': 'CpuInstanceProperties',
2732 # Host memory policy types
2734 # @default: restore default policy, remove any nondefault policy
2736 # @preferred: set the preferred host nodes for allocation
2738 # @bind: a strict policy that restricts memory allocation to the
2739 # host nodes specified
2741 # @interleave: memory allocations are interleaved across the set
2742 # of host nodes specified
2746 { 'enum': 'HostMemPolicy',
2747 'data': [ 'default', 'preferred', 'bind', 'interleave' ] }
2752 # Information about memory backend
2754 # @id: backend's ID if backend has 'id' property (since 2.9)
2756 # @size: memory backend size
2758 # @merge: enables or disables memory merge support
2760 # @dump: includes memory backend's memory in a core dump or not
2762 # @prealloc: enables or disables memory preallocation
2764 # @host-nodes: host nodes for its memory policy
2766 # @policy: memory policy of memory backend
2770 { 'struct': 'Memdev',
2777 'host-nodes': ['uint16'],
2778 'policy': 'HostMemPolicy' }}
2783 # Returns information for all memory backends.
2785 # Returns: a list of @Memdev.
2791 # -> { "execute": "query-memdev" }
2795 # "size": 536870912,
2798 # "prealloc": false,
2799 # "host-nodes": [0, 1],
2803 # "size": 536870912,
2807 # "host-nodes": [2, 3],
2808 # "policy": "preferred"
2814 { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
2817 # @PCDIMMDeviceInfo:
2819 # PCDIMMDevice state information
2823 # @addr: physical address, where device is mapped
2825 # @size: size of memory that the device provides
2827 # @slot: slot number at which device is plugged in
2829 # @node: NUMA node number where device is plugged in
2831 # @memdev: memory backend linked with device
2833 # @hotplugged: true if device was hotplugged
2835 # @hotpluggable: true if device if could be added/removed while machine is running
2839 { 'struct': 'PCDIMMDeviceInfo',
2840 'data': { '*id': 'str',
2846 'hotplugged': 'bool',
2847 'hotpluggable': 'bool'
2852 # @MemoryDeviceInfo:
2854 # Union containing information about a memory device
2858 { 'union': 'MemoryDeviceInfo',
2859 'data': { 'dimm': 'PCDIMMDeviceInfo',
2860 'nvdimm': 'PCDIMMDeviceInfo'
2865 # @query-memory-devices:
2867 # Lists available memory devices and their state
2873 # -> { "execute": "query-memory-devices" }
2874 # <- { "return": [ { "data":
2875 # { "addr": 5368709120,
2876 # "hotpluggable": true,
2877 # "hotplugged": true,
2879 # "memdev": "/objects/memX",
2881 # "size": 1073741824,
2887 { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
2890 # @MEM_UNPLUG_ERROR:
2892 # Emitted when memory hot unplug error occurs.
2894 # @device: device name
2896 # @msg: Informative message
2902 # <- { "event": "MEM_UNPLUG_ERROR"
2903 # "data": { "device": "dimm1",
2904 # "msg": "acpi: device unplug for unsupported device"
2906 # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
2909 { 'event': 'MEM_UNPLUG_ERROR',
2910 'data': { 'device': 'str', 'msg': 'str' } }
2915 # @DIMM: memory slot
2916 # @CPU: logical CPU slot (since 2.7)
2918 { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
2923 # OSPM Status Indication for a device
2924 # For description of possible values of @source and @status fields
2925 # see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
2927 # @device: device ID associated with slot
2929 # @slot: slot ID, unique per slot of a given @slot-type
2931 # @slot-type: type of the slot
2933 # @source: an integer containing the source event
2935 # @status: an integer containing the status code
2939 { 'struct': 'ACPIOSTInfo',
2940 'data' : { '*device': 'str',
2942 'slot-type': 'ACPISlotType',
2947 # @query-acpi-ospm-status:
2949 # Return a list of ACPIOSTInfo for devices that support status
2950 # reporting via ACPI _OST method.
2956 # -> { "execute": "query-acpi-ospm-status" }
2957 # <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
2958 # { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
2959 # { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
2960 # { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
2964 { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
2969 # Emitted when guest executes ACPI _OST method.
2971 # @info: OSPM Status Indication
2977 # <- { "event": "ACPI_DEVICE_OST",
2978 # "data": { "device": "d1", "slot": "0",
2979 # "slot-type": "DIMM", "source": 1, "status": 0 } }
2982 { 'event': 'ACPI_DEVICE_OST',
2983 'data': { 'info': 'ACPIOSTInfo' } }
2988 # Emitted when the guest changes the RTC time.
2990 # @offset: offset between base RTC clock (as specified by -rtc base), and
2991 # new RTC clock value. Note that value will be different depending
2992 # on clock chosen to drive RTC (specified by -rtc clock).
2994 # Note: This event is rate-limited.
3000 # <- { "event": "RTC_CHANGE",
3001 # "data": { "offset": 78 },
3002 # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
3005 { 'event': 'RTC_CHANGE',
3006 'data': { 'offset': 'int' } }
3011 # Mode of the replay subsystem.
3013 # @none: normal execution mode. Replay or record are not enabled.
3015 # @record: record mode. All non-deterministic data is written into the
3018 # @play: replay mode. Non-deterministic data required for system execution
3019 # is read from the log.
3023 { 'enum': 'ReplayMode',
3024 'data': [ 'none', 'record', 'play' ] }
3027 # @xen-load-devices-state:
3029 # Load the state of all devices from file. The RAM and the block devices
3030 # of the VM are not loaded by this command.
3032 # @filename: the file to load the state of the devices from as binary
3033 # data. See xen-save-devices-state.txt for a description of the binary
3040 # -> { "execute": "xen-load-devices-state",
3041 # "arguments": { "filename": "/tmp/resume" } }
3042 # <- { "return": {} }
3045 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }
3050 # The struct describes capability for a specific GIC (Generic
3051 # Interrupt Controller) version. These bits are not only decided by
3052 # QEMU/KVM software version, but also decided by the hardware that
3053 # the program is running upon.
3055 # @version: version of GIC to be described. Currently, only 2 and 3
3058 # @emulated: whether current QEMU/hardware supports emulated GIC
3059 # device in user space.
3061 # @kernel: whether current QEMU/hardware supports hardware
3062 # accelerated GIC device in kernel.
3066 { 'struct': 'GICCapability',
3067 'data': { 'version': 'int',
3069 'kernel': 'bool' } }
3072 # @query-gic-capabilities:
3074 # This command is ARM-only. It will return a list of GICCapability
3075 # objects that describe its capability bits.
3077 # Returns: a list of GICCapability objects.
3083 # -> { "execute": "query-gic-capabilities" }
3084 # <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
3085 # { "version": 3, "emulated": false, "kernel": true } ] }
3088 { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] }
3091 # @CpuInstanceProperties:
3093 # List of properties to be used for hotplugging a CPU instance,
3094 # it should be passed by management with device_add command when
3095 # a CPU is being hotplugged.
3097 # @node-id: NUMA node ID the CPU belongs to
3098 # @socket-id: socket number within node/board the CPU belongs to
3099 # @core-id: core number within socket the CPU belongs to
3100 # @thread-id: thread number within core the CPU belongs to
3102 # Note: currently there are 4 properties that could be present
3103 # but management should be prepared to pass through other
3104 # properties with device_add command to allow for future
3105 # interface extension. This also requires the filed names to be kept in
3106 # sync with the properties passed to -device/device_add.
3110 { 'struct': 'CpuInstanceProperties',
3111 'data': { '*node-id': 'int',
3112 '*socket-id': 'int',
3121 # @type: CPU object type for usage with device_add command
3122 # @props: list of properties to be used for hotplugging CPU
3123 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
3124 # @qom-path: link to existing CPU object if CPU is present or
3125 # omitted if CPU is not present.
3129 { 'struct': 'HotpluggableCPU',
3130 'data': { 'type': 'str',
3131 'vcpus-count': 'int',
3132 'props': 'CpuInstanceProperties',
3138 # @query-hotpluggable-cpus:
3140 # TODO: Better documentation; currently there is none.
3142 # Returns: a list of HotpluggableCPU objects.
3148 # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
3150 # -> { "execute": "query-hotpluggable-cpus" }
3152 # { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
3153 # "vcpus-count": 1 },
3154 # { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
3155 # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
3158 # For pc machine type started with -smp 1,maxcpus=2:
3160 # -> { "execute": "query-hotpluggable-cpus" }
3163 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3164 # "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
3167 # "qom-path": "/machine/unattached/device[0]",
3168 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3169 # "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
3173 # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
3176 # -> { "execute": "query-hotpluggable-cpus" }
3179 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
3180 # "props": { "core-id": 1 }
3183 # "qom-path": "/machine/unattached/device[0]",
3184 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
3185 # "props": { "core-id": 0 }
3190 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
3191 'allow-preconfig': true }
3198 # @guid: the globally unique identifier
3202 { 'struct': 'GuidInfo', 'data': {'guid': 'str'} }
3205 # @query-vm-generation-id:
3207 # Show Virtual Machine Generation ID
3211 { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' }
3216 # Runtime equivalent of '-numa' CLI option, available at
3217 # preconfigure stage to configure numa mapping before initializing
3222 { 'command': 'set-numa-node', 'boxed': true,
3223 'data': 'NumaOptions',
3224 'allow-preconfig': true