qapi: Indent tagged doc comment sections properly
[qemu/armbru.git] / qapi / misc.json
blob2ca8c39874994492086cf913676ab979eaaf31a4
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 character
15 # devices to be passed in to QEMU via SCM_RIGHTS.
17 # If the FD associated with @fdname is not a socket, the command will
18 # fail and the FD will be closed.
20 # @protocol: protocol name.  Valid names are "vnc", "spice",
21 #     "@dbus-display" or the name of a character device (e.g. from
22 #     -chardev id=XXXX)
24 # @fdname: file descriptor name previously passed via 'getfd' command
26 # @skipauth: whether to skip authentication.  Only applies to "vnc"
27 #     and "spice" protocols
29 # @tls: whether to perform TLS. Only applies to the "spice" protocol
31 # Returns: nothing on success.
33 # Since: 0.14
35 # Example:
37 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
38 #                                              "fdname": "myclient" } }
39 # <- { "return": {} }
41 { 'command': 'add_client',
42   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
43             '*tls': 'bool' } }
46 # @NameInfo:
48 # Guest name information.
50 # @name: The name of the guest
52 # Since: 0.14
54 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
57 # @query-name:
59 # Return the name information of a guest.
61 # Returns: @NameInfo of the guest
63 # Since: 0.14
65 # Example:
67 # -> { "execute": "query-name" }
68 # <- { "return": { "name": "qemu-name" } }
70 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
73 # @IOThreadInfo:
75 # Information about an iothread
77 # @id: the identifier of the iothread
79 # @thread-id: ID of the underlying host thread
81 # @poll-max-ns: maximum polling time in ns, 0 means polling is
82 #     disabled (since 2.9)
84 # @poll-grow: how many ns will be added to polling time, 0 means that
85 #     it's not configured (since 2.9)
87 # @poll-shrink: how many ns will be removed from polling time, 0 means
88 #     that it's not configured (since 2.9)
90 # @aio-max-batch: maximum number of requests in a batch for the AIO
91 #     engine, 0 means that the engine will use its default (since 6.1)
93 # Since: 2.0
95 { 'struct': 'IOThreadInfo',
96   'data': {'id': 'str',
97            'thread-id': 'int',
98            'poll-max-ns': 'int',
99            'poll-grow': 'int',
100            'poll-shrink': 'int',
101            'aio-max-batch': 'int' } }
104 # @query-iothreads:
106 # Returns a list of information about each iothread.
108 # Note: this list excludes the QEMU main loop thread, which is not
109 #     declared using the -object iothread command-line option.  It is
110 #     always the main thread of the process.
112 # Returns: a list of @IOThreadInfo for each iothread
114 # Since: 2.0
116 # Example:
118 # -> { "execute": "query-iothreads" }
119 # <- { "return": [
120 #          {
121 #             "id":"iothread0",
122 #             "thread-id":3134
123 #          },
124 #          {
125 #             "id":"iothread1",
126 #             "thread-id":3135
127 #          }
128 #       ]
129 #    }
131 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
132   'allow-preconfig': true }
135 # @stop:
137 # Stop guest VM execution.
139 # Since: 0.14
141 # Notes: This function will succeed even if the guest is already in
142 #     the stopped state.  In "inmigrate" state, it will ensure that
143 #     the guest remains paused once migration finishes, as if the -S
144 #     option was passed on the command line.
146 #     In the "suspended" state, it will completely stop the VM and
147 #     cause a transition to the "paused" state. (Since 9.0)
149 # Example:
151 # -> { "execute": "stop" }
152 # <- { "return": {} }
154 { 'command': 'stop' }
157 # @cont:
159 # Resume guest VM execution.
161 # Since: 0.14
163 # Returns: If successful, nothing
165 # Notes: This command will succeed if the guest is currently running.
166 #     It will also succeed if the guest is in the "inmigrate" state;
167 #     in this case, the effect of the command is to make sure the
168 #     guest starts once migration finishes, removing the effect of the
169 #     -S command line option if it was passed.
171 #     If the VM was previously suspended, and not been reset or woken,
172 #     this command will transition back to the "suspended" state.
173 #     (Since 9.0)
175 # Example:
177 # -> { "execute": "cont" }
178 # <- { "return": {} }
180 { 'command': 'cont' }
183 # @x-exit-preconfig:
185 # Exit from "preconfig" state
187 # This command makes QEMU exit the preconfig state and proceed with VM
188 # initialization using configuration data provided on the command line
189 # and via the QMP monitor during the preconfig state.  The command is
190 # only available during the preconfig state (i.e. when the --preconfig
191 # command line option was in use).
193 # Features:
195 # @unstable: This command is experimental.
197 # Since: 3.0
199 # Returns: nothing
201 # Example:
203 # -> { "execute": "x-exit-preconfig" }
204 # <- { "return": {} }
206 { 'command': 'x-exit-preconfig', 'allow-preconfig': true,
207   'features': [ 'unstable' ] }
210 # @human-monitor-command:
212 # Execute a command on the human monitor and return the output.
214 # @command-line: the command to execute in the human monitor
216 # @cpu-index: The CPU to use for commands that require an implicit CPU
218 # Features:
220 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
221 #     monitor-owned nodes if they have no parents.  This allows the
222 #     use of 'savevm' with -blockdev.  (since 4.2)
224 # Returns: the output of the command as a string
226 # Since: 0.14
228 # Notes: This command only exists as a stop-gap.  Its use is highly
229 #     discouraged.  The semantics of this command are not guaranteed:
230 #     this means that command names, arguments and responses can
231 #     change or be removed at ANY time.  Applications that rely on
232 #     long term stability guarantees should NOT use this command.
234 #     Known limitations:
236 #     * This command is stateless, this means that commands that
237 #       depend on state information (such as getfd) might not work
239 #     * Commands that prompt the user for data don't currently work
241 # Example:
243 # -> { "execute": "human-monitor-command",
244 #      "arguments": { "command-line": "info kvm" } }
245 # <- { "return": "kvm support: enabled\r\n" }
247 { 'command': 'human-monitor-command',
248   'data': {'command-line': 'str', '*cpu-index': 'int'},
249   'returns': 'str',
250   'features': [ 'savevm-monitor-nodes' ] }
253 # @getfd:
255 # Receive a file descriptor via SCM rights and assign it a name
257 # @fdname: file descriptor name
259 # Returns: Nothing on success
261 # Since: 0.14
263 # Notes: If @fdname already exists, the file descriptor assigned to it
264 #     will be closed and replaced by the received file descriptor.
266 #     The 'closefd' command can be used to explicitly close the file
267 #     descriptor when it is no longer needed.
269 # Example:
271 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
272 # <- { "return": {} }
274 { 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' }
277 # @get-win32-socket:
279 # Add a socket that was duplicated to QEMU process with
280 # WSADuplicateSocketW() via WSASocket() & WSAPROTOCOL_INFOW structure
281 # and assign it a name (the SOCKET is associated with a CRT file
282 # descriptor)
284 # @info: the WSAPROTOCOL_INFOW structure (encoded in base64)
286 # @fdname: file descriptor name
288 # Returns: Nothing on success
290 # Since: 8.0
292 # Notes: If @fdname already exists, the file descriptor assigned to it
293 #     will be closed and replaced by the received file descriptor.
295 #     The 'closefd' command can be used to explicitly close the file
296 #     descriptor when it is no longer needed.
298 # Example:
300 # -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } }
301 # <- { "return": {} }
303 { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
306 # @closefd:
308 # Close a file descriptor previously passed via SCM rights
310 # @fdname: file descriptor name
312 # Returns: Nothing on success
314 # Since: 0.14
316 # Example:
318 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
319 # <- { "return": {} }
321 { 'command': 'closefd', 'data': {'fdname': 'str'} }
324 # @AddfdInfo:
326 # Information about a file descriptor that was added to an fd set.
328 # @fdset-id: The ID of the fd set that @fd was added to.
330 # @fd: The file descriptor that was received via SCM rights and added
331 #     to the fd set.
333 # Since: 1.2
335 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
338 # @add-fd:
340 # Add a file descriptor, that was passed via SCM rights, to an fd set.
342 # @fdset-id: The ID of the fd set to add the file descriptor to.
344 # @opaque: A free-form string that can be used to describe the fd.
346 # Returns:
347 #     - @AddfdInfo on success
348 #     - If file descriptor was not received, GenericError
349 #     - If @fdset-id is a negative value, GenericError
351 # Notes: The list of fd sets is shared by all monitor connections.
353 # If @fdset-id is not specified, a new fd set will be created.
355 # Since: 1.2
357 # Example:
359 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
360 # <- { "return": { "fdset-id": 1, "fd": 3 } }
362 { 'command': 'add-fd',
363   'data': { '*fdset-id': 'int',
364             '*opaque': 'str' },
365   'returns': 'AddfdInfo' }
368 # @remove-fd:
370 # Remove a file descriptor from an fd set.
372 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
374 # @fd: The file descriptor that is to be removed.
376 # Returns:
377 #     - Nothing on success
378 #     - If @fdset-id or @fd is not found, GenericError
380 # Since: 1.2
382 # Notes: The list of fd sets is shared by all monitor connections.
384 # If @fd is not specified, all file descriptors in @fdset-id will be
385 # removed.
387 # Example:
389 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
390 # <- { "return": {} }
392 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
395 # @FdsetFdInfo:
397 # Information about a file descriptor that belongs to an fd set.
399 # @fd: The file descriptor value.
401 # @opaque: A free-form string that can be used to describe the fd.
403 # Since: 1.2
405 { 'struct': 'FdsetFdInfo',
406   'data': {'fd': 'int', '*opaque': 'str'} }
409 # @FdsetInfo:
411 # Information about an fd set.
413 # @fdset-id: The ID of the fd set.
415 # @fds: A list of file descriptors that belong to this fd set.
417 # Since: 1.2
419 { 'struct': 'FdsetInfo',
420   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
423 # @query-fdsets:
425 # Return information describing all fd sets.
427 # Returns: A list of @FdsetInfo
429 # Since: 1.2
431 # Note: The list of fd sets is shared by all monitor connections.
433 # Example:
435 # -> { "execute": "query-fdsets" }
436 # <- { "return": [
437 #        {
438 #          "fds": [
439 #            {
440 #              "fd": 30,
441 #              "opaque": "rdonly:/path/to/file"
442 #            },
443 #            {
444 #              "fd": 24,
445 #              "opaque": "rdwr:/path/to/file"
446 #            }
447 #          ],
448 #          "fdset-id": 1
449 #        },
450 #        {
451 #          "fds": [
452 #            {
453 #              "fd": 28
454 #            },
455 #            {
456 #              "fd": 29
457 #            }
458 #          ],
459 #          "fdset-id": 0
460 #        }
461 #      ]
462 #    }
464 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
467 # @CommandLineParameterType:
469 # Possible types for an option parameter.
471 # @string: accepts a character string
473 # @boolean: accepts "on" or "off"
475 # @number: accepts a number
477 # @size: accepts a number followed by an optional suffix (K)ilo,
478 #     (M)ega, (G)iga, (T)era
480 # Since: 1.5
482 { 'enum': 'CommandLineParameterType',
483   'data': ['string', 'boolean', 'number', 'size'] }
486 # @CommandLineParameterInfo:
488 # Details about a single parameter of a command line option.
490 # @name: parameter name
492 # @type: parameter @CommandLineParameterType
494 # @help: human readable text string, not suitable for parsing.
496 # @default: default value string (since 2.1)
498 # Since: 1.5
500 { 'struct': 'CommandLineParameterInfo',
501   'data': { 'name': 'str',
502             'type': 'CommandLineParameterType',
503             '*help': 'str',
504             '*default': 'str' } }
507 # @CommandLineOptionInfo:
509 # Details about a command line option, including its list of parameter
510 # details
512 # @option: option name
514 # @parameters: an array of @CommandLineParameterInfo
516 # Since: 1.5
518 { 'struct': 'CommandLineOptionInfo',
519   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
522 # @query-command-line-options:
524 # Query command line option schema.
526 # @option: option name
528 # Returns: list of @CommandLineOptionInfo for all options (or for the
529 #     given @option).  Returns an error if the given @option doesn't
530 #     exist.
532 # Since: 1.5
534 # Example:
536 # -> { "execute": "query-command-line-options",
537 #      "arguments": { "option": "option-rom" } }
538 # <- { "return": [
539 #         {
540 #             "parameters": [
541 #                 {
542 #                     "name": "romfile",
543 #                     "type": "string"
544 #                 },
545 #                 {
546 #                     "name": "bootindex",
547 #                     "type": "number"
548 #                 }
549 #             ],
550 #             "option": "option-rom"
551 #         }
552 #      ]
553 #    }
555 {'command': 'query-command-line-options',
556  'data': {'*option': 'str'},
557  'returns': ['CommandLineOptionInfo'],
558  'allow-preconfig': true}
561 # @RTC_CHANGE:
563 # Emitted when the guest changes the RTC time.
565 # @offset: offset in seconds between base RTC clock (as specified by
566 #     -rtc base), and new RTC clock value
568 # @qom-path: path to the RTC object in the QOM tree
570 # Note: This event is rate-limited.  It is not guaranteed that the RTC
571 #     in the system implements this event, or even that the system has
572 #     an RTC at all.
574 # Since: 0.13
576 # Example:
578 # <- { "event": "RTC_CHANGE",
579 #      "data": { "offset": 78 },
580 #      "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
582 { 'event': 'RTC_CHANGE',
583   'data': { 'offset': 'int', 'qom-path': 'str' } }
586 # @VFU_CLIENT_HANGUP:
588 # Emitted when the client of a TYPE_VFIO_USER_SERVER closes the
589 # communication channel
591 # @vfu-id: ID of the TYPE_VFIO_USER_SERVER object.  It is the last
592 #     component of @vfu-qom-path referenced below
594 # @vfu-qom-path: path to the TYPE_VFIO_USER_SERVER object in the QOM
595 #     tree
597 # @dev-id: ID of attached PCI device
599 # @dev-qom-path: path to attached PCI device in the QOM tree
601 # Since: 7.1
603 # Example:
605 # <- { "event": "VFU_CLIENT_HANGUP",
606 #      "data": { "vfu-id": "vfu1",
607 #                "vfu-qom-path": "/objects/vfu1",
608 #                "dev-id": "sas1",
609 #                "dev-qom-path": "/machine/peripheral/sas1" },
610 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
612 { 'event': 'VFU_CLIENT_HANGUP',
613   'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str',
614             'dev-id': 'str', 'dev-qom-path': 'str' } }