mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
6ba254801f
qemu/qapi/misc.json
Steve Sistare b9ae473d80 cpus: stop vm in suspended runstate 
Currently, a vm in the suspended state is not completely stopped.  The VCPUs
have been paused, but the cpu clock still runs, and runstate notifiers for
the transition to stopped have not been called.  This causes problems for
live migration.  Stale cpu timers_state is saved to the migration stream,
causing time errors in the guest when it wakes from suspend, and state that
would have been modified by runstate notifiers is wrong.

Modify vm_stop to completely stop the vm if the current state is suspended,
transition to RUN_STATE_PAUSED, and remember that the machine was suspended.
Modify vm_start to restore the suspended state.

This affects all callers of vm_stop and vm_start, notably, the qapi stop and
cont commands:

  old behavior:
    RUN_STATE_SUSPENDED --> stop --> RUN_STATE_SUSPENDED

  new behavior:
    RUN_STATE_SUSPENDED --> stop --> RUN_STATE_PAUSED
    RUN_STATE_PAUSED    --> cont --> RUN_STATE_SUSPENDED

For example:

    (qemu) info status
    VM status: paused (suspended)

    (qemu) stop
    (qemu) info status
    VM status: paused

    (qemu) system_wakeup
    Error: Unable to wake up: guest is not in suspended state

    (qemu) cont
    (qemu) info status
    VM status: paused (suspended)

    (qemu) system_wakeup
    (qemu) info status
    VM status: running

Suggested-by: Peter Xu <peterx@redhat.com>
Signed-off-by: Steve Sistare <steven.sistare@oracle.com>
Reviewed-by: Peter Xu <peterx@redhat.com>
Link: https://lore.kernel.org/r/1704312341-66640-3-git-send-email-steven.sistare@oracle.com
Signed-off-by: Peter Xu <peterx@redhat.com>
2024-01-04 09:52:42 +08:00

615 lines
14 KiB
Python
Raw Blame History

# -*- 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
#
# Returns: nothing on success.
#
# 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
#
# 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.
#
# 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
#
# Returns: nothing
#
# 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
#
# Returns: Nothing on success
#
# 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
#
# Returns: Nothing on success
#
# 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
#
# Returns: Nothing on success
#
# 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 on success
# - 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.
#
# Returns:
# - Nothing on success
# - 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). 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'],
'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' } }
Reference in New Issue View Git Blame Copy Permalink