802ea53d00fd82e3f2603a1aa16d549128ae72e1
[qemu.git] / qapi-schema.json
1 # -*- Mode: Python -*-
2 ##
3 # = Introduction
4 #
5 # This document describes all commands currently supported by QMP.
6 #
7 # Most of the time their usage is exactly the same as in the user Monitor, this
8 # means that any other document which also describe commands (the manpage,
9 # QEMU's manual, etc) can and should be consulted.
10 #
11 # QMP has two types of commands: regular and query commands. Regular commands
12 # usually change the Virtual Machine's state someway, while query commands just
13 # return information. The sections below are divided accordingly.
14 #
15 # It's important to observe that all communication examples are formatted in
16 # a reader-friendly way, so that they're easier to understand. However, in real
17 # protocol usage, they're emitted as a single line.
18 #
19 # Also, the following notation is used to denote data flow:
20 #
21 # Example:
22 #
23 # | -> data issued by the Client
24 # | <- Server data response
25 #
26 # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
27 # detailed information on the Server command and response formats.
28 #
29 # = Stability Considerations
30 #
31 # The current QMP command set (described in this file) may be useful for a
32 # number of use cases, however it's limited and several commands have bad
33 # defined semantics, specially with regard to command completion.
34 #
35 # These problems are going to be solved incrementally in the next QEMU releases
36 # and we're going to establish a deprecation policy for badly defined commands.
37 #
38 # If you're planning to adopt QMP, please observe the following:
39 #
40 #     1. The deprecation policy will take effect and be documented soon, please
41 #        check the documentation of each used command as soon as a new release of
42 #        QEMU is available
43 #
44 #     2. DO NOT rely on anything which is not explicit documented
45 #
46 #     3. Errors, in special, are not documented. Applications should NOT check
47 #        for specific errors classes or data (it's strongly recommended to only
48 #        check for the "error" key)
49 #
50 ##
51
52 { 'pragma': { 'doc-required': true } }
53
54 # Whitelists to permit QAPI rule violations; think twice before you
55 # add to them!
56 { 'pragma': {
57     # Commands allowed to return a non-dictionary:
58     'returns-whitelist': [
59         'human-monitor-command',
60         'qom-get',
61         'query-migrate-cache-size',
62         'query-tpm-models',
63         'query-tpm-types',
64         'ringbuf-read' ],
65     'name-case-whitelist': [
66         'ACPISlotType',         # DIMM, visible through query-acpi-ospm-status
67         'CpuInfoMIPS',          # PC, visible through query-cpu
68         'CpuInfoTricore',       # PC, visible through query-cpu
69         'QapiErrorClass',       # all members, visible through errors
70         'UuidInfo',             # UUID, visible through query-uuid
71         'X86CPURegister32',     # all members, visible indirectly through qom-get
72         'q_obj_CpuInfo-base'    # CPU, visible through query-cpu
73     ] } }
74
75 # QAPI common definitions
76 { 'include': 'qapi/common.json' }
77
78 # QAPI crypto definitions
79 { 'include': 'qapi/crypto.json' }
80
81 # QAPI block definitions
82 { 'include': 'qapi/block.json' }
83
84 # QAPI event definitions
85 { 'include': 'qapi/event.json' }
86
87 # Tracing commands
88 { 'include': 'qapi/trace.json' }
89
90 # QAPI introspection
91 { 'include': 'qapi/introspect.json' }
92
93 ##
94 # = QMP commands
95 ##
96
97 ##
98 # @qmp_capabilities:
99 #
100 # Enable QMP capabilities.
101 #
102 # Arguments: None.
103 #
104 # Example:
105 #
106 # -> { "execute": "qmp_capabilities" }
107 # <- { "return": {} }
108 #
109 # Notes: This command is valid exactly when first connecting: it must be
110 # issued before any other command will be accepted, and will fail once the
111 # monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
112 #
113 # Since: 0.13
114 #
115 ##
116 { 'command': 'qmp_capabilities' }
117
118 ##
119 # @StrOrNull:
120 #
121 # This is a string value or the explicit lack of a string (null
122 # pointer in C).  Intended for cases when 'optional absent' already
123 # has a different meaning.
124 #
125 # @s: the string value
126 # @n: no string value
127 #
128 # Since: 2.10
129 ##
130 { 'alternate': 'StrOrNull',
131   'data': { 's': 'str',
132             'n': 'null' } }
133
134 ##
135 # @LostTickPolicy:
136 #
137 # Policy for handling lost ticks in timer devices.
138 #
139 # @discard: throw away the missed tick(s) and continue with future injection
140 #           normally.  Guest time may be delayed, unless the OS has explicit
141 #           handling of lost ticks
142 #
143 # @delay: continue to deliver ticks at the normal rate.  Guest time will be
144 #         delayed due to the late tick
145 #
146 # @merge: merge the missed tick(s) into one tick and inject.  Guest time
147 #         may be delayed, depending on how the OS reacts to the merging
148 #         of ticks
149 #
150 # @slew: deliver ticks at a higher rate to catch up with the missed tick. The
151 #        guest time should not be delayed once catchup is complete.
152 #
153 # Since: 2.0
154 ##
155 { 'enum': 'LostTickPolicy',
156   'data': ['discard', 'delay', 'merge', 'slew' ] }
157
158 ##
159 # @add_client:
160 #
161 # Allow client connections for VNC, Spice and socket based
162 # character devices to be passed in to QEMU via SCM_RIGHTS.
163 #
164 # @protocol: protocol name. Valid names are "vnc", "spice" or the
165 #            name of a character device (eg. from -chardev id=XXXX)
166 #
167 # @fdname: file descriptor name previously passed via 'getfd' command
168 #
169 # @skipauth: whether to skip authentication. Only applies
170 #            to "vnc" and "spice" protocols
171 #
172 # @tls: whether to perform TLS. Only applies to the "spice"
173 #       protocol
174 #
175 # Returns: nothing on success.
176 #
177 # Since: 0.14.0
178 #
179 # Example:
180 #
181 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
182 #                                              "fdname": "myclient" } }
183 # <- { "return": {} }
184 #
185 ##
186 { 'command': 'add_client',
187   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
188             '*tls': 'bool' } }
189
190 ##
191 # @NameInfo:
192 #
193 # Guest name information.
194 #
195 # @name: The name of the guest
196 #
197 # Since: 0.14.0
198 ##
199 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
200
201 ##
202 # @query-name:
203 #
204 # Return the name information of a guest.
205 #
206 # Returns: @NameInfo of the guest
207 #
208 # Since: 0.14.0
209 #
210 # Example:
211 #
212 # -> { "execute": "query-name" }
213 # <- { "return": { "name": "qemu-name" } }
214 #
215 ##
216 { 'command': 'query-name', 'returns': 'NameInfo' }
217
218 ##
219 # @KvmInfo:
220 #
221 # Information about support for KVM acceleration
222 #
223 # @enabled: true if KVM acceleration is active
224 #
225 # @present: true if KVM acceleration is built into this executable
226 #
227 # Since: 0.14.0
228 ##
229 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
230
231 ##
232 # @query-kvm:
233 #
234 # Returns information about KVM acceleration
235 #
236 # Returns: @KvmInfo
237 #
238 # Since: 0.14.0
239 #
240 # Example:
241 #
242 # -> { "execute": "query-kvm" }
243 # <- { "return": { "enabled": true, "present": true } }
244 #
245 ##
246 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
247
248 ##
249 # @RunState:
250 #
251 # An enumeration of VM run states.
252 #
253 # @debug: QEMU is running on a debugger
254 #
255 # @finish-migrate: guest is paused to finish the migration process
256 #
257 # @inmigrate: guest is paused waiting for an incoming migration.  Note
258 # that this state does not tell whether the machine will start at the
259 # end of the migration.  This depends on the command-line -S option and
260 # any invocation of 'stop' or 'cont' that has happened since QEMU was
261 # started.
262 #
263 # @internal-error: An internal error that prevents further guest execution
264 # has occurred
265 #
266 # @io-error: the last IOP has failed and the device is configured to pause
267 # on I/O errors
268 #
269 # @paused: guest has been paused via the 'stop' command
270 #
271 # @postmigrate: guest is paused following a successful 'migrate'
272 #
273 # @prelaunch: QEMU was started with -S and guest has not started
274 #
275 # @restore-vm: guest is paused to restore VM state
276 #
277 # @running: guest is actively running
278 #
279 # @save-vm: guest is paused to save the VM state
280 #
281 # @shutdown: guest is shut down (and -no-shutdown is in use)
282 #
283 # @suspended: guest is suspended (ACPI S3)
284 #
285 # @watchdog: the watchdog action is configured to pause and has been triggered
286 #
287 # @guest-panicked: guest has been panicked as a result of guest OS panic
288 #
289 # @colo: guest is paused to save/restore VM state under colo checkpoint,
290 #        VM can not get into this state unless colo capability is enabled
291 #        for migration. (since 2.8)
292 ##
293 { 'enum': 'RunState',
294   'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
295             'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
296             'running', 'save-vm', 'shutdown', 'suspended', 'watchdog',
297             'guest-panicked', 'colo' ] }
298
299 ##
300 # @StatusInfo:
301 #
302 # Information about VCPU run state
303 #
304 # @running: true if all VCPUs are runnable, false if not runnable
305 #
306 # @singlestep: true if VCPUs are in single-step mode
307 #
308 # @status: the virtual machine @RunState
309 #
310 # Since:  0.14.0
311 #
312 # Notes: @singlestep is enabled through the GDB stub
313 ##
314 { 'struct': 'StatusInfo',
315   'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
316
317 ##
318 # @query-status:
319 #
320 # Query the run status of all VCPUs
321 #
322 # Returns: @StatusInfo reflecting all VCPUs
323 #
324 # Since:  0.14.0
325 #
326 # Example:
327 #
328 # -> { "execute": "query-status" }
329 # <- { "return": { "running": true,
330 #                  "singlestep": false,
331 #                  "status": "running" } }
332 #
333 ##
334 { 'command': 'query-status', 'returns': 'StatusInfo' }
335
336 ##
337 # @UuidInfo:
338 #
339 # Guest UUID information (Universally Unique Identifier).
340 #
341 # @UUID: the UUID of the guest
342 #
343 # Since: 0.14.0
344 #
345 # Notes: If no UUID was specified for the guest, a null UUID is returned.
346 ##
347 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
348
349 ##
350 # @query-uuid:
351 #
352 # Query the guest UUID information.
353 #
354 # Returns: The @UuidInfo for the guest
355 #
356 # Since: 0.14.0
357 #
358 # Example:
359 #
360 # -> { "execute": "query-uuid" }
361 # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
362 #
363 ##
364 { 'command': 'query-uuid', 'returns': 'UuidInfo' }
365
366 ##
367 # @ChardevInfo:
368 #
369 # Information about a character device.
370 #
371 # @label: the label of the character device
372 #
373 # @filename: the filename of the character device
374 #
375 # @frontend-open: shows whether the frontend device attached to this backend
376 #                 (eg. with the chardev=... option) is in open or closed state
377 #                 (since 2.1)
378 #
379 # Notes: @filename is encoded using the QEMU command line character device
380 #        encoding.  See the QEMU man page for details.
381 #
382 # Since: 0.14.0
383 ##
384 { 'struct': 'ChardevInfo', 'data': {'label': 'str',
385                                   'filename': 'str',
386                                   'frontend-open': 'bool'} }
387
388 ##
389 # @query-chardev:
390 #
391 # Returns information about current character devices.
392 #
393 # Returns: a list of @ChardevInfo
394 #
395 # Since: 0.14.0
396 #
397 # Example:
398 #
399 # -> { "execute": "query-chardev" }
400 # <- {
401 #       "return": [
402 #          {
403 #             "label": "charchannel0",
404 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
405 #             "frontend-open": false
406 #          },
407 #          {
408 #             "label": "charmonitor",
409 #             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
410 #             "frontend-open": true
411 #          },
412 #          {
413 #             "label": "charserial0",
414 #             "filename": "pty:/dev/pts/2",
415 #             "frontend-open": true
416 #          }
417 #       ]
418 #    }
419 #
420 ##
421 { 'command': 'query-chardev', 'returns': ['ChardevInfo'] }
422
423 ##
424 # @ChardevBackendInfo:
425 #
426 # Information about a character device backend
427 #
428 # @name: The backend name
429 #
430 # Since: 2.0
431 ##
432 { 'struct': 'ChardevBackendInfo', 'data': {'name': 'str'} }
433
434 ##
435 # @query-chardev-backends:
436 #
437 # Returns information about character device backends.
438 #
439 # Returns: a list of @ChardevBackendInfo
440 #
441 # Since: 2.0
442 #
443 # Example:
444 #
445 # -> { "execute": "query-chardev-backends" }
446 # <- {
447 #       "return":[
448 #          {
449 #             "name":"udp"
450 #          },
451 #          {
452 #             "name":"tcp"
453 #          },
454 #          {
455 #             "name":"unix"
456 #          },
457 #          {
458 #             "name":"spiceport"
459 #          }
460 #       ]
461 #    }
462 #
463 ##
464 { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
465
466 ##
467 # @DataFormat:
468 #
469 # An enumeration of data format.
470 #
471 # @utf8: Data is a UTF-8 string (RFC 3629)
472 #
473 # @base64: Data is Base64 encoded binary (RFC 3548)
474 #
475 # Since: 1.4
476 ##
477 { 'enum': 'DataFormat',
478   'data': [ 'utf8', 'base64' ] }
479
480 ##
481 # @ringbuf-write:
482 #
483 # Write to a ring buffer character device.
484 #
485 # @device: the ring buffer character device name
486 #
487 # @data: data to write
488 #
489 # @format: data encoding (default 'utf8').
490 #          - base64: data must be base64 encoded text.  Its binary
491 #            decoding gets written.
492 #          - utf8: data's UTF-8 encoding is written
493 #          - data itself is always Unicode regardless of format, like
494 #            any other string.
495 #
496 # Returns: Nothing on success
497 #
498 # Since: 1.4
499 #
500 # Example:
501 #
502 # -> { "execute": "ringbuf-write",
503 #      "arguments": { "device": "foo",
504 #                     "data": "abcdefgh",
505 #                     "format": "utf8" } }
506 # <- { "return": {} }
507 #
508 ##
509 { 'command': 'ringbuf-write',
510   'data': {'device': 'str', 'data': 'str',
511            '*format': 'DataFormat'} }
512
513 ##
514 # @ringbuf-read:
515 #
516 # Read from a ring buffer character device.
517 #
518 # @device: the ring buffer character device name
519 #
520 # @size: how many bytes to read at most
521 #
522 # @format: data encoding (default 'utf8').
523 #          - base64: the data read is returned in base64 encoding.
524 #          - utf8: the data read is interpreted as UTF-8.
525 #            Bug: can screw up when the buffer contains invalid UTF-8
526 #            sequences, NUL characters, after the ring buffer lost
527 #            data, and when reading stops because the size limit is
528 #            reached.
529 #          - The return value is always Unicode regardless of format,
530 #            like any other string.
531 #
532 # Returns: data read from the device
533 #
534 # Since: 1.4
535 #
536 # Example:
537 #
538 # -> { "execute": "ringbuf-read",
539 #      "arguments": { "device": "foo",
540 #                     "size": 1000,
541 #                     "format": "utf8" } }
542 # <- { "return": "abcdefgh" }
543 #
544 ##
545 { 'command': 'ringbuf-read',
546   'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
547   'returns': 'str' }
548
549 ##
550 # @EventInfo:
551 #
552 # Information about a QMP event
553 #
554 # @name: The event name
555 #
556 # Since: 1.2.0
557 ##
558 { 'struct': 'EventInfo', 'data': {'name': 'str'} }
559
560 ##
561 # @query-events:
562 #
563 # Return a list of supported QMP events by this server
564 #
565 # Returns: A list of @EventInfo for all supported events
566 #
567 # Since: 1.2.0
568 #
569 # Example:
570 #
571 # -> { "execute": "query-events" }
572 # <- {
573 #      "return": [
574 #          {
575 #             "name":"SHUTDOWN"
576 #          },
577 #          {
578 #             "name":"RESET"
579 #          }
580 #       ]
581 #    }
582 #
583 # Note: This example has been shortened as the real response is too long.
584 #
585 ##
586 { 'command': 'query-events', 'returns': ['EventInfo'] }
587
588 ##
589 # @MigrationStats:
590 #
591 # Detailed migration status.
592 #
593 # @transferred: amount of bytes already transferred to the target VM
594 #
595 # @remaining: amount of bytes remaining to be transferred to the target VM
596 #
597 # @total: total amount of bytes involved in the migration process
598 #
599 # @duplicate: number of duplicate (zero) pages (since 1.2)
600 #
601 # @skipped: number of skipped zero pages (since 1.5)
602 #
603 # @normal: number of normal pages (since 1.2)
604 #
605 # @normal-bytes: number of normal bytes sent (since 1.2)
606 #
607 # @dirty-pages-rate: number of pages dirtied by second by the
608 #        guest (since 1.3)
609 #
610 # @mbps: throughput in megabits/sec. (since 1.6)
611 #
612 # @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
613 #
614 # @postcopy-requests: The number of page requests received from the destination
615 #        (since 2.7)
616 #
617 # @page-size: The number of bytes per page for the various page-based
618 #        statistics (since 2.10)
619 #
620 # Since: 0.14.0
621 ##
622 { 'struct': 'MigrationStats',
623   'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
624            'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
625            'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
626            'mbps' : 'number', 'dirty-sync-count' : 'int',
627            'postcopy-requests' : 'int', 'page-size' : 'int' } }
628
629 ##
630 # @XBZRLECacheStats:
631 #
632 # Detailed XBZRLE migration cache statistics
633 #
634 # @cache-size: XBZRLE cache size
635 #
636 # @bytes: amount of bytes already transferred to the target VM
637 #
638 # @pages: amount of pages transferred to the target VM
639 #
640 # @cache-miss: number of cache miss
641 #
642 # @cache-miss-rate: rate of cache miss (since 2.1)
643 #
644 # @overflow: number of overflows
645 #
646 # Since: 1.2
647 ##
648 { 'struct': 'XBZRLECacheStats',
649   'data': {'cache-size': 'int', 'bytes': 'int', 'pages': 'int',
650            'cache-miss': 'int', 'cache-miss-rate': 'number',
651            'overflow': 'int' } }
652
653 ##
654 # @MigrationStatus:
655 #
656 # An enumeration of migration status.
657 #
658 # @none: no migration has ever happened.
659 #
660 # @setup: migration process has been initiated.
661 #
662 # @cancelling: in the process of cancelling migration.
663 #
664 # @cancelled: cancelling migration is finished.
665 #
666 # @active: in the process of doing migration.
667 #
668 # @postcopy-active: like active, but now in postcopy mode. (since 2.5)
669 #
670 # @completed: migration is finished.
671 #
672 # @failed: some error occurred during migration process.
673 #
674 # @colo: VM is in the process of fault tolerance, VM can not get into this
675 #        state unless colo capability is enabled for migration. (since 2.8)
676 #
677 # Since: 2.3
678 #
679 ##
680 { 'enum': 'MigrationStatus',
681   'data': [ 'none', 'setup', 'cancelling', 'cancelled',
682             'active', 'postcopy-active', 'completed', 'failed', 'colo' ] }
683
684 ##
685 # @MigrationInfo:
686 #
687 # Information about current migration process.
688 #
689 # @status: @MigrationStatus describing the current migration status.
690 #          If this field is not returned, no migration process
691 #          has been initiated
692 #
693 # @ram: @MigrationStats containing detailed migration
694 #       status, only returned if status is 'active' or
695 #       'completed'(since 1.2)
696 #
697 # @disk: @MigrationStats containing detailed disk migration
698 #        status, only returned if status is 'active' and it is a block
699 #        migration
700 #
701 # @xbzrle-cache: @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: 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: only present when migration finishes correctly
710 #        total downtime in milliseconds for the guest.
711 #        (since 1.3)
712 #
713 # @expected-downtime: 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: 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 # @cpu-throttle-percentage: percentage of time guest cpus are being
724 #        throttled during auto-converge. This is only present when auto-converge
725 #        has started throttling guest cpus. (Since 2.7)
726 #
727 # @error-desc: the human readable error description string, when
728 #              @status is 'failed'. Clients should not attempt to parse the
729 #              error strings. (Since 2.7)
730 #
731 # Since: 0.14.0
732 ##
733 { 'struct': 'MigrationInfo',
734   'data': {'*status': 'MigrationStatus', '*ram': 'MigrationStats',
735            '*disk': 'MigrationStats',
736            '*xbzrle-cache': 'XBZRLECacheStats',
737            '*total-time': 'int',
738            '*expected-downtime': 'int',
739            '*downtime': 'int',
740            '*setup-time': 'int',
741            '*cpu-throttle-percentage': 'int',
742            '*error-desc': 'str'} }
743
744 ##
745 # @query-migrate:
746 #
747 # Returns information about current migration process. If migration
748 # is active there will be another json-object with RAM migration
749 # status and if block migration is active another one with block
750 # migration status.
751 #
752 # Returns: @MigrationInfo
753 #
754 # Since: 0.14.0
755 #
756 # Example:
757 #
758 # 1. Before the first migration
759 #
760 # -> { "execute": "query-migrate" }
761 # <- { "return": {} }
762 #
763 # 2. Migration is done and has succeeded
764 #
765 # -> { "execute": "query-migrate" }
766 # <- { "return": {
767 #         "status": "completed",
768 #         "ram":{
769 #           "transferred":123,
770 #           "remaining":123,
771 #           "total":246,
772 #           "total-time":12345,
773 #           "setup-time":12345,
774 #           "downtime":12345,
775 #           "duplicate":123,
776 #           "normal":123,
777 #           "normal-bytes":123456,
778 #           "dirty-sync-count":15
779 #         }
780 #      }
781 #    }
782 #
783 # 3. Migration is done and has failed
784 #
785 # -> { "execute": "query-migrate" }
786 # <- { "return": { "status": "failed" } }
787 #
788 # 4. Migration is being performed and is not a block migration:
789 #
790 # -> { "execute": "query-migrate" }
791 # <- {
792 #       "return":{
793 #          "status":"active",
794 #          "ram":{
795 #             "transferred":123,
796 #             "remaining":123,
797 #             "total":246,
798 #             "total-time":12345,
799 #             "setup-time":12345,
800 #             "expected-downtime":12345,
801 #             "duplicate":123,
802 #             "normal":123,
803 #             "normal-bytes":123456,
804 #             "dirty-sync-count":15
805 #          }
806 #       }
807 #    }
808 #
809 # 5. Migration is being performed and is a block migration:
810 #
811 # -> { "execute": "query-migrate" }
812 # <- {
813 #       "return":{
814 #          "status":"active",
815 #          "ram":{
816 #             "total":1057024,
817 #             "remaining":1053304,
818 #             "transferred":3720,
819 #             "total-time":12345,
820 #             "setup-time":12345,
821 #             "expected-downtime":12345,
822 #             "duplicate":123,
823 #             "normal":123,
824 #             "normal-bytes":123456,
825 #             "dirty-sync-count":15
826 #          },
827 #          "disk":{
828 #             "total":20971520,
829 #             "remaining":20880384,
830 #             "transferred":91136
831 #          }
832 #       }
833 #    }
834 #
835 # 6. Migration is being performed and XBZRLE is active:
836 #
837 # -> { "execute": "query-migrate" }
838 # <- {
839 #       "return":{
840 #          "status":"active",
841 #          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
842 #          "ram":{
843 #             "total":1057024,
844 #             "remaining":1053304,
845 #             "transferred":3720,
846 #             "total-time":12345,
847 #             "setup-time":12345,
848 #             "expected-downtime":12345,
849 #             "duplicate":10,
850 #             "normal":3333,
851 #             "normal-bytes":3412992,
852 #             "dirty-sync-count":15
853 #          },
854 #          "xbzrle-cache":{
855 #             "cache-size":67108864,
856 #             "bytes":20971520,
857 #             "pages":2444343,
858 #             "cache-miss":2244,
859 #             "cache-miss-rate":0.123,
860 #             "overflow":34434
861 #          }
862 #       }
863 #    }
864 #
865 ##
866 { 'command': 'query-migrate', 'returns': 'MigrationInfo' }
867
868 ##
869 # @MigrationCapability:
870 #
871 # Migration capabilities enumeration
872 #
873 # @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
874 #          This feature allows us to minimize migration traffic for certain work
875 #          loads, by sending compressed difference of the pages
876 #
877 # @rdma-pin-all: Controls whether or not the entire VM memory footprint is
878 #          mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
879 #          Disabled by default. (since 2.0)
880 #
881 # @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
882 #          essentially saves 1MB of zeroes per block on the wire. Enabling requires
883 #          source and target VM to support this feature. To enable it is sufficient
884 #          to enable the capability on the source VM. The feature is disabled by
885 #          default. (since 1.6)
886 #
887 # @compress: Use multiple compression threads to accelerate live migration.
888 #          This feature can help to reduce the migration traffic, by sending
889 #          compressed pages. Please note that if compress and xbzrle are both
890 #          on, compress only takes effect in the ram bulk stage, after that,
891 #          it will be disabled and only xbzrle takes effect, this can help to
892 #          minimize migration traffic. The feature is disabled by default.
893 #          (since 2.4 )
894 #
895 # @events: generate events for each migration state change
896 #          (since 2.4 )
897 #
898 # @auto-converge: If enabled, QEMU will automatically throttle down the guest
899 #          to speed up convergence of RAM migration. (since 1.6)
900 #
901 # @postcopy-ram: Start executing on the migration target before all of RAM has
902 #          been migrated, pulling the remaining pages along as needed. NOTE: If
903 #          the migration fails during postcopy the VM will fail.  (since 2.6)
904 #
905 # @x-colo: If enabled, migration will never end, and the state of the VM on the
906 #        primary side will be migrated continuously to the VM on secondary
907 #        side, this process is called COarse-Grain LOck Stepping (COLO) for
908 #        Non-stop Service. (since 2.8)
909 #
910 # @release-ram: if enabled, qemu will free the migrated ram pages on the source
911 #        during postcopy-ram migration. (since 2.9)
912 #
913 # @block: If enabled, QEMU will also migrate the contents of all block
914 #          devices.  Default is disabled.  A possible alternative uses
915 #          mirror jobs to a builtin NBD server on the destination, which
916 #          offers more flexibility.
917 #          (Since 2.10)
918 #
919 # @return-path: If enabled, migration will use the return path even
920 #               for precopy. (since 2.10)
921 #
922 # Since: 1.2
923 ##
924 { 'enum': 'MigrationCapability',
925   'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks',
926            'compress', 'events', 'postcopy-ram', 'x-colo', 'release-ram',
927            'block', 'return-path' ] }
928
929 ##
930 # @MigrationCapabilityStatus:
931 #
932 # Migration capability information
933 #
934 # @capability: capability enum
935 #
936 # @state: capability state bool
937 #
938 # Since: 1.2
939 ##
940 { 'struct': 'MigrationCapabilityStatus',
941   'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
942
943 ##
944 # @migrate-set-capabilities:
945 #
946 # Enable/Disable the following migration capabilities (like xbzrle)
947 #
948 # @capabilities: json array of capability modifications to make
949 #
950 # Since: 1.2
951 #
952 # Example:
953 #
954 # -> { "execute": "migrate-set-capabilities" , "arguments":
955 #      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
956 #
957 ##
958 { 'command': 'migrate-set-capabilities',
959   'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
960
961 ##
962 # @query-migrate-capabilities:
963 #
964 # Returns information about the current migration capabilities status
965 #
966 # Returns: @MigrationCapabilitiesStatus
967 #
968 # Since: 1.2
969 #
970 # Example:
971 #
972 # -> { "execute": "query-migrate-capabilities" }
973 # <- { "return": [
974 #       {"state": false, "capability": "xbzrle"},
975 #       {"state": false, "capability": "rdma-pin-all"},
976 #       {"state": false, "capability": "auto-converge"},
977 #       {"state": false, "capability": "zero-blocks"},
978 #       {"state": false, "capability": "compress"},
979 #       {"state": true, "capability": "events"},
980 #       {"state": false, "capability": "postcopy-ram"},
981 #       {"state": false, "capability": "x-colo"}
982 #    ]}
983 #
984 ##
985 { 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus']}
986
987 ##
988 # @MigrationParameter:
989 #
990 # Migration parameters enumeration
991 #
992 # @compress-level: Set the compression level to be used in live migration,
993 #          the compression level is an integer between 0 and 9, where 0 means
994 #          no compression, 1 means the best compression speed, and 9 means best
995 #          compression ratio which will consume more CPU.
996 #
997 # @compress-threads: Set compression thread count to be used in live migration,
998 #          the compression thread count is an integer between 1 and 255.
999 #
1000 # @decompress-threads: Set decompression thread count to be used in live
1001 #          migration, the decompression thread count is an integer between 1
1002 #          and 255. Usually, decompression is at least 4 times as fast as
1003 #          compression, so set the decompress-threads to the number about 1/4
1004 #          of compress-threads is adequate.
1005 #
1006 # @cpu-throttle-initial: Initial percentage of time guest cpus are throttled
1007 #                        when migration auto-converge is activated. The
1008 #                        default value is 20. (Since 2.7)
1009 #
1010 # @cpu-throttle-increment: throttle percentage increase each time
1011 #                          auto-converge detects that migration is not making
1012 #                          progress. The default value is 10. (Since 2.7)
1013 #
1014 # @tls-creds: ID of the 'tls-creds' object that provides credentials for
1015 #             establishing a TLS connection over the migration data channel.
1016 #             On the outgoing side of the migration, the credentials must
1017 #             be for a 'client' endpoint, while for the incoming side the
1018 #             credentials must be for a 'server' endpoint. Setting this
1019 #             will enable TLS for all migrations. The default is unset,
1020 #             resulting in unsecured migration at the QEMU level. (Since 2.7)
1021 #
1022 # @tls-hostname: hostname of the target host for the migration. This is
1023 #                required when using x509 based TLS credentials and the
1024 #                migration URI does not already include a hostname. For
1025 #                example if using fd: or exec: based migration, the
1026 #                hostname must be provided so that the server's x509
1027 #                certificate identity can be validated. (Since 2.7)
1028 #
1029 # @max-bandwidth: to set maximum speed for migration. maximum speed in
1030 #                 bytes per second. (Since 2.8)
1031 #
1032 # @downtime-limit: set maximum tolerated downtime for migration. maximum
1033 #                  downtime in milliseconds (Since 2.8)
1034 #
1035 # @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in
1036 #          periodic mode. (Since 2.8)
1037 #
1038 # @block-incremental: Affects how much storage is migrated when the
1039 #       block migration capability is enabled.  When false, the entire
1040 #       storage backing chain is migrated into a flattened image at
1041 #       the destination; when true, only the active qcow2 layer is
1042 #       migrated and the destination must already have access to the
1043 #       same backing chain as was used on the source.  (since 2.10)
1044 #
1045 # Since: 2.4
1046 ##
1047 { 'enum': 'MigrationParameter',
1048   'data': ['compress-level', 'compress-threads', 'decompress-threads',
1049            'cpu-throttle-initial', 'cpu-throttle-increment',
1050            'tls-creds', 'tls-hostname', 'max-bandwidth',
1051            'downtime-limit', 'x-checkpoint-delay', 'block-incremental' ] }
1052
1053 ##
1054 # @MigrateSetParameters:
1055 #
1056 # @compress-level: compression level
1057 #
1058 # @compress-threads: compression thread count
1059 #
1060 # @decompress-threads: decompression thread count
1061 #
1062 # @cpu-throttle-initial: Initial percentage of time guest cpus are
1063 #                        throttled when migration auto-converge is activated.
1064 #                        The default value is 20. (Since 2.7)
1065 #
1066 # @cpu-throttle-increment: throttle percentage increase each time
1067 #                          auto-converge detects that migration is not making
1068 #                          progress. The default value is 10. (Since 2.7)
1069 #
1070 # @tls-creds: ID of the 'tls-creds' object that provides credentials
1071 #             for establishing a TLS connection over the migration data
1072 #             channel. On the outgoing side of the migration, the credentials
1073 #             must be for a 'client' endpoint, while for the incoming side the
1074 #             credentials must be for a 'server' endpoint. Setting this
1075 #             to a non-empty string enables TLS for all migrations.
1076 #             An empty string means that QEMU will use plain text mode for
1077 #             migration, rather than TLS (Since 2.9)
1078 #             Previously (since 2.7), this was reported by omitting
1079 #             tls-creds instead.
1080 #
1081 # @tls-hostname: hostname of the target host for the migration. This
1082 #                is required when using x509 based TLS credentials and the
1083 #                migration URI does not already include a hostname. For
1084 #                example if using fd: or exec: based migration, the
1085 #                hostname must be provided so that the server's x509
1086 #                certificate identity can be validated. (Since 2.7)
1087 #                An empty string means that QEMU will use the hostname
1088 #                associated with the migration URI, if any. (Since 2.9)
1089 #                Previously (since 2.7), this was reported by omitting
1090 #                tls-hostname instead.
1091 #
1092 # @max-bandwidth: to set maximum speed for migration. maximum speed in
1093 #                 bytes per second. (Since 2.8)
1094 #
1095 # @downtime-limit: set maximum tolerated downtime for migration. maximum
1096 #                  downtime in milliseconds (Since 2.8)
1097 #
1098 # @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
1099 #
1100 # @block-incremental: Affects how much storage is migrated when the
1101 #       block migration capability is enabled.  When false, the entire
1102 #       storage backing chain is migrated into a flattened image at
1103 #       the destination; when true, only the active qcow2 layer is
1104 #       migrated and the destination must already have access to the
1105 #       same backing chain as was used on the source.  (since 2.10)
1106 #
1107 # Since: 2.4
1108 ##
1109 # TODO either fuse back into MigrationParameters, or make
1110 # MigrationParameters members mandatory
1111 { 'struct': 'MigrateSetParameters',
1112   'data': { '*compress-level': 'int',
1113             '*compress-threads': 'int',
1114             '*decompress-threads': 'int',
1115             '*cpu-throttle-initial': 'int',
1116             '*cpu-throttle-increment': 'int',
1117             '*tls-creds': 'StrOrNull',
1118             '*tls-hostname': 'StrOrNull',
1119             '*max-bandwidth': 'int',
1120             '*downtime-limit': 'int',
1121             '*x-checkpoint-delay': 'int',
1122             '*block-incremental': 'bool' } }
1123
1124 ##
1125 # @migrate-set-parameters:
1126 #
1127 # Set various migration parameters.
1128 #
1129 # Since: 2.4
1130 #
1131 # Example:
1132 #
1133 # -> { "execute": "migrate-set-parameters" ,
1134 #      "arguments": { "compress-level": 1 } }
1135 #
1136 ##
1137 { 'command': 'migrate-set-parameters', 'boxed': true,
1138   'data': 'MigrateSetParameters' }
1139
1140 ##
1141 # @MigrationParameters:
1142 #
1143 # The optional members aren't actually optional.
1144 #
1145 # @compress-level: compression level
1146 #
1147 # @compress-threads: compression thread count
1148 #
1149 # @decompress-threads: decompression thread count
1150 #
1151 # @cpu-throttle-initial: Initial percentage of time guest cpus are
1152 #                        throttled when migration auto-converge is activated.
1153 #                        (Since 2.7)
1154 #
1155 # @cpu-throttle-increment: throttle percentage increase each time
1156 #                          auto-converge detects that migration is not making
1157 #                          progress. (Since 2.7)
1158 #
1159 # @tls-creds: ID of the 'tls-creds' object that provides credentials
1160 #             for establishing a TLS connection over the migration data
1161 #             channel. On the outgoing side of the migration, the credentials
1162 #             must be for a 'client' endpoint, while for the incoming side the
1163 #             credentials must be for a 'server' endpoint.
1164 #             An empty string means that QEMU will use plain text mode for
1165 #             migration, rather than TLS (Since 2.7)
1166 #             Note: 2.8 reports this by omitting tls-creds instead.
1167 #
1168 # @tls-hostname: hostname of the target host for the migration. This
1169 #                is required when using x509 based TLS credentials and the
1170 #                migration URI does not already include a hostname. For
1171 #                example if using fd: or exec: based migration, the
1172 #                hostname must be provided so that the server's x509
1173 #                certificate identity can be validated. (Since 2.7)
1174 #                An empty string means that QEMU will use the hostname
1175 #                associated with the migration URI, if any. (Since 2.9)
1176 #                Note: 2.8 reports this by omitting tls-hostname instead.
1177 #
1178 # @max-bandwidth: to set maximum speed for migration. maximum speed in
1179 #                 bytes per second. (Since 2.8)
1180 #
1181 # @downtime-limit: set maximum tolerated downtime for migration. maximum
1182 #                  downtime in milliseconds (Since 2.8)
1183 #
1184 # @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8)
1185 #
1186 # @block-incremental: Affects how much storage is migrated when the
1187 #       block migration capability is enabled.  When false, the entire
1188 #       storage backing chain is migrated into a flattened image at
1189 #       the destination; when true, only the active qcow2 layer is
1190 #       migrated and the destination must already have access to the
1191 #       same backing chain as was used on the source.  (since 2.10)
1192 #
1193 # Since: 2.4
1194 ##
1195 { 'struct': 'MigrationParameters',
1196   'data': { '*compress-level': 'int',
1197             '*compress-threads': 'int',
1198             '*decompress-threads': 'int',
1199             '*cpu-throttle-initial': 'int',
1200             '*cpu-throttle-increment': 'int',
1201             '*tls-creds': 'str',
1202             '*tls-hostname': 'str',
1203             '*max-bandwidth': 'int',
1204             '*downtime-limit': 'int',
1205             '*x-checkpoint-delay': 'int',
1206             '*block-incremental': 'bool' } }
1207
1208 ##
1209 # @query-migrate-parameters:
1210 #
1211 # Returns information about the current migration parameters
1212 #
1213 # Returns: @MigrationParameters
1214 #
1215 # Since: 2.4
1216 #
1217 # Example:
1218 #
1219 # -> { "execute": "query-migrate-parameters" }
1220 # <- { "return": {
1221 #          "decompress-threads": 2,
1222 #          "cpu-throttle-increment": 10,
1223 #          "compress-threads": 8,
1224 #          "compress-level": 1,
1225 #          "cpu-throttle-initial": 20,
1226 #          "max-bandwidth": 33554432,
1227 #          "downtime-limit": 300
1228 #       }
1229 #    }
1230 #
1231 ##
1232 { 'command': 'query-migrate-parameters',
1233   'returns': 'MigrationParameters' }
1234
1235 ##
1236 # @client_migrate_info:
1237 #
1238 # Set migration information for remote display.  This makes the server
1239 # ask the client to automatically reconnect using the new parameters
1240 # once migration finished successfully.  Only implemented for SPICE.
1241 #
1242 # @protocol:     must be "spice"
1243 # @hostname:     migration target hostname
1244 # @port:         spice tcp port for plaintext channels
1245 # @tls-port:     spice tcp port for tls-secured channels
1246 # @cert-subject: server certificate subject
1247 #
1248 # Since: 0.14.0
1249 #
1250 # Example:
1251 #
1252 # -> { "execute": "client_migrate_info",
1253 #      "arguments": { "protocol": "spice",
1254 #                     "hostname": "virt42.lab.kraxel.org",
1255 #                     "port": 1234 } }
1256 # <- { "return": {} }
1257 #
1258 ##
1259 { 'command': 'client_migrate_info',
1260   'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int',
1261             '*tls-port': 'int', '*cert-subject': 'str' } }
1262
1263 ##
1264 # @migrate-start-postcopy:
1265 #
1266 # Followup to a migration command to switch the migration to postcopy mode.
1267 # The postcopy-ram capability must be set before the original migration
1268 # command.
1269 #
1270 # Since: 2.5
1271 #
1272 # Example:
1273 #
1274 # -> { "execute": "migrate-start-postcopy" }
1275 # <- { "return": {} }
1276 #
1277 ##
1278 { 'command': 'migrate-start-postcopy' }
1279
1280 ##
1281 # @COLOMessage:
1282 #
1283 # The message transmission between Primary side and Secondary side.
1284 #
1285 # @checkpoint-ready: Secondary VM (SVM) is ready for checkpointing
1286 #
1287 # @checkpoint-request: Primary VM (PVM) tells SVM to prepare for checkpointing
1288 #
1289 # @checkpoint-reply: SVM gets PVM's checkpoint request
1290 #
1291 # @vmstate-send: VM's state will be sent by PVM.
1292 #
1293 # @vmstate-size: The total size of VMstate.
1294 #
1295 # @vmstate-received: VM's state has been received by SVM.
1296 #
1297 # @vmstate-loaded: VM's state has been loaded by SVM.
1298 #
1299 # Since: 2.8
1300 ##
1301 { 'enum': 'COLOMessage',
1302   'data': [ 'checkpoint-ready', 'checkpoint-request', 'checkpoint-reply',
1303             'vmstate-send', 'vmstate-size', 'vmstate-received',
1304             'vmstate-loaded' ] }
1305
1306 ##
1307 # @COLOMode:
1308 #
1309 # The colo mode
1310 #
1311 # @unknown: unknown mode
1312 #
1313 # @primary: master side
1314 #
1315 # @secondary: slave side
1316 #
1317 # Since: 2.8
1318 ##
1319 { 'enum': 'COLOMode',
1320   'data': [ 'unknown', 'primary', 'secondary'] }
1321
1322 ##
1323 # @FailoverStatus:
1324 #
1325 # An enumeration of COLO failover status
1326 #
1327 # @none: no failover has ever happened
1328 #
1329 # @require: got failover requirement but not handled
1330 #
1331 # @active: in the process of doing failover
1332 #
1333 # @completed: finish the process of failover
1334 #
1335 # @relaunch: restart the failover process, from 'none' -> 'completed' (Since 2.9)
1336 #
1337 # Since: 2.8
1338 ##
1339 { 'enum': 'FailoverStatus',
1340   'data': [ 'none', 'require', 'active', 'completed', 'relaunch' ] }
1341
1342 ##
1343 # @x-colo-lost-heartbeat:
1344 #
1345 # Tell qemu that heartbeat is lost, request it to do takeover procedures.
1346 # If this command is sent to the PVM, the Primary side will exit COLO mode.
1347 # If sent to the Secondary, the Secondary side will run failover work,
1348 # then takes over server operation to become the service VM.
1349 #
1350 # Since: 2.8
1351 #
1352 # Example:
1353 #
1354 # -> { "execute": "x-colo-lost-heartbeat" }
1355 # <- { "return": {} }
1356 #
1357 ##
1358 { 'command': 'x-colo-lost-heartbeat' }
1359
1360 ##
1361 # @MouseInfo:
1362 #
1363 # Information about a mouse device.
1364 #
1365 # @name: the name of the mouse device
1366 #
1367 # @index: the index of the mouse device
1368 #
1369 # @current: true if this device is currently receiving mouse events
1370 #
1371 # @absolute: true if this device supports absolute coordinates as input
1372 #
1373 # Since: 0.14.0
1374 ##
1375 { 'struct': 'MouseInfo',
1376   'data': {'name': 'str', 'index': 'int', 'current': 'bool',
1377            'absolute': 'bool'} }
1378
1379 ##
1380 # @query-mice:
1381 #
1382 # Returns information about each active mouse device
1383 #
1384 # Returns: a list of @MouseInfo for each device
1385 #
1386 # Since: 0.14.0
1387 #
1388 # Example:
1389 #
1390 # -> { "execute": "query-mice" }
1391 # <- { "return": [
1392 #          {
1393 #             "name":"QEMU Microsoft Mouse",
1394 #             "index":0,
1395 #             "current":false,
1396 #             "absolute":false
1397 #          },
1398 #          {
1399 #             "name":"QEMU PS/2 Mouse",
1400 #             "index":1,
1401 #             "current":true,
1402 #             "absolute":true
1403 #          }
1404 #       ]
1405 #    }
1406 #
1407 ##
1408 { 'command': 'query-mice', 'returns': ['MouseInfo'] }
1409
1410 ##
1411 # @CpuInfoArch:
1412 #
1413 # An enumeration of cpu types that enable additional information during
1414 # @query-cpus.
1415 #
1416 # Since: 2.6
1417 ##
1418 { 'enum': 'CpuInfoArch',
1419   'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 'other' ] }
1420
1421 ##
1422 # @CpuInfo:
1423 #
1424 # Information about a virtual CPU
1425 #
1426 # @CPU: the index of the virtual CPU
1427 #
1428 # @current: this only exists for backwards compatibility and should be ignored
1429 #
1430 # @halted: true if the virtual CPU is in the halt state.  Halt usually refers
1431 #          to a processor specific low power mode.
1432 #
1433 # @qom_path: path to the CPU object in the QOM tree (since 2.4)
1434 #
1435 # @thread_id: ID of the underlying host thread
1436 #
1437 # @props: properties describing to which node/socket/core/thread
1438 #         virtual CPU belongs to, provided if supported by board (since 2.10)
1439 #
1440 # @arch: architecture of the cpu, which determines which additional fields
1441 #        will be listed (since 2.6)
1442 #
1443 # Since: 0.14.0
1444 #
1445 # Notes: @halted is a transient state that changes frequently.  By the time the
1446 #        data is sent to the client, the guest may no longer be halted.
1447 ##
1448 { 'union': 'CpuInfo',
1449   'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool',
1450            'qom_path': 'str', 'thread_id': 'int',
1451            '*props': 'CpuInstanceProperties', 'arch': 'CpuInfoArch' },
1452   'discriminator': 'arch',
1453   'data': { 'x86': 'CpuInfoX86',
1454             'sparc': 'CpuInfoSPARC',
1455             'ppc': 'CpuInfoPPC',
1456             'mips': 'CpuInfoMIPS',
1457             'tricore': 'CpuInfoTricore',
1458             'other': 'CpuInfoOther' } }
1459
1460 ##
1461 # @CpuInfoX86:
1462 #
1463 # Additional information about a virtual i386 or x86_64 CPU
1464 #
1465 # @pc: the 64-bit instruction pointer
1466 #
1467 # Since: 2.6
1468 ##
1469 { 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } }
1470
1471 ##
1472 # @CpuInfoSPARC:
1473 #
1474 # Additional information about a virtual SPARC CPU
1475 #
1476 # @pc: the PC component of the instruction pointer
1477 #
1478 # @npc: the NPC component of the instruction pointer
1479 #
1480 # Since: 2.6
1481 ##
1482 { 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } }
1483
1484 ##
1485 # @CpuInfoPPC:
1486 #
1487 # Additional information about a virtual PPC CPU
1488 #
1489 # @nip: the instruction pointer
1490 #
1491 # Since: 2.6
1492 ##
1493 { 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } }
1494
1495 ##
1496 # @CpuInfoMIPS:
1497 #
1498 # Additional information about a virtual MIPS CPU
1499 #
1500 # @PC: the instruction pointer
1501 #
1502 # Since: 2.6
1503 ##
1504 { 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } }
1505
1506 ##
1507 # @CpuInfoTricore:
1508 #
1509 # Additional information about a virtual Tricore CPU
1510 #
1511 # @PC: the instruction pointer
1512 #
1513 # Since: 2.6
1514 ##
1515 { 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } }
1516
1517 ##
1518 # @CpuInfoOther:
1519 #
1520 # No additional information is available about the virtual CPU
1521 #
1522 # Since: 2.6
1523 #
1524 ##
1525 { 'struct': 'CpuInfoOther', 'data': { } }
1526
1527 ##
1528 # @query-cpus:
1529 #
1530 # Returns a list of information about each virtual CPU.
1531 #
1532 # Returns: a list of @CpuInfo for each virtual CPU
1533 #
1534 # Since: 0.14.0
1535 #
1536 # Example:
1537 #
1538 # -> { "execute": "query-cpus" }
1539 # <- { "return": [
1540 #          {
1541 #             "CPU":0,
1542 #             "current":true,
1543 #             "halted":false,
1544 #             "qom_path":"/machine/unattached/device[0]",
1545 #             "arch":"x86",
1546 #             "pc":3227107138,
1547 #             "thread_id":3134
1548 #          },
1549 #          {
1550 #             "CPU":1,
1551 #             "current":false,
1552 #             "halted":true,
1553 #             "qom_path":"/machine/unattached/device[2]",
1554 #             "arch":"x86",
1555 #             "pc":7108165,
1556 #             "thread_id":3135
1557 #          }
1558 #       ]
1559 #    }
1560 #
1561 ##
1562 { 'command': 'query-cpus', 'returns': ['CpuInfo'] }
1563
1564 ##
1565 # @IOThreadInfo:
1566 #
1567 # Information about an iothread
1568 #
1569 # @id: the identifier of the iothread
1570 #
1571 # @thread-id: ID of the underlying host thread
1572 #
1573 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
1574 #               (since 2.9)
1575 #
1576 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
1577 #             configured (since 2.9)
1578 #
1579 # @poll-shrink: how many ns will be removed from polling time, 0 means that
1580 #               it's not configured (since 2.9)
1581 #
1582 # Since: 2.0
1583 ##
1584 { 'struct': 'IOThreadInfo',
1585   'data': {'id': 'str',
1586            'thread-id': 'int',
1587            'poll-max-ns': 'int',
1588            'poll-grow': 'int',
1589            'poll-shrink': 'int' } }
1590
1591 ##
1592 # @query-iothreads:
1593 #
1594 # Returns a list of information about each iothread.
1595 #
1596 # Note: this list excludes the QEMU main loop thread, which is not declared
1597 # using the -object iothread command-line option.  It is always the main thread
1598 # of the process.
1599 #
1600 # Returns: a list of @IOThreadInfo for each iothread
1601 #
1602 # Since: 2.0
1603 #
1604 # Example:
1605 #
1606 # -> { "execute": "query-iothreads" }
1607 # <- { "return": [
1608 #          {
1609 #             "id":"iothread0",
1610 #             "thread-id":3134
1611 #          },
1612 #          {
1613 #             "id":"iothread1",
1614 #             "thread-id":3135
1615 #          }
1616 #       ]
1617 #    }
1618 #
1619 ##
1620 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'] }
1621
1622 ##
1623 # @NetworkAddressFamily:
1624 #
1625 # The network address family
1626 #
1627 # @ipv4: IPV4 family
1628 #
1629 # @ipv6: IPV6 family
1630 #
1631 # @unix: unix socket
1632 #
1633 # @vsock: vsock family (since 2.8)
1634 #
1635 # @unknown: otherwise
1636 #
1637 # Since: 2.1
1638 ##
1639 { 'enum': 'NetworkAddressFamily',
1640   'data': [ 'ipv4', 'ipv6', 'unix', 'vsock', 'unknown' ] }
1641
1642 ##
1643 # @VncBasicInfo:
1644 #
1645 # The basic information for vnc network connection
1646 #
1647 # @host: IP address
1648 #
1649 # @service: The service name of the vnc port. This may depend on the host
1650 #           system's service database so symbolic names should not be relied
1651 #           on.
1652 #
1653 # @family: address family
1654 #
1655 # @websocket: true in case the socket is a websocket (since 2.3).
1656 #
1657 # Since: 2.1
1658 ##
1659 { 'struct': 'VncBasicInfo',
1660   'data': { 'host': 'str',
1661             'service': 'str',
1662             'family': 'NetworkAddressFamily',
1663             'websocket': 'bool' } }
1664
1665 ##
1666 # @VncServerInfo:
1667 #
1668 # The network connection information for server
1669 #
1670 # @auth: authentication method used for
1671 #        the plain (non-websocket) VNC server
1672 #
1673 # Since: 2.1
1674 ##
1675 { 'struct': 'VncServerInfo',
1676   'base': 'VncBasicInfo',
1677   'data': { '*auth': 'str' } }
1678
1679 ##
1680 # @VncClientInfo:
1681 #
1682 # Information about a connected VNC client.
1683 #
1684 # @x509_dname: If x509 authentication is in use, the Distinguished
1685 #              Name of the client.
1686 #
1687 # @sasl_username: If SASL authentication is in use, the SASL username
1688 #                 used for authentication.
1689 #
1690 # Since: 0.14.0
1691 ##
1692 { 'struct': 'VncClientInfo',
1693   'base': 'VncBasicInfo',
1694   'data': { '*x509_dname': 'str', '*sasl_username': 'str' } }
1695
1696 ##
1697 # @VncInfo:
1698 #
1699 # Information about the VNC session.
1700 #
1701 # @enabled: true if the VNC server is enabled, false otherwise
1702 #
1703 # @host: The hostname the VNC server is bound to.  This depends on
1704 #        the name resolution on the host and may be an IP address.
1705 #
1706 # @family: 'ipv6' if the host is listening for IPv6 connections
1707 #                    'ipv4' if the host is listening for IPv4 connections
1708 #                    'unix' if the host is listening on a unix domain socket
1709 #                    'unknown' otherwise
1710 #
1711 # @service: The service name of the server's port.  This may depends
1712 #           on the host system's service database so symbolic names should not
1713 #           be relied on.
1714 #
1715 # @auth: the current authentication type used by the server
1716 #        'none' if no authentication is being used
1717 #        'vnc' if VNC authentication is being used
1718 #        'vencrypt+plain' if VEncrypt is used with plain text authentication
1719 #        'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
1720 #        'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
1721 #        'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
1722 #        'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
1723 #        'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
1724 #        'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
1725 #        'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
1726 #        'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
1727 #
1728 # @clients: a list of @VncClientInfo of all currently connected clients
1729 #
1730 # Since: 0.14.0
1731 ##
1732 { 'struct': 'VncInfo',
1733   'data': {'enabled': 'bool', '*host': 'str',
1734            '*family': 'NetworkAddressFamily',
1735            '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']} }
1736
1737 ##
1738 # @VncPrimaryAuth:
1739 #
1740 # vnc primary authentication method.
1741 #
1742 # Since: 2.3
1743 ##
1744 { 'enum': 'VncPrimaryAuth',
1745   'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra',
1746             'tls', 'vencrypt', 'sasl' ] }
1747
1748 ##
1749 # @VncVencryptSubAuth:
1750 #
1751 # vnc sub authentication method with vencrypt.
1752 #
1753 # Since: 2.3
1754 ##
1755 { 'enum': 'VncVencryptSubAuth',
1756   'data': [ 'plain',
1757             'tls-none',  'x509-none',
1758             'tls-vnc',   'x509-vnc',
1759             'tls-plain', 'x509-plain',
1760             'tls-sasl',  'x509-sasl' ] }
1761
1762
1763 ##
1764 # @VncServerInfo2:
1765 #
1766 # The network connection information for server
1767 #
1768 # @auth: The current authentication type used by the servers
1769 #
1770 # @vencrypt: The vencrypt sub authentication type used by the
1771 #            servers, only specified in case auth == vencrypt.
1772 #
1773 # Since: 2.9
1774 ##
1775 { 'struct': 'VncServerInfo2',
1776   'base': 'VncBasicInfo',
1777   'data': { 'auth'      : 'VncPrimaryAuth',
1778             '*vencrypt' : 'VncVencryptSubAuth' } }
1779
1780
1781 ##
1782 # @VncInfo2:
1783 #
1784 # Information about a vnc server
1785 #
1786 # @id: vnc server name.
1787 #
1788 # @server: A list of @VncBasincInfo describing all listening sockets.
1789 #          The list can be empty (in case the vnc server is disabled).
1790 #          It also may have multiple entries: normal + websocket,
1791 #          possibly also ipv4 + ipv6 in the future.
1792 #
1793 # @clients: A list of @VncClientInfo of all currently connected clients.
1794 #           The list can be empty, for obvious reasons.
1795 #
1796 # @auth: The current authentication type used by the non-websockets servers
1797 #
1798 # @vencrypt: The vencrypt authentication type used by the servers,
1799 #            only specified in case auth == vencrypt.
1800 #
1801 # @display: The display device the vnc server is linked to.
1802 #
1803 # Since: 2.3
1804 ##
1805 { 'struct': 'VncInfo2',
1806   'data': { 'id'        : 'str',
1807             'server'    : ['VncServerInfo2'],
1808             'clients'   : ['VncClientInfo'],
1809             'auth'      : 'VncPrimaryAuth',
1810             '*vencrypt' : 'VncVencryptSubAuth',
1811             '*display'  : 'str' } }
1812
1813 ##
1814 # @query-vnc:
1815 #
1816 # Returns information about the current VNC server
1817 #
1818 # Returns: @VncInfo
1819 #
1820 # Since: 0.14.0
1821 #
1822 # Example:
1823 #
1824 # -> { "execute": "query-vnc" }
1825 # <- { "return": {
1826 #          "enabled":true,
1827 #          "host":"0.0.0.0",
1828 #          "service":"50402",
1829 #          "auth":"vnc",
1830 #          "family":"ipv4",
1831 #          "clients":[
1832 #             {
1833 #                "host":"127.0.0.1",
1834 #                "service":"50401",
1835 #                "family":"ipv4"
1836 #             }
1837 #          ]
1838 #       }
1839 #    }
1840 #
1841 ##
1842 { 'command': 'query-vnc', 'returns': 'VncInfo' }
1843
1844 ##
1845 # @query-vnc-servers:
1846 #
1847 # Returns a list of vnc servers.  The list can be empty.
1848 #
1849 # Returns: a list of @VncInfo2
1850 #
1851 # Since: 2.3
1852 ##
1853 { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'] }
1854
1855 ##
1856 # @SpiceBasicInfo:
1857 #
1858 # The basic information for SPICE network connection
1859 #
1860 # @host: IP address
1861 #
1862 # @port: port number
1863 #
1864 # @family: address family
1865 #
1866 # Since: 2.1
1867 ##
1868 { 'struct': 'SpiceBasicInfo',
1869   'data': { 'host': 'str',
1870             'port': 'str',
1871             'family': 'NetworkAddressFamily' } }
1872
1873 ##
1874 # @SpiceServerInfo:
1875 #
1876 # Information about a SPICE server
1877 #
1878 # @auth: authentication method
1879 #
1880 # Since: 2.1
1881 ##
1882 { 'struct': 'SpiceServerInfo',
1883   'base': 'SpiceBasicInfo',
1884   'data': { '*auth': 'str' } }
1885
1886 ##
1887 # @SpiceChannel:
1888 #
1889 # Information about a SPICE client channel.
1890 #
1891 # @connection-id: SPICE connection id number.  All channels with the same id
1892 #                 belong to the same SPICE session.
1893 #
1894 # @channel-type: SPICE channel type number.  "1" is the main control
1895 #                channel, filter for this one if you want to track spice
1896 #                sessions only
1897 #
1898 # @channel-id: SPICE channel ID number.  Usually "0", might be different when
1899 #              multiple channels of the same type exist, such as multiple
1900 #              display channels in a multihead setup
1901 #
1902 # @tls: true if the channel is encrypted, false otherwise.
1903 #
1904 # Since: 0.14.0
1905 ##
1906 { 'struct': 'SpiceChannel',
1907   'base': 'SpiceBasicInfo',
1908   'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
1909            'tls': 'bool'} }
1910
1911 ##
1912 # @SpiceQueryMouseMode:
1913 #
1914 # An enumeration of Spice mouse states.
1915 #
1916 # @client: Mouse cursor position is determined by the client.
1917 #
1918 # @server: Mouse cursor position is determined by the server.
1919 #
1920 # @unknown: No information is available about mouse mode used by
1921 #           the spice server.
1922 #
1923 # Note: spice/enums.h has a SpiceMouseMode already, hence the name.
1924 #
1925 # Since: 1.1
1926 ##
1927 { 'enum': 'SpiceQueryMouseMode',
1928   'data': [ 'client', 'server', 'unknown' ] }
1929
1930 ##
1931 # @SpiceInfo:
1932 #
1933 # Information about the SPICE session.
1934 #
1935 # @enabled: true if the SPICE server is enabled, false otherwise
1936 #
1937 # @migrated: true if the last guest migration completed and spice
1938 #            migration had completed as well. false otherwise. (since 1.4)
1939 #
1940 # @host: The hostname the SPICE server is bound to.  This depends on
1941 #        the name resolution on the host and may be an IP address.
1942 #
1943 # @port: The SPICE server's port number.
1944 #
1945 # @compiled-version: SPICE server version.
1946 #
1947 # @tls-port: The SPICE server's TLS port number.
1948 #
1949 # @auth: the current authentication type used by the server
1950 #        'none'  if no authentication is being used
1951 #        'spice' uses SASL or direct TLS authentication, depending on command
1952 #                line options
1953 #
1954 # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
1955 #              be determined by the client or the server, or unknown if spice
1956 #              server doesn't provide this information. (since: 1.1)
1957 #
1958 # @channels: a list of @SpiceChannel for each active spice channel
1959 #
1960 # Since: 0.14.0
1961 ##
1962 { 'struct': 'SpiceInfo',
1963   'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
1964            '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
1965            'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']} }
1966
1967 ##
1968 # @query-spice:
1969 #
1970 # Returns information about the current SPICE server
1971 #
1972 # Returns: @SpiceInfo
1973 #
1974 # Since: 0.14.0
1975 #
1976 # Example:
1977 #
1978 # -> { "execute": "query-spice" }
1979 # <- { "return": {
1980 #          "enabled": true,
1981 #          "auth": "spice",
1982 #          "port": 5920,
1983 #          "tls-port": 5921,
1984 #          "host": "0.0.0.0",
1985 #          "channels": [
1986 #             {
1987 #                "port": "54924",
1988 #                "family": "ipv4",
1989 #                "channel-type": 1,
1990 #                "connection-id": 1804289383,
1991 #                "host": "127.0.0.1",
1992 #                "channel-id": 0,
1993 #                "tls": true
1994 #             },
1995 #             {
1996 #                "port": "36710",
1997 #                "family": "ipv4",
1998 #                "channel-type": 4,
1999 #                "connection-id": 1804289383,
2000 #                "host": "127.0.0.1",
2001 #                "channel-id": 0,
2002 #                "tls": false
2003 #             },
2004 #             [ ... more channels follow ... ]
2005 #          ]
2006 #       }
2007 #    }
2008 #
2009 ##
2010 { 'command': 'query-spice', 'returns': 'SpiceInfo' }
2011
2012 ##
2013 # @BalloonInfo:
2014 #
2015 # Information about the guest balloon device.
2016 #
2017 # @actual: the number of bytes the balloon currently contains
2018 #
2019 # Since: 0.14.0
2020 #
2021 ##
2022 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
2023
2024 ##
2025 # @query-balloon:
2026 #
2027 # Return information about the balloon device.
2028 #
2029 # Returns: @BalloonInfo on success
2030 #
2031 #          If the balloon driver is enabled but not functional because the KVM
2032 #          kernel module cannot support it, KvmMissingCap
2033 #
2034 #          If no balloon device is present, DeviceNotActive
2035 #
2036 # Since: 0.14.0
2037 #
2038 # Example:
2039 #
2040 # -> { "execute": "query-balloon" }
2041 # <- { "return": {
2042 #          "actual": 1073741824,
2043 #       }
2044 #    }
2045 #
2046 ##
2047 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
2048
2049 ##
2050 # @PciMemoryRange:
2051 #
2052 # A PCI device memory region
2053 #
2054 # @base: the starting address (guest physical)
2055 #
2056 # @limit: the ending address (guest physical)
2057 #
2058 # Since: 0.14.0
2059 ##
2060 { 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
2061
2062 ##
2063 # @PciMemoryRegion:
2064 #
2065 # Information about a PCI device I/O region.
2066 #
2067 # @bar: the index of the Base Address Register for this region
2068 #
2069 # @type: 'io' if the region is a PIO region
2070 #        'memory' if the region is a MMIO region
2071 #
2072 # @size: memory size
2073 #
2074 # @prefetch: if @type is 'memory', true if the memory is prefetchable
2075 #
2076 # @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
2077 #
2078 # Since: 0.14.0
2079 ##
2080 { 'struct': 'PciMemoryRegion',
2081   'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
2082            '*prefetch': 'bool', '*mem_type_64': 'bool' } }
2083
2084 ##
2085 # @PciBusInfo:
2086 #
2087 # Information about a bus of a PCI Bridge device
2088 #
2089 # @number: primary bus interface number.  This should be the number of the
2090 #          bus the device resides on.
2091 #
2092 # @secondary: secondary bus interface number.  This is the number of the
2093 #             main bus for the bridge
2094 #
2095 # @subordinate: This is the highest number bus that resides below the
2096 #               bridge.
2097 #
2098 # @io_range: The PIO range for all devices on this bridge
2099 #
2100 # @memory_range: The MMIO range for all devices on this bridge
2101 #
2102 # @prefetchable_range: The range of prefetchable MMIO for all devices on
2103 #                      this bridge
2104 #
2105 # Since: 2.4
2106 ##
2107 { 'struct': 'PciBusInfo',
2108   'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
2109            'io_range': 'PciMemoryRange',
2110            'memory_range': 'PciMemoryRange',
2111            'prefetchable_range': 'PciMemoryRange' } }
2112
2113 ##
2114 # @PciBridgeInfo:
2115 #
2116 # Information about a PCI Bridge device
2117 #
2118 # @bus: information about the bus the device resides on
2119 #
2120 # @devices: a list of @PciDeviceInfo for each device on this bridge
2121 #
2122 # Since: 0.14.0
2123 ##
2124 { 'struct': 'PciBridgeInfo',
2125   'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }
2126
2127 ##
2128 # @PciDeviceClass:
2129 #
2130 # Information about the Class of a PCI device
2131 #
2132 # @desc: a string description of the device's class
2133 #
2134 # @class: the class code of the device
2135 #
2136 # Since: 2.4
2137 ##
2138 { 'struct': 'PciDeviceClass',
2139   'data': {'*desc': 'str', 'class': 'int'} }
2140
2141 ##
2142 # @PciDeviceId:
2143 #
2144 # Information about the Id of a PCI device
2145 #
2146 # @device: the PCI device id
2147 #
2148 # @vendor: the PCI vendor id
2149 #
2150 # Since: 2.4
2151 ##
2152 { 'struct': 'PciDeviceId',
2153   'data': {'device': 'int', 'vendor': 'int'} }
2154
2155 ##
2156 # @PciDeviceInfo:
2157 #
2158 # Information about a PCI device
2159 #
2160 # @bus: the bus number of the device
2161 #
2162 # @slot: the slot the device is located in
2163 #
2164 # @function: the function of the slot used by the device
2165 #
2166 # @class_info: the class of the device
2167 #
2168 # @id: the PCI device id
2169 #
2170 # @irq: if an IRQ is assigned to the device, the IRQ number
2171 #
2172 # @qdev_id: the device name of the PCI device
2173 #
2174 # @pci_bridge: if the device is a PCI bridge, the bridge information
2175 #
2176 # @regions: a list of the PCI I/O regions associated with the device
2177 #
2178 # Notes: the contents of @class_info.desc are not stable and should only be
2179 #        treated as informational.
2180 #
2181 # Since: 0.14.0
2182 ##
2183 { 'struct': 'PciDeviceInfo',
2184   'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
2185            'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
2186            '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo',
2187            'regions': ['PciMemoryRegion']} }
2188
2189 ##
2190 # @PciInfo:
2191 #
2192 # Information about a PCI bus
2193 #
2194 # @bus: the bus index
2195 #
2196 # @devices: a list of devices on this bus
2197 #
2198 # Since: 0.14.0
2199 ##
2200 { 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
2201
2202 ##
2203 # @query-pci:
2204 #
2205 # Return information about the PCI bus topology of the guest.
2206 #
2207 # Returns: a list of @PciInfo for each PCI bus. Each bus is
2208 # represented by a json-object, which has a key with a json-array of
2209 # all PCI devices attached to it. Each device is represented by a
2210 # json-object.
2211 #
2212 # Since: 0.14.0
2213 #
2214 # Example:
2215 #
2216 # -> { "execute": "query-pci" }
2217 # <- { "return": [
2218 #          {
2219 #             "bus": 0,
2220 #             "devices": [
2221 #                {
2222 #                   "bus": 0,
2223 #                   "qdev_id": "",
2224 #                   "slot": 0,
2225 #                   "class_info": {
2226 #                      "class": 1536,
2227 #                      "desc": "Host bridge"
2228 #                   },
2229 #                   "id": {
2230 #                      "device": 32902,
2231 #                      "vendor": 4663
2232 #                   },
2233 #                   "function": 0,
2234 #                   "regions": [
2235 #                   ]
2236 #                },
2237 #                {
2238 #                   "bus": 0,
2239 #                   "qdev_id": "",
2240 #                   "slot": 1,
2241 #                   "class_info": {
2242 #                      "class": 1537,
2243 #                      "desc": "ISA bridge"
2244 #                   },
2245 #                   "id": {
2246 #                      "device": 32902,
2247 #                      "vendor": 28672
2248 #                   },
2249 #                   "function": 0,
2250 #                   "regions": [
2251 #                   ]
2252 #                },
2253 #                {
2254 #                   "bus": 0,
2255 #                   "qdev_id": "",
2256 #                   "slot": 1,
2257 #                   "class_info": {
2258 #                      "class": 257,
2259 #                      "desc": "IDE controller"
2260 #                   },
2261 #                   "id": {
2262 #                      "device": 32902,
2263 #                      "vendor": 28688
2264 #                   },
2265 #                   "function": 1,
2266 #                   "regions": [
2267 #                      {
2268 #                         "bar": 4,
2269 #                         "size": 16,
2270 #                         "address": 49152,
2271 #                         "type": "io"
2272 #                      }
2273 #                   ]
2274 #                },
2275 #                {
2276 #                   "bus": 0,
2277 #                   "qdev_id": "",
2278 #                   "slot": 2,
2279 #                   "class_info": {
2280 #                      "class": 768,
2281 #                      "desc": "VGA controller"
2282 #                   },
2283 #                   "id": {
2284 #                      "device": 4115,
2285 #                      "vendor": 184
2286 #                   },
2287 #                   "function": 0,
2288 #                   "regions": [
2289 #                      {
2290 #                         "prefetch": true,
2291 #                         "mem_type_64": false,
2292 #                         "bar": 0,
2293 #                         "size": 33554432,
2294 #                         "address": 4026531840,
2295 #                         "type": "memory"
2296 #                      },
2297 #                      {
2298 #                         "prefetch": false,
2299 #                         "mem_type_64": false,
2300 #                         "bar": 1,
2301 #                         "size": 4096,
2302 #                         "address": 4060086272,
2303 #                         "type": "memory"
2304 #                      },
2305 #                      {
2306 #                         "prefetch": false,
2307 #                         "mem_type_64": false,
2308 #                         "bar": 6,
2309 #                         "size": 65536,
2310 #                         "address": -1,
2311 #                         "type": "memory"
2312 #                      }
2313 #                   ]
2314 #                },
2315 #                {
2316 #                   "bus": 0,
2317 #                   "qdev_id": "",
2318 #                   "irq": 11,
2319 #                   "slot": 4,
2320 #                   "class_info": {
2321 #                      "class": 1280,
2322 #                      "desc": "RAM controller"
2323 #                   },
2324 #                   "id": {
2325 #                      "device": 6900,
2326 #                      "vendor": 4098
2327 #                   },
2328 #                   "function": 0,
2329 #                   "regions": [
2330 #                      {
2331 #                         "bar": 0,
2332 #                         "size": 32,
2333 #                         "address": 49280,
2334 #                         "type": "io"
2335 #                      }
2336 #                   ]
2337 #                }
2338 #             ]
2339 #          }
2340 #       ]
2341 #    }
2342 #
2343 # Note: This example has been shortened as the real response is too long.
2344 #
2345 ##
2346 { 'command': 'query-pci', 'returns': ['PciInfo'] }
2347
2348 ##
2349 # @quit:
2350 #
2351 # This command will cause the QEMU process to exit gracefully.  While every
2352 # attempt is made to send the QMP response before terminating, this is not
2353 # guaranteed.  When using this interface, a premature EOF would not be
2354 # unexpected.
2355 #
2356 # Since: 0.14.0
2357 #
2358 # Example:
2359 #
2360 # -> { "execute": "quit" }
2361 # <- { "return": {} }
2362 ##
2363 { 'command': 'quit' }
2364
2365 ##
2366 # @stop:
2367 #
2368 # Stop all guest VCPU execution.
2369 #
2370 # Since:  0.14.0
2371 #
2372 # Notes:  This function will succeed even if the guest is already in the stopped
2373 #         state.  In "inmigrate" state, it will ensure that the guest
2374 #         remains paused once migration finishes, as if the -S option was
2375 #         passed on the command line.
2376 #
2377 # Example:
2378 #
2379 # -> { "execute": "stop" }
2380 # <- { "return": {} }
2381 #
2382 ##
2383 { 'command': 'stop' }
2384
2385 ##
2386 # @system_reset:
2387 #
2388 # Performs a hard reset of a guest.
2389 #
2390 # Since: 0.14.0
2391 #
2392 # Example:
2393 #
2394 # -> { "execute": "system_reset" }
2395 # <- { "return": {} }
2396 #
2397 ##
2398 { 'command': 'system_reset' }
2399
2400 ##
2401 # @system_powerdown:
2402 #
2403 # Requests that a guest perform a powerdown operation.
2404 #
2405 # Since: 0.14.0
2406 #
2407 # Notes: A guest may or may not respond to this command.  This command
2408 #        returning does not indicate that a guest has accepted the request or
2409 #        that it has shut down.  Many guests will respond to this command by
2410 #        prompting the user in some way.
2411 # Example:
2412 #
2413 # -> { "execute": "system_powerdown" }
2414 # <- { "return": {} }
2415 #
2416 ##
2417 { 'command': 'system_powerdown' }
2418
2419 ##
2420 # @cpu:
2421 #
2422 # This command is a nop that is only provided for the purposes of compatibility.
2423 #
2424 # Since: 0.14.0
2425 #
2426 # Notes: Do not use this command.
2427 ##
2428 { 'command': 'cpu', 'data': {'index': 'int'} }
2429
2430 ##
2431 # @cpu-add:
2432 #
2433 # Adds CPU with specified ID
2434 #
2435 # @id: ID of CPU to be created, valid values [0..max_cpus)
2436 #
2437 # Returns: Nothing on success
2438 #
2439 # Since: 1.5
2440 #
2441 # Example:
2442 #
2443 # -> { "execute": "cpu-add", "arguments": { "id": 2 } }
2444 # <- { "return": {} }
2445 #
2446 ##
2447 { 'command': 'cpu-add', 'data': {'id': 'int'} }
2448
2449 ##
2450 # @memsave:
2451 #
2452 # Save a portion of guest memory to a file.
2453 #
2454 # @val: the virtual address of the guest to start from
2455 #
2456 # @size: the size of memory region to save
2457 #
2458 # @filename: the file to save the memory to as binary data
2459 #
2460 # @cpu-index: the index of the virtual CPU to use for translating the
2461 #                       virtual address (defaults to CPU 0)
2462 #
2463 # Returns: Nothing on success
2464 #
2465 # Since: 0.14.0
2466 #
2467 # Notes: Errors were not reliably returned until 1.1
2468 #
2469 # Example:
2470 #
2471 # -> { "execute": "memsave",
2472 #      "arguments": { "val": 10,
2473 #                     "size": 100,
2474 #                     "filename": "/tmp/virtual-mem-dump" } }
2475 # <- { "return": {} }
2476 #
2477 ##
2478 { 'command': 'memsave',
2479   'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
2480
2481 ##
2482 # @pmemsave:
2483 #
2484 # Save a portion of guest physical memory to a file.
2485 #
2486 # @val: the physical address of the guest to start from
2487 #
2488 # @size: the size of memory region to save
2489 #
2490 # @filename: the file to save the memory to as binary data
2491 #
2492 # Returns: Nothing on success
2493 #
2494 # Since: 0.14.0
2495 #
2496 # Notes: Errors were not reliably returned until 1.1
2497 #
2498 # Example:
2499 #
2500 # -> { "execute": "pmemsave",
2501 #      "arguments": { "val": 10,
2502 #                     "size": 100,
2503 #                     "filename": "/tmp/physical-mem-dump" } }
2504 # <- { "return": {} }
2505 #
2506 ##
2507 { 'command': 'pmemsave',
2508   'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
2509
2510 ##
2511 # @cont:
2512 #
2513 # Resume guest VCPU execution.
2514 #
2515 # Since:  0.14.0
2516 #
2517 # Returns:  If successful, nothing
2518 #
2519 # Notes:  This command will succeed if the guest is currently running.  It
2520 #         will also succeed if the guest is in the "inmigrate" state; in
2521 #         this case, the effect of the command is to make sure the guest
2522 #         starts once migration finishes, removing the effect of the -S
2523 #         command line option if it was passed.
2524 #
2525 # Example:
2526 #
2527 # -> { "execute": "cont" }
2528 # <- { "return": {} }
2529 #
2530 ##
2531 { 'command': 'cont' }
2532
2533 ##
2534 # @system_wakeup:
2535 #
2536 # Wakeup guest from suspend.  Does nothing in case the guest isn't suspended.
2537 #
2538 # Since:  1.1
2539 #
2540 # Returns:  nothing.
2541 #
2542 # Example:
2543 #
2544 # -> { "execute": "system_wakeup" }
2545 # <- { "return": {} }
2546 #
2547 ##
2548 { 'command': 'system_wakeup' }
2549
2550 ##
2551 # @inject-nmi:
2552 #
2553 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
2554 # The command fails when the guest doesn't support injecting.
2555 #
2556 # Returns:  If successful, nothing
2557 #
2558 # Since:  0.14.0
2559 #
2560 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
2561 #
2562 # Example:
2563 #
2564 # -> { "execute": "inject-nmi" }
2565 # <- { "return": {} }
2566 #
2567 ##
2568 { 'command': 'inject-nmi' }
2569
2570 ##
2571 # @set_link:
2572 #
2573 # Sets the link status of a virtual network adapter.
2574 #
2575 # @name: the device name of the virtual network adapter
2576 #
2577 # @up: true to set the link status to be up
2578 #
2579 # Returns: Nothing on success
2580 #          If @name is not a valid network device, DeviceNotFound
2581 #
2582 # Since: 0.14.0
2583 #
2584 # Notes: Not all network adapters support setting link status.  This command
2585 #        will succeed even if the network adapter does not support link status
2586 #        notification.
2587 #
2588 # Example:
2589 #
2590 # -> { "execute": "set_link",
2591 #      "arguments": { "name": "e1000.0", "up": false } }
2592 # <- { "return": {} }
2593 #
2594 ##
2595 { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
2596
2597 ##
2598 # @balloon:
2599 #
2600 # Request the balloon driver to change its balloon size.
2601 #
2602 # @value: the target size of the balloon in bytes
2603 #
2604 # Returns: Nothing on success
2605 #          If the balloon driver is enabled but not functional because the KVM
2606 #            kernel module cannot support it, KvmMissingCap
2607 #          If no balloon device is present, DeviceNotActive
2608 #
2609 # Notes: This command just issues a request to the guest.  When it returns,
2610 #        the balloon size may not have changed.  A guest can change the balloon
2611 #        size independent of this command.
2612 #
2613 # Since: 0.14.0
2614 #
2615 # Example:
2616 #
2617 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
2618 # <- { "return": {} }
2619 #
2620 ##
2621 { 'command': 'balloon', 'data': {'value': 'int'} }
2622
2623 ##
2624 # @Abort:
2625 #
2626 # This action can be used to test transaction failure.
2627 #
2628 # Since: 1.6
2629 ##
2630 { 'struct': 'Abort',
2631   'data': { } }
2632
2633 ##
2634 # @ActionCompletionMode:
2635 #
2636 # An enumeration of Transactional completion modes.
2637 #
2638 # @individual: Do not attempt to cancel any other Actions if any Actions fail
2639 #              after the Transaction request succeeds. All Actions that
2640 #              can complete successfully will do so without waiting on others.
2641 #              This is the default.
2642 #
2643 # @grouped: If any Action fails after the Transaction succeeds, cancel all
2644 #           Actions. Actions do not complete until all Actions are ready to
2645 #           complete. May be rejected by Actions that do not support this
2646 #           completion mode.
2647 #
2648 # Since: 2.5
2649 ##
2650 { 'enum': 'ActionCompletionMode',
2651   'data': [ 'individual', 'grouped' ] }
2652
2653 ##
2654 # @TransactionAction:
2655 #
2656 # A discriminated record of operations that can be performed with
2657 # @transaction. Action @type can be:
2658 #
2659 # - @abort: since 1.6
2660 # - @block-dirty-bitmap-add: since 2.5
2661 # - @block-dirty-bitmap-clear: since 2.5
2662 # - @blockdev-backup: since 2.3
2663 # - @blockdev-snapshot: since 2.5
2664 # - @blockdev-snapshot-internal-sync: since 1.7
2665 # - @blockdev-snapshot-sync: since 1.1
2666 # - @drive-backup: since 1.6
2667 #
2668 # Since: 1.1
2669 ##
2670 { 'union': 'TransactionAction',
2671   'data': {
2672        'abort': 'Abort',
2673        'block-dirty-bitmap-add': 'BlockDirtyBitmapAdd',
2674        'block-dirty-bitmap-clear': 'BlockDirtyBitmap',
2675        'blockdev-backup': 'BlockdevBackup',
2676        'blockdev-snapshot': 'BlockdevSnapshot',
2677        'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternal',
2678        'blockdev-snapshot-sync': 'BlockdevSnapshotSync',
2679        'drive-backup': 'DriveBackup'
2680    } }
2681
2682 ##
2683 # @TransactionProperties:
2684 #
2685 # Optional arguments to modify the behavior of a Transaction.
2686 #
2687 # @completion-mode: Controls how jobs launched asynchronously by
2688 #                   Actions will complete or fail as a group.
2689 #                   See @ActionCompletionMode for details.
2690 #
2691 # Since: 2.5
2692 ##
2693 { 'struct': 'TransactionProperties',
2694   'data': {
2695        '*completion-mode': 'ActionCompletionMode'
2696   }
2697 }
2698
2699 ##
2700 # @transaction:
2701 #
2702 # Executes a number of transactionable QMP commands atomically. If any
2703 # operation fails, then the entire set of actions will be abandoned and the
2704 # appropriate error returned.
2705 #
2706 # For external snapshots, the dictionary contains the device, the file to use for
2707 # the new snapshot, and the format.  The default format, if not specified, is
2708 # qcow2.
2709 #
2710 # Each new snapshot defaults to being created by QEMU (wiping any
2711 # contents if the file already exists), but it is also possible to reuse
2712 # an externally-created file.  In the latter case, you should ensure that
2713 # the new image file has the same contents as the current one; QEMU cannot
2714 # perform any meaningful check.  Typically this is achieved by using the
2715 # current image file as the backing file for the new image.
2716 #
2717 # On failure, the original disks pre-snapshot attempt will be used.
2718 #
2719 # For internal snapshots, the dictionary contains the device and the snapshot's
2720 # name.  If an internal snapshot matching name already exists, the request will
2721 # be rejected.  Only some image formats support it, for example, qcow2, rbd,
2722 # and sheepdog.
2723 #
2724 # On failure, qemu will try delete the newly created internal snapshot in the
2725 # transaction.  When an I/O error occurs during deletion, the user needs to fix
2726 # it later with qemu-img or other command.
2727 #
2728 # @actions: List of @TransactionAction;
2729 #           information needed for the respective operations.
2730 #
2731 # @properties: structure of additional options to control the
2732 #              execution of the transaction. See @TransactionProperties
2733 #              for additional detail.
2734 #
2735 # Returns: nothing on success
2736 #
2737 #          Errors depend on the operations of the transaction
2738 #
2739 # Note: The transaction aborts on the first failure.  Therefore, there will be
2740 # information on only one failed operation returned in an error condition, and
2741 # subsequent actions will not have been attempted.
2742 #
2743 # Since: 1.1
2744 #
2745 # Example:
2746 #
2747 # -> { "execute": "transaction",
2748 #      "arguments": { "actions": [
2749 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
2750 #                                      "snapshot-file": "/some/place/my-image",
2751 #                                      "format": "qcow2" } },
2752 #          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
2753 #                                      "snapshot-file": "/some/place/my-image2",
2754 #                                      "snapshot-node-name": "node3432",
2755 #                                      "mode": "existing",
2756 #                                      "format": "qcow2" } },
2757 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
2758 #                                      "snapshot-file": "/some/place/my-image2",
2759 #                                      "mode": "existing",
2760 #                                      "format": "qcow2" } },
2761 #          { "type": "blockdev-snapshot-internal-sync", "data" : {
2762 #                                      "device": "ide-hd2",
2763 #                                      "name": "snapshot0" } } ] } }
2764 # <- { "return": {} }
2765 #
2766 ##
2767 { 'command': 'transaction',
2768   'data': { 'actions': [ 'TransactionAction' ],
2769             '*properties': 'TransactionProperties'
2770           }
2771 }
2772
2773 ##
2774 # @human-monitor-command:
2775 #
2776 # Execute a command on the human monitor and return the output.
2777 #
2778 # @command-line: the command to execute in the human monitor
2779 #
2780 # @cpu-index: The CPU to use for commands that require an implicit CPU
2781 #
2782 # Returns: the output of the command as a string
2783 #
2784 # Since: 0.14.0
2785 #
2786 # Notes: This command only exists as a stop-gap.  Its use is highly
2787 #        discouraged.  The semantics of this command are not
2788 #        guaranteed: this means that command names, arguments and
2789 #        responses can change or be removed at ANY time.  Applications
2790 #        that rely on long term stability guarantees should NOT
2791 #        use this command.
2792 #
2793 #        Known limitations:
2794 #
2795 #        * This command is stateless, this means that commands that depend
2796 #          on state information (such as getfd) might not work
2797 #
2798 #        * Commands that prompt the user for data don't currently work
2799 #
2800 # Example:
2801 #
2802 # -> { "execute": "human-monitor-command",
2803 #      "arguments": { "command-line": "info kvm" } }
2804 # <- { "return": "kvm support: enabled\r\n" }
2805 #
2806 ##
2807 { 'command': 'human-monitor-command',
2808   'data': {'command-line': 'str', '*cpu-index': 'int'},
2809   'returns': 'str' }
2810
2811 ##
2812 # @migrate_cancel:
2813 #
2814 # Cancel the current executing migration process.
2815 #
2816 # Returns: nothing on success
2817 #
2818 # Notes: This command succeeds even if there is no migration process running.
2819 #
2820 # Since: 0.14.0
2821 #
2822 # Example:
2823 #
2824 # -> { "execute": "migrate_cancel" }
2825 # <- { "return": {} }
2826 #
2827 ##
2828 { 'command': 'migrate_cancel' }
2829
2830 ##
2831 # @migrate_set_downtime:
2832 #
2833 # Set maximum tolerated downtime for migration.
2834 #
2835 # @value: maximum downtime in seconds
2836 #
2837 # Returns: nothing on success
2838 #
2839 # Notes: This command is deprecated in favor of 'migrate-set-parameters'
2840 #
2841 # Since: 0.14.0
2842 #
2843 # Example:
2844 #
2845 # -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
2846 # <- { "return": {} }
2847 #
2848 ##
2849 { 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
2850
2851 ##
2852 # @migrate_set_speed:
2853 #
2854 # Set maximum speed for migration.
2855 #
2856 # @value: maximum speed in bytes per second.
2857 #
2858 # Returns: nothing on success
2859 #
2860 # Notes: This command is deprecated in favor of 'migrate-set-parameters'
2861 #
2862 # Since: 0.14.0
2863 #
2864 # Example:
2865 #
2866 # -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
2867 # <- { "return": {} }
2868 #
2869 ##
2870 { 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
2871
2872 ##
2873 # @migrate-set-cache-size:
2874 #
2875 # Set cache size to be used by XBZRLE migration
2876 #
2877 # @value: cache size in bytes
2878 #
2879 # The size will be rounded down to the nearest power of 2.
2880 # The cache size can be modified before and during ongoing migration
2881 #
2882 # Returns: nothing on success
2883 #
2884 # Since: 1.2
2885 #
2886 # Example:
2887 #
2888 # -> { "execute": "migrate-set-cache-size",
2889 #      "arguments": { "value": 536870912 } }
2890 # <- { "return": {} }
2891 #
2892 ##
2893 { 'command': 'migrate-set-cache-size', 'data': {'value': 'int'} }
2894
2895 ##
2896 # @query-migrate-cache-size:
2897 #
2898 # Query migration XBZRLE cache size
2899 #
2900 # Returns: XBZRLE cache size in bytes
2901 #
2902 # Since: 1.2
2903 #
2904 # Example:
2905 #
2906 # -> { "execute": "query-migrate-cache-size" }
2907 # <- { "return": 67108864 }
2908 #
2909 ##
2910 { 'command': 'query-migrate-cache-size', 'returns': 'int' }
2911
2912 ##
2913 # @ObjectPropertyInfo:
2914 #
2915 # @name: the name of the property
2916 #
2917 # @type: the type of the property.  This will typically come in one of four
2918 #        forms:
2919 #
2920 #        1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
2921 #           These types are mapped to the appropriate JSON type.
2922 #
2923 #        2) A child type in the form 'child<subtype>' where subtype is a qdev
2924 #           device type name.  Child properties create the composition tree.
2925 #
2926 #        3) A link type in the form 'link<subtype>' where subtype is a qdev
2927 #           device type name.  Link properties form the device model graph.
2928 #
2929 # Since: 1.2
2930 ##
2931 { 'struct': 'ObjectPropertyInfo',
2932   'data': { 'name': 'str', 'type': 'str' } }
2933
2934 ##
2935 # @qom-list:
2936 #
2937 # This command will list any properties of a object given a path in the object
2938 # model.
2939 #
2940 # @path: the path within the object model.  See @qom-get for a description of
2941 #        this parameter.
2942 #
2943 # Returns: a list of @ObjectPropertyInfo that describe the properties of the
2944 #          object.
2945 #
2946 # Since: 1.2
2947 ##
2948 { 'command': 'qom-list',
2949   'data': { 'path': 'str' },
2950   'returns': [ 'ObjectPropertyInfo' ] }
2951
2952 ##
2953 # @qom-get:
2954 #
2955 # This command will get a property from a object model path and return the
2956 # value.
2957 #
2958 # @path: The path within the object model.  There are two forms of supported
2959 #        paths--absolute and partial paths.
2960 #
2961 #        Absolute paths are derived from the root object and can follow child<>
2962 #        or link<> properties.  Since they can follow link<> properties, they
2963 #        can be arbitrarily long.  Absolute paths look like absolute filenames
2964 #        and are prefixed  with a leading slash.
2965 #
2966 #        Partial paths look like relative filenames.  They do not begin
2967 #        with a prefix.  The matching rules for partial paths are subtle but
2968 #        designed to make specifying objects easy.  At each level of the
2969 #        composition tree, the partial path is matched as an absolute path.
2970 #        The first match is not returned.  At least two matches are searched
2971 #        for.  A successful result is only returned if only one match is
2972 #        found.  If more than one match is found, a flag is return to
2973 #        indicate that the match was ambiguous.
2974 #
2975 # @property: The property name to read
2976 #
2977 # Returns: The property value.  The type depends on the property
2978 #          type. child<> and link<> properties are returned as #str
2979 #          pathnames.  All integer property types (u8, u16, etc) are
2980 #          returned as #int.
2981 #
2982 # Since: 1.2
2983 ##
2984 { 'command': 'qom-get',
2985   'data': { 'path': 'str', 'property': 'str' },
2986   'returns': 'any' }
2987
2988 ##
2989 # @qom-set:
2990 #
2991 # This command will set a property from a object model path.
2992 #
2993 # @path: see @qom-get for a description of this parameter
2994 #
2995 # @property: the property name to set
2996 #
2997 # @value: a value who's type is appropriate for the property type.  See @qom-get
2998 #         for a description of type mapping.
2999 #
3000 # Since: 1.2
3001 ##
3002 { 'command': 'qom-set',
3003   'data': { 'path': 'str', 'property': 'str', 'value': 'any' } }
3004
3005 ##
3006 # @set_password:
3007 #
3008 # Sets the password of a remote display session.
3009 #
3010 # @protocol: `vnc' to modify the VNC server password
3011 #            `spice' to modify the Spice server password
3012 #
3013 # @password: the new password
3014 #
3015 # @connected: how to handle existing clients when changing the
3016 #                       password.  If nothing is specified, defaults to `keep'
3017 #                       `fail' to fail the command if clients are connected
3018 #                       `disconnect' to disconnect existing clients
3019 #                       `keep' to maintain existing clients
3020 #
3021 # Returns: Nothing on success
3022 #          If Spice is not enabled, DeviceNotFound
3023 #
3024 # Since: 0.14.0
3025 #
3026 # Example:
3027 #
3028 # -> { "execute": "set_password", "arguments": { "protocol": "vnc",
3029 #                                                "password": "secret" } }
3030 # <- { "return": {} }
3031 #
3032 ##
3033 { 'command': 'set_password',
3034   'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
3035
3036 ##
3037 # @expire_password:
3038 #
3039 # Expire the password of a remote display server.
3040 #
3041 # @protocol: the name of the remote display protocol `vnc' or `spice'
3042 #
3043 # @time: when to expire the password.
3044 #        `now' to expire the password immediately
3045 #        `never' to cancel password expiration
3046 #        `+INT' where INT is the number of seconds from now (integer)
3047 #        `INT' where INT is the absolute time in seconds
3048 #
3049 # Returns: Nothing on success
3050 #          If @protocol is `spice' and Spice is not active, DeviceNotFound
3051 #
3052 # Since: 0.14.0
3053 #
3054 # Notes: Time is relative to the server and currently there is no way to
3055 #        coordinate server time with client time.  It is not recommended to
3056 #        use the absolute time version of the @time parameter unless you're
3057 #        sure you are on the same machine as the QEMU instance.
3058 #
3059 # Example:
3060 #
3061 # -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
3062 #                                                   "time": "+60" } }
3063 # <- { "return": {} }
3064 #
3065 ##
3066 { 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
3067
3068 ##
3069 # @change-vnc-password:
3070 #
3071 # Change the VNC server password.
3072 #
3073 # @password:  the new password to use with VNC authentication
3074 #
3075 # Since: 1.1
3076 #
3077 # Notes:  An empty password in this command will set the password to the empty
3078 #         string.  Existing clients are unaffected by executing this command.
3079 ##
3080 { 'command': 'change-vnc-password', 'data': {'password': 'str'} }
3081
3082 ##
3083 # @change:
3084 #
3085 # This command is multiple commands multiplexed together.
3086 #
3087 # @device: This is normally the name of a block device but it may also be 'vnc'.
3088 #          when it's 'vnc', then sub command depends on @target
3089 #
3090 # @target: If @device is a block device, then this is the new filename.
3091 #          If @device is 'vnc', then if the value 'password' selects the vnc
3092 #          change password command.   Otherwise, this specifies a new server URI
3093 #          address to listen to for VNC connections.
3094 #
3095 # @arg:    If @device is a block device, then this is an optional format to open
3096 #          the device with.
3097 #          If @device is 'vnc' and @target is 'password', this is the new VNC
3098 #          password to set.  See change-vnc-password for additional notes.
3099 #
3100 # Returns: Nothing on success.
3101 #          If @device is not a valid block device, DeviceNotFound
3102 #
3103 # Notes:  This interface is deprecated, and it is strongly recommended that you
3104 #         avoid using it.  For changing block devices, use
3105 #         blockdev-change-medium; for changing VNC parameters, use
3106 #         change-vnc-password.
3107 #
3108 # Since: 0.14.0
3109 #
3110 # Example:
3111 #
3112 # 1. Change a removable medium
3113 #
3114 # -> { "execute": "change",
3115 #      "arguments": { "device": "ide1-cd0",
3116 #                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
3117 # <- { "return": {} }
3118 #
3119 # 2. Change VNC password
3120 #
3121 # -> { "execute": "change",
3122 #      "arguments": { "device": "vnc", "target": "password",
3123 #                     "arg": "foobar1" } }
3124 # <- { "return": {} }
3125 #
3126 ##
3127 { 'command': 'change',
3128   'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
3129
3130 ##
3131 # @ObjectTypeInfo:
3132 #
3133 # This structure describes a search result from @qom-list-types
3134 #
3135 # @name: the type name found in the search
3136 #
3137 # @abstract: the type is abstract and can't be directly instantiated.
3138 #            Omitted if false. (since 2.10)
3139 #
3140 # @parent: Name of parent type, if any (since 2.10)
3141 #
3142 # Since: 1.1
3143 ##
3144 { 'struct': 'ObjectTypeInfo',
3145   'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } }
3146
3147 ##
3148 # @qom-list-types:
3149 #
3150 # This command will return a list of types given search parameters
3151 #
3152 # @implements: if specified, only return types that implement this type name
3153 #
3154 # @abstract: if true, include abstract types in the results
3155 #
3156 # Returns: a list of @ObjectTypeInfo or an empty list if no results are found
3157 #
3158 # Since: 1.1
3159 ##
3160 { 'command': 'qom-list-types',
3161   'data': { '*implements': 'str', '*abstract': 'bool' },
3162   'returns': [ 'ObjectTypeInfo' ] }
3163
3164 ##
3165 # @DevicePropertyInfo:
3166 #
3167 # Information about device properties.
3168 #
3169 # @name: the name of the property
3170 # @type: the typename of the property
3171 # @description: if specified, the description of the property.
3172 #               (since 2.2)
3173 #
3174 # Since: 1.2
3175 ##
3176 { 'struct': 'DevicePropertyInfo',
3177   'data': { 'name': 'str', 'type': 'str', '*description': 'str' } }
3178
3179 ##
3180 # @device-list-properties:
3181 #
3182 # List properties associated with a device.
3183 #
3184 # @typename: the type name of a device
3185 #
3186 # Returns: a list of DevicePropertyInfo describing a devices properties
3187 #
3188 # Since: 1.2
3189 ##
3190 { 'command': 'device-list-properties',
3191   'data': { 'typename': 'str'},
3192   'returns': [ 'DevicePropertyInfo' ] }
3193
3194 ##
3195 # @migrate:
3196 #
3197 # Migrates the current running guest to another Virtual Machine.
3198 #
3199 # @uri: the Uniform Resource Identifier of the destination VM
3200 #
3201 # @blk: do block migration (full disk copy)
3202 #
3203 # @inc: incremental disk copy migration
3204 #
3205 # @detach: this argument exists only for compatibility reasons and
3206 #          is ignored by QEMU
3207 #
3208 # Returns: nothing on success
3209 #
3210 # Since: 0.14.0
3211 #
3212 # Notes:
3213 #
3214 # 1. The 'query-migrate' command should be used to check migration's progress
3215 #    and final result (this information is provided by the 'status' member)
3216 #
3217 # 2. All boolean arguments default to false
3218 #
3219 # 3. The user Monitor's "detach" argument is invalid in QMP and should not
3220 #    be used
3221 #
3222 # Example:
3223 #
3224 # -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
3225 # <- { "return": {} }
3226 #
3227 ##
3228 { 'command': 'migrate',
3229   'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', '*detach': 'bool' } }
3230
3231 ##
3232 # @migrate-incoming:
3233 #
3234 # Start an incoming migration, the qemu must have been started
3235 # with -incoming defer
3236 #
3237 # @uri: The Uniform Resource Identifier identifying the source or
3238 #       address to listen on
3239 #
3240 # Returns: nothing on success
3241 #
3242 # Since: 2.3
3243 #
3244 # Notes:
3245 #
3246 # 1. It's a bad idea to use a string for the uri, but it needs to stay
3247 #    compatible with -incoming and the format of the uri is already exposed
3248 #    above libvirt.
3249 #
3250 # 2. QEMU must be started with -incoming defer to allow migrate-incoming to
3251 #    be used.
3252 #
3253 # 3. The uri format is the same as for -incoming
3254 #
3255 # Example:
3256 #
3257 # -> { "execute": "migrate-incoming",
3258 #      "arguments": { "uri": "tcp::4446" } }
3259 # <- { "return": {} }
3260 #
3261 ##
3262 { 'command': 'migrate-incoming', 'data': {'uri': 'str' } }
3263
3264 ##
3265 # @xen-save-devices-state:
3266 #
3267 # Save the state of all devices to file. The RAM and the block devices
3268 # of the VM are not saved by this command.
3269 #
3270 # @filename: the file to save the state of the devices to as binary
3271 # data. See xen-save-devices-state.txt for a description of the binary
3272 # format.
3273 #
3274 # Returns: Nothing on success
3275 #
3276 # Since: 1.1
3277 #
3278 # Example:
3279 #
3280 # -> { "execute": "xen-save-devices-state",
3281 #      "arguments": { "filename": "/tmp/save" } }
3282 # <- { "return": {} }
3283 #
3284 ##
3285 { 'command': 'xen-save-devices-state', 'data': {'filename': 'str'} }
3286
3287 ##
3288 # @xen-set-global-dirty-log:
3289 #
3290 # Enable or disable the global dirty log mode.
3291 #
3292 # @enable: true to enable, false to disable.
3293 #
3294 # Returns: nothing
3295 #
3296 # Since: 1.3
3297 #
3298 # Example:
3299 #
3300 # -> { "execute": "xen-set-global-dirty-log",
3301 #      "arguments": { "enable": true } }
3302 # <- { "return": {} }
3303 #
3304 ##
3305 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
3306
3307 ##
3308 # @device_add:
3309 #
3310 # @driver: the name of the new device's driver
3311 #
3312 # @bus: the device's parent bus (device tree path)
3313 #
3314 # @id: the device's ID, must be unique
3315 #
3316 # Additional arguments depend on the type.
3317 #
3318 # Add a device.
3319 #
3320 # Notes:
3321 # 1. For detailed information about this command, please refer to the
3322 #    'docs/qdev-device-use.txt' file.
3323 #
3324 # 2. It's possible to list device properties by running QEMU with the
3325 #    "-device DEVICE,help" command-line argument, where DEVICE is the
3326 #    device's name
3327 #
3328 # Example:
3329 #
3330 # -> { "execute": "device_add",
3331 #      "arguments": { "driver": "e1000", "id": "net1",
3332 #                     "bus": "pci.0",
3333 #                     "mac": "52:54:00:12:34:56" } }
3334 # <- { "return": {} }
3335 #
3336 # TODO: This command effectively bypasses QAPI completely due to its
3337 # "additional arguments" business.  It shouldn't have been added to
3338 # the schema in this form.  It should be qapified properly, or
3339 # replaced by a properly qapified command.
3340 #
3341 # Since: 0.13
3342 ##
3343 { 'command': 'device_add',
3344   'data': {'driver': 'str', '*bus': 'str', '*id': 'str'},
3345   'gen': false } # so we can get the additional arguments
3346
3347 ##
3348 # @device_del:
3349 #
3350 # Remove a device from a guest
3351 #
3352 # @id: the device's ID or QOM path
3353 #
3354 # Returns: Nothing on success
3355 #          If @id is not a valid device, DeviceNotFound
3356 #
3357 # Notes: When this command completes, the device may not be removed from the
3358 #        guest.  Hot removal is an operation that requires guest cooperation.
3359 #        This command merely requests that the guest begin the hot removal
3360 #        process.  Completion of the device removal process is signaled with a
3361 #        DEVICE_DELETED event. Guest reset will automatically complete removal
3362 #        for all devices.
3363 #
3364 # Since: 0.14.0
3365 #
3366 # Example:
3367 #
3368 # -> { "execute": "device_del",
3369 #      "arguments": { "id": "net1" } }
3370 # <- { "return": {} }
3371 #
3372 # -> { "execute": "device_del",
3373 #      "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
3374 # <- { "return": {} }
3375 #
3376 ##
3377 { 'command': 'device_del', 'data': {'id': 'str'} }
3378
3379 ##
3380 # @DumpGuestMemoryFormat:
3381 #
3382 # An enumeration of guest-memory-dump's format.
3383 #
3384 # @elf: elf format
3385 #
3386 # @kdump-zlib: kdump-compressed format with zlib-compressed
3387 #
3388 # @kdump-lzo: kdump-compressed format with lzo-compressed
3389 #
3390 # @kdump-snappy: kdump-compressed format with snappy-compressed
3391 #
3392 # Since: 2.0
3393 ##
3394 { 'enum': 'DumpGuestMemoryFormat',
3395   'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy' ] }
3396
3397 ##
3398 # @dump-guest-memory:
3399 #
3400 # Dump guest's memory to vmcore. It is a synchronous operation that can take
3401 # very long depending on the amount of guest memory.
3402 #
3403 # @paging: if true, do paging to get guest's memory mapping. This allows
3404 #          using gdb to process the core file.
3405 #
3406 #          IMPORTANT: this option can make QEMU allocate several gigabytes
3407 #                     of RAM. This can happen for a large guest, or a
3408 #                     malicious guest pretending to be large.
3409 #
3410 #          Also, paging=true has the following limitations:
3411 #
3412 #             1. The guest may be in a catastrophic state or can have corrupted
3413 #                memory, which cannot be trusted
3414 #             2. The guest can be in real-mode even if paging is enabled. For
3415 #                example, the guest uses ACPI to sleep, and ACPI sleep state
3416 #                goes in real-mode
3417 #             3. Currently only supported on i386 and x86_64.
3418 #
3419 # @protocol: the filename or file descriptor of the vmcore. The supported
3420 #            protocols are:
3421 #
3422 #            1. file: the protocol starts with "file:", and the following
3423 #               string is the file's path.
3424 #            2. fd: the protocol starts with "fd:", and the following string
3425 #               is the fd's name.
3426 #
3427 # @detach: if true, QMP will return immediately rather than
3428 #          waiting for the dump to finish. The user can track progress
3429 #          using "query-dump". (since 2.6).
3430 #
3431 # @begin: if specified, the starting physical address.
3432 #
3433 # @length: if specified, the memory size, in bytes. If you don't
3434 #          want to dump all guest's memory, please specify the start @begin
3435 #          and @length
3436 #
3437 # @format: if specified, the format of guest memory dump. But non-elf
3438 #          format is conflict with paging and filter, ie. @paging, @begin and
3439 #          @length is not allowed to be specified with non-elf @format at the
3440 #          same time (since 2.0)
3441 #
3442 # Note: All boolean arguments default to false
3443 #
3444 # Returns: nothing on success
3445 #
3446 # Since: 1.2
3447 #
3448 # Example:
3449 #
3450 # -> { "execute": "dump-guest-memory",
3451 #      "arguments": { "protocol": "fd:dump" } }
3452 # <- { "return": {} }
3453 #
3454 ##
3455 { 'command': 'dump-guest-memory',
3456   'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
3457             '*begin': 'int', '*length': 'int',
3458             '*format': 'DumpGuestMemoryFormat'} }
3459
3460 ##
3461 # @DumpStatus:
3462 #
3463 # Describe the status of a long-running background guest memory dump.
3464 #
3465 # @none: no dump-guest-memory has started yet.
3466 #
3467 # @active: there is one dump running in background.
3468 #
3469 # @completed: the last dump has finished successfully.
3470 #
3471 # @failed: the last dump has failed.
3472 #
3473 # Since: 2.6
3474 ##
3475 { 'enum': 'DumpStatus',
3476   'data': [ 'none', 'active', 'completed', 'failed' ] }
3477
3478 ##
3479 # @DumpQueryResult:
3480 #
3481 # The result format for 'query-dump'.
3482 #
3483 # @status: enum of @DumpStatus, which shows current dump status
3484 #
3485 # @completed: bytes written in latest dump (uncompressed)
3486 #
3487 # @total: total bytes to be written in latest dump (uncompressed)
3488 #
3489 # Since: 2.6
3490 ##
3491 { 'struct': 'DumpQueryResult',
3492   'data': { 'status': 'DumpStatus',
3493             'completed': 'int',
3494             'total': 'int' } }
3495
3496 ##
3497 # @query-dump:
3498 #
3499 # Query latest dump status.
3500 #
3501 # Returns: A @DumpStatus object showing the dump status.
3502 #
3503 # Since: 2.6
3504 #
3505 # Example:
3506 #
3507 # -> { "execute": "query-dump" }
3508 # <- { "return": { "status": "active", "completed": 1024000,
3509 #                  "total": 2048000 } }
3510 #
3511 ##
3512 { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
3513
3514 ##
3515 # @DumpGuestMemoryCapability:
3516 #
3517 # A list of the available formats for dump-guest-memory
3518 #
3519 # Since: 2.0
3520 ##
3521 { 'struct': 'DumpGuestMemoryCapability',
3522   'data': {
3523       'formats': ['DumpGuestMemoryFormat'] } }
3524
3525 ##
3526 # @query-dump-guest-memory-capability:
3527 #
3528 # Returns the available formats for dump-guest-memory
3529 #
3530 # Returns:  A @DumpGuestMemoryCapability object listing available formats for
3531 #           dump-guest-memory
3532 #
3533 # Since: 2.0
3534 #
3535 # Example:
3536 #
3537 # -> { "execute": "query-dump-guest-memory-capability" }
3538 # <- { "return": { "formats":
3539 #                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
3540 #
3541 ##
3542 { 'command': 'query-dump-guest-memory-capability',
3543   'returns': 'DumpGuestMemoryCapability' }
3544
3545 ##
3546 # @dump-skeys:
3547 #
3548 # Dump guest's storage keys
3549 #
3550 # @filename: the path to the file to dump to
3551 #
3552 # This command is only supported on s390 architecture.
3553 #
3554 # Since: 2.5
3555 #
3556 # Example:
3557 #
3558 # -> { "execute": "dump-skeys",
3559 #      "arguments": { "filename": "/tmp/skeys" } }
3560 # <- { "return": {} }
3561 #
3562 ##
3563 { 'command': 'dump-skeys',
3564   'data': { 'filename': 'str' } }
3565
3566 ##
3567 # @netdev_add:
3568 #
3569 # Add a network backend.
3570 #
3571 # @type: the type of network backend.  Current valid values are 'user', 'tap',
3572 #        'vde', 'socket', 'dump' and 'bridge'
3573 #
3574 # @id: the name of the new network backend
3575 #
3576 # Additional arguments depend on the type.
3577 #
3578 # TODO: This command effectively bypasses QAPI completely due to its
3579 # "additional arguments" business.  It shouldn't have been added to
3580 # the schema in this form.  It should be qapified properly, or
3581 # replaced by a properly qapified command.
3582 #
3583 # Since: 0.14.0
3584 #
3585 # Returns: Nothing on success
3586 #          If @type is not a valid network backend, DeviceNotFound
3587 #
3588 # Example:
3589 #
3590 # -> { "execute": "netdev_add",
3591 #      "arguments": { "type": "user", "id": "netdev1",
3592 #                     "dnssearch": "example.org" } }
3593 # <- { "return": {} }
3594 #
3595 ##
3596 { 'command': 'netdev_add',
3597   'data': {'type': 'str', 'id': 'str'},
3598   'gen': false }                # so we can get the additional arguments
3599
3600 ##
3601 # @netdev_del:
3602 #
3603 # Remove a network backend.
3604 #
3605 # @id: the name of the network backend to remove
3606 #
3607 # Returns: Nothing on success
3608 #          If @id is not a valid network backend, DeviceNotFound
3609 #
3610 # Since: 0.14.0
3611 #
3612 # Example:
3613 #
3614 # -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
3615 # <- { "return": {} }
3616 #
3617 ##
3618 { 'command': 'netdev_del', 'data': {'id': 'str'} }
3619
3620 ##
3621 # @object-add:
3622 #
3623 # Create a QOM object.
3624 #
3625 # @qom-type: the class name for the object to be created
3626 #
3627 # @id: the name of the new object
3628 #
3629 # @props: a dictionary of properties to be passed to the backend
3630 #
3631 # Returns: Nothing on success
3632 #          Error if @qom-type is not a valid class name
3633 #
3634 # Since: 2.0
3635 #
3636 # Example:
3637 #
3638 # -> { "execute": "object-add",
3639 #      "arguments": { "qom-type": "rng-random", "id": "rng1",
3640 #                     "props": { "filename": "/dev/hwrng" } } }
3641 # <- { "return": {} }
3642 #
3643 ##
3644 { 'command': 'object-add',
3645   'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'} }
3646
3647 ##
3648 # @object-del:
3649 #
3650 # Remove a QOM object.
3651 #
3652 # @id: the name of the QOM object to remove
3653 #
3654 # Returns: Nothing on success
3655 #          Error if @id is not a valid id for a QOM object
3656 #
3657 # Since: 2.0
3658 #
3659 # Example:
3660 #
3661 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
3662 # <- { "return": {} }
3663 #
3664 ##
3665 { 'command': 'object-del', 'data': {'id': 'str'} }
3666
3667 ##
3668 # @NetdevNoneOptions:
3669 #
3670 # Use it alone to have zero network devices.
3671 #
3672 # Since: 1.2
3673 ##
3674 { 'struct': 'NetdevNoneOptions',
3675   'data': { } }
3676
3677 ##
3678 # @NetLegacyNicOptions:
3679 #
3680 # Create a new Network Interface Card.
3681 #
3682 # @netdev: id of -netdev to connect to
3683 #
3684 # @macaddr: MAC address
3685 #
3686 # @model: device model (e1000, rtl8139, virtio etc.)
3687 #
3688 # @addr: PCI device address
3689 #
3690 # @vectors: number of MSI-x vectors, 0 to disable MSI-X
3691 #
3692 # Since: 1.2
3693 ##
3694 { 'struct': 'NetLegacyNicOptions',
3695   'data': {
3696     '*netdev':  'str',
3697     '*macaddr': 'str',
3698     '*model':   'str',
3699     '*addr':    'str',
3700     '*vectors': 'uint32' } }
3701
3702 ##
3703 # @String:
3704 #
3705 # A fat type wrapping 'str', to be embedded in lists.
3706 #
3707 # Since: 1.2
3708 ##
3709 { 'struct': 'String',
3710   'data': {
3711     'str': 'str' } }
3712
3713 ##
3714 # @NetdevUserOptions:
3715 #
3716 # Use the user mode network stack which requires no administrator privilege to
3717 # run.
3718 #
3719 # @hostname: client hostname reported by the builtin DHCP server
3720 #
3721 # @restrict: isolate the guest from the host
3722 #
3723 # @ipv4: whether to support IPv4, default true for enabled
3724 #        (since 2.6)
3725 #
3726 # @ipv6: whether to support IPv6, default true for enabled
3727 #        (since 2.6)
3728 #
3729 # @ip: legacy parameter, use net= instead
3730 #
3731 # @net: IP network address that the guest will see, in the
3732 #       form addr[/netmask] The netmask is optional, and can be
3733 #       either in the form a.b.c.d or as a number of valid top-most
3734 #       bits. Default is 10.0.2.0/24.
3735 #
3736 # @host: guest-visible address of the host
3737 #
3738 # @tftp: root directory of the built-in TFTP server
3739 #
3740 # @bootfile: BOOTP filename, for use with tftp=
3741 #
3742 # @dhcpstart: the first of the 16 IPs the built-in DHCP server can
3743 #             assign
3744 #
3745 # @dns: guest-visible address of the virtual nameserver
3746 #
3747 # @dnssearch: list of DNS suffixes to search, passed as DHCP option
3748 #             to the guest
3749 #
3750 # @ipv6-prefix: IPv6 network prefix (default is fec0::) (since
3751 #               2.6). The network prefix is given in the usual
3752 #               hexadecimal IPv6 address notation.
3753 #
3754 # @ipv6-prefixlen: IPv6 network prefix length (default is 64)
3755 #                  (since 2.6)
3756 #
3757 # @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
3758 #
3759 # @ipv6-dns: guest-visible IPv6 address of the virtual
3760 #            nameserver (since 2.6)
3761 #
3762 # @smb: root directory of the built-in SMB server
3763 #
3764 # @smbserver: IP address of the built-in SMB server
3765 #
3766 # @hostfwd: redirect incoming TCP or UDP host connections to guest
3767 #           endpoints
3768 #
3769 # @guestfwd: forward guest TCP connections
3770 #
3771 # Since: 1.2
3772 ##
3773 { 'struct': 'NetdevUserOptions',
3774   'data': {
3775     '*hostname':  'str',
3776     '*restrict':  'bool',
3777     '*ipv4':      'bool',
3778     '*ipv6':      'bool',
3779     '*ip':        'str',
3780     '*net':       'str',
3781     '*host':      'str',
3782     '*tftp':      'str',
3783     '*bootfile':  'str',
3784     '*dhcpstart': 'str',
3785     '*dns':       'str',
3786     '*dnssearch': ['String'],
3787     '*ipv6-prefix':      'str',
3788     '*ipv6-prefixlen':   'int',
3789     '*ipv6-host':        'str',
3790     '*ipv6-dns':         'str',
3791     '*smb':       'str',
3792     '*smbserver': 'str',
3793     '*hostfwd':   ['String'],
3794     '*guestfwd':  ['String'] } }
3795
3796 ##
3797 # @NetdevTapOptions:
3798 #
3799 # Connect the host TAP network interface name to the VLAN.
3800 #
3801 # @ifname: interface name
3802 #
3803 # @fd: file descriptor of an already opened tap
3804 #
3805 # @fds: multiple file descriptors of already opened multiqueue capable
3806 # tap
3807 #
3808 # @script: script to initialize the interface
3809 #
3810 # @downscript: script to shut down the interface
3811 #
3812 # @br: bridge name (since 2.8)
3813 #
3814 # @helper: command to execute to configure bridge
3815 #
3816 # @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
3817 #
3818 # @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface
3819 #
3820 # @vhost: enable vhost-net network accelerator
3821 #
3822 # @vhostfd: file descriptor of an already opened vhost net device
3823 #
3824 # @vhostfds: file descriptors of multiple already opened vhost net
3825 # devices
3826 #
3827 # @vhostforce: vhost on for non-MSIX virtio guests
3828 #
3829 # @queues: number of queues to be created for multiqueue capable tap
3830 #
3831 # @poll-us: maximum number of microseconds that could
3832 # be spent on busy polling for tap (since 2.7)
3833 #
3834 # Since: 1.2
3835 ##
3836 { 'struct': 'NetdevTapOptions',
3837   'data': {
3838     '*ifname':     'str',
3839     '*fd':         'str',
3840     '*fds':        'str',
3841     '*script':     'str',
3842     '*downscript': 'str',
3843     '*br':         'str',
3844     '*helper':     'str',
3845     '*sndbuf':     'size',
3846     '*vnet_hdr':   'bool',
3847     '*vhost':      'bool',
3848     '*vhostfd':    'str',
3849     '*vhostfds':   'str',
3850     '*vhostforce': 'bool',
3851     '*queues':     'uint32',
3852     '*poll-us':    'uint32'} }
3853
3854 ##
3855 # @NetdevSocketOptions:
3856 #
3857 # Connect the VLAN to a remote VLAN in another QEMU virtual machine using a TCP
3858 # socket connection.
3859 #
3860 # @fd: file descriptor of an already opened socket
3861 #
3862 # @listen: port number, and optional hostname, to listen on
3863 #
3864 # @connect: port number, and optional hostname, to connect to
3865 #
3866 # @mcast: UDP multicast address and port number
3867 #
3868 # @localaddr: source address and port for multicast and udp packets
3869 #
3870 # @udp: UDP unicast address and port number
3871 #
3872 # Since: 1.2
3873 ##
3874 { 'struct': 'NetdevSocketOptions',
3875   'data': {
3876     '*fd':        'str',
3877     '*listen':    'str',
3878     '*connect':   'str',
3879     '*mcast':     'str',
3880     '*localaddr': 'str',
3881     '*udp':       'str' } }
3882
3883 ##
3884 # @NetdevL2TPv3Options:
3885 #
3886 # Connect the VLAN to Ethernet over L2TPv3 Static tunnel
3887 #
3888 # @src: source address
3889 #
3890 # @dst: destination address
3891 #
3892 # @srcport: source port - mandatory for udp, optional for ip
3893 #
3894 # @dstport: destination port - mandatory for udp, optional for ip
3895 #
3896 # @ipv6: force the use of ipv6
3897 #
3898 # @udp: use the udp version of l2tpv3 encapsulation
3899 #
3900 # @cookie64: use 64 bit coookies
3901 #
3902 # @counter: have sequence counter
3903 #
3904 # @pincounter: pin sequence counter to zero -
3905 #              workaround for buggy implementations or
3906 #              networks with packet reorder
3907 #
3908 # @txcookie: 32 or 64 bit transmit cookie
3909 #
3910 # @rxcookie: 32 or 64 bit receive cookie
3911 #
3912 # @txsession: 32 bit transmit session
3913 #
3914 # @rxsession: 32 bit receive session - if not specified
3915 #             set to the same value as transmit
3916 #
3917 # @offset: additional offset - allows the insertion of
3918 #          additional application-specific data before the packet payload
3919 #
3920 # Since: 2.1
3921 ##
3922 { 'struct': 'NetdevL2TPv3Options',
3923   'data': {
3924     'src':          'str',
3925     'dst':          'str',
3926     '*srcport':     'str',
3927     '*dstport':     'str',
3928     '*ipv6':        'bool',
3929     '*udp':         'bool',
3930     '*cookie64':    'bool',
3931     '*counter':     'bool',
3932     '*pincounter':  'bool',
3933     '*txcookie':    'uint64',
3934     '*rxcookie':    'uint64',
3935     'txsession':    'uint32',
3936     '*rxsession':   'uint32',
3937     '*offset':      'uint32' } }
3938
3939 ##
3940 # @NetdevVdeOptions:
3941 #
3942 # Connect the VLAN to a vde switch running on the host.
3943 #
3944 # @sock: socket path
3945 #
3946 # @port: port number
3947 #
3948 # @group: group owner of socket
3949 #
3950 # @mode: permissions for socket
3951 #
3952 # Since: 1.2
3953 ##
3954 { 'struct': 'NetdevVdeOptions',
3955   'data': {
3956     '*sock':  'str',
3957     '*port':  'uint16',
3958     '*group': 'str',
3959     '*mode':  'uint16' } }
3960
3961 ##
3962 # @NetdevDumpOptions:
3963 #
3964 # Dump VLAN network traffic to a file.
3965 #
3966 # @len: per-packet size limit (64k default). Understands [TGMKkb]
3967 # suffixes.
3968 #
3969 # @file: dump file path (default is qemu-vlan0.pcap)
3970 #
3971 # Since: 1.2
3972 ##
3973 { 'struct': 'NetdevDumpOptions',
3974   'data': {
3975     '*len':  'size',
3976     '*file': 'str' } }
3977
3978 ##
3979 # @NetdevBridgeOptions:
3980 #
3981 # Connect a host TAP network interface to a host bridge device.
3982 #
3983 # @br: bridge name
3984 #
3985 # @helper: command to execute to configure bridge
3986 #
3987 # Since: 1.2
3988 ##
3989 { 'struct': 'NetdevBridgeOptions',
3990   'data': {
3991     '*br':     'str',
3992     '*helper': 'str' } }
3993
3994 ##
3995 # @NetdevHubPortOptions:
3996 #
3997 # Connect two or more net clients through a software hub.
3998 #
3999 # @hubid: hub identifier number
4000 #
4001 # Since: 1.2
4002 ##
4003 { 'struct': 'NetdevHubPortOptions',
4004   'data': {
4005     'hubid':     'int32' } }
4006
4007 ##
4008 # @NetdevNetmapOptions:
4009 #
4010 # Connect a client to a netmap-enabled NIC or to a VALE switch port
4011 #
4012 # @ifname: Either the name of an existing network interface supported by
4013 #          netmap, or the name of a VALE port (created on the fly).
4014 #          A VALE port name is in the form 'valeXXX:YYY', where XXX and
4015 #          YYY are non-negative integers. XXX identifies a switch and
4016 #          YYY identifies a port of the switch. VALE ports having the
4017 #          same XXX are therefore connected to the same switch.
4018 #
4019 # @devname: path of the netmap device (default: '/dev/netmap').
4020 #
4021 # Since: 2.0
4022 ##
4023 { 'struct': 'NetdevNetmapOptions',
4024   'data': {
4025     'ifname':     'str',
4026     '*devname':    'str' } }
4027
4028 ##
4029 # @NetdevVhostUserOptions:
4030 #
4031 # Vhost-user network backend
4032 #
4033 # @chardev: name of a unix socket chardev
4034 #
4035 # @vhostforce: vhost on for non-MSIX virtio guests (default: false).
4036 #
4037 # @queues: number of queues to be created for multiqueue vhost-user
4038 #          (default: 1) (Since 2.5)
4039 #
4040 # Since: 2.1
4041 ##
4042 { 'struct': 'NetdevVhostUserOptions',
4043   'data': {
4044     'chardev':        'str',
4045     '*vhostforce':    'bool',
4046     '*queues':        'int' } }
4047
4048 ##
4049 # @NetClientDriver:
4050 #
4051 # Available netdev drivers.
4052 #
4053 # Since: 2.7
4054 ##
4055 { 'enum': 'NetClientDriver',
4056   'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', 'dump',
4057             'bridge', 'hubport', 'netmap', 'vhost-user' ] }
4058
4059 ##
4060 # @Netdev:
4061 #
4062 # Captures the configuration of a network device.
4063 #
4064 # @id: identifier for monitor commands.
4065 #
4066 # @type: Specify the driver used for interpreting remaining arguments.
4067 #
4068 # Since: 1.2
4069 #
4070 # 'l2tpv3' - since 2.1
4071 ##
4072 { 'union': 'Netdev',
4073   'base': { 'id': 'str', 'type': 'NetClientDriver' },
4074   'discriminator': 'type',
4075   'data': {
4076     'none':     'NetdevNoneOptions',
4077     'nic':      'NetLegacyNicOptions',
4078     'user':     'NetdevUserOptions',
4079     'tap':      'NetdevTapOptions',
4080     'l2tpv3':   'NetdevL2TPv3Options',
4081     'socket':   'NetdevSocketOptions',
4082     'vde':      'NetdevVdeOptions',
4083     'dump':     'NetdevDumpOptions',
4084     'bridge':   'NetdevBridgeOptions',
4085     'hubport':  'NetdevHubPortOptions',
4086     'netmap':   'NetdevNetmapOptions',
4087     'vhost-user': 'NetdevVhostUserOptions' } }
4088
4089 ##
4090 # @NetLegacy:
4091 #
4092 # Captures the configuration of a network device; legacy.
4093 #
4094 # @vlan: vlan number
4095 #
4096 # @id: identifier for monitor commands
4097 #
4098 # @name: identifier for monitor commands, ignored if @id is present
4099 #
4100 # @opts: device type specific properties (legacy)
4101 #
4102 # Since: 1.2
4103 ##
4104 { 'struct': 'NetLegacy',
4105   'data': {
4106     '*vlan': 'int32',
4107     '*id':   'str',
4108     '*name': 'str',
4109     'opts':  'NetLegacyOptions' } }
4110
4111 ##
4112 # @NetLegacyOptionsType:
4113 #
4114 # Since: 1.2
4115 ##
4116 { 'enum': 'NetLegacyOptionsType',
4117   'data': ['none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
4118            'dump', 'bridge', 'netmap', 'vhost-user'] }
4119
4120 ##
4121 # @NetLegacyOptions:
4122 #
4123 # Like Netdev, but for use only by the legacy command line options
4124 #
4125 # Since: 1.2
4126 ##
4127 { 'union': 'NetLegacyOptions',
4128   'base': { 'type': 'NetLegacyOptionsType' },
4129   'discriminator': 'type',
4130   'data': {
4131     'none':     'NetdevNoneOptions',
4132     'nic':      'NetLegacyNicOptions',
4133     'user':     'NetdevUserOptions',
4134     'tap':      'NetdevTapOptions',
4135     'l2tpv3':   'NetdevL2TPv3Options',
4136     'socket':   'NetdevSocketOptions',
4137     'vde':      'NetdevVdeOptions',
4138     'dump':     'NetdevDumpOptions',
4139     'bridge':   'NetdevBridgeOptions',
4140     'netmap':   'NetdevNetmapOptions',
4141     'vhost-user': 'NetdevVhostUserOptions' } }
4142
4143 ##
4144 # @NetFilterDirection:
4145 #
4146 # Indicates whether a netfilter is attached to a netdev's transmit queue or
4147 # receive queue or both.
4148 #
4149 # @all: the filter is attached both to the receive and the transmit
4150 #       queue of the netdev (default).
4151 #
4152 # @rx: the filter is attached to the receive queue of the netdev,
4153 #      where it will receive packets sent to the netdev.
4154 #
4155 # @tx: the filter is attached to the transmit queue of the netdev,
4156 #      where it will receive packets sent by the netdev.
4157 #
4158 # Since: 2.5
4159 ##
4160 { 'enum': 'NetFilterDirection',
4161   'data': [ 'all', 'rx', 'tx' ] }
4162
4163 ##
4164 # @InetSocketAddressBase:
4165 #
4166 # @host: host part of the address
4167 # @port: port part of the address
4168 ##
4169 { 'struct': 'InetSocketAddressBase',
4170   'data': {
4171     'host': 'str',
4172     'port': 'str' } }
4173
4174 ##
4175 # @InetSocketAddress:
4176 #
4177 # Captures a socket address or address range in the Internet namespace.
4178 #
4179 # @numeric: true if the host/port are guaranteed to be numeric,
4180 #           false if name resolution should be attempted. Defaults to false.
4181 #           (Since 2.9)
4182 #
4183 # @to: If present, this is range of possible addresses, with port
4184 #      between @port and @to.
4185 #
4186 # @ipv4: whether to accept IPv4 addresses, default try both IPv4 and IPv6
4187 #
4188 # @ipv6: whether to accept IPv6 addresses, default try both IPv4 and IPv6
4189 #
4190 # Since: 1.3
4191 ##
4192 { 'struct': 'InetSocketAddress',
4193   'base': 'InetSocketAddressBase',
4194   'data': {
4195     '*numeric':  'bool',
4196     '*to': 'uint16',
4197     '*ipv4': 'bool',
4198     '*ipv6': 'bool' } }
4199
4200 ##
4201 # @UnixSocketAddress:
4202 #
4203 # Captures a socket address in the local ("Unix socket") namespace.
4204 #
4205 # @path: filesystem path to use
4206 #
4207 # Since: 1.3
4208 ##
4209 { 'struct': 'UnixSocketAddress',
4210   'data': {
4211     'path': 'str' } }
4212
4213 ##
4214 # @VsockSocketAddress:
4215 #
4216 # Captures a socket address in the vsock namespace.
4217 #
4218 # @cid: unique host identifier
4219 # @port: port
4220 #
4221 # Note: string types are used to allow for possible future hostname or
4222 # service resolution support.
4223 #
4224 # Since: 2.8
4225 ##
4226 { 'struct': 'VsockSocketAddress',
4227   'data': {
4228     'cid': 'str',
4229     'port': 'str' } }
4230
4231 ##
4232 # @SocketAddressLegacy:
4233 #
4234 # Captures the address of a socket, which could also be a named file descriptor
4235 #
4236 # Note: This type is deprecated in favor of SocketAddress.  The
4237 # difference between SocketAddressLegacy and SocketAddress is that the
4238 # latter is a flat union rather than a simple union. Flat is nicer
4239 # because it avoids nesting on the wire, i.e. that form has fewer {}.
4240
4241 #
4242 # Since: 1.3
4243 ##
4244 { 'union': 'SocketAddressLegacy',
4245   'data': {
4246     'inet': 'InetSocketAddress',
4247     'unix': 'UnixSocketAddress',
4248     'vsock': 'VsockSocketAddress',
4249     'fd': 'String' } }
4250
4251 ##
4252 # @SocketAddressType:
4253 #
4254 # Available SocketAddress types
4255 #
4256 # @inet:  Internet address
4257 #
4258 # @unix:  Unix domain socket
4259 #
4260 # Since: 2.9
4261 ##
4262 { 'enum': 'SocketAddressType',
4263   'data': [ 'inet', 'unix', 'vsock', 'fd' ] }
4264
4265 ##
4266 # @SocketAddress:
4267 #
4268 # Captures the address of a socket, which could also be a named file
4269 # descriptor
4270 #
4271 # @type:       Transport type
4272 #
4273 # Since: 2.9
4274 ##
4275 { 'union': 'SocketAddress',
4276   'base': { 'type': 'SocketAddressType' },
4277   'discriminator': 'type',
4278   'data': { 'inet': 'InetSocketAddress',
4279             'unix': 'UnixSocketAddress',
4280             'vsock': 'VsockSocketAddress',
4281             'fd': 'String' } }
4282
4283 ##
4284 # @getfd:
4285 #
4286 # Receive a file descriptor via SCM rights and assign it a name
4287 #
4288 # @fdname: file descriptor name
4289 #
4290 # Returns: Nothing on success
4291 #
4292 # Since: 0.14.0
4293 #
4294 # Notes: If @fdname already exists, the file descriptor assigned to
4295 #        it will be closed and replaced by the received file
4296 #        descriptor.
4297 #
4298 #        The 'closefd' command can be used to explicitly close the
4299 #        file descriptor when it is no longer needed.
4300 #
4301 # Example:
4302 #
4303 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
4304 # <- { "return": {} }
4305 #
4306 ##
4307 { 'command': 'getfd', 'data': {'fdname': 'str'} }
4308
4309 ##
4310 # @closefd:
4311 #
4312 # Close a file descriptor previously passed via SCM rights
4313 #
4314 # @fdname: file descriptor name
4315 #
4316 # Returns: Nothing on success
4317 #
4318 # Since: 0.14.0
4319 #
4320 # Example:
4321 #
4322 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
4323 # <- { "return": {} }
4324 #
4325 ##
4326 { 'command': 'closefd', 'data': {'fdname': 'str'} }
4327
4328 ##
4329 # @MachineInfo:
4330 #
4331 # Information describing a machine.
4332 #
4333 # @name: the name of the machine
4334 #
4335 # @alias: an alias for the machine name
4336 #
4337 # @is-default: whether the machine is default
4338 #
4339 # @cpu-max: maximum number of CPUs supported by the machine type
4340 #           (since 1.5.0)
4341 #
4342 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
4343 #
4344 # Since: 1.2.0
4345 ##
4346 { 'struct': 'MachineInfo',
4347   'data': { 'name': 'str', '*alias': 'str',
4348             '*is-default': 'bool', 'cpu-max': 'int',
4349             'hotpluggable-cpus': 'bool'} }
4350
4351 ##
4352 # @query-machines:
4353 #
4354 # Return a list of supported machines
4355 #
4356 # Returns: a list of MachineInfo
4357 #
4358 # Since: 1.2.0
4359 ##
4360 { 'command': 'query-machines', 'returns': ['MachineInfo'] }
4361
4362 ##
4363 # @CpuDefinitionInfo:
4364 #
4365 # Virtual CPU definition.
4366 #
4367 # @name: the name of the CPU definition
4368 #
4369 # @migration-safe: whether a CPU definition can be safely used for
4370 #                  migration in combination with a QEMU compatibility machine
4371 #                  when migrating between different QMU versions and between
4372 #                  hosts with different sets of (hardware or software)
4373 #                  capabilities. If not provided, information is not available
4374 #                  and callers should not assume the CPU definition to be
4375 #                  migration-safe. (since 2.8)
4376 #
4377 # @static: whether a CPU definition is static and will not change depending on
4378 #          QEMU version, machine type, machine options and accelerator options.
4379 #          A static model is always migration-safe. (since 2.8)
4380 #
4381 # @unavailable-features: List of properties that prevent
4382 #                        the CPU model from running in the current
4383 #                        host. (since 2.8)
4384 # @typename: Type name that can be used as argument to @device-list-properties,
4385 #            to introspect properties configurable using -cpu or -global.
4386 #            (since 2.9)
4387 #
4388 # @unavailable-features is a list of QOM property names that
4389 # represent CPU model attributes that prevent the CPU from running.
4390 # If the QOM property is read-only, that means there's no known
4391 # way to make the CPU model run in the current host. Implementations
4392 # that choose not to provide specific information return the
4393 # property name "type".
4394 # If the property is read-write, it means that it MAY be possible
4395 # to run the CPU model in the current host if that property is
4396 # changed. Management software can use it as hints to suggest or
4397 # choose an alternative for the user, or just to generate meaningful
4398 # error messages explaining why the CPU model can't be used.
4399 # If @unavailable-features is an empty list, the CPU model is
4400 # runnable using the current host and machine-type.
4401 # If @unavailable-features is not present, runnability
4402 # information for the CPU is not available.
4403 #
4404 # Since: 1.2.0
4405 ##
4406 { 'struct': 'CpuDefinitionInfo',
4407   'data': { 'name': 'str', '*migration-safe': 'bool', 'static': 'bool',
4408             '*unavailable-features': [ 'str' ], 'typename': 'str' } }
4409
4410 ##
4411 # @query-cpu-definitions:
4412 #
4413 # Return a list of supported virtual CPU definitions
4414 #
4415 # Returns: a list of CpuDefInfo
4416 #
4417 # Since: 1.2.0
4418 ##
4419 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }
4420
4421 ##
4422 # @CpuModelInfo:
4423 #
4424 # Virtual CPU model.
4425 #
4426 # A CPU model consists of the name of a CPU definition, to which
4427 # delta changes are applied (e.g. features added/removed). Most magic values
4428 # that an architecture might require should be hidden behind the name.
4429 # However, if required, architectures can expose relevant properties.
4430 #
4431 # @name: the name of the CPU definition the model is based on
4432 # @props: a dictionary of QOM properties to be applied
4433 #
4434 # Since: 2.8.0
4435 ##
4436 { 'struct': 'CpuModelInfo',
4437   'data': { 'name': 'str',
4438             '*props': 'any' } }
4439
4440 ##
4441 # @CpuModelExpansionType:
4442 #
4443 # An enumeration of CPU model expansion types.
4444 #
4445 # @static: Expand to a static CPU model, a combination of a static base
4446 #          model name and property delta changes. As the static base model will
4447 #          never change, the expanded CPU model will be the same, independant of
4448 #          independent of QEMU version, machine type, machine options, and
4449 #          accelerator options. Therefore, the resulting model can be used by
4450 #          tooling without having to specify a compatibility machine - e.g. when
4451 #          displaying the "host" model. static CPU models are migration-safe.
4452 #
4453 # @full: Expand all properties. The produced model is not guaranteed to be
4454 #        migration-safe, but allows tooling to get an insight and work with
4455 #        model details.
4456 #
4457 # Note: When a non-migration-safe CPU model is expanded in static mode, some
4458 # features enabled by the CPU model may be omitted, because they can't be
4459 # implemented by a static CPU model definition (e.g. cache info passthrough and
4460 # PMU passthrough in x86). If you need an accurate representation of the
4461 # features enabled by a non-migration-safe CPU model, use @full. If you need a
4462 # static representation that will keep ABI compatibility even when changing QEMU
4463 # version or machine-type, use @static (but keep in mind that some features may
4464 # be omitted).
4465 #
4466 # Since: 2.8.0
4467 ##
4468 { 'enum': 'CpuModelExpansionType',
4469   'data': [ 'static', 'full' ] }
4470
4471
4472 ##
4473 # @CpuModelExpansionInfo:
4474 #
4475 # The result of a cpu model expansion.
4476 #
4477 # @model: the expanded CpuModelInfo.
4478 #
4479 # Since: 2.8.0
4480 ##
4481 { 'struct': 'CpuModelExpansionInfo',
4482   'data': { 'model': 'CpuModelInfo' } }
4483
4484
4485 ##
4486 # @query-cpu-model-expansion:
4487 #
4488 # Expands a given CPU model (or a combination of CPU model + additional options)
4489 # to different granularities, allowing tooling to get an understanding what a
4490 # specific CPU model looks like in QEMU under a certain configuration.
4491 #
4492 # This interface can be used to query the "host" CPU model.
4493 #
4494 # The data returned by this command may be affected by:
4495 #
4496 # * QEMU version: CPU models may look different depending on the QEMU version.
4497 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
4498 # * machine-type: CPU model  may look different depending on the machine-type.
4499 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
4500 # * machine options (including accelerator): in some architectures, CPU models
4501 #   may look different depending on machine and accelerator options. (Except for
4502 #   CPU models reported as "static" in query-cpu-definitions.)
4503 # * "-cpu" arguments and global properties: arguments to the -cpu option and
4504 #   global properties may affect expansion of CPU models. Using
4505 #   query-cpu-model-expansion while using these is not advised.
4506 #
4507 # Some architectures may not support all expansion types. s390x supports
4508 # "full" and "static".
4509 #
4510 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
4511 #          not supported, if the model cannot be expanded, if the model contains
4512 #          an unknown CPU definition name, unknown properties or properties
4513 #          with a wrong type. Also returns an error if an expansion type is
4514 #          not supported.
4515 #
4516 # Since: 2.8.0
4517 ##
4518 { 'command': 'query-cpu-model-expansion',
4519   'data': { 'type': 'CpuModelExpansionType',
4520             'model': 'CpuModelInfo' },
4521   'returns': 'CpuModelExpansionInfo' }
4522
4523 ##
4524 # @CpuModelCompareResult:
4525 #
4526 # An enumeration of CPU model comparation results. The result is usually
4527 # calculated using e.g. CPU features or CPU generations.
4528 #
4529 # @incompatible: If model A is incompatible to model B, model A is not
4530 #                guaranteed to run where model B runs and the other way around.
4531 #
4532 # @identical: If model A is identical to model B, model A is guaranteed to run
4533 #             where model B runs and the other way around.
4534 #
4535 # @superset: If model A is a superset of model B, model B is guaranteed to run
4536 #            where model A runs. There are no guarantees about the other way.
4537 #
4538 # @subset: If model A is a subset of model B, model A is guaranteed to run
4539 #          where model B runs. There are no guarantees about the other way.
4540 #
4541 # Since: 2.8.0
4542 ##
4543 { 'enum': 'CpuModelCompareResult',
4544   'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
4545
4546 ##
4547 # @CpuModelCompareInfo:
4548 #
4549 # The result of a CPU model comparison.
4550 #
4551 # @result: The result of the compare operation.
4552 # @responsible-properties: List of properties that led to the comparison result
4553 #                          not being identical.
4554 #
4555 # @responsible-properties is a list of QOM property names that led to
4556 # both CPUs not being detected as identical. For identical models, this
4557 # list is empty.
4558 # If a QOM property is read-only, that means there's no known way to make the
4559 # CPU models identical. If the special property name "type" is included, the
4560 # models are by definition not identical and cannot be made identical.
4561 #
4562 # Since: 2.8.0
4563 ##
4564 { 'struct': 'CpuModelCompareInfo',
4565   'data': {'result': 'CpuModelCompareResult',
4566            'responsible-properties': ['str']
4567           }
4568 }
4569
4570 ##
4571 # @query-cpu-model-comparison:
4572 #
4573 # Compares two CPU models, returning how they compare in a specific
4574 # configuration. The results indicates how both models compare regarding
4575 # runnability. This result can be used by tooling to make decisions if a
4576 # certain CPU model will run in a certain configuration or if a compatible
4577 # CPU model has to be created by baselining.
4578 #
4579 # Usually, a CPU model is compared against the maximum possible CPU model
4580 # of a certain configuration (e.g. the "host" model for KVM). If that CPU
4581 # model is identical or a subset, it will run in that configuration.
4582 #
4583 # The result returned by this command may be affected by:
4584 #
4585 # * QEMU version: CPU models may look different depending on the QEMU version.
4586 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
4587 # * machine-type: CPU model may look different depending on the machine-type.
4588 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
4589 # * machine options (including accelerator): in some architectures, CPU models
4590 #   may look different depending on machine and accelerator options. (Except for
4591 #   CPU models reported as "static" in query-cpu-definitions.)
4592 # * "-cpu" arguments and global properties: arguments to the -cpu option and
4593 #   global properties may affect expansion of CPU models. Using
4594 #   query-cpu-model-expansion while using these is not advised.
4595 #
4596 # Some architectures may not support comparing CPU models. s390x supports
4597 # comparing CPU models.
4598 #
4599 # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
4600 #          not supported, if a model cannot be used, if a model contains
4601 #          an unknown cpu definition name, unknown properties or properties
4602 #          with wrong types.
4603 #
4604 # Since: 2.8.0
4605 ##
4606 { 'command': 'query-cpu-model-comparison',
4607   'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
4608   'returns': 'CpuModelCompareInfo' }
4609
4610 ##
4611 # @CpuModelBaselineInfo:
4612 #
4613 # The result of a CPU model baseline.
4614 #
4615 # @model: the baselined CpuModelInfo.
4616 #
4617 # Since: 2.8.0
4618 ##
4619 { 'struct': 'CpuModelBaselineInfo',
4620   'data': { 'model': 'CpuModelInfo' } }
4621
4622 ##
4623 # @query-cpu-model-baseline:
4624 #
4625 # Baseline two CPU models, creating a compatible third model. The created
4626 # model will always be a static, migration-safe CPU model (see "static"
4627 # CPU model expansion for details).
4628 #
4629 # This interface can be used by tooling to create a compatible CPU model out
4630 # two CPU models. The created CPU model will be identical to or a subset of
4631 # both CPU models when comparing them. Therefore, the created CPU model is
4632 # guaranteed to run where the given CPU models run.
4633 #
4634 # The result returned by this command may be affected by:
4635 #
4636 # * QEMU version: CPU models may look different depending on the QEMU version.
4637 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
4638 # * machine-type: CPU model may look different depending on the machine-type.
4639 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
4640 # * machine options (including accelerator): in some architectures, CPU models
4641 #   may look different depending on machine and accelerator options. (Except for
4642 #   CPU models reported as "static" in query-cpu-definitions.)
4643 # * "-cpu" arguments and global properties: arguments to the -cpu option and
4644 #   global properties may affect expansion of CPU models. Using
4645 #   query-cpu-model-expansion while using these is not advised.
4646 #
4647 # Some architectures may not support baselining CPU models. s390x supports
4648 # baselining CPU models.
4649 #
4650 # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
4651 #          not supported, if a model cannot be used, if a model contains
4652 #          an unknown cpu definition name, unknown properties or properties
4653 #          with wrong types.
4654 #
4655 # Since: 2.8.0
4656 ##
4657 { 'command': 'query-cpu-model-baseline',
4658   'data': { 'modela': 'CpuModelInfo',
4659             'modelb': 'CpuModelInfo' },
4660   'returns': 'CpuModelBaselineInfo' }
4661
4662 ##
4663 # @AddfdInfo:
4664 #
4665 # Information about a file descriptor that was added to an fd set.
4666 #
4667 # @fdset-id: The ID of the fd set that @fd was added to.
4668 #
4669 # @fd: The file descriptor that was received via SCM rights and
4670 #      added to the fd set.
4671 #
4672 # Since: 1.2.0
4673 ##
4674 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
4675
4676 ##
4677 # @add-fd:
4678 #
4679 # Add a file descriptor, that was passed via SCM rights, to an fd set.
4680 #
4681 # @fdset-id: The ID of the fd set to add the file descriptor to.
4682 #
4683 # @opaque: A free-form string that can be used to describe the fd.
4684 #
4685 # Returns: @AddfdInfo on success
4686 #
4687 #          If file descriptor was not received, FdNotSupplied
4688 #
4689 #          If @fdset-id is a negative value, InvalidParameterValue
4690 #
4691 # Notes: The list of fd sets is shared by all monitor connections.
4692 #
4693 #        If @fdset-id is not specified, a new fd set will be created.
4694 #
4695 # Since: 1.2.0
4696 #
4697 # Example:
4698 #
4699 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
4700 # <- { "return": { "fdset-id": 1, "fd": 3 } }
4701 #
4702 ##
4703 { 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'},
4704   'returns': 'AddfdInfo' }
4705
4706 ##
4707 # @remove-fd:
4708 #
4709 # Remove a file descriptor from an fd set.
4710 #
4711 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
4712 #
4713 # @fd: The file descriptor that is to be removed.
4714 #
4715 # Returns: Nothing on success
4716 #          If @fdset-id or @fd is not found, FdNotFound
4717 #
4718 # Since: 1.2.0
4719 #
4720 # Notes: The list of fd sets is shared by all monitor connections.
4721 #
4722 #        If @fd is not specified, all file descriptors in @fdset-id
4723 #        will be removed.
4724 #
4725 # Example:
4726 #
4727 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
4728 # <- { "return": {} }
4729 #
4730 ##
4731 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
4732
4733 ##
4734 # @FdsetFdInfo:
4735 #
4736 # Information about a file descriptor that belongs to an fd set.
4737 #
4738 # @fd: The file descriptor value.
4739 #
4740 # @opaque: A free-form string that can be used to describe the fd.
4741 #
4742 # Since: 1.2.0
4743 ##
4744 { 'struct': 'FdsetFdInfo',
4745   'data': {'fd': 'int', '*opaque': 'str'} }
4746
4747 ##
4748 # @FdsetInfo:
4749 #
4750 # Information about an fd set.
4751 #
4752 # @fdset-id: The ID of the fd set.
4753 #
4754 # @fds: A list of file descriptors that belong to this fd set.
4755 #
4756 # Since: 1.2.0
4757 ##
4758 { 'struct': 'FdsetInfo',
4759   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
4760
4761 ##
4762 # @query-fdsets:
4763 #
4764 # Return information describing all fd sets.
4765 #
4766 # Returns: A list of @FdsetInfo
4767 #
4768 # Since: 1.2.0
4769 #
4770 # Note: The list of fd sets is shared by all monitor connections.
4771 #
4772 # Example:
4773 #
4774 # -> { "execute": "query-fdsets" }
4775 # <- { "return": [
4776 #        {
4777 #          "fds": [
4778 #            {
4779 #              "fd": 30,
4780 #              "opaque": "rdonly:/path/to/file"
4781 #            },
4782 #            {
4783 #              "fd": 24,
4784 #              "opaque": "rdwr:/path/to/file"
4785 #            }
4786 #          ],
4787 #          "fdset-id": 1
4788 #        },
4789 #        {
4790 #          "fds": [
4791 #            {
4792 #              "fd": 28
4793 #            },
4794 #            {
4795 #              "fd": 29
4796 #            }
4797 #          ],
4798 #          "fdset-id": 0
4799 #        }
4800 #      ]
4801 #    }
4802 #
4803 ##
4804 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
4805
4806 ##
4807 # @TargetInfo:
4808 #
4809 # Information describing the QEMU target.
4810 #
4811 # @arch: the target architecture (eg "x86_64", "i386", etc)
4812 #
4813 # Since: 1.2.0
4814 ##
4815 { 'struct': 'TargetInfo',
4816   'data': { 'arch': 'str' } }
4817
4818 ##
4819 # @query-target:
4820 #
4821 # Return information about the target for this QEMU
4822 #
4823 # Returns: TargetInfo
4824 #
4825 # Since: 1.2.0
4826 ##
4827 { 'command': 'query-target', 'returns': 'TargetInfo' }
4828
4829 ##
4830 # @QKeyCode:
4831 #
4832 # An enumeration of key name.
4833 #
4834 # This is used by the @send-key command.
4835 #
4836 # @unmapped: since 2.0
4837 # @pause: since 2.0
4838 # @ro: since 2.4
4839 # @kp_comma: since 2.4
4840 # @kp_equals: since 2.6
4841 # @power: since 2.6
4842 # @hiragana: since 2.9
4843 # @henkan: since 2.9
4844 # @yen: since 2.9
4845 #
4846 # @sleep: since 2.10
4847 # @wake: since 2.10
4848 # @audionext: since 2.10
4849 # @audioprev: since 2.10
4850 # @audiostop: since 2.10
4851 # @audioplay: since 2.10
4852 # @audiomute: since 2.10
4853 # @volumeup: since 2.10
4854 # @volumedown: since 2.10
4855 # @mediaselect: since 2.10
4856 # @mail: since 2.10
4857 # @calculator: since 2.10
4858 # @computer: since 2.10
4859 # @ac_home: since 2.10
4860 # @ac_back: since 2.10
4861 # @ac_forward: since 2.10
4862 # @ac_refresh: since 2.10
4863 # @ac_bookmarks: since 2.10
4864 # altgr, altgr_r: dropped in 2.10
4865 #
4866 # Since: 1.3.0
4867 #
4868 ##
4869 { 'enum': 'QKeyCode',
4870   'data': [ 'unmapped',
4871             'shift', 'shift_r', 'alt', 'alt_r', 'ctrl',
4872             'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
4873             '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
4874             'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
4875             'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
4876             'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
4877             'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
4878             'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
4879             'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
4880             'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
4881             'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
4882             'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
4883             'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
4884             'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
4885             'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause',
4886             'ro', 'hiragana', 'henkan', 'yen',
4887             'kp_comma', 'kp_equals', 'power', 'sleep', 'wake',
4888             'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute',
4889             'volumeup', 'volumedown', 'mediaselect',
4890             'mail', 'calculator', 'computer',
4891             'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks' ] }
4892
4893 ##
4894 # @KeyValue:
4895 #
4896 # Represents a keyboard key.
4897 #
4898 # Since: 1.3.0
4899 ##
4900 { 'union': 'KeyValue',
4901   'data': {
4902     'number': 'int',
4903     'qcode': 'QKeyCode' } }
4904
4905 ##
4906 # @send-key:
4907 #
4908 # Send keys to guest.
4909 #
4910 # @keys: An array of @KeyValue elements. All @KeyValues in this array are
4911 #        simultaneously sent to the guest. A @KeyValue.number value is sent
4912 #        directly to the guest, while @KeyValue.qcode must be a valid
4913 #        @QKeyCode value
4914 #
4915 # @hold-time: time to delay key up events, milliseconds. Defaults
4916 #             to 100
4917 #
4918 # Returns: Nothing on success
4919 #          If key is unknown or redundant, InvalidParameter
4920 #
4921 # Since: 1.3.0
4922 #
4923 # Example:
4924 #
4925 # -> { "execute": "send-key",
4926 #      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
4927 #                               { "type": "qcode", "data": "alt" },
4928 #                               { "type": "qcode", "data": "delete" } ] } }
4929 # <- { "return": {} }
4930 #
4931 ##
4932 { 'command': 'send-key',
4933   'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
4934
4935 ##
4936 # @screendump:
4937 #
4938 # Write a PPM of the VGA screen to a file.
4939 #
4940 # @filename: the path of a new PPM file to store the image
4941 #
4942 # Returns: Nothing on success
4943 #
4944 # Since: 0.14.0
4945 #
4946 # Example:
4947 #
4948 # -> { "execute": "screendump",
4949 #      "arguments": { "filename": "/tmp/image" } }
4950 # <- { "return": {} }
4951 #
4952 ##
4953 { 'command': 'screendump', 'data': {'filename': 'str'} }
4954
4955
4956 ##
4957 # @ChardevCommon:
4958 #
4959 # Configuration shared across all chardev backends
4960 #
4961 # @logfile: The name of a logfile to save output
4962 # @logappend: true to append instead of truncate
4963 #             (default to false to truncate)
4964 #
4965 # Since: 2.6
4966 ##
4967 { 'struct': 'ChardevCommon', 'data': { '*logfile': 'str',
4968                                        '*logappend': 'bool' } }
4969
4970 ##
4971 # @ChardevFile:
4972 #
4973 # Configuration info for file chardevs.
4974 #
4975 # @in:  The name of the input file
4976 # @out: The name of the output file
4977 # @append: Open the file in append mode (default false to
4978 #          truncate) (Since 2.6)
4979 #
4980 # Since: 1.4
4981 ##
4982 { 'struct': 'ChardevFile', 'data': { '*in' : 'str',
4983                                    'out' : 'str',
4984                                    '*append': 'bool' },
4985   'base': 'ChardevCommon' }
4986
4987 ##
4988 # @ChardevHostdev:
4989 #
4990 # Configuration info for device and pipe chardevs.
4991 #
4992 # @device: The name of the special file for the device,
4993 #          i.e. /dev/ttyS0 on Unix or COM1: on Windows
4994 #
4995 # Since: 1.4
4996 ##
4997 { 'struct': 'ChardevHostdev', 'data': { 'device' : 'str' },
4998   'base': 'ChardevCommon' }
4999
5000 ##
5001 # @ChardevSocket:
5002 #
5003 # Configuration info for (stream) socket chardevs.
5004 #
5005 # @addr: socket address to listen on (server=true)
5006 #        or connect to (server=false)
5007 # @tls-creds: the ID of the TLS credentials object (since 2.6)
5008 # @server: create server socket (default: true)
5009 # @wait: wait for incoming connection on server
5010 #        sockets (default: false).
5011 # @nodelay: set TCP_NODELAY socket option (default: false)
5012 # @telnet: enable telnet protocol on server
5013 #          sockets (default: false)
5014 # @tn3270: enable tn3270 protocol on server
5015 #          sockets (default: false) (Since: 2.10)
5016 # @reconnect: For a client socket, if a socket is disconnected,
5017 #          then attempt a reconnect after the given number of seconds.
5018 #          Setting this to zero disables this function. (default: 0)
5019 #          (Since: 2.2)
5020 #
5021 # Since: 1.4
5022 ##
5023 { 'struct': 'ChardevSocket', 'data': { 'addr'       : 'SocketAddressLegacy',
5024                                      '*tls-creds'  : 'str',
5025                                      '*server'    : 'bool',
5026                                      '*wait'      : 'bool',
5027                                      '*nodelay'   : 'bool',
5028                                      '*telnet'    : 'bool',
5029                                      '*tn3270'    : 'bool',
5030                                      '*reconnect' : 'int' },
5031   'base': 'ChardevCommon' }
5032
5033 ##
5034 # @ChardevUdp:
5035 #
5036 # Configuration info for datagram socket chardevs.
5037 #
5038 # @remote: remote address
5039 # @local: local address
5040 #
5041 # Since: 1.5
5042 ##
5043 { 'struct': 'ChardevUdp', 'data': { 'remote' : 'SocketAddressLegacy',
5044                                   '*local' : 'SocketAddressLegacy' },
5045   'base': 'ChardevCommon' }
5046
5047 ##
5048 # @ChardevMux:
5049 #
5050 # Configuration info for mux chardevs.
5051 #
5052 # @chardev: name of the base chardev.
5053 #
5054 # Since: 1.5
5055 ##
5056 { 'struct': 'ChardevMux', 'data': { 'chardev' : 'str' },
5057   'base': 'ChardevCommon' }
5058
5059 ##
5060 # @ChardevStdio:
5061 #
5062 # Configuration info for stdio chardevs.
5063 #
5064 # @signal: Allow signals (such as SIGINT triggered by ^C)
5065 #          be delivered to qemu.  Default: true in -nographic mode,
5066 #          false otherwise.
5067 #
5068 # Since: 1.5
5069 ##
5070 { 'struct': 'ChardevStdio', 'data': { '*signal' : 'bool' },
5071   'base': 'ChardevCommon' }
5072
5073
5074 ##
5075 # @ChardevSpiceChannel:
5076 #
5077 # Configuration info for spice vm channel chardevs.
5078 #
5079 # @type: kind of channel (for example vdagent).
5080 #
5081 # Since: 1.5
5082 ##
5083 { 'struct': 'ChardevSpiceChannel', 'data': { 'type'  : 'str' },
5084   'base': 'ChardevCommon' }
5085
5086 ##
5087 # @ChardevSpicePort:
5088 #
5089 # Configuration info for spice port chardevs.
5090 #
5091 # @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
5092 #
5093 # Since: 1.5
5094 ##
5095 { 'struct': 'ChardevSpicePort', 'data': { 'fqdn'  : 'str' },
5096   'base': 'ChardevCommon' }
5097
5098 ##
5099 # @ChardevVC:
5100 #
5101 # Configuration info for virtual console chardevs.
5102 #
5103 # @width:  console width,  in pixels
5104 # @height: console height, in pixels
5105 # @cols:   console width,  in chars
5106 # @rows:   console height, in chars
5107 #
5108 # Since: 1.5
5109 ##
5110 { 'struct': 'ChardevVC', 'data': { '*width'  : 'int',
5111                                  '*height' : 'int',
5112                                  '*cols'   : 'int',
5113                                  '*rows'   : 'int' },
5114   'base': 'ChardevCommon' }
5115
5116 ##
5117 # @ChardevRingbuf:
5118 #
5119 # Configuration info for ring buffer chardevs.
5120 #
5121 # @size: ring buffer size, must be power of two, default is 65536
5122 #
5123 # Since: 1.5
5124 ##
5125 { 'struct': 'ChardevRingbuf', 'data': { '*size'  : 'int' },
5126   'base': 'ChardevCommon' }
5127
5128 ##
5129 # @ChardevBackend:
5130 #
5131 # Configuration info for the new chardev backend.
5132 #
5133 # Since: 1.4 (testdev since 2.2, wctablet since 2.9)
5134 ##
5135 { 'union': 'ChardevBackend', 'data': { 'file'   : 'ChardevFile',
5136                                        'serial' : 'ChardevHostdev',
5137                                        'parallel': 'ChardevHostdev',
5138                                        'pipe'   : 'ChardevHostdev',
5139                                        'socket' : 'ChardevSocket',
5140                                        'udp'    : 'ChardevUdp',
5141                                        'pty'    : 'ChardevCommon',
5142                                        'null'   : 'ChardevCommon',
5143                                        'mux'    : 'ChardevMux',
5144                                        'msmouse': 'ChardevCommon',
5145                                        'wctablet' : 'ChardevCommon',
5146                                        'braille': 'ChardevCommon',
5147                                        'testdev': 'ChardevCommon',
5148                                        'stdio'  : 'ChardevStdio',
5149                                        'console': 'ChardevCommon',
5150                                        'spicevmc' : 'ChardevSpiceChannel',
5151                                        'spiceport' : 'ChardevSpicePort',
5152                                        'vc'     : 'ChardevVC',
5153                                        'ringbuf': 'ChardevRingbuf',
5154                                        # next one is just for compatibility
5155                                        'memory' : 'ChardevRingbuf' } }
5156
5157 ##
5158 # @ChardevReturn:
5159 #
5160 # Return info about the chardev backend just created.
5161 #
5162 # @pty: name of the slave pseudoterminal device, present if
5163 #       and only if a chardev of type 'pty' was created
5164 #
5165 # Since: 1.4
5166 ##
5167 { 'struct' : 'ChardevReturn', 'data': { '*pty' : 'str' } }
5168
5169 ##
5170 # @chardev-add:
5171 #
5172 # Add a character device backend
5173 #
5174 # @id: the chardev's ID, must be unique
5175 # @backend: backend type and parameters
5176 #
5177 # Returns: ChardevReturn.
5178 #
5179 # Since: 1.4
5180 #
5181 # Example:
5182 #
5183 # -> { "execute" : "chardev-add",
5184 #      "arguments" : { "id" : "foo",
5185 #                      "backend" : { "type" : "null", "data" : {} } } }
5186 # <- { "return": {} }
5187 #
5188 # -> { "execute" : "chardev-add",
5189 #      "arguments" : { "id" : "bar",
5190 #                      "backend" : { "type" : "file",
5191 #                                    "data" : { "out" : "/tmp/bar.log" } } } }
5192 # <- { "return": {} }
5193 #
5194 # -> { "execute" : "chardev-add",
5195 #      "arguments" : { "id" : "baz",
5196 #                      "backend" : { "type" : "pty", "data" : {} } } }
5197 # <- { "return": { "pty" : "/dev/pty/42" } }
5198 #
5199 ##
5200 { 'command': 'chardev-add', 'data': {'id'      : 'str',
5201                                      'backend' : 'ChardevBackend' },
5202   'returns': 'ChardevReturn' }
5203
5204 ##
5205 # @chardev-change:
5206 #
5207 # Change a character device backend
5208 #
5209 # @id: the chardev's ID, must exist
5210 # @backend: new backend type and parameters
5211 #
5212 # Returns: ChardevReturn.
5213 #
5214 # Since: 2.10
5215 #
5216 # Example:
5217 #
5218 # -> { "execute" : "chardev-change",
5219 #      "arguments" : { "id" : "baz",
5220 #                      "backend" : { "type" : "pty", "data" : {} } } }
5221 # <- { "return": { "pty" : "/dev/pty/42" } }
5222 #
5223 # -> {"execute" : "chardev-change",
5224 #     "arguments" : {
5225 #         "id" : "charchannel2",
5226 #         "backend" : {
5227 #             "type" : "socket",
5228 #             "data" : {
5229 #                 "addr" : {
5230 #                     "type" : "unix" ,
5231 #                     "data" : {
5232 #                         "path" : "/tmp/charchannel2.socket"
5233 #                     }
5234 #                  },
5235 #                  "server" : true,
5236 #                  "wait" : false }}}}
5237 # <- {"return": {}}
5238 #
5239 ##
5240 { 'command': 'chardev-change', 'data': {'id'      : 'str',
5241                                         'backend' : 'ChardevBackend' },
5242   'returns': 'ChardevReturn' }
5243
5244 ##
5245 # @chardev-remove:
5246 #
5247 # Remove a character device backend
5248 #
5249 # @id: the chardev's ID, must exist and not be in use
5250 #
5251 # Returns: Nothing on success
5252 #
5253 # Since: 1.4
5254 #
5255 # Example:
5256 #
5257 # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
5258 # <- { "return": {} }
5259 #
5260 ##
5261 { 'command': 'chardev-remove', 'data': {'id': 'str'} }
5262
5263 ##
5264 # @chardev-send-break:
5265 #
5266 # Send a break to a character device
5267 #
5268 # @id: the chardev's ID, must exist
5269 #
5270 # Returns: Nothing on success
5271 #
5272 # Since: 2.10
5273 #
5274 # Example:
5275 #
5276 # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
5277 # <- { "return": {} }
5278 #
5279 ##
5280 { 'command': 'chardev-send-break', 'data': {'id': 'str'} }
5281
5282
5283 ##
5284 # @TpmModel:
5285 #
5286 # An enumeration of TPM models
5287 #
5288 # @tpm-tis: TPM TIS model
5289 #
5290 # Since: 1.5
5291 ##
5292 { 'enum': 'TpmModel', 'data': [ 'tpm-tis' ] }
5293
5294 ##
5295 # @query-tpm-models:
5296 #
5297 # Return a list of supported TPM models
5298 #
5299 # Returns: a list of TpmModel
5300 #
5301 # Since: 1.5
5302 #
5303 # Example:
5304 #
5305 # -> { "execute": "query-tpm-models" }
5306 # <- { "return": [ "tpm-tis" ] }
5307 #
5308 ##
5309 { 'command': 'query-tpm-models', 'returns': ['TpmModel'] }
5310
5311 ##
5312 # @TpmType:
5313 #
5314 # An enumeration of TPM types
5315 #
5316 # @passthrough: TPM passthrough type
5317 #
5318 # Since: 1.5
5319 ##
5320 { 'enum': 'TpmType', 'data': [ 'passthrough' ] }
5321
5322 ##
5323 # @query-tpm-types:
5324 #
5325 # Return a list of supported TPM types
5326 #
5327 # Returns: a list of TpmType
5328 #
5329 # Since: 1.5
5330 #
5331 # Example:
5332 #
5333 # -> { "execute": "query-tpm-types" }
5334 # <- { "return": [ "passthrough" ] }
5335 #
5336 ##
5337 { 'command': 'query-tpm-types', 'returns': ['TpmType'] }
5338
5339 ##
5340 # @TPMPassthroughOptions:
5341 #
5342 # Information about the TPM passthrough type
5343 #
5344 # @path: string describing the path used for accessing the TPM device
5345 #
5346 # @cancel-path: string showing the TPM's sysfs cancel file
5347 #               for cancellation of TPM commands while they are executing
5348 #
5349 # Since: 1.5
5350 ##
5351 { 'struct': 'TPMPassthroughOptions', 'data': { '*path' : 'str',
5352                                              '*cancel-path' : 'str'} }
5353
5354 ##
5355 # @TpmTypeOptions:
5356 #
5357 # A union referencing different TPM backend types' configuration options
5358 #
5359 # @type: 'passthrough' The configuration options for the TPM passthrough type
5360 #
5361 # Since: 1.5
5362 ##
5363 { 'union': 'TpmTypeOptions',
5364    'data': { 'passthrough' : 'TPMPassthroughOptions' } }
5365
5366 ##
5367 # @TPMInfo:
5368 #
5369 # Information about the TPM
5370 #
5371 # @id: The Id of the TPM
5372 #
5373 # @model: The TPM frontend model
5374 #
5375 # @options: The TPM (backend) type configuration options
5376 #
5377 # Since: 1.5
5378 ##
5379 { 'struct': 'TPMInfo',
5380   'data': {'id': 'str',
5381            'model': 'TpmModel',
5382            'options': 'TpmTypeOptions' } }
5383
5384 ##
5385 # @query-tpm:
5386 #
5387 # Return information about the TPM device
5388 #
5389 # Returns: @TPMInfo on success
5390 #
5391 # Since: 1.5
5392 #
5393 # Example:
5394 #
5395 # -> { "execute": "query-tpm" }
5396 # <- { "return":
5397 #      [
5398 #        { "model": "tpm-tis",
5399 #          "options":
5400 #            { "type": "passthrough",
5401 #              "data":
5402 #                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
5403 #                  "path": "/dev/tpm0"
5404 #                }
5405 #            },
5406 #          "id": "tpm0"
5407 #        }
5408 #      ]
5409 #    }
5410 #
5411 ##
5412 { 'command': 'query-tpm', 'returns': ['TPMInfo'] }
5413
5414 ##
5415 # @AcpiTableOptions:
5416 #
5417 # Specify an ACPI table on the command line to load.
5418 #
5419 # At most one of @file and @data can be specified. The list of files specified
5420 # by any one of them is loaded and concatenated in order. If both are omitted,
5421 # @data is implied.
5422 #
5423 # Other fields / optargs can be used to override fields of the generic ACPI
5424 # table header; refer to the ACPI specification 5.0, section 5.2.6 System
5425 # Description Table Header. If a header field is not overridden, then the
5426 # corresponding value from the concatenated blob is used (in case of @file), or
5427 # it is filled in with a hard-coded value (in case of @data).
5428 #
5429 # String fields are copied into the matching ACPI member from lowest address
5430 # upwards, and silently truncated / NUL-padded to length.
5431 #
5432 # @sig: table signature / identifier (4 bytes)
5433 #
5434 # @rev: table revision number (dependent on signature, 1 byte)
5435 #
5436 # @oem_id: OEM identifier (6 bytes)
5437 #
5438 # @oem_table_id: OEM table identifier (8 bytes)
5439 #
5440 # @oem_rev: OEM-supplied revision number (4 bytes)
5441 #
5442 # @asl_compiler_id: identifier of the utility that created the table
5443 #                   (4 bytes)
5444 #
5445 # @asl_compiler_rev: revision number of the utility that created the
5446 #                    table (4 bytes)
5447 #
5448 # @file: colon (:) separated list of pathnames to load and
5449 #        concatenate as table data. The resultant binary blob is expected to
5450 #        have an ACPI table header. At least one file is required. This field
5451 #        excludes @data.
5452 #
5453 # @data: colon (:) separated list of pathnames to load and
5454 #        concatenate as table data. The resultant binary blob must not have an
5455 #        ACPI table header. At least one file is required. This field excludes
5456 #        @file.
5457 #
5458 # Since: 1.5
5459 ##
5460 { 'struct': 'AcpiTableOptions',
5461   'data': {
5462     '*sig':               'str',
5463     '*rev':               'uint8',
5464     '*oem_id':            'str',
5465     '*oem_table_id':      'str',
5466     '*oem_rev':           'uint32',
5467     '*asl_compiler_id':   'str',
5468     '*asl_compiler_rev':  'uint32',
5469     '*file':              'str',
5470     '*data':              'str' }}
5471
5472 ##
5473 # @CommandLineParameterType:
5474 #
5475 # Possible types for an option parameter.
5476 #
5477 # @string: accepts a character string
5478 #
5479 # @boolean: accepts "on" or "off"
5480 #
5481 # @number: accepts a number
5482 #
5483 # @size: accepts a number followed by an optional suffix (K)ilo,
5484 #        (M)ega, (G)iga, (T)era
5485 #
5486 # Since: 1.5
5487 ##
5488 { 'enum': 'CommandLineParameterType',
5489   'data': ['string', 'boolean', 'number', 'size'] }
5490
5491 ##
5492 # @CommandLineParameterInfo:
5493 #
5494 # Details about a single parameter of a command line option.
5495 #
5496 # @name: parameter name
5497 #
5498 # @type: parameter @CommandLineParameterType
5499 #
5500 # @help: human readable text string, not suitable for parsing.
5501 #
5502 # @default: default value string (since 2.1)
5503 #
5504 # Since: 1.5
5505 ##
5506 { 'struct': 'CommandLineParameterInfo',
5507   'data': { 'name': 'str',
5508             'type': 'CommandLineParameterType',
5509             '*help': 'str',
5510             '*default': 'str' } }
5511
5512 ##
5513 # @CommandLineOptionInfo:
5514 #
5515 # Details about a command line option, including its list of parameter details
5516 #
5517 # @option: option name
5518 #
5519 # @parameters: an array of @CommandLineParameterInfo
5520 #
5521 # Since: 1.5
5522 ##
5523 { 'struct': 'CommandLineOptionInfo',
5524   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
5525
5526 ##
5527 # @query-command-line-options:
5528 #
5529 # Query command line option schema.
5530 #
5531 # @option: option name
5532 #
5533 # Returns: list of @CommandLineOptionInfo for all options (or for the given
5534 #          @option).  Returns an error if the given @option doesn't exist.
5535 #
5536 # Since: 1.5
5537 #
5538 # Example:
5539 #
5540 # -> { "execute": "query-command-line-options",
5541 #      "arguments": { "option": "option-rom" } }
5542 # <- { "return": [
5543 #         {
5544 #             "parameters": [
5545 #                 {
5546 #                     "name": "romfile",
5547 #                     "type": "string"
5548 #                 },
5549 #                 {
5550 #                     "name": "bootindex",
5551 #                     "type": "number"
5552 #                 }
5553 #             ],
5554 #             "option": "option-rom"
5555 #         }
5556 #      ]
5557 #    }
5558 #
5559 ##
5560 {'command': 'query-command-line-options', 'data': { '*option': 'str' },
5561  'returns': ['CommandLineOptionInfo'] }
5562
5563 ##
5564 # @X86CPURegister32:
5565 #
5566 # A X86 32-bit register
5567 #
5568 # Since: 1.5
5569 ##
5570 { 'enum': 'X86CPURegister32',
5571   'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
5572
5573 ##
5574 # @X86CPUFeatureWordInfo:
5575 #
5576 # Information about a X86 CPU feature word
5577 #
5578 # @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
5579 #
5580 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
5581 #                   feature word
5582 #
5583 # @cpuid-register: Output register containing the feature bits
5584 #
5585 # @features: value of output register, containing the feature bits
5586 #
5587 # Since: 1.5
5588 ##
5589 { 'struct': 'X86CPUFeatureWordInfo',
5590   'data': { 'cpuid-input-eax': 'int',
5591             '*cpuid-input-ecx': 'int',
5592             'cpuid-register': 'X86CPURegister32',
5593             'features': 'int' } }
5594
5595 ##
5596 # @DummyForceArrays:
5597 #
5598 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
5599 #
5600 # Since: 2.5
5601 ##
5602 { 'struct': 'DummyForceArrays',
5603   'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
5604
5605
5606 ##
5607 # @RxState:
5608 #
5609 # Packets receiving state
5610 #
5611 # @normal: filter assigned packets according to the mac-table
5612 #
5613 # @none: don't receive any assigned packet
5614 #
5615 # @all: receive all assigned packets
5616 #
5617 # Since: 1.6
5618 ##
5619 { 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }
5620
5621 ##
5622 # @RxFilterInfo:
5623 #
5624 # Rx-filter information for a NIC.
5625 #
5626 # @name: net client name
5627 #
5628 # @promiscuous: whether promiscuous mode is enabled
5629 #
5630 # @multicast: multicast receive state
5631 #
5632 # @unicast: unicast receive state
5633 #
5634 # @vlan: vlan receive state (Since 2.0)
5635 #
5636 # @broadcast-allowed: whether to receive broadcast
5637 #
5638 # @multicast-overflow: multicast table is overflowed or not
5639 #
5640 # @unicast-overflow: unicast table is overflowed or not
5641 #
5642 # @main-mac: the main macaddr string
5643 #
5644 # @vlan-table: a list of active vlan id
5645 #
5646 # @unicast-table: a list of unicast macaddr string
5647 #
5648 # @multicast-table: a list of multicast macaddr string
5649 #
5650 # Since: 1.6
5651 ##
5652 { 'struct': 'RxFilterInfo',
5653   'data': {
5654     'name':               'str',
5655     'promiscuous':        'bool',
5656     'multicast':          'RxState',
5657     'unicast':            'RxState',
5658     'vlan':               'RxState',
5659     'broadcast-allowed':  'bool',
5660     'multicast-overflow': 'bool',
5661     'unicast-overflow':   'bool',
5662     'main-mac':           'str',
5663     'vlan-table':         ['int'],
5664     'unicast-table':      ['str'],
5665     'multicast-table':    ['str'] }}
5666
5667 ##
5668 # @query-rx-filter:
5669 #
5670 # Return rx-filter information for all NICs (or for the given NIC).
5671 #
5672 # @name: net client name
5673 #
5674 # Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
5675 #          Returns an error if the given @name doesn't exist, or given
5676 #          NIC doesn't support rx-filter querying, or given net client
5677 #          isn't a NIC.
5678 #
5679 # Since: 1.6
5680 #
5681 # Example:
5682 #
5683 # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
5684 # <- { "return": [
5685 #         {
5686 #             "promiscuous": true,
5687 #             "name": "vnet0",
5688 #             "main-mac": "52:54:00:12:34:56",
5689 #             "unicast": "normal",
5690 #             "vlan": "normal",
5691 #             "vlan-table": [
5692 #                 4,
5693 #                 0
5694 #             ],
5695 #             "unicast-table": [
5696 #             ],
5697 #             "multicast": "normal",
5698 #             "multicast-overflow": false,
5699 #             "unicast-overflow": false,
5700 #             "multicast-table": [
5701 #                 "01:00:5e:00:00:01",
5702 #                 "33:33:00:00:00:01",
5703 #                 "33:33:ff:12:34:56"
5704 #             ],
5705 #             "broadcast-allowed": false
5706 #         }
5707 #       ]
5708 #    }
5709 #
5710 ##
5711 { 'command': 'query-rx-filter', 'data': { '*name': 'str' },
5712   'returns': ['RxFilterInfo'] }
5713
5714 ##
5715 # @InputButton:
5716 #
5717 # Button of a pointer input device (mouse, tablet).
5718 #
5719 # @side: front side button of a 5-button mouse (since 2.9)
5720 #
5721 # @extra: rear side button of a 5-button mouse (since 2.9)
5722 #
5723 # Since: 2.0
5724 ##
5725 { 'enum'  : 'InputButton',
5726   'data'  : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side',
5727   'extra' ] }
5728
5729 ##
5730 # @InputAxis:
5731 #
5732 # Position axis of a pointer input device (mouse, tablet).
5733 #
5734 # Since: 2.0
5735 ##
5736 { 'enum'  : 'InputAxis',
5737   'data'  : [ 'x', 'y' ] }
5738
5739 ##
5740 # @InputKeyEvent:
5741 #
5742 # Keyboard input event.
5743 #
5744 # @key:    Which key this event is for.
5745 # @down:   True for key-down and false for key-up events.
5746 #
5747 # Since: 2.0
5748 ##
5749 { 'struct'  : 'InputKeyEvent',
5750   'data'  : { 'key'     : 'KeyValue',
5751               'down'    : 'bool' } }
5752
5753 ##
5754 # @InputBtnEvent:
5755 #
5756 # Pointer button input event.
5757 #
5758 # @button: Which button this event is for.
5759 # @down:   True for key-down and false for key-up events.
5760 #
5761 # Since: 2.0<