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