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 # @loongarch64: since 7.1
29 # .. note:: The resulting QMP strings can be appended to the
30 # "qemu-system-" prefix to produce the corresponding QEMU
31 # executable name. This is true even for "qemu-system-x86_64".
35 { 'enum' : 'SysEmuTarget',
36 'data' : [ 'aarch64', 'alpha', 'arm', 'avr', 'cris', 'hppa', 'i386',
37 'loongarch64', 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64',
38 'mips64el', 'mipsel', 'or1k', 'ppc',
39 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4',
40 'sh4eb', 'sparc', 'sparc64', 'tricore',
41 'x86_64', 'xtensa', 'xtensaeb' ] }
46 # An enumeration of cpu states that can be assumed by a virtual S390
51 { 'enum': 'CpuS390State',
52 'prefix': 'S390_CPU_STATE',
53 'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] }
58 # Additional information about a virtual S390 CPU
60 # @cpu-state: the virtual CPU's state
62 # @dedicated: the virtual CPU's dedication (since 8.2)
64 # @entitlement: the virtual CPU's entitlement (since 8.2)
68 { 'struct': 'CpuInfoS390',
69 'data': { 'cpu-state': 'CpuS390State',
71 '*entitlement': 'CpuS390Entitlement' } }
76 # Information about a virtual CPU
78 # @cpu-index: index of the virtual CPU
80 # @qom-path: path to the CPU object in the QOM tree
82 # @thread-id: ID of the underlying host thread
84 # @props: properties associated with a virtual CPU, e.g. the socket id
86 # @target: the QEMU system emulation target, which determines which
87 # additional fields will be listed (since 3.0)
91 { 'union' : 'CpuInfoFast',
92 'base' : { 'cpu-index' : 'int',
95 '*props' : 'CpuInstanceProperties',
96 'target' : 'SysEmuTarget' },
97 'discriminator' : 'target',
98 'data' : { 's390x' : 'CpuInfoS390' } }
103 # Returns information about all virtual CPUs.
105 # Returns: list of @CpuInfoFast
111 # -> { "execute": "query-cpus-fast" }
114 # "thread-id": 25627,
120 # "qom-path": "/machine/unattached/device[0]",
125 # "thread-id": 25628,
131 # "qom-path": "/machine/unattached/device[2]",
138 { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
143 # Property default values specific to a machine type, for use by
144 # scripts/compare-machine-types.
146 # @qom-type: name of the QOM type to which the default applies
148 # @property: name of its property to which the default applies
150 # @value: the default value (machine-specific default can overwrite
151 # the "default" default, to avoid this use -machine none)
155 { 'struct': 'CompatProperty',
156 'data': { 'qom-type': 'str',
163 # Information describing a machine.
165 # @name: the name of the machine
167 # @alias: an alias for the machine name
169 # @is-default: whether the machine is default
171 # @cpu-max: maximum number of CPUs supported by the machine type
174 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7)
176 # @numa-mem-supported: true if '-numa node,mem' option is supported by
177 # the machine type and false otherwise (since 4.1)
179 # @deprecated: if true, the machine type is deprecated and may be
180 # removed in future versions of QEMU according to the QEMU
181 # deprecation policy (since 4.1)
183 # @default-cpu-type: default CPU model typename if none is requested
184 # via the -cpu argument. (since 4.2)
186 # @default-ram-id: the default ID of initial RAM memory backend (since
189 # @acpi: machine type supports ACPI (since 8.0)
191 # @compat-props: The machine type's compatibility properties. Only
192 # present when query-machines argument @compat-props is true.
197 # @unstable: Member @compat-props is experimental.
201 { 'struct': 'MachineInfo',
202 'data': { 'name': 'str', '*alias': 'str',
203 '*is-default': 'bool', 'cpu-max': 'int',
204 'hotpluggable-cpus': 'bool', 'numa-mem-supported': 'bool',
205 'deprecated': 'bool', '*default-cpu-type': 'str',
206 '*default-ram-id': 'str', 'acpi': 'bool',
207 '*compat-props': { 'type': ['CompatProperty'],
208 'features': ['unstable'] } } }
213 # Return a list of supported machines
215 # @compat-props: if true, also return compatibility properties.
216 # (default: false) (since 9.1)
220 # @unstable: Argument @compat-props is experimental.
222 # Returns: a list of MachineInfo
228 # -> { "execute": "query-machines", "arguments": { "compat-props": true } }
231 # "hotpluggable-cpus": true,
232 # "name": "pc-q35-6.2",
235 # "qom-type": "virtio-mem",
236 # "property": "unplugged-inaccessible",
240 # "numa-mem-supported": false,
241 # "default-cpu-type": "qemu64-x86_64-cpu",
243 # "deprecated": false,
244 # "default-ram-id": "pc.ram"
249 { 'command': 'query-machines',
250 'data': { '*compat-props': { 'type': 'bool',
251 'features': [ 'unstable' ] } },
252 'returns': ['MachineInfo'] }
255 # @CurrentMachineParams:
257 # Information describing the running machine parameters.
259 # @wakeup-suspend-support: true if the machine supports wake up from
264 { 'struct': 'CurrentMachineParams',
265 'data': { 'wakeup-suspend-support': 'bool'} }
268 # @query-current-machine:
270 # Return information on the current virtual machine.
272 # Returns: CurrentMachineParams
276 { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
281 # Information describing the QEMU target.
283 # @arch: the target architecture
287 { 'struct': 'TargetInfo',
288 'data': { 'arch': 'SysEmuTarget' } }
293 # Return information about the target for this QEMU
295 # Returns: TargetInfo
299 { 'command': 'query-target', 'returns': 'TargetInfo' }
304 # Guest UUID information (Universally Unique Identifier).
306 # @UUID: the UUID of the guest
310 # .. note:: If no UUID was specified for the guest, the nil UUID (all
311 # zeroes) is returned.
313 { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
318 # Query the guest UUID information.
320 # Returns: The @UuidInfo for the guest
326 # -> { "execute": "query-uuid" }
327 # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
329 { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true }
336 # @guid: the globally unique identifier
340 { 'struct': 'GuidInfo', 'data': {'guid': 'str'} }
343 # @query-vm-generation-id:
345 # Show Virtual Machine Generation ID
349 { 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' }
354 # Performs a hard reset of a guest.
360 # -> { "execute": "system_reset" }
361 # <- { "return": {} }
363 { 'command': 'system_reset' }
368 # Requests that a guest perform a powerdown operation.
372 # .. note:: A guest may or may not respond to this command. This
373 # command returning does not indicate that a guest has accepted the
374 # request or that it has shut down. Many guests will respond to
375 # this command by prompting the user in some way.
379 # -> { "execute": "system_powerdown" }
380 # <- { "return": {} }
382 { 'command': 'system_powerdown' }
387 # Wake up guest from suspend. If the guest has wake-up from suspend
388 # support enabled (wakeup-suspend-support flag from
389 # query-current-machine), wake-up guest from suspend if the guest is
390 # in SUSPENDED state. Return an error otherwise.
394 # .. note:: Prior to 4.0, this command does nothing in case the guest
399 # -> { "execute": "system_wakeup" }
400 # <- { "return": {} }
402 { 'command': 'system_wakeup' }
407 # Policy for handling lost ticks in timer devices. Ticks end up
408 # getting lost when, for example, the guest is paused.
410 # @discard: throw away the missed ticks and continue with future
411 # injection normally. The guest OS will see the timer jump ahead
412 # by a potentially quite significant amount all at once, as if the
413 # intervening chunk of time had simply not existed; needless to
414 # say, such a sudden jump can easily confuse a guest OS which is
415 # not specifically prepared to deal with it. Assuming the guest
416 # OS can deal correctly with the time jump, the time in the guest
417 # and in the host should now match.
419 # @delay: continue to deliver ticks at the normal rate. The guest OS
420 # will not notice anything is amiss, as from its point of view
421 # time will have continued to flow normally. The time in the
422 # guest should now be behind the time in the host by exactly the
423 # amount of time during which ticks have been missed.
425 # @slew: deliver ticks at a higher rate to catch up with the missed
426 # ticks. The guest OS will not notice anything is amiss, as from
427 # its point of view time will have continued to flow normally.
428 # Once the timer has managed to catch up with all the missing
429 # ticks, the time in the guest and in the host should match.
433 { 'enum': 'LostTickPolicy',
434 'data': ['discard', 'delay', 'slew' ] }
439 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or
440 # all CPUs (ppc64). The command fails when the guest doesn't support
445 # .. note:: Prior to 2.1, this command was only supported for x86 and
450 # -> { "execute": "inject-nmi" }
451 # <- { "return": {} }
453 { 'command': 'inject-nmi' }
458 # Information about support for KVM acceleration
460 # @enabled: true if KVM acceleration is active
462 # @present: true if KVM acceleration is built into this executable
466 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
471 # Returns information about KVM acceleration
479 # -> { "execute": "query-kvm" }
480 # <- { "return": { "enabled": true, "present": true } }
482 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
487 # @node: NUMA nodes configuration
489 # @dist: NUMA distance configuration (since 2.10)
491 # @cpu: property based CPU(s) to node mapping (Since: 2.10)
493 # @hmat-lb: memory latency and bandwidth information (Since: 5.0)
495 # @hmat-cache: memory side cache information (Since: 5.0)
499 { 'enum': 'NumaOptionsType',
500 'data': [ 'node', 'dist', 'cpu', 'hmat-lb', 'hmat-cache' ] }
505 # A discriminated record of NUMA options. (for OptsVisitor)
507 # @type: NUMA option type
511 { 'union': 'NumaOptions',
512 'base': { 'type': 'NumaOptionsType' },
513 'discriminator': 'type',
515 'node': 'NumaNodeOptions',
516 'dist': 'NumaDistOptions',
517 'cpu': 'NumaCpuOptions',
518 'hmat-lb': 'NumaHmatLBOptions',
519 'hmat-cache': 'NumaHmatCacheOptions' }}
524 # Create a guest NUMA node. (for OptsVisitor)
526 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
528 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin if
531 # @mem: memory size of this node; mutually exclusive with @memdev.
532 # Equally divide total memory among nodes if both @mem and @memdev
535 # @memdev: memory backend object. If specified for one node, it must
536 # be specified for all nodes.
538 # @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points
539 # to the nodeid which has the memory controller responsible for
540 # this NUMA node. This field provides additional information as
541 # to the initiator node that is closest (as in directly attached)
542 # to this node, and therefore has the best performance (since 5.0)
546 { 'struct': 'NumaNodeOptions',
552 '*initiator': 'uint16' }}
557 # Set the distance between 2 NUMA nodes.
559 # @src: source NUMA node.
561 # @dst: destination NUMA node.
563 # @val: NUMA distance from source node to destination node. When a
564 # node is unreachable from another node, set the distance between
569 { 'struct': 'NumaDistOptions',
576 # @CXLFixedMemoryWindowOptions:
578 # Create a CXL Fixed Memory Window
580 # @size: Size of the Fixed Memory Window in bytes. Must be a multiple
583 # @interleave-granularity: Number of contiguous bytes for which
584 # accesses will go to a given interleave target. Accepted values
585 # [256, 512, 1k, 2k, 4k, 8k, 16k]
587 # @targets: Target root bridge IDs from -device ...,id=<ID> for each
592 { 'struct': 'CXLFixedMemoryWindowOptions',
595 '*interleave-granularity': 'size',
596 'targets': ['str'] }}
601 # List of CXL Fixed Memory Windows.
603 # @cxl-fmw: List of CXLFixedMemoryWindowOptions
607 { 'struct' : 'CXLFMWProperties',
608 'data': { 'cxl-fmw': ['CXLFixedMemoryWindowOptions'] }
614 # A X86 32-bit register
618 { 'enum': 'X86CPURegister32',
619 'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
622 # @X86CPUFeatureWordInfo:
624 # Information about a X86 CPU feature word
626 # @cpuid-input-eax: Input EAX value for CPUID instruction for that
629 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
632 # @cpuid-register: Output register containing the feature bits
634 # @features: value of output register, containing the feature bits
638 { 'struct': 'X86CPUFeatureWordInfo',
639 'data': { 'cpuid-input-eax': 'int',
640 '*cpuid-input-ecx': 'int',
641 'cpuid-register': 'X86CPURegister32',
642 'features': 'int' } }
647 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
652 { 'struct': 'DummyForceArrays',
653 'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
658 # Option "-numa cpu" overrides default cpu to node mapping. It
659 # accepts the same set of cpu properties as returned by
660 # query-hotpluggable-cpus[].props, where node-id could be used to
661 # override default node mapping.
665 { 'struct': 'NumaCpuOptions',
666 'base': 'CpuInstanceProperties',
670 # @HmatLBMemoryHierarchy:
672 # The memory hierarchy in the System Locality Latency and Bandwidth
673 # Information Structure of HMAT (Heterogeneous Memory Attribute Table)
675 # For more information about @HmatLBMemoryHierarchy, see chapter
676 # 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
678 # @memory: the structure represents the memory performance
680 # @first-level: first level of memory side cache
682 # @second-level: second level of memory side cache
684 # @third-level: third level of memory side cache
688 { 'enum': 'HmatLBMemoryHierarchy',
689 'data': [ 'memory', 'first-level', 'second-level', 'third-level' ] }
694 # Data type in the System Locality Latency and Bandwidth Information
695 # Structure of HMAT (Heterogeneous Memory Attribute Table)
697 # For more information about @HmatLBDataType, see chapter 5.2.27.4:
698 # Table 5-146: Field "Data Type" of ACPI 6.3 spec.
700 # @access-latency: access latency (nanoseconds)
702 # @read-latency: read latency (nanoseconds)
704 # @write-latency: write latency (nanoseconds)
706 # @access-bandwidth: access bandwidth (Bytes per second)
708 # @read-bandwidth: read bandwidth (Bytes per second)
710 # @write-bandwidth: write bandwidth (Bytes per second)
714 { 'enum': 'HmatLBDataType',
715 'data': [ 'access-latency', 'read-latency', 'write-latency',
716 'access-bandwidth', 'read-bandwidth', 'write-bandwidth' ] }
719 # @NumaHmatLBOptions:
721 # Set the system locality latency and bandwidth information between
722 # Initiator and Target proximity Domains.
724 # For more information about @NumaHmatLBOptions, see chapter 5.2.27.4:
725 # Table 5-146 of ACPI 6.3 spec.
727 # @initiator: the Initiator Proximity Domain.
729 # @target: the Target Proximity Domain.
731 # @hierarchy: the Memory Hierarchy. Indicates the performance of
732 # memory or side cache.
734 # @data-type: presents the type of data, access/read/write latency or
737 # @latency: the value of latency from @initiator to @target proximity
738 # domain, the latency unit is "ns(nanosecond)".
740 # @bandwidth: the value of bandwidth between @initiator and @target
741 # proximity domain, the bandwidth unit is "Bytes per second".
745 { 'struct': 'NumaHmatLBOptions',
747 'initiator': 'uint16',
749 'hierarchy': 'HmatLBMemoryHierarchy',
750 'data-type': 'HmatLBDataType',
751 '*latency': 'uint64',
752 '*bandwidth': 'size' }}
755 # @HmatCacheAssociativity:
757 # Cache associativity in the Memory Side Cache Information Structure
760 # For more information of @HmatCacheAssociativity, see chapter
761 # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
763 # @none: None (no memory side cache in this proximity domain, or cache
764 # associativity unknown)
766 # @direct: Direct Mapped
768 # @complex: Complex Cache Indexing (implementation specific)
772 { 'enum': 'HmatCacheAssociativity',
773 'data': [ 'none', 'direct', 'complex' ] }
776 # @HmatCacheWritePolicy:
778 # Cache write policy in the Memory Side Cache Information Structure of
781 # For more information of @HmatCacheWritePolicy, see chapter 5.2.27.5:
782 # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
784 # @none: None (no memory side cache in this proximity domain, or cache
785 # write policy unknown)
787 # @write-back: Write Back (WB)
789 # @write-through: Write Through (WT)
793 { 'enum': 'HmatCacheWritePolicy',
794 'data': [ 'none', 'write-back', 'write-through' ] }
797 # @NumaHmatCacheOptions:
799 # Set the memory side cache information for a given memory domain.
801 # For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5:
802 # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
804 # @node-id: the memory proximity domain to which the memory belongs.
806 # @size: the size of memory side cache in bytes.
808 # @level: the cache level described in this structure.
810 # @associativity: the cache associativity,
811 # none/direct-mapped/complex(complex cache indexing).
813 # @policy: the write policy, none/write-back/write-through.
815 # @line: the cache Line size in bytes.
819 { 'struct': 'NumaHmatCacheOptions',
824 'associativity': 'HmatCacheAssociativity',
825 'policy': 'HmatCacheWritePolicy',
831 # Save a portion of guest memory to a file.
833 # @val: the virtual address of the guest to start from
835 # @size: the size of memory region to save
837 # @filename: the file to save the memory to as binary data
839 # @cpu-index: the index of the virtual CPU to use for translating the
840 # virtual address (defaults to CPU 0)
844 # .. caution:: Errors were not reliably returned until 1.1.
848 # -> { "execute": "memsave",
849 # "arguments": { "val": 10,
851 # "filename": "/tmp/virtual-mem-dump" } }
852 # <- { "return": {} }
854 { 'command': 'memsave',
859 '*cpu-index': 'int' } }
864 # Save a portion of guest physical memory to a file.
866 # @val: the physical address of the guest to start from
868 # @size: the size of memory region to save
870 # @filename: the file to save the memory to as binary data
874 # .. caution:: Errors were not reliably returned until 1.1.
878 # -> { "execute": "pmemsave",
879 # "arguments": { "val": 10,
881 # "filename": "/tmp/physical-mem-dump" } }
882 # <- { "return": {} }
884 { 'command': 'pmemsave',
888 'filename': 'str' } }
893 # Information about memory backend
895 # @id: backend's ID if backend has 'id' property (since 2.9)
897 # @size: memory backend size
899 # @merge: whether memory merge support is enabled
901 # @dump: whether memory backend's memory is included in a core dump
903 # @prealloc: whether memory was preallocated
905 # @share: whether memory is private to QEMU or shared (since 6.1)
907 # @reserve: whether swap space (or huge pages) was reserved if
908 # applicable. This corresponds to the user configuration and not
909 # the actual behavior implemented in the OS to perform the
910 # reservation. For example, Linux will never reserve swap space
911 # for shared file mappings. (since 6.1)
913 # @host-nodes: host nodes for its memory policy
915 # @policy: memory policy of memory backend
919 { 'struct': 'Memdev',
928 'host-nodes': ['uint16'],
929 'policy': 'HostMemPolicy' }}
934 # Returns information for all memory backends.
936 # Returns: a list of @Memdev.
942 # -> { "execute": "query-memdev" }
951 # "host-nodes": [0, 1],
960 # "host-nodes": [2, 3],
961 # "policy": "preferred"
966 { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
969 # @CpuInstanceProperties:
971 # Properties identifying a CPU.
973 # Which members are optional and which mandatory depends on the
974 # architecture and board.
976 # For s390x see :ref:`cpu-topology-s390x`.
978 # The ids other than the node-id specify the position of the CPU
979 # within the CPU topology (as defined by the machine property "smp",
980 # thus see also type @SMPConfiguration)
982 # @node-id: NUMA node ID the CPU belongs to
984 # @drawer-id: drawer number within CPU topology the CPU belongs to
987 # @book-id: book number within parent container the CPU belongs to
990 # @socket-id: socket number within parent container the CPU belongs to
992 # @die-id: die number within the parent container the CPU belongs to
995 # @cluster-id: cluster number within the parent container the CPU
996 # belongs to (since 7.1)
998 # @module-id: module number within the parent container the CPU
999 # belongs to (since 9.1)
1001 # @core-id: core number within the parent container the CPU belongs to
1003 # @thread-id: thread number within the core the CPU belongs to
1007 { 'struct': 'CpuInstanceProperties',
1008 # Keep these in sync with the properties device_add accepts
1009 'data': { '*node-id': 'int',
1010 '*drawer-id': 'int',
1012 '*socket-id': 'int',
1014 '*cluster-id': 'int',
1015 '*module-id': 'int',
1024 # @type: CPU object type for usage with device_add command
1026 # @props: list of properties to pass for hotplugging a CPU with
1029 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU
1032 # @qom-path: link to existing CPU object if CPU is present or omitted
1033 # if CPU is not present.
1035 # .. note:: Management should be prepared to pass through additional
1036 # properties with device_add.
1040 { 'struct': 'HotpluggableCPU',
1041 'data': { 'type': 'str',
1042 'vcpus-count': 'int',
1043 'props': 'CpuInstanceProperties',
1049 # @query-hotpluggable-cpus:
1051 # TODO: Better documentation; currently there is none.
1053 # Returns: a list of HotpluggableCPU objects.
1060 # For pseries machine type started with
1061 # ``-smp 2,cores=2,maxcpus=4 -cpu POWER8``::
1063 # -> { "execute": "query-hotpluggable-cpus" }
1065 # { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
1066 # "vcpus-count": 1 },
1067 # { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
1068 # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
1074 # For pc machine type started with ``-smp 1,maxcpus=2``::
1076 # -> { "execute": "query-hotpluggable-cpus" }
1079 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1080 # "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
1083 # "qom-path": "/machine/unattached/device[0]",
1084 # "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1085 # "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
1092 # For s390x-virtio-ccw machine type started with
1093 # ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11)::
1095 # -> { "execute": "query-hotpluggable-cpus" }
1098 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
1099 # "props": { "core-id": 1 }
1102 # "qom-path": "/machine/unattached/device[0]",
1103 # "type": "qemu-s390x-cpu", "vcpus-count": 1,
1104 # "props": { "core-id": 0 }
1108 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
1109 'allow-preconfig': true }
1114 # Runtime equivalent of '-numa' CLI option, available at preconfigure
1115 # stage to configure numa mapping before initializing machine.
1119 { 'command': 'set-numa-node', 'boxed': true,
1120 'data': 'NumaOptions',
1121 'allow-preconfig': true
1127 # Request the balloon driver to change its balloon size.
1129 # @value: the target logical size of the VM in bytes. We can deduce
1130 # the size of the balloon using this formula:
1132 # logical_vm_size = vm_ram_size - balloon_size
1134 # From it we have: balloon_size = vm_ram_size - @value
1137 # - If the balloon driver is enabled but not functional because
1138 # the KVM kernel module cannot support it, KVMMissingCap
1139 # - If no balloon device is present, DeviceNotActive
1141 # .. note:: This command just issues a request to the guest. When it
1142 # returns, the balloon size may not have changed. A guest can
1143 # change the balloon size independent of this command.
1152 # -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1153 # <- { "return": {} }
1155 # With a 2.5GiB guest this command inflated the ballon to 3GiB.
1157 { 'command': 'balloon', 'data': {'value': 'int'} }
1162 # Information about the guest balloon device.
1164 # @actual: the logical size of the VM in bytes Formula used:
1165 # logical_vm_size = vm_ram_size - balloon_size
1169 { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } }
1174 # Return information about the balloon device.
1180 # - If the balloon driver is enabled but not functional because
1181 # the KVM kernel module cannot support it, KVMMissingCap
1182 # - If no balloon device is present, DeviceNotActive
1188 # -> { "execute": "query-balloon" }
1190 # "actual": 1073741824
1194 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }
1199 # Emitted when the guest changes the actual BALLOON level. This value
1200 # is equivalent to the @actual field return by the 'query-balloon'
1203 # @actual: the logical size of the VM in bytes Formula used:
1204 # logical_vm_size = vm_ram_size - balloon_size
1206 # .. note:: This event is rate-limited.
1212 # <- { "event": "BALLOON_CHANGE",
1213 # "data": { "actual": 944766976 },
1214 # "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
1216 { 'event': 'BALLOON_CHANGE',
1217 'data': { 'actual': 'int' } }
1222 # hv-balloon guest-provided memory status information.
1224 # @committed: the amount of memory in use inside the guest plus the
1225 # amount of the memory unusable inside the guest (ballooned out,
1228 # @available: the amount of the memory inside the guest available for
1229 # new allocations ("free")
1233 { 'struct': 'HvBalloonInfo',
1234 'data': { 'committed': 'size', 'available': 'size' } }
1237 # @query-hv-balloon-status-report:
1239 # Returns the hv-balloon driver data contained in the last received
1240 # "STATUS" message from the guest.
1246 # - If no hv-balloon device is present, guest memory status
1247 # reporting is not enabled or no guest memory status report
1248 # received yet, GenericError
1254 # -> { "execute": "query-hv-balloon-status-report" }
1256 # "committed": 816640000,
1257 # "available": 3333054464
1261 { 'command': 'query-hv-balloon-status-report', 'returns': 'HvBalloonInfo' }
1264 # @HV_BALLOON_STATUS_REPORT:
1266 # Emitted when the hv-balloon driver receives a "STATUS" message from
1269 # .. note:: This event is rate-limited.
1275 # <- { "event": "HV_BALLOON_STATUS_REPORT",
1276 # "data": { "committed": 816640000, "available": 3333054464 },
1277 # "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
1279 { 'event': 'HV_BALLOON_STATUS_REPORT',
1280 'data': 'HvBalloonInfo' }
1285 # Actual memory information in bytes.
1287 # @base-memory: size of "base" memory specified with command line
1290 # @plugged-memory: size of memory that can be hot-unplugged. This
1291 # field is omitted if target doesn't support memory hotplug (i.e.
1292 # CONFIG_MEM_DEVICE not defined at build time).
1296 { 'struct': 'MemoryInfo',
1297 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } }
1300 # @query-memory-size-summary:
1302 # Return the amount of initially allocated and present hotpluggable
1303 # (if enabled) memory in bytes.
1307 # -> { "execute": "query-memory-size-summary" }
1308 # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
1312 { 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
1315 # @PCDIMMDeviceInfo:
1317 # PCDIMMDevice state information
1321 # @addr: physical address, where device is mapped
1323 # @size: size of memory that the device provides
1325 # @slot: slot number at which device is plugged in
1327 # @node: NUMA node number where device is plugged in
1329 # @memdev: memory backend linked with device
1331 # @hotplugged: true if device was hotplugged
1333 # @hotpluggable: true if device if could be added/removed while
1334 # machine is running
1338 { 'struct': 'PCDIMMDeviceInfo',
1339 'data': { '*id': 'str',
1345 'hotplugged': 'bool',
1346 'hotpluggable': 'bool'
1351 # @VirtioPMEMDeviceInfo:
1353 # VirtioPMEM state information
1357 # @memaddr: physical address in memory, where device is mapped
1359 # @size: size of memory that the device provides
1361 # @memdev: memory backend linked with device
1365 { 'struct': 'VirtioPMEMDeviceInfo',
1366 'data': { '*id': 'str',
1374 # @VirtioMEMDeviceInfo:
1376 # VirtioMEMDevice state information
1380 # @memaddr: physical address in memory, where device is mapped
1382 # @requested-size: the user requested size of the device
1384 # @size: the (current) size of memory that the device provides
1386 # @max-size: the maximum size of memory that the device can provide
1388 # @block-size: the block size of memory that the device provides
1390 # @node: NUMA node number where device is assigned to
1392 # @memdev: memory backend linked with the region
1396 { 'struct': 'VirtioMEMDeviceInfo',
1397 'data': { '*id': 'str',
1399 'requested-size': 'size',
1402 'block-size': 'size',
1409 # @SgxEPCDeviceInfo:
1411 # Sgx EPC state information
1415 # @memaddr: physical address in memory, where device is mapped
1417 # @size: size of memory that the device provides
1419 # @memdev: memory backend linked with device
1421 # @node: the numa node (Since: 7.0)
1425 { 'struct': 'SgxEPCDeviceInfo',
1426 'data': { '*id': 'str',
1435 # @HvBalloonDeviceInfo:
1437 # hv-balloon provided memory state information
1441 # @memaddr: physical address in memory, where device is mapped
1443 # @max-size: the maximum size of memory that the device can provide
1445 # @memdev: memory backend linked with device
1449 { 'struct': 'HvBalloonDeviceInfo',
1450 'data': { '*id': 'str',
1458 # @MemoryDeviceInfoKind:
1460 # @nvdimm: since 2.12
1462 # @virtio-pmem: since 4.1
1464 # @virtio-mem: since 5.1
1466 # @sgx-epc: since 6.2.
1468 # @hv-balloon: since 8.2.
1472 { 'enum': 'MemoryDeviceInfoKind',
1473 'data': [ 'dimm', 'nvdimm', 'virtio-pmem', 'virtio-mem', 'sgx-epc',
1477 # @PCDIMMDeviceInfoWrapper:
1479 # @data: PCDIMMDevice state information
1483 { 'struct': 'PCDIMMDeviceInfoWrapper',
1484 'data': { 'data': 'PCDIMMDeviceInfo' } }
1487 # @VirtioPMEMDeviceInfoWrapper:
1489 # @data: VirtioPMEM state information
1493 { 'struct': 'VirtioPMEMDeviceInfoWrapper',
1494 'data': { 'data': 'VirtioPMEMDeviceInfo' } }
1497 # @VirtioMEMDeviceInfoWrapper:
1499 # @data: VirtioMEMDevice state information
1503 { 'struct': 'VirtioMEMDeviceInfoWrapper',
1504 'data': { 'data': 'VirtioMEMDeviceInfo' } }
1507 # @SgxEPCDeviceInfoWrapper:
1509 # @data: Sgx EPC state information
1513 { 'struct': 'SgxEPCDeviceInfoWrapper',
1514 'data': { 'data': 'SgxEPCDeviceInfo' } }
1517 # @HvBalloonDeviceInfoWrapper:
1519 # @data: hv-balloon provided memory state information
1523 { 'struct': 'HvBalloonDeviceInfoWrapper',
1524 'data': { 'data': 'HvBalloonDeviceInfo' } }
1527 # @MemoryDeviceInfo:
1529 # Union containing information about a memory device
1531 # @type: memory device type
1535 { 'union': 'MemoryDeviceInfo',
1536 'base': { 'type': 'MemoryDeviceInfoKind' },
1537 'discriminator': 'type',
1538 'data': { 'dimm': 'PCDIMMDeviceInfoWrapper',
1539 'nvdimm': 'PCDIMMDeviceInfoWrapper',
1540 'virtio-pmem': 'VirtioPMEMDeviceInfoWrapper',
1541 'virtio-mem': 'VirtioMEMDeviceInfoWrapper',
1542 'sgx-epc': 'SgxEPCDeviceInfoWrapper',
1543 'hv-balloon': 'HvBalloonDeviceInfoWrapper'
1550 # Sgx EPC cmdline information
1552 # @memdev: memory backend linked with device
1554 # @node: the numa node (Since: 7.0)
1558 { 'struct': 'SgxEPC',
1559 'data': { 'memdev': 'str',
1565 # @SgxEPCProperties:
1567 # SGX properties of machine types.
1569 # @sgx-epc: list of ids of memory-backend-epc objects.
1573 { 'struct': 'SgxEPCProperties',
1574 'data': { 'sgx-epc': ['SgxEPC'] }
1578 # @query-memory-devices:
1580 # Lists available memory devices and their state
1586 # -> { "execute": "query-memory-devices" }
1587 # <- { "return": [ { "data":
1588 # { "addr": 5368709120,
1589 # "hotpluggable": true,
1590 # "hotplugged": true,
1592 # "memdev": "/objects/memX",
1594 # "size": 1073741824,
1599 { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
1602 # @MEMORY_DEVICE_SIZE_CHANGE:
1604 # Emitted when the size of a memory device changes. Only emitted for
1605 # memory devices that can actually change the size (e.g., virtio-mem
1606 # due to guest action).
1610 # @size: the new size of memory that the device provides
1612 # @qom-path: path to the device object in the QOM tree (since 6.2)
1614 # .. note:: This event is rate-limited.
1620 # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
1621 # "data": { "id": "vm0", "size": 1073741824,
1622 # "qom-path": "/machine/unattached/device[2]" },
1623 # "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
1625 { 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
1626 'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} }
1629 # @BootConfiguration:
1631 # Schema for virtual machine boot configuration.
1633 # @order: Boot order (a=floppy, c=hard disk, d=CD-ROM, n=network)
1635 # @once: Boot order to apply on first boot
1637 # @menu: Whether to show a boot menu
1639 # @splash: The name of the file to be passed to the firmware as logo
1640 # picture, if @menu is true.
1642 # @splash-time: How long to show the logo picture, in milliseconds
1644 # @reboot-timeout: Timeout before guest reboots after boot fails
1646 # @strict: Whether to attempt booting from devices not included in the
1651 { 'struct': 'BootConfiguration', 'data': {
1656 '*splash-time': 'int',
1657 '*reboot-timeout': 'int',
1658 '*strict': 'bool' } }
1661 # @SMPConfiguration:
1663 # Schema for CPU topology configuration. A missing value lets QEMU
1664 # figure out a suitable value based on the ones that are provided.
1666 # The members other than @cpus and @maxcpus define a topology of
1669 # The ordering from highest/coarsest to lowest/finest is: @drawers,
1670 # @books, @sockets, @dies, @clusters, @cores, @threads.
1672 # Different architectures support different subsets of topology
1675 # For example, s390x does not have clusters and dies, and the socket
1676 # is the parent container of cores.
1678 # @cpus: number of virtual CPUs in the virtual machine
1680 # @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual
1683 # @drawers: number of drawers in the CPU topology (since 8.2)
1685 # @books: number of books in the CPU topology (since 8.2)
1687 # @sockets: number of sockets per parent container
1689 # @dies: number of dies per parent container
1691 # @clusters: number of clusters per parent container (since 7.0)
1693 # @modules: number of modules per parent container (since 9.1)
1695 # @cores: number of cores per parent container
1697 # @threads: number of threads per core
1701 { 'struct': 'SMPConfiguration', 'data': {
1711 '*maxcpus': 'int' } }
1716 # Query interrupt statistics
1720 # @unstable: This command is meant for debugging.
1722 # Returns: interrupt statistics
1726 { 'command': 'x-query-irq',
1727 'returns': 'HumanReadableText',
1728 'features': [ 'unstable' ] }
1733 # Query TCG compiler statistics
1737 # @unstable: This command is meant for debugging.
1739 # Returns: TCG compiler statistics
1743 { 'command': 'x-query-jit',
1744 'returns': 'HumanReadableText',
1746 'features': [ 'unstable' ] }
1751 # Query NUMA topology information
1755 # @unstable: This command is meant for debugging.
1757 # Returns: topology information
1761 { 'command': 'x-query-numa',
1762 'returns': 'HumanReadableText',
1763 'features': [ 'unstable' ] }
1768 # Query TCG opcode counters
1772 # @unstable: This command is meant for debugging.
1774 # Returns: TCG opcode counters
1778 { 'command': 'x-query-opcount',
1779 'returns': 'HumanReadableText',
1781 'features': [ 'unstable' ] }
1784 # @x-query-ramblock:
1786 # Query system ramblock information
1790 # @unstable: This command is meant for debugging.
1792 # Returns: system ramblock information
1796 { 'command': 'x-query-ramblock',
1797 'returns': 'HumanReadableText',
1798 'features': [ 'unstable' ] }
1803 # Query information on the registered ROMS
1807 # @unstable: This command is meant for debugging.
1809 # Returns: registered ROMs
1813 { 'command': 'x-query-roms',
1814 'returns': 'HumanReadableText',
1815 'features': [ 'unstable' ] }
1820 # Query information on the USB devices
1824 # @unstable: This command is meant for debugging.
1826 # Returns: USB device information
1830 { 'command': 'x-query-usb',
1831 'returns': 'HumanReadableText',
1832 'features': [ 'unstable' ] }
1835 # @SmbiosEntryPointType:
1837 # @32: SMBIOS version 2.1 (32-bit) Entry Point
1839 # @64: SMBIOS version 3.0 (64-bit) Entry Point
1841 # @auto: Either 2.x or 3.x SMBIOS version, 2.x if configuration can be
1842 # described by it and 3.x otherwise (since: 9.0)
1846 { 'enum': 'SmbiosEntryPointType',
1847 'data': [ '32', '64', 'auto' ] }
1850 # @MemorySizeConfiguration:
1852 # Schema for memory size configuration.
1854 # @size: memory size in bytes
1856 # @max-size: maximum hotpluggable memory size in bytes
1858 # @slots: number of available memory slots for hotplug
1862 { 'struct': 'MemorySizeConfiguration', 'data': {
1864 '*max-size': 'size',
1865 '*slots': 'uint64' } }
1870 # Save the FDT in dtb format.
1872 # @filename: name of the dtb file to be created
1878 # -> { "execute": "dumpdtb" }
1879 # "arguments": { "filename": "fdt.dtb" } }
1880 # <- { "return": {} }
1882 { 'command': 'dumpdtb',
1883 'data': { 'filename': 'str' },
1884 'if': 'CONFIG_FDT' }
1887 # @x-query-interrupt-controllers:
1889 # Query information on interrupt controller devices
1893 # @unstable: This command is meant for debugging.
1895 # Returns: Interrupt controller devices information
1899 { 'command': 'x-query-interrupt-controllers',
1900 'returns': 'HumanReadableText',
1901 'features': [ 'unstable' ]}