| blob | 157712f00614a2ab4058657cc4ee69db1d504476 |
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.
7 ##
8 # = Machines
9 ##
11 { 'include': 'common.json' }
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',
33 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64',
34 'mips64el', 'mipsel', 'nios2', 'or1k', 'ppc',
35 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4',
36 'sh4eb', 'sparc', 'sparc64', 'tricore',
37 'x86_64', 'xtensa', 'xtensaeb' ] }
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' ] }
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' } }
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' } }
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' ] }
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' } }
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'] }
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'} }
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' }
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' } }
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' }
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'} }
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 }
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'} }
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' }
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' }
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' }
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' }
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' ] }
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' }
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'} }
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' }
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' ] }
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' }}
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' }}
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' }}
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' ] }
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' } }
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'] } }
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' : {} }
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' ] }
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' ] }
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' }}
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' ] }
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' ] }
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' }}
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'} }
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'} }
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: whether memory merge support is enabled
794 #
795 # @dump: whether memory backend's memory is included in a core dump
796 #
797 # @prealloc: whether memory was preallocated
798 #
799 # @share: whether memory is private to QEMU or shared (since 6.1)
800 #
801 # @reserve: whether swap space (or huge pages) was reserved if applicable.
802 # This corresponds to the user configuration and not the actual
803 # behavior implemented in the OS to perform the reservation.
804 # For example, Linux will never reserve swap space for shared
805 # file mappings. (since 6.1)
806 #
807 # @host-nodes: host nodes for its memory policy
808 #
809 # @policy: memory policy of memory backend
810 #
811 # Since: 2.1
812 ##
813 { 'struct': 'Memdev',
814 'data': {
815 '*id': 'str',
816 'size': 'size',
817 'merge': 'bool',
818 'dump': 'bool',
819 'prealloc': 'bool',
820 'share': 'bool',
821 '*reserve': 'bool',
822 'host-nodes': ['uint16'],
823 'policy': 'HostMemPolicy' }}
825 ##
826 # @query-memdev:
827 #
828 # Returns information for all memory backends.
829 #
830 # Returns: a list of @Memdev.
831 #
832 # Since: 2.1
833 #
834 # Example:
835 #
836 # -> { "execute": "query-memdev" }
837 # <- { "return": [
838 # {
839 # "id": "mem1",
840 # "size": 536870912,
841 # "merge": false,
842 # "dump": true,
843 # "prealloc": false,
844 # "host-nodes": [0, 1],
845 # "policy": "bind"
846 # },
847 # {
848 # "size": 536870912,
849 # "merge": false,
850 # "dump": true,
851 # "prealloc": true,
852 # "host-nodes": [2, 3],
853 # "policy": "preferred"
854 # }
855 # ]
856 # }
857 #
858 ##
859 { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
861 ##
862 # @CpuInstanceProperties:
863 #
864 # List of properties to be used for hotplugging a CPU instance,
865 # it should be passed by management with device_add command when
866 # a CPU is being hotplugged.
867 #
868 # @node-id: NUMA node ID the CPU belongs to
869 # @socket-id: socket number within node/board the CPU belongs to
870 # @die-id: die number within node/board the CPU belongs to (Since 4.1)
871 # @core-id: core number within die the CPU belongs to
872 # @thread-id: thread number within core the CPU belongs to
873 #
874 # Note: currently there are 5 properties that could be present
875 # but management should be prepared to pass through other
876 # properties with device_add command to allow for future
877 # interface extension. This also requires the filed names to be kept in
878 # sync with the properties passed to -device/device_add.
879 #
880 # Since: 2.7
881 ##
882 { 'struct': 'CpuInstanceProperties',
883 'data': { '*node-id': 'int',
884 '*socket-id': 'int',
885 '*die-id': 'int',
886 '*core-id': 'int',
887 '*thread-id': 'int'
888 }
889 }
891 ##
892 # @HotpluggableCPU:
893 #
894 # @type: CPU object type for usage with device_add command
895 # @props: list of properties to be used for hotplugging CPU
896 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
897 # @qom-path: link to existing CPU object if CPU is present or
898 # omitted if CPU is not present.
899 #
900 # Since: 2.7
901 ##
902 { 'struct': 'HotpluggableCPU',
903 'data': { 'type': 'str',
904 'vcpus-count': 'int',
905 'props': 'CpuInstanceProperties',
906 '*qom-path': 'str'
907 }
908 }
910 ##
911 # @query-hotpluggable-cpus:
912 #
913 # TODO: Better documentation; currently there is none.
914 #
915 # Returns: a list of HotpluggableCPU objects.
916 #
917 # Since: 2.7
918 #
919 # Example:
920 #
921 # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
922 #
923 # -> { "execute": "query-hotpluggable-cpus" }
924 # <- {"return": [
925 # { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
926 # "vcpus-count": 1 },
927 # { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
928 # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
929 # ]}'
930 #
931 # For pc machine type started with -smp 1,maxcpus=2:
932 #
933 # -> { "execute": "query-hotpluggable-cpus" }
934 # <- {"return": [
935 # {
936 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
937 # "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
938 # },
939 # {
940 # "qom-path": "/machine/unattached/device[0]",
941 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
942 # "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
943 # }
944 # ]}
945 #
946 # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
947 # (Since: 2.11):
948 #
949 # -> { "execute": "query-hotpluggable-cpus" }
950 # <- {"return": [
951 # {
952 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
953 # "props": { "core-id": 1 }
954 # },
955 # {
956 # "qom-path": "/machine/unattached/device[0]",
957 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
958 # "props": { "core-id": 0 }
959 # }
960 # ]}
961 #
962 ##
963 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
964 'allow-preconfig': true }
966 ##
967 # @set-numa-node:
968 #
969 # Runtime equivalent of '-numa' CLI option, available at
970 # preconfigure stage to configure numa mapping before initializing
971 # machine.
972 #
973 # Since 3.0
974 ##
975 { 'command': 'set-numa-node', 'boxed': true,
976 'data': 'NumaOptions',
977 'allow-preconfig': true
978 }
980 ##
981 # @balloon:
982 #
983 # Request the balloon driver to change its balloon size.
984 #
985 # @value: the target logical size of the VM in bytes.
986 # We can deduce the size of the balloon using this formula:
987 #
988 # logical_vm_size = vm_ram_size - balloon_size
989 #
990 # From it we have: balloon_size = vm_ram_size - @value
991 #
992 # Returns: - Nothing on success
993 # - If the balloon driver is enabled but not functional because the KVM
994 # kernel module cannot support it, KvmMissingCap
995 # - If no balloon device is present, DeviceNotActive
996 #
997 # Notes: This command just issues a request to the guest. When it returns,
998 # the balloon size may not have changed. A guest can change the balloon
999 # size independent of this command.
1000 #
1001 # Since: 0.14
1002 #
1003 # Example:
1004 #
1005 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1006 # <- { "return": {} }
1007 #
1008 # With a 2.5GiB guest this command inflated the ballon to 3GiB.
1009 #
1010 ##
1011 { 'command': 'balloon', 'data': {'value': 'int'} }
1013 ##
1014 # @BalloonInfo:
1015 #
1016 # Information about the guest balloon device.
1017 #
1018 # @actual: the logical size of the VM in bytes
1019 # Formula used: logical_vm_size = vm_ram_size - balloon_size
1020 #
1021 # Since: 0.14
1022 #
1023 ##
1024 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
1026 ##
1027 # @query-balloon:
1028 #
1029 # Return information about the balloon device.
1030 #
1031 # Returns: - @BalloonInfo on success
1032 # - If the balloon driver is enabled but not functional because the KVM
1033 # kernel module cannot support it, KvmMissingCap
1034 # - If no balloon device is present, DeviceNotActive
1035 #
1036 # Since: 0.14
1037 #
1038 # Example:
1039 #
1040 # -> { "execute": "query-balloon" }
1041 # <- { "return": {
1042 # "actual": 1073741824,
1043 # }
1044 # }
1045 #
1046 ##
1047 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
1049 ##
1050 # @BALLOON_CHANGE:
1051 #
1052 # Emitted when the guest changes the actual BALLOON level. This value is
1053 # equivalent to the @actual field return by the 'query-balloon' command
1054 #
1055 # @actual: the logical size of the VM in bytes
1056 # Formula used: logical_vm_size = vm_ram_size - balloon_size
1057 #
1058 # Note: this event is rate-limited.
1059 #
1060 # Since: 1.2
1061 #
1062 # Example:
1063 #
1064 # <- { "event": "BALLOON_CHANGE",
1065 # "data": { "actual": 944766976 },
1066 # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
1067 #
1068 ##
1069 { 'event': 'BALLOON_CHANGE',
1070 'data': { 'actual': 'int' } }
1072 ##
1073 # @MemoryInfo:
1074 #
1075 # Actual memory information in bytes.
1076 #
1077 # @base-memory: size of "base" memory specified with command line
1078 # option -m.
1079 #
1080 # @plugged-memory: size of memory that can be hot-unplugged. This field
1081 # is omitted if target doesn't support memory hotplug
1082 # (i.e. CONFIG_MEM_DEVICE not defined at build time).
1083 #
1084 # Since: 2.11
1085 ##
1086 { 'struct': 'MemoryInfo',
1087 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } }
1089 ##
1090 # @query-memory-size-summary:
1091 #
1092 # Return the amount of initially allocated and present hotpluggable (if
1093 # enabled) memory in bytes.
1094 #
1095 # Example:
1096 #
1097 # -> { "execute": "query-memory-size-summary" }
1098 # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
1099 #
1100 # Since: 2.11
1101 ##
1102 { 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
1104 ##
1105 # @PCDIMMDeviceInfo:
1106 #
1107 # PCDIMMDevice state information
1108 #
1109 # @id: device's ID
1110 #
1111 # @addr: physical address, where device is mapped
1112 #
1113 # @size: size of memory that the device provides
1114 #
1115 # @slot: slot number at which device is plugged in
1116 #
1117 # @node: NUMA node number where device is plugged in
1118 #
1119 # @memdev: memory backend linked with device
1120 #
1121 # @hotplugged: true if device was hotplugged
1122 #
1123 # @hotpluggable: true if device if could be added/removed while machine is running
1124 #
1125 # Since: 2.1
1126 ##
1127 { 'struct': 'PCDIMMDeviceInfo',
1128 'data': { '*id': 'str',
1129 'addr': 'int',
1130 'size': 'int',
1131 'slot': 'int',
1132 'node': 'int',
1133 'memdev': 'str',
1134 'hotplugged': 'bool',
1135 'hotpluggable': 'bool'
1136 }
1137 }
1139 ##
1140 # @VirtioPMEMDeviceInfo:
1141 #
1142 # VirtioPMEM state information
1143 #
1144 # @id: device's ID
1145 #
1146 # @memaddr: physical address in memory, where device is mapped
1147 #
1148 # @size: size of memory that the device provides
1149 #
1150 # @memdev: memory backend linked with device
1151 #
1152 # Since: 4.1
1153 ##
1154 { 'struct': 'VirtioPMEMDeviceInfo',
1155 'data': { '*id': 'str',
1156 'memaddr': 'size',
1157 'size': 'size',
1158 'memdev': 'str'
1159 }
1160 }
1162 ##
1163 # @VirtioMEMDeviceInfo:
1164 #
1165 # VirtioMEMDevice state information
1166 #
1167 # @id: device's ID
1168 #
1169 # @memaddr: physical address in memory, where device is mapped
1170 #
1171 # @requested-size: the user requested size of the device
1172 #
1173 # @size: the (current) size of memory that the device provides
1174 #
1175 # @max-size: the maximum size of memory that the device can provide
1176 #
1177 # @block-size: the block size of memory that the device provides
1178 #
1179 # @node: NUMA node number where device is assigned to
1180 #
1181 # @memdev: memory backend linked with the region
1182 #
1183 # Since: 5.1
1184 ##
1185 { 'struct': 'VirtioMEMDeviceInfo',
1186 'data': { '*id': 'str',
1187 'memaddr': 'size',
1188 'requested-size': 'size',
1189 'size': 'size',
1190 'max-size': 'size',
1191 'block-size': 'size',
1192 'node': 'int',
1193 'memdev': 'str'
1194 }
1195 }
1197 ##
1198 # @MemoryDeviceInfo:
1199 #
1200 # Union containing information about a memory device
1201 #
1202 # nvdimm is included since 2.12. virtio-pmem is included since 4.1.
1203 # virtio-mem is included since 5.1.
1204 #
1205 # Since: 2.1
1206 ##
1207 { 'union': 'MemoryDeviceInfo',
1208 'data': { 'dimm': 'PCDIMMDeviceInfo',
1209 'nvdimm': 'PCDIMMDeviceInfo',
1210 'virtio-pmem': 'VirtioPMEMDeviceInfo',
1211 'virtio-mem': 'VirtioMEMDeviceInfo'
1212 }
1213 }
1215 ##
1216 # @query-memory-devices:
1217 #
1218 # Lists available memory devices and their state
1219 #
1220 # Since: 2.1
1221 #
1222 # Example:
1223 #
1224 # -> { "execute": "query-memory-devices" }
1225 # <- { "return": [ { "data":
1226 # { "addr": 5368709120,
1227 # "hotpluggable": true,
1228 # "hotplugged": true,
1229 # "id": "d1",
1230 # "memdev": "/objects/memX",
1231 # "node": 0,
1232 # "size": 1073741824,
1233 # "slot": 0},
1234 # "type": "dimm"
1235 # } ] }
1236 #
1237 ##
1238 { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
1240 ##
1241 # @MEMORY_DEVICE_SIZE_CHANGE:
1242 #
1243 # Emitted when the size of a memory device changes. Only emitted for memory
1244 # devices that can actually change the size (e.g., virtio-mem due to guest
1245 # action).
1246 #
1247 # @id: device's ID
1248 # @size: the new size of memory that the device provides
1249 #
1250 # Note: this event is rate-limited.
1251 #
1252 # Since: 5.1
1253 #
1254 # Example:
1255 #
1256 # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
1257 # "data": { "id": "vm0", "size": 1073741824},
1258 # "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
1259 #
1260 ##
1261 { 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
1262 'data': { '*id': 'str', 'size': 'size' } }
1265 ##
1266 # @MEM_UNPLUG_ERROR:
1267 #
1268 # Emitted when memory hot unplug error occurs.
1269 #
1270 # @device: device name
1271 #
1272 # @msg: Informative message
1273 #
1274 # Since: 2.4
1275 #
1276 # Example:
1277 #
1278 # <- { "event": "MEM_UNPLUG_ERROR"
1279 # "data": { "device": "dimm1",
1280 # "msg": "acpi: device unplug for unsupported device"
1281 # },
1282 # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
1283 #
1284 ##
1285 { 'event': 'MEM_UNPLUG_ERROR',
1286 'data': { 'device': 'str', 'msg': 'str' } }
1288 ##
1289 # @SMPConfiguration:
1290 #
1291 # Schema for CPU topology configuration. A missing value lets
1292 # QEMU figure out a suitable value based on the ones that are provided.
1293 #
1294 # @cpus: number of virtual CPUs in the virtual machine
1295 #
1296 # @sockets: number of sockets in the CPU topology
1297 #
1298 # @dies: number of dies per socket in the CPU topology
1299 #
1300 # @cores: number of cores per thread in the CPU topology
1301 #
1302 # @threads: number of threads per core in the CPU topology
1303 #
1304 # @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual machine
1305 #
1306 # Since: 6.1
1307 ##
1308 { 'struct': 'SMPConfiguration', 'data': {
1309 '*cpus': 'int',
1310 '*sockets': 'int',
1311 '*dies': 'int',
1312 '*cores': 'int',
1313 '*threads': 'int',
1314 '*maxcpus': 'int' } }