hw/arm/virt: pass VirtMachineState instead of VirtGuestInfo
[qemu.git] / qapi-schema.json
1 # -*- Mode: Python -*-
2 #
3 # QAPI Schema
4
5 # QAPI common definitions
6 { 'include': 'qapi/common.json' }
7
8 # QAPI crypto definitions
9 { 'include': 'qapi/crypto.json' }
10
11 # QAPI block definitions
12 { 'include': 'qapi/block.json' }
13
14 # QAPI event definitions
15 { 'include': 'qapi/event.json' }
16
17 # Tracing commands
18 { 'include': 'qapi/trace.json' }
19
20 # QAPI introspection
21 { 'include': 'qapi/introspect.json' }
22
23 ##
24 # @qmp_capabilities:
25 #
26 # Enable QMP capabilities.
27 #
28 # Arguments: None.
29 #
30 # Example:
31 #
32 # -> { "execute": "qmp_capabilities" }
33 # <- { "return": {} }
34 #
35 # Notes: This command is valid exactly when first connecting: it must be
36 # issued before any other command will be accepted, and will fail once the
37 # monitor is accepting other commands. (see qemu docs/qmp-spec.txt)
38 #
39 # Since: 0.13
40 #
41 ##
42 { 'command': 'qmp_capabilities' }
43
44 ##
45 # @LostTickPolicy:
46 #
47 # Policy for handling lost ticks in timer devices.
48 #
49 # @discard: throw away the missed tick(s) and continue with future injection
50 #           normally.  Guest time may be delayed, unless the OS has explicit
51 #           handling of lost ticks
52 #
53 # @delay: continue to deliver ticks at the normal rate.  Guest time will be
54 #         delayed due to the late tick
55 #
56 # @merge: merge the missed tick(s) into one tick and inject.  Guest time
57 #         may be delayed, depending on how the OS reacts to the merging
58 #         of ticks
59 #
60 # @slew: deliver ticks at a higher rate to catch up with the missed tick. The
61 #        guest time should not be delayed once catchup is complete.
62 #
63 # Since: 2.0
64 ##
65 { 'enum': 'LostTickPolicy',
66   'data': ['discard', 'delay', 'merge', 'slew' ] }
67
68 ##
69 # @add_client:
70 #
71 # Allow client connections for VNC, Spice and socket based
72 # character devices to be passed in to QEMU via SCM_RIGHTS.
73 #
74 # @protocol: protocol name. Valid names are "vnc", "spice" or the
75 #            name of a character device (eg. from -chardev id=XXXX)
76 #
77 # @fdname: file descriptor name previously passed via 'getfd' command
78 #
79 # @skipauth: #optional whether to skip authentication. Only applies
80 #            to "vnc" and "spice" protocols
81 #
82 # @tls: #optional whether to perform TLS. Only applies to the "spice"
83 #       protocol
84 #
85 # Returns: nothing on success.
86 #
87 # Since: 0.14.0
88 ##
89 { 'command': 'add_client',
90   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
91             '*tls': 'bool' } }
92
93 ##
94 # @NameInfo:
95 #
96 # Guest name information.
97 #
98 # @name: #optional The name of the guest
99 #
100 # Since: 0.14.0
101 ##
102 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
103
104 ##
105 # @query-name:
106 #
107 # Return the name information of a guest.
108 #
109 # Returns: @NameInfo of the guest
110 #
111 # Since: 0.14.0
112 ##
113 { 'command': 'query-name', 'returns': 'NameInfo' }
114
115 ##
116 # @KvmInfo:
117 #
118 # Information about support for KVM acceleration
119 #
120 # @enabled: true if KVM acceleration is active
121 #
122 # @present: true if KVM acceleration is built into this executable
123 #
124 # Since: 0.14.0
125 ##
126 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
127
128 ##
129 # @query-kvm:
130 #
131 # Returns information about KVM acceleration
132 #
133 # Returns: @KvmInfo
134 #
135 # Since: 0.14.0
136 ##
137 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
138
139 ##
140 # @RunState:
141 #
142 # An enumeration of VM run states.
143 #
144 # @debug: QEMU is running on a debugger
145 #
146 # @finish-migrate: guest is paused to finish the migration process
147 #
148 # @inmigrate: guest is paused waiting for an incoming migration.  Note
149 # that this state does not tell whether the machine will start at the
150 # end of the migration.  This depends on the command-line -S option and
151 # any invocation of 'stop' or 'cont' that has happened since QEMU was
152 # started.
153 #
154 # @internal-error: An internal error that prevents further guest execution
155 # has occurred
156 #
157 # @io-error: the last IOP has failed and the device is configured to pause
158 # on I/O errors
159 #
160 # @paused: guest has been paused via the 'stop' command
161 #
162 # @postmigrate: guest is paused following a successful 'migrate'
163 #
164 # @prelaunch: QEMU was started with -S and guest has not started
165 #
166 # @restore-vm: guest is paused to restore VM state
167 #
168 # @running: guest is actively running
169 #
170 # @save-vm: guest is paused to save the VM state
171 #
172 # @shutdown: guest is shut down (and -no-shutdown is in use)
173 #
174 # @suspended: guest is suspended (ACPI S3)
175 #
176 # @watchdog: the watchdog action is configured to pause and has been triggered
177 #
178 # @guest-panicked: guest has been panicked as a result of guest OS panic
179 #
180 # @colo: guest is paused to save/restore VM state under colo checkpoint,
181 #        VM can not get into this state unless colo capability is enabled
182 #        for migration. (since 2.8)
183 ##
184 { 'enum': 'RunState',
185   'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
186             'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
187             'running', 'save-vm', 'shutdown', 'suspended', 'watchdog',
188             'guest-panicked', 'colo' ] }
189
190 ##
191 # @StatusInfo:
192 #
193 # Information about VCPU run state
194 #
195 # @running: true if all VCPUs are runnable, false if not runnable
196 #
197 # @singlestep: true if VCPUs are in single-step mode
198 #
199 # @status: the virtual machine @RunState
200 #
201 # Since:  0.14.0
202 #
203 # Notes: @singlestep is enabled through the GDB stub
204 ##
205 { 'struct': 'StatusInfo',
206   'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
207
208 ##
209 # @query-status:
210 #
211 # Query the run status of all VCPUs
212 #
213 # Returns: @StatusInfo reflecting all VCPUs
214 #
215 # Since:  0.14.0
216 ##
217 { 'command': 'query-status', 'returns': 'StatusInfo' }
218
219 ##
220 # @UuidInfo:
221 #
222 # Guest UUID information.
223 #
224 # @UUID: the UUID of the guest
225 #
226 # Since: 0.14.0
227 #
228 # Notes: If no UUID was specified for the guest, a null UUID is returned.
229 ##
230 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
231
232 ##
233 # @query-uuid:
234 #
235 # Query the guest UUID information.
236 #
237 # Returns: The @UuidInfo for the guest
238 #
239 # Since: 0.14.0
240 ##
241 { 'command': 'query-uuid', 'returns': 'UuidInfo' }
242
243 ##
244 # @ChardevInfo:
245 #
246 # Information about a character device.
247 #
248 # @label: the label of the character device
249 #
250 # @filename: the filename of the character device
251 #
252 # @frontend-open: shows whether the frontend device attached to this backend
253 #                 (eg. with the chardev=... option) is in open or closed state
254 #                 (since 2.1)
255 #
256 # Notes: @filename is encoded using the QEMU command line character device
257 #        encoding.  See the QEMU man page for details.
258 #
259 # Since: 0.14.0
260 ##
261 { 'struct': 'ChardevInfo', 'data': {'label': 'str',
262                                   'filename': 'str',
263                                   'frontend-open': 'bool'} }
264
265 ##
266 # @query-chardev:
267 #
268 # Returns information about current character devices.
269 #
270 # Returns: a list of @ChardevInfo
271 #
272 # Since: 0.14.0
273 ##
274 { 'command': 'query-chardev', 'returns': ['ChardevInfo'] }
275
276 ##
277 # @ChardevBackendInfo:
278 #
279 # Information about a character device backend
280 #
281 # @name: The backend name
282 #
283 # Since: 2.0
284 ##
285 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
286
287 ##
288 # @query-chardev-backends:
289 #
290 # Returns information about character device backends.
291 #
292 # Returns: a list of @ChardevBackendInfo
293 #
294 # Since: 2.0
295 ##
296 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
297
298 ##
299 # @DataFormat:
300 #
301 # An enumeration of data format.
302 #
303 # @utf8: Data is a UTF-8 string (RFC 3629)
304 #
305 # @base64: Data is Base64 encoded binary (RFC 3548)
306 #
307 # Since: 1.4
308 ##
309 { 'enum': 'DataFormat',
310   'data': [ 'utf8', 'base64' ] }
311
312 ##
313 # @ringbuf-write:
314 #
315 # Write to a ring buffer character device.
316 #
317 # @device: the ring buffer character device name
318 #
319 # @data: data to write
320 #
321 # @format: #optional data encoding (default 'utf8').
322 #          - base64: data must be base64 encoded text.  Its binary
323 #            decoding gets written.
324 #          - utf8: data's UTF-8 encoding is written
325 #          - data itself is always Unicode regardless of format, like
326 #            any other string.
327 #
328 # Returns: Nothing on success
329 #
330 # Since: 1.4
331 ##
332 { 'command': 'ringbuf-write',
333   'data': {'device': 'str', 'data': 'str',
334            '*format': 'DataFormat'} }
335
336 ##
337 # @ringbuf-read:
338 #
339 # Read from a ring buffer character device.
340 #
341 # @device: the ring buffer character device name
342 #
343 # @size: how many bytes to read at most
344 #
345 # @format: #optional data encoding (default 'utf8').
346 #          - base64: the data read is returned in base64 encoding.
347 #          - utf8: the data read is interpreted as UTF-8.
348 #            Bug: can screw up when the buffer contains invalid UTF-8
349 #            sequences, NUL characters, after the ring buffer lost
350 #            data, and when reading stops because the size limit is
351 #            reached.
352 #          - The return value is always Unicode regardless of format,
353 #            like any other string.
354 #
355 # Returns: data read from the device
356 #
357 # Since: 1.4
358 ##
359 { 'command': 'ringbuf-read',
360   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
361   'returns': 'str' }
362
363 ##
364 # @EventInfo:
365 #
366 # Information about a QMP event
367 #
368 # @name: The event name
369 #
370 # Since: 1.2.0
371 ##
372 { 'struct': 'EventInfo', 'data': {'name': 'str'} }
373
374 ##
375 # @query-events:
376 #
377 # Return a list of supported QMP events by this server
378 #
379 # Returns: A list of @EventInfo for all supported events
380 #
381 # Since: 1.2.0
382 ##
383 { 'command': 'query-events', 'returns': ['EventInfo'] }
384
385 ##
386 # @MigrationStats:
387 #
388 # Detailed migration status.
389 #
390 # @transferred: amount of bytes already transferred to the target VM
391 #
392 # @remaining: amount of bytes remaining to be transferred to the target VM
393 #
394 # @total: total amount of bytes involved in the migration process
395 #
396 # @duplicate: number of duplicate (zero) pages (since 1.2)
397 #
398 # @skipped: number of skipped zero pages (since 1.5)
399 #
400 # @normal: number of normal pages (since 1.2)
401 #
402 # @normal-bytes: number of normal bytes sent (since 1.2)
403 #
404 # @dirty-pages-rate: number of pages dirtied by second by the
405 #        guest (since 1.3)
406 #
407 # @mbps: throughput in megabits/sec. (since 1.6)
408 #
409 # @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
410 #
411 # @postcopy-requests: The number of page requests received from the destination
412 #        (since 2.7)
413 #
414 # Since: 0.14.0
415 ##
416 { 'struct': 'MigrationStats',
417   'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
418            'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
419            'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
420            'mbps' : 'number', 'dirty-sync-count' : 'int',
421            'postcopy-requests' : 'int' } }
422
423 ##
424 # @XBZRLECacheStats:
425 #
426 # Detailed XBZRLE migration cache statistics
427 #
428 # @cache-size: XBZRLE cache size
429 #
430 # @bytes: amount of bytes already transferred to the target VM
431 #
432 # @pages: amount of pages transferred to the target VM
433 #
434 # @cache-miss: number of cache miss
435 #
436 # @cache-miss-rate: rate of cache miss (since 2.1)
437 #
438 # @overflow: number of overflows
439 #
440 # Since: 1.2
441 ##
442 { 'struct': 'XBZRLECacheStats',
443   'data': {'cache-size': 'int', 'bytes': 'int', 'pages': 'int',
444            'cache-miss': 'int', 'cache-miss-rate': 'number',
445            'overflow': 'int' } }
446
447 ##
448 # @MigrationStatus:
449 #
450 # An enumeration of migration status.
451 #
452 # @none: no migration has ever happened.
453 #
454 # @setup: migration process has been initiated.
455 #
456 # @cancelling: in the process of cancelling migration.
457 #
458 # @cancelled: cancelling migration is finished.
459 #
460 # @active: in the process of doing migration.
461 #
462 # @postcopy-active: like active, but now in postcopy mode. (since 2.5)
463 #
464 # @completed: migration is finished.
465 #
466 # @failed: some error occurred during migration process.
467 #
468 # @colo: VM is in the process of fault tolerance, VM can not get into this
469 #        state unless colo capability is enabled for migration. (since 2.8)
470 #
471 # Since: 2.3
472 #
473 ##
474 { 'enum': 'MigrationStatus',
475   'data': [ 'none', 'setup', 'cancelling', 'cancelled',
476             'active', 'postcopy-active', 'completed', 'failed', 'colo' ] }
477
478 ##
479 # @MigrationInfo:
480 #
481 # Information about current migration process.
482 #
483 # @status: #optional @MigrationStatus describing the current migration status.
484 #          If this field is not returned, no migration process
485 #          has been initiated
486 #
487 # @ram: #optional @MigrationStats containing detailed migration
488 #       status, only returned if status is 'active' or
489 #       'completed'(since 1.2)
490 #
491 # @disk: #optional @MigrationStats containing detailed disk migration
492 #        status, only returned if status is 'active' and it is a block
493 #        migration
494 #
495 # @xbzrle-cache: #optional @XBZRLECacheStats containing detailed XBZRLE
496 #                migration statistics, only returned if XBZRLE feature is on and
497 #                status is 'active' or 'completed' (since 1.2)
498 #
499 # @total-time: #optional total amount of milliseconds since migration started.
500 #        If migration has ended, it returns the total migration
501 #        time. (since 1.2)
502 #
503 # @downtime: #optional only present when migration finishes correctly
504 #        total downtime in milliseconds for the guest.
505 #        (since 1.3)
506 #
507 # @expected-downtime: #optional only present while migration is active
508 #        expected downtime in milliseconds for the guest in last walk
509 #        of the dirty bitmap. (since 1.3)
510 #
511 # @setup-time: #optional amount of setup time in milliseconds _before_ the
512 #        iterations begin but _after_ the QMP command is issued. This is designed
513 #        to provide an accounting of any activities (such as RDMA pinning) which
514 #        may be expensive, but do not actually occur during the iterative
515 #        migration rounds themselves. (since 1.6)
516 #
517 # @cpu-throttle-percentage: #optional percentage of time guest cpus are being
518 #        throttled during auto-converge. This is only present when auto-converge
519 #        has started throttling guest cpus. (Since 2.7)
520 #
521 # @error-desc: #optional the human readable error description string, when
522 #              @status is 'failed'. Clients should not attempt to parse the
523 #              error strings. (Since 2.7)
524 #
525 # Since: 0.14.0
526 ##
527 { 'struct': 'MigrationInfo',
528   'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats',
529            '*disk': 'MigrationStats',
530            '*xbzrle-cache': 'XBZRLECacheStats',
531            '*total-time': 'int',
532            '*expected-downtime': 'int',
533            '*downtime': 'int',
534            '*setup-time': 'int',
535            '*cpu-throttle-percentage': 'int',
536            '*error-desc': 'str'} }
537
538 ##
539 # @query-migrate:
540 #
541 # Returns information about current migration process.
542 #
543 # Returns: @MigrationInfo
544 #
545 # Since: 0.14.0
546 ##
547 { 'command': 'query-migrate', 'returns': 'MigrationInfo' }
548
549 ##
550 # @MigrationCapability:
551 #
552 # Migration capabilities enumeration
553 #
554 # @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
555 #          This feature allows us to minimize migration traffic for certain work
556 #          loads, by sending compressed difference of the pages
557 #
558 # @rdma-pin-all: Controls whether or not the entire VM memory footprint is
559 #          mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
560 #          Disabled by default. (since 2.0)
561 #
562 # @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
563 #          essentially saves 1MB of zeroes per block on the wire. Enabling requires
564 #          source and target VM to support this feature. To enable it is sufficient
565 #          to enable the capability on the source VM. The feature is disabled by
566 #          default. (since 1.6)
567 #
568 # @compress: Use multiple compression threads to accelerate live migration.
569 #          This feature can help to reduce the migration traffic, by sending
570 #          compressed pages. Please note that if compress and xbzrle are both
571 #          on, compress only takes effect in the ram bulk stage, after that,
572 #          it will be disabled and only xbzrle takes effect, this can help to
573 #          minimize migration traffic. The feature is disabled by default.
574 #          (since 2.4 )
575 #
576 # @events: generate events for each migration state change
577 #          (since 2.4 )
578 #
579 # @auto-converge: If enabled, QEMU will automatically throttle down the guest
580 #          to speed up convergence of RAM migration. (since 1.6)
581 #
582 # @postcopy-ram: Start executing on the migration target before all of RAM has
583 #          been migrated, pulling the remaining pages along as needed. NOTE: If
584 #          the migration fails during postcopy the VM will fail.  (since 2.6)
585 #
586 # @x-colo: If enabled, migration will never end, and the state of the VM on the
587 #        primary side will be migrated continuously to the VM on secondary
588 #        side, this process is called COarse-Grain LOck Stepping (COLO) for
589 #        Non-stop Service. (since 2.8)
590 #
591 # Since: 1.2
592 ##
593 { 'enum': 'MigrationCapability',
594   'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
595            'compress', 'events', 'postcopy-ram', 'x-colo'] }
596
597 ##
598 # @MigrationCapabilityStatus:
599 #
600 # Migration capability information
601 #
602 # @capability: capability enum
603 #
604 # @state: capability state bool
605 #
606 # Since: 1.2
607 ##
608 { 'struct': 'MigrationCapabilityStatus',
609   'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
610
611 ##
612 # @migrate-set-capabilities:
613 #
614 # Enable/Disable the following migration capabilities (like xbzrle)
615 #
616 # @capabilities: json array of capability modifications to make
617 #
618 # Since: 1.2
619 ##
620 { 'command': 'migrate-set-capabilities',
621   'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
622
623 ##
624 # @query-migrate-capabilities:
625 #
626 # Returns information about the current migration capabilities status
627 #
628 # Returns: @MigrationCapabilitiesStatus
629 #
630 # Since: 1.2
631 ##
632 { 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus']}
633
634 ##
635 # @MigrationParameter:
636 #
637 # Migration parameters enumeration
638 #
639 # @compress-level: Set the compression level to be used in live migration,
640 #          the compression level is an integer between 0 and 9, where 0 means
641 #          no compression, 1 means the best compression speed, and 9 means best
642 #          compression ratio which will consume more CPU.
643 #
644 # @compress-threads: Set compression thread count to be used in live migration,
645 #          the compression thread count is an integer between 1 and 255.
646 #
647 # @decompress-threads: Set decompression thread count to be used in live
648 #          migration, the decompression thread count is an integer between 1
649 #          and 255. Usually, decompression is at least 4 times as fast as
650 #          compression, so set the decompress-threads to the number about 1/4
651 #          of compress-threads is adequate.
652 #
653 # @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
654 #                        when migration auto-converge is activated. The
655 #                        default value is 20. (Since 2.7)
656 #
657 # @cpu-throttle-increment: throttle percentage increase each time
658 #                          auto-converge detects that migration is not making
659 #                          progress. The default value is 10. (Since 2.7)
660 #
661 # @tls-creds: ID of the 'tls-creds' object that provides credentials for
662 #             establishing a TLS connection over the migration data channel.
663 #             On the outgoing side of the migration, the credentials must
664 #             be for a 'client' endpoint, while for the incoming side the
665 #             credentials must be for a 'server' endpoint. Setting this
666 #             will enable TLS for all migrations. The default is unset,
667 #             resulting in unsecured migration at the QEMU level. (Since 2.7)
668 #
669 # @tls-hostname: hostname of the target host for the migration. This is
670 #                required when using x509 based TLS credentials and the
671 #                migration URI does not already include a hostname. For
672 #                example if using fd: or exec: based migration, the
673 #                hostname must be provided so that the server's x509
674 #                certificate identity can be validated. (Since 2.7)
675 #
676 # @max-bandwidth: to set maximum speed for migration. maximum speed in
677 #                 bytes per second. (Since 2.8)
678 #
679 # @downtime-limit: set maximum tolerated downtime for migration. maximum
680 #                  downtime in milliseconds (Since 2.8)
681 #
682 # @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
683 #          periodic mode. (Since 2.8)
684 #
685 # Since: 2.4
686 ##
687 { 'enum': 'MigrationParameter',
688   'data': ['compress-level', 'compress-threads', 'decompress-threads',
689            'cpu-throttle-initial', 'cpu-throttle-increment',
690            'tls-creds', 'tls-hostname', 'max-bandwidth',
691            'downtime-limit', 'x-checkpoint-delay' ] }
692
693 ##
694 # @migrate-set-parameters:
695 #
696 # Set various migration parameters.  See MigrationParameters for details.
697 #
698 # Since: 2.4
699 ##
700 { 'command': 'migrate-set-parameters', 'boxed': true,
701   'data': 'MigrationParameters' }
702
703 ##
704 # @MigrationParameters:
705 #
706 # Optional members can be omitted on input ('migrate-set-parameters')
707 # but most members will always be present on output
708 # ('query-migrate-parameters'), with the exception of tls-creds and
709 # tls-hostname.
710 #
711 # @compress-level: #optional compression level
712 #
713 # @compress-threads: #optional compression thread count
714 #
715 # @decompress-threads: #optional decompression thread count
716 #
717 # @cpu-throttle-initial: #optional Initial percentage of time guest cpus are
718 #                        throttledwhen migration auto-converge is activated.
719 #                        The default value is 20. (Since 2.7)
720 #
721 # @cpu-throttle-increment: #optional throttle percentage increase each time
722 #                          auto-converge detects that migration is not making
723 #                          progress. The default value is 10. (Since 2.7)
724 #
725 # @tls-creds: #optional ID of the 'tls-creds' object that provides credentials
726 #             for establishing a TLS connection over the migration data
727 #             channel. On the outgoing side of the migration, the credentials
728 #             must be for a 'client' endpoint, while for the incoming side the
729 #             credentials must be for a 'server' endpoint. Setting this
730 #             will enable TLS for all migrations. The default is unset,
731 #             resulting in unsecured migration at the QEMU level. (Since 2.7)
732 #
733 # @tls-hostname: #optional hostname of the target host for the migration. This
734 #                is required when using x509 based TLS credentials and the
735 #                migration URI does not already include a hostname. For
736 #                example if using fd: or exec: based migration, the
737 #                hostname must be provided so that the server's x509
738 #                certificate identity can be validated. (Since 2.7)
739 #
740 # @max-bandwidth: to set maximum speed for migration. maximum speed in
741 #                 bytes per second. (Since 2.8)
742 #
743 # @downtime-limit: set maximum tolerated downtime for migration. maximum
744 #                  downtime in milliseconds (Since 2.8)
745 #
746 # @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
747 #
748 # Since: 2.4
749 ##
750 { 'struct': 'MigrationParameters',
751   'data': { '*compress-level': 'int',
752             '*compress-threads': 'int',
753             '*decompress-threads': 'int',
754             '*cpu-throttle-initial': 'int',
755             '*cpu-throttle-increment': 'int',
756             '*tls-creds': 'str',
757             '*tls-hostname': 'str',
758             '*max-bandwidth': 'int',
759             '*downtime-limit': 'int',
760             '*x-checkpoint-delay': 'int'} }
761
762 ##
763 # @query-migrate-parameters:
764 #
765 # Returns information about the current migration parameters
766 #
767 # Returns: @MigrationParameters
768 #
769 # Since: 2.4
770 ##
771 { 'command': 'query-migrate-parameters',
772   'returns': 'MigrationParameters' }
773
774 ##
775 # @client_migrate_info:
776 #
777 # Set migration information for remote display.  This makes the server
778 # ask the client to automatically reconnect using the new parameters
779 # once migration finished successfully.  Only implemented for SPICE.
780 #
781 # @protocol:     must be "spice"
782 # @hostname:     migration target hostname
783 # @port:         #optional spice tcp port for plaintext channels
784 # @tls-port:     #optional spice tcp port for tls-secured channels
785 # @cert-subject: #optional server certificate subject
786 #
787 # Since: 0.14.0
788 ##
789 { 'command': 'client_migrate_info',
790   'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
791             '*tls-port': 'int', '*cert-subject': 'str' } }
792
793 ##
794 # @migrate-start-postcopy:
795 #
796 # Followup to a migration command to switch the migration to postcopy mode.
797 # The postcopy-ram capability must be set before the original migration
798 # command.
799 #
800 # Since: 2.5
801 ##
802 { 'command': 'migrate-start-postcopy' }
803
804 ##
805 # @COLOMessage:
806 #
807 # The message transmission between Primary side and Secondary side.
808 #
809 # @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing
810 #
811 # @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing
812 #
813 # @checkpoint-reply: SVM gets PVM's checkpoint request
814 #
815 # @vmstate-send: VM's state will be sent by PVM.
816 #
817 # @vmstate-size: The total size of VMstate.
818 #
819 # @vmstate-received: VM's state has been received by SVM.
820 #
821 # @vmstate-loaded: VM's state has been loaded by SVM.
822 #
823 # Since: 2.8
824 ##
825 { 'enum': 'COLOMessage',
826   'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply',
827             'vmstate-send', 'vmstate-size', 'vmstate-received',
828             'vmstate-loaded' ] }
829
830 ##
831 # @COLOMode:
832 #
833 # The colo mode
834 #
835 # @unknown: unknown mode
836 #
837 # @primary: master side
838 #
839 # @secondary: slave side
840 #
841 # Since: 2.8
842 ##
843 { 'enum': 'COLOMode',
844   'data': [ 'unknown', 'primary', 'secondary'] }
845
846 ##
847 # @FailoverStatus:
848 #
849 # An enumeration of COLO failover status
850 #
851 # @none: no failover has ever happened
852 #
853 # @require: got failover requirement but not handled
854 #
855 # @active: in the process of doing failover
856 #
857 # @completed: finish the process of failover
858 #
859 # Since: 2.8
860 ##
861 { 'enum': 'FailoverStatus',
862   'data': [ 'none', 'require', 'active', 'completed'] }
863
864 ##
865 # @x-colo-lost-heartbeat:
866 #
867 # Tell qemu that heartbeat is lost, request it to do takeover procedures.
868 # If this command is sent to the PVM, the Primary side will exit COLO mode.
869 # If sent to the Secondary, the Secondary side will run failover work,
870 # then takes over server operation to become the service VM.
871 #
872 # Since: 2.8
873 ##
874 { 'command': 'x-colo-lost-heartbeat' }
875
876 ##
877 # @MouseInfo:
878 #
879 # Information about a mouse device.
880 #
881 # @name: the name of the mouse device
882 #
883 # @index: the index of the mouse device
884 #
885 # @current: true if this device is currently receiving mouse events
886 #
887 # @absolute: true if this device supports absolute coordinates as input
888 #
889 # Since: 0.14.0
890 ##
891 { 'struct': 'MouseInfo',
892   'data': {'name': 'str', 'index': 'int', 'current': 'bool',
893            'absolute': 'bool'} }
894
895 ##
896 # @query-mice:
897 #
898 # Returns information about each active mouse device
899 #
900 # Returns: a list of @MouseInfo for each device
901 #
902 # Since: 0.14.0
903 ##
904 { 'command': 'query-mice', 'returns': ['MouseInfo'] }
905
906 ##
907 # @CpuInfoArch:
908 #
909 # An enumeration of cpu types that enable additional information during
910 # @query-cpus.
911 #
912 # Since: 2.6
913 ##
914 { 'enum': 'CpuInfoArch',
915   'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 'other' ] }
916
917 ##
918 # @CpuInfo:
919 #
920 # Information about a virtual CPU
921 #
922 # @CPU: the index of the virtual CPU
923 #
924 # @current: this only exists for backwards compatibility and should be ignored
925 #
926 # @halted: true if the virtual CPU is in the halt state.  Halt usually refers
927 #          to a processor specific low power mode.
928 #
929 # @qom_path: path to the CPU object in the QOM tree (since 2.4)
930 #
931 # @thread_id: ID of the underlying host thread
932 #
933 # @arch: architecture of the cpu, which determines which additional fields
934 #        will be listed (since 2.6)
935 #
936 # Since: 0.14.0
937 #
938 # Notes: @halted is a transient state that changes frequently.  By the time the
939 #        data is sent to the client, the guest may no longer be halted.
940 ##
941 { 'union': 'CpuInfo',
942   'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool',
943            'qom_path': 'str', 'thread_id': 'int', 'arch': 'CpuInfoArch' },
944   'discriminator': 'arch',
945   'data': { 'x86': 'CpuInfoX86',
946             'sparc': 'CpuInfoSPARC',
947             'ppc': 'CpuInfoPPC',
948             'mips': 'CpuInfoMIPS',
949             'tricore': 'CpuInfoTricore',
950             'other': 'CpuInfoOther' } }
951
952 ##
953 # @CpuInfoX86:
954 #
955 # Additional information about a virtual i386 or x86_64 CPU
956 #
957 # @pc: the 64-bit instruction pointer
958 #
959 # Since: 2.6
960 ##
961 { 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } }
962
963 ##
964 # @CpuInfoSPARC:
965 #
966 # Additional information about a virtual SPARC CPU
967 #
968 # @pc: the PC component of the instruction pointer
969 #
970 # @npc: the NPC component of the instruction pointer
971 #
972 # Since: 2.6
973 ##
974 { 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } }
975
976 ##
977 # @CpuInfoPPC:
978 #
979 # Additional information about a virtual PPC CPU
980 #
981 # @nip: the instruction pointer
982 #
983 # Since: 2.6
984 ##
985 { 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } }
986
987 ##
988 # @CpuInfoMIPS:
989 #
990 # Additional information about a virtual MIPS CPU
991 #
992 # @PC: the instruction pointer
993 #
994 # Since: 2.6
995 ##
996 { 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } }
997
998 ##
999 # @CpuInfoTricore:
1000 #
1001 # Additional information about a virtual Tricore CPU
1002 #
1003 # @PC: the instruction pointer
1004 #
1005 # Since: 2.6
1006 ##
1007 { 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } }
1008
1009 ##
1010 # @CpuInfoOther:
1011 #
1012 # No additional information is available about the virtual CPU
1013 #
1014 # Since: 2.6
1015 #
1016 ##
1017 { 'struct': 'CpuInfoOther', 'data': { } }
1018
1019 ##
1020 # @query-cpus:
1021 #
1022 # Returns a list of information about each virtual CPU.
1023 #
1024 # Returns: a list of @CpuInfo for each virtual CPU
1025 #
1026 # Since: 0.14.0
1027 ##
1028 { 'command': 'query-cpus', 'returns': ['CpuInfo'] }
1029
1030 ##
1031 # @IOThreadInfo:
1032 #
1033 # Information about an iothread
1034 #
1035 # @id: the identifier of the iothread
1036 #
1037 # @thread-id: ID of the underlying host thread
1038 #
1039 # Since: 2.0
1040 ##
1041 { 'struct': 'IOThreadInfo',
1042   'data': {'id': 'str', 'thread-id': 'int'} }
1043
1044 ##
1045 # @query-iothreads:
1046 #
1047 # Returns a list of information about each iothread.
1048 #
1049 # Note: this list excludes the QEMU main loop thread, which is not declared
1050 # using the -object iothread command-line option.  It is always the main thread
1051 # of the process.
1052 #
1053 # Returns: a list of @IOThreadInfo for each iothread
1054 #
1055 # Since: 2.0
1056 ##
1057 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'] }
1058
1059 ##
1060 # @NetworkAddressFamily:
1061 #
1062 # The network address family
1063 #
1064 # @ipv4: IPV4 family
1065 #
1066 # @ipv6: IPV6 family
1067 #
1068 # @unix: unix socket
1069 #
1070 # @vsock: vsock family (since 2.8)
1071 #
1072 # @unknown: otherwise
1073 #
1074 # Since: 2.1
1075 ##
1076 { 'enum': 'NetworkAddressFamily',
1077   'data': [ 'ipv4', 'ipv6', 'unix', 'vsock', 'unknown' ] }
1078
1079 ##
1080 # @VncBasicInfo:
1081 #
1082 # The basic information for vnc network connection
1083 #
1084 # @host: IP address
1085 #
1086 # @service: The service name of the vnc port. This may depend on the host
1087 #           system's service database so symbolic names should not be relied
1088 #           on.
1089 #
1090 # @family: address family
1091 #
1092 # @websocket: true in case the socket is a websocket (since 2.3).
1093 #
1094 # Since: 2.1
1095 ##
1096 { 'struct': 'VncBasicInfo',
1097   'data': { 'host': 'str',
1098             'service': 'str',
1099             'family': 'NetworkAddressFamily',
1100             'websocket': 'bool' } }
1101
1102 ##
1103 # @VncServerInfo:
1104 #
1105 # The network connection information for server
1106 #
1107 # @auth: #optional, authentication method
1108 #
1109 # Since: 2.1
1110 ##
1111 { 'struct': 'VncServerInfo',
1112   'base': 'VncBasicInfo',
1113   'data': { '*auth': 'str' } }
1114
1115 ##
1116 # @VncClientInfo:
1117 #
1118 # Information about a connected VNC client.
1119 #
1120 # @x509_dname: #optional If x509 authentication is in use, the Distinguished
1121 #              Name of the client.
1122 #
1123 # @sasl_username: #optional If SASL authentication is in use, the SASL username
1124 #                 used for authentication.
1125 #
1126 # Since: 0.14.0
1127 ##
1128 { 'struct': 'VncClientInfo',
1129   'base': 'VncBasicInfo',
1130   'data': { '*x509_dname': 'str', '*sasl_username': 'str' } }
1131
1132 ##
1133 # @VncInfo:
1134 #
1135 # Information about the VNC session.
1136 #
1137 # @enabled: true if the VNC server is enabled, false otherwise
1138 #
1139 # @host: #optional The hostname the VNC server is bound to.  This depends on
1140 #        the name resolution on the host and may be an IP address.
1141 #
1142 # @family: #optional 'ipv6' if the host is listening for IPv6 connections
1143 #                    'ipv4' if the host is listening for IPv4 connections
1144 #                    'unix' if the host is listening on a unix domain socket
1145 #                    'unknown' otherwise
1146 #
1147 # @service: #optional The service name of the server's port.  This may depends
1148 #           on the host system's service database so symbolic names should not
1149 #           be relied on.
1150 #
1151 # @auth: #optional the current authentication type used by the server
1152 #        'none' if no authentication is being used
1153 #        'vnc' if VNC authentication is being used
1154 #        'vencrypt+plain' if VEncrypt is used with plain text authentication
1155 #        'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
1156 #        'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
1157 #        'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
1158 #        'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
1159 #        'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
1160 #        'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
1161 #        'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
1162 #        'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
1163 #
1164 # @clients: a list of @VncClientInfo of all currently connected clients
1165 #
1166 # Since: 0.14.0
1167 ##
1168 { 'struct': 'VncInfo',
1169   'data': {'enabled': 'bool', '*host': 'str',
1170            '*family': 'NetworkAddressFamily',
1171            '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']} }
1172
1173 ##
1174 # @VncPrimaryAuth:
1175 #
1176 # vnc primary authentication method.
1177 #
1178 # Since: 2.3
1179 ##
1180 { 'enum': 'VncPrimaryAuth',
1181   'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra',
1182             'tls', 'vencrypt', 'sasl' ] }
1183
1184 ##
1185 # @VncVencryptSubAuth:
1186 #
1187 # vnc sub authentication method with vencrypt.
1188 #
1189 # Since: 2.3
1190 ##
1191 { 'enum': 'VncVencryptSubAuth',
1192   'data': [ 'plain',
1193             'tls-none',  'x509-none',
1194             'tls-vnc',   'x509-vnc',
1195             'tls-plain', 'x509-plain',
1196             'tls-sasl',  'x509-sasl' ] }
1197
1198 ##
1199 # @VncInfo2:
1200 #
1201 # Information about a vnc server
1202 #
1203 # @id: vnc server name.
1204 #
1205 # @server: A list of @VncBasincInfo describing all listening sockets.
1206 #          The list can be empty (in case the vnc server is disabled).
1207 #          It also may have multiple entries: normal + websocket,
1208 #          possibly also ipv4 + ipv6 in the future.
1209 #
1210 # @clients: A list of @VncClientInfo of all currently connected clients.
1211 #           The list can be empty, for obvious reasons.
1212 #
1213 # @auth: The current authentication type used by the server
1214 #
1215 # @vencrypt: #optional The vencrypt sub authentication type used by the server,
1216 #            only specified in case auth == vencrypt.
1217 #
1218 # @display: #optional The display device the vnc server is linked to.
1219 #
1220 # Since: 2.3
1221 ##
1222 { 'struct': 'VncInfo2',
1223   'data': { 'id'        : 'str',
1224             'server'    : ['VncBasicInfo'],
1225             'clients'   : ['VncClientInfo'],
1226             'auth'      : 'VncPrimaryAuth',
1227             '*vencrypt' : 'VncVencryptSubAuth',
1228             '*display'  : 'str' } }
1229
1230 ##
1231 # @query-vnc:
1232 #
1233 # Returns information about the current VNC server
1234 #
1235 # Returns: @VncInfo
1236 #
1237 # Since: 0.14.0
1238 ##
1239 { 'command': 'query-vnc', 'returns': 'VncInfo' }
1240
1241 ##
1242 # @query-vnc-servers:
1243 #
1244 # Returns a list of vnc servers.  The list can be empty.
1245 #
1246 # Returns: a list of @VncInfo2
1247 #
1248 # Since: 2.3
1249 ##
1250 { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'] }
1251
1252 ##
1253 # @SpiceBasicInfo:
1254 #
1255 # The basic information for SPICE network connection
1256 #
1257 # @host: IP address
1258 #
1259 # @port: port number
1260 #
1261 # @family: address family
1262 #
1263 # Since: 2.1
1264 ##
1265 { 'struct': 'SpiceBasicInfo',
1266   'data': { 'host': 'str',
1267             'port': 'str',
1268             'family': 'NetworkAddressFamily' } }
1269
1270 ##
1271 # @SpiceServerInfo:
1272 #
1273 # Information about a SPICE server
1274 #
1275 # @auth: #optional, authentication method
1276 #
1277 # Since: 2.1
1278 ##
1279 { 'struct': 'SpiceServerInfo',
1280   'base': 'SpiceBasicInfo',
1281   'data': { '*auth': 'str' } }
1282
1283 ##
1284 # @SpiceChannel:
1285 #
1286 # Information about a SPICE client channel.
1287 #
1288 # @connection-id: SPICE connection id number.  All channels with the same id
1289 #                 belong to the same SPICE session.
1290 #
1291 # @channel-type: SPICE channel type number.  "1" is the main control
1292 #                channel, filter for this one if you want to track spice
1293 #                sessions only
1294 #
1295 # @channel-id: SPICE channel ID number.  Usually "0", might be different when
1296 #              multiple channels of the same type exist, such as multiple
1297 #              display channels in a multihead setup
1298 #
1299 # @tls: true if the channel is encrypted, false otherwise.
1300 #
1301 # Since: 0.14.0
1302 ##
1303 { 'struct': 'SpiceChannel',
1304   'base': 'SpiceBasicInfo',
1305   'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
1306            'tls': 'bool'} }
1307
1308 ##
1309 # @SpiceQueryMouseMode:
1310 #
1311 # An enumeration of Spice mouse states.
1312 #
1313 # @client: Mouse cursor position is determined by the client.
1314 #
1315 # @server: Mouse cursor position is determined by the server.
1316 #
1317 # @unknown: No information is available about mouse mode used by
1318 #           the spice server.
1319 #
1320 # Note: spice/enums.h has a SpiceMouseMode already, hence the name.
1321 #
1322 # Since: 1.1
1323 ##
1324 { 'enum': 'SpiceQueryMouseMode',
1325   'data': [ 'client', 'server', 'unknown' ] }
1326
1327 ##
1328 # @SpiceInfo:
1329 #
1330 # Information about the SPICE session.
1331 #
1332 # @enabled: true if the SPICE server is enabled, false otherwise
1333 #
1334 # @migrated: true if the last guest migration completed and spice
1335 #            migration had completed as well. false otherwise.
1336 #
1337 # @host: #optional The hostname the SPICE server is bound to.  This depends on
1338 #        the name resolution on the host and may be an IP address.
1339 #
1340 # @port: #optional The SPICE server's port number.
1341 #
1342 # @compiled-version: #optional SPICE server version.
1343 #
1344 # @tls-port: #optional The SPICE server's TLS port number.
1345 #
1346 # @auth: #optional the current authentication type used by the server
1347 #        'none'  if no authentication is being used
1348 #        'spice' uses SASL or direct TLS authentication, depending on command
1349 #                line options
1350 #
1351 # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
1352 #              be determined by the client or the server, or unknown if spice
1353 #              server doesn't provide this information.
1354 #
1355 #              Since: 1.1
1356 #
1357 # @channels: a list of @SpiceChannel for each active spice channel
1358 #
1359 # Since: 0.14.0
1360 ##
1361 { 'struct': 'SpiceInfo',
1362   'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
1363            '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
1364            'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']} }
1365
1366 ##
1367 # @query-spice:
1368 #
1369 # Returns information about the current SPICE server
1370 #
1371 # Returns: @SpiceInfo
1372 #
1373 # Since: 0.14.0
1374 ##
1375 { 'command': 'query-spice', 'returns': 'SpiceInfo' }
1376
1377 ##
1378 # @BalloonInfo:
1379 #
1380 # Information about the guest balloon device.
1381 #
1382 # @actual: the number of bytes the balloon currently contains
1383 #
1384 # Since: 0.14.0
1385 #
1386 ##
1387 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
1388
1389 ##
1390 # @query-balloon:
1391 #
1392 # Return information about the balloon device.
1393 #
1394 # Returns: @BalloonInfo on success
1395 #          If the balloon driver is enabled but not functional because the KVM
1396 #          kernel module cannot support it, KvmMissingCap
1397 #          If no balloon device is present, DeviceNotActive
1398 #
1399 # Since: 0.14.0
1400 ##
1401 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
1402
1403 ##
1404 # @PciMemoryRange:
1405 #
1406 # A PCI device memory region
1407 #
1408 # @base: the starting address (guest physical)
1409 #
1410 # @limit: the ending address (guest physical)
1411 #
1412 # Since: 0.14.0
1413 ##
1414 { 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
1415
1416 ##
1417 # @PciMemoryRegion:
1418 #
1419 # Information about a PCI device I/O region.
1420 #
1421 # @bar: the index of the Base Address Register for this region
1422 #
1423 # @type: 'io' if the region is a PIO region
1424 #        'memory' if the region is a MMIO region
1425 #
1426 # @prefetch: #optional if @type is 'memory', true if the memory is prefetchable
1427 #
1428 # @mem_type_64: #optional if @type is 'memory', true if the BAR is 64-bit
1429 #
1430 # Since: 0.14.0
1431 ##
1432 { 'struct': 'PciMemoryRegion',
1433   'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
1434            '*prefetch': 'bool', '*mem_type_64': 'bool' } }
1435
1436 ##
1437 # @PciBusInfo:
1438 #
1439 # Information about a bus of a PCI Bridge device
1440 #
1441 # @number: primary bus interface number.  This should be the number of the
1442 #          bus the device resides on.
1443 #
1444 # @secondary: secondary bus interface number.  This is the number of the
1445 #             main bus for the bridge
1446 #
1447 # @subordinate: This is the highest number bus that resides below the
1448 #               bridge.
1449 #
1450 # @io_range: The PIO range for all devices on this bridge
1451 #
1452 # @memory_range: The MMIO range for all devices on this bridge
1453 #
1454 # @prefetchable_range: The range of prefetchable MMIO for all devices on
1455 #                      this bridge
1456 #
1457 # Since: 2.4
1458 ##
1459 { 'struct': 'PciBusInfo',
1460   'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
1461            'io_range': 'PciMemoryRange',
1462            'memory_range': 'PciMemoryRange',
1463            'prefetchable_range': 'PciMemoryRange' } }
1464
1465 ##
1466 # @PciBridgeInfo:
1467 #
1468 # Information about a PCI Bridge device
1469 #
1470 # @bus: information about the bus the device resides on
1471 #
1472 # @devices: a list of @PciDeviceInfo for each device on this bridge
1473 #
1474 # Since: 0.14.0
1475 ##
1476 { 'struct': 'PciBridgeInfo',
1477   'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }
1478
1479 ##
1480 # @PciDeviceClass:
1481 #
1482 # Information about the Class of a PCI device
1483 #
1484 # @desc: #optional a string description of the device's class
1485 #
1486 # @class: the class code of the device
1487 #
1488 # Since: 2.4
1489 ##
1490 { 'struct': 'PciDeviceClass',
1491   'data': {'*desc': 'str', 'class': 'int'} }
1492
1493 ##
1494 # @PciDeviceId:
1495 #
1496 # Information about the Id of a PCI device
1497 #
1498 # @device: the PCI device id
1499 #
1500 # @vendor: the PCI vendor id
1501 #
1502 # Since: 2.4
1503 ##
1504 { 'struct': 'PciDeviceId',
1505   'data': {'device': 'int', 'vendor': 'int'} }
1506
1507 ##
1508 # @PciDeviceInfo:
1509 #
1510 # Information about a PCI device
1511 #
1512 # @bus: the bus number of the device
1513 #
1514 # @slot: the slot the device is located in
1515 #
1516 # @function: the function of the slot used by the device
1517 #
1518 # @class_info: the class of the device
1519 #
1520 # @id: the PCI device id
1521 #
1522 # @irq: #optional if an IRQ is assigned to the device, the IRQ number
1523 #
1524 # @qdev_id: the device name of the PCI device
1525 #
1526 # @pci_bridge: if the device is a PCI bridge, the bridge information
1527 #
1528 # @regions: a list of the PCI I/O regions associated with the device
1529 #
1530 # Notes: the contents of @class_info.desc are not stable and should only be
1531 #        treated as informational.
1532 #
1533 # Since: 0.14.0
1534 ##
1535 { 'struct': 'PciDeviceInfo',
1536   'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
1537            'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
1538            '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo',
1539            'regions': ['PciMemoryRegion']} }
1540
1541 ##
1542 # @PciInfo:
1543 #
1544 # Information about a PCI bus
1545 #
1546 # @bus: the bus index
1547 #
1548 # @devices: a list of devices on this bus
1549 #
1550 # Since: 0.14.0
1551 ##
1552 { 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
1553
1554 ##
1555 # @query-pci:
1556 #
1557 # Return information about the PCI bus topology of the guest.
1558 #
1559 # Returns: a list of @PciInfo for each PCI bus
1560 #
1561 # Since: 0.14.0
1562 ##
1563 { 'command': 'query-pci', 'returns': ['PciInfo'] }
1564
1565 ##
1566 # @quit:
1567 #
1568 # This command will cause the QEMU process to exit gracefully.  While every
1569 # attempt is made to send the QMP response before terminating, this is not
1570 # guaranteed.  When using this interface, a premature EOF would not be
1571 # unexpected.
1572 #
1573 # Since: 0.14.0
1574 ##
1575 { 'command': 'quit' }
1576
1577 ##
1578 # @stop:
1579 #
1580 # Stop all guest VCPU execution.
1581 #
1582 # Since:  0.14.0
1583 #
1584 # Notes:  This function will succeed even if the guest is already in the stopped
1585 #         state.  In "inmigrate" state, it will ensure that the guest
1586 #         remains paused once migration finishes, as if the -S option was
1587 #         passed on the command line.
1588 ##
1589 { 'command': 'stop' }
1590
1591 ##
1592 # @system_reset:
1593 #
1594 # Performs a hard reset of a guest.
1595 #
1596 # Since: 0.14.0
1597 ##
1598 { 'command': 'system_reset' }
1599
1600 ##
1601 # @system_powerdown:
1602 #
1603 # Requests that a guest perform a powerdown operation.
1604 #
1605 # Since: 0.14.0
1606 #
1607 # Notes: A guest may or may not respond to this command.  This command
1608 #        returning does not indicate that a guest has accepted the request or
1609 #        that it has shut down.  Many guests will respond to this command by
1610 #        prompting the user in some way.
1611 ##
1612 { 'command': 'system_powerdown' }
1613
1614 ##
1615 # @cpu:
1616 #
1617 # This command is a nop that is only provided for the purposes of compatibility.
1618 #
1619 # Since: 0.14.0
1620 #
1621 # Notes: Do not use this command.
1622 ##
1623 { 'command': 'cpu', 'data': {'index': 'int'} }
1624
1625 ##
1626 # @cpu-add:
1627 #
1628 # Adds CPU with specified ID
1629 #
1630 # @id: ID of CPU to be created, valid values [0..max_cpus)
1631 #
1632 # Returns: Nothing on success
1633 #
1634 # Since: 1.5
1635 ##
1636 { 'command': 'cpu-add', 'data': {'id': 'int'} }
1637
1638 ##
1639 # @memsave:
1640 #
1641 # Save a portion of guest memory to a file.
1642 #
1643 # @val: the virtual address of the guest to start from
1644 #
1645 # @size: the size of memory region to save
1646 #
1647 # @filename: the file to save the memory to as binary data
1648 #
1649 # @cpu-index: #optional the index of the virtual CPU to use for translating the
1650 #                       virtual address (defaults to CPU 0)
1651 #
1652 # Returns: Nothing on success
1653 #
1654 # Since: 0.14.0
1655 #
1656 # Notes: Errors were not reliably returned until 1.1
1657 ##
1658 { 'command': 'memsave',
1659   'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
1660
1661 ##
1662 # @pmemsave:
1663 #
1664 # Save a portion of guest physical memory to a file.
1665 #
1666 # @val: the physical address of the guest to start from
1667 #
1668 # @size: the size of memory region to save
1669 #
1670 # @filename: the file to save the memory to as binary data
1671 #
1672 # Returns: Nothing on success
1673 #
1674 # Since: 0.14.0
1675 #
1676 # Notes: Errors were not reliably returned until 1.1
1677 ##
1678 { 'command': 'pmemsave',
1679   'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
1680
1681 ##
1682 # @cont:
1683 #
1684 # Resume guest VCPU execution.
1685 #
1686 # Since:  0.14.0
1687 #
1688 # Returns:  If successful, nothing
1689 #           If QEMU was started with an encrypted block device and a key has
1690 #              not yet been set, DeviceEncrypted.
1691 #
1692 # Notes:  This command will succeed if the guest is currently running.  It
1693 #         will also succeed if the guest is in the "inmigrate" state; in
1694 #         this case, the effect of the command is to make sure the guest
1695 #         starts once migration finishes, removing the effect of the -S
1696 #         command line option if it was passed.
1697 ##
1698 { 'command': 'cont' }
1699
1700 ##
1701 # @system_wakeup:
1702 #
1703 # Wakeup guest from suspend.  Does nothing in case the guest isn't suspended.
1704 #
1705 # Since:  1.1
1706 #
1707 # Returns:  nothing.
1708 ##
1709 { 'command': 'system_wakeup' }
1710
1711 ##
1712 # @inject-nmi:
1713 #
1714 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
1715 #
1716 # Returns:  If successful, nothing
1717 #
1718 # Since:  0.14.0
1719 #
1720 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
1721 ##
1722 { 'command': 'inject-nmi' }
1723
1724 ##
1725 # @set_link:
1726 #
1727 # Sets the link status of a virtual network adapter.
1728 #
1729 # @name: the device name of the virtual network adapter
1730 #
1731 # @up: true to set the link status to be up
1732 #
1733 # Returns: Nothing on success
1734 #          If @name is not a valid network device, DeviceNotFound
1735 #
1736 # Since: 0.14.0
1737 #
1738 # Notes: Not all network adapters support setting link status.  This command
1739 #        will succeed even if the network adapter does not support link status
1740 #        notification.
1741 ##
1742 { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
1743
1744 ##
1745 # @balloon:
1746 #
1747 # Request the balloon driver to change its balloon size.
1748 #
1749 # @value: the target size of the balloon in bytes
1750 #
1751 # Returns: Nothing on success
1752 #          If the balloon driver is enabled but not functional because the KVM
1753 #            kernel module cannot support it, KvmMissingCap
1754 #          If no balloon device is present, DeviceNotActive
1755 #
1756 # Notes: This command just issues a request to the guest.  When it returns,
1757 #        the balloon size may not have changed.  A guest can change the balloon
1758 #        size independent of this command.
1759 #
1760 # Since: 0.14.0
1761 ##
1762 { 'command': 'balloon', 'data': {'value': 'int'} }
1763
1764 ##
1765 # @Abort:
1766 #
1767 # This action can be used to test transaction failure.
1768 #
1769 # Since: 1.6
1770 ##
1771 { 'struct': 'Abort',
1772   'data': { } }
1773
1774 ##
1775 # @ActionCompletionMode:
1776 #
1777 # An enumeration of Transactional completion modes.
1778 #
1779 # @individual: Do not attempt to cancel any other Actions if any Actions fail
1780 #              after the Transaction request succeeds. All Actions that
1781 #              can complete successfully will do so without waiting on others.
1782 #              This is the default.
1783 #
1784 # @grouped: If any Action fails after the Transaction succeeds, cancel all
1785 #           Actions. Actions do not complete until all Actions are ready to
1786 #           complete. May be rejected by Actions that do not support this
1787 #           completion mode.
1788 #
1789 # Since: 2.5
1790 ##
1791 { 'enum': 'ActionCompletionMode',
1792   'data': [ 'individual', 'grouped' ] }
1793
1794 ##
1795 # @TransactionAction:
1796 #
1797 # A discriminated record of operations that can be performed with
1798 # @transaction.
1799 #
1800 # Since: 1.1
1801 #
1802 # drive-backup since 1.6
1803 # abort since 1.6
1804 # blockdev-snapshot-internal-sync since 1.7
1805 # blockdev-backup since 2.3
1806 # blockdev-snapshot since 2.5
1807 # block-dirty-bitmap-add since 2.5
1808 # block-dirty-bitmap-clear since 2.5
1809 ##
1810 { 'union': 'TransactionAction',
1811   'data': {
1812        'blockdev-snapshot': 'BlockdevSnapshot',
1813        'blockdev-snapshot-sync': 'BlockdevSnapshotSync',
1814        'drive-backup': 'DriveBackup',
1815        'blockdev-backup': 'BlockdevBackup',
1816        'abort': 'Abort',
1817        'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternal',
1818        'block-dirty-bitmap-add': 'BlockDirtyBitmapAdd',
1819        'block-dirty-bitmap-clear': 'BlockDirtyBitmap'
1820    } }
1821
1822 ##
1823 # @TransactionProperties:
1824 #
1825 # Optional arguments to modify the behavior of a Transaction.
1826 #
1827 # @completion-mode: #optional Controls how jobs launched asynchronously by
1828 #                   Actions will complete or fail as a group.
1829 #                   See @ActionCompletionMode for details.
1830 #
1831 # Since: 2.5
1832 ##
1833 { 'struct': 'TransactionProperties',
1834   'data': {
1835        '*completion-mode': 'ActionCompletionMode'
1836   }
1837 }
1838
1839 ##
1840 # @transaction:
1841 #
1842 # Executes a number of transactionable QMP commands atomically. If any
1843 # operation fails, then the entire set of actions will be abandoned and the
1844 # appropriate error returned.
1845 #
1846 # @actions: List of @TransactionAction;
1847 #           information needed for the respective operations.
1848 #
1849 # @properties: #optional structure of additional options to control the
1850 #              execution of the transaction. See @TransactionProperties
1851 #              for additional detail.
1852 #
1853 # Returns: nothing on success
1854 #          Errors depend on the operations of the transaction
1855 #
1856 # Note: The transaction aborts on the first failure.  Therefore, there will be
1857 # information on only one failed operation returned in an error condition, and
1858 # subsequent actions will not have been attempted.
1859 #
1860 # Since: 1.1
1861 ##
1862 { 'command': 'transaction',
1863   'data': { 'actions': [ 'TransactionAction' ],
1864             '*properties': 'TransactionProperties'
1865           }
1866 }
1867
1868 ##
1869 # @human-monitor-command:
1870 #
1871 # Execute a command on the human monitor and return the output.
1872 #
1873 # @command-line: the command to execute in the human monitor
1874 #
1875 # @cpu-index: #optional The CPU to use for commands that require an implicit CPU
1876 #
1877 # Returns: the output of the command as a string
1878 #
1879 # Since: 0.14.0
1880 #
1881 # Notes: This command only exists as a stop-gap.  Its use is highly
1882 #        discouraged.  The semantics of this command are not guaranteed.
1883 #
1884 #        Known limitations:
1885 #
1886 #        o This command is stateless, this means that commands that depend
1887 #          on state information (such as getfd) might not work
1888 #
1889 #       o Commands that prompt the user for data (eg. 'cont' when the block
1890 #         device is encrypted) don't currently work
1891 ##
1892 { 'command': 'human-monitor-command',
1893   'data': {'command-line': 'str', '*cpu-index': 'int'},
1894   'returns': 'str' }
1895
1896 ##
1897 # @migrate_cancel:
1898 #
1899 # Cancel the current executing migration process.
1900 #
1901 # Returns: nothing on success
1902 #
1903 # Notes: This command succeeds even if there is no migration process running.
1904 #
1905 # Since: 0.14.0
1906 ##
1907 { 'command': 'migrate_cancel' }
1908
1909 ##
1910 # @migrate_set_downtime:
1911 #
1912 # Set maximum tolerated downtime for migration.
1913 #
1914 # @value: maximum downtime in seconds
1915 #
1916 # Returns: nothing on success
1917 #
1918 # Notes: This command is deprecated in favor of 'migrate-set-parameters'
1919 #
1920 # Since: 0.14.0
1921 ##
1922 { 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
1923
1924 ##
1925 # @migrate_set_speed:
1926 #
1927 # Set maximum speed for migration.
1928 #
1929 # @value: maximum speed in bytes.
1930 #
1931 # Returns: nothing on success
1932 #
1933 # Notes: This command is deprecated in favor of 'migrate-set-parameters'
1934 #
1935 # Since: 0.14.0
1936 ##
1937 { 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
1938
1939 ##
1940 # @migrate-set-cache-size:
1941 #
1942 # Set XBZRLE cache size
1943 #
1944 # @value: cache size in bytes
1945 #
1946 # The size will be rounded down to the nearest power of 2.
1947 # The cache size can be modified before and during ongoing migration
1948 #
1949 # Returns: nothing on success
1950 #
1951 # Since: 1.2
1952 ##
1953 { 'command': 'migrate-set-cache-size', 'data': {'value': 'int'} }
1954
1955 ##
1956 # @query-migrate-cache-size:
1957 #
1958 # query XBZRLE cache size
1959 #
1960 # Returns: XBZRLE cache size in bytes
1961 #
1962 # Since: 1.2
1963 ##
1964 { 'command': 'query-migrate-cache-size', 'returns': 'int' }
1965
1966 ##
1967 # @ObjectPropertyInfo:
1968 #
1969 # @name: the name of the property
1970 #
1971 # @type: the type of the property.  This will typically come in one of four
1972 #        forms:
1973 #
1974 #        1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
1975 #           These types are mapped to the appropriate JSON type.
1976 #
1977 #        2) A child type in the form 'child<subtype>' where subtype is a qdev
1978 #           device type name.  Child properties create the composition tree.
1979 #
1980 #        3) A link type in the form 'link<subtype>' where subtype is a qdev
1981 #           device type name.  Link properties form the device model graph.
1982 #
1983 # Since: 1.2
1984 ##
1985 { 'struct': 'ObjectPropertyInfo',
1986   'data': { 'name': 'str', 'type': 'str' } }
1987
1988 ##
1989 # @qom-list:
1990 #
1991 # This command will list any properties of a object given a path in the object
1992 # model.
1993 #
1994 # @path: the path within the object model.  See @qom-get for a description of
1995 #        this parameter.
1996 #
1997 # Returns: a list of @ObjectPropertyInfo that describe the properties of the
1998 #          object.
1999 #
2000 # Since: 1.2
2001 ##
2002 { 'command': 'qom-list',
2003   'data': { 'path': 'str' },
2004   'returns': [ 'ObjectPropertyInfo' ] }
2005
2006 ##
2007 # @qom-get:
2008 #
2009 # This command will get a property from a object model path and return the
2010 # value.
2011 #
2012 # @path: The path within the object model.  There are two forms of supported
2013 #        paths--absolute and partial paths.
2014 #
2015 #        Absolute paths are derived from the root object and can follow child<>
2016 #        or link<> properties.  Since they can follow link<> properties, they
2017 #        can be arbitrarily long.  Absolute paths look like absolute filenames
2018 #        and are prefixed  with a leading slash.
2019 #
2020 #        Partial paths look like relative filenames.  They do not begin
2021 #        with a prefix.  The matching rules for partial paths are subtle but
2022 #        designed to make specifying objects easy.  At each level of the
2023 #        composition tree, the partial path is matched as an absolute path.
2024 #        The first match is not returned.  At least two matches are searched
2025 #        for.  A successful result is only returned if only one match is
2026 #        found.  If more than one match is found, a flag is return to
2027 #        indicate that the match was ambiguous.
2028 #
2029 # @property: The property name to read
2030 #
2031 # Returns: The property value.  The type depends on the property
2032 #          type. child<> and link<> properties are returned as #str
2033 #          pathnames.  All integer property types (u8, u16, etc) are
2034 #          returned as #int.
2035 #
2036 # Since: 1.2
2037 ##
2038 { 'command': 'qom-get',
2039   'data': { 'path': 'str', 'property': 'str' },
2040   'returns': 'any' }
2041
2042 ##
2043 # @qom-set:
2044 #
2045 # This command will set a property from a object model path.
2046 #
2047 # @path: see @qom-get for a description of this parameter
2048 #
2049 # @property: the property name to set
2050 #
2051 # @value: a value who's type is appropriate for the property type.  See @qom-get
2052 #         for a description of type mapping.
2053 #
2054 # Since: 1.2
2055 ##
2056 { 'command': 'qom-set',
2057   'data': { 'path': 'str', 'property': 'str', 'value': 'any' } }
2058
2059 ##
2060 # @set_password:
2061 #
2062 # Sets the password of a remote display session.
2063 #
2064 # @protocol: `vnc' to modify the VNC server password
2065 #            `spice' to modify the Spice server password
2066 #
2067 # @password: the new password
2068 #
2069 # @connected: #optional how to handle existing clients when changing the
2070 #                       password.  If nothing is specified, defaults to `keep'
2071 #                       `fail' to fail the command if clients are connected
2072 #                       `disconnect' to disconnect existing clients
2073 #                       `keep' to maintain existing clients
2074 #
2075 # Returns: Nothing on success
2076 #          If Spice is not enabled, DeviceNotFound
2077 #
2078 # Since: 0.14.0
2079 ##
2080 { 'command': 'set_password',
2081   'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
2082
2083 ##
2084 # @expire_password:
2085 #
2086 # Expire the password of a remote display server.
2087 #
2088 # @protocol: the name of the remote display protocol `vnc' or `spice'
2089 #
2090 # @time: when to expire the password.
2091 #        `now' to expire the password immediately
2092 #        `never' to cancel password expiration
2093 #        `+INT' where INT is the number of seconds from now (integer)
2094 #        `INT' where INT is the absolute time in seconds
2095 #
2096 # Returns: Nothing on success
2097 #          If @protocol is `spice' and Spice is not active, DeviceNotFound
2098 #
2099 # Since: 0.14.0
2100 #
2101 # Notes: Time is relative to the server and currently there is no way to
2102 #        coordinate server time with client time.  It is not recommended to
2103 #        use the absolute time version of the @time parameter unless you're
2104 #        sure you are on the same machine as the QEMU instance.
2105 ##
2106 { 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
2107
2108 ##
2109 # @change-vnc-password:
2110 #
2111 # Change the VNC server password.
2112 #
2113 # @password:  the new password to use with VNC authentication
2114 #
2115 # Since: 1.1
2116 #
2117 # Notes:  An empty password in this command will set the password to the empty
2118 #         string.  Existing clients are unaffected by executing this command.
2119 ##
2120 { 'command': 'change-vnc-password', 'data': {'password': 'str'} }
2121
2122 ##
2123 # @change:
2124 #
2125 # This command is multiple commands multiplexed together.
2126 #
2127 # @device: This is normally the name of a block device but it may also be 'vnc'.
2128 #          when it's 'vnc', then sub command depends on @target
2129 #
2130 # @target: If @device is a block device, then this is the new filename.
2131 #          If @device is 'vnc', then if the value 'password' selects the vnc
2132 #          change password command.   Otherwise, this specifies a new server URI
2133 #          address to listen to for VNC connections.
2134 #
2135 # @arg:    If @device is a block device, then this is an optional format to open
2136 #          the device with.
2137 #          If @device is 'vnc' and @target is 'password', this is the new VNC
2138 #          password to set.  If this argument is an empty string, then no future
2139 #          logins will be allowed.
2140 #
2141 # Returns: Nothing on success.
2142 #          If @device is not a valid block device, DeviceNotFound
2143 #          If the new block device is encrypted, DeviceEncrypted.  Note that
2144 #          if this error is returned, the device has been opened successfully
2145 #          and an additional call to @block_passwd is required to set the
2146 #          device's password.  The behavior of reads and writes to the block
2147 #          device between when these calls are executed is undefined.
2148 #
2149 # Notes:  This interface is deprecated, and it is strongly recommended that you
2150 #         avoid using it.  For changing block devices, use
2151 #         blockdev-change-medium; for changing VNC parameters, use
2152 #         change-vnc-password.
2153 #
2154 # Since: 0.14.0
2155 ##
2156 { 'command': 'change',
2157   'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
2158
2159 ##
2160 # @ObjectTypeInfo:
2161 #
2162 # This structure describes a search result from @qom-list-types
2163 #
2164 # @name: the type name found in the search
2165 #
2166 # Since: 1.1
2167 #
2168 # Notes: This command is experimental and may change syntax in future releases.
2169 ##
2170 { 'struct': 'ObjectTypeInfo',
2171   'data': { 'name': 'str' } }
2172
2173 ##
2174 # @qom-list-types:
2175 #
2176 # This command will return a list of types given search parameters
2177 #
2178 # @implements: if specified, only return types that implement this type name
2179 #
2180 # @abstract: if true, include abstract types in the results
2181 #
2182 # Returns: a list of @ObjectTypeInfo or an empty list if no results are found
2183 #
2184 # Since: 1.1
2185 ##
2186 { 'command': 'qom-list-types',
2187   'data': { '*implements': 'str', '*abstract': 'bool' },
2188   'returns': [ 'ObjectTypeInfo' ] }
2189
2190 ##
2191 # @DevicePropertyInfo:
2192 #
2193 # Information about device properties.
2194 #
2195 # @name: the name of the property
2196 # @type: the typename of the property
2197 # @description: #optional if specified, the description of the property.
2198 #               (since 2.2)
2199 #
2200 # Since: 1.2
2201 ##
2202 { 'struct': 'DevicePropertyInfo',
2203   'data': { 'name': 'str', 'type': 'str', '*description': 'str' } }
2204
2205 ##
2206 # @device-list-properties:
2207 #
2208 # List properties associated with a device.
2209 #
2210 # @typename: the type name of a device
2211 #
2212 # Returns: a list of DevicePropertyInfo describing a devices properties
2213 #
2214 # Since: 1.2
2215 ##
2216 { 'command': 'device-list-properties',
2217   'data': { 'typename': 'str'},
2218   'returns': [ 'DevicePropertyInfo' ] }
2219
2220 ##
2221 # @migrate:
2222 #
2223 # Migrates the current running guest to another Virtual Machine.
2224 #
2225 # @uri: the Uniform Resource Identifier of the destination VM
2226 #
2227 # @blk: #optional do block migration (full disk copy)
2228 #
2229 # @inc: #optional incremental disk copy migration
2230 #
2231 # @detach: this argument exists only for compatibility reasons and
2232 #          is ignored by QEMU
2233 #
2234 # Returns: nothing on success
2235 #
2236 # Since: 0.14.0
2237 ##
2238 { 'command': 'migrate',
2239   'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', '*detach': 'bool' } }
2240
2241 ##
2242 # @migrate-incoming:
2243 #
2244 # Start an incoming migration, the qemu must have been started
2245 # with -incoming defer
2246 #
2247 # @uri: The Uniform Resource Identifier identifying the source or
2248 #       address to listen on
2249 #
2250 # Returns: nothing on success
2251 #
2252 # Since: 2.3
2253 # Note: It's a bad idea to use a string for the uri, but it needs to stay
2254 # compatible with -incoming and the format of the uri is already exposed
2255 # above libvirt
2256 ##
2257 { 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
2258
2259 ##
2260 # @xen-save-devices-state:
2261 #
2262 # Save the state of all devices to file. The RAM and the block devices
2263 # of the VM are not saved by this command.
2264 #
2265 # @filename: the file to save the state of the devices to as binary
2266 # data. See xen-save-devices-state.txt for a description of the binary
2267 # format.
2268 #
2269 # Returns: Nothing on success
2270 #
2271 # Since: 1.1
2272 ##
2273 { 'command': 'xen-save-devices-state', 'data': {'filename': 'str'} }
2274
2275 ##
2276 # @xen-set-global-dirty-log:
2277 #
2278 # Enable or disable the global dirty log mode.
2279 #
2280 # @enable: true to enable, false to disable.
2281 #
2282 # Returns: nothing
2283 #
2284 # Since: 1.3
2285 ##
2286 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
2287
2288 ##
2289 # @device_add:
2290 #
2291 # @driver: the name of the new device's driver
2292 #
2293 # @bus: #optional the device's parent bus (device tree path)
2294 #
2295 # @id: the device's ID, must be unique
2296 #
2297 # Additional arguments depend on the type.
2298 #
2299 # Add a device.
2300 #
2301 # Notes:
2302 # 1. For detailed information about this command, please refer to the
2303 #    'docs/qdev-device-use.txt' file.
2304 #
2305 # 2. It's possible to list device properties by running QEMU with the
2306 #    "-device DEVICE,help" command-line argument, where DEVICE is the
2307 #    device's name
2308 #
2309 # Example:
2310 #
2311 # -> { "execute": "device_add",
2312 #      "arguments": { "driver": "e1000", "id": "net1",
2313 #                     "bus": "pci.0",
2314 #                     "mac": "52:54:00:12:34:56" } }
2315 # <- { "return": {} }
2316 #
2317 # TODO This command effectively bypasses QAPI completely due to its
2318 # "additional arguments" business.  It shouldn't have been added to
2319 # the schema in this form.  It should be qapified properly, or
2320 # replaced by a properly qapified command.
2321 #
2322 # Since: 0.13
2323 ##
2324 { 'command': 'device_add',
2325   'data': {'driver': 'str', 'id': 'str'},
2326   'gen': false } # so we can get the additional arguments
2327
2328 ##
2329 # @device_del:
2330 #
2331 # Remove a device from a guest
2332 #
2333 # @id: the name or QOM path of the device
2334 #
2335 # Returns: Nothing on success
2336 #          If @id is not a valid device, DeviceNotFound
2337 #
2338 # Notes: When this command completes, the device may not be removed from the
2339 #        guest.  Hot removal is an operation that requires guest cooperation.
2340 #        This command merely requests that the guest begin the hot removal
2341 #        process.  Completion of the device removal process is signaled with a
2342 #        DEVICE_DELETED event. Guest reset will automatically complete removal
2343 #        for all devices.
2344 #
2345 # Since: 0.14.0
2346 ##
2347 { 'command': 'device_del', 'data': {'id': 'str'} }
2348
2349 ##
2350 # @DumpGuestMemoryFormat:
2351 #
2352 # An enumeration of guest-memory-dump's format.
2353 #
2354 # @elf: elf format
2355 #
2356 # @kdump-zlib: kdump-compressed format with zlib-compressed
2357 #
2358 # @kdump-lzo: kdump-compressed format with lzo-compressed
2359 #
2360 # @kdump-snappy: kdump-compressed format with snappy-compressed
2361 #
2362 # Since: 2.0
2363 ##
2364 { 'enum': 'DumpGuestMemoryFormat',
2365   'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy' ] }
2366
2367 ##
2368 # @dump-guest-memory:
2369 #
2370 # Dump guest's memory to vmcore. It is a synchronous operation that can take
2371 # very long depending on the amount of guest memory.
2372 #
2373 # @paging: if true, do paging to get guest's memory mapping. This allows
2374 #          using gdb to process the core file.
2375 #
2376 #          IMPORTANT: this option can make QEMU allocate several gigabytes
2377 #                     of RAM. This can happen for a large guest, or a
2378 #                     malicious guest pretending to be large.
2379 #
2380 #          Also, paging=true has the following limitations:
2381 #
2382 #             1. The guest may be in a catastrophic state or can have corrupted
2383 #                memory, which cannot be trusted
2384 #             2. The guest can be in real-mode even if paging is enabled. For
2385 #                example, the guest uses ACPI to sleep, and ACPI sleep state
2386 #                goes in real-mode
2387 #             3. Currently only supported on i386 and x86_64.
2388 #
2389 # @protocol: the filename or file descriptor of the vmcore. The supported
2390 #            protocols are:
2391 #
2392 #            1. file: the protocol starts with "file:", and the following
2393 #               string is the file's path.
2394 #            2. fd: the protocol starts with "fd:", and the following string
2395 #               is the fd's name.
2396 #
2397 # @detach: #optional if true, QMP will return immediately rather than
2398 #          waiting for the dump to finish. The user can track progress
2399 #          using "query-dump". (since 2.6).
2400 #
2401 # @begin: #optional if specified, the starting physical address.
2402 #
2403 # @length: #optional if specified, the memory size, in bytes. If you don't
2404 #          want to dump all guest's memory, please specify the start @begin
2405 #          and @length
2406 #
2407 # @format: #optional if specified, the format of guest memory dump. But non-elf
2408 #          format is conflict with paging and filter, ie. @paging, @begin and
2409 #          @length is not allowed to be specified with non-elf @format at the
2410 #          same time (since 2.0)
2411 #
2412 # Returns: nothing on success
2413 #
2414 # Since: 1.2
2415 ##
2416 { 'command': 'dump-guest-memory',
2417   'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
2418             '*begin': 'int', '*length': 'int',
2419             '*format': 'DumpGuestMemoryFormat'} }
2420
2421 ##
2422 # @DumpStatus:
2423 #
2424 # Describe the status of a long-running background guest memory dump.
2425 #
2426 # @none: no dump-guest-memory has started yet.
2427 #
2428 # @active: there is one dump running in background.
2429 #
2430 # @completed: the last dump has finished successfully.
2431 #
2432 # @failed: the last dump has failed.
2433 #
2434 # Since: 2.6
2435 ##
2436 { 'enum': 'DumpStatus',
2437   'data': [ 'none', 'active', 'completed', 'failed' ] }
2438
2439 ##
2440 # @DumpQueryResult:
2441 #
2442 # The result format for 'query-dump'.
2443 #
2444 # @status: enum of @DumpStatus, which shows current dump status
2445 #
2446 # @completed: bytes written in latest dump (uncompressed)
2447 #
2448 # @total: total bytes to be written in latest dump (uncompressed)
2449 #
2450 # Since: 2.6
2451 ##
2452 { 'struct': 'DumpQueryResult',
2453   'data': { 'status': 'DumpStatus',
2454             'completed': 'int',
2455             'total': 'int' } }
2456
2457 ##
2458 # @query-dump:
2459 #
2460 # Query latest dump status.
2461 #
2462 # Returns: A @DumpStatus object showing the dump status.
2463 #
2464 # Since: 2.6
2465 ##
2466 { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
2467
2468 ##
2469 # @DumpGuestMemoryCapability:
2470 #
2471 # A list of the available formats for dump-guest-memory
2472 #
2473 # Since: 2.0
2474 ##
2475 { 'struct': 'DumpGuestMemoryCapability',
2476   'data': {
2477       'formats': ['DumpGuestMemoryFormat'] } }
2478
2479 ##
2480 # @query-dump-guest-memory-capability:
2481 #
2482 # Returns the available formats for dump-guest-memory
2483 #
2484 # Returns:  A @DumpGuestMemoryCapability object listing available formats for
2485 #           dump-guest-memory
2486 #
2487 # Since: 2.0
2488 ##
2489 { 'command': 'query-dump-guest-memory-capability',
2490   'returns': 'DumpGuestMemoryCapability' }
2491
2492 ##
2493 # @dump-skeys:
2494 #
2495 # Dump guest's storage keys
2496 #
2497 # @filename: the path to the file to dump to
2498 #
2499 # This command is only supported on s390 architecture.
2500 #
2501 # Since: 2.5
2502 ##
2503 { 'command': 'dump-skeys',
2504   'data': { 'filename': 'str' } }
2505
2506 ##
2507 # @netdev_add:
2508 #
2509 # Add a network backend.
2510 #
2511 # @type: the type of network backend.  Current valid values are 'user', 'tap',
2512 #        'vde', 'socket', 'dump' and 'bridge'
2513 #
2514 # @id: the name of the new network backend
2515 #
2516 # Additional arguments depend on the type.
2517 #
2518 # TODO This command effectively bypasses QAPI completely due to its
2519 # "additional arguments" business.  It shouldn't have been added to
2520 # the schema in this form.  It should be qapified properly, or
2521 # replaced by a properly qapified command.
2522 #
2523 # Since: 0.14.0
2524 #
2525 # Returns: Nothing on success
2526 #          If @type is not a valid network backend, DeviceNotFound
2527 ##
2528 { 'command': 'netdev_add',
2529   'data': {'type': 'str', 'id': 'str'},
2530   'gen': false }                # so we can get the additional arguments
2531
2532 ##
2533 # @netdev_del:
2534 #
2535 # Remove a network backend.
2536 #
2537 # @id: the name of the network backend to remove
2538 #
2539 # Returns: Nothing on success
2540 #          If @id is not a valid network backend, DeviceNotFound
2541 #
2542 # Since: 0.14.0
2543 ##
2544 { 'command': 'netdev_del', 'data': {'id': 'str'} }
2545
2546 ##
2547 # @object-add:
2548 #
2549 # Create a QOM object.
2550 #
2551 # @qom-type: the class name for the object to be created
2552 #
2553 # @id: the name of the new object
2554 #
2555 # @props: #optional a dictionary of properties to be passed to the backend
2556 #
2557 # Returns: Nothing on success
2558 #          Error if @qom-type is not a valid class name
2559 #
2560 # Since: 2.0
2561 ##
2562 { 'command': 'object-add',
2563   'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'} }
2564
2565 ##
2566 # @object-del:
2567 #
2568 # Remove a QOM object.
2569 #
2570 # @id: the name of the QOM object to remove
2571 #
2572 # Returns: Nothing on success
2573 #          Error if @id is not a valid id for a QOM object
2574 #
2575 # Since: 2.0
2576 ##
2577 { 'command': 'object-del', 'data': {'id': 'str'} }
2578
2579 ##
2580 # @NetdevNoneOptions:
2581 #
2582 # Use it alone to have zero network devices.
2583 #
2584 # Since: 1.2
2585 ##
2586 { 'struct': 'NetdevNoneOptions',
2587   'data': { } }
2588
2589 ##
2590 # @NetLegacyNicOptions:
2591 #
2592 # Create a new Network Interface Card.
2593 #
2594 # @netdev: #optional id of -netdev to connect to
2595 #
2596 # @macaddr: #optional MAC address
2597 #
2598 # @model: #optional device model (e1000, rtl8139, virtio etc.)
2599 #
2600 # @addr: #optional PCI device address
2601 #
2602 # @vectors: #optional number of MSI-x vectors, 0 to disable MSI-X
2603 #
2604 # Since: 1.2
2605 ##
2606 { 'struct': 'NetLegacyNicOptions',
2607   'data': {
2608     '*netdev':  'str',
2609     '*macaddr': 'str',
2610     '*model':   'str',
2611     '*addr':    'str',
2612     '*vectors': 'uint32' } }
2613
2614 ##
2615 # @String:
2616 #
2617 # A fat type wrapping 'str', to be embedded in lists.
2618 #
2619 # Since: 1.2
2620 ##
2621 { 'struct': 'String',
2622   'data': {
2623     'str': 'str' } }
2624
2625 ##
2626 # @NetdevUserOptions:
2627 #
2628 # Use the user mode network stack which requires no administrator privilege to
2629 # run.
2630 #
2631 # @hostname: #optional client hostname reported by the builtin DHCP server
2632 #
2633 # @restrict: #optional isolate the guest from the host
2634 #
2635 # @ipv4: #optional whether to support IPv4, default true for enabled
2636 #        (since 2.6)
2637 #
2638 # @ipv6: #optional whether to support IPv6, default true for enabled
2639 #        (since 2.6)
2640 #
2641 # @ip: #optional legacy parameter, use net= instead
2642 #
2643 # @net: #optional IP network address that the guest will see, in the
2644 #       form addr[/netmask] The netmask is optional, and can be
2645 #       either in the form a.b.c.d or as a number of valid top-most
2646 #       bits. Default is 10.0.2.0/24.
2647 #
2648 # @host: #optional guest-visible address of the host
2649 #
2650 # @tftp: #optional root directory of the built-in TFTP server
2651 #
2652 # @bootfile: #optional BOOTP filename, for use with tftp=
2653 #
2654 # @dhcpstart: #optional the first of the 16 IPs the built-in DHCP server can
2655 #             assign
2656 #
2657 # @dns: #optional guest-visible address of the virtual nameserver
2658 #
2659 # @dnssearch: #optional list of DNS suffixes to search, passed as DHCP option
2660 #             to the guest
2661 #
2662 # @ipv6-prefix: #optional IPv6 network prefix (default is fec0::) (since
2663 #               2.6). The network prefix is given in the usual
2664 #               hexadecimal IPv6 address notation.
2665 #
2666 # @ipv6-prefixlen: #optional IPv6 network prefix length (default is 64)
2667 #                  (since 2.6)
2668 #
2669 # @ipv6-host: #optional guest-visible IPv6 address of the host (since 2.6)
2670 #
2671 # @ipv6-dns: #optional guest-visible IPv6 address of the virtual
2672 #            nameserver (since 2.6)
2673 #
2674 # @smb: #optional root directory of the built-in SMB server
2675 #
2676 # @smbserver: #optional IP address of the built-in SMB server
2677 #
2678 # @hostfwd: #optional redirect incoming TCP or UDP host connections to guest
2679 #           endpoints
2680 #
2681 # @guestfwd: #optional forward guest TCP connections
2682 #
2683 # Since: 1.2
2684 ##
2685 { 'struct': 'NetdevUserOptions',
2686   'data': {
2687     '*hostname':  'str',
2688     '*restrict':  'bool',
2689     '*ipv4':      'bool',
2690     '*ipv6':      'bool',
2691     '*ip':        'str',
2692     '*net':       'str',
2693     '*host':      'str',
2694     '*tftp':      'str',
2695     '*bootfile':  'str',
2696     '*dhcpstart': 'str',
2697     '*dns':       'str',
2698     '*dnssearch': ['String'],
2699     '*ipv6-prefix':      'str',
2700     '*ipv6-prefixlen':   'int',
2701     '*ipv6-host':        'str',
2702     '*ipv6-dns':         'str',
2703     '*smb':       'str',
2704     '*smbserver': 'str',
2705     '*hostfwd':   ['String'],
2706     '*guestfwd':  ['String'] } }
2707
2708 ##
2709 # @NetdevTapOptions:
2710 #
2711 # Connect the host TAP network interface name to the VLAN.
2712 #
2713 # @ifname: #optional interface name
2714 #
2715 # @fd: #optional file descriptor of an already opened tap
2716 #
2717 # @fds: #optional multiple file descriptors of already opened multiqueue capable
2718 # tap
2719 #
2720 # @script: #optional script to initialize the interface
2721 #
2722 # @downscript: #optional script to shut down the interface
2723 #
2724 # @br: #optional bridge name (since 2.8)
2725 #
2726 # @helper: #optional command to execute to configure bridge
2727 #
2728 # @sndbuf: #optional send buffer limit. Understands [TGMKkb] suffixes.
2729 #
2730 # @vnet_hdr: #optional enable the IFF_VNET_HDR flag on the tap interface
2731 #
2732 # @vhost: #optional enable vhost-net network accelerator
2733 #
2734 # @vhostfd: #optional file descriptor of an already opened vhost net device
2735 #
2736 # @vhostfds: #optional file descriptors of multiple already opened vhost net
2737 # devices
2738 #
2739 # @vhostforce: #optional vhost on for non-MSIX virtio guests
2740 #
2741 # @queues: #optional number of queues to be created for multiqueue capable tap
2742 #
2743 # @poll-us: #optional maximum number of microseconds that could
2744 # be spent on busy polling for tap (since 2.7)
2745 #
2746 # Since: 1.2
2747 ##
2748 { 'struct': 'NetdevTapOptions',
2749   'data': {
2750     '*ifname':     'str',
2751     '*fd':         'str',
2752     '*fds':        'str',
2753     '*script':     'str',
2754     '*downscript': 'str',
2755     '*br':         'str',
2756     '*helper':     'str',
2757     '*sndbuf':     'size',
2758     '*vnet_hdr':   'bool',
2759     '*vhost':      'bool',
2760     '*vhostfd':    'str',
2761     '*vhostfds':   'str',
2762     '*vhostforce': 'bool',
2763     '*queues':     'uint32',
2764     '*poll-us':    'uint32'} }
2765
2766 ##
2767 # @NetdevSocketOptions:
2768 #
2769 # Connect the VLAN to a remote VLAN in another QEMU virtual machine using a TCP
2770 # socket connection.
2771 #
2772 # @fd: #optional file descriptor of an already opened socket
2773 #
2774 # @listen: #optional port number, and optional hostname, to listen on
2775 #
2776 # @connect: #optional port number, and optional hostname, to connect to
2777 #
2778 # @mcast: #optional UDP multicast address and port number
2779 #
2780 # @localaddr: #optional source address and port for multicast and udp packets
2781 #
2782 # @udp: #optional UDP unicast address and port number
2783 #
2784 # Since: 1.2
2785 ##
2786 { 'struct': 'NetdevSocketOptions',
2787   'data': {
2788     '*fd':        'str',
2789     '*listen':    'str',
2790     '*connect':   'str',
2791     '*mcast':     'str',
2792     '*localaddr': 'str',
2793     '*udp':       'str' } }
2794
2795 ##
2796 # @NetdevL2TPv3Options:
2797 #
2798 # Connect the VLAN to Ethernet over L2TPv3 Static tunnel
2799 #
2800 # @src: source address
2801 #
2802 # @dst: destination address
2803 #
2804 # @srcport: #optional source port - mandatory for udp, optional for ip
2805 #
2806 # @dstport: #optional destination port - mandatory for udp, optional for ip
2807 #
2808 # @ipv6: #optional - force the use of ipv6
2809 #
2810 # @udp: #optional - use the udp version of l2tpv3 encapsulation
2811 #
2812 # @cookie64: #optional - use 64 bit coookies
2813 #
2814 # @counter: #optional have sequence counter
2815 #
2816 # @pincounter: #optional pin sequence counter to zero -
2817 #              workaround for buggy implementations or
2818 #              networks with packet reorder
2819 #
2820 # @txcookie: #optional 32 or 64 bit transmit cookie
2821 #
2822 # @rxcookie: #optional 32 or 64 bit receive cookie
2823 #
2824 # @txsession: 32 bit transmit session
2825 #
2826 # @rxsession: #optional 32 bit receive session - if not specified
2827 #             set to the same value as transmit
2828 #
2829 # @offset: #optional additional offset - allows the insertion of
2830 #          additional application-specific data before the packet payload
2831 #
2832 # Since: 2.1
2833 ##
2834 { 'struct': 'NetdevL2TPv3Options',
2835   'data': {
2836     'src':          'str',
2837     'dst':          'str',
2838     '*srcport':     'str',
2839     '*dstport':     'str',
2840     '*ipv6':        'bool',
2841     '*udp':         'bool',
2842     '*cookie64':    'bool',
2843     '*counter':     'bool',
2844     '*pincounter':  'bool',
2845     '*txcookie':    'uint64',
2846     '*rxcookie':    'uint64',
2847     'txsession':    'uint32',
2848     '*rxsession':   'uint32',
2849     '*offset':      'uint32' } }
2850
2851 ##
2852 # @NetdevVdeOptions:
2853 #
2854 # Connect the VLAN to a vde switch running on the host.
2855 #
2856 # @sock: #optional socket path
2857 #
2858 # @port: #optional port number
2859 #
2860 # @group: #optional group owner of socket
2861 #
2862 # @mode: #optional permissions for socket
2863 #
2864 # Since: 1.2
2865 ##
2866 { 'struct': 'NetdevVdeOptions',
2867   'data': {
2868     '*sock':  'str',
2869     '*port':  'uint16',
2870     '*group': 'str',
2871     '*mode':  'uint16' } }
2872
2873 ##
2874 # @NetdevDumpOptions:
2875 #
2876 # Dump VLAN network traffic to a file.
2877 #
2878 # @len: #optional per-packet size limit (64k default). Understands [TGMKkb]
2879 # suffixes.
2880 #
2881 # @file: #optional dump file path (default is qemu-vlan0.pcap)
2882 #
2883 # Since: 1.2
2884 ##
2885 { 'struct': 'NetdevDumpOptions',
2886   'data': {
2887     '*len':  'size',
2888     '*file': 'str' } }
2889
2890 ##
2891 # @NetdevBridgeOptions:
2892 #
2893 # Connect a host TAP network interface to a host bridge device.
2894 #
2895 # @br: #optional bridge name
2896 #
2897 # @helper: #optional command to execute to configure bridge
2898 #
2899 # Since: 1.2
2900 ##
2901 { 'struct': 'NetdevBridgeOptions',
2902   'data': {
2903     '*br':     'str',
2904     '*helper': 'str' } }
2905
2906 ##
2907 # @NetdevHubPortOptions:
2908 #
2909 # Connect two or more net clients through a software hub.
2910 #
2911 # @hubid: hub identifier number
2912 #
2913 # Since: 1.2
2914 ##
2915 { 'struct': 'NetdevHubPortOptions',
2916   'data': {
2917     'hubid':     'int32' } }
2918
2919 ##
2920 # @NetdevNetmapOptions:
2921 #
2922 # Connect a client to a netmap-enabled NIC or to a VALE switch port
2923 #
2924 # @ifname: Either the name of an existing network interface supported by
2925 #          netmap, or the name of a VALE port (created on the fly).
2926 #          A VALE port name is in the form 'valeXXX:YYY', where XXX and
2927 #          YYY are non-negative integers. XXX identifies a switch and
2928 #          YYY identifies a port of the switch. VALE ports having the
2929 #          same XXX are therefore connected to the same switch.
2930 #
2931 # @devname: #optional path of the netmap device (default: '/dev/netmap').
2932 #
2933 # Since: 2.0
2934 ##
2935 { 'struct': 'NetdevNetmapOptions',
2936   'data': {
2937     'ifname':     'str',
2938     '*devname':    'str' } }
2939
2940 ##
2941 # @NetdevVhostUserOptions:
2942 #
2943 # Vhost-user network backend
2944 #
2945 # @chardev: name of a unix socket chardev
2946 #
2947 # @vhostforce: #optional vhost on for non-MSIX virtio guests (default: false).
2948 #
2949 # @queues: #optional number of queues to be created for multiqueue vhost-user
2950 #          (default: 1) (Since 2.5)
2951 #
2952 # Since: 2.1
2953 ##
2954 { 'struct': 'NetdevVhostUserOptions',
2955   'data': {
2956     'chardev':        'str',
2957     '*vhostforce':    'bool',
2958     '*queues':        'int' } }
2959
2960 ##
2961 # @NetClientDriver:
2962 #
2963 # Available netdev drivers.
2964 #
2965 # Since: 2.7
2966 ##
2967 { 'enum': 'NetClientDriver',
2968   'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', 'dump',
2969             'bridge', 'hubport', 'netmap', 'vhost-user' ] }
2970
2971 ##
2972 # @Netdev:
2973 #
2974 # Captures the configuration of a network device.
2975 #
2976 # @id: identifier for monitor commands.
2977 #
2978 # @type: Specify the driver used for interpreting remaining arguments.
2979 #
2980 # Since: 1.2
2981 #
2982 # 'l2tpv3' - since 2.1
2983 ##
2984 { 'union': 'Netdev',
2985   'base': { 'id': 'str', 'type': 'NetClientDriver' },
2986   'discriminator': 'type',
2987   'data': {
2988     'none':     'NetdevNoneOptions',
2989     'nic':      'NetLegacyNicOptions',
2990     'user':     'NetdevUserOptions',
2991     'tap':      'NetdevTapOptions',
2992     'l2tpv3':   'NetdevL2TPv3Options',
2993     'socket':   'NetdevSocketOptions',
2994     'vde':      'NetdevVdeOptions',
2995     'dump':     'NetdevDumpOptions',
2996     'bridge':   'NetdevBridgeOptions',
2997     'hubport':  'NetdevHubPortOptions',
2998     'netmap':   'NetdevNetmapOptions',
2999     'vhost-user': 'NetdevVhostUserOptions' } }
3000
3001 ##
3002 # @NetLegacy:
3003 #
3004 # Captures the configuration of a network device; legacy.
3005 #
3006 # @vlan: #optional vlan number
3007 #
3008 # @id: #optional identifier for monitor commands
3009 #
3010 # @name: #optional identifier for monitor commands, ignored if @id is present
3011 #
3012 # @opts: device type specific properties (legacy)
3013 #
3014 # Since: 1.2
3015 ##
3016 { 'struct': 'NetLegacy',
3017   'data': {
3018     '*vlan': 'int32',
3019     '*id':   'str',
3020     '*name': 'str',
3021     'opts':  'NetLegacyOptions' } }
3022
3023 ##
3024 # @NetLegacyOptions:
3025 #
3026 # Like Netdev, but for use only by the legacy command line options
3027 #
3028 # Since: 1.2
3029 ##
3030 { 'union': 'NetLegacyOptions',
3031   'data': {
3032     'none':     'NetdevNoneOptions',
3033     'nic':      'NetLegacyNicOptions',
3034     'user':     'NetdevUserOptions',
3035     'tap':      'NetdevTapOptions',
3036     'l2tpv3':   'NetdevL2TPv3Options',
3037     'socket':   'NetdevSocketOptions',
3038     'vde':      'NetdevVdeOptions',
3039     'dump':     'NetdevDumpOptions',
3040     'bridge':   'NetdevBridgeOptions',
3041     'netmap':   'NetdevNetmapOptions',
3042     'vhost-user': 'NetdevVhostUserOptions' } }
3043
3044 ##
3045 # @NetFilterDirection:
3046 #
3047 # Indicates whether a netfilter is attached to a netdev's transmit queue or
3048 # receive queue or both.
3049 #
3050 # @all: the filter is attached both to the receive and the transmit
3051 #       queue of the netdev (default).
3052 #
3053 # @rx: the filter is attached to the receive queue of the netdev,
3054 #      where it will receive packets sent to the netdev.
3055 #
3056 # @tx: the filter is attached to the transmit queue of the netdev,
3057 #      where it will receive packets sent by the netdev.
3058 #
3059 # Since: 2.5
3060 ##
3061 { 'enum': 'NetFilterDirection',
3062   'data': [ 'all', 'rx', 'tx' ] }
3063
3064 ##
3065 # @InetSocketAddress:
3066 #
3067 # Captures a socket address or address range in the Internet namespace.
3068 #
3069 # @host: host part of the address
3070 #
3071 # @port: port part of the address, or lowest port if @to is present
3072 #
3073 # @to: highest port to try
3074 #
3075 # @ipv4: whether to accept IPv4 addresses, default try both IPv4 and IPv6
3076 #        #optional
3077 #
3078 # @ipv6: whether to accept IPv6 addresses, default try both IPv4 and IPv6
3079 #        #optional
3080 #
3081 # Since: 1.3
3082 ##
3083 { 'struct': 'InetSocketAddress',
3084   'data': {
3085     'host': 'str',
3086     'port': 'str',
3087     '*to': 'uint16',
3088     '*ipv4': 'bool',
3089     '*ipv6': 'bool' } }
3090
3091 ##
3092 # @UnixSocketAddress:
3093 #
3094 # Captures a socket address in the local ("Unix socket") namespace.
3095 #
3096 # @path: filesystem path to use
3097 #
3098 # Since: 1.3
3099 ##
3100 { 'struct': 'UnixSocketAddress',
3101   'data': {
3102     'path': 'str' } }
3103
3104 ##
3105 # @VsockSocketAddress:
3106 #
3107 # Captures a socket address in the vsock namespace.
3108 #
3109 # @cid: unique host identifier
3110 # @port: port
3111 #
3112 # Note: string types are used to allow for possible future hostname or
3113 # service resolution support.
3114 #
3115 # Since: 2.8
3116 ##
3117 { 'struct': 'VsockSocketAddress',
3118   'data': {
3119     'cid': 'str',
3120     'port': 'str' } }
3121
3122 ##
3123 # @SocketAddress:
3124 #
3125 # Captures the address of a socket, which could also be a named file descriptor
3126 #
3127 # Since: 1.3
3128 ##
3129 { 'union': 'SocketAddress',
3130   'data': {
3131     'inet': 'InetSocketAddress',
3132     'unix': 'UnixSocketAddress',
3133     'vsock': 'VsockSocketAddress',
3134     'fd': 'String' } }
3135
3136 ##
3137 # @getfd:
3138 #
3139 # Receive a file descriptor via SCM rights and assign it a name
3140 #
3141 # @fdname: file descriptor name
3142 #
3143 # Returns: Nothing on success
3144 #
3145 # Since: 0.14.0
3146 #
3147 # Notes: If @fdname already exists, the file descriptor assigned to
3148 #        it will be closed and replaced by the received file
3149 #        descriptor.
3150 #        The 'closefd' command can be used to explicitly close the
3151 #        file descriptor when it is no longer needed.
3152 ##
3153 { 'command': 'getfd', 'data': {'fdname': 'str'} }
3154
3155 ##
3156 # @closefd:
3157 #
3158 # Close a file descriptor previously passed via SCM rights
3159 #
3160 # @fdname: file descriptor name
3161 #
3162 # Returns: Nothing on success
3163 #
3164 # Since: 0.14.0
3165 ##
3166 { 'command': 'closefd', 'data': {'fdname': 'str'} }
3167
3168 ##
3169 # @MachineInfo:
3170 #
3171 # Information describing a machine.
3172 #
3173 # @name: the name of the machine
3174 #
3175 # @alias: #optional an alias for the machine name
3176 #
3177 # @is-default: #optional whether the machine is default
3178 #
3179 # @cpu-max: maximum number of CPUs supported by the machine type
3180 #           (since 1.5.0)
3181 #
3182 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
3183 #
3184 # Since: 1.2.0
3185 ##
3186 { 'struct': 'MachineInfo',
3187   'data': { 'name': 'str', '*alias': 'str',
3188             '*is-default': 'bool', 'cpu-max': 'int',
3189             'hotpluggable-cpus': 'bool'} }
3190
3191 ##
3192 # @query-machines:
3193 #
3194 # Return a list of supported machines
3195 #
3196 # Returns: a list of MachineInfo
3197 #
3198 # Since: 1.2.0
3199 ##
3200 { 'command': 'query-machines', 'returns': ['MachineInfo'] }
3201
3202 ##
3203 # @CpuDefinitionInfo:
3204 #
3205 # Virtual CPU definition.
3206 #
3207 # @name: the name of the CPU definition
3208 #
3209 # @migration-safe: #optional whether a CPU definition can be safely used for
3210 #                  migration in combination with a QEMU compatibility machine
3211 #                  when migrating between different QMU versions and between
3212 #                  hosts with different sets of (hardware or software)
3213 #                  capabilities. If not provided, information is not available
3214 #                  and callers should not assume the CPU definition to be
3215 #                  migration-safe. (since 2.8)
3216 #
3217 # @static: whether a CPU definition is static and will not change depending on
3218 #          QEMU version, machine type, machine options and accelerator options.
3219 #          A static model is always migration-safe. (since 2.8)
3220 #
3221 # @unavailable-features: #optional List of properties that prevent
3222 #                        the CPU model from running in the current
3223 #                        host. (since 2.8)
3224 #
3225 # @unavailable-features is a list of QOM property names that
3226 # represent CPU model attributes that prevent the CPU from running.
3227 # If the QOM property is read-only, that means there's no known
3228 # way to make the CPU model run in the current host. Implementations
3229 # that choose not to provide specific information return the
3230 # property name "type".
3231 # If the property is read-write, it means that it MAY be possible
3232 # to run the CPU model in the current host if that property is
3233 # changed. Management software can use it as hints to suggest or
3234 # choose an alternative for the user, or just to generate meaningful
3235 # error messages explaining why the CPU model can't be used.
3236 # If @unavailable-features is an empty list, the CPU model is
3237 # runnable using the current host and machine-type.
3238 # If @unavailable-features is not present, runnability
3239 # information for the CPU is not available.
3240 #
3241 # Since: 1.2.0
3242 ##
3243 { 'struct': 'CpuDefinitionInfo',
3244   'data': { 'name': 'str', '*migration-safe': 'bool', 'static': 'bool',
3245             '*unavailable-features': [ 'str' ] } }
3246
3247 ##
3248 # @query-cpu-definitions:
3249 #
3250 # Return a list of supported virtual CPU definitions
3251 #
3252 # Returns: a list of CpuDefInfo
3253 #
3254 # Since: 1.2.0
3255 ##
3256 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }
3257
3258 ##
3259 # @CpuModelInfo:
3260 #
3261 # Virtual CPU model.
3262 #
3263 # A CPU model consists of the name of a CPU definition, to which
3264 # delta changes are applied (e.g. features added/removed). Most magic values
3265 # that an architecture might require should be hidden behind the name.
3266 # However, if required, architectures can expose relevant properties.
3267 #
3268 # @name: the name of the CPU definition the model is based on
3269 # @props: #optional a dictionary of QOM properties to be applied
3270 #
3271 # Since: 2.8.0
3272 ##
3273 { 'struct': 'CpuModelInfo',
3274   'data': { 'name': 'str',
3275             '*props': 'any' } }
3276
3277 ##
3278 # @CpuModelExpansionType:
3279 #
3280 # An enumeration of CPU model expansion types.
3281 #
3282 # @static: Expand to a static CPU model, a combination of a static base
3283 #          model name and property delta changes. As the static base model will
3284 #          never change, the expanded CPU model will be the same, independant of
3285 #          independent of QEMU version, machine type, machine options, and
3286 #          accelerator options. Therefore, the resulting model can be used by
3287 #          tooling without having to specify a compatibility machine - e.g. when
3288 #          displaying the "host" model. static CPU models are migration-safe.
3289 #
3290 # @full: Expand all properties. The produced model is not guaranteed to be
3291 #        migration-safe, but allows tooling to get an insight and work with
3292 #        model details.
3293 #
3294 # Since: 2.8.0
3295 ##
3296 { 'enum': 'CpuModelExpansionType',
3297   'data': [ 'static', 'full' ] }
3298
3299
3300 ##
3301 # @CpuModelExpansionInfo:
3302 #
3303 # The result of a cpu model expansion.
3304 #
3305 # @model: the expanded CpuModelInfo.
3306 #
3307 # Since: 2.8.0
3308 ##
3309 { 'struct': 'CpuModelExpansionInfo',
3310   'data': { 'model': 'CpuModelInfo' } }
3311
3312
3313 ##
3314 # @query-cpu-model-expansion:
3315 #
3316 # Expands a given CPU model (or a combination of CPU model + additional options)
3317 # to different granularities, allowing tooling to get an understanding what a
3318 # specific CPU model looks like in QEMU under a certain configuration.
3319 #
3320 # This interface can be used to query the "host" CPU model.
3321 #
3322 # The data returned by this command may be affected by:
3323 #
3324 # * QEMU version: CPU models may look different depending on the QEMU version.
3325 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
3326 # * machine-type: CPU model  may look different depending on the machine-type.
3327 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
3328 # * machine options (including accelerator): in some architectures, CPU models
3329 #   may look different depending on machine and accelerator options. (Except for
3330 #   CPU models reported as "static" in query-cpu-definitions.)
3331 # * "-cpu" arguments and global properties: arguments to the -cpu option and
3332 #   global properties may affect expansion of CPU models. Using
3333 #   query-cpu-model-expansion while using these is not advised.
3334 #
3335 # Some architectures may not support all expansion types. s390x supports
3336 # "full" and "static".
3337 #
3338 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
3339 #          not supported, if the model cannot be expanded, if the model contains
3340 #          an unknown CPU definition name, unknown properties or properties
3341 #          with a wrong type. Also returns an error if an expansion type is
3342 #          not supported.
3343 #
3344 # Since: 2.8.0
3345 ##
3346 { 'command': 'query-cpu-model-expansion',
3347   'data': { 'type': 'CpuModelExpansionType',
3348             'model': 'CpuModelInfo' },
3349   'returns': 'CpuModelExpansionInfo' }
3350
3351 ##
3352 # @CpuModelCompareResult:
3353 #
3354 # An enumeration of CPU model comparation results. The result is usually
3355 # calculated using e.g. CPU features or CPU generations.
3356 #
3357 # @incompatible: If model A is incompatible to model B, model A is not
3358 #                guaranteed to run where model B runs and the other way around.
3359 #
3360 # @identical: If model A is identical to model B, model A is guaranteed to run
3361 #             where model B runs and the other way around.
3362 #
3363 # @superset: If model A is a superset of model B, model B is guaranteed to run
3364 #            where model A runs. There are no guarantees about the other way.
3365 #
3366 # @subset: If model A is a subset of model B, model A is guaranteed to run
3367 #          where model B runs. There are no guarantees about the other way.
3368 #
3369 # Since: 2.8.0
3370 ##
3371 { 'enum': 'CpuModelCompareResult',
3372   'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
3373
3374 ##
3375 # @CpuModelCompareInfo:
3376 #
3377 # The result of a CPU model comparison.
3378 #
3379 # @result: The result of the compare operation.
3380 # @responsible-properties: List of properties that led to the comparison result
3381 #                          not being identical.
3382 #
3383 # @responsible-properties is a list of QOM property names that led to
3384 # both CPUs not being detected as identical. For identical models, this
3385 # list is empty.
3386 # If a QOM property is read-only, that means there's no known way to make the
3387 # CPU models identical. If the special property name "type" is included, the
3388 # models are by definition not identical and cannot be made identical.
3389 #
3390 # Since: 2.8.0
3391 ##
3392 { 'struct': 'CpuModelCompareInfo',
3393   'data': {'result': 'CpuModelCompareResult',
3394            'responsible-properties': ['str']
3395           }
3396 }
3397
3398 ##
3399 # @query-cpu-model-comparison:
3400 #
3401 # Compares two CPU models, returning how they compare in a specific
3402 # configuration. The results indicates how both models compare regarding
3403 # runnability. This result can be used by tooling to make decisions if a
3404 # certain CPU model will run in a certain configuration or if a compatible
3405 # CPU model has to be created by baselining.
3406 #
3407 # Usually, a CPU model is compared against the maximum possible CPU model
3408 # of a certain configuration (e.g. the "host" model for KVM). If that CPU
3409 # model is identical or a subset, it will run in that configuration.
3410 #
3411 # The result returned by this command may be affected by:
3412 #
3413 # * QEMU version: CPU models may look different depending on the QEMU version.
3414 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
3415 # * machine-type: CPU model may look different depending on the machine-type.
3416 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
3417 # * machine options (including accelerator): in some architectures, CPU models
3418 #   may look different depending on machine and accelerator options. (Except for
3419 #   CPU models reported as "static" in query-cpu-definitions.)
3420 # * "-cpu" arguments and global properties: arguments to the -cpu option and
3421 #   global properties may affect expansion of CPU models. Using
3422 #   query-cpu-model-expansion while using these is not advised.
3423 #
3424 # Some architectures may not support comparing CPU models. s390x supports
3425 # comparing CPU models.
3426 #
3427 # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
3428 #          not supported, if a model cannot be used, if a model contains
3429 #          an unknown cpu definition name, unknown properties or properties
3430 #          with wrong types.
3431 #
3432 # Since: 2.8.0
3433 ##
3434 { 'command': 'query-cpu-model-comparison',
3435   'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
3436   'returns': 'CpuModelCompareInfo' }
3437
3438 ##
3439 # @CpuModelBaselineInfo:
3440 #
3441 # The result of a CPU model baseline.
3442 #
3443 # @model: the baselined CpuModelInfo.
3444 #
3445 # Since: 2.8.0
3446 ##
3447 { 'struct': 'CpuModelBaselineInfo',
3448   'data': { 'model': 'CpuModelInfo' } }
3449
3450 ##
3451 # @query-cpu-model-baseline:
3452 #
3453 # Baseline two CPU models, creating a compatible third model. The created
3454 # model will always be a static, migration-safe CPU model (see "static"
3455 # CPU model expansion for details).
3456 #
3457 # This interface can be used by tooling to create a compatible CPU model out
3458 # two CPU models. The created CPU model will be identical to or a subset of
3459 # both CPU models when comparing them. Therefore, the created CPU model is
3460 # guaranteed to run where the given CPU models run.
3461 #
3462 # The result returned by this command may be affected by:
3463 #
3464 # * QEMU version: CPU models may look different depending on the QEMU version.
3465 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
3466 # * machine-type: CPU model may look different depending on the machine-type.
3467 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
3468 # * machine options (including accelerator): in some architectures, CPU models
3469 #   may look different depending on machine and accelerator options. (Except for
3470 #   CPU models reported as "static" in query-cpu-definitions.)
3471 # * "-cpu" arguments and global properties: arguments to the -cpu option and
3472 #   global properties may affect expansion of CPU models. Using
3473 #   query-cpu-model-expansion while using these is not advised.
3474 #
3475 # Some architectures may not support baselining CPU models. s390x supports
3476 # baselining CPU models.
3477 #
3478 # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
3479 #          not supported, if a model cannot be used, if a model contains
3480 #          an unknown cpu definition name, unknown properties or properties
3481 #          with wrong types.
3482 #
3483 # Since: 2.8.0
3484 ##
3485 { 'command': 'query-cpu-model-baseline',
3486   'data': { 'modela': 'CpuModelInfo',
3487             'modelb': 'CpuModelInfo' },
3488   'returns': 'CpuModelBaselineInfo' }
3489
3490 ##
3491 # @AddfdInfo:
3492 #
3493 # Information about a file descriptor that was added to an fd set.
3494 #
3495 # @fdset-id: The ID of the fd set that @fd was added to.
3496 #
3497 # @fd: The file descriptor that was received via SCM rights and
3498 #      added to the fd set.
3499 #
3500 # Since: 1.2.0
3501 ##
3502 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
3503
3504 ##
3505 # @add-fd:
3506 #
3507 # Add a file descriptor, that was passed via SCM rights, to an fd set.
3508 #
3509 # @fdset-id: #optional The ID of the fd set to add the file descriptor to.
3510 #
3511 # @opaque: #optional A free-form string that can be used to describe the fd.
3512 #
3513 # Returns: @AddfdInfo on success
3514 #          If file descriptor was not received, FdNotSupplied
3515 #          If @fdset-id is a negative value, InvalidParameterValue
3516 #
3517 # Notes: The list of fd sets is shared by all monitor connections.
3518 #
3519 #        If @fdset-id is not specified, a new fd set will be created.
3520 #
3521 # Since: 1.2.0
3522 ##
3523 { 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'},
3524   'returns': 'AddfdInfo' }
3525
3526 ##
3527 # @remove-fd:
3528 #
3529 # Remove a file descriptor from an fd set.
3530 #
3531 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
3532 #
3533 # @fd: #optional The file descriptor that is to be removed.
3534 #
3535 # Returns: Nothing on success
3536 #          If @fdset-id or @fd is not found, FdNotFound
3537 #
3538 # Since: 1.2.0
3539 #
3540 # Notes: The list of fd sets is shared by all monitor connections.
3541 #
3542 #        If @fd is not specified, all file descriptors in @fdset-id
3543 #        will be removed.
3544 ##
3545 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
3546
3547 ##
3548 # @FdsetFdInfo:
3549 #
3550 # Information about a file descriptor that belongs to an fd set.
3551 #
3552 # @fd: The file descriptor value.
3553 #
3554 # @opaque: #optional A free-form string that can be used to describe the fd.
3555 #
3556 # Since: 1.2.0
3557 ##
3558 { 'struct': 'FdsetFdInfo',
3559   'data': {'fd': 'int', '*opaque': 'str'} }
3560
3561 ##
3562 # @FdsetInfo:
3563 #
3564 # Information about an fd set.
3565 #
3566 # @fdset-id: The ID of the fd set.
3567 #
3568 # @fds: A list of file descriptors that belong to this fd set.
3569 #
3570 # Since: 1.2.0
3571 ##
3572 { 'struct': 'FdsetInfo',
3573   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
3574
3575 ##
3576 # @query-fdsets:
3577 #
3578 # Return information describing all fd sets.
3579 #
3580 # Returns: A list of @FdsetInfo
3581 #
3582 # Since: 1.2.0
3583 #
3584 # Note: The list of fd sets is shared by all monitor connections.
3585 #
3586 ##
3587 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
3588
3589 ##
3590 # @TargetInfo:
3591 #
3592 # Information describing the QEMU target.
3593 #
3594 # @arch: the target architecture (eg "x86_64", "i386", etc)
3595 #
3596 # Since: 1.2.0
3597 ##
3598 { 'struct': 'TargetInfo',
3599   'data': { 'arch': 'str' } }
3600
3601 ##
3602 # @query-target:
3603 #
3604 # Return information about the target for this QEMU
3605 #
3606 # Returns: TargetInfo
3607 #
3608 # Since: 1.2.0
3609 ##
3610 { 'command': 'query-target', 'returns': 'TargetInfo' }
3611
3612 ##
3613 # @QKeyCode:
3614 #
3615 # @unmapped: since 2.0
3616 # @pause: since 2.0
3617 # @ro: since 2.4
3618 # @kp_comma: since 2.4
3619 # @kp_equals: since 2.6
3620 # @power: since 2.6
3621 #
3622 # An enumeration of key name.
3623 #
3624 # This is used by the send-key command.
3625 #
3626 # Since: 1.3.0
3627 #
3628 ##
3629 { 'enum': 'QKeyCode',
3630   'data': [ 'unmapped',
3631             'shift', 'shift_r', 'alt', 'alt_r', 'altgr', 'altgr_r', 'ctrl',
3632             'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
3633             '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
3634             'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
3635             'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
3636             'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
3637             'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
3638             'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
3639             'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
3640             'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
3641             'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
3642             'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
3643             'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
3644             'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
3645             'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause', 'ro',
3646             'kp_comma', 'kp_equals', 'power' ] }
3647
3648 ##
3649 # @KeyValue:
3650 #
3651 # Represents a keyboard key.
3652 #
3653 # Since: 1.3.0
3654 ##
3655 { 'union': 'KeyValue',
3656   'data': {
3657     'number': 'int',
3658     'qcode': 'QKeyCode' } }
3659
3660 ##
3661 # @send-key:
3662 #
3663 # Send keys to guest.
3664 #
3665 # @keys: An array of @KeyValue elements. All @KeyValues in this array are
3666 #        simultaneously sent to the guest. A @KeyValue.number value is sent
3667 #        directly to the guest, while @KeyValue.qcode must be a valid
3668 #        @QKeyCode value
3669 #
3670 # @hold-time: #optional time to delay key up events, milliseconds. Defaults
3671 #             to 100
3672 #
3673 # Returns: Nothing on success
3674 #          If key is unknown or redundant, InvalidParameter
3675 #
3676 # Since: 1.3.0
3677 #
3678 ##
3679 { 'command': 'send-key',
3680   'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
3681
3682 ##
3683 # @screendump:
3684 #
3685 # Write a PPM of the VGA screen to a file.
3686 #
3687 # @filename: the path of a new PPM file to store the image
3688 #
3689 # Returns: Nothing on success
3690 #
3691 # Since: 0.14.0
3692 ##
3693 { 'command': 'screendump', 'data': {'filename': 'str'} }
3694
3695
3696 ##
3697 # @ChardevCommon:
3698 #
3699 # Configuration shared across all chardev backends
3700 #
3701 # @logfile: #optional The name of a logfile to save output
3702 # @logappend: #optional true to append instead of truncate
3703 #             (default to false to truncate)
3704 #
3705 # Since: 2.6
3706 ##
3707 { 'struct': 'ChardevCommon', 'data': { '*logfile': 'str',
3708                                        '*logappend': 'bool' } }
3709
3710 ##
3711 # @ChardevFile:
3712 #
3713 # Configuration info for file chardevs.
3714 #
3715 # @in:  #optional The name of the input file
3716 # @out: The name of the output file
3717 # @append: #optional Open the file in append mode (default false to
3718 #          truncate) (Since 2.6)
3719 #
3720 # Since: 1.4
3721 ##
3722 { 'struct': 'ChardevFile', 'data': { '*in' : 'str',
3723                                    'out' : 'str',
3724                                    '*append': 'bool' },
3725   'base': 'ChardevCommon' }
3726
3727 ##
3728 # @ChardevHostdev:
3729 #
3730 # Configuration info for device and pipe chardevs.
3731 #
3732 # @device: The name of the special file for the device,
3733 #          i.e. /dev/ttyS0 on Unix or COM1: on Windows
3734 #
3735 # Since: 1.4
3736 ##
3737 { 'struct': 'ChardevHostdev', 'data': { 'device' : 'str' },
3738   'base': 'ChardevCommon' }
3739
3740 ##
3741 # @ChardevSocket:
3742 #
3743 # Configuration info for (stream) socket chardevs.
3744 #
3745 # @addr: socket address to listen on (server=true)
3746 #        or connect to (server=false)
3747 # @tls-creds: #optional the ID of the TLS credentials object (since 2.6)
3748 # @server: #optional create server socket (default: true)
3749 # @wait: #optional wait for incoming connection on server
3750 #        sockets (default: false).
3751 # @nodelay: #optional set TCP_NODELAY socket option (default: false)
3752 # @telnet: #optional enable telnet protocol on server
3753 #          sockets (default: false)
3754 # @reconnect: #optional For a client socket, if a socket is disconnected,
3755 #          then attempt a reconnect after the given number of seconds.
3756 #          Setting this to zero disables this function. (default: 0)
3757 #          (Since: 2.2)
3758 #
3759 # Since: 1.4
3760 ##
3761 { 'struct': 'ChardevSocket', 'data': { 'addr'       : 'SocketAddress',
3762                                      '*tls-creds'  : 'str',
3763                                      '*server'    : 'bool',
3764                                      '*wait'      : 'bool',
3765                                      '*nodelay'   : 'bool',
3766                                      '*telnet'    : 'bool',
3767                                      '*reconnect' : 'int' },
3768   'base': 'ChardevCommon' }
3769
3770 ##
3771 # @ChardevUdp:
3772 #
3773 # Configuration info for datagram socket chardevs.
3774 #
3775 # @remote: remote address
3776 # @local: #optional local address
3777 #
3778 # Since: 1.5
3779 ##
3780 { 'struct': 'ChardevUdp', 'data': { 'remote' : 'SocketAddress',
3781                                   '*local' : 'SocketAddress' },
3782   'base': 'ChardevCommon' }
3783
3784 ##
3785 # @ChardevMux:
3786 #
3787 # Configuration info for mux chardevs.
3788 #
3789 # @chardev: name of the base chardev.
3790 #
3791 # Since: 1.5
3792 ##
3793 { 'struct': 'ChardevMux', 'data': { 'chardev' : 'str' },
3794   'base': 'ChardevCommon' }
3795
3796 ##
3797 # @ChardevStdio:
3798 #
3799 # Configuration info for stdio chardevs.
3800 #
3801 # @signal: #optional Allow signals (such as SIGINT triggered by ^C)
3802 #          be delivered to qemu.  Default: true in -nographic mode,
3803 #          false otherwise.
3804 #
3805 # Since: 1.5
3806 ##
3807 { 'struct': 'ChardevStdio', 'data': { '*signal' : 'bool' },
3808   'base': 'ChardevCommon' }
3809
3810
3811 ##
3812 # @ChardevSpiceChannel:
3813 #
3814 # Configuration info for spice vm channel chardevs.
3815 #
3816 # @type: kind of channel (for example vdagent).
3817 #
3818 # Since: 1.5
3819 ##
3820 { 'struct': 'ChardevSpiceChannel', 'data': { 'type'  : 'str' },
3821   'base': 'ChardevCommon' }
3822
3823 ##
3824 # @ChardevSpicePort:
3825 #
3826 # Configuration info for spice port chardevs.
3827 #
3828 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
3829 #
3830 # Since: 1.5
3831 ##
3832 { 'struct': 'ChardevSpicePort', 'data': { 'fqdn'  : 'str' },
3833   'base': 'ChardevCommon' }
3834
3835 ##
3836 # @ChardevVC:
3837 #
3838 # Configuration info for virtual console chardevs.
3839 #
3840 # @width:  console width,  in pixels
3841 # @height: console height, in pixels
3842 # @cols:   console width,  in chars
3843 # @rows:   console height, in chars
3844 #
3845 # Since: 1.5
3846 ##
3847 { 'struct': 'ChardevVC', 'data': { '*width'  : 'int',
3848                                  '*height' : 'int',
3849                                  '*cols'   : 'int',
3850                                  '*rows'   : 'int' },
3851   'base': 'ChardevCommon' }
3852
3853 ##
3854 # @ChardevRingbuf:
3855 #
3856 # Configuration info for ring buffer chardevs.
3857 #
3858 # @size: #optional ring buffer size, must be power of two, default is 65536
3859 #
3860 # Since: 1.5
3861 ##
3862 { 'struct': 'ChardevRingbuf', 'data': { '*size'  : 'int' },
3863   'base': 'ChardevCommon' }
3864
3865 ##
3866 # @ChardevBackend:
3867 #
3868 # Configuration info for the new chardev backend.
3869 #
3870 # Since: 1.4 (testdev since 2.2)
3871 ##
3872 { 'union': 'ChardevBackend', 'data': { 'file'   : 'ChardevFile',
3873                                        'serial' : 'ChardevHostdev',
3874                                        'parallel': 'ChardevHostdev',
3875                                        'pipe'   : 'ChardevHostdev',
3876                                        'socket' : 'ChardevSocket',
3877                                        'udp'    : 'ChardevUdp',
3878                                        'pty'    : 'ChardevCommon',
3879                                        'null'   : 'ChardevCommon',
3880                                        'mux'    : 'ChardevMux',
3881                                        'msmouse': 'ChardevCommon',
3882                                        'braille': 'ChardevCommon',
3883                                        'testdev': 'ChardevCommon',
3884                                        'stdio'  : 'ChardevStdio',
3885                                        'console': 'ChardevCommon',
3886                                        'spicevmc' : 'ChardevSpiceChannel',
3887                                        'spiceport' : 'ChardevSpicePort',
3888                                        'vc'     : 'ChardevVC',
3889                                        'ringbuf': 'ChardevRingbuf',
3890                                        # next one is just for compatibility
3891                                        'memory' : 'ChardevRingbuf' } }
3892
3893 ##
3894 # @ChardevReturn:
3895 #
3896 # Return info about the chardev backend just created.
3897 #
3898 # @pty: #optional name of the slave pseudoterminal device, present if
3899 #       and only if a chardev of type 'pty' was created
3900 #
3901 # Since: 1.4
3902 ##
3903 { 'struct' : 'ChardevReturn', 'data': { '*pty' : 'str' } }
3904
3905 ##
3906 # @chardev-add:
3907 #
3908 # Add a character device backend
3909 #
3910 # @id: the chardev's ID, must be unique
3911 # @backend: backend type and parameters
3912 #
3913 # Returns: ChardevReturn.
3914 #
3915 # Since: 1.4
3916 ##
3917 { 'command': 'chardev-add', 'data': {'id'      : 'str',
3918                                      'backend' : 'ChardevBackend' },
3919   'returns': 'ChardevReturn' }
3920
3921 ##
3922 # @chardev-remove:
3923 #
3924 # Remove a character device backend
3925 #
3926 # @id: the chardev's ID, must exist and not be in use
3927 #
3928 # Returns: Nothing on success
3929 #
3930 # Since: 1.4
3931 ##
3932 { 'command': 'chardev-remove', 'data': {'id': 'str'} }
3933
3934 ##
3935 # @TpmModel:
3936 #
3937 # An enumeration of TPM models
3938 #
3939 # @tpm-tis: TPM TIS model
3940 #
3941 # Since: 1.5
3942 ##
3943 { 'enum': 'TpmModel', 'data': [ 'tpm-tis' ] }
3944
3945 ##
3946 # @query-tpm-models:
3947 #
3948 # Return a list of supported TPM models
3949 #
3950 # Returns: a list of TpmModel
3951 #
3952 # Since: 1.5
3953 ##
3954 { 'command': 'query-tpm-models', 'returns': ['TpmModel'] }
3955
3956 ##
3957 # @TpmType:
3958 #
3959 # An enumeration of TPM types
3960 #
3961 # @passthrough: TPM passthrough type
3962 #
3963 # Since: 1.5
3964 ##
3965 { 'enum': 'TpmType', 'data': [ 'passthrough' ] }
3966
3967 ##
3968 # @query-tpm-types:
3969 #
3970 # Return a list of supported TPM types
3971 #
3972 # Returns: a list of TpmType
3973 #
3974 # Since: 1.5
3975 ##
3976 { 'command': 'query-tpm-types', 'returns': ['TpmType'] }
3977
3978 ##
3979 # @TPMPassthroughOptions:
3980 #
3981 # Information about the TPM passthrough type
3982 #
3983 # @path: #optional string describing the path used for accessing the TPM device
3984 #
3985 # @cancel-path: #optional string showing the TPM's sysfs cancel file
3986 #               for cancellation of TPM commands while they are executing
3987 #
3988 # Since: 1.5
3989 ##
3990 { 'struct': 'TPMPassthroughOptions', 'data': { '*path' : 'str',
3991                                              '*cancel-path' : 'str'} }
3992
3993 ##
3994 # @TpmTypeOptions:
3995 #
3996 # A union referencing different TPM backend types' configuration options
3997 #
3998 # @type: 'passthrough' The configuration options for the TPM passthrough type
3999 #
4000 # Since: 1.5
4001 ##
4002 { 'union': 'TpmTypeOptions',
4003    'data': { 'passthrough' : 'TPMPassthroughOptions' } }
4004
4005 ##
4006 # @TPMInfo:
4007 #
4008 # Information about the TPM
4009 #
4010 # @id: The Id of the TPM
4011 #
4012 # @model: The TPM frontend model
4013 #
4014 # @options: The TPM (backend) type configuration options
4015 #
4016 # Since: 1.5
4017 ##
4018 { 'struct': 'TPMInfo',
4019   'data': {'id': 'str',
4020            'model': 'TpmModel',
4021            'options': 'TpmTypeOptions' } }
4022
4023 ##
4024 # @query-tpm:
4025 #
4026 # Return information about the TPM device
4027 #
4028 # Returns: @TPMInfo on success
4029 #
4030 # Since: 1.5
4031 ##
4032 { 'command': 'query-tpm', 'returns': ['TPMInfo'] }
4033
4034 ##
4035 # @AcpiTableOptions:
4036 #
4037 # Specify an ACPI table on the command line to load.
4038 #
4039 # At most one of @file and @data can be specified. The list of files specified
4040 # by any one of them is loaded and concatenated in order. If both are omitted,
4041 # @data is implied.
4042 #
4043 # Other fields / optargs can be used to override fields of the generic ACPI
4044 # table header; refer to the ACPI specification 5.0, section 5.2.6 System
4045 # Description Table Header. If a header field is not overridden, then the
4046 # corresponding value from the concatenated blob is used (in case of @file), or
4047 # it is filled in with a hard-coded value (in case of @data).
4048 #
4049 # String fields are copied into the matching ACPI member from lowest address
4050 # upwards, and silently truncated / NUL-padded to length.
4051 #
4052 # @sig: #optional table signature / identifier (4 bytes)
4053 #
4054 # @rev: #optional table revision number (dependent on signature, 1 byte)
4055 #
4056 # @oem_id: #optional OEM identifier (6 bytes)
4057 #
4058 # @oem_table_id: #optional OEM table identifier (8 bytes)
4059 #
4060 # @oem_rev: #optional OEM-supplied revision number (4 bytes)
4061 #
4062 # @asl_compiler_id: #optional identifier of the utility that created the table
4063 #                   (4 bytes)
4064 #
4065 # @asl_compiler_rev: #optional revision number of the utility that created the
4066 #                    table (4 bytes)
4067 #
4068 # @file: #optional colon (:) separated list of pathnames to load and
4069 #        concatenate as table data. The resultant binary blob is expected to
4070 #        have an ACPI table header. At least one file is required. This field
4071 #        excludes @data.
4072 #
4073 # @data: #optional colon (:) separated list of pathnames to load and
4074 #        concatenate as table data. The resultant binary blob must not have an
4075 #        ACPI table header. At least one file is required. This field excludes
4076 #        @file.
4077 #
4078 # Since: 1.5
4079 ##
4080 { 'struct': 'AcpiTableOptions',
4081   'data': {
4082     '*sig':               'str',
4083     '*rev':               'uint8',
4084     '*oem_id':            'str',
4085     '*oem_table_id':      'str',
4086     '*oem_rev':           'uint32',
4087     '*asl_compiler_id':   'str',
4088     '*asl_compiler_rev':  'uint32',
4089     '*file':              'str',
4090     '*data':              'str' }}
4091
4092 ##
4093 # @CommandLineParameterType:
4094 #
4095 # Possible types for an option parameter.
4096 #
4097 # @string: accepts a character string
4098 #
4099 # @boolean: accepts "on" or "off"
4100 #
4101 # @number: accepts a number
4102 #
4103 # @size: accepts a number followed by an optional suffix (K)ilo,
4104 #        (M)ega, (G)iga, (T)era
4105 #
4106 # Since: 1.5
4107 ##
4108 { 'enum': 'CommandLineParameterType',
4109   'data': ['string', 'boolean', 'number', 'size'] }
4110
4111 ##
4112 # @CommandLineParameterInfo:
4113 #
4114 # Details about a single parameter of a command line option.
4115 #
4116 # @name: parameter name
4117 #
4118 # @type: parameter @CommandLineParameterType
4119 #
4120 # @help: #optional&