ff9a915655
Start the deprecation period for QAPI query-cpus (replaced by query-cpus-fast) beginning with 2.12.0. Signed-off-by: Viktor Mihajlovski <mihajlov@linux.vnet.ibm.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1518797321-28356-5-git-send-email-mihajlov@linux.vnet.ibm.com> Reviewed-by: Cornelia Huck <cohuck@redhat.com> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
3303 lines
84 KiB
Python
3303 lines
84 KiB
Python
# -*- 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 and @query-cpus-fast.
|
|
#
|
|
# @s390: since 2.12
|
|
#
|
|
# Since: 2.6
|
|
##
|
|
{ 'enum': 'CpuInfoArch',
|
|
'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 's390', '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',
|
|
's390': 'CpuInfoS390',
|
|
'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': { } }
|
|
|
|
##
|
|
# @CpuS390State:
|
|
#
|
|
# An enumeration of cpu states that can be assumed by a virtual
|
|
# S390 CPU
|
|
#
|
|
# Since: 2.12
|
|
##
|
|
{ 'enum': 'CpuS390State',
|
|
'prefix': 'S390_CPU_STATE',
|
|
'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] }
|
|
|
|
##
|
|
# @CpuInfoS390:
|
|
#
|
|
# Additional information about a virtual S390 CPU
|
|
#
|
|
# @cpu-state: the virtual CPU's state
|
|
#
|
|
# Since: 2.12
|
|
##
|
|
{ 'struct': 'CpuInfoS390', 'data': { 'cpu-state': 'CpuS390State' } }
|
|
|
|
##
|
|
# @query-cpus:
|
|
#
|
|
# Returns a list of information about each virtual CPU.
|
|
#
|
|
# This command causes vCPU threads to exit to userspace, which causes
|
|
# a small interruption to guest CPU execution. This will have a negative
|
|
# impact on realtime guests and other latency sensitive guest workloads.
|
|
# It is recommended to use @query-cpus-fast instead of this command to
|
|
# avoid the vCPU interruption.
|
|
#
|
|
# 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
|
|
# }
|
|
# ]
|
|
# }
|
|
#
|
|
# Notes: This interface is deprecated (since 2.12.0), and it is strongly
|
|
# recommended that you avoid using it. Use @query-cpus-fast to
|
|
# obtain information about virtual CPUs.
|
|
#
|
|
##
|
|
{ 'command': 'query-cpus', 'returns': ['CpuInfo'] }
|
|
|
|
##
|
|
# @CpuInfoFast:
|
|
#
|
|
# Information about a virtual CPU
|
|
#
|
|
# @cpu-index: index of the virtual CPU
|
|
#
|
|
# @qom-path: path to the CPU object in the QOM tree
|
|
#
|
|
# @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
|
|
#
|
|
# @arch: architecture of the cpu, which determines which additional fields
|
|
# will be listed
|
|
#
|
|
# Since: 2.12
|
|
#
|
|
##
|
|
{ 'union': 'CpuInfoFast',
|
|
'base': {'cpu-index': 'int', 'qom-path': 'str',
|
|
'thread-id': 'int', '*props': 'CpuInstanceProperties',
|
|
'arch': 'CpuInfoArch' },
|
|
'discriminator': 'arch',
|
|
'data': { 'x86': 'CpuInfoOther',
|
|
'sparc': 'CpuInfoOther',
|
|
'ppc': 'CpuInfoOther',
|
|
'mips': 'CpuInfoOther',
|
|
'tricore': 'CpuInfoOther',
|
|
's390': 'CpuInfoS390',
|
|
'other': 'CpuInfoOther' } }
|
|
|
|
##
|
|
# @query-cpus-fast:
|
|
#
|
|
# Returns information about all virtual CPUs. This command does not
|
|
# incur a performance penalty and should be used in production
|
|
# instead of query-cpus.
|
|
#
|
|
# Returns: list of @CpuInfoFast
|
|
#
|
|
# Since: 2.12
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-cpus-fast" }
|
|
# <- { "return": [
|
|
# {
|
|
# "thread-id": 25627,
|
|
# "props": {
|
|
# "core-id": 0,
|
|
# "thread-id": 0,
|
|
# "socket-id": 0
|
|
# },
|
|
# "qom-path": "/machine/unattached/device[0]",
|
|
# "arch":"x86",
|
|
# "cpu-index": 0
|
|
# },
|
|
# {
|
|
# "thread-id": 25628,
|
|
# "props": {
|
|
# "core-id": 0,
|
|
# "thread-id": 0,
|
|
# "socket-id": 1
|
|
# },
|
|
# "qom-path": "/machine/unattached/device[2]",
|
|
# "arch":"x86",
|
|
# "cpu-index": 1
|
|
# }
|
|
# ]
|
|
# }
|
|
##
|
|
{ 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
|
|
|
|
##
|
|
# @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-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' } }
|
|
|
|
##
|
|
# @MemoryInfo:
|
|
#
|
|
# Actual memory information in bytes.
|
|
#
|
|
# @base-memory: size of "base" memory specified with command line
|
|
# option -m.
|
|
#
|
|
# @plugged-memory: size of memory that can be hot-unplugged. This field
|
|
# is omitted if target doesn't support memory hotplug
|
|
# (i.e. CONFIG_MEM_HOTPLUG not defined on build time).
|
|
#
|
|
# Since: 2.11.0
|
|
##
|
|
{ 'struct': 'MemoryInfo',
|
|
'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } }
|
|
|
|
##
|
|
# @query-memory-size-summary:
|
|
#
|
|
# Return the amount of initially allocated and present hotpluggable (if
|
|
# enabled) memory in bytes.
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-memory-size-summary" }
|
|
# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
|
|
#
|
|
# Since: 2.11.0
|
|
##
|
|
{ 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
|
|
|
|
##
|
|
# @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, independent 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 comparison 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}
|
|
# }
|
|
# ]}
|
|
#
|
|
# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
|
|
# (Since: 2.11):
|
|
#
|
|
# -> { "execute": "query-hotpluggable-cpus" }
|
|
# <- {"return": [
|
|
# {
|
|
# "type": "qemu-s390x-cpu", "vcpus-count": 1,
|
|
# "props": { "core-id": 1 }
|
|
# },
|
|
# {
|
|
# "qom-path": "/machine/unattached/device[0]",
|
|
# "type": "qemu-s390x-cpu", "vcpus-count": 1,
|
|
# "props": { "core-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' }
|
|
|
|
##
|
|
# @watchdog-set-action:
|
|
#
|
|
# Set watchdog action
|
|
#
|
|
# Since: 2.11
|
|
##
|
|
{ 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }
|