# -*- 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.
#
# @protocol: protocol name. Valid names are "vnc", "spice", "@dbus-display" 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
#
# 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 all guest VCPU 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.
#
# Example:
#
# -> { "execute": "stop" }
# <- { "return": {} }
#
##
{ 'command': 'stop' }

##
# @cont:
#
# Resume guest VCPU 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.
#
# 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'} }

##
# @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, 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
#
# 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
#
# 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 between base RTC clock (as specified by -rtc base), and
#          new RTC clock value
#
# Note: This event is rate-limited.
#
# Since: 0.13
#
# Example:
#
# <-   { "event": "RTC_CHANGE",
#        "data": { "offset": 78 },
#        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
#
##
{ 'event': 'RTC_CHANGE',
  'data': { 'offset': 'int' } }