Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20210921' into staging
[qemu.git] / qapi / machine.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
4 # This work is licensed under the terms of the GNU GPL, version 2 or later.
5 # See the COPYING file in the top-level directory.
6
7 ##
8 # = Machines
9 ##
10
11 { 'include': 'common.json' }
12
13 ##
14 # @SysEmuTarget:
15 #
16 # The comprehensive enumeration of QEMU system emulation ("softmmu")
17 # targets. Run "./configure --help" in the project root directory, and
18 # look for the \*-softmmu targets near the "--target-list" option. The
19 # individual target constants are not documented here, for the time
20 # being.
21 #
22 # @rx: since 5.0
23 # @avr: since 5.1
24 #
25 # Notes: The resulting QMP strings can be appended to the "qemu-system-"
26 #        prefix to produce the corresponding QEMU executable name. This
27 #        is true even for "qemu-system-x86_64".
28 #
29 # Since: 3.0
30 ##
31 { 'enum' : 'SysEmuTarget',
32   'data' : [ 'aarch64', 'alpha', 'arm', 'avr', 'cris', 'hppa', 'i386', 'lm32',
33              'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64',
34              'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc',
35              'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4',
36              'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
37              'x86_64', 'xtensa', 'xtensaeb' ] }
38
39 ##
40 # @CpuS390State:
41 #
42 # An enumeration of cpu states that can be assumed by a virtual
43 # S390 CPU
44 #
45 # Since: 2.12
46 ##
47 { 'enum': 'CpuS390State',
48   'prefix': 'S390_CPU_STATE',
49   'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] }
50
51 ##
52 # @CpuInfoS390:
53 #
54 # Additional information about a virtual S390 CPU
55 #
56 # @cpu-state: the virtual CPU's state
57 #
58 # Since: 2.12
59 ##
60 { 'struct': 'CpuInfoS390', 'data': { 'cpu-state': 'CpuS390State' } }
61
62 ##
63 # @CpuInfoFast:
64 #
65 # Information about a virtual CPU
66 #
67 # @cpu-index: index of the virtual CPU
68 #
69 # @qom-path: path to the CPU object in the QOM tree
70 #
71 # @thread-id: ID of the underlying host thread
72 #
73 # @props: properties describing to which node/socket/core/thread
74 #         virtual CPU belongs to, provided if supported by board
75 #
76 # @target: the QEMU system emulation target, which determines which
77 #          additional fields will be listed (since 3.0)
78 #
79 # Since: 2.12
80 #
81 ##
82 { 'union'         : 'CpuInfoFast',
83   'base'          : { 'cpu-index'    : 'int',
84                       'qom-path'     : 'str',
85                       'thread-id'    : 'int',
86                       '*props'       : 'CpuInstanceProperties',
87                       'target'       : 'SysEmuTarget' },
88   'discriminator' : 'target',
89   'data'          : { 's390x'        : 'CpuInfoS390' } }
90
91 ##
92 # @query-cpus-fast:
93 #
94 # Returns information about all virtual CPUs.
95 #
96 # Returns: list of @CpuInfoFast
97 #
98 # Since: 2.12
99 #
100 # Example:
101 #
102 # -> { "execute": "query-cpus-fast" }
103 # <- { "return": [
104 #         {
105 #             "thread-id": 25627,
106 #             "props": {
107 #                 "core-id": 0,
108 #                 "thread-id": 0,
109 #                 "socket-id": 0
110 #             },
111 #             "qom-path": "/machine/unattached/device[0]",
112 #             "arch":"x86",
113 #             "target":"x86_64",
114 #             "cpu-index": 0
115 #         },
116 #         {
117 #             "thread-id": 25628,
118 #             "props": {
119 #                 "core-id": 0,
120 #                 "thread-id": 0,
121 #                 "socket-id": 1
122 #             },
123 #             "qom-path": "/machine/unattached/device[2]",
124 #             "arch":"x86",
125 #             "target":"x86_64",
126 #             "cpu-index": 1
127 #         }
128 #     ]
129 # }
130 ##
131 { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
132
133 ##
134 # @MachineInfo:
135 #
136 # Information describing a machine.
137 #
138 # @name: the name of the machine
139 #
140 # @alias: an alias for the machine name
141 #
142 # @is-default: whether the machine is default
143 #
144 # @cpu-max: maximum number of CPUs supported by the machine type
145 #           (since 1.5)
146 #
147 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7)
148 #
149 # @numa-mem-supported: true if '-numa node,mem' option is supported by
150 #                      the machine type and false otherwise (since 4.1)
151 #
152 # @deprecated: if true, the machine type is deprecated and may be removed
153 #              in future versions of QEMU according to the QEMU deprecation
154 #              policy (since 4.1)
155 #
156 # @default-cpu-type: default CPU model typename if none is requested via
157 #                    the -cpu argument. (since 4.2)
158 #
159 # @default-ram-id: the default ID of initial RAM memory backend (since 5.2)
160 #
161 # Since: 1.2
162 ##
163 { 'struct': 'MachineInfo',
164   'data': { 'name': 'str', '*alias': 'str',
165             '*is-default': 'bool', 'cpu-max': 'int',
166             'hotpluggable-cpus': 'bool',  'numa-mem-supported': 'bool',
167             'deprecated': 'bool', '*default-cpu-type': 'str',
168             '*default-ram-id': 'str' } }
169
170 ##
171 # @query-machines:
172 #
173 # Return a list of supported machines
174 #
175 # Returns: a list of MachineInfo
176 #
177 # Since: 1.2
178 ##
179 { 'command': 'query-machines', 'returns': ['MachineInfo'] }
180
181 ##
182 # @CurrentMachineParams:
183 #
184 # Information describing the running machine parameters.
185 #
186 # @wakeup-suspend-support: true if the machine supports wake up from
187 #                          suspend
188 #
189 # Since: 4.0
190 ##
191 { 'struct': 'CurrentMachineParams',
192   'data': { 'wakeup-suspend-support': 'bool'} }
193
194 ##
195 # @query-current-machine:
196 #
197 # Return information on the current virtual machine.
198 #
199 # Returns: CurrentMachineParams
200 #
201 # Since: 4.0
202 ##
203 { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
204
205 ##
206 # @TargetInfo:
207 #
208 # Information describing the QEMU target.
209 #
210 # @arch: the target architecture
211 #
212 # Since: 1.2
213 ##
214 { 'struct': 'TargetInfo',
215   'data': { 'arch': 'SysEmuTarget' } }
216
217 ##
218 # @query-target:
219 #
220 # Return information about the target for this QEMU
221 #
222 # Returns: TargetInfo
223 #
224 # Since: 1.2
225 ##
226 { 'command': 'query-target', 'returns': 'TargetInfo' }
227
228 ##
229 # @UuidInfo:
230 #
231 # Guest UUID information (Universally Unique Identifier).
232 #
233 # @UUID: the UUID of the guest
234 #
235 # Since: 0.14
236 #
237 # Notes: If no UUID was specified for the guest, a null UUID is returned.
238 ##
239 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
240
241 ##
242 # @query-uuid:
243 #
244 # Query the guest UUID information.
245 #
246 # Returns: The @UuidInfo for the guest
247 #
248 # Since: 0.14
249 #
250 # Example:
251 #
252 # -> { "execute": "query-uuid" }
253 # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
254 #
255 ##
256 { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
257
258 ##
259 # @GuidInfo:
260 #
261 # GUID information.
262 #
263 # @guid: the globally unique identifier
264 #
265 # Since: 2.9
266 ##
267 { 'struct': 'GuidInfo', 'data': {'guid': 'str'} }
268
269 ##
270 # @query-vm-generation-id:
271 #
272 # Show Virtual Machine Generation ID
273 #
274 # Since: 2.9
275 ##
276 { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' }
277
278 ##
279 # @system_reset:
280 #
281 # Performs a hard reset of a guest.
282 #
283 # Since: 0.14
284 #
285 # Example:
286 #
287 # -> { "execute": "system_reset" }
288 # <- { "return": {} }
289 #
290 ##
291 { 'command': 'system_reset' }
292
293 ##
294 # @system_powerdown:
295 #
296 # Requests that a guest perform a powerdown operation.
297 #
298 # Since: 0.14
299 #
300 # Notes: A guest may or may not respond to this command.  This command
301 #        returning does not indicate that a guest has accepted the request or
302 #        that it has shut down.  Many guests will respond to this command by
303 #        prompting the user in some way.
304 # Example:
305 #
306 # -> { "execute": "system_powerdown" }
307 # <- { "return": {} }
308 #
309 ##
310 { 'command': 'system_powerdown' }
311
312 ##
313 # @system_wakeup:
314 #
315 # Wake up guest from suspend. If the guest has wake-up from suspend
316 # support enabled (wakeup-suspend-support flag from
317 # query-current-machine), wake-up guest from suspend if the guest is
318 # in SUSPENDED state. Return an error otherwise.
319 #
320 # Since:  1.1
321 #
322 # Returns:  nothing.
323 #
324 # Note: prior to 4.0, this command does nothing in case the guest
325 #       isn't suspended.
326 #
327 # Example:
328 #
329 # -> { "execute": "system_wakeup" }
330 # <- { "return": {} }
331 #
332 ##
333 { 'command': 'system_wakeup' }
334
335 ##
336 # @LostTickPolicy:
337 #
338 # Policy for handling lost ticks in timer devices.  Ticks end up getting
339 # lost when, for example, the guest is paused.
340 #
341 # @discard: throw away the missed ticks and continue with future injection
342 #           normally.  The guest OS will see the timer jump ahead by a
343 #           potentially quite significant amount all at once, as if the
344 #           intervening chunk of time had simply not existed; needless to
345 #           say, such a sudden jump can easily confuse a guest OS which is
346 #           not specifically prepared to deal with it.  Assuming the guest
347 #           OS can deal correctly with the time jump, the time in the guest
348 #           and in the host should now match.
349 #
350 # @delay: continue to deliver ticks at the normal rate.  The guest OS will
351 #         not notice anything is amiss, as from its point of view time will
352 #         have continued to flow normally.  The time in the guest should now
353 #         be behind the time in the host by exactly the amount of time during
354 #         which ticks have been missed.
355 #
356 # @slew: deliver ticks at a higher rate to catch up with the missed ticks.
357 #        The guest OS will not notice anything is amiss, as from its point
358 #        of view time will have continued to flow normally.  Once the timer
359 #        has managed to catch up with all the missing ticks, the time in
360 #        the guest and in the host should match.
361 #
362 # Since: 2.0
363 ##
364 { 'enum': 'LostTickPolicy',
365   'data': ['discard', 'delay', 'slew' ] }
366
367 ##
368 # @inject-nmi:
369 #
370 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
371 # The command fails when the guest doesn't support injecting.
372 #
373 # Returns:  If successful, nothing
374 #
375 # Since:  0.14
376 #
377 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
378 #
379 # Example:
380 #
381 # -> { "execute": "inject-nmi" }
382 # <- { "return": {} }
383 #
384 ##
385 { 'command': 'inject-nmi' }
386
387 ##
388 # @KvmInfo:
389 #
390 # Information about support for KVM acceleration
391 #
392 # @enabled: true if KVM acceleration is active
393 #
394 # @present: true if KVM acceleration is built into this executable
395 #
396 # Since: 0.14
397 ##
398 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
399
400 ##
401 # @query-kvm:
402 #
403 # Returns information about KVM acceleration
404 #
405 # Returns: @KvmInfo
406 #
407 # Since: 0.14
408 #
409 # Example:
410 #
411 # -> { "execute": "query-kvm" }
412 # <- { "return": { "enabled": true, "present": true } }
413 #
414 ##
415 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
416
417 ##
418 # @NumaOptionsType:
419 #
420 # @node: NUMA nodes configuration
421 #
422 # @dist: NUMA distance configuration (since 2.10)
423 #
424 # @cpu: property based CPU(s) to node mapping (Since: 2.10)
425 #
426 # @hmat-lb: memory latency and bandwidth information (Since: 5.0)
427 #
428 # @hmat-cache: memory side cache information (Since: 5.0)
429 #
430 # Since: 2.1
431 ##
432 { 'enum': 'NumaOptionsType',
433   'data': [ 'node', 'dist', 'cpu', 'hmat-lb', 'hmat-cache' ] }
434
435 ##
436 # @NumaOptions:
437 #
438 # A discriminated record of NUMA options. (for OptsVisitor)
439 #
440 # Since: 2.1
441 ##
442 { 'union': 'NumaOptions',
443   'base': { 'type': 'NumaOptionsType' },
444   'discriminator': 'type',
445   'data': {
446     'node': 'NumaNodeOptions',
447     'dist': 'NumaDistOptions',
448     'cpu': 'NumaCpuOptions',
449     'hmat-lb': 'NumaHmatLBOptions',
450     'hmat-cache': 'NumaHmatCacheOptions' }}
451
452 ##
453 # @NumaNodeOptions:
454 #
455 # Create a guest NUMA node. (for OptsVisitor)
456 #
457 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
458 #
459 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin
460 #         if omitted)
461 #
462 # @mem: memory size of this node; mutually exclusive with @memdev.
463 #       Equally divide total memory among nodes if both @mem and @memdev are
464 #       omitted.
465 #
466 # @memdev: memory backend object.  If specified for one node,
467 #          it must be specified for all nodes.
468 #
469 # @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145,
470 #             points to the nodeid which has the memory controller
471 #             responsible for this NUMA node. This field provides
472 #             additional information as to the initiator node that
473 #             is closest (as in directly attached) to this node, and
474 #             therefore has the best performance (since 5.0)
475 #
476 # Since: 2.1
477 ##
478 { 'struct': 'NumaNodeOptions',
479   'data': {
480    '*nodeid': 'uint16',
481    '*cpus':   ['uint16'],
482    '*mem':    'size',
483    '*memdev': 'str',
484    '*initiator': 'uint16' }}
485
486 ##
487 # @NumaDistOptions:
488 #
489 # Set the distance between 2 NUMA nodes.
490 #
491 # @src: source NUMA node.
492 #
493 # @dst: destination NUMA node.
494 #
495 # @val: NUMA distance from source node to destination node.
496 #       When a node is unreachable from another node, set the distance
497 #       between them to 255.
498 #
499 # Since: 2.10
500 ##
501 { 'struct': 'NumaDistOptions',
502   'data': {
503    'src': 'uint16',
504    'dst': 'uint16',
505    'val': 'uint8' }}
506
507 ##
508 # @X86CPURegister32:
509 #
510 # A X86 32-bit register
511 #
512 # Since: 1.5
513 ##
514 { 'enum': 'X86CPURegister32',
515   'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
516
517 ##
518 # @X86CPUFeatureWordInfo:
519 #
520 # Information about a X86 CPU feature word
521 #
522 # @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
523 #
524 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
525 #                   feature word
526 #
527 # @cpuid-register: Output register containing the feature bits
528 #
529 # @features: value of output register, containing the feature bits
530 #
531 # Since: 1.5
532 ##
533 { 'struct': 'X86CPUFeatureWordInfo',
534   'data': { 'cpuid-input-eax': 'int',
535             '*cpuid-input-ecx': 'int',
536             'cpuid-register': 'X86CPURegister32',
537             'features': 'int' } }
538
539 ##
540 # @DummyForceArrays:
541 #
542 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
543 #
544 # Since: 2.5
545 ##
546 { 'struct': 'DummyForceArrays',
547   'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
548
549 ##
550 # @NumaCpuOptions:
551 #
552 # Option "-numa cpu" overrides default cpu to node mapping.
553 # It accepts the same set of cpu properties as returned by
554 # query-hotpluggable-cpus[].props, where node-id could be used to
555 # override default node mapping.
556 #
557 # Since: 2.10
558 ##
559 { 'struct': 'NumaCpuOptions',
560    'base': 'CpuInstanceProperties',
561    'data' : {} }
562
563 ##
564 # @HmatLBMemoryHierarchy:
565 #
566 # The memory hierarchy in the System Locality Latency and Bandwidth
567 # Information Structure of HMAT (Heterogeneous Memory Attribute Table)
568 #
569 # For more information about @HmatLBMemoryHierarchy, see chapter
570 # 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
571 #
572 # @memory: the structure represents the memory performance
573 #
574 # @first-level: first level of memory side cache
575 #
576 # @second-level: second level of memory side cache
577 #
578 # @third-level: third level of memory side cache
579 #
580 # Since: 5.0
581 ##
582 { 'enum': 'HmatLBMemoryHierarchy',
583   'data': [ 'memory', 'first-level', 'second-level', 'third-level' ] }
584
585 ##
586 # @HmatLBDataType:
587 #
588 # Data type in the System Locality Latency and Bandwidth
589 # Information Structure of HMAT (Heterogeneous Memory Attribute Table)
590 #
591 # For more information about @HmatLBDataType, see chapter
592 # 5.2.27.4: Table 5-146:  Field "Data Type" of ACPI 6.3 spec.
593 #
594 # @access-latency: access latency (nanoseconds)
595 #
596 # @read-latency: read latency (nanoseconds)
597 #
598 # @write-latency: write latency (nanoseconds)
599 #
600 # @access-bandwidth: access bandwidth (Bytes per second)
601 #
602 # @read-bandwidth: read bandwidth (Bytes per second)
603 #
604 # @write-bandwidth: write bandwidth (Bytes per second)
605 #
606 # Since: 5.0
607 ##
608 { 'enum': 'HmatLBDataType',
609   'data': [ 'access-latency', 'read-latency', 'write-latency',
610             'access-bandwidth', 'read-bandwidth', 'write-bandwidth' ] }
611
612 ##
613 # @NumaHmatLBOptions:
614 #
615 # Set the system locality latency and bandwidth information
616 # between Initiator and Target proximity Domains.
617 #
618 # For more information about @NumaHmatLBOptions, see chapter
619 # 5.2.27.4: Table 5-146 of ACPI 6.3 spec.
620 #
621 # @initiator: the Initiator Proximity Domain.
622 #
623 # @target: the Target Proximity Domain.
624 #
625 # @hierarchy: the Memory Hierarchy. Indicates the performance
626 #             of memory or side cache.
627 #
628 # @data-type: presents the type of data, access/read/write
629 #             latency or hit latency.
630 #
631 # @latency: the value of latency from @initiator to @target
632 #           proximity domain, the latency unit is "ns(nanosecond)".
633 #
634 # @bandwidth: the value of bandwidth between @initiator and @target
635 #             proximity domain, the bandwidth unit is
636 #             "Bytes per second".
637 #
638 # Since: 5.0
639 ##
640 { 'struct': 'NumaHmatLBOptions',
641     'data': {
642     'initiator': 'uint16',
643     'target': 'uint16',
644     'hierarchy': 'HmatLBMemoryHierarchy',
645     'data-type': 'HmatLBDataType',
646     '*latency': 'uint64',
647     '*bandwidth': 'size' }}
648
649 ##
650 # @HmatCacheAssociativity:
651 #
652 # Cache associativity in the Memory Side Cache Information Structure
653 # of HMAT
654 #
655 # For more information of @HmatCacheAssociativity, see chapter
656 # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
657 #
658 # @none: None (no memory side cache in this proximity domain,
659 #              or cache associativity unknown)
660 #
661 # @direct: Direct Mapped
662 #
663 # @complex: Complex Cache Indexing (implementation specific)
664 #
665 # Since: 5.0
666 ##
667 { 'enum': 'HmatCacheAssociativity',
668   'data': [ 'none', 'direct', 'complex' ] }
669
670 ##
671 # @HmatCacheWritePolicy:
672 #
673 # Cache write policy in the Memory Side Cache Information Structure
674 # of HMAT
675 #
676 # For more information of @HmatCacheWritePolicy, see chapter
677 # 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
678 #
679 # @none: None (no memory side cache in this proximity domain,
680 #        or cache write policy unknown)
681 #
682 # @write-back: Write Back (WB)
683 #
684 # @write-through: Write Through (WT)
685 #
686 # Since: 5.0
687 ##
688 { 'enum': 'HmatCacheWritePolicy',
689   'data': [ 'none', 'write-back', 'write-through' ] }
690
691 ##
692 # @NumaHmatCacheOptions:
693 #
694 # Set the memory side cache information for a given memory domain.
695 #
696 # For more information of @NumaHmatCacheOptions, see chapter
697 # 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
698 #
699 # @node-id: the memory proximity domain to which the memory belongs.
700 #
701 # @size: the size of memory side cache in bytes.
702 #
703 # @level: the cache level described in this structure.
704 #
705 # @associativity: the cache associativity,
706 #                 none/direct-mapped/complex(complex cache indexing).
707 #
708 # @policy: the write policy, none/write-back/write-through.
709 #
710 # @line: the cache Line size in bytes.
711 #
712 # Since: 5.0
713 ##
714 { 'struct': 'NumaHmatCacheOptions',
715   'data': {
716    'node-id': 'uint32',
717    'size': 'size',
718    'level': 'uint8',
719    'associativity': 'HmatCacheAssociativity',
720    'policy': 'HmatCacheWritePolicy',
721    'line': 'uint16' }}
722
723 ##
724 # @memsave:
725 #
726 # Save a portion of guest memory to a file.
727 #
728 # @val: the virtual address of the guest to start from
729 #
730 # @size: the size of memory region to save
731 #
732 # @filename: the file to save the memory to as binary data
733 #
734 # @cpu-index: the index of the virtual CPU to use for translating the
735 #             virtual address (defaults to CPU 0)
736 #
737 # Returns: Nothing on success
738 #
739 # Since: 0.14
740 #
741 # Notes: Errors were not reliably returned until 1.1
742 #
743 # Example:
744 #
745 # -> { "execute": "memsave",
746 #      "arguments": { "val": 10,
747 #                     "size": 100,
748 #                     "filename": "/tmp/virtual-mem-dump" } }
749 # <- { "return": {} }
750 #
751 ##
752 { 'command': 'memsave',
753   'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
754
755 ##
756 # @pmemsave:
757 #
758 # Save a portion of guest physical memory to a file.
759 #
760 # @val: the physical address of the guest to start from
761 #
762 # @size: the size of memory region to save
763 #
764 # @filename: the file to save the memory to as binary data
765 #
766 # Returns: Nothing on success
767 #
768 # Since: 0.14
769 #
770 # Notes: Errors were not reliably returned until 1.1
771 #
772 # Example:
773 #
774 # -> { "execute": "pmemsave",
775 #      "arguments": { "val": 10,
776 #                     "size": 100,
777 #                     "filename": "/tmp/physical-mem-dump" } }
778 # <- { "return": {} }
779 #
780 ##
781 { 'command': 'pmemsave',
782   'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
783
784 ##
785 # @Memdev:
786 #
787 # Information about memory backend
788 #
789 # @id: backend's ID if backend has 'id' property (since 2.9)
790 #
791 # @size: memory backend size
792 #
793 # @merge: enables or disables memory merge support
794 #
795 # @dump: includes memory backend's memory in a core dump or not
796 #
797 # @prealloc: enables or disables memory preallocation
798 #
799 # @host-nodes: host nodes for its memory policy
800 #
801 # @policy: memory policy of memory backend
802 #
803 # Since: 2.1
804 ##
805 { 'struct': 'Memdev',
806   'data': {
807     '*id':        'str',
808     'size':       'size',
809     'merge':      'bool',
810     'dump':       'bool',
811     'prealloc':   'bool',
812     'host-nodes': ['uint16'],
813     'policy':     'HostMemPolicy' }}
814
815 ##
816 # @query-memdev:
817 #
818 # Returns information for all memory backends.
819 #
820 # Returns: a list of @Memdev.
821 #
822 # Since: 2.1
823 #
824 # Example:
825 #
826 # -> { "execute": "query-memdev" }
827 # <- { "return": [
828 #        {
829 #          "id": "mem1",
830 #          "size": 536870912,
831 #          "merge": false,
832 #          "dump": true,
833 #          "prealloc": false,
834 #          "host-nodes": [0, 1],
835 #          "policy": "bind"
836 #        },
837 #        {
838 #          "size": 536870912,
839 #          "merge": false,
840 #          "dump": true,
841 #          "prealloc": true,
842 #          "host-nodes": [2, 3],
843 #          "policy": "preferred"
844 #        }
845 #      ]
846 #    }
847 #
848 ##
849 { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
850
851 ##
852 # @CpuInstanceProperties:
853 #
854 # List of properties to be used for hotplugging a CPU instance,
855 # it should be passed by management with device_add command when
856 # a CPU is being hotplugged.
857 #
858 # @node-id: NUMA node ID the CPU belongs to
859 # @socket-id: socket number within node/board the CPU belongs to
860 # @die-id: die number within node/board the CPU belongs to (Since 4.1)
861 # @core-id: core number within die the CPU belongs to
862 # @thread-id: thread number within core the CPU belongs to
863 #
864 # Note: currently there are 5 properties that could be present
865 #       but management should be prepared to pass through other
866 #       properties with device_add command to allow for future
867 #       interface extension. This also requires the filed names to be kept in
868 #       sync with the properties passed to -device/device_add.
869 #
870 # Since: 2.7
871 ##
872 { 'struct': 'CpuInstanceProperties',
873   'data': { '*node-id': 'int',
874             '*socket-id': 'int',
875             '*die-id': 'int',
876             '*core-id': 'int',
877             '*thread-id': 'int'
878   }
879 }
880
881 ##
882 # @HotpluggableCPU:
883 #
884 # @type: CPU object type for usage with device_add command
885 # @props: list of properties to be used for hotplugging CPU
886 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
887 # @qom-path: link to existing CPU object if CPU is present or
888 #            omitted if CPU is not present.
889 #
890 # Since: 2.7
891 ##
892 { 'struct': 'HotpluggableCPU',
893   'data': { 'type': 'str',
894             'vcpus-count': 'int',
895             'props': 'CpuInstanceProperties',
896             '*qom-path': 'str'
897           }
898 }
899
900 ##
901 # @query-hotpluggable-cpus:
902 #
903 # TODO: Better documentation; currently there is none.
904 #
905 # Returns: a list of HotpluggableCPU objects.
906 #
907 # Since: 2.7
908 #
909 # Example:
910 #
911 # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
912 #
913 # -> { "execute": "query-hotpluggable-cpus" }
914 # <- {"return": [
915 #      { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
916 #        "vcpus-count": 1 },
917 #      { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
918 #        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
919 #    ]}'
920 #
921 # For pc machine type started with -smp 1,maxcpus=2:
922 #
923 # -> { "execute": "query-hotpluggable-cpus" }
924 # <- {"return": [
925 #      {
926 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
927 #         "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
928 #      },
929 #      {
930 #         "qom-path": "/machine/unattached/device[0]",
931 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
932 #         "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
933 #      }
934 #    ]}
935 #
936 # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
937 # (Since: 2.11):
938 #
939 # -> { "execute": "query-hotpluggable-cpus" }
940 # <- {"return": [
941 #      {
942 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
943 #         "props": { "core-id": 1 }
944 #      },
945 #      {
946 #         "qom-path": "/machine/unattached/device[0]",
947 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
948 #         "props": { "core-id": 0 }
949 #      }
950 #    ]}
951 #
952 ##
953 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
954              'allow-preconfig': true }
955
956 ##
957 # @set-numa-node:
958 #
959 # Runtime equivalent of '-numa' CLI option, available at
960 # preconfigure stage to configure numa mapping before initializing
961 # machine.
962 #
963 # Since 3.0
964 ##
965 { 'command': 'set-numa-node', 'boxed': true,
966   'data': 'NumaOptions',
967   'allow-preconfig': true
968 }
969
970 ##
971 # @balloon:
972 #
973 # Request the balloon driver to change its balloon size.
974 #
975 # @value: the target logical size of the VM in bytes.
976 #         We can deduce the size of the balloon using this formula:
977 #
978 #            logical_vm_size = vm_ram_size - balloon_size
979 #
980 #         From it we have: balloon_size = vm_ram_size - @value
981 #
982 # Returns: - Nothing on success
983 #          - If the balloon driver is enabled but not functional because the KVM
984 #            kernel module cannot support it, KvmMissingCap
985 #          - If no balloon device is present, DeviceNotActive
986 #
987 # Notes: This command just issues a request to the guest.  When it returns,
988 #        the balloon size may not have changed.  A guest can change the balloon
989 #        size independent of this command.
990 #
991 # Since: 0.14
992 #
993 # Example:
994 #
995 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
996 # <- { "return": {} }
997 #
998 # With a 2.5GiB guest this command inflated the ballon to 3GiB.
999 #
1000 ##
1001 { 'command': 'balloon', 'data': {'value': 'int'} }
1002
1003 ##
1004 # @BalloonInfo:
1005 #
1006 # Information about the guest balloon device.
1007 #
1008 # @actual: the logical size of the VM in bytes
1009 #          Formula used: logical_vm_size = vm_ram_size - balloon_size
1010 #
1011 # Since: 0.14
1012 #
1013 ##
1014 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
1015
1016 ##
1017 # @query-balloon:
1018 #
1019 # Return information about the balloon device.
1020 #
1021 # Returns: - @BalloonInfo on success
1022 #          - If the balloon driver is enabled but not functional because the KVM
1023 #            kernel module cannot support it, KvmMissingCap
1024 #          - If no balloon device is present, DeviceNotActive
1025 #
1026 # Since: 0.14
1027 #
1028 # Example:
1029 #
1030 # -> { "execute": "query-balloon" }
1031 # <- { "return": {
1032 #          "actual": 1073741824,
1033 #       }
1034 #    }
1035 #
1036 ##
1037 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
1038
1039 ##
1040 # @BALLOON_CHANGE:
1041 #
1042 # Emitted when the guest changes the actual BALLOON level. This value is
1043 # equivalent to the @actual field return by the 'query-balloon' command
1044 #
1045 # @actual: the logical size of the VM in bytes
1046 #          Formula used: logical_vm_size = vm_ram_size - balloon_size
1047 #
1048 # Note: this event is rate-limited.
1049 #
1050 # Since: 1.2
1051 #
1052 # Example:
1053 #
1054 # <- { "event": "BALLOON_CHANGE",
1055 #      "data": { "actual": 944766976 },
1056 #      "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
1057 #
1058 ##
1059 { 'event': 'BALLOON_CHANGE',
1060   'data': { 'actual': 'int' } }
1061
1062 ##
1063 # @MemoryInfo:
1064 #
1065 # Actual memory information in bytes.
1066 #
1067 # @base-memory: size of "base" memory specified with command line
1068 #               option -m.
1069 #
1070 # @plugged-memory: size of memory that can be hot-unplugged. This field
1071 #                  is omitted if target doesn't support memory hotplug
1072 #                  (i.e. CONFIG_MEM_DEVICE not defined at build time).
1073 #
1074 # Since: 2.11
1075 ##
1076 { 'struct': 'MemoryInfo',
1077   'data'  : { 'base-memory': 'size', '*plugged-memory': 'size' } }
1078
1079 ##
1080 # @query-memory-size-summary:
1081 #
1082 # Return the amount of initially allocated and present hotpluggable (if
1083 # enabled) memory in bytes.
1084 #
1085 # Example:
1086 #
1087 # -> { "execute": "query-memory-size-summary" }
1088 # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
1089 #
1090 # Since: 2.11
1091 ##
1092 { 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
1093
1094 ##
1095 # @PCDIMMDeviceInfo:
1096 #
1097 # PCDIMMDevice state information
1098 #
1099 # @id: device's ID
1100 #
1101 # @addr: physical address, where device is mapped
1102 #
1103 # @size: size of memory that the device provides
1104 #
1105 # @slot: slot number at which device is plugged in
1106 #
1107 # @node: NUMA node number where device is plugged in
1108 #
1109 # @memdev: memory backend linked with device
1110 #
1111 # @hotplugged: true if device was hotplugged
1112 #
1113 # @hotpluggable: true if device if could be added/removed while machine is running
1114 #
1115 # Since: 2.1
1116 ##
1117 { 'struct': 'PCDIMMDeviceInfo',
1118   'data': { '*id': 'str',
1119             'addr': 'int',
1120             'size': 'int',
1121             'slot': 'int',
1122             'node': 'int',
1123             'memdev': 'str',
1124             'hotplugged': 'bool',
1125             'hotpluggable': 'bool'
1126           }
1127 }
1128
1129 ##
1130 # @VirtioPMEMDeviceInfo:
1131 #
1132 # VirtioPMEM state information
1133 #
1134 # @id: device's ID
1135 #
1136 # @memaddr: physical address in memory, where device is mapped
1137 #
1138 # @size: size of memory that the device provides
1139 #
1140 # @memdev: memory backend linked with device
1141 #
1142 # Since: 4.1
1143 ##
1144 { 'struct': 'VirtioPMEMDeviceInfo',
1145   'data': { '*id': 'str',
1146             'memaddr': 'size',
1147             'size': 'size',
1148             'memdev': 'str'
1149           }
1150 }
1151
1152 ##
1153 # @VirtioMEMDeviceInfo:
1154 #
1155 # VirtioMEMDevice state information
1156 #
1157 # @id: device's ID
1158 #
1159 # @memaddr: physical address in memory, where device is mapped
1160 #
1161 # @requested-size: the user requested size of the device
1162 #
1163 # @size: the (current) size of memory that the device provides
1164 #
1165 # @max-size: the maximum size of memory that the device can provide
1166 #
1167 # @block-size: the block size of memory that the device provides
1168 #
1169 # @node: NUMA node number where device is assigned to
1170 #
1171 # @memdev: memory backend linked with the region
1172 #
1173 # Since: 5.1
1174 ##
1175 { 'struct': 'VirtioMEMDeviceInfo',
1176   'data': { '*id': 'str',
1177             'memaddr': 'size',
1178             'requested-size': 'size',
1179             'size': 'size',
1180             'max-size': 'size',
1181             'block-size': 'size',
1182             'node': 'int',
1183             'memdev': 'str'
1184           }
1185 }
1186
1187 ##
1188 # @MemoryDeviceInfo:
1189 #
1190 # Union containing information about a memory device
1191 #
1192 # nvdimm is included since 2.12. virtio-pmem is included since 4.1.
1193 # virtio-mem is included since 5.1.
1194 #
1195 # Since: 2.1
1196 ##
1197 { 'union': 'MemoryDeviceInfo',
1198   'data': { 'dimm': 'PCDIMMDeviceInfo',
1199             'nvdimm': 'PCDIMMDeviceInfo',
1200             'virtio-pmem': 'VirtioPMEMDeviceInfo',
1201             'virtio-mem': 'VirtioMEMDeviceInfo'
1202           }
1203 }
1204
1205 ##
1206 # @query-memory-devices:
1207 #
1208 # Lists available memory devices and their state
1209 #
1210 # Since: 2.1
1211 #
1212 # Example:
1213 #
1214 # -> { "execute": "query-memory-devices" }
1215 # <- { "return": [ { "data":
1216 #                       { "addr": 5368709120,
1217 #                         "hotpluggable": true,
1218 #                         "hotplugged": true,
1219 #                         "id": "d1",
1220 #                         "memdev": "/objects/memX",
1221 #                         "node": 0,
1222 #                         "size": 1073741824,
1223 #                         "slot": 0},
1224 #                    "type": "dimm"
1225 #                  } ] }
1226 #
1227 ##
1228 { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
1229
1230 ##
1231 # @MEMORY_DEVICE_SIZE_CHANGE:
1232 #
1233 # Emitted when the size of a memory device changes. Only emitted for memory
1234 # devices that can actually change the size (e.g., virtio-mem due to guest
1235 # action).
1236 #
1237 # @id: device's ID
1238 # @size: the new size of memory that the device provides
1239 #
1240 # Note: this event is rate-limited.
1241 #
1242 # Since: 5.1
1243 #
1244 # Example:
1245 #
1246 # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
1247 #      "data": { "id": "vm0", "size": 1073741824},
1248 #      "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
1249 #
1250 ##
1251 { 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
1252   'data': { '*id': 'str', 'size': 'size' } }
1253
1254
1255 ##
1256 # @MEM_UNPLUG_ERROR:
1257 #
1258 # Emitted when memory hot unplug error occurs.
1259 #
1260 # @device: device name
1261 #
1262 # @msg: Informative message
1263 #
1264 # Since: 2.4
1265 #
1266 # Example:
1267 #
1268 # <- { "event": "MEM_UNPLUG_ERROR"
1269 #      "data": { "device": "dimm1",
1270 #                "msg": "acpi: device unplug for unsupported device"
1271 #      },
1272 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
1273 #
1274 ##
1275 { 'event': 'MEM_UNPLUG_ERROR',
1276   'data': { 'device': 'str', 'msg': 'str' } }