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