qapi: Restrict Xen migration commands to migration.json
[qemu.git] / qapi / misc.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
4
5 ##
6 # = Miscellanea
7 ##
8
9 { 'include': 'common.json' }
10
11 ##
12 # @add_client:
13 #
14 # Allow client connections for VNC, Spice and socket based
15 # character devices to be passed in to QEMU via SCM_RIGHTS.
16 #
17 # @protocol: protocol name. Valid names are "vnc", "spice" or the
18 #            name of a character device (eg. from -chardev id=XXXX)
19 #
20 # @fdname: file descriptor name previously passed via 'getfd' command
21 #
22 # @skipauth: whether to skip authentication. Only applies
23 #            to "vnc" and "spice" protocols
24 #
25 # @tls: whether to perform TLS. Only applies to the "spice"
26 #       protocol
27 #
28 # Returns: nothing on success.
29 #
30 # Since: 0.14.0
31 #
32 # Example:
33 #
34 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
35 #                                              "fdname": "myclient" } }
36 # <- { "return": {} }
37 #
38 ##
39 { 'command': 'add_client',
40   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
41             '*tls': 'bool' } }
42
43 ##
44 # @NameInfo:
45 #
46 # Guest name information.
47 #
48 # @name: The name of the guest
49 #
50 # Since: 0.14.0
51 ##
52 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
53
54 ##
55 # @query-name:
56 #
57 # Return the name information of a guest.
58 #
59 # Returns: @NameInfo of the guest
60 #
61 # Since: 0.14.0
62 #
63 # Example:
64 #
65 # -> { "execute": "query-name" }
66 # <- { "return": { "name": "qemu-name" } }
67 #
68 ##
69 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
70
71 ##
72 # @IOThreadInfo:
73 #
74 # Information about an iothread
75 #
76 # @id: the identifier of the iothread
77 #
78 # @thread-id: ID of the underlying host thread
79 #
80 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
81 #               (since 2.9)
82 #
83 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
84 #             configured (since 2.9)
85 #
86 # @poll-shrink: how many ns will be removed from polling time, 0 means that
87 #               it's not configured (since 2.9)
88 #
89 # Since: 2.0
90 ##
91 { 'struct': 'IOThreadInfo',
92   'data': {'id': 'str',
93            'thread-id': 'int',
94            'poll-max-ns': 'int',
95            'poll-grow': 'int',
96            'poll-shrink': 'int' } }
97
98 ##
99 # @query-iothreads:
100 #
101 # Returns a list of information about each iothread.
102 #
103 # Note: this list excludes the QEMU main loop thread, which is not declared
104 #       using the -object iothread command-line option.  It is always the main thread
105 #       of the process.
106 #
107 # Returns: a list of @IOThreadInfo for each iothread
108 #
109 # Since: 2.0
110 #
111 # Example:
112 #
113 # -> { "execute": "query-iothreads" }
114 # <- { "return": [
115 #          {
116 #             "id":"iothread0",
117 #             "thread-id":3134
118 #          },
119 #          {
120 #             "id":"iothread1",
121 #             "thread-id":3135
122 #          }
123 #       ]
124 #    }
125 #
126 ##
127 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
128   'allow-preconfig': true }
129
130 ##
131 # @stop:
132 #
133 # Stop all guest VCPU execution.
134 #
135 # Since:  0.14.0
136 #
137 # Notes: This function will succeed even if the guest is already in the stopped
138 #        state.  In "inmigrate" state, it will ensure that the guest
139 #        remains paused once migration finishes, as if the -S option was
140 #        passed on the command line.
141 #
142 # Example:
143 #
144 # -> { "execute": "stop" }
145 # <- { "return": {} }
146 #
147 ##
148 { 'command': 'stop' }
149
150 ##
151 # @cont:
152 #
153 # Resume guest VCPU execution.
154 #
155 # Since:  0.14.0
156 #
157 # Returns:  If successful, nothing
158 #
159 # Notes: This command will succeed if the guest is currently running.  It
160 #        will also succeed if the guest is in the "inmigrate" state; in
161 #        this case, the effect of the command is to make sure the guest
162 #        starts once migration finishes, removing the effect of the -S
163 #        command line option if it was passed.
164 #
165 # Example:
166 #
167 # -> { "execute": "cont" }
168 # <- { "return": {} }
169 #
170 ##
171 { 'command': 'cont' }
172
173 ##
174 # @x-exit-preconfig:
175 #
176 # Exit from "preconfig" state
177 #
178 # This command makes QEMU exit the preconfig state and proceed with
179 # VM initialization using configuration data provided on the command line
180 # and via the QMP monitor during the preconfig state. The command is only
181 # available during the preconfig state (i.e. when the --preconfig command
182 # line option was in use).
183 #
184 # Since 3.0
185 #
186 # Returns: nothing
187 #
188 # Example:
189 #
190 # -> { "execute": "x-exit-preconfig" }
191 # <- { "return": {} }
192 #
193 ##
194 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }
195
196 ##
197 # @human-monitor-command:
198 #
199 # Execute a command on the human monitor and return the output.
200 #
201 # @command-line: the command to execute in the human monitor
202 #
203 # @cpu-index: The CPU to use for commands that require an implicit CPU
204 #
205 # Features:
206 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
207 #                        monitor-owned nodes if they have no parents.
208 #                        This allows the use of 'savevm' with
209 #                        -blockdev. (since 4.2)
210 #
211 # Returns: the output of the command as a string
212 #
213 # Since: 0.14.0
214 #
215 # Notes: This command only exists as a stop-gap.  Its use is highly
216 #        discouraged.  The semantics of this command are not
217 #        guaranteed: this means that command names, arguments and
218 #        responses can change or be removed at ANY time.  Applications
219 #        that rely on long term stability guarantees should NOT
220 #        use this command.
221 #
222 #        Known limitations:
223 #
224 #        * This command is stateless, this means that commands that depend
225 #          on state information (such as getfd) might not work
226 #
227 #        * Commands that prompt the user for data don't currently work
228 #
229 # Example:
230 #
231 # -> { "execute": "human-monitor-command",
232 #      "arguments": { "command-line": "info kvm" } }
233 # <- { "return": "kvm support: enabled\r\n" }
234 #
235 ##
236 { 'command': 'human-monitor-command',
237   'data': {'command-line': 'str', '*cpu-index': 'int'},
238   'returns': 'str',
239   'features': [ 'savevm-monitor-nodes' ] }
240
241 ##
242 # @change:
243 #
244 # This command is multiple commands multiplexed together.
245 #
246 # @device: This is normally the name of a block device but it may also be 'vnc'.
247 #          when it's 'vnc', then sub command depends on @target
248 #
249 # @target: If @device is a block device, then this is the new filename.
250 #          If @device is 'vnc', then if the value 'password' selects the vnc
251 #          change password command.   Otherwise, this specifies a new server URI
252 #          address to listen to for VNC connections.
253 #
254 # @arg: If @device is a block device, then this is an optional format to open
255 #       the device with.
256 #       If @device is 'vnc' and @target is 'password', this is the new VNC
257 #       password to set.  See change-vnc-password for additional notes.
258 #
259 # Features:
260 # @deprecated: This command is deprecated.  For changing block
261 #              devices, use 'blockdev-change-medium' instead; for changing VNC
262 #              parameters, use 'change-vnc-password' instead.
263 #
264 # Returns: - Nothing on success.
265 #          - If @device is not a valid block device, DeviceNotFound
266 #
267 # Since: 0.14.0
268 #
269 # Example:
270 #
271 # 1. Change a removable medium
272 #
273 # -> { "execute": "change",
274 #      "arguments": { "device": "ide1-cd0",
275 #                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
276 # <- { "return": {} }
277 #
278 # 2. Change VNC password
279 #
280 # -> { "execute": "change",
281 #      "arguments": { "device": "vnc", "target": "password",
282 #                     "arg": "foobar1" } }
283 # <- { "return": {} }
284 #
285 ##
286 { 'command': 'change',
287   'data': {'device': 'str', 'target': 'str', '*arg': 'str'},
288   'features': [ 'deprecated' ] }
289
290 ##
291 # @getfd:
292 #
293 # Receive a file descriptor via SCM rights and assign it a name
294 #
295 # @fdname: file descriptor name
296 #
297 # Returns: Nothing on success
298 #
299 # Since: 0.14.0
300 #
301 # Notes: If @fdname already exists, the file descriptor assigned to
302 #        it will be closed and replaced by the received file
303 #        descriptor.
304 #
305 #        The 'closefd' command can be used to explicitly close the
306 #        file descriptor when it is no longer needed.
307 #
308 # Example:
309 #
310 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
311 # <- { "return": {} }
312 #
313 ##
314 { 'command': 'getfd', 'data': {'fdname': 'str'} }
315
316 ##
317 # @closefd:
318 #
319 # Close a file descriptor previously passed via SCM rights
320 #
321 # @fdname: file descriptor name
322 #
323 # Returns: Nothing on success
324 #
325 # Since: 0.14.0
326 #
327 # Example:
328 #
329 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
330 # <- { "return": {} }
331 #
332 ##
333 { 'command': 'closefd', 'data': {'fdname': 'str'} }
334
335 ##
336 # @AddfdInfo:
337 #
338 # Information about a file descriptor that was added to an fd set.
339 #
340 # @fdset-id: The ID of the fd set that @fd was added to.
341 #
342 # @fd: The file descriptor that was received via SCM rights and
343 #      added to the fd set.
344 #
345 # Since: 1.2.0
346 ##
347 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
348
349 ##
350 # @add-fd:
351 #
352 # Add a file descriptor, that was passed via SCM rights, to an fd set.
353 #
354 # @fdset-id: The ID of the fd set to add the file descriptor to.
355 #
356 # @opaque: A free-form string that can be used to describe the fd.
357 #
358 # Returns: - @AddfdInfo on success
359 #          - If file descriptor was not received, FdNotSupplied
360 #          - If @fdset-id is a negative value, InvalidParameterValue
361 #
362 # Notes: The list of fd sets is shared by all monitor connections.
363 #
364 #        If @fdset-id is not specified, a new fd set will be created.
365 #
366 # Since: 1.2.0
367 #
368 # Example:
369 #
370 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
371 # <- { "return": { "fdset-id": 1, "fd": 3 } }
372 #
373 ##
374 { 'command': 'add-fd',
375   'data': { '*fdset-id': 'int',
376             '*opaque': 'str' },
377   'returns': 'AddfdInfo' }
378
379 ##
380 # @remove-fd:
381 #
382 # Remove a file descriptor from an fd set.
383 #
384 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
385 #
386 # @fd: The file descriptor that is to be removed.
387 #
388 # Returns: - Nothing on success
389 #          - If @fdset-id or @fd is not found, FdNotFound
390 #
391 # Since: 1.2.0
392 #
393 # Notes: The list of fd sets is shared by all monitor connections.
394 #
395 #        If @fd is not specified, all file descriptors in @fdset-id
396 #        will be removed.
397 #
398 # Example:
399 #
400 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
401 # <- { "return": {} }
402 #
403 ##
404 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
405
406 ##
407 # @FdsetFdInfo:
408 #
409 # Information about a file descriptor that belongs to an fd set.
410 #
411 # @fd: The file descriptor value.
412 #
413 # @opaque: A free-form string that can be used to describe the fd.
414 #
415 # Since: 1.2.0
416 ##
417 { 'struct': 'FdsetFdInfo',
418   'data': {'fd': 'int', '*opaque': 'str'} }
419
420 ##
421 # @FdsetInfo:
422 #
423 # Information about an fd set.
424 #
425 # @fdset-id: The ID of the fd set.
426 #
427 # @fds: A list of file descriptors that belong to this fd set.
428 #
429 # Since: 1.2.0
430 ##
431 { 'struct': 'FdsetInfo',
432   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
433
434 ##
435 # @query-fdsets:
436 #
437 # Return information describing all fd sets.
438 #
439 # Returns: A list of @FdsetInfo
440 #
441 # Since: 1.2.0
442 #
443 # Note: The list of fd sets is shared by all monitor connections.
444 #
445 # Example:
446 #
447 # -> { "execute": "query-fdsets" }
448 # <- { "return": [
449 #        {
450 #          "fds": [
451 #            {
452 #              "fd": 30,
453 #              "opaque": "rdonly:/path/to/file"
454 #            },
455 #            {
456 #              "fd": 24,
457 #              "opaque": "rdwr:/path/to/file"
458 #            }
459 #          ],
460 #          "fdset-id": 1
461 #        },
462 #        {
463 #          "fds": [
464 #            {
465 #              "fd": 28
466 #            },
467 #            {
468 #              "fd": 29
469 #            }
470 #          ],
471 #          "fdset-id": 0
472 #        }
473 #      ]
474 #    }
475 #
476 ##
477 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
478
479 ##
480 # @CommandLineParameterType:
481 #
482 # Possible types for an option parameter.
483 #
484 # @string: accepts a character string
485 #
486 # @boolean: accepts "on" or "off"
487 #
488 # @number: accepts a number
489 #
490 # @size: accepts a number followed by an optional suffix (K)ilo,
491 #        (M)ega, (G)iga, (T)era
492 #
493 # Since: 1.5
494 ##
495 { 'enum': 'CommandLineParameterType',
496   'data': ['string', 'boolean', 'number', 'size'] }
497
498 ##
499 # @CommandLineParameterInfo:
500 #
501 # Details about a single parameter of a command line option.
502 #
503 # @name: parameter name
504 #
505 # @type: parameter @CommandLineParameterType
506 #
507 # @help: human readable text string, not suitable for parsing.
508 #
509 # @default: default value string (since 2.1)
510 #
511 # Since: 1.5
512 ##
513 { 'struct': 'CommandLineParameterInfo',
514   'data': { 'name': 'str',
515             'type': 'CommandLineParameterType',
516             '*help': 'str',
517             '*default': 'str' } }
518
519 ##
520 # @CommandLineOptionInfo:
521 #
522 # Details about a command line option, including its list of parameter details
523 #
524 # @option: option name
525 #
526 # @parameters: an array of @CommandLineParameterInfo
527 #
528 # Since: 1.5
529 ##
530 { 'struct': 'CommandLineOptionInfo',
531   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
532
533 ##
534 # @query-command-line-options:
535 #
536 # Query command line option schema.
537 #
538 # @option: option name
539 #
540 # Returns: list of @CommandLineOptionInfo for all options (or for the given
541 #          @option).  Returns an error if the given @option doesn't exist.
542 #
543 # Since: 1.5
544 #
545 # Example:
546 #
547 # -> { "execute": "query-command-line-options",
548 #      "arguments": { "option": "option-rom" } }
549 # <- { "return": [
550 #         {
551 #             "parameters": [
552 #                 {
553 #                     "name": "romfile",
554 #                     "type": "string"
555 #                 },
556 #                 {
557 #                     "name": "bootindex",
558 #                     "type": "number"
559 #                 }
560 #             ],
561 #             "option": "option-rom"
562 #         }
563 #      ]
564 #    }
565 #
566 ##
567 {'command': 'query-command-line-options',
568  'data': { '*option': 'str' },
569  'returns': ['CommandLineOptionInfo'],
570  'allow-preconfig': true }