target/i386/kvm: Free xsave_buf when destroying vCPU
[qemu/rayw.git] / qapi / misc.json
blobb83cc3902988b9ac2a92dcfcafe4f0be2fe3f6f8
1 # -*- Mode: Python -*-
2 # vim: filetype=python
5 ##
6 # = Miscellanea
7 ##
9 { 'include': 'common.json' }
12 # @add_client:
14 # Allow client connections for VNC, Spice and socket based
15 # character devices to be passed in to QEMU via SCM_RIGHTS.
17 # @protocol: protocol name. Valid names are "vnc", "spice", "@dbus-display" or
18 #            the name of a character device (eg. from -chardev id=XXXX)
20 # @fdname: file descriptor name previously passed via 'getfd' command
22 # @skipauth: whether to skip authentication. Only applies
23 #            to "vnc" and "spice" protocols
25 # @tls: whether to perform TLS. Only applies to the "spice"
26 #       protocol
28 # Returns: nothing on success.
30 # Since: 0.14
32 # Example:
34 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
35 #                                              "fdname": "myclient" } }
36 # <- { "return": {} }
39 { 'command': 'add_client',
40   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
41             '*tls': 'bool' } }
44 # @NameInfo:
46 # Guest name information.
48 # @name: The name of the guest
50 # Since: 0.14
52 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
55 # @query-name:
57 # Return the name information of a guest.
59 # Returns: @NameInfo of the guest
61 # Since: 0.14
63 # Example:
65 # -> { "execute": "query-name" }
66 # <- { "return": { "name": "qemu-name" } }
69 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
72 # @IOThreadInfo:
74 # Information about an iothread
76 # @id: the identifier of the iothread
78 # @thread-id: ID of the underlying host thread
80 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
81 #               (since 2.9)
83 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
84 #             configured (since 2.9)
86 # @poll-shrink: how many ns will be removed from polling time, 0 means that
87 #               it's not configured (since 2.9)
89 # @aio-max-batch: maximum number of requests in a batch for the AIO engine,
90 #                 0 means that the engine will use its default (since 6.1)
92 # Since: 2.0
94 { 'struct': 'IOThreadInfo',
95   'data': {'id': 'str',
96            'thread-id': 'int',
97            'poll-max-ns': 'int',
98            'poll-grow': 'int',
99            'poll-shrink': 'int',
100            'aio-max-batch': 'int' } }
103 # @query-iothreads:
105 # Returns a list of information about each iothread.
107 # Note: this list excludes the QEMU main loop thread, which is not declared
108 #       using the -object iothread command-line option.  It is always the main thread
109 #       of the process.
111 # Returns: a list of @IOThreadInfo for each iothread
113 # Since: 2.0
115 # Example:
117 # -> { "execute": "query-iothreads" }
118 # <- { "return": [
119 #          {
120 #             "id":"iothread0",
121 #             "thread-id":3134
122 #          },
123 #          {
124 #             "id":"iothread1",
125 #             "thread-id":3135
126 #          }
127 #       ]
128 #    }
131 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
132   'allow-preconfig': true }
135 # @stop:
137 # Stop all guest VCPU execution.
139 # Since:  0.14
141 # Notes: This function will succeed even if the guest is already in the stopped
142 #        state.  In "inmigrate" state, it will ensure that the guest
143 #        remains paused once migration finishes, as if the -S option was
144 #        passed on the command line.
146 # Example:
148 # -> { "execute": "stop" }
149 # <- { "return": {} }
152 { 'command': 'stop' }
155 # @cont:
157 # Resume guest VCPU execution.
159 # Since:  0.14
161 # Returns:  If successful, nothing
163 # Notes: This command will succeed if the guest is currently running.  It
164 #        will also succeed if the guest is in the "inmigrate" state; in
165 #        this case, the effect of the command is to make sure the guest
166 #        starts once migration finishes, removing the effect of the -S
167 #        command line option if it was passed.
169 # Example:
171 # -> { "execute": "cont" }
172 # <- { "return": {} }
175 { 'command': 'cont' }
178 # @x-exit-preconfig:
180 # Exit from "preconfig" state
182 # This command makes QEMU exit the preconfig state and proceed with
183 # VM initialization using configuration data provided on the command line
184 # and via the QMP monitor during the preconfig state. The command is only
185 # available during the preconfig state (i.e. when the --preconfig command
186 # line option was in use).
188 # Features:
189 # @unstable: This command is experimental.
191 # Since 3.0
193 # Returns: nothing
195 # Example:
197 # -> { "execute": "x-exit-preconfig" }
198 # <- { "return": {} }
201 { 'command': 'x-exit-preconfig', 'allow-preconfig': true,
202   'features': [ 'unstable' ] }
205 # @human-monitor-command:
207 # Execute a command on the human monitor and return the output.
209 # @command-line: the command to execute in the human monitor
211 # @cpu-index: The CPU to use for commands that require an implicit CPU
213 # Features:
214 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
215 #                        monitor-owned nodes if they have no parents.
216 #                        This allows the use of 'savevm' with
217 #                        -blockdev. (since 4.2)
219 # Returns: the output of the command as a string
221 # Since: 0.14
223 # Notes: This command only exists as a stop-gap.  Its use is highly
224 #        discouraged.  The semantics of this command are not
225 #        guaranteed: this means that command names, arguments and
226 #        responses can change or be removed at ANY time.  Applications
227 #        that rely on long term stability guarantees should NOT
228 #        use this command.
230 #        Known limitations:
232 #        * This command is stateless, this means that commands that depend
233 #          on state information (such as getfd) might not work
235 #        * Commands that prompt the user for data don't currently work
237 # Example:
239 # -> { "execute": "human-monitor-command",
240 #      "arguments": { "command-line": "info kvm" } }
241 # <- { "return": "kvm support: enabled\r\n" }
244 { 'command': 'human-monitor-command',
245   'data': {'command-line': 'str', '*cpu-index': 'int'},
246   'returns': 'str',
247   'features': [ 'savevm-monitor-nodes' ] }
250 # @getfd:
252 # Receive a file descriptor via SCM rights and assign it a name
254 # @fdname: file descriptor name
256 # Returns: Nothing on success
258 # Since: 0.14
260 # Notes: If @fdname already exists, the file descriptor assigned to
261 #        it will be closed and replaced by the received file
262 #        descriptor.
264 #        The 'closefd' command can be used to explicitly close the
265 #        file descriptor when it is no longer needed.
267 # Example:
269 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
270 # <- { "return": {} }
273 { 'command': 'getfd', 'data': {'fdname': 'str'} }
276 # @closefd:
278 # Close a file descriptor previously passed via SCM rights
280 # @fdname: file descriptor name
282 # Returns: Nothing on success
284 # Since: 0.14
286 # Example:
288 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
289 # <- { "return": {} }
292 { 'command': 'closefd', 'data': {'fdname': 'str'} }
295 # @AddfdInfo:
297 # Information about a file descriptor that was added to an fd set.
299 # @fdset-id: The ID of the fd set that @fd was added to.
301 # @fd: The file descriptor that was received via SCM rights and
302 #      added to the fd set.
304 # Since: 1.2
306 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
309 # @add-fd:
311 # Add a file descriptor, that was passed via SCM rights, to an fd set.
313 # @fdset-id: The ID of the fd set to add the file descriptor to.
315 # @opaque: A free-form string that can be used to describe the fd.
317 # Returns: - @AddfdInfo on success
318 #          - If file descriptor was not received, FdNotSupplied
319 #          - If @fdset-id is a negative value, InvalidParameterValue
321 # Notes: The list of fd sets is shared by all monitor connections.
323 #        If @fdset-id is not specified, a new fd set will be created.
325 # Since: 1.2
327 # Example:
329 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
330 # <- { "return": { "fdset-id": 1, "fd": 3 } }
333 { 'command': 'add-fd',
334   'data': { '*fdset-id': 'int',
335             '*opaque': 'str' },
336   'returns': 'AddfdInfo' }
339 # @remove-fd:
341 # Remove a file descriptor from an fd set.
343 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
345 # @fd: The file descriptor that is to be removed.
347 # Returns: - Nothing on success
348 #          - If @fdset-id or @fd is not found, FdNotFound
350 # Since: 1.2
352 # Notes: The list of fd sets is shared by all monitor connections.
354 #        If @fd is not specified, all file descriptors in @fdset-id
355 #        will be removed.
357 # Example:
359 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
360 # <- { "return": {} }
363 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
366 # @FdsetFdInfo:
368 # Information about a file descriptor that belongs to an fd set.
370 # @fd: The file descriptor value.
372 # @opaque: A free-form string that can be used to describe the fd.
374 # Since: 1.2
376 { 'struct': 'FdsetFdInfo',
377   'data': {'fd': 'int', '*opaque': 'str'} }
380 # @FdsetInfo:
382 # Information about an fd set.
384 # @fdset-id: The ID of the fd set.
386 # @fds: A list of file descriptors that belong to this fd set.
388 # Since: 1.2
390 { 'struct': 'FdsetInfo',
391   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
394 # @query-fdsets:
396 # Return information describing all fd sets.
398 # Returns: A list of @FdsetInfo
400 # Since: 1.2
402 # Note: The list of fd sets is shared by all monitor connections.
404 # Example:
406 # -> { "execute": "query-fdsets" }
407 # <- { "return": [
408 #        {
409 #          "fds": [
410 #            {
411 #              "fd": 30,
412 #              "opaque": "rdonly:/path/to/file"
413 #            },
414 #            {
415 #              "fd": 24,
416 #              "opaque": "rdwr:/path/to/file"
417 #            }
418 #          ],
419 #          "fdset-id": 1
420 #        },
421 #        {
422 #          "fds": [
423 #            {
424 #              "fd": 28
425 #            },
426 #            {
427 #              "fd": 29
428 #            }
429 #          ],
430 #          "fdset-id": 0
431 #        }
432 #      ]
433 #    }
436 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
439 # @CommandLineParameterType:
441 # Possible types for an option parameter.
443 # @string: accepts a character string
445 # @boolean: accepts "on" or "off"
447 # @number: accepts a number
449 # @size: accepts a number followed by an optional suffix (K)ilo,
450 #        (M)ega, (G)iga, (T)era
452 # Since: 1.5
454 { 'enum': 'CommandLineParameterType',
455   'data': ['string', 'boolean', 'number', 'size'] }
458 # @CommandLineParameterInfo:
460 # Details about a single parameter of a command line option.
462 # @name: parameter name
464 # @type: parameter @CommandLineParameterType
466 # @help: human readable text string, not suitable for parsing.
468 # @default: default value string (since 2.1)
470 # Since: 1.5
472 { 'struct': 'CommandLineParameterInfo',
473   'data': { 'name': 'str',
474             'type': 'CommandLineParameterType',
475             '*help': 'str',
476             '*default': 'str' } }
479 # @CommandLineOptionInfo:
481 # Details about a command line option, including its list of parameter details
483 # @option: option name
485 # @parameters: an array of @CommandLineParameterInfo
487 # Since: 1.5
489 { 'struct': 'CommandLineOptionInfo',
490   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
493 # @query-command-line-options:
495 # Query command line option schema.
497 # @option: option name
499 # Returns: list of @CommandLineOptionInfo for all options (or for the given
500 #          @option).  Returns an error if the given @option doesn't exist.
502 # Since: 1.5
504 # Example:
506 # -> { "execute": "query-command-line-options",
507 #      "arguments": { "option": "option-rom" } }
508 # <- { "return": [
509 #         {
510 #             "parameters": [
511 #                 {
512 #                     "name": "romfile",
513 #                     "type": "string"
514 #                 },
515 #                 {
516 #                     "name": "bootindex",
517 #                     "type": "number"
518 #                 }
519 #             ],
520 #             "option": "option-rom"
521 #         }
522 #      ]
523 #    }
526 {'command': 'query-command-line-options',
527  'data': { '*option': 'str' },
528  'returns': ['CommandLineOptionInfo'],
529  'allow-preconfig': true }
532 # @RTC_CHANGE:
534 # Emitted when the guest changes the RTC time.
536 # @offset: offset in seconds between base RTC clock (as specified
537 #          by -rtc base), and new RTC clock value
539 # @qom-path: path to the RTC object in the QOM tree
541 # Note: This event is rate-limited.
542 #       It is not guaranteed that the RTC in the system implements
543 #       this event, or even that the system has an RTC at all.
545 # Since: 0.13
547 # Example:
549 # <-   { "event": "RTC_CHANGE",
550 #        "data": { "offset": 78 },
551 #        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
554 { 'event': 'RTC_CHANGE',
555   'data': { 'offset': 'int', 'qom-path': 'str' } }