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.
11 { 'include': 'common.json' }
12 { 'include': 'machine-common.json' }
17 # The comprehensive enumeration of QEMU system emulation ("softmmu")
18 # targets. Run "./configure --help" in the project root directory,
19 # and look for the \*-softmmu targets near the "--target-list" option.
20 # The individual target constants are not documented here, for the
27 # .. note:: The resulting QMP strings can be appended to the
28 # "qemu-system-" prefix to produce the corresponding QEMU executable
29 # name. This is true even for "qemu-system-x86_64".
33 { 'enum' : 'SysEmuTarget',
34 'data' : [ 'aarch64', 'alpha', 'arm', 'avr', 'cris', 'hppa', 'i386',
35 'loongarch64', 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64',
36 'mips64el', 'mipsel', 'or1k', 'ppc',
37 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4',
38 'sh4eb', 'sparc', 'sparc64', 'tricore',
39 'x86_64', 'xtensa', 'xtensaeb' ] }
44 # An enumeration of cpu states that can be assumed by a virtual S390
49 { 'enum': 'CpuS390State',
50 'prefix': 'S390_CPU_STATE',
51 'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] }
56 # Additional information about a virtual S390 CPU
58 # @cpu-state: the virtual CPU's state
60 # @dedicated: the virtual CPU's dedication (since 8.2)
62 # @entitlement: the virtual CPU's entitlement (since 8.2)
66 { 'struct': 'CpuInfoS390',
67 'data': { 'cpu-state': 'CpuS390State',
69 '*entitlement': 'CpuS390Entitlement' } }
74 # Information about a virtual CPU
76 # @cpu-index: index of the virtual CPU
78 # @qom-path: path to the CPU object in the QOM tree
80 # @thread-id: ID of the underlying host thread
82 # @props: properties associated with a virtual CPU, e.g. the socket id
84 # @target: the QEMU system emulation target, which determines which
85 # additional fields will be listed (since 3.0)
89 { 'union' : 'CpuInfoFast',
90 'base' : { 'cpu-index' : 'int',
93 '*props' : 'CpuInstanceProperties',
94 'target' : 'SysEmuTarget' },
95 'discriminator' : 'target',
96 'data' : { 's390x' : 'CpuInfoS390' } }
101 # Returns information about all virtual CPUs.
103 # Returns: list of @CpuInfoFast
109 # -> { "execute": "query-cpus-fast" }
112 # "thread-id": 25627,
118 # "qom-path": "/machine/unattached/device[0]",
123 # "thread-id": 25628,
129 # "qom-path": "/machine/unattached/device[2]",
136 { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
141 # Property default values specific to a machine type, for use by
142 # scripts/compare-machine-types.
144 # @qom-type: name of the QOM type to which the default applies
146 # @property: name of its property to which the default applies
148 # @value: the default value (machine-specific default can overwrite
149 # the "default" default, to avoid this use -machine none)
153 { 'struct': 'CompatProperty',
154 'data': { 'qom-type': 'str',
161 # Information describing a machine.
163 # @name: the name of the machine
165 # @alias: an alias for the machine name
167 # @is-default: whether the machine is default
169 # @cpu-max: maximum number of CPUs supported by the machine type
172 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7)
174 # @numa-mem-supported: true if '-numa node,mem' option is supported by
175 # the machine type and false otherwise (since 4.1)
177 # @deprecated: if true, the machine type is deprecated and may be
178 # removed in future versions of QEMU according to the QEMU
179 # deprecation policy (since 4.1)
181 # @default-cpu-type: default CPU model typename if none is requested
182 # via the -cpu argument. (since 4.2)
184 # @default-ram-id: the default ID of initial RAM memory backend (since
187 # @acpi: machine type supports ACPI (since 8.0)
189 # @compat-props: The machine type's compatibility properties. Only
190 # present when query-machines argument @compat-props is true.
195 # @unstable: Member @compat-props is experimental.
199 { 'struct': 'MachineInfo',
200 'data': { 'name': 'str', '*alias': 'str',
201 '*is-default': 'bool', 'cpu-max': 'int',
202 'hotpluggable-cpus': 'bool', 'numa-mem-supported': 'bool',
203 'deprecated': 'bool', '*default-cpu-type': 'str',
204 '*default-ram-id': 'str', 'acpi': 'bool',
205 '*compat-props': { 'type': ['CompatProperty'],
206 'features': ['unstable'] } } }
211 # Return a list of supported machines
213 # @compat-props: if true, also return compatibility properties.
214 # (default: false) (since 9.1)
218 # @unstable: Argument @compat-props is experimental.
220 # Returns: a list of MachineInfo
226 # -> { "execute": "query-machines", "arguments": { "compat-props": true } }
229 # "hotpluggable-cpus": true,
230 # "name": "pc-q35-6.2",
233 # "qom-type": "virtio-mem",
234 # "property": "unplugged-inaccessible",
238 # "numa-mem-supported": false,
239 # "default-cpu-type": "qemu64-x86_64-cpu",
241 # "deprecated": false,
242 # "default-ram-id": "pc.ram"
247 { 'command': 'query-machines',
248 'data': { '*compat-props': { 'type': 'bool',
249 'features': [ 'unstable' ] } },
250 'returns': ['MachineInfo'] }
253 # @CurrentMachineParams:
255 # Information describing the running machine parameters.
257 # @wakeup-suspend-support: true if the machine supports wake up from
262 { 'struct': 'CurrentMachineParams',
263 'data': { 'wakeup-suspend-support': 'bool'} }
266 # @query-current-machine:
268 # Return information on the current virtual machine.
270 # Returns: CurrentMachineParams
274 { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
279 # Information describing the QEMU target.
281 # @arch: the target architecture
285 { 'struct': 'TargetInfo',
286 'data': { 'arch': 'SysEmuTarget' } }
291 # Return information about the target for this QEMU
293 # Returns: TargetInfo
297 { 'command': 'query-target', 'returns': 'TargetInfo' }
302 # Guest UUID information (Universally Unique Identifier).
304 # @UUID: the UUID of the guest
308 # .. note:: If no UUID was specified for the guest, a null UUID is
312 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
317 # Query the guest UUID information.
319 # Returns: The @UuidInfo for the guest
325 # -> { "execute": "query-uuid" }
326 # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
328 { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
335 # @guid: the globally unique identifier
339 { 'struct': 'GuidInfo', 'data': {'guid': 'str'} }
342 # @query-vm-generation-id:
344 # Show Virtual Machine Generation ID
348 { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' }
353 # Performs a hard reset of a guest.
359 # -> { "execute": "system_reset" }
360 # <- { "return": {} }
362 { 'command': 'system_reset' }
367 # Requests that a guest perform a powerdown operation.
371 # .. note:: A guest may or may not respond to this command. This
372 # command returning does not indicate that a guest has accepted the
373 # request or that it has shut down. Many guests will respond to this
374 # command by prompting the user in some way.
378 # -> { "execute": "system_powerdown" }
379 # <- { "return": {} }
381 { 'command': 'system_powerdown' }
386 # Wake up guest from suspend. If the guest has wake-up from suspend
387 # support enabled (wakeup-suspend-support flag from
388 # query-current-machine), wake-up guest from suspend if the guest is
389 # in SUSPENDED state. Return an error otherwise.
393 # .. note:: Prior to 4.0, this command does nothing in case the guest
398 # -> { "execute": "system_wakeup" }
399 # <- { "return": {} }
401 { 'command': 'system_wakeup' }
406 # Policy for handling lost ticks in timer devices. Ticks end up
407 # getting lost when, for example, the guest is paused.
409 # @discard: throw away the missed ticks and continue with future
410 # injection normally. The guest OS will see the timer jump ahead
411 # by a potentially quite significant amount all at once, as if the
412 # intervening chunk of time had simply not existed; needless to
413 # say, such a sudden jump can easily confuse a guest OS which is
414 # not specifically prepared to deal with it. Assuming the guest
415 # OS can deal correctly with the time jump, the time in the guest
416 # and in the host should now match.
418 # @delay: continue to deliver ticks at the normal rate. The guest OS
419 # will not notice anything is amiss, as from its point of view
420 # time will have continued to flow normally. The time in the
421 # guest should now be behind the time in the host by exactly the
422 # amount of time during which ticks have been missed.
424 # @slew: deliver ticks at a higher rate to catch up with the missed
425 # ticks. The guest OS will not notice anything is amiss, as from
426 # its point of view time will have continued to flow normally.
427 # Once the timer has managed to catch up with all the missing
428 # ticks, the time in the guest and in the host should match.
432 { 'enum': 'LostTickPolicy',
433 'data': ['discard', 'delay', 'slew' ] }
438 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or
439 # all CPUs (ppc64). The command fails when the guest doesn't support
444 # .. note:: Prior to 2.1, this command was only supported for x86 and
449 # -> { "execute": "inject-nmi" }
450 # <- { "return": {} }
452 { 'command': 'inject-nmi' }
457 # Information about support for KVM acceleration
459 # @enabled: true if KVM acceleration is active
461 # @present: true if KVM acceleration is built into this executable
465 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
470 # Returns information about KVM acceleration
478 # -> { "execute": "query-kvm" }
479 # <- { "return": { "enabled": true, "present": true } }
481 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
486 # @node: NUMA nodes configuration
488 # @dist: NUMA distance configuration (since 2.10)
490 # @cpu: property based CPU(s) to node mapping (Since: 2.10)
492 # @hmat-lb: memory latency and bandwidth information (Since: 5.0)
494 # @hmat-cache: memory side cache information (Since: 5.0)
498 { 'enum': 'NumaOptionsType',
499 'data': [ 'node', 'dist', 'cpu', 'hmat-lb', 'hmat-cache' ] }
504 # A discriminated record of NUMA options. (for OptsVisitor)
506 # @type: NUMA option type
510 { 'union': 'NumaOptions',
511 'base': { 'type': 'NumaOptionsType' },
512 'discriminator': 'type',
514 'node': 'NumaNodeOptions',
515 'dist': 'NumaDistOptions',
516 'cpu': 'NumaCpuOptions',
517 'hmat-lb': 'NumaHmatLBOptions',
518 'hmat-cache': 'NumaHmatCacheOptions' }}
523 # Create a guest NUMA node. (for OptsVisitor)
525 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
527 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin if
530 # @mem: memory size of this node; mutually exclusive with @memdev.
531 # Equally divide total memory among nodes if both @mem and @memdev
534 # @memdev: memory backend object. If specified for one node, it must
535 # be specified for all nodes.
537 # @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points
538 # to the nodeid which has the memory controller responsible for
539 # this NUMA node. This field provides additional information as
540 # to the initiator node that is closest (as in directly attached)
541 # to this node, and therefore has the best performance (since 5.0)
545 { 'struct': 'NumaNodeOptions',
551 '*initiator': 'uint16' }}
556 # Set the distance between 2 NUMA nodes.
558 # @src: source NUMA node.
560 # @dst: destination NUMA node.
562 # @val: NUMA distance from source node to destination node. When a
563 # node is unreachable from another node, set the distance between
568 { 'struct': 'NumaDistOptions',
575 # @CXLFixedMemoryWindowOptions:
577 # Create a CXL Fixed Memory Window
579 # @size: Size of the Fixed Memory Window in bytes. Must be a multiple
582 # @interleave-granularity: Number of contiguous bytes for which
583 # accesses will go to a given interleave target. Accepted values
584 # [256, 512, 1k, 2k, 4k, 8k, 16k]
586 # @targets: Target root bridge IDs from -device ...,id=<ID> for each
591 { 'struct': 'CXLFixedMemoryWindowOptions',
594 '*interleave-granularity': 'size',
595 'targets': ['str'] }}
600 # List of CXL Fixed Memory Windows.
602 # @cxl-fmw: List of CXLFixedMemoryWindowOptions
606 { 'struct' : 'CXLFMWProperties',
607 'data': { 'cxl-fmw': ['CXLFixedMemoryWindowOptions'] }
613 # A X86 32-bit register
617 { 'enum': 'X86CPURegister32',
618 'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
621 # @X86CPUFeatureWordInfo:
623 # Information about a X86 CPU feature word
625 # @cpuid-input-eax: Input EAX value for CPUID instruction for that
628 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
631 # @cpuid-register: Output register containing the feature bits
633 # @features: value of output register, containing the feature bits
637 { 'struct': 'X86CPUFeatureWordInfo',
638 'data': { 'cpuid-input-eax': 'int',
639 '*cpuid-input-ecx': 'int',
640 'cpuid-register': 'X86CPURegister32',
641 'features': 'int' } }
646 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
651 { 'struct': 'DummyForceArrays',
652 'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
657 # Option "-numa cpu" overrides default cpu to node mapping. It
658 # accepts the same set of cpu properties as returned by
659 # query-hotpluggable-cpus[].props, where node-id could be used to
660 # override default node mapping.
664 { 'struct': 'NumaCpuOptions',
665 'base': 'CpuInstanceProperties',
669 # @HmatLBMemoryHierarchy:
671 # The memory hierarchy in the System Locality Latency and Bandwidth
672 # Information Structure of HMAT (Heterogeneous Memory Attribute Table)
674 # For more information about @HmatLBMemoryHierarchy, see chapter
675 # 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
677 # @memory: the structure represents the memory performance
679 # @first-level: first level of memory side cache
681 # @second-level: second level of memory side cache
683 # @third-level: third level of memory side cache
687 { 'enum': 'HmatLBMemoryHierarchy',
688 'data': [ 'memory', 'first-level', 'second-level', 'third-level' ] }
693 # Data type in the System Locality Latency and Bandwidth Information
694 # Structure of HMAT (Heterogeneous Memory Attribute Table)
696 # For more information about @HmatLBDataType, see chapter 5.2.27.4:
697 # Table 5-146: Field "Data Type" of ACPI 6.3 spec.
699 # @access-latency: access latency (nanoseconds)
701 # @read-latency: read latency (nanoseconds)
703 # @write-latency: write latency (nanoseconds)
705 # @access-bandwidth: access bandwidth (Bytes per second)
707 # @read-bandwidth: read bandwidth (Bytes per second)
709 # @write-bandwidth: write bandwidth (Bytes per second)
713 { 'enum': 'HmatLBDataType',
714 'data': [ 'access-latency', 'read-latency', 'write-latency',
715 'access-bandwidth', 'read-bandwidth', 'write-bandwidth' ] }
718 # @NumaHmatLBOptions:
720 # Set the system locality latency and bandwidth information between
721 # Initiator and Target proximity Domains.
723 # For more information about @NumaHmatLBOptions, see chapter 5.2.27.4:
724 # Table 5-146 of ACPI 6.3 spec.
726 # @initiator: the Initiator Proximity Domain.
728 # @target: the Target Proximity Domain.
730 # @hierarchy: the Memory Hierarchy. Indicates the performance of
731 # memory or side cache.
733 # @data-type: presents the type of data, access/read/write latency or
736 # @latency: the value of latency from @initiator to @target proximity
737 # domain, the latency unit is "ns(nanosecond)".
739 # @bandwidth: the value of bandwidth between @initiator and @target
740 # proximity domain, the bandwidth unit is "Bytes per second".
744 { 'struct': 'NumaHmatLBOptions',
746 'initiator': 'uint16',
748 'hierarchy': 'HmatLBMemoryHierarchy',
749 'data-type': 'HmatLBDataType',
750 '*latency': 'uint64',
751 '*bandwidth': 'size' }}
754 # @HmatCacheAssociativity:
756 # Cache associativity in the Memory Side Cache Information Structure
759 # For more information of @HmatCacheAssociativity, see chapter
760 # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
762 # @none: None (no memory side cache in this proximity domain, or cache
763 # associativity unknown)
765 # @direct: Direct Mapped
767 # @complex: Complex Cache Indexing (implementation specific)
771 { 'enum': 'HmatCacheAssociativity',
772 'data': [ 'none', 'direct', 'complex' ] }
775 # @HmatCacheWritePolicy:
777 # Cache write policy in the Memory Side Cache Information Structure of
780 # For more information of @HmatCacheWritePolicy, see chapter 5.2.27.5:
781 # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
783 # @none: None (no memory side cache in this proximity domain, or cache
784 # write policy unknown)
786 # @write-back: Write Back (WB)
788 # @write-through: Write Through (WT)
792 { 'enum': 'HmatCacheWritePolicy',
793 'data': [ 'none', 'write-back', 'write-through' ] }
796 # @NumaHmatCacheOptions:
798 # Set the memory side cache information for a given memory domain.
800 # For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5:
801 # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
803 # @node-id: the memory proximity domain to which the memory belongs.
805 # @size: the size of memory side cache in bytes.
807 # @level: the cache level described in this structure.
809 # @associativity: the cache associativity,
810 # none/direct-mapped/complex(complex cache indexing).
812 # @policy: the write policy, none/write-back/write-through.
814 # @line: the cache Line size in bytes.
818 { 'struct': 'NumaHmatCacheOptions',
823 'associativity': 'HmatCacheAssociativity',
824 'policy': 'HmatCacheWritePolicy',
830 # Save a portion of guest memory to a file.
832 # @val: the virtual address of the guest to start from
834 # @size: the size of memory region to save
836 # @filename: the file to save the memory to as binary data
838 # @cpu-index: the index of the virtual CPU to use for translating the
839 # virtual address (defaults to CPU 0)
843 # .. caution:: Errors were not reliably returned until 1.1.
847 # -> { "execute": "memsave",
848 # "arguments": { "val": 10,
850 # "filename": "/tmp/virtual-mem-dump" } }
851 # <- { "return": {} }
853 { 'command': 'memsave',
854 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
859 # Save a portion of guest physical memory to a file.
861 # @val: the physical address of the guest to start from
863 # @size: the size of memory region to save
865 # @filename: the file to save the memory to as binary data
869 # .. caution:: Errors were not reliably returned until 1.1.
873 # -> { "execute": "pmemsave",
874 # "arguments": { "val": 10,
876 # "filename": "/tmp/physical-mem-dump" } }
877 # <- { "return": {} }
879 { 'command': 'pmemsave',
880 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
885 # Information about memory backend
887 # @id: backend's ID if backend has 'id' property (since 2.9)
889 # @size: memory backend size
891 # @merge: whether memory merge support is enabled
893 # @dump: whether memory backend's memory is included in a core dump
895 # @prealloc: whether memory was preallocated
897 # @share: whether memory is private to QEMU or shared (since 6.1)
899 # @reserve: whether swap space (or huge pages) was reserved if
900 # applicable. This corresponds to the user configuration and not
901 # the actual behavior implemented in the OS to perform the
902 # reservation. For example, Linux will never reserve swap space
903 # for shared file mappings. (since 6.1)
905 # @host-nodes: host nodes for its memory policy
907 # @policy: memory policy of memory backend
911 { 'struct': 'Memdev',
920 'host-nodes': ['uint16'],
921 'policy': 'HostMemPolicy' }}
926 # Returns information for all memory backends.
928 # Returns: a list of @Memdev.
934 # -> { "execute": "query-memdev" }
943 # "host-nodes": [0, 1],
952 # "host-nodes": [2, 3],
953 # "policy": "preferred"
958 { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
961 # @CpuInstanceProperties:
963 # List of properties to be used for hotplugging a CPU instance, it
964 # should be passed by management with device_add command when a CPU is
967 # Which members are optional and which mandatory depends on the
968 # architecture and board.
970 # For s390x see :ref:`cpu-topology-s390x`.
972 # The ids other than the node-id specify the position of the CPU
973 # within the CPU topology (as defined by the machine property "smp",
974 # thus see also type @SMPConfiguration)
976 # @node-id: NUMA node ID the CPU belongs to
978 # @drawer-id: drawer number within CPU topology the CPU belongs to
981 # @book-id: book number within parent container the CPU belongs to
984 # @socket-id: socket number within parent container the CPU belongs to
986 # @die-id: die number within the parent container the CPU belongs to
989 # @cluster-id: cluster number within the parent container the CPU
990 # belongs to (since 7.1)
992 # @module-id: module number within the parent container the CPU belongs
995 # @core-id: core number within the parent container the CPU belongs to
997 # @thread-id: thread number within the core the CPU belongs to
999 # .. note:: Management should be prepared to pass through additional
1000 # properties with device_add.
1004 { 'struct': 'CpuInstanceProperties',
1005 # Keep these in sync with the properties device_add accepts
1006 'data': { '*node-id': 'int',
1007 '*drawer-id': 'int',
1009 '*socket-id': 'int',
1011 '*cluster-id': 'int',
1012 '*module-id': 'int',
1021 # @type: CPU object type for usage with device_add command
1023 # @props: list of properties to be used for hotplugging CPU
1025 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU
1028 # @qom-path: link to existing CPU object if CPU is present or omitted
1029 # if CPU is not present.
1033 { 'struct': 'HotpluggableCPU',
1034 'data': { 'type': 'str',
1035 'vcpus-count': 'int',
1036 'props': 'CpuInstanceProperties',
1042 # @query-hotpluggable-cpus:
1044 # TODO: Better documentation; currently there is none.
1046 # Returns: a list of HotpluggableCPU objects.
1052 # For pseries machine type started with -smp 2,cores=2,maxcpus=4
1055 # -> { "execute": "query-hotpluggable-cpus" }
1057 # { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
1058 # "vcpus-count": 1 },
1059 # { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
1060 # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
1063 # For pc machine type started with -smp 1,maxcpus=2:
1065 # -> { "execute": "query-hotpluggable-cpus" }
1068 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1069 # "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
1072 # "qom-path": "/machine/unattached/device[0]",
1073 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1074 # "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
1078 # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2
1079 # -cpu qemu (Since: 2.11):
1081 # -> { "execute": "query-hotpluggable-cpus" }
1084 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
1085 # "props": { "core-id": 1 }
1088 # "qom-path": "/machine/unattached/device[0]",
1089 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
1090 # "props": { "core-id": 0 }
1094 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
1095 'allow-preconfig': true }
1100 # Runtime equivalent of '-numa' CLI option, available at preconfigure
1101 # stage to configure numa mapping before initializing machine.
1105 { 'command': 'set-numa-node', 'boxed': true,
1106 'data': 'NumaOptions',
1107 'allow-preconfig': true
1113 # Request the balloon driver to change its balloon size.
1115 # @value: the target logical size of the VM in bytes. We can deduce
1116 # the size of the balloon using this formula:
1118 # logical_vm_size = vm_ram_size - balloon_size
1120 # From it we have: balloon_size = vm_ram_size - @value
1123 # - If the balloon driver is enabled but not functional because
1124 # the KVM kernel module cannot support it, KVMMissingCap
1125 # - If no balloon device is present, DeviceNotActive
1127 # .. note:: This command just issues a request to the guest. When it
1128 # returns, the balloon size may not have changed. A guest can change
1129 # the balloon size independent of this command.
1135 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1136 # <- { "return": {} }
1138 # With a 2.5GiB guest this command inflated the ballon to 3GiB.
1140 { 'command': 'balloon', 'data': {'value': 'int'} }
1145 # Information about the guest balloon device.
1147 # @actual: the logical size of the VM in bytes Formula used:
1148 # logical_vm_size = vm_ram_size - balloon_size
1152 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
1157 # Return information about the balloon device.
1163 # - If the balloon driver is enabled but not functional because
1164 # the KVM kernel module cannot support it, KVMMissingCap
1165 # - If no balloon device is present, DeviceNotActive
1171 # -> { "execute": "query-balloon" }
1173 # "actual": 1073741824
1177 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
1182 # Emitted when the guest changes the actual BALLOON level. This value
1183 # is equivalent to the @actual field return by the 'query-balloon'
1186 # @actual: the logical size of the VM in bytes Formula used:
1187 # logical_vm_size = vm_ram_size - balloon_size
1189 # .. note:: This event is rate-limited.
1195 # <- { "event": "BALLOON_CHANGE",
1196 # "data": { "actual": 944766976 },
1197 # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
1199 { 'event': 'BALLOON_CHANGE',
1200 'data': { 'actual': 'int' } }
1205 # hv-balloon guest-provided memory status information.
1207 # @committed: the amount of memory in use inside the guest plus the
1208 # amount of the memory unusable inside the guest (ballooned out,
1211 # @available: the amount of the memory inside the guest available for
1212 # new allocations ("free")
1216 { 'struct': 'HvBalloonInfo',
1217 'data': { 'committed': 'size', 'available': 'size' } }
1220 # @query-hv-balloon-status-report:
1222 # Returns the hv-balloon driver data contained in the last received
1223 # "STATUS" message from the guest.
1229 # - If no hv-balloon device is present, guest memory status
1230 # reporting is not enabled or no guest memory status report
1231 # received yet, GenericError
1237 # -> { "execute": "query-hv-balloon-status-report" }
1239 # "committed": 816640000,
1240 # "available": 3333054464
1244 { 'command': 'query-hv-balloon-status-report', 'returns': 'HvBalloonInfo' }
1247 # @HV_BALLOON_STATUS_REPORT:
1249 # Emitted when the hv-balloon driver receives a "STATUS" message from
1252 # .. note:: This event is rate-limited.
1258 # <- { "event": "HV_BALLOON_STATUS_REPORT",
1259 # "data": { "committed": 816640000, "available": 3333054464 },
1260 # "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
1262 { 'event': 'HV_BALLOON_STATUS_REPORT',
1263 'data': 'HvBalloonInfo' }
1268 # Actual memory information in bytes.
1270 # @base-memory: size of "base" memory specified with command line
1273 # @plugged-memory: size of memory that can be hot-unplugged. This
1274 # field is omitted if target doesn't support memory hotplug (i.e.
1275 # CONFIG_MEM_DEVICE not defined at build time).
1279 { 'struct': 'MemoryInfo',
1280 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } }
1283 # @query-memory-size-summary:
1285 # Return the amount of initially allocated and present hotpluggable
1286 # (if enabled) memory in bytes.
1290 # -> { "execute": "query-memory-size-summary" }
1291 # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
1295 { 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
1298 # @PCDIMMDeviceInfo:
1300 # PCDIMMDevice state information
1304 # @addr: physical address, where device is mapped
1306 # @size: size of memory that the device provides
1308 # @slot: slot number at which device is plugged in
1310 # @node: NUMA node number where device is plugged in
1312 # @memdev: memory backend linked with device
1314 # @hotplugged: true if device was hotplugged
1316 # @hotpluggable: true if device if could be added/removed while
1317 # machine is running
1321 { 'struct': 'PCDIMMDeviceInfo',
1322 'data': { '*id': 'str',
1328 'hotplugged': 'bool',
1329 'hotpluggable': 'bool'
1334 # @VirtioPMEMDeviceInfo:
1336 # VirtioPMEM state information
1340 # @memaddr: physical address in memory, where device is mapped
1342 # @size: size of memory that the device provides
1344 # @memdev: memory backend linked with device
1348 { 'struct': 'VirtioPMEMDeviceInfo',
1349 'data': { '*id': 'str',
1357 # @VirtioMEMDeviceInfo:
1359 # VirtioMEMDevice state information
1363 # @memaddr: physical address in memory, where device is mapped
1365 # @requested-size: the user requested size of the device
1367 # @size: the (current) size of memory that the device provides
1369 # @max-size: the maximum size of memory that the device can provide
1371 # @block-size: the block size of memory that the device provides
1373 # @node: NUMA node number where device is assigned to
1375 # @memdev: memory backend linked with the region
1379 { 'struct': 'VirtioMEMDeviceInfo',
1380 'data': { '*id': 'str',
1382 'requested-size': 'size',
1385 'block-size': 'size',
1392 # @SgxEPCDeviceInfo:
1394 # Sgx EPC state information
1398 # @memaddr: physical address in memory, where device is mapped
1400 # @size: size of memory that the device provides
1402 # @memdev: memory backend linked with device
1404 # @node: the numa node (Since: 7.0)
1408 { 'struct': 'SgxEPCDeviceInfo',
1409 'data': { '*id': 'str',
1418 # @HvBalloonDeviceInfo:
1420 # hv-balloon provided memory state information
1424 # @memaddr: physical address in memory, where device is mapped
1426 # @max-size: the maximum size of memory that the device can provide
1428 # @memdev: memory backend linked with device
1432 { 'struct': 'HvBalloonDeviceInfo',
1433 'data': { '*id': 'str',
1441 # @MemoryDeviceInfoKind:
1443 # @nvdimm: since 2.12
1445 # @virtio-pmem: since 4.1
1447 # @virtio-mem: since 5.1
1449 # @sgx-epc: since 6.2.
1451 # @hv-balloon: since 8.2.
1455 { 'enum': 'MemoryDeviceInfoKind',
1456 'data': [ 'dimm', 'nvdimm', 'virtio-pmem', 'virtio-mem', 'sgx-epc',
1460 # @PCDIMMDeviceInfoWrapper:
1462 # @data: PCDIMMDevice state information
1466 { 'struct': 'PCDIMMDeviceInfoWrapper',
1467 'data': { 'data': 'PCDIMMDeviceInfo' } }
1470 # @VirtioPMEMDeviceInfoWrapper:
1472 # @data: VirtioPMEM state information
1476 { 'struct': 'VirtioPMEMDeviceInfoWrapper',
1477 'data': { 'data': 'VirtioPMEMDeviceInfo' } }
1480 # @VirtioMEMDeviceInfoWrapper:
1482 # @data: VirtioMEMDevice state information
1486 { 'struct': 'VirtioMEMDeviceInfoWrapper',
1487 'data': { 'data': 'VirtioMEMDeviceInfo' } }
1490 # @SgxEPCDeviceInfoWrapper:
1492 # @data: Sgx EPC state information
1496 { 'struct': 'SgxEPCDeviceInfoWrapper',
1497 'data': { 'data': 'SgxEPCDeviceInfo' } }
1500 # @HvBalloonDeviceInfoWrapper:
1502 # @data: hv-balloon provided memory state information
1506 { 'struct': 'HvBalloonDeviceInfoWrapper',
1507 'data': { 'data': 'HvBalloonDeviceInfo' } }
1510 # @MemoryDeviceInfo:
1512 # Union containing information about a memory device
1514 # @type: memory device type
1518 { 'union': 'MemoryDeviceInfo',
1519 'base': { 'type': 'MemoryDeviceInfoKind' },
1520 'discriminator': 'type',
1521 'data': { 'dimm': 'PCDIMMDeviceInfoWrapper',
1522 'nvdimm': 'PCDIMMDeviceInfoWrapper',
1523 'virtio-pmem': 'VirtioPMEMDeviceInfoWrapper',
1524 'virtio-mem': 'VirtioMEMDeviceInfoWrapper',
1525 'sgx-epc': 'SgxEPCDeviceInfoWrapper',
1526 'hv-balloon': 'HvBalloonDeviceInfoWrapper'
1533 # Sgx EPC cmdline information
1535 # @memdev: memory backend linked with device
1537 # @node: the numa node (Since: 7.0)
1541 { 'struct': 'SgxEPC',
1542 'data': { 'memdev': 'str',
1548 # @SgxEPCProperties:
1550 # SGX properties of machine types.
1552 # @sgx-epc: list of ids of memory-backend-epc objects.
1556 { 'struct': 'SgxEPCProperties',
1557 'data': { 'sgx-epc': ['SgxEPC'] }
1561 # @query-memory-devices:
1563 # Lists available memory devices and their state
1569 # -> { "execute": "query-memory-devices" }
1570 # <- { "return": [ { "data":
1571 # { "addr": 5368709120,
1572 # "hotpluggable": true,
1573 # "hotplugged": true,
1575 # "memdev": "/objects/memX",
1577 # "size": 1073741824,
1582 { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
1585 # @MEMORY_DEVICE_SIZE_CHANGE:
1587 # Emitted when the size of a memory device changes. Only emitted for
1588 # memory devices that can actually change the size (e.g., virtio-mem
1589 # due to guest action).
1593 # @size: the new size of memory that the device provides
1595 # @qom-path: path to the device object in the QOM tree (since 6.2)
1597 # .. note:: This event is rate-limited.
1603 # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
1604 # "data": { "id": "vm0", "size": 1073741824,
1605 # "qom-path": "/machine/unattached/device[2]" },
1606 # "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
1608 { 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
1609 'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} }
1612 # @BootConfiguration:
1614 # Schema for virtual machine boot configuration.
1616 # @order: Boot order (a=floppy, c=hard disk, d=CD-ROM, n=network)
1618 # @once: Boot order to apply on first boot
1620 # @menu: Whether to show a boot menu
1622 # @splash: The name of the file to be passed to the firmware as logo
1623 # picture, if @menu is true.
1625 # @splash-time: How long to show the logo picture, in milliseconds
1627 # @reboot-timeout: Timeout before guest reboots after boot fails
1629 # @strict: Whether to attempt booting from devices not included in the
1634 { 'struct': 'BootConfiguration', 'data': {
1639 '*splash-time': 'int',
1640 '*reboot-timeout': 'int',
1641 '*strict': 'bool' } }
1644 # @SMPConfiguration:
1646 # Schema for CPU topology configuration. A missing value lets QEMU
1647 # figure out a suitable value based on the ones that are provided.
1649 # The members other than @cpus and @maxcpus define a topology of
1652 # The ordering from highest/coarsest to lowest/finest is:
1653 # @drawers, @books, @sockets, @dies, @clusters, @cores, @threads.
1655 # Different architectures support different subsets of topology
1658 # For example, s390x does not have clusters and dies, and the socket
1659 # is the parent container of cores.
1661 # @cpus: number of virtual CPUs in the virtual machine
1663 # @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual
1666 # @drawers: number of drawers in the CPU topology (since 8.2)
1668 # @books: number of books in the CPU topology (since 8.2)
1670 # @sockets: number of sockets per parent container
1672 # @dies: number of dies per parent container
1674 # @clusters: number of clusters per parent container (since 7.0)
1676 # @modules: number of modules per parent container (since 9.1)
1678 # @cores: number of cores per parent container
1680 # @threads: number of threads per core
1684 { 'struct': 'SMPConfiguration', 'data': {
1694 '*maxcpus': 'int' } }
1699 # Query interrupt statistics
1703 # @unstable: This command is meant for debugging.
1705 # Returns: interrupt statistics
1709 { 'command': 'x-query-irq',
1710 'returns': 'HumanReadableText',
1711 'features': [ 'unstable' ] }
1716 # Query TCG compiler statistics
1720 # @unstable: This command is meant for debugging.
1722 # Returns: TCG compiler statistics
1726 { 'command': 'x-query-jit',
1727 'returns': 'HumanReadableText',
1729 'features': [ 'unstable' ] }
1734 # Query NUMA topology information
1738 # @unstable: This command is meant for debugging.
1740 # Returns: topology information
1744 { 'command': 'x-query-numa',
1745 'returns': 'HumanReadableText',
1746 'features': [ 'unstable' ] }
1751 # Query TCG opcode counters
1755 # @unstable: This command is meant for debugging.
1757 # Returns: TCG opcode counters
1761 { 'command': 'x-query-opcount',
1762 'returns': 'HumanReadableText',
1764 'features': [ 'unstable' ] }
1767 # @x-query-ramblock:
1769 # Query system ramblock information
1773 # @unstable: This command is meant for debugging.
1775 # Returns: system ramblock information
1779 { 'command': 'x-query-ramblock',
1780 'returns': 'HumanReadableText',
1781 'features': [ 'unstable' ] }
1786 # Query information on the registered ROMS
1790 # @unstable: This command is meant for debugging.
1792 # Returns: registered ROMs
1796 { 'command': 'x-query-roms',
1797 'returns': 'HumanReadableText',
1798 'features': [ 'unstable' ] }
1803 # Query information on the USB devices
1807 # @unstable: This command is meant for debugging.
1809 # Returns: USB device information
1813 { 'command': 'x-query-usb',
1814 'returns': 'HumanReadableText',
1815 'features': [ 'unstable' ] }
1818 # @SmbiosEntryPointType:
1820 # @32: SMBIOS version 2.1 (32-bit) Entry Point
1822 # @64: SMBIOS version 3.0 (64-bit) Entry Point
1824 # @auto: Either 2.x or 3.x SMBIOS version, 2.x if configuration can be
1825 # described by it and 3.x otherwise (since: 9.0)
1829 { 'enum': 'SmbiosEntryPointType',
1830 'data': [ '32', '64', 'auto' ] }
1833 # @MemorySizeConfiguration:
1835 # Schema for memory size configuration.
1837 # @size: memory size in bytes
1839 # @max-size: maximum hotpluggable memory size in bytes
1841 # @slots: number of available memory slots for hotplug
1845 { 'struct': 'MemorySizeConfiguration', 'data': {
1847 '*max-size': 'size',
1848 '*slots': 'uint64' } }
1853 # Save the FDT in dtb format.
1855 # @filename: name of the dtb file to be created
1861 # -> { "execute": "dumpdtb" }
1862 # "arguments": { "filename": "fdt.dtb" } }
1863 # <- { "return": {} }
1865 { 'command': 'dumpdtb',
1866 'data': { 'filename': 'str' },
1867 'if': 'CONFIG_FDT' }
1870 # @x-query-interrupt-controllers:
1872 # Query information on interrupt controller devices
1876 # @unstable: This command is meant for debugging.
1878 # Returns: Interrupt controller devices information
1882 { 'command': 'x-query-interrupt-controllers',
1883 'returns': 'HumanReadableText',
1884 'features': [ 'unstable' ]}