# -*- Mode: Python -*- ## # = Introduction # # This document describes all commands currently supported by QMP. # # Most of the time their usage is exactly the same as in the user Monitor, this # means that any other document which also describe commands (the manpage, # QEMU's manual, etc) can and should be consulted. # # QMP has two types of commands: regular and query commands. Regular commands # usually change the Virtual Machine's state someway, while query commands just # return information. The sections below are divided accordingly. # # It's important to observe that all communication examples are formatted in # a reader-friendly way, so that they're easier to understand. However, in real # protocol usage, they're emitted as a single line. # # Also, the following notation is used to denote data flow: # # Example: # # | -> data issued by the Client # | <- Server data response # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. # # = Stability Considerations # # The current QMP command set (described in this file) may be useful for a # number of use cases, however it's limited and several commands have bad # defined semantics, specially with regard to command completion. # # These problems are going to be solved incrementally in the next QEMU releases # and we're going to establish a deprecation policy for badly defined commands. # # If you're planning to adopt QMP, please observe the following: # # 1. The deprecation policy will take effect and be documented soon, please # check the documentation of each used command as soon as a new release of # QEMU is available # # 2. DO NOT rely on anything which is not explicit documented # # 3. Errors, in special, are not documented. Applications should NOT check # for specific errors classes or data (it's strongly recommended to only # check for the "error" key) # ## { 'pragma': { 'doc-required': true } } # Whitelists to permit QAPI rule violations; think twice before you # add to them! { 'pragma': { # Commands allowed to return a non-dictionary: 'returns-whitelist': [ 'human-monitor-command', 'qom-get', 'query-migrate-cache-size', 'query-tpm-models', 'query-tpm-types', 'ringbuf-read' ], 'name-case-whitelist': [ 'ACPISlotType', # DIMM, visible through query-acpi-ospm-status 'CpuInfoMIPS', # PC, visible through query-cpu 'CpuInfoTricore', # PC, visible through query-cpu 'QapiErrorClass', # all members, visible through errors 'UuidInfo', # UUID, visible through query-uuid 'X86CPURegister32', # all members, visible indirectly through qom-get 'q_obj_CpuInfo-base' # CPU, visible through query-cpu ] } } # Documentation generated with qapi2texi.py is in source order, with # included sub-schemas inserted at the first include directive # (subsequent include directives have no effect). To get a sane and # stable order, it's best to include each sub-schema just once, or # include it first in qapi-schema.json. { 'include': 'qapi/common.json' } { 'include': 'qapi/sockets.json' } { 'include': 'qapi/run-state.json' } { 'include': 'qapi/crypto.json' } { 'include': 'qapi/block.json' } { 'include': 'qapi/char.json' } { 'include': 'qapi/net.json' } { 'include': 'qapi/rocker.json' } { 'include': 'qapi/tpm.json' } { 'include': 'qapi/ui.json' } { 'include': 'qapi/migration.json' } { 'include': 'qapi/transaction.json' } { 'include': 'qapi/trace.json' } { 'include': 'qapi/introspect.json' } ## # = Miscellanea ## ## # @qmp_capabilities: # # Enable QMP capabilities. # # Arguments: None. # # Example: # # -> { "execute": "qmp_capabilities" } # <- { "return": {} } # # Notes: This command is valid exactly when first connecting: it must be # issued before any other command will be accepted, and will fail once the # monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt) # # Since: 0.13 # ## { 'command': 'qmp_capabilities' } ## # @VersionTriple: # # A three-part version number. # # @major: The major version number. # # @minor: The minor version number. # # @micro: The micro version number. # # Since: 2.4 ## { 'struct': 'VersionTriple', 'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} } ## # @VersionInfo: # # A description of QEMU's version. # # @qemu: The version of QEMU. By current convention, a micro # version of 50 signifies a development branch. A micro version # greater than or equal to 90 signifies a release candidate for # the next minor version. A micro version of less than 50 # signifies a stable release. # # @package: QEMU will always set this field to an empty string. Downstream # versions of QEMU should set this to a non-empty string. The # exact format depends on the downstream however it highly # recommended that a unique name is used. # # Since: 0.14.0 ## { 'struct': 'VersionInfo', 'data': {'qemu': 'VersionTriple', 'package': 'str'} } ## # @query-version: # # Returns the current version of QEMU. # # Returns: A @VersionInfo object describing the current version of QEMU. # # Since: 0.14.0 # # Example: # # -> { "execute": "query-version" } # <- { # "return":{ # "qemu":{ # "major":0, # "minor":11, # "micro":5 # }, # "package":"" # } # } # ## { 'command': 'query-version', 'returns': 'VersionInfo' } ## # @CommandInfo: # # Information about a QMP command # # @name: The command name # # Since: 0.14.0 ## { 'struct': 'CommandInfo', 'data': {'name': 'str'} } ## # @query-commands: # # Return a list of supported QMP commands by this server # # Returns: A list of @CommandInfo for all supported commands # # Since: 0.14.0 # # Example: # # -> { "execute": "query-commands" } # <- { # "return":[ # { # "name":"query-balloon" # }, # { # "name":"system_powerdown" # } # ] # } # # Note: This example has been shortened as the real response is too long. # ## { 'command': 'query-commands', 'returns': ['CommandInfo'] } ## # @LostTickPolicy: # # Policy for handling lost ticks in timer devices. # # @discard: throw away the missed tick(s) and continue with future injection # normally. Guest time may be delayed, unless the OS has explicit # handling of lost ticks # # @delay: continue to deliver ticks at the normal rate. Guest time will be # delayed due to the late tick # # @merge: merge the missed tick(s) into one tick and inject. Guest time # may be delayed, depending on how the OS reacts to the merging # of ticks # # @slew: deliver ticks at a higher rate to catch up with the missed tick. The # guest time should not be delayed once catchup is complete. # # Since: 2.0 ## { 'enum': 'LostTickPolicy', 'data': ['discard', 'delay', 'merge', 'slew' ] } ## # @add_client: # # Allow client connections for VNC, Spice and socket based # character devices to be passed in to QEMU via SCM_RIGHTS. # # @protocol: protocol name. Valid names are "vnc", "spice" or the # name of a character device (eg. from -chardev id=XXXX) # # @fdname: file descriptor name previously passed via 'getfd' command # # @skipauth: whether to skip authentication. Only applies # to "vnc" and "spice" protocols # # @tls: whether to perform TLS. Only applies to the "spice" # protocol # # Returns: nothing on success. # # Since: 0.14.0 # # Example: # # -> { "execute": "add_client", "arguments": { "protocol": "vnc", # "fdname": "myclient" } } # <- { "return": {} } # ## { 'command': 'add_client', 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool', '*tls': 'bool' } } ## # @NameInfo: # # Guest name information. # # @name: The name of the guest # # Since: 0.14.0 ## { 'struct': 'NameInfo', 'data': {'*name': 'str'} } ## # @query-name: # # Return the name information of a guest. # # Returns: @NameInfo of the guest # # Since: 0.14.0 # # Example: # # -> { "execute": "query-name" } # <- { "return": { "name": "qemu-name" } } # ## { 'command': 'query-name', 'returns': 'NameInfo' } ## # @KvmInfo: # # Information about support for KVM acceleration # # @enabled: true if KVM acceleration is active # # @present: true if KVM acceleration is built into this executable # # Since: 0.14.0 ## { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } ## # @query-kvm: # # Returns information about KVM acceleration # # Returns: @KvmInfo # # Since: 0.14.0 # # Example: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } # ## { 'command': 'query-kvm', 'returns': 'KvmInfo' } ## # @UuidInfo: # # Guest UUID information (Universally Unique Identifier). # # @UUID: the UUID of the guest # # Since: 0.14.0 # # Notes: If no UUID was specified for the guest, a null UUID is returned. ## { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } ## # @query-uuid: # # Query the guest UUID information. # # Returns: The @UuidInfo for the guest # # Since: 0.14.0 # # Example: # # -> { "execute": "query-uuid" } # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } # ## { 'command': 'query-uuid', 'returns': 'UuidInfo' } ## # @EventInfo: # # Information about a QMP event # # @name: The event name # # Since: 1.2.0 ## { 'struct': 'EventInfo', 'data': {'name': 'str'} } ## # @query-events: # # Return a list of supported QMP events by this server # # Returns: A list of @EventInfo for all supported events # # Since: 1.2.0 # # Example: # # -> { "execute": "query-events" } # <- { # "return": [ # { # "name":"SHUTDOWN" # }, # { # "name":"RESET" # } # ] # } # # Note: This example has been shortened as the real response is too long. # ## { 'command': 'query-events', 'returns': ['EventInfo'] } ## # @CpuInfoArch: # # An enumeration of cpu types that enable additional information during # @query-cpus. # # Since: 2.6 ## { 'enum': 'CpuInfoArch', 'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 'other' ] } ## # @CpuInfo: # # Information about a virtual CPU # # @CPU: the index of the virtual CPU # # @current: this only exists for backwards compatibility and should be ignored # # @halted: true if the virtual CPU is in the halt state. Halt usually refers # to a processor specific low power mode. # # @qom_path: path to the CPU object in the QOM tree (since 2.4) # # @thread_id: ID of the underlying host thread # # @props: properties describing to which node/socket/core/thread # virtual CPU belongs to, provided if supported by board (since 2.10) # # @arch: architecture of the cpu, which determines which additional fields # will be listed (since 2.6) # # Since: 0.14.0 # # Notes: @halted is a transient state that changes frequently. By the time the # data is sent to the client, the guest may no longer be halted. ## { 'union': 'CpuInfo', 'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool', 'qom_path': 'str', 'thread_id': 'int', '*props': 'CpuInstanceProperties', 'arch': 'CpuInfoArch' }, 'discriminator': 'arch', 'data': { 'x86': 'CpuInfoX86', 'sparc': 'CpuInfoSPARC', 'ppc': 'CpuInfoPPC', 'mips': 'CpuInfoMIPS', 'tricore': 'CpuInfoTricore', 'other': 'CpuInfoOther' } } ## # @CpuInfoX86: # # Additional information about a virtual i386 or x86_64 CPU # # @pc: the 64-bit instruction pointer # # Since: 2.6 ## { 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } } ## # @CpuInfoSPARC: # # Additional information about a virtual SPARC CPU # # @pc: the PC component of the instruction pointer # # @npc: the NPC component of the instruction pointer # # Since: 2.6 ## { 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } } ## # @CpuInfoPPC: # # Additional information about a virtual PPC CPU # # @nip: the instruction pointer # # Since: 2.6 ## { 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } } ## # @CpuInfoMIPS: # # Additional information about a virtual MIPS CPU # # @PC: the instruction pointer # # Since: 2.6 ## { 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } } ## # @CpuInfoTricore: # # Additional information about a virtual Tricore CPU # # @PC: the instruction pointer # # Since: 2.6 ## { 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } } ## # @CpuInfoOther: # # No additional information is available about the virtual CPU # # Since: 2.6 # ## { 'struct': 'CpuInfoOther', 'data': { } } ## # @query-cpus: # # Returns a list of information about each virtual CPU. # # Returns: a list of @CpuInfo for each virtual CPU # # Since: 0.14.0 # # Example: # # -> { "execute": "query-cpus" } # <- { "return": [ # { # "CPU":0, # "current":true, # "halted":false, # "qom_path":"/machine/unattached/device[0]", # "arch":"x86", # "pc":3227107138, # "thread_id":3134 # }, # { # "CPU":1, # "current":false, # "halted":true, # "qom_path":"/machine/unattached/device[2]", # "arch":"x86", # "pc":7108165, # "thread_id":3135 # } # ] # } # ## { 'command': 'query-cpus', 'returns': ['CpuInfo'] } ## # @IOThreadInfo: # # Information about an iothread # # @id: the identifier of the iothread # # @thread-id: ID of the underlying host thread # # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled # (since 2.9) # # @poll-grow: how many ns will be added to polling time, 0 means that it's not # configured (since 2.9) # # @poll-shrink: how many ns will be removed from polling time, 0 means that # it's not configured (since 2.9) # # Since: 2.0 ## { 'struct': 'IOThreadInfo', 'data': {'id': 'str', 'thread-id': 'int', 'poll-max-ns': 'int', 'poll-grow': 'int', 'poll-shrink': 'int' } } ## # @query-iothreads: # # Returns a list of information about each iothread. # # Note: this list excludes the QEMU main loop thread, which is not declared # using the -object iothread command-line option. It is always the main thread # of the process. # # Returns: a list of @IOThreadInfo for each iothread # # Since: 2.0 # # Example: # # -> { "execute": "query-iothreads" } # <- { "return": [ # { # "id":"iothread0", # "thread-id":3134 # }, # { # "id":"iothread1", # "thread-id":3135 # } # ] # } # ## { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'] } ## # @BalloonInfo: # # Information about the guest balloon device. # # @actual: the number of bytes the balloon currently contains # # Since: 0.14.0 # ## { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } } ## # @query-balloon: # # Return information about the balloon device. # # Returns: @BalloonInfo on success # # If the balloon driver is enabled but not functional because the KVM # kernel module cannot support it, KvmMissingCap # # If no balloon device is present, DeviceNotActive # # Since: 0.14.0 # # Example: # # -> { "execute": "query-balloon" } # <- { "return": { # "actual": 1073741824, # } # } # ## { 'command': 'query-balloon', 'returns': 'BalloonInfo' } ## # @BALLOON_CHANGE: # # Emitted when the guest changes the actual BALLOON level. This value is # equivalent to the @actual field return by the 'query-balloon' command # # @actual: actual level of the guest memory balloon in bytes # # Note: this event is rate-limited. # # Since: 1.2 # # Example: # # <- { "event": "BALLOON_CHANGE", # "data": { "actual": 944766976 }, # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } # ## { 'event': 'BALLOON_CHANGE', 'data': { 'actual': 'int' } } ## # @PciMemoryRange: # # A PCI device memory region # # @base: the starting address (guest physical) # # @limit: the ending address (guest physical) # # Since: 0.14.0 ## { 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} } ## # @PciMemoryRegion: # # Information about a PCI device I/O region. # # @bar: the index of the Base Address Register for this region # # @type: 'io' if the region is a PIO region # 'memory' if the region is a MMIO region # # @size: memory size # # @prefetch: if @type is 'memory', true if the memory is prefetchable # # @mem_type_64: if @type is 'memory', true if the BAR is 64-bit # # Since: 0.14.0 ## { 'struct': 'PciMemoryRegion', 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int', '*prefetch': 'bool', '*mem_type_64': 'bool' } } ## # @PciBusInfo: # # Information about a bus of a PCI Bridge device # # @number: primary bus interface number. This should be the number of the # bus the device resides on. # # @secondary: secondary bus interface number. This is the number of the # main bus for the bridge # # @subordinate: This is the highest number bus that resides below the # bridge. # # @io_range: The PIO range for all devices on this bridge # # @memory_range: The MMIO range for all devices on this bridge # # @prefetchable_range: The range of prefetchable MMIO for all devices on # this bridge # # Since: 2.4 ## { 'struct': 'PciBusInfo', 'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int', 'io_range': 'PciMemoryRange', 'memory_range': 'PciMemoryRange', 'prefetchable_range': 'PciMemoryRange' } } ## # @PciBridgeInfo: # # Information about a PCI Bridge device # # @bus: information about the bus the device resides on # # @devices: a list of @PciDeviceInfo for each device on this bridge # # Since: 0.14.0 ## { 'struct': 'PciBridgeInfo', 'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} } ## # @PciDeviceClass: # # Information about the Class of a PCI device # # @desc: a string description of the device's class # # @class: the class code of the device # # Since: 2.4 ## { 'struct': 'PciDeviceClass', 'data': {'*desc': 'str', 'class': 'int'} } ## # @PciDeviceId: # # Information about the Id of a PCI device # # @device: the PCI device id # # @vendor: the PCI vendor id # # Since: 2.4 ## { 'struct': 'PciDeviceId', 'data': {'device': 'int', 'vendor': 'int'} } ## # @PciDeviceInfo: # # Information about a PCI device # # @bus: the bus number of the device # # @slot: the slot the device is located in # # @function: the function of the slot used by the device # # @class_info: the class of the device # # @id: the PCI device id # # @irq: if an IRQ is assigned to the device, the IRQ number # # @qdev_id: the device name of the PCI device # # @pci_bridge: if the device is a PCI bridge, the bridge information # # @regions: a list of the PCI I/O regions associated with the device # # Notes: the contents of @class_info.desc are not stable and should only be # treated as informational. # # Since: 0.14.0 ## { 'struct': 'PciDeviceInfo', 'data': {'bus': 'int', 'slot': 'int', 'function': 'int', 'class_info': 'PciDeviceClass', 'id': 'PciDeviceId', '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo', 'regions': ['PciMemoryRegion']} } ## # @PciInfo: # # Information about a PCI bus # # @bus: the bus index # # @devices: a list of devices on this bus # # Since: 0.14.0 ## { 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} } ## # @query-pci: # # Return information about the PCI bus topology of the guest. # # Returns: a list of @PciInfo for each PCI bus. Each bus is # represented by a json-object, which has a key with a json-array of # all PCI devices attached to it. Each device is represented by a # json-object. # # Since: 0.14.0 # # Example: # # -> { "execute": "query-pci" } # <- { "return": [ # { # "bus": 0, # "devices": [ # { # "bus": 0, # "qdev_id": "", # "slot": 0, # "class_info": { # "class": 1536, # "desc": "Host bridge" # }, # "id": { # "device": 32902, # "vendor": 4663 # }, # "function": 0, # "regions": [ # ] # }, # { # "bus": 0, # "qdev_id": "", # "slot": 1, # "class_info": { # "class": 1537, # "desc": "ISA bridge" # }, # "id": { # "device": 32902, # "vendor": 28672 # }, # "function": 0, # "regions": [ # ] # }, # { # "bus": 0, # "qdev_id": "", # "slot": 1, # "class_info": { # "class": 257, # "desc": "IDE controller" # }, # "id": { # "device": 32902, # "vendor": 28688 # }, # "function": 1, # "regions": [ # { # "bar": 4, # "size": 16, # "address": 49152, # "type": "io" # } # ] # }, # { # "bus": 0, # "qdev_id": "", # "slot": 2, # "class_info": { # "class": 768, # "desc": "VGA controller" # }, # "id": { # "device": 4115, # "vendor": 184 # }, # "function": 0, # "regions": [ # { # "prefetch": true, # "mem_type_64": false, # "bar": 0, # "size": 33554432, # "address": 4026531840, # "type": "memory" # }, # { # "prefetch": false, # "mem_type_64": false, # "bar": 1, # "size": 4096, # "address": 4060086272, # "type": "memory" # }, # { # "prefetch": false, # "mem_type_64": false, # "bar": 6, # "size": 65536, # "address": -1, # "type": "memory" # } # ] # }, # { # "bus": 0, # "qdev_id": "", # "irq": 11, # "slot": 4, # "class_info": { # "class": 1280, # "desc": "RAM controller" # }, # "id": { # "device": 6900, # "vendor": 4098 # }, # "function": 0, # "regions": [ # { # "bar": 0, # "size": 32, # "address": 49280, # "type": "io" # } # ] # } # ] # } # ] # } # # Note: This example has been shortened as the real response is too long. # ## { 'command': 'query-pci', 'returns': ['PciInfo'] } ## # @quit: # # This command will cause the QEMU process to exit gracefully. While every # attempt is made to send the QMP response before terminating, this is not # guaranteed. When using this interface, a premature EOF would not be # unexpected. # # Since: 0.14.0 # # Example: # # -> { "execute": "quit" } # <- { "return": {} } ## { 'command': 'quit' } ## # @stop: # # Stop all guest VCPU execution. # # Since: 0.14.0 # # Notes: This function will succeed even if the guest is already in the stopped # state. In "inmigrate" state, it will ensure that the guest # remains paused once migration finishes, as if the -S option was # passed on the command line. # # Example: # # -> { "execute": "stop" } # <- { "return": {} } # ## { 'command': 'stop' } ## # @system_reset: # # Performs a hard reset of a guest. # # Since: 0.14.0 # # Example: # # -> { "execute": "system_reset" } # <- { "return": {} } # ## { 'command': 'system_reset' } ## # @system_powerdown: # # Requests that a guest perform a powerdown operation. # # Since: 0.14.0 # # Notes: A guest may or may not respond to this command. This command # returning does not indicate that a guest has accepted the request or # that it has shut down. Many guests will respond to this command by # prompting the user in some way. # Example: # # -> { "execute": "system_powerdown" } # <- { "return": {} } # ## { 'command': 'system_powerdown' } ## # @cpu: # # This command is a nop that is only provided for the purposes of compatibility. # # Since: 0.14.0 # # Notes: Do not use this command. ## { 'command': 'cpu', 'data': {'index': 'int'} } ## # @cpu-add: # # Adds CPU with specified ID # # @id: ID of CPU to be created, valid values [0..max_cpus) # # Returns: Nothing on success # # Since: 1.5 # # Example: # # -> { "execute": "cpu-add", "arguments": { "id": 2 } } # <- { "return": {} } # ## { 'command': 'cpu-add', 'data': {'id': 'int'} } ## # @memsave: # # Save a portion of guest memory to a file. # # @val: the virtual address of the guest to start from # # @size: the size of memory region to save # # @filename: the file to save the memory to as binary data # # @cpu-index: the index of the virtual CPU to use for translating the # virtual address (defaults to CPU 0) # # Returns: Nothing on success # # Since: 0.14.0 # # Notes: Errors were not reliably returned until 1.1 # # Example: # # -> { "execute": "memsave", # "arguments": { "val": 10, # "size": 100, # "filename": "/tmp/virtual-mem-dump" } } # <- { "return": {} } # ## { 'command': 'memsave', 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} } ## # @pmemsave: # # Save a portion of guest physical memory to a file. # # @val: the physical address of the guest to start from # # @size: the size of memory region to save # # @filename: the file to save the memory to as binary data # # Returns: Nothing on success # # Since: 0.14.0 # # Notes: Errors were not reliably returned until 1.1 # # Example: # # -> { "execute": "pmemsave", # "arguments": { "val": 10, # "size": 100, # "filename": "/tmp/physical-mem-dump" } } # <- { "return": {} } # ## { 'command': 'pmemsave', 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} } ## # @cont: # # Resume guest VCPU execution. # # Since: 0.14.0 # # Returns: If successful, nothing # # Notes: This command will succeed if the guest is currently running. It # will also succeed if the guest is in the "inmigrate" state; in # this case, the effect of the command is to make sure the guest # starts once migration finishes, removing the effect of the -S # command line option if it was passed. # # Example: # # -> { "execute": "cont" } # <- { "return": {} } # ## { 'command': 'cont' } ## # @system_wakeup: # # Wakeup guest from suspend. Does nothing in case the guest isn't suspended. # # Since: 1.1 # # Returns: nothing. # # Example: # # -> { "execute": "system_wakeup" } # <- { "return": {} } # ## { 'command': 'system_wakeup' } ## # @inject-nmi: # # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64). # The command fails when the guest doesn't support injecting. # # Returns: If successful, nothing # # Since: 0.14.0 # # Note: prior to 2.1, this command was only supported for x86 and s390 VMs # # Example: # # -> { "execute": "inject-nmi" } # <- { "return": {} } # ## { 'command': 'inject-nmi' } ## # @balloon: # # Request the balloon driver to change its balloon size. # # @value: the target size of the balloon in bytes # # Returns: Nothing on success # If the balloon driver is enabled but not functional because the KVM # kernel module cannot support it, KvmMissingCap # If no balloon device is present, DeviceNotActive # # Notes: This command just issues a request to the guest. When it returns, # the balloon size may not have changed. A guest can change the balloon # size independent of this command. # # Since: 0.14.0 # # Example: # # -> { "execute": "balloon", "arguments": { "value": 536870912 } } # <- { "return": {} } # ## { 'command': 'balloon', 'data': {'value': 'int'} } ## # @human-monitor-command: # # Execute a command on the human monitor and return the output. # # @command-line: the command to execute in the human monitor # # @cpu-index: The CPU to use for commands that require an implicit CPU # # Returns: the output of the command as a string # # Since: 0.14.0 # # Notes: This command only exists as a stop-gap. Its use is highly # discouraged. The semantics of this command are not # guaranteed: this means that command names, arguments and # responses can change or be removed at ANY time. Applications # that rely on long term stability guarantees should NOT # use this command. # # Known limitations: # # * This command is stateless, this means that commands that depend # on state information (such as getfd) might not work # # * Commands that prompt the user for data don't currently work # # Example: # # -> { "execute": "human-monitor-command", # "arguments": { "command-line": "info kvm" } } # <- { "return": "kvm support: enabled\r\n" } # ## { 'command': 'human-monitor-command', 'data': {'command-line': 'str', '*cpu-index': 'int'}, 'returns': 'str' } ## # @ObjectPropertyInfo: # # @name: the name of the property # # @type: the type of the property. This will typically come in one of four # forms: # # 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'. # These types are mapped to the appropriate JSON type. # # 2) A child type in the form 'child<subtype>' where subtype is a qdev # device type name. Child properties create the composition tree. # # 3) A link type in the form 'link<subtype>' where subtype is a qdev # device type name. Link properties form the device model graph. # # Since: 1.2 ## { 'struct': 'ObjectPropertyInfo', 'data': { 'name': 'str', 'type': 'str' } } ## # @qom-list: # # This command will list any properties of a object given a path in the object # model. # # @path: the path within the object model. See @qom-get for a description of # this parameter. # # Returns: a list of @ObjectPropertyInfo that describe the properties of the # object. # # Since: 1.2 ## { 'command': 'qom-list', 'data': { 'path': 'str' }, 'returns': [ 'ObjectPropertyInfo' ] } ## # @qom-get: # # This command will get a property from a object model path and return the # value. # # @path: The path within the object model. There are two forms of supported # paths--absolute and partial paths. # # Absolute paths are derived from the root object and can follow child<> # or link<> properties. Since they can follow link<> properties, they # can be arbitrarily long. Absolute paths look like absolute filenames # and are prefixed with a leading slash. # # Partial paths look like relative filenames. They do not begin # with a prefix. The matching rules for partial paths are subtle but # designed to make specifying objects easy. At each level of the # composition tree, the partial path is matched as an absolute path. # The first match is not returned. At least two matches are searched # for. A successful result is only returned if only one match is # found. If more than one match is found, a flag is return to # indicate that the match was ambiguous. # # @property: The property name to read # # Returns: The property value. The type depends on the property # type. child<> and link<> properties are returned as #str # pathnames. All integer property types (u8, u16, etc) are # returned as #int. # # Since: 1.2 ## { 'command': 'qom-get', 'data': { 'path': 'str', 'property': 'str' }, 'returns': 'any' } ## # @qom-set: # # This command will set a property from a object model path. # # @path: see @qom-get for a description of this parameter # # @property: the property name to set # # @value: a value who's type is appropriate for the property type. See @qom-get # for a description of type mapping. # # Since: 1.2 ## { 'command': 'qom-set', 'data': { 'path': 'str', 'property': 'str', 'value': 'any' } } ## # @change: # # This command is multiple commands multiplexed together. # # @device: This is normally the name of a block device but it may also be 'vnc'. # when it's 'vnc', then sub command depends on @target # # @target: If @device is a block device, then this is the new filename. # If @device is 'vnc', then if the value 'password' selects the vnc # change password command. Otherwise, this specifies a new server URI # address to listen to for VNC connections. # # @arg: If @device is a block device, then this is an optional format to open # the device with. # If @device is 'vnc' and @target is 'password', this is the new VNC # password to set. See change-vnc-password for additional notes. # # Returns: Nothing on success. # If @device is not a valid block device, DeviceNotFound # # Notes: This interface is deprecated, and it is strongly recommended that you # avoid using it. For changing block devices, use # blockdev-change-medium; for changing VNC parameters, use # change-vnc-password. # # Since: 0.14.0 # # Example: # # 1. Change a removable medium # # -> { "execute": "change", # "arguments": { "device": "ide1-cd0", # "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } } # <- { "return": {} } # # 2. Change VNC password # # -> { "execute": "change", # "arguments": { "device": "vnc", "target": "password", # "arg": "foobar1" } } # <- { "return": {} } # ## { 'command': 'change', 'data': {'device': 'str', 'target': 'str', '*arg': 'str'} } ## # @ObjectTypeInfo: # # This structure describes a search result from @qom-list-types # # @name: the type name found in the search # # @abstract: the type is abstract and can't be directly instantiated. # Omitted if false. (since 2.10) # # @parent: Name of parent type, if any (since 2.10) # # Since: 1.1 ## { 'struct': 'ObjectTypeInfo', 'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } } ## # @qom-list-types: # # This command will return a list of types given search parameters # # @implements: if specified, only return types that implement this type name # # @abstract: if true, include abstract types in the results # # Returns: a list of @ObjectTypeInfo or an empty list if no results are found # # Since: 1.1 ## { 'command': 'qom-list-types', 'data': { '*implements': 'str', '*abstract': 'bool' }, 'returns': [ 'ObjectTypeInfo' ] } ## # @DevicePropertyInfo: # # Information about device properties. # # @name: the name of the property # @type: the typename of the property # @description: if specified, the description of the property. # (since 2.2) # # Since: 1.2 ## { 'struct': 'DevicePropertyInfo', 'data': { 'name': 'str', 'type': 'str', '*description': 'str' } } ## # @device-list-properties: # # List properties associated with a device. # # @typename: the type name of a device # # Returns: a list of DevicePropertyInfo describing a devices properties # # Since: 1.2 ## { 'command': 'device-list-properties', 'data': { 'typename': 'str'}, 'returns': [ 'DevicePropertyInfo' ] } ## # @xen-set-global-dirty-log: # # Enable or disable the global dirty log mode. # # @enable: true to enable, false to disable. # # Returns: nothing # # Since: 1.3 # # Example: # # -> { "execute": "xen-set-global-dirty-log", # "arguments": { "enable": true } } # <- { "return": {} } # ## { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } ## # @device_add: # # @driver: the name of the new device's driver # # @bus: the device's parent bus (device tree path) # # @id: the device's ID, must be unique # # Additional arguments depend on the type. # # Add a device. # # Notes: # 1. For detailed information about this command, please refer to the # 'docs/qdev-device-use.txt' file. # # 2. It's possible to list device properties by running QEMU with the # "-device DEVICE,help" command-line argument, where DEVICE is the # device's name # # Example: # # -> { "execute": "device_add", # "arguments": { "driver": "e1000", "id": "net1", # "bus": "pci.0", # "mac": "52:54:00:12:34:56" } } # <- { "return": {} } # # TODO: This command effectively bypasses QAPI completely due to its # "additional arguments" business. It shouldn't have been added to # the schema in this form. It should be qapified properly, or # replaced by a properly qapified command. # # Since: 0.13 ## { 'command': 'device_add', 'data': {'driver': 'str', '*bus': 'str', '*id': 'str'}, 'gen': false } # so we can get the additional arguments ## # @device_del: # # Remove a device from a guest # # @id: the device's ID or QOM path # # Returns: Nothing on success # If @id is not a valid device, DeviceNotFound # # Notes: When this command completes, the device may not be removed from the # guest. Hot removal is an operation that requires guest cooperation. # This command merely requests that the guest begin the hot removal # process. Completion of the device removal process is signaled with a # DEVICE_DELETED event. Guest reset will automatically complete removal # for all devices. # # Since: 0.14.0 # # Example: # # -> { "execute": "device_del", # "arguments": { "id": "net1" } } # <- { "return": {} } # # -> { "execute": "device_del", # "arguments": { "id": "/machine/peripheral-anon/device[0]" } } # <- { "return": {} } # ## { 'command': 'device_del', 'data': {'id': 'str'} } ## # @DEVICE_DELETED: # # Emitted whenever the device removal completion is acknowledged by the guest. # At this point, it's safe to reuse the specified device ID. Device removal can # be initiated by the guest or by HMP/QMP commands. # # @device: device name # # @path: device path # # Since: 1.5 # # Example: # # <- { "event": "DEVICE_DELETED", # "data": { "device": "virtio-net-pci-0", # "path": "/machine/peripheral/virtio-net-pci-0" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'DEVICE_DELETED', 'data': { '*device': 'str', 'path': 'str' } } ## # @DumpGuestMemoryFormat: # # An enumeration of guest-memory-dump's format. # # @elf: elf format # # @kdump-zlib: kdump-compressed format with zlib-compressed # # @kdump-lzo: kdump-compressed format with lzo-compressed # # @kdump-snappy: kdump-compressed format with snappy-compressed # # Since: 2.0 ## { 'enum': 'DumpGuestMemoryFormat', 'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy' ] } ## # @dump-guest-memory: # # Dump guest's memory to vmcore. It is a synchronous operation that can take # very long depending on the amount of guest memory. # # @paging: if true, do paging to get guest's memory mapping. This allows # using gdb to process the core file. # # IMPORTANT: this option can make QEMU allocate several gigabytes # of RAM. This can happen for a large guest, or a # malicious guest pretending to be large. # # Also, paging=true has the following limitations: # # 1. The guest may be in a catastrophic state or can have corrupted # memory, which cannot be trusted # 2. The guest can be in real-mode even if paging is enabled. For # example, the guest uses ACPI to sleep, and ACPI sleep state # goes in real-mode # 3. Currently only supported on i386 and x86_64. # # @protocol: the filename or file descriptor of the vmcore. The supported # protocols are: # # 1. file: the protocol starts with "file:", and the following # string is the file's path. # 2. fd: the protocol starts with "fd:", and the following string # is the fd's name. # # @detach: if true, QMP will return immediately rather than # waiting for the dump to finish. The user can track progress # using "query-dump". (since 2.6). # # @begin: if specified, the starting physical address. # # @length: if specified, the memory size, in bytes. If you don't # want to dump all guest's memory, please specify the start @begin # and @length # # @format: if specified, the format of guest memory dump. But non-elf # format is conflict with paging and filter, ie. @paging, @begin and # @length is not allowed to be specified with non-elf @format at the # same time (since 2.0) # # Note: All boolean arguments default to false # # Returns: nothing on success # # Since: 1.2 # # Example: # # -> { "execute": "dump-guest-memory", # "arguments": { "protocol": "fd:dump" } } # <- { "return": {} } # ## { 'command': 'dump-guest-memory', 'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool', '*begin': 'int', '*length': 'int', '*format': 'DumpGuestMemoryFormat'} } ## # @DumpStatus: # # Describe the status of a long-running background guest memory dump. # # @none: no dump-guest-memory has started yet. # # @active: there is one dump running in background. # # @completed: the last dump has finished successfully. # # @failed: the last dump has failed. # # Since: 2.6 ## { 'enum': 'DumpStatus', 'data': [ 'none', 'active', 'completed', 'failed' ] } ## # @DumpQueryResult: # # The result format for 'query-dump'. # # @status: enum of @DumpStatus, which shows current dump status # # @completed: bytes written in latest dump (uncompressed) # # @total: total bytes to be written in latest dump (uncompressed) # # Since: 2.6 ## { 'struct': 'DumpQueryResult', 'data': { 'status': 'DumpStatus', 'completed': 'int', 'total': 'int' } } ## # @query-dump: # # Query latest dump status. # # Returns: A @DumpStatus object showing the dump status. # # Since: 2.6 # # Example: # # -> { "execute": "query-dump" } # <- { "return": { "status": "active", "completed": 1024000, # "total": 2048000 } } # ## { 'command': 'query-dump', 'returns': 'DumpQueryResult' } ## # @DUMP_COMPLETED: # # Emitted when background dump has completed # # @result: DumpQueryResult type described in qapi-schema.json. # # @error: human-readable error string that provides # hint on why dump failed. Only presents on failure. The # user should not try to interpret the error string. # # Since: 2.6 # # Example: # # { "event": "DUMP_COMPLETED", # "data": {"result": {"total": 1090650112, "status": "completed", # "completed": 1090650112} } } # ## { 'event': 'DUMP_COMPLETED' , 'data': { 'result': 'DumpQueryResult', '*error': 'str' } } ## # @DumpGuestMemoryCapability: # # A list of the available formats for dump-guest-memory # # Since: 2.0 ## { 'struct': 'DumpGuestMemoryCapability', 'data': { 'formats': ['DumpGuestMemoryFormat'] } } ## # @query-dump-guest-memory-capability: # # Returns the available formats for dump-guest-memory # # Returns: A @DumpGuestMemoryCapability object listing available formats for # dump-guest-memory # # Since: 2.0 # # Example: # # -> { "execute": "query-dump-guest-memory-capability" } # <- { "return": { "formats": # ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } # ## { 'command': 'query-dump-guest-memory-capability', 'returns': 'DumpGuestMemoryCapability' } ## # @dump-skeys: # # Dump guest's storage keys # # @filename: the path to the file to dump to # # This command is only supported on s390 architecture. # # Since: 2.5 # # Example: # # -> { "execute": "dump-skeys", # "arguments": { "filename": "/tmp/skeys" } } # <- { "return": {} } # ## { 'command': 'dump-skeys', 'data': { 'filename': 'str' } } ## # @object-add: # # Create a QOM object. # # @qom-type: the class name for the object to be created # # @id: the name of the new object # # @props: a dictionary of properties to be passed to the backend # # Returns: Nothing on success # Error if @qom-type is not a valid class name # # Since: 2.0 # # Example: # # -> { "execute": "object-add", # "arguments": { "qom-type": "rng-random", "id": "rng1", # "props": { "filename": "/dev/hwrng" } } } # <- { "return": {} } # ## { 'command': 'object-add', 'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'} } ## # @object-del: # # Remove a QOM object. # # @id: the name of the QOM object to remove # # Returns: Nothing on success # Error if @id is not a valid id for a QOM object # # Since: 2.0 # # Example: # # -> { "execute": "object-del", "arguments": { "id": "rng1" } } # <- { "return": {} } # ## { 'command': 'object-del', 'data': {'id': 'str'} } ## # @getfd: # # Receive a file descriptor via SCM rights and assign it a name # # @fdname: file descriptor name # # Returns: Nothing on success # # Since: 0.14.0 # # Notes: If @fdname already exists, the file descriptor assigned to # it will be closed and replaced by the received file # descriptor. # # The 'closefd' command can be used to explicitly close the # file descriptor when it is no longer needed. # # Example: # # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } # ## { 'command': 'getfd', 'data': {'fdname': 'str'} } ## # @closefd: # # Close a file descriptor previously passed via SCM rights # # @fdname: file descriptor name # # Returns: Nothing on success # # Since: 0.14.0 # # Example: # # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } # ## { 'command': 'closefd', 'data': {'fdname': 'str'} } ## # @MachineInfo: # # Information describing a machine. # # @name: the name of the machine # # @alias: an alias for the machine name # # @is-default: whether the machine is default # # @cpu-max: maximum number of CPUs supported by the machine type # (since 1.5.0) # # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0) # # Since: 1.2.0 ## { 'struct': 'MachineInfo', 'data': { 'name': 'str', '*alias': 'str', '*is-default': 'bool', 'cpu-max': 'int', 'hotpluggable-cpus': 'bool'} } ## # @query-machines: # # Return a list of supported machines # # Returns: a list of MachineInfo # # Since: 1.2.0 ## { 'command': 'query-machines', 'returns': ['MachineInfo'] } ## # @CpuDefinitionInfo: # # Virtual CPU definition. # # @name: the name of the CPU definition # # @migration-safe: whether a CPU definition can be safely used for # migration in combination with a QEMU compatibility machine # when migrating between different QMU versions and between # hosts with different sets of (hardware or software) # capabilities. If not provided, information is not available # and callers should not assume the CPU definition to be # migration-safe. (since 2.8) # # @static: whether a CPU definition is static and will not change depending on # QEMU version, machine type, machine options and accelerator options. # A static model is always migration-safe. (since 2.8) # # @unavailable-features: List of properties that prevent # the CPU model from running in the current # host. (since 2.8) # @typename: Type name that can be used as argument to @device-list-properties, # to introspect properties configurable using -cpu or -global. # (since 2.9) # # @unavailable-features is a list of QOM property names that # represent CPU model attributes that prevent the CPU from running. # If the QOM property is read-only, that means there's no known # way to make the CPU model run in the current host. Implementations # that choose not to provide specific information return the # property name "type". # If the property is read-write, it means that it MAY be possible # to run the CPU model in the current host if that property is # changed. Management software can use it as hints to suggest or # choose an alternative for the user, or just to generate meaningful # error messages explaining why the CPU model can't be used. # If @unavailable-features is an empty list, the CPU model is # runnable using the current host and machine-type. # If @unavailable-features is not present, runnability # information for the CPU is not available. # # Since: 1.2.0 ## { 'struct': 'CpuDefinitionInfo', 'data': { 'name': 'str', '*migration-safe': 'bool', 'static': 'bool', '*unavailable-features': [ 'str' ], 'typename': 'str' } } ## # @query-cpu-definitions: # # Return a list of supported virtual CPU definitions # # Returns: a list of CpuDefInfo # # Since: 1.2.0 ## { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] } ## # @CpuModelInfo: # # Virtual CPU model. # # A CPU model consists of the name of a CPU definition, to which # delta changes are applied (e.g. features added/removed). Most magic values # that an architecture might require should be hidden behind the name. # However, if required, architectures can expose relevant properties. # # @name: the name of the CPU definition the model is based on # @props: a dictionary of QOM properties to be applied # # Since: 2.8.0 ## { 'struct': 'CpuModelInfo', 'data': { 'name': 'str', '*props': 'any' } } ## # @CpuModelExpansionType: # # An enumeration of CPU model expansion types. # # @static: Expand to a static CPU model, a combination of a static base # model name and property delta changes. As the static base model will # never change, the expanded CPU model will be the same, independant of # independent of QEMU version, machine type, machine options, and # accelerator options. Therefore, the resulting model can be used by # tooling without having to specify a compatibility machine - e.g. when # displaying the "host" model. static CPU models are migration-safe. # # @full: Expand all properties. The produced model is not guaranteed to be # migration-safe, but allows tooling to get an insight and work with # model details. # # Note: When a non-migration-safe CPU model is expanded in static mode, some # features enabled by the CPU model may be omitted, because they can't be # implemented by a static CPU model definition (e.g. cache info passthrough and # PMU passthrough in x86). If you need an accurate representation of the # features enabled by a non-migration-safe CPU model, use @full. If you need a # static representation that will keep ABI compatibility even when changing QEMU # version or machine-type, use @static (but keep in mind that some features may # be omitted). # # Since: 2.8.0 ## { 'enum': 'CpuModelExpansionType', 'data': [ 'static', 'full' ] } ## # @CpuModelExpansionInfo: # # The result of a cpu model expansion. # # @model: the expanded CpuModelInfo. # # Since: 2.8.0 ## { 'struct': 'CpuModelExpansionInfo', 'data': { 'model': 'CpuModelInfo' } } ## # @query-cpu-model-expansion: # # Expands a given CPU model (or a combination of CPU model + additional options) # to different granularities, allowing tooling to get an understanding what a # specific CPU model looks like in QEMU under a certain configuration. # # This interface can be used to query the "host" CPU model. # # The data returned by this command may be affected by: # # * QEMU version: CPU models may look different depending on the QEMU version. # (Except for CPU models reported as "static" in query-cpu-definitions.) # * machine-type: CPU model may look different depending on the machine-type. # (Except for CPU models reported as "static" in query-cpu-definitions.) # * machine options (including accelerator): in some architectures, CPU models # may look different depending on machine and accelerator options. (Except for # CPU models reported as "static" in query-cpu-definitions.) # * "-cpu" arguments and global properties: arguments to the -cpu option and # global properties may affect expansion of CPU models. Using # query-cpu-model-expansion while using these is not advised. # # Some architectures may not support all expansion types. s390x supports # "full" and "static". # # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is # not supported, if the model cannot be expanded, if the model contains # an unknown CPU definition name, unknown properties or properties # with a wrong type. Also returns an error if an expansion type is # not supported. # # Since: 2.8.0 ## { 'command': 'query-cpu-model-expansion', 'data': { 'type': 'CpuModelExpansionType', 'model': 'CpuModelInfo' }, 'returns': 'CpuModelExpansionInfo' } ## # @CpuModelCompareResult: # # An enumeration of CPU model comparation results. The result is usually # calculated using e.g. CPU features or CPU generations. # # @incompatible: If model A is incompatible to model B, model A is not # guaranteed to run where model B runs and the other way around. # # @identical: If model A is identical to model B, model A is guaranteed to run # where model B runs and the other way around. # # @superset: If model A is a superset of model B, model B is guaranteed to run # where model A runs. There are no guarantees about the other way. # # @subset: If model A is a subset of model B, model A is guaranteed to run # where model B runs. There are no guarantees about the other way. # # Since: 2.8.0 ## { 'enum': 'CpuModelCompareResult', 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } ## # @CpuModelCompareInfo: # # The result of a CPU model comparison. # # @result: The result of the compare operation. # @responsible-properties: List of properties that led to the comparison result # not being identical. # # @responsible-properties is a list of QOM property names that led to # both CPUs not being detected as identical. For identical models, this # list is empty. # If a QOM property is read-only, that means there's no known way to make the # CPU models identical. If the special property name "type" is included, the # models are by definition not identical and cannot be made identical. # # Since: 2.8.0 ## { 'struct': 'CpuModelCompareInfo', 'data': {'result': 'CpuModelCompareResult', 'responsible-properties': ['str'] } } ## # @query-cpu-model-comparison: # # Compares two CPU models, returning how they compare in a specific # configuration. The results indicates how both models compare regarding # runnability. This result can be used by tooling to make decisions if a # certain CPU model will run in a certain configuration or if a compatible # CPU model has to be created by baselining. # # Usually, a CPU model is compared against the maximum possible CPU model # of a certain configuration (e.g. the "host" model for KVM). If that CPU # model is identical or a subset, it will run in that configuration. # # The result returned by this command may be affected by: # # * QEMU version: CPU models may look different depending on the QEMU version. # (Except for CPU models reported as "static" in query-cpu-definitions.) # * machine-type: CPU model may look different depending on the machine-type. # (Except for CPU models reported as "static" in query-cpu-definitions.) # * machine options (including accelerator): in some architectures, CPU models # may look different depending on machine and accelerator options. (Except for # CPU models reported as "static" in query-cpu-definitions.) # * "-cpu" arguments and global properties: arguments to the -cpu option and # global properties may affect expansion of CPU models. Using # query-cpu-model-expansion while using these is not advised. # # Some architectures may not support comparing CPU models. s390x supports # comparing CPU models. # # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is # not supported, if a model cannot be used, if a model contains # an unknown cpu definition name, unknown properties or properties # with wrong types. # # Since: 2.8.0 ## { 'command': 'query-cpu-model-comparison', 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 'returns': 'CpuModelCompareInfo' } ## # @CpuModelBaselineInfo: # # The result of a CPU model baseline. # # @model: the baselined CpuModelInfo. # # Since: 2.8.0 ## { 'struct': 'CpuModelBaselineInfo', 'data': { 'model': 'CpuModelInfo' } } ## # @query-cpu-model-baseline: # # Baseline two CPU models, creating a compatible third model. The created # model will always be a static, migration-safe CPU model (see "static" # CPU model expansion for details). # # This interface can be used by tooling to create a compatible CPU model out # two CPU models. The created CPU model will be identical to or a subset of # both CPU models when comparing them. Therefore, the created CPU model is # guaranteed to run where the given CPU models run. # # The result returned by this command may be affected by: # # * QEMU version: CPU models may look different depending on the QEMU version. # (Except for CPU models reported as "static" in query-cpu-definitions.) # * machine-type: CPU model may look different depending on the machine-type. # (Except for CPU models reported as "static" in query-cpu-definitions.) # * machine options (including accelerator): in some architectures, CPU models # may look different depending on machine and accelerator options. (Except for # CPU models reported as "static" in query-cpu-definitions.) # * "-cpu" arguments and global properties: arguments to the -cpu option and # global properties may affect expansion of CPU models. Using # query-cpu-model-expansion while using these is not advised. # # Some architectures may not support baselining CPU models. s390x supports # baselining CPU models. # # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is # not supported, if a model cannot be used, if a model contains # an unknown cpu definition name, unknown properties or properties # with wrong types. # # Since: 2.8.0 ## { 'command': 'query-cpu-model-baseline', 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 'returns': 'CpuModelBaselineInfo' } ## # @AddfdInfo: # # Information about a file descriptor that was added to an fd set. # # @fdset-id: The ID of the fd set that @fd was added to. # # @fd: The file descriptor that was received via SCM rights and # added to the fd set. # # Since: 1.2.0 ## { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} } ## # @add-fd: # # Add a file descriptor, that was passed via SCM rights, to an fd set. # # @fdset-id: The ID of the fd set to add the file descriptor to. # # @opaque: A free-form string that can be used to describe the fd. # # Returns: @AddfdInfo on success # # If file descriptor was not received, FdNotSupplied # # If @fdset-id is a negative value, InvalidParameterValue # # Notes: The list of fd sets is shared by all monitor connections. # # If @fdset-id is not specified, a new fd set will be created. # # Since: 1.2.0 # # Example: # # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } # <- { "return": { "fdset-id": 1, "fd": 3 } } # ## { 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'}, 'returns': 'AddfdInfo' } ## # @remove-fd: # # Remove a file descriptor from an fd set. # # @fdset-id: The ID of the fd set that the file descriptor belongs to. # # @fd: The file descriptor that is to be removed. # # Returns: Nothing on success # If @fdset-id or @fd is not found, FdNotFound # # Since: 1.2.0 # # Notes: The list of fd sets is shared by all monitor connections. # # If @fd is not specified, all file descriptors in @fdset-id # will be removed. # # Example: # # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } # <- { "return": {} } # ## { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} } ## # @FdsetFdInfo: # # Information about a file descriptor that belongs to an fd set. # # @fd: The file descriptor value. # # @opaque: A free-form string that can be used to describe the fd. # # Since: 1.2.0 ## { 'struct': 'FdsetFdInfo', 'data': {'fd': 'int', '*opaque': 'str'} } ## # @FdsetInfo: # # Information about an fd set. # # @fdset-id: The ID of the fd set. # # @fds: A list of file descriptors that belong to this fd set. # # Since: 1.2.0 ## { 'struct': 'FdsetInfo', 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} } ## # @query-fdsets: # # Return information describing all fd sets. # # Returns: A list of @FdsetInfo # # Since: 1.2.0 # # Note: The list of fd sets is shared by all monitor connections. # # Example: # # -> { "execute": "query-fdsets" } # <- { "return": [ # { # "fds": [ # { # "fd": 30, # "opaque": "rdonly:/path/to/file" # }, # { # "fd": 24, # "opaque": "rdwr:/path/to/file" # } # ], # "fdset-id": 1 # }, # { # "fds": [ # { # "fd": 28 # }, # { # "fd": 29 # } # ], # "fdset-id": 0 # } # ] # } # ## { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] } ## # @TargetInfo: # # Information describing the QEMU target. # # @arch: the target architecture (eg "x86_64", "i386", etc) # # Since: 1.2.0 ## { 'struct': 'TargetInfo', 'data': { 'arch': 'str' } } ## # @query-target: # # Return information about the target for this QEMU # # Returns: TargetInfo # # Since: 1.2.0 ## { 'command': 'query-target', 'returns': 'TargetInfo' } ## # @AcpiTableOptions: # # Specify an ACPI table on the command line to load. # # At most one of @file and @data can be specified. The list of files specified # by any one of them is loaded and concatenated in order. If both are omitted, # @data is implied. # # Other fields / optargs can be used to override fields of the generic ACPI # table header; refer to the ACPI specification 5.0, section 5.2.6 System # Description Table Header. If a header field is not overridden, then the # corresponding value from the concatenated blob is used (in case of @file), or # it is filled in with a hard-coded value (in case of @data). # # String fields are copied into the matching ACPI member from lowest address # upwards, and silently truncated / NUL-padded to length. # # @sig: table signature / identifier (4 bytes) # # @rev: table revision number (dependent on signature, 1 byte) # # @oem_id: OEM identifier (6 bytes) # # @oem_table_id: OEM table identifier (8 bytes) # # @oem_rev: OEM-supplied revision number (4 bytes) # # @asl_compiler_id: identifier of the utility that created the table # (4 bytes) # # @asl_compiler_rev: revision number of the utility that created the # table (4 bytes) # # @file: colon (:) separated list of pathnames to load and # concatenate as table data. The resultant binary blob is expected to # have an ACPI table header. At least one file is required. This field # excludes @data. # # @data: colon (:) separated list of pathnames to load and # concatenate as table data. The resultant binary blob must not have an # ACPI table header. At least one file is required. This field excludes # @file. # # Since: 1.5 ## { 'struct': 'AcpiTableOptions', 'data': { '*sig': 'str', '*rev': 'uint8', '*oem_id': 'str', '*oem_table_id': 'str', '*oem_rev': 'uint32', '*asl_compiler_id': 'str', '*asl_compiler_rev': 'uint32', '*file': 'str', '*data': 'str' }} ## # @CommandLineParameterType: # # Possible types for an option parameter. # # @string: accepts a character string # # @boolean: accepts "on" or "off" # # @number: accepts a number # # @size: accepts a number followed by an optional suffix (K)ilo, # (M)ega, (G)iga, (T)era # # Since: 1.5 ## { 'enum': 'CommandLineParameterType', 'data': ['string', 'boolean', 'number', 'size'] } ## # @CommandLineParameterInfo: # # Details about a single parameter of a command line option. # # @name: parameter name # # @type: parameter @CommandLineParameterType # # @help: human readable text string, not suitable for parsing. # # @default: default value string (since 2.1) # # Since: 1.5 ## { 'struct': 'CommandLineParameterInfo', 'data': { 'name': 'str', 'type': 'CommandLineParameterType', '*help': 'str', '*default': 'str' } } ## # @CommandLineOptionInfo: # # Details about a command line option, including its list of parameter details # # @option: option name # # @parameters: an array of @CommandLineParameterInfo # # Since: 1.5 ## { 'struct': 'CommandLineOptionInfo', 'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } } ## # @query-command-line-options: # # Query command line option schema. # # @option: option name # # Returns: list of @CommandLineOptionInfo for all options (or for the given # @option). Returns an error if the given @option doesn't exist. # # Since: 1.5 # # Example: # # -> { "execute": "query-command-line-options", # "arguments": { "option": "option-rom" } } # <- { "return": [ # { # "parameters": [ # { # "name": "romfile", # "type": "string" # }, # { # "name": "bootindex", # "type": "number" # } # ], # "option": "option-rom" # } # ] # } # ## {'command': 'query-command-line-options', 'data': { '*option': 'str' }, 'returns': ['CommandLineOptionInfo'] } ## # @X86CPURegister32: # # A X86 32-bit register # # Since: 1.5 ## { 'enum': 'X86CPURegister32', 'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] } ## # @X86CPUFeatureWordInfo: # # Information about a X86 CPU feature word # # @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word # # @cpuid-input-ecx: Input ECX value for CPUID instruction for that # feature word # # @cpuid-register: Output register containing the feature bits # # @features: value of output register, containing the feature bits # # Since: 1.5 ## { 'struct': 'X86CPUFeatureWordInfo', 'data': { 'cpuid-input-eax': 'int', '*cpuid-input-ecx': 'int', 'cpuid-register': 'X86CPURegister32', 'features': 'int' } } ## # @DummyForceArrays: # # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally # # Since: 2.5 ## { 'struct': 'DummyForceArrays', 'data': { 'unused': ['X86CPUFeatureWordInfo'] } } ## # @NumaOptionsType: # # @node: NUMA nodes configuration # # @dist: NUMA distance configuration (since 2.10) # # @cpu: property based CPU(s) to node mapping (Since: 2.10) # # Since: 2.1 ## { 'enum': 'NumaOptionsType', 'data': [ 'node', 'dist', 'cpu' ] } ## # @NumaOptions: # # A discriminated record of NUMA options. (for OptsVisitor) # # Since: 2.1 ## { 'union': 'NumaOptions', 'base': { 'type': 'NumaOptionsType' }, 'discriminator': 'type', 'data': { 'node': 'NumaNodeOptions', 'dist': 'NumaDistOptions', 'cpu': 'NumaCpuOptions' }} ## # @NumaNodeOptions: # # Create a guest NUMA node. (for OptsVisitor) # # @nodeid: NUMA node ID (increase by 1 from 0 if omitted) # # @cpus: VCPUs belonging to this node (assign VCPUS round-robin # if omitted) # # @mem: memory size of this node; mutually exclusive with @memdev. # Equally divide total memory among nodes if both @mem and @memdev are # omitted. # # @memdev: memory backend object. If specified for one node, # it must be specified for all nodes. # # Since: 2.1 ## { 'struct': 'NumaNodeOptions', 'data': { '*nodeid': 'uint16', '*cpus': ['uint16'], '*mem': 'size', '*memdev': 'str' }} ## # @NumaDistOptions: # # Set the distance between 2 NUMA nodes. # # @src: source NUMA node. # # @dst: destination NUMA node. # # @val: NUMA distance from source node to destination node. # When a node is unreachable from another node, set the distance # between them to 255. # # Since: 2.10 ## { 'struct': 'NumaDistOptions', 'data': { 'src': 'uint16', 'dst': 'uint16', 'val': 'uint8' }} ## # @NumaCpuOptions: # # Option "-numa cpu" overrides default cpu to node mapping. # It accepts the same set of cpu properties as returned by # query-hotpluggable-cpus[].props, where node-id could be used to # override default node mapping. # # Since: 2.10 ## { 'struct': 'NumaCpuOptions', 'base': 'CpuInstanceProperties', 'data' : {} } ## # @HostMemPolicy: # # Host memory policy types # # @default: restore default policy, remove any nondefault policy # # @preferred: set the preferred host nodes for allocation # # @bind: a strict policy that restricts memory allocation to the # host nodes specified # # @interleave: memory allocations are interleaved across the set # of host nodes specified # # Since: 2.1 ## { 'enum': 'HostMemPolicy', 'data': [ 'default', 'preferred', 'bind', 'interleave' ] } ## # @Memdev: # # Information about memory backend # # @id: backend's ID if backend has 'id' property (since 2.9) # # @size: memory backend size # # @merge: enables or disables memory merge support # # @dump: includes memory backend's memory in a core dump or not # # @prealloc: enables or disables memory preallocation # # @host-nodes: host nodes for its memory policy # # @policy: memory policy of memory backend # # Since: 2.1 ## { 'struct': 'Memdev', 'data': { '*id': 'str', 'size': 'size', 'merge': 'bool', 'dump': 'bool', 'prealloc': 'bool', 'host-nodes': ['uint16'], 'policy': 'HostMemPolicy' }} ## # @query-memdev: # # Returns information for all memory backends. # # Returns: a list of @Memdev. # # Since: 2.1 # # Example: # # -> { "execute": "query-memdev" } # <- { "return": [ # { # "id": "mem1", # "size": 536870912, # "merge": false, # "dump": true, # "prealloc": false, # "host-nodes": [0, 1], # "policy": "bind" # }, # { # "size": 536870912, # "merge": false, # "dump": true, # "prealloc": true, # "host-nodes": [2, 3], # "policy": "preferred" # } # ] # } # ## { 'command': 'query-memdev', 'returns': ['Memdev'] } ## # @PCDIMMDeviceInfo: # # PCDIMMDevice state information # # @id: device's ID # # @addr: physical address, where device is mapped # # @size: size of memory that the device provides # # @slot: slot number at which device is plugged in # # @node: NUMA node number where device is plugged in # # @memdev: memory backend linked with device # # @hotplugged: true if device was hotplugged # # @hotpluggable: true if device if could be added/removed while machine is running # # Since: 2.1 ## { 'struct': 'PCDIMMDeviceInfo', 'data': { '*id': 'str', 'addr': 'int', 'size': 'int', 'slot': 'int', 'node': 'int', 'memdev': 'str', 'hotplugged': 'bool', 'hotpluggable': 'bool' } } ## # @MemoryDeviceInfo: # # Union containing information about a memory device # # Since: 2.1 ## { 'union': 'MemoryDeviceInfo', 'data': {'dimm': 'PCDIMMDeviceInfo'} } ## # @query-memory-devices: # # Lists available memory devices and their state # # Since: 2.1 # # Example: # # -> { "execute": "query-memory-devices" } # <- { "return": [ { "data": # { "addr": 5368709120, # "hotpluggable": true, # "hotplugged": true, # "id": "d1", # "memdev": "/objects/memX", # "node": 0, # "size": 1073741824, # "slot": 0}, # "type": "dimm" # } ] } # ## { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } ## # @MEM_UNPLUG_ERROR: # # Emitted when memory hot unplug error occurs. # # @device: device name # # @msg: Informative message # # Since: 2.4 # # Example: # # <- { "event": "MEM_UNPLUG_ERROR" # "data": { "device": "dimm1", # "msg": "acpi: device unplug for unsupported device" # }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'MEM_UNPLUG_ERROR', 'data': { 'device': 'str', 'msg': 'str' } } ## # @ACPISlotType: # # @DIMM: memory slot # @CPU: logical CPU slot (since 2.7) ## { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } ## # @ACPIOSTInfo: # # OSPM Status Indication for a device # For description of possible values of @source and @status fields # see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec. # # @device: device ID associated with slot # # @slot: slot ID, unique per slot of a given @slot-type # # @slot-type: type of the slot # # @source: an integer containing the source event # # @status: an integer containing the status code # # Since: 2.1 ## { 'struct': 'ACPIOSTInfo', 'data' : { '*device': 'str', 'slot': 'str', 'slot-type': 'ACPISlotType', 'source': 'int', 'status': 'int' } } ## # @query-acpi-ospm-status: # # Return a list of ACPIOSTInfo for devices that support status # reporting via ACPI _OST method. # # Since: 2.1 # # Example: # # -> { "execute": "query-acpi-ospm-status" } # <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, # { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, # { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, # { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} # ]} # ## { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } ## # @ACPI_DEVICE_OST: # # Emitted when guest executes ACPI _OST method. # # @info: ACPIOSTInfo type as described in qapi-schema.json # # Since: 2.1 # # Example: # # <- { "event": "ACPI_DEVICE_OST", # "data": { "device": "d1", "slot": "0", # "slot-type": "DIMM", "source": 1, "status": 0 } } # ## { 'event': 'ACPI_DEVICE_OST', 'data': { 'info': 'ACPIOSTInfo' } } ## # @rtc-reset-reinjection: # # This command will reset the RTC interrupt reinjection backlog. # Can be used if another mechanism to synchronize guest time # is in effect, for example QEMU guest agent's guest-set-time # command. # # Since: 2.1 # # Example: # # -> { "execute": "rtc-reset-reinjection" } # <- { "return": {} } # ## { 'command': 'rtc-reset-reinjection' } ## # @RTC_CHANGE: # # Emitted when the guest changes the RTC time. # # @offset: offset between base RTC clock (as specified by -rtc base), and # new RTC clock value # # Note: This event is rate-limited. # # Since: 0.13.0 # # Example: # # <- { "event": "RTC_CHANGE", # "data": { "offset": 78 }, # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } # ## { 'event': 'RTC_CHANGE', 'data': { 'offset': 'int' } } ## # @ReplayMode: # # Mode of the replay subsystem. # # @none: normal execution mode. Replay or record are not enabled. # # @record: record mode. All non-deterministic data is written into the # replay log. # # @play: replay mode. Non-deterministic data required for system execution # is read from the log. # # Since: 2.5 ## { 'enum': 'ReplayMode', 'data': [ 'none', 'record', 'play' ] } ## # @xen-load-devices-state: # # Load the state of all devices from file. The RAM and the block devices # of the VM are not loaded by this command. # # @filename: the file to load the state of the devices from as binary # data. See xen-save-devices-state.txt for a description of the binary # format. # # Since: 2.7 # # Example: # # -> { "execute": "xen-load-devices-state", # "arguments": { "filename": "/tmp/resume" } } # <- { "return": {} } # ## { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } ## # @GICCapability: # # The struct describes capability for a specific GIC (Generic # Interrupt Controller) version. These bits are not only decided by # QEMU/KVM software version, but also decided by the hardware that # the program is running upon. # # @version: version of GIC to be described. Currently, only 2 and 3 # are supported. # # @emulated: whether current QEMU/hardware supports emulated GIC # device in user space. # # @kernel: whether current QEMU/hardware supports hardware # accelerated GIC device in kernel. # # Since: 2.6 ## { 'struct': 'GICCapability', 'data': { 'version': 'int', 'emulated': 'bool', 'kernel': 'bool' } } ## # @query-gic-capabilities: # # This command is ARM-only. It will return a list of GICCapability # objects that describe its capability bits. # # Returns: a list of GICCapability objects. # # Since: 2.6 # # Example: # # -> { "execute": "query-gic-capabilities" } # <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, # { "version": 3, "emulated": false, "kernel": true } ] } # ## { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] } ## # @CpuInstanceProperties: # # List of properties to be used for hotplugging a CPU instance, # it should be passed by management with device_add command when # a CPU is being hotplugged. # # @node-id: NUMA node ID the CPU belongs to # @socket-id: socket number within node/board the CPU belongs to # @core-id: core number within socket the CPU belongs to # @thread-id: thread number within core the CPU belongs to # # Note: currently there are 4 properties that could be present # but management should be prepared to pass through other # properties with device_add command to allow for future # interface extension. This also requires the filed names to be kept in # sync with the properties passed to -device/device_add. # # Since: 2.7 ## { 'struct': 'CpuInstanceProperties', 'data': { '*node-id': 'int', '*socket-id': 'int', '*core-id': 'int', '*thread-id': 'int' } } ## # @HotpluggableCPU: # # @type: CPU object type for usage with device_add command # @props: list of properties to be used for hotplugging CPU # @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides # @qom-path: link to existing CPU object if CPU is present or # omitted if CPU is not present. # # Since: 2.7 ## { 'struct': 'HotpluggableCPU', 'data': { 'type': 'str', 'vcpus-count': 'int', 'props': 'CpuInstanceProperties', '*qom-path': 'str' } } ## # @query-hotpluggable-cpus: # # Returns: a list of HotpluggableCPU objects. # # Since: 2.7 # # Example: # # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ # { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core", # "vcpus-count": 1 }, # { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core", # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} # ]}' # # For pc machine type started with -smp 1,maxcpus=2: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ # { # "type": "qemu64-x86_64-cpu", "vcpus-count": 1, # "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} # }, # { # "qom-path": "/machine/unattached/device[0]", # "type": "qemu64-x86_64-cpu", "vcpus-count": 1, # "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} # } # ]} # ## { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'] } ## # @GuidInfo: # # GUID information. # # @guid: the globally unique identifier # # Since: 2.9 ## { 'struct': 'GuidInfo', 'data': {'guid': 'str'} } ## # @query-vm-generation-id: # # Show Virtual Machine Generation ID # # Since 2.9 ## { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' }