qemu

misc.json (13736B)

---

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