qapi/misc.json - qemu - Git at Google

 # -*- 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" 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', 'allow-preconfig': true }

 ##
 # @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' }

 ##
 # @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'],
   'allow-preconfig': true }

 ##
 # @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' }

 ##
 # @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' }

 ##
 # @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).
 #
 # Since 3.0
 #
 # Returns: nothing
 #
 # Example:
 #
 # -> { "execute": "x-exit-preconfig" }
 # <- { "return": {} }
 #
 ##
 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }

 ##
 # @system_wakeup:
 #
 # Wake up guest from suspend. If the guest has wake-up from suspend
 # support enabled (wakeup-suspend-support flag from
 # query-current-machine), wake-up guest from suspend if the guest is
 # in SUSPENDED state. Return an error otherwise.
 #
 # Since:  1.1
 #
 # Returns:  nothing.
 #
 # Note: prior to 4.0, this command does nothing in case the guest
 #       isn't suspended.
 #
 # 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' }

 ##
 # @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.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',
   'features': [ 'savevm-monitor-nodes' ] }

 ##
 # @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.
 #
 # Features:
 # @deprecated: This command is deprecated.  For changing block
 #              devices, use 'blockdev-change-medium' instead; for changing VNC
 #              parameters, use 'change-vnc-password' instead.
 #
 # Returns: - Nothing on success.
 #          - If @device is not a valid block device, DeviceNotFound
 #
 # 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'},
   'features': [ 'deprecated' ] }

 ##
 # @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' } }

 ##
 # @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'} }

 ##
 # @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'] }

 ##
 # @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 }

 ##
 # @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'} }
	# -- 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" 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', 'allow-preconfig': true }

	##
	# @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' }

	##
	# @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'],
	'allow-preconfig': true }

	##
	# @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' }

	##
	# @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' }

	##
	# @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).
	#
	# Since 3.0
	#
	# Returns: nothing
	#
	# Example:
	#
	# -> { "execute": "x-exit-preconfig" }
	# <- { "return": {} }
	#
	##
	{ 'command': 'x-exit-preconfig', 'allow-preconfig': true }

	##
	# @system_wakeup:
	#
	# Wake up guest from suspend. If the guest has wake-up from suspend
	# support enabled (wakeup-suspend-support flag from
	# query-current-machine), wake-up guest from suspend if the guest is
	# in SUSPENDED state. Return an error otherwise.
	#
	# Since: 1.1
	#
	# Returns: nothing.
	#
	# Note: prior to 4.0, this command does nothing in case the guest
	# isn't suspended.
	#
	# 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' }

	##
	# @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.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',
	'features': [ 'savevm-monitor-nodes' ] }

	##
	# @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.
	#
	# Features:
	# @deprecated: This command is deprecated. For changing block
	# devices, use 'blockdev-change-medium' instead; for changing VNC
	# parameters, use 'change-vnc-password' instead.
	#
	# Returns: - Nothing on success.
	# - If @device is not a valid block device, DeviceNotFound
	#
	# 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'},
	'features': [ 'deprecated' ] }

	##
	# @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' } }

	##
	# @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'} }

	##
	# @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'] }

	##
	# @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 }

	##
	# @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'} }