9 { 'include': 'common.json' }
14 # Allow client connections for VNC, Spice and socket based
15 # character devices to be passed in to QEMU via SCM_RIGHTS.
17 # If the FD associated with @fdname is not a socket, the command will fail and
18 # the FD will be closed.
20 # @protocol: protocol name. Valid names are "vnc", "spice", "@dbus-display" or
21 # the name of a character device (eg. from -chardev id=XXXX)
23 # @fdname: file descriptor name previously passed via 'getfd' command
25 # @skipauth: whether to skip authentication. Only applies
26 # to "vnc" and "spice" protocols
28 # @tls: whether to perform TLS. Only applies to the "spice"
31 # Returns: nothing on success.
37 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
38 # "fdname": "myclient" } }
42 { 'command': 'add_client',
43 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
49 # Guest name information.
51 # @name: The name of the guest
55 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
60 # Return the name information of a guest.
62 # Returns: @NameInfo of the guest
68 # -> { "execute": "query-name" }
69 # <- { "return": { "name": "qemu-name" } }
72 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
77 # Information about an iothread
79 # @id: the identifier of the iothread
81 # @thread-id: ID of the underlying host thread
83 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
86 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
87 # configured (since 2.9)
89 # @poll-shrink: how many ns will be removed from polling time, 0 means that
90 # it's not configured (since 2.9)
92 # @aio-max-batch: maximum number of requests in a batch for the AIO engine,
93 # 0 means that the engine will use its default (since 6.1)
97 { 'struct': 'IOThreadInfo',
100 'poll-max-ns': 'int',
102 'poll-shrink': 'int',
103 'aio-max-batch': 'int' } }
108 # Returns a list of information about each iothread.
110 # Note: this list excludes the QEMU main loop thread, which is not declared
111 # using the -object iothread command-line option. It is always the main thread
114 # Returns: a list of @IOThreadInfo for each iothread
120 # -> { "execute": "query-iothreads" }
134 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
135 'allow-preconfig': true }
140 # Stop all guest VCPU execution.
144 # Notes: This function will succeed even if the guest is already in the stopped
145 # state. In "inmigrate" state, it will ensure that the guest
146 # remains paused once migration finishes, as if the -S option was
147 # passed on the command line.
151 # -> { "execute": "stop" }
152 # <- { "return": {} }
155 { 'command': 'stop' }
160 # Resume guest VCPU execution.
164 # Returns: If successful, nothing
166 # Notes: This command will succeed if the guest is currently running. It
167 # will also succeed if the guest is in the "inmigrate" state; in
168 # this case, the effect of the command is to make sure the guest
169 # starts once migration finishes, removing the effect of the -S
170 # command line option if it was passed.
174 # -> { "execute": "cont" }
175 # <- { "return": {} }
178 { 'command': 'cont' }
183 # Exit from "preconfig" state
185 # This command makes QEMU exit the preconfig state and proceed with
186 # VM initialization using configuration data provided on the command line
187 # and via the QMP monitor during the preconfig state. The command is only
188 # available during the preconfig state (i.e. when the --preconfig command
189 # line option was in use).
192 # @unstable: This command is experimental.
200 # -> { "execute": "x-exit-preconfig" }
201 # <- { "return": {} }
204 { 'command': 'x-exit-preconfig', 'allow-preconfig': true,
205 'features': [ 'unstable' ] }
208 # @human-monitor-command:
210 # Execute a command on the human monitor and return the output.
212 # @command-line: the command to execute in the human monitor
214 # @cpu-index: The CPU to use for commands that require an implicit CPU
217 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
218 # monitor-owned nodes if they have no parents.
219 # This allows the use of 'savevm' with
220 # -blockdev. (since 4.2)
222 # Returns: the output of the command as a string
226 # Notes: This command only exists as a stop-gap. Its use is highly
227 # discouraged. The semantics of this command are not
228 # guaranteed: this means that command names, arguments and
229 # responses can change or be removed at ANY time. Applications
230 # that rely on long term stability guarantees should NOT
235 # * This command is stateless, this means that commands that depend
236 # on state information (such as getfd) might not work
238 # * Commands that prompt the user for data don't currently work
242 # -> { "execute": "human-monitor-command",
243 # "arguments": { "command-line": "info kvm" } }
244 # <- { "return": "kvm support: enabled\r\n" }
247 { 'command': 'human-monitor-command',
248 'data': {'command-line': 'str', '*cpu-index': 'int'},
250 'features': [ 'savevm-monitor-nodes' ] }
255 # Receive a file descriptor via SCM rights and assign it a name
257 # @fdname: file descriptor name
259 # Returns: Nothing on success
263 # Notes: If @fdname already exists, the file descriptor assigned to
264 # it will be closed and replaced by the received file
267 # The 'closefd' command can be used to explicitly close the
268 # file descriptor when it is no longer needed.
272 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
273 # <- { "return": {} }
276 { 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' }
281 # Add a socket that was duplicated to QEMU process with
282 # WSADuplicateSocketW() via WSASocket() & WSAPROTOCOL_INFOW structure
283 # and assign it a name (the SOCKET is associated with a CRT file
286 # @info: the WSAPROTOCOL_INFOW structure (encoded in base64)
288 # @fdname: file descriptor name
290 # Returns: Nothing on success
294 # Notes: If @fdname already exists, the file descriptor assigned to
295 # it will be closed and replaced by the received file
298 # The 'closefd' command can be used to explicitly close the
299 # file descriptor when it is no longer needed.
303 # -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } }
304 # <- { "return": {} }
307 { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
312 # Close a file descriptor previously passed via SCM rights
314 # @fdname: file descriptor name
316 # Returns: Nothing on success
322 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
323 # <- { "return": {} }
326 { 'command': 'closefd', 'data': {'fdname': 'str'} }
331 # Information about a file descriptor that was added to an fd set.
333 # @fdset-id: The ID of the fd set that @fd was added to.
335 # @fd: The file descriptor that was received via SCM rights and
336 # added to the fd set.
340 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
345 # Add a file descriptor, that was passed via SCM rights, to an fd set.
347 # @fdset-id: The ID of the fd set to add the file descriptor to.
349 # @opaque: A free-form string that can be used to describe the fd.
351 # Returns: - @AddfdInfo on success
352 # - If file descriptor was not received, GenericError
353 # - If @fdset-id is a negative value, GenericError
355 # Notes: The list of fd sets is shared by all monitor connections.
357 # If @fdset-id is not specified, a new fd set will be created.
363 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
364 # <- { "return": { "fdset-id": 1, "fd": 3 } }
367 { 'command': 'add-fd',
368 'data': { '*fdset-id': 'int',
370 'returns': 'AddfdInfo' }
375 # Remove a file descriptor from an fd set.
377 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
379 # @fd: The file descriptor that is to be removed.
381 # Returns: - Nothing on success
382 # - If @fdset-id or @fd is not found, GenericError
386 # Notes: The list of fd sets is shared by all monitor connections.
388 # If @fd is not specified, all file descriptors in @fdset-id
393 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
394 # <- { "return": {} }
397 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
402 # Information about a file descriptor that belongs to an fd set.
404 # @fd: The file descriptor value.
406 # @opaque: A free-form string that can be used to describe the fd.
410 { 'struct': 'FdsetFdInfo',
411 'data': {'fd': 'int', '*opaque': 'str'} }
416 # Information about an fd set.
418 # @fdset-id: The ID of the fd set.
420 # @fds: A list of file descriptors that belong to this fd set.
424 { 'struct': 'FdsetInfo',
425 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
430 # Return information describing all fd sets.
432 # Returns: A list of @FdsetInfo
436 # Note: The list of fd sets is shared by all monitor connections.
440 # -> { "execute": "query-fdsets" }
446 # "opaque": "rdonly:/path/to/file"
450 # "opaque": "rdwr:/path/to/file"
470 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
473 # @CommandLineParameterType:
475 # Possible types for an option parameter.
477 # @string: accepts a character string
479 # @boolean: accepts "on" or "off"
481 # @number: accepts a number
483 # @size: accepts a number followed by an optional suffix (K)ilo,
484 # (M)ega, (G)iga, (T)era
488 { 'enum': 'CommandLineParameterType',
489 'data': ['string', 'boolean', 'number', 'size'] }
492 # @CommandLineParameterInfo:
494 # Details about a single parameter of a command line option.
496 # @name: parameter name
498 # @type: parameter @CommandLineParameterType
500 # @help: human readable text string, not suitable for parsing.
502 # @default: default value string (since 2.1)
506 { 'struct': 'CommandLineParameterInfo',
507 'data': { 'name': 'str',
508 'type': 'CommandLineParameterType',
510 '*default': 'str' } }
513 # @CommandLineOptionInfo:
515 # Details about a command line option, including its list of parameter details
517 # @option: option name
519 # @parameters: an array of @CommandLineParameterInfo
523 { 'struct': 'CommandLineOptionInfo',
524 'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
527 # @query-command-line-options:
529 # Query command line option schema.
531 # @option: option name
533 # Returns: list of @CommandLineOptionInfo for all options (or for the given
534 # @option). Returns an error if the given @option doesn't exist.
540 # -> { "execute": "query-command-line-options",
541 # "arguments": { "option": "option-rom" } }
550 # "name": "bootindex",
554 # "option": "option-rom"
560 {'command': 'query-command-line-options',
561 'data': { '*option': 'str' },
562 'returns': ['CommandLineOptionInfo'],
563 'allow-preconfig': true }
568 # Emitted when the guest changes the RTC time.
570 # @offset: offset in seconds between base RTC clock (as specified
571 # by -rtc base), and new RTC clock value
573 # @qom-path: path to the RTC object in the QOM tree
575 # Note: This event is rate-limited.
576 # It is not guaranteed that the RTC in the system implements
577 # this event, or even that the system has an RTC at all.
583 # <- { "event": "RTC_CHANGE",
584 # "data": { "offset": 78 },
585 # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
587 { 'event': 'RTC_CHANGE',
588 'data': { 'offset': 'int', 'qom-path': 'str' } }
591 # @VFU_CLIENT_HANGUP:
593 # Emitted when the client of a TYPE_VFIO_USER_SERVER closes the
594 # communication channel
596 # @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last component
597 # of @vfu-qom-path referenced below
599 # @vfu-qom-path: path to the TYPE_VFIO_USER_SERVER object in the QOM tree
601 # @dev-id: ID of attached PCI device
603 # @dev-qom-path: path to attached PCI device in the QOM tree
609 # <- { "event": "VFU_CLIENT_HANGUP",
610 # "data": { "vfu-id": "vfu1",
611 # "vfu-qom-path": "/objects/vfu1",
613 # "dev-qom-path": "/machine/peripheral/sas1" },
614 # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
617 { 'event': 'VFU_CLIENT_HANGUP',
618 'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str',
619 'dev-id': 'str', 'dev-qom-path': 'str' } }