e2c1dcbccc
Drop list markup, since there's just one item left. Drop "on success" where it is redundant with "Returns:". Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-7-armbru@redhat.com>
608 lines
15 KiB
Python
608 lines
15 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
|
|
##
|
|
# = Miscellanea
|
|
##
|
|
|
|
{ 'include': 'common.json' }
|
|
|
|
##
|
|
# @add_client:
|
|
#
|
|
# Allow client connections for VNC, Spice and socket based character
|
|
# devices to be passed in to QEMU via SCM_RIGHTS.
|
|
#
|
|
# If the FD associated with @fdname is not a socket, the command will
|
|
# fail and the FD will be closed.
|
|
#
|
|
# @protocol: protocol name. Valid names are "vnc", "spice",
|
|
# "@dbus-display" or the name of a character device (e.g. 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
|
|
#
|
|
# Since: 0.14
|
|
#
|
|
# 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
|
|
##
|
|
{ 'struct': 'NameInfo', 'data': {'*name': 'str'} }
|
|
|
|
##
|
|
# @query-name:
|
|
#
|
|
# Return the name information of a guest.
|
|
#
|
|
# Returns: @NameInfo of the guest
|
|
#
|
|
# Since: 0.14
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-name" }
|
|
# <- { "return": { "name": "qemu-name" } }
|
|
##
|
|
{ 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
|
|
|
|
##
|
|
# @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)
|
|
#
|
|
# @aio-max-batch: maximum number of requests in a batch for the AIO
|
|
# engine, 0 means that the engine will use its default (since 6.1)
|
|
#
|
|
# Since: 2.0
|
|
##
|
|
{ 'struct': 'IOThreadInfo',
|
|
'data': {'id': 'str',
|
|
'thread-id': 'int',
|
|
'poll-max-ns': 'int',
|
|
'poll-grow': 'int',
|
|
'poll-shrink': 'int',
|
|
'aio-max-batch': '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'],
|
|
'allow-preconfig': true }
|
|
|
|
##
|
|
# @stop:
|
|
#
|
|
# Stop guest VM execution.
|
|
#
|
|
# Since: 0.14
|
|
#
|
|
# 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.
|
|
#
|
|
# In the "suspended" state, it will completely stop the VM and
|
|
# cause a transition to the "paused" state. (Since 9.0)
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "stop" }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'stop' }
|
|
|
|
##
|
|
# @cont:
|
|
#
|
|
# Resume guest VM execution.
|
|
#
|
|
# Since: 0.14
|
|
#
|
|
# 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.
|
|
#
|
|
# If the VM was previously suspended, and not been reset or woken,
|
|
# this command will transition back to the "suspended" state.
|
|
# (Since 9.0)
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "cont" }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'cont' }
|
|
|
|
##
|
|
# @x-exit-preconfig:
|
|
#
|
|
# Exit from "preconfig" state
|
|
#
|
|
# This command makes QEMU exit the preconfig state and proceed with VM
|
|
# initialization using configuration data provided on the command line
|
|
# and via the QMP monitor during the preconfig state. The command is
|
|
# only available during the preconfig state (i.e. when the --preconfig
|
|
# command line option was in use).
|
|
#
|
|
# Features:
|
|
#
|
|
# @unstable: This command is experimental.
|
|
#
|
|
# Since: 3.0
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "x-exit-preconfig" }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'x-exit-preconfig', 'allow-preconfig': true,
|
|
'features': [ 'unstable' ] }
|
|
|
|
##
|
|
# @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
|
|
#
|
|
# Features:
|
|
#
|
|
# @savevm-monitor-nodes: If present, HMP command savevm only snapshots
|
|
# monitor-owned nodes if they have no parents. This allows the
|
|
# use of 'savevm' with -blockdev. (since 4.2)
|
|
#
|
|
# Returns: the output of the command as a string
|
|
#
|
|
# Since: 0.14
|
|
#
|
|
# 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',
|
|
'features': [ 'savevm-monitor-nodes' ] }
|
|
|
|
##
|
|
# @getfd:
|
|
#
|
|
# Receive a file descriptor via SCM rights and assign it a name
|
|
#
|
|
# @fdname: file descriptor name
|
|
#
|
|
# Since: 0.14
|
|
#
|
|
# 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'}, 'if': 'CONFIG_POSIX' }
|
|
|
|
##
|
|
# @get-win32-socket:
|
|
#
|
|
# Add a socket that was duplicated to QEMU process with
|
|
# WSADuplicateSocketW() via WSASocket() & WSAPROTOCOL_INFOW structure
|
|
# and assign it a name (the SOCKET is associated with a CRT file
|
|
# descriptor)
|
|
#
|
|
# @info: the WSAPROTOCOL_INFOW structure (encoded in base64)
|
|
#
|
|
# @fdname: file descriptor name
|
|
#
|
|
# Since: 8.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": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
|
|
|
|
##
|
|
# @closefd:
|
|
#
|
|
# Close a file descriptor previously passed via SCM rights
|
|
#
|
|
# @fdname: file descriptor name
|
|
#
|
|
# Since: 0.14
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'closefd', 'data': {'fdname': 'str'} }
|
|
|
|
##
|
|
# @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
|
|
##
|
|
{ '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
|
|
#
|
|
# Errors:
|
|
# - If file descriptor was not received, GenericError
|
|
# - If @fdset-id is a negative value, GenericError
|
|
#
|
|
# 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
|
|
#
|
|
# 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.
|
|
#
|
|
# Errors:
|
|
# - If @fdset-id or @fd is not found, GenericError
|
|
#
|
|
# Since: 1.2
|
|
#
|
|
# 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
|
|
##
|
|
{ '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
|
|
##
|
|
{ 'struct': 'FdsetInfo',
|
|
'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
|
|
|
|
##
|
|
# @query-fdsets:
|
|
#
|
|
# Return information describing all fd sets.
|
|
#
|
|
# Returns: A list of @FdsetInfo
|
|
#
|
|
# Since: 1.2
|
|
#
|
|
# 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'] }
|
|
|
|
##
|
|
# @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).
|
|
#
|
|
# Errors:
|
|
# - 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'],
|
|
'allow-preconfig': true}
|
|
|
|
##
|
|
# @RTC_CHANGE:
|
|
#
|
|
# Emitted when the guest changes the RTC time.
|
|
#
|
|
# @offset: offset in seconds between base RTC clock (as specified by
|
|
# -rtc base), and new RTC clock value
|
|
#
|
|
# @qom-path: path to the RTC object in the QOM tree
|
|
#
|
|
# Note: This event is rate-limited. It is not guaranteed that the RTC
|
|
# in the system implements this event, or even that the system has
|
|
# an RTC at all.
|
|
#
|
|
# Since: 0.13
|
|
#
|
|
# Example:
|
|
#
|
|
# <- { "event": "RTC_CHANGE",
|
|
# "data": { "offset": 78 },
|
|
# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
|
|
##
|
|
{ 'event': 'RTC_CHANGE',
|
|
'data': { 'offset': 'int', 'qom-path': 'str' } }
|
|
|
|
##
|
|
# @VFU_CLIENT_HANGUP:
|
|
#
|
|
# Emitted when the client of a TYPE_VFIO_USER_SERVER closes the
|
|
# communication channel
|
|
#
|
|
# @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last
|
|
# component of @vfu-qom-path referenced below
|
|
#
|
|
# @vfu-qom-path: path to the TYPE_VFIO_USER_SERVER object in the QOM
|
|
# tree
|
|
#
|
|
# @dev-id: ID of attached PCI device
|
|
#
|
|
# @dev-qom-path: path to attached PCI device in the QOM tree
|
|
#
|
|
# Since: 7.1
|
|
#
|
|
# Example:
|
|
#
|
|
# <- { "event": "VFU_CLIENT_HANGUP",
|
|
# "data": { "vfu-id": "vfu1",
|
|
# "vfu-qom-path": "/objects/vfu1",
|
|
# "dev-id": "sas1",
|
|
# "dev-qom-path": "/machine/peripheral/sas1" },
|
|
# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
|
|
##
|
|
{ 'event': 'VFU_CLIENT_HANGUP',
|
|
'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str',
|
|
'dev-id': 'str', 'dev-qom-path': 'str' } }
|