qemu/qapi-schema.json
Laszlo Ersek 14aa0c2de0 qapi schema: add Netdev types
NetdevTapOptions::sndbuf and NetdevDumpOptions::len use the new "size"
type.

v1->v2:
- NetLegacy::name is optional
- NetLegacyNicOptions::vectors is of type uint32
- NetdevVdeOptions::port and ::mode are of type uint16
- NetLegacy::vlan has type int32

v2->v3:
- NetLegacy::id is allowed and takes precedence over NetLegacy::name
- replace "@traits" with "@opts" in NetLegacy & Netdev descriptions

Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>
2012-07-23 11:55:18 +01:00

2186 lines
60 KiB
Python

# -*- Mode: Python -*-
#
# QAPI Schema
##
# @NameInfo:
#
# Guest name information.
#
# @name: #optional The name of the guest
#
# Since 0.14.0
##
{ 'type': 'NameInfo', 'data': {'*name': 'str'} }
##
# @query-name:
#
# Return the name information of a guest.
#
# Returns: @NameInfo of the guest
#
# Since 0.14.0
##
{ 'command': 'query-name', 'returns': 'NameInfo' }
##
# @VersionInfo:
#
# A description of QEMU's version.
#
# @qemu.major: The major version of QEMU
#
# @qemu.minor: The minor version of QEMU
#
# @qemu.micro: The micro 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
##
{ 'type': 'VersionInfo',
'data': {'qemu': {'major': 'int', 'minor': 'int', 'micro': 'int'},
'package': 'str'} }
##
# @query-version:
#
# Returns the current version of QEMU.
#
# Returns: A @VersionInfo object describing the current version of QEMU.
#
# Since: 0.14.0
##
{ 'command': 'query-version', 'returns': 'VersionInfo' }
##
# @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
##
{ 'type': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
##
# @query-kvm:
#
# Returns information about KVM acceleration
#
# Returns: @KvmInfo
#
# Since: 0.14.0
##
{ 'command': 'query-kvm', 'returns': 'KvmInfo' }
##
# @RunState
#
# An enumation of VM run states.
#
# @debug: QEMU is running on a debugger
#
# @finish-migrate: guest is paused to finish the migration process
#
# @inmigrate: guest is paused waiting for an incoming migration
#
# @internal-error: An internal error that prevents further guest execution
# has occurred
#
# @io-error: the last IOP has failed and the device is configured to pause
# on I/O errors
#
# @paused: guest has been paused via the 'stop' command
#
# @postmigrate: guest is paused following a successful 'migrate'
#
# @prelaunch: QEMU was started with -S and guest has not started
#
# @restore-vm: guest is paused to restore VM state
#
# @running: guest is actively running
#
# @save-vm: guest is paused to save the VM state
#
# @shutdown: guest is shut down (and -no-shutdown is in use)
#
# @suspended: guest is suspended (ACPI S3)
#
# @watchdog: the watchdog action is configured to pause and has been triggered
##
{ 'enum': 'RunState',
'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
'running', 'save-vm', 'shutdown', 'suspended', 'watchdog' ] }
##
# @StatusInfo:
#
# Information about VCPU run state
#
# @running: true if all VCPUs are runnable, false if not runnable
#
# @singlestep: true if VCPUs are in single-step mode
#
# @status: the virtual machine @RunState
#
# Since: 0.14.0
#
# Notes: @singlestep is enabled through the GDB stub
##
{ 'type': 'StatusInfo',
'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
##
# @query-status:
#
# Query the run status of all VCPUs
#
# Returns: @StatusInfo reflecting all VCPUs
#
# Since: 0.14.0
##
{ 'command': 'query-status', 'returns': 'StatusInfo' }
##
# @UuidInfo:
#
# Guest UUID information.
#
# @UUID: the UUID of the guest
#
# Since: 0.14.0
#
# Notes: If no UUID was specified for the guest, a null UUID is returned.
##
{ 'type': 'UuidInfo', 'data': {'UUID': 'str'} }
##
# @query-uuid:
#
# Query the guest UUID information.
#
# Returns: The @UuidInfo for the guest
#
# Since 0.14.0
##
{ 'command': 'query-uuid', 'returns': 'UuidInfo' }
##
# @ChardevInfo:
#
# Information about a character device.
#
# @label: the label of the character device
#
# @filename: the filename of the character device
#
# Notes: @filename is encoded using the QEMU command line character device
# encoding. See the QEMU man page for details.
#
# Since: 0.14.0
##
{ 'type': 'ChardevInfo', 'data': {'label': 'str', 'filename': 'str'} }
##
# @query-chardev:
#
# Returns information about current character devices.
#
# Returns: a list of @ChardevInfo
#
# Since: 0.14.0
##
{ 'command': 'query-chardev', 'returns': ['ChardevInfo'] }
##
# @CommandInfo:
#
# Information about a QMP command
#
# @name: The command name
#
# Since: 0.14.0
##
{ 'type': '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
##
{ 'command': 'query-commands', 'returns': ['CommandInfo'] }
##
# @EventInfo:
#
# Information about a QMP event
#
# @name: The event name
#
# Since: 1.2.0
##
{ 'type': '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
##
{ 'command': 'query-events', 'returns': ['EventInfo'] }
##
# @MigrationStats
#
# Detailed migration status.
#
# @transferred: amount of bytes already transferred to the target VM
#
# @remaining: amount of bytes remaining to be transferred to the target VM
#
# @total: total amount of bytes involved in the migration process
#
# @total_time: tota0l amount of ms since migration started. If
# migration has ended, it returns the total migration
# time. (since 1.2)
#
# Since: 0.14.0.
##
{ 'type': 'MigrationStats',
'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
'total_time': 'int' } }
##
# @MigrationInfo
#
# Information about current migration process.
#
# @status: #optional string describing the current migration status.
# As of 0.14.0 this can be 'active', 'completed', 'failed' or
# 'cancelled'. If this field is not returned, no migration process
# has been initiated
#
# @ram: #optional @MigrationStats containing detailed migration
# status, only returned if status is 'active' or
# 'completed'. 'comppleted' (since 1.2)
#
# @disk: #optional @MigrationStats containing detailed disk migration
# status, only returned if status is 'active' and it is a block
# migration
#
# Since: 0.14.0
##
{ 'type': 'MigrationInfo',
'data': {'*status': 'str', '*ram': 'MigrationStats',
'*disk': 'MigrationStats'} }
##
# @query-migrate
#
# Returns information about current migration process.
#
# Returns: @MigrationInfo
#
# Since: 0.14.0
##
{ 'command': 'query-migrate', 'returns': 'MigrationInfo' }
##
# @MouseInfo:
#
# Information about a mouse device.
#
# @name: the name of the mouse device
#
# @index: the index of the mouse device
#
# @current: true if this device is currently receiving mouse events
#
# @absolute: true if this device supports absolute coordinates as input
#
# Since: 0.14.0
##
{ 'type': 'MouseInfo',
'data': {'name': 'str', 'index': 'int', 'current': 'bool',
'absolute': 'bool'} }
##
# @query-mice:
#
# Returns information about each active mouse device
#
# Returns: a list of @MouseInfo for each device
#
# Since: 0.14.0
##
{ 'command': 'query-mice', 'returns': ['MouseInfo'] }
##
# @CpuInfo:
#
# Information about a virtual CPU
#
# @CPU: the index of the virtual CPU
#
# @current: this only exists for backwards compatible 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.
#
# @pc: #optional If the target is i386 or x86_64, this is the 64-bit instruction
# pointer.
# If the target is Sparc, this is the PC component of the
# instruction pointer.
#
# @nip: #optional If the target is PPC, the instruction pointer
#
# @npc: #optional If the target is Sparc, the NPC component of the instruction
# pointer
#
# @PC: #optional If the target is MIPS, the instruction pointer
#
# @thread_id: ID of the underlying host thread
#
# 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.
##
{ 'type': 'CpuInfo',
'data': {'CPU': 'int', 'current': 'bool', 'halted': 'bool', '*pc': 'int',
'*nip': 'int', '*npc': 'int', '*PC': 'int', 'thread_id': 'int'} }
##
# @query-cpus:
#
# Returns a list of information about each virtual CPU.
#
# Returns: a list of @CpuInfo for each virtual CPU
#
# Since: 0.14.0
##
{ 'command': 'query-cpus', 'returns': ['CpuInfo'] }
##
# @BlockDeviceInfo:
#
# Information about the backing device for a block device.
#
# @file: the filename of the backing device
#
# @ro: true if the backing device was open read-only
#
# @drv: the name of the block format used to open the backing device. As of
# 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
# 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
# 'host_floppy', 'http', 'https', 'nbd', 'parallels', 'qcow',
# 'qcow2', 'raw', 'tftp', 'vdi', 'vmdk', 'vpc', 'vvfat'
#
# @backing_file: #optional the name of the backing file (for copy-on-write)
#
# @encrypted: true if the backing device is encrypted
#
# @bps: total throughput limit in bytes per second is specified
#
# @bps_rd: read throughput limit in bytes per second is specified
#
# @bps_wr: write throughput limit in bytes per second is specified
#
# @iops: total I/O operations per second is specified
#
# @iops_rd: read I/O operations per second is specified
#
# @iops_wr: write I/O operations per second is specified
#
# Since: 0.14.0
#
# Notes: This interface is only found in @BlockInfo.
##
{ 'type': 'BlockDeviceInfo',
'data': { 'file': 'str', 'ro': 'bool', 'drv': 'str',
'*backing_file': 'str', 'encrypted': 'bool',
'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int'} }
##
# @BlockDeviceIoStatus:
#
# An enumeration of block device I/O status.
#
# @ok: The last I/O operation has succeeded
#
# @failed: The last I/O operation has failed
#
# @nospace: The last I/O operation has failed due to a no-space condition
#
# Since: 1.0
##
{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
##
# @BlockInfo:
#
# Block device information. This structure describes a virtual device and
# the backing device associated with it.
#
# @device: The device name associated with the virtual device.
#
# @type: This field is returned only for compatibility reasons, it should
# not be used (always returns 'unknown')
#
# @removable: True if the device supports removable media.
#
# @locked: True if the guest has locked this device from having its media
# removed
#
# @tray_open: #optional True if the device has a tray and it is open
# (only present if removable is true)
#
# @io-status: #optional @BlockDeviceIoStatus. Only present if the device
# supports it and the VM is configured to stop on errors
#
# @inserted: #optional @BlockDeviceInfo describing the device if media is
# present
#
# Since: 0.14.0
##
{ 'type': 'BlockInfo',
'data': {'device': 'str', 'type': 'str', 'removable': 'bool',
'locked': 'bool', '*inserted': 'BlockDeviceInfo',
'*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus'} }
##
# @query-block:
#
# Get a list of BlockInfo for all virtual block devices.
#
# Returns: a list of @BlockInfo describing each virtual block device
#
# Since: 0.14.0
##
{ 'command': 'query-block', 'returns': ['BlockInfo'] }
##
# @BlockDeviceStats:
#
# Statistics of a virtual block device or a block backing device.
#
# @rd_bytes: The number of bytes read by the device.
#
# @wr_bytes: The number of bytes written by the device.
#
# @rd_operations: The number of read operations performed by the device.
#
# @wr_operations: The number of write operations performed by the device.
#
# @flush_operations: The number of cache flush operations performed by the
# device (since 0.15.0)
#
# @flush_total_time_ns: Total time spend on cache flushes in nano-seconds
# (since 0.15.0).
#
# @wr_total_time_ns: Total time spend on writes in nano-seconds (since 0.15.0).
#
# @rd_total_time_ns: Total_time_spend on reads in nano-seconds (since 0.15.0).
#
# @wr_highest_offset: The offset after the greatest byte written to the
# device. The intended use of this information is for
# growable sparse files (like qcow2) that are used on top
# of a physical device.
#
# Since: 0.14.0
##
{ 'type': 'BlockDeviceStats',
'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'rd_operations': 'int',
'wr_operations': 'int', 'flush_operations': 'int',
'flush_total_time_ns': 'int', 'wr_total_time_ns': 'int',
'rd_total_time_ns': 'int', 'wr_highest_offset': 'int' } }
##
# @BlockStats:
#
# Statistics of a virtual block device or a block backing device.
#
# @device: #optional If the stats are for a virtual block device, the name
# corresponding to the virtual block device.
#
# @stats: A @BlockDeviceStats for the device.
#
# @parent: #optional This may point to the backing block device if this is a
# a virtual block device. If it's a backing block, this will point
# to the backing file is one is present.
#
# Since: 0.14.0
##
{ 'type': 'BlockStats',
'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
'*parent': 'BlockStats'} }
##
# @query-blockstats:
#
# Query the @BlockStats for all virtual block devices.
#
# Returns: A list of @BlockStats for each virtual block devices.
#
# Since: 0.14.0
##
{ 'command': 'query-blockstats', 'returns': ['BlockStats'] }
##
# @VncClientInfo:
#
# Information about a connected VNC client.
#
# @host: The host name of the client. QEMU tries to resolve this to a DNS name
# when possible.
#
# @family: 'ipv6' if the client is connected via IPv6 and TCP
# 'ipv4' if the client is connected via IPv4 and TCP
# 'unix' if the client is connected via a unix domain socket
# 'unknown' otherwise
#
# @service: The service name of the client's port. This may depends on the
# host system's service database so symbolic names should not be
# relied on.
#
# @x509_dname: #optional If x509 authentication is in use, the Distinguished
# Name of the client.
#
# @sasl_username: #optional If SASL authentication is in use, the SASL username
# used for authentication.
#
# Since: 0.14.0
##
{ 'type': 'VncClientInfo',
'data': {'host': 'str', 'family': 'str', 'service': 'str',
'*x509_dname': 'str', '*sasl_username': 'str'} }
##
# @VncInfo:
#
# Information about the VNC session.
#
# @enabled: true if the VNC server is enabled, false otherwise
#
# @host: #optional The hostname the VNC server is bound to. This depends on
# the name resolution on the host and may be an IP address.
#
# @family: #optional 'ipv6' if the host is listening for IPv6 connections
# 'ipv4' if the host is listening for IPv4 connections
# 'unix' if the host is listening on a unix domain socket
# 'unknown' otherwise
#
# @service: #optional The service name of the server's port. This may depends
# on the host system's service database so symbolic names should not
# be relied on.
#
# @auth: #optional the current authentication type used by the server
# 'none' if no authentication is being used
# 'vnc' if VNC authentication is being used
# 'vencrypt+plain' if VEncrypt is used with plain text authentication
# 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
# 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
# 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
# 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
# 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
# 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
# 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
# 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
#
# @clients: a list of @VncClientInfo of all currently connected clients
#
# Since: 0.14.0
##
{ 'type': 'VncInfo',
'data': {'enabled': 'bool', '*host': 'str', '*family': 'str',
'*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']} }
##
# @query-vnc:
#
# Returns information about the current VNC server
#
# Returns: @VncInfo
# If VNC support is not compiled in, FeatureDisabled
#
# Since: 0.14.0
##
{ 'command': 'query-vnc', 'returns': 'VncInfo' }
##
# @SpiceChannel
#
# Information about a SPICE client channel.
#
# @host: The host name of the client. QEMU tries to resolve this to a DNS name
# when possible.
#
# @family: 'ipv6' if the client is connected via IPv6 and TCP
# 'ipv4' if the client is connected via IPv4 and TCP
# 'unix' if the client is connected via a unix domain socket
# 'unknown' otherwise
#
# @port: The client's port number.
#
# @connection-id: SPICE connection id number. All channels with the same id
# belong to the same SPICE session.
#
# @connection-type: SPICE channel type number. "1" is the main control
# channel, filter for this one if you want to track spice
# sessions only
#
# @channel-id: SPICE channel ID number. Usually "0", might be different when
# multiple channels of the same type exist, such as multiple
# display channels in a multihead setup
#
# @tls: true if the channel is encrypted, false otherwise.
#
# Since: 0.14.0
##
{ 'type': 'SpiceChannel',
'data': {'host': 'str', 'family': 'str', 'port': 'str',
'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
'tls': 'bool'} }
##
# @SpiceQueryMouseMode
#
# An enumation of Spice mouse states.
#
# @client: Mouse cursor position is determined by the client.
#
# @server: Mouse cursor position is determined by the server.
#
# @unknown: No information is available about mouse mode used by
# the spice server.
#
# Note: spice/enums.h has a SpiceMouseMode already, hence the name.
#
# Since: 1.1
##
{ 'enum': 'SpiceQueryMouseMode',
'data': [ 'client', 'server', 'unknown' ] }
##
# @SpiceInfo
#
# Information about the SPICE session.
#
# @enabled: true if the SPICE server is enabled, false otherwise
#
# @host: #optional The hostname the SPICE server is bound to. This depends on
# the name resolution on the host and may be an IP address.
#
# @port: #optional The SPICE server's port number.
#
# @compiled-version: #optional SPICE server version.
#
# @tls-port: #optional The SPICE server's TLS port number.
#
# @auth: #optional the current authentication type used by the server
# 'none' if no authentication is being used
# 'spice' uses SASL or direct TLS authentication, depending on command
# line options
#
# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
# be determined by the client or the server, or unknown if spice
# server doesn't provide this information.
#
# Since: 1.1
#
# @channels: a list of @SpiceChannel for each active spice channel
#
# Since: 0.14.0
##
{ 'type': 'SpiceInfo',
'data': {'enabled': 'bool', '*host': 'str', '*port': 'int',
'*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']} }
##
# @query-spice
#
# Returns information about the current SPICE server
#
# Returns: @SpiceInfo
#
# Since: 0.14.0
##
{ 'command': 'query-spice', 'returns': 'SpiceInfo' }
##
# @BalloonInfo:
#
# Information about the guest balloon device.
#
# @actual: the number of bytes the balloon currently contains
#
# @mem_swapped_in: #optional number of pages swapped in within the guest
#
# @mem_swapped_out: #optional number of pages swapped out within the guest
#
# @major_page_faults: #optional number of major page faults within the guest
#
# @minor_page_faults: #optional number of minor page faults within the guest
#
# @free_mem: #optional amount of memory (in bytes) free in the guest
#
# @total_mem: #optional amount of memory (in bytes) visible to the guest
#
# Since: 0.14.0
#
# Notes: all current versions of QEMU do not fill out optional information in
# this structure.
##
{ 'type': 'BalloonInfo',
'data': {'actual': 'int', '*mem_swapped_in': 'int',
'*mem_swapped_out': 'int', '*major_page_faults': 'int',
'*minor_page_faults': 'int', '*free_mem': 'int',
'*total_mem': '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
##
{ 'command': 'query-balloon', 'returns': 'BalloonInfo' }
##
# @PciMemoryRange:
#
# A PCI device memory region
#
# @base: the starting address (guest physical)
#
# @limit: the ending address (guest physical)
#
# Since: 0.14.0
##
{ 'type': '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
#
# @prefetch: #optional if @type is 'memory', true if the memory is prefetchable
#
# @mem_type_64: #optional if @type is 'memory', true if the BAR is 64-bit
#
# Since: 0.14.0
##
{ 'type': 'PciMemoryRegion',
'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
'*prefetch': 'bool', '*mem_type_64': 'bool' } }
##
# @PciBridgeInfo:
#
# Information about a PCI Bridge device
#
# @bus.number: primary bus interface number. This should be the number of the
# bus the device resides on.
#
# @bus.secondary: secondary bus interface number. This is the number of the
# main bus for the bridge
#
# @bus.subordinate: This is the highest number bus that resides below the
# bridge.
#
# @bus.io_range: The PIO range for all devices on this bridge
#
# @bus.memory_range: The MMIO range for all devices on this bridge
#
# @bus.prefetchable_range: The range of prefetchable MMIO for all devices on
# this bridge
#
# @devices: a list of @PciDeviceInfo for each device on this bridge
#
# Since: 0.14.0
##
{ 'type': 'PciBridgeInfo',
'data': {'bus': { 'number': 'int', 'secondary': 'int', 'subordinate': 'int',
'io_range': 'PciMemoryRange',
'memory_range': 'PciMemoryRange',
'prefetchable_range': 'PciMemoryRange' },
'*devices': ['PciDeviceInfo']} }
##
# @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.desc: #optional a string description of the device's class
#
# @class_info.class: the class code of the device
#
# @id.device: the PCI device id
#
# @id.vendor: the PCI vendor id
#
# @irq: #optional 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
##
{ 'type': 'PciDeviceInfo',
'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
'class_info': {'*desc': 'str', 'class': 'int'},
'id': {'device': 'int', 'vendor': 'int'},
'*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
##
{ 'type': '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
#
# Since: 0.14.0
##
{ 'command': 'query-pci', 'returns': ['PciInfo'] }
##
# @BlockJobInfo:
#
# Information about a long-running block device operation.
#
# @type: the job type ('stream' for image streaming)
#
# @device: the block device name
#
# @len: the maximum progress value
#
# @offset: the current progress value
#
# @speed: the rate limit, bytes per second
#
# Since: 1.1
##
{ 'type': 'BlockJobInfo',
'data': {'type': 'str', 'device': 'str', 'len': 'int',
'offset': 'int', 'speed': 'int'} }
##
# @query-block-jobs:
#
# Return information about long-running block device operations.
#
# Returns: a list of @BlockJobInfo for each active block job
#
# Since: 1.1
##
{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] }
##
# @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
##
{ '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
##
{ 'command': 'stop' }
##
# @system_reset:
#
# Performs a hard reset of a guest.
#
# Since: 0.14.0
##
{ '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.
##
{ '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'} }
##
# @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: #optional the index of the virtual CPU to use for translating the
# virtual address (defaults to CPU 0)
#
# Returns: Nothing on success
# If @cpu is not a valid VCPU, InvalidParameterValue
# If @filename cannot be opened, OpenFileFailed
# If an I/O error occurs while writing the file, IOError
#
# Since: 0.14.0
#
# Notes: Errors were not reliably returned until 1.1
##
{ '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
# If @filename cannot be opened, OpenFileFailed
# If an I/O error occurs while writing the file, IOError
#
# Since: 0.14.0
#
# Notes: Errors were not reliably returned until 1.1
##
{ 'command': 'pmemsave',
'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
##
# @cont:
#
# Resume guest VCPU execution.
#
# Since: 0.14.0
#
# Returns: If successful, nothing
# If the QEMU is waiting for an incoming migration, MigrationExpected
# If QEMU was started with an encrypted block device and a key has
# not yet been set, DeviceEncrypted.
#
# Notes: This command will succeed if the guest is currently running.
##
{ 'command': 'cont' }
##
# @system_wakeup:
#
# Wakeup guest from suspend. Does nothing in case the guest isn't suspended.
#
# Since: 1.1
#
# Returns: nothing.
##
{ 'command': 'system_wakeup' }
##
# @inject-nmi:
#
# Injects an Non-Maskable Interrupt into all guest's VCPUs.
#
# Returns: If successful, nothing
# If the Virtual Machine doesn't support NMI injection, Unsupported
#
# Since: 0.14.0
#
# Notes: Only x86 Virtual Machines support this command.
##
{ 'command': 'inject-nmi' }
##
# @set_link:
#
# Sets the link status of a virtual network adapter.
#
# @name: the device name of the virtual network adapter
#
# @up: true to set the link status to be up
#
# Returns: Nothing on success
# If @name is not a valid network device, DeviceNotFound
#
# Since: 0.14.0
#
# Notes: Not all network adapters support setting link status. This command
# will succeed even if the network adapter does not support link status
# notification.
##
{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
##
# @block_passwd:
#
# This command sets the password of a block device that has not been open
# with a password and requires one.
#
# The two cases where this can happen are a block device is created through
# QEMU's initial command line or a block device is changed through the legacy
# @change interface.
#
# In the event that the block device is created through the initial command
# line, the VM will start in the stopped state regardless of whether '-S' is
# used. The intention is for a management tool to query the block devices to
# determine which ones are encrypted, set the passwords with this command, and
# then start the guest with the @cont command.
#
# @device: the name of the device to set the password on
#
# @password: the password to use for the device
#
# Returns: nothing on success
# If @device is not a valid block device, DeviceNotFound
# If @device is not encrypted, DeviceNotEncrypted
# If @password is not valid for this device, InvalidPassword
#
# Notes: Not all block formats support encryption and some that do are not
# able to validate that a password is correct. Disk corruption may
# occur if an invalid password is specified.
#
# Since: 0.14.0
##
{ 'command': 'block_passwd', 'data': {'device': 'str', 'password': 'str'} }
##
# @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
##
{ 'command': 'balloon', 'data': {'value': 'int'} }
##
# @block_resize
#
# Resize a block image while a guest is running.
#
# @device: the name of the device to get the image resized
#
# @size: new image size in bytes
#
# Returns: nothing on success
# If @device is not a valid block device, DeviceNotFound
# If @size is negative, InvalidParameterValue
# If the block device has no medium inserted, DeviceHasNoMedium
# If the block device does not support resize, Unsupported
# If the block device is read-only, DeviceIsReadOnly
# If a long-running operation is using the device, DeviceInUse
#
# Since: 0.14.0
##
{ 'command': 'block_resize', 'data': { 'device': 'str', 'size': 'int' }}
##
# @NewImageMode
#
# An enumeration that tells QEMU how to set the backing file path in
# a new image file.
#
# @existing: QEMU should look for an existing image file.
#
# @absolute-paths: QEMU should create a new image with absolute paths
# for the backing file.
#
# Since: 1.1
##
{ 'enum': 'NewImageMode'
'data': [ 'existing', 'absolute-paths' ] }
##
# @BlockdevSnapshot
#
# @device: the name of the device to generate the snapshot from.
#
# @snapshot-file: the target of the new image. A new file will be created.
#
# @format: #optional the format of the snapshot image, default is 'qcow2'.
#
# @mode: #optional whether and how QEMU should create a new image, default is
# 'absolute-paths'.
##
{ 'type': 'BlockdevSnapshot',
'data': { 'device': 'str', 'snapshot-file': 'str', '*format': 'str',
'*mode': 'NewImageMode' } }
##
# @BlockdevAction
#
# A discriminated record of operations that can be performed with
# @transaction.
##
{ 'union': 'BlockdevAction',
'data': {
'blockdev-snapshot-sync': 'BlockdevSnapshot',
} }
##
# @transaction
#
# Atomically operate on a group of one or more block devices. If
# any operation fails, then the entire set of actions will be
# abandoned and the appropriate error returned. The only operation
# supported is currently blockdev-snapshot-sync.
#
# List of:
# @BlockdevAction: information needed for the device snapshot
#
# Returns: nothing on success
# If @device is not a valid block device, DeviceNotFound
# If @device is busy, DeviceInUse will be returned
# If @snapshot-file can't be created, OpenFileFailed
# If @snapshot-file can't be opened, OpenFileFailed
# If @format is invalid, InvalidBlockFormat
#
# Note: The transaction aborts on the first failure. Therefore, there will
# be only one device or snapshot file returned in an error condition, and
# subsequent actions will not have been attempted.
#
# Since 1.1
##
{ 'command': 'transaction',
'data': { 'actions': [ 'BlockdevAction' ] } }
##
# @blockdev-snapshot-sync
#
# Generates a synchronous snapshot of a block device.
#
# @device: the name of the device to generate the snapshot from.
#
# @snapshot-file: the target of the new image. If the file exists, or if it
# is a device, the snapshot will be created in the existing
# file/device. If does not exist, a new file will be created.
#
# @format: #optional the format of the snapshot image, default is 'qcow2'.
#
# @mode: #optional whether and how QEMU should create a new image, default is
# 'absolute-paths'.
#
# Returns: nothing on success
# If @device is not a valid block device, DeviceNotFound
# If @snapshot-file can't be opened, OpenFileFailed
# If @format is invalid, InvalidBlockFormat
#
# Since 0.14.0
##
{ 'command': 'blockdev-snapshot-sync',
'data': { 'device': 'str', 'snapshot-file': 'str', '*format': 'str',
'*mode': 'NewImageMode'} }
##
# @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: #optional 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. It's use is highly
# discouraged. The semantics of this command are not guaranteed.
#
# Known limitations:
#
# o This command is stateless, this means that commands that depend
# on state information (such as getfd) might not work
#
# o Commands that prompt the user for data (eg. 'cont' when the block
# device is encrypted) don't currently work
##
{ 'command': 'human-monitor-command',
'data': {'command-line': 'str', '*cpu-index': 'int'},
'returns': 'str' }
##
# @migrate_cancel
#
# Cancel the current executing migration process.
#
# Returns: nothing on success
#
# Notes: This command succeeds even if there is no migration process running.
#
# Since: 0.14.0
##
{ 'command': 'migrate_cancel' }
##
# @migrate_set_downtime
#
# Set maximum tolerated downtime for migration.
#
# @value: maximum downtime in seconds
#
# Returns: nothing on success
#
# Since: 0.14.0
##
{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
##
# @migrate_set_speed
#
# Set maximum speed for migration.
#
# @value: maximum speed in bytes.
#
# Returns: nothing on success
#
# Notes: A value lesser than zero will be automatically round up to zero.
#
# Since: 0.14.0
##
{ 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
##
# @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 legacy type in the form 'legacy<subtype>' where subtype is the
# legacy qdev typename. These types are always treated as strings.
#
# 3) A child type in the form 'child<subtype>' where subtype is a qdev
# device type name. Child properties create the composition tree.
#
# 4) 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.1
#
# Notes: This type is experimental. Its syntax may change in future releases.
##
{ 'type': '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.1
#
# Notes: This command is experimental. It's syntax may change in future
# releases.
##
{ '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. legacy<>
# properties are returned as #str. child<> and link<> properties are
# returns as #str pathnames. All integer property types (u8, u16, etc)
# are returned as #int.
#
# Since: 1.1
#
# Notes: This command is experimental and may change syntax in future releases.
##
{ 'command': 'qom-get',
'data': { 'path': 'str', 'property': 'str' },
'returns': 'visitor',
'gen': 'no' }
##
# @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.1
#
# Notes: This command is experimental and may change syntax in future releases.
##
{ 'command': 'qom-set',
'data': { 'path': 'str', 'property': 'str', 'value': 'visitor' },
'gen': 'no' }
##
# @set_password:
#
# Sets the password of a remote display session.
#
# @protocol: `vnc' to modify the VNC server password
# `spice' to modify the Spice server password
#
# @password: the new password
#
# @connected: #optional how to handle existing clients when changing the
# password. If nothing is specified, defaults to `keep'
# `fail' to fail the command if clients are connected
# `disconnect' to disconnect existing clients
# `keep' to maintain existing clients
#
# Returns: Nothing on success
# If Spice is not enabled, DeviceNotFound
# If @protocol does not support connected, InvalidParameter
# If @protocol is invalid, InvalidParameter
# If any other error occurs, SetPasswdFailed
#
# Notes: If VNC is not enabled, SetPasswdFailed is returned.
#
# Since: 0.14.0
##
{ 'command': 'set_password',
'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
##
# @expire_password:
#
# Expire the password of a remote display server.
#
# @protocol: the name of the remote display protocol `vnc' or `spice'
#
# @time: when to expire the password.
# `now' to expire the password immediately
# `never' to cancel password expiration
# `+INT' where INT is the number of seconds from now (integer)
# `INT' where INT is the absolute time in seconds
#
# Returns: Nothing on success
# If @protocol is `spice' and Spice is not active, DeviceNotFound
# If an error occurs setting password expiration, SetPasswdFailed
# If @protocol is not `spice' or 'vnc', InvalidParameter
#
# Since: 0.14.0
#
# Notes: Time is relative to the server and currently there is no way to
# coordinate server time with client time. It is not recommended to
# use the absolute time version of the @time parameter unless you're
# sure you are on the same machine as the QEMU instance.
##
{ 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
##
# @eject:
#
# Ejects a device from a removable drive.
#
# @device: The name of the device
#
# @force: @optional If true, eject regardless of whether the drive is locked.
# If not specified, the default value is false.
#
# Returns: Nothing on success
# If @device is not a valid block device, DeviceNotFound
# If @device is not removable and @force is false, DeviceNotRemovable
# If @force is false and @device is locked, DeviceLocked
#
# Notes: Ejecting a device will no media results in success
#
# Since: 0.14.0
##
{ 'command': 'eject', 'data': {'device': 'str', '*force': 'bool'} }
##
# @change-vnc-password:
#
# Change the VNC server password.
#
# @target: the new password to use with VNC authentication
#
# Since: 1.1
#
# Notes: An empty password in this command will set the password to the empty
# string. Existing clients are unaffected by executing this command.
##
{ 'command': 'change-vnc-password', 'data': {'password': 'str'} }
##
# @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. If this argument is an empty string, then no future
# logins will be allowed.
#
# Returns: Nothing on success.
# If @device is not a valid block device, DeviceNotFound
# If @format is not a valid block format, InvalidBlockFormat
# If the new block device is encrypted, DeviceEncrypted. Note that
# if this error is returned, the device has been opened successfully
# and an additional call to @block_passwd is required to set the
# device's password. The behavior of reads and writes to the block
# device between when these calls are executed is undefined.
#
# Notes: It is strongly recommended that this interface is not used especially
# for changing block devices.
#
# Since: 0.14.0
##
{ 'command': 'change',
'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
##
# @block_set_io_throttle:
#
# Change I/O throttle limits for a block drive.
#
# @device: The name of the device
#
# @bps: total throughput limit in bytes per second
#
# @bps_rd: read throughput limit in bytes per second
#
# @bps_wr: write throughput limit in bytes per second
#
# @iops: total I/O operations per second
#
# @ops_rd: read I/O operations per second
#
# @iops_wr: write I/O operations per second
#
# Returns: Nothing on success
# If @device is not a valid block device, DeviceNotFound
# If the argument combination is invalid, InvalidParameterCombination
#
# Since: 1.1
##
{ 'command': 'block_set_io_throttle',
'data': { 'device': 'str', 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int' } }
##
# @block-stream:
#
# Copy data from a backing file into a block device.
#
# The block streaming operation is performed in the background until the entire
# backing file has been copied. This command returns immediately once streaming
# has started. The status of ongoing block streaming operations can be checked
# with query-block-jobs. The operation can be stopped before it has completed
# using the block-job-cancel command.
#
# If a base file is specified then sectors are not copied from that base file and
# its backing chain. When streaming completes the image file will have the base
# file as its backing file. This can be used to stream a subset of the backing
# file chain instead of flattening the entire image.
#
# On successful completion the image file is updated to drop the backing file
# and the BLOCK_JOB_COMPLETED event is emitted.
#
# @device: the device name
#
# @base: #optional the common backing file name
#
# @speed: #optional the maximum speed, in bytes per second
#
# Returns: Nothing on success
# If streaming is already active on this device, DeviceInUse
# If @device does not exist, DeviceNotFound
# If image streaming is not supported by this device, NotSupported
# If @base does not exist, BaseNotFound
# If @speed is invalid, InvalidParameter
#
# Since: 1.1
##
{ 'command': 'block-stream', 'data': { 'device': 'str', '*base': 'str',
'*speed': 'int' } }
##
# @block-job-set-speed:
#
# Set maximum speed for a background block operation.
#
# This command can only be issued when there is an active block job.
#
# Throttling can be disabled by setting the speed to 0.
#
# @device: the device name
#
# @speed: the maximum speed, in bytes per second, or 0 for unlimited.
# Defaults to 0.
#
# Returns: Nothing on success
# If the job type does not support throttling, NotSupported
# If the speed value is invalid, InvalidParameter
# If streaming is not active on this device, DeviceNotActive
#
# Since: 1.1
##
{ 'command': 'block-job-set-speed',
'data': { 'device': 'str', 'speed': 'int' } }
##
# @block-job-cancel:
#
# Stop an active block streaming operation.
#
# This command returns immediately after marking the active block streaming
# operation for cancellation. It is an error to call this command if no
# operation is in progress.
#
# The operation will cancel as soon as possible and then emit the
# BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when
# enumerated using query-block-jobs.
#
# The image file retains its backing file unless the streaming operation happens
# to complete just as it is being cancelled.
#
# A new block streaming operation can be started at a later time to finish
# copying all data from the backing file.
#
# @device: the device name
#
# Returns: Nothing on success
# If streaming is not active on this device, DeviceNotActive
# If cancellation already in progress, DeviceInUse
#
# Since: 1.1
##
{ 'command': 'block-job-cancel', 'data': { 'device': 'str' } }
##
# @ObjectTypeInfo:
#
# This structure describes a search result from @qom-list-types
#
# @name: the type name found in the search
#
# Since: 1.1
#
# Notes: This command is experimental and may change syntax in future releases.
##
{ 'type': 'ObjectTypeInfo',
'data': { 'name': '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
#
# Notes: This command is experimental and may change syntax in future releases.
##
{ 'command': 'qom-list-types',
'data': { '*implements': 'str', '*abstract': 'bool' },
'returns': [ 'ObjectTypeInfo' ] }
##
# @migrate
#
# Migrates the current running guest to another Virtual Machine.
#
# @uri: the Uniform Resource Identifier of the destination VM
#
# @blk: #optional do block migration (full disk copy)
#
# @inc: #optional incremental disk copy migration
#
# @detach: this argument exists only for compatibility reasons and
# is ignored by QEMU
#
# Returns: nothing on success
#
# Since: 0.14.0
##
{ 'command': 'migrate',
'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', '*detach': 'bool' } }
# @xen-save-devices-state:
#
# Save the state of all devices to file. The RAM and the block devices
# of the VM are not saved by this command.
#
# @filename: the file to save the state of the devices to as binary
# data. See xen-save-devices-state.txt for a description of the binary
# format.
#
# Returns: Nothing on success
# If @filename cannot be opened, OpenFileFailed
# If an I/O error occurs while writing the file, IOError
#
# Since: 1.1
##
{ 'command': 'xen-save-devices-state', 'data': {'filename': 'str'} }
##
# @device_del:
#
# Remove a device from a guest
#
# @id: the name of the device
#
# Returns: Nothing on success
# If @id is not a valid device, DeviceNotFound
# If the device does not support unplug, BusNoHotplug
#
# 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.
#
# Since: 0.14.0
##
{ 'command': 'device_del', 'data': {'id': 'str'} }
##
# @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. This command is only
# supported on i386 and x86_64.
#
# @paging: if true, do paging to get guest's memory mapping. This allows
# using gdb to process the core file. However, setting @paging to false
# may be desirable because of two reasons:
#
# 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
#
# @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.
#
# @begin: #optional if specified, the starting physical address.
#
# @length: #optional 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
#
# Returns: nothing on success
# If @begin contains an invalid address, InvalidParameter
# If only one of @begin and @length is specified, MissingParameter
# If @protocol stats with "fd:", and the fd cannot be found, FdNotFound
# If @protocol starts with "file:", and the file cannot be
# opened, OpenFileFailed
# If @protocol does not start with "fd:" or "file:", InvalidParameter
# If an I/O error occurs while writing the file, IOError
# If the target does not support this command, Unsupported
#
# Since: 1.2
##
{ 'command': 'dump-guest-memory',
'data': { 'paging': 'bool', 'protocol': 'str', '*begin': 'int',
'*length': 'int' } }
##
# @netdev_add:
#
# Add a network backend.
#
# @type: the type of network backend. Current valid values are 'user', 'tap',
# 'vde', 'socket', 'dump' and 'bridge'
#
# @id: the name of the new network backend
#
# @props: #optional a list of properties to be passed to the backend in
# the format 'name=value', like 'ifname=tap0,script=no'
#
# Notes: The semantics of @props is not well defined. Future commands will be
# introduced that provide stronger typing for backend creation.
#
# Since: 0.14.0
#
# Returns: Nothing on success
# If @type is not a valid network backend, DeviceNotFound
# If @id is not a valid identifier, InvalidParameterValue
# if @id already exists, DuplicateId
# If @props contains an invalid parameter for this backend,
# InvalidParameter
##
{ 'command': 'netdev_add',
'data': {'type': 'str', 'id': 'str', '*props': '**'},
'gen': 'no' }
##
# @netdev_del:
#
# Remove a network backend.
#
# @id: the name of the network backend to remove
#
# Returns: Nothing on success
# If @id is not a valid network backend, DeviceNotFound
#
# Since: 0.14.0
##
{ 'command': 'netdev_del', 'data': {'id': 'str'} }
##
# @NetdevNoneOptions
#
# Use it alone to have zero network devices.
#
# Since 1.2
##
{ 'type': 'NetdevNoneOptions',
'data': { } }
##
# @NetLegacyNicOptions
#
# Create a new Network Interface Card.
#
# @netdev: #optional id of -netdev to connect to
#
# @macaddr: #optional MAC address
#
# @model: #optional device model (e1000, rtl8139, virtio etc.)
#
# @addr: #optional PCI device address
#
# @vectors: #optional number of MSI-x vectors, 0 to disable MSI-X
#
# Since 1.2
##
{ 'type': 'NetLegacyNicOptions',
'data': {
'*netdev': 'str',
'*macaddr': 'str',
'*model': 'str',
'*addr': 'str',
'*vectors': 'uint32' } }
##
# @String
#
# A fat type wrapping 'str', to be embedded in lists.
#
# Since 1.2
##
{ 'type': 'String',
'data': {
'str': 'str' } }
##
# @NetdevUserOptions
#
# Use the user mode network stack which requires no administrator privilege to
# run.
#
# @hostname: #optional client hostname reported by the builtin DHCP server
#
# @restrict: #optional isolate the guest from the host
#
# @ip: #optional legacy parameter, use net= instead
#
# @net: #optional IP address and optional netmask
#
# @host: #optional guest-visible address of the host
#
# @tftp: #optional root directory of the built-in TFTP server
#
# @bootfile: #optional BOOTP filename, for use with tftp=
#
# @dhcpstart: #optional the first of the 16 IPs the built-in DHCP server can
# assign
#
# @dns: #optional guest-visible address of the virtual nameserver
#
# @smb: #optional root directory of the built-in SMB server
#
# @smbserver: #optional IP address of the built-in SMB server
#
# @hostfwd: #optional redirect incoming TCP or UDP host connections to guest
# endpoints
#
# @guestfwd: #optional forward guest TCP connections
#
# Since 1.2
##
{ 'type': 'NetdevUserOptions',
'data': {
'*hostname': 'str',
'*restrict': 'bool',
'*ip': 'str',
'*net': 'str',
'*host': 'str',
'*tftp': 'str',
'*bootfile': 'str',
'*dhcpstart': 'str',
'*dns': 'str',
'*smb': 'str',
'*smbserver': 'str',
'*hostfwd': ['String'],
'*guestfwd': ['String'] } }
##
# @NetdevTapOptions
#
# Connect the host TAP network interface name to the VLAN.
#
# @ifname: #optional interface name
#
# @fd: #optional file descriptor of an already opened tap
#
# @script: #optional script to initialize the interface
#
# @downscript: #optional script to shut down the interface
#
# @helper: #optional command to execute to configure bridge
#
# @sndbuf: #optional send buffer limit. Understands [TGMKkb] suffixes.
#
# @vnet_hdr: #optional enable the IFF_VNET_HDR flag on the tap interface
#
# @vhost: #optional enable vhost-net network accelerator
#
# @vhostfd: #optional file descriptor of an already opened vhost net device
#
# @vhostforce: #optional vhost on for non-MSIX virtio guests
#
# Since 1.2
##
{ 'type': 'NetdevTapOptions',
'data': {
'*ifname': 'str',
'*fd': 'str',
'*script': 'str',
'*downscript': 'str',
'*helper': 'str',
'*sndbuf': 'size',
'*vnet_hdr': 'bool',
'*vhost': 'bool',
'*vhostfd': 'str',
'*vhostforce': 'bool' } }
##
# @NetdevSocketOptions
#
# Connect the VLAN to a remote VLAN in another QEMU virtual machine using a TCP
# socket connection.
#
# @fd: #optional file descriptor of an already opened socket
#
# @listen: #optional port number, and optional hostname, to listen on
#
# @connect: #optional port number, and optional hostname, to connect to
#
# @mcast: #optional UDP multicast address and port number
#
# @localaddr: #optional source address and port for multicast and udp packets
#
# @udp: #optional UDP unicast address and port number
#
# Since 1.2
##
{ 'type': 'NetdevSocketOptions',
'data': {
'*fd': 'str',
'*listen': 'str',
'*connect': 'str',
'*mcast': 'str',
'*localaddr': 'str',
'*udp': 'str' } }
##
# @NetdevVdeOptions
#
# Connect the VLAN to a vde switch running on the host.
#
# @sock: #optional socket path
#
# @port: #optional port number
#
# @group: #optional group owner of socket
#
# @mode: #optional permissions for socket
#
# Since 1.2
##
{ 'type': 'NetdevVdeOptions',
'data': {
'*sock': 'str',
'*port': 'uint16',
'*group': 'str',
'*mode': 'uint16' } }
##
# @NetdevDumpOptions
#
# Dump VLAN network traffic to a file.
#
# @len: #optional per-packet size limit (64k default). Understands [TGMKkb]
# suffixes.
#
# @file: #optional dump file path (default is qemu-vlan0.pcap)
#
# Since 1.2
##
{ 'type': 'NetdevDumpOptions',
'data': {
'*len': 'size',
'*file': 'str' } }
##
# @NetdevBridgeOptions
#
# Connect a host TAP network interface to a host bridge device.
#
# @br: #optional bridge name
#
# @helper: #optional command to execute to configure bridge
#
# Since 1.2
##
{ 'type': 'NetdevBridgeOptions',
'data': {
'*br': 'str',
'*helper': 'str' } }
##
# @NetClientOptions
#
# A discriminated record of network device traits.
#
# Since 1.2
##
{ 'union': 'NetClientOptions',
'data': {
'none': 'NetdevNoneOptions',
'nic': 'NetLegacyNicOptions',
'user': 'NetdevUserOptions',
'tap': 'NetdevTapOptions',
'socket': 'NetdevSocketOptions',
'vde': 'NetdevVdeOptions',
'dump': 'NetdevDumpOptions',
'bridge': 'NetdevBridgeOptions' } }
##
# @NetLegacy
#
# Captures the configuration of a network device; legacy.
#
# @vlan: #optional vlan number
#
# @id: #optional identifier for monitor commands
#
# @name: #optional identifier for monitor commands, ignored if @id is present
#
# @opts: device type specific properties (legacy)
#
# Since 1.2
##
{ 'type': 'NetLegacy',
'data': {
'*vlan': 'int32',
'*id': 'str',
'*name': 'str',
'opts': 'NetClientOptions' } }
##
# @Netdev
#
# Captures the configuration of a network device.
#
# @id: identifier for monitor commands.
#
# @opts: device type specific properties
#
# Since 1.2
##
{ 'type': 'Netdev',
'data': {
'id': 'str',
'opts': 'NetClientOptions' } }
##
# @getfd:
#
# Receive a file descriptor via SCM rights and assign it a name
#
# @fdname: file descriptor name
#
# Returns: Nothing on success
# If file descriptor was not received, FdNotSupplied
# If @fdname is not valid, InvalidParameterType
#
# 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.
##
{ 'command': 'getfd', 'data': {'fdname': 'str'} }
##
# @closefd:
#
# Close a file descriptor previously passed via SCM rights
#
# @fdname: file descriptor name
#
# Returns: Nothing on success
# If @fdname is not found, FdNotFound
#
# Since: 0.14.0
##
{ 'command': 'closefd', 'data': {'fdname': 'str'} }