1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4# This work is licensed under the terms of the GNU GPL, version 2 or later. 5# See the COPYING file in the top-level directory. 6 7## 8# ******** 9# Machines 10# ******** 11## 12 13{ 'include': 'common.json' } 14{ 'include': 'machine-common.json' } 15 16## 17# @SysEmuTarget: 18# 19# The comprehensive enumeration of QEMU system emulation ("softmmu") 20# targets. Run "./configure --help" in the project root directory, 21# and look for the \*-softmmu targets near the "--target-list" option. 22# The individual target constants are not documented here, for the 23# time being. 24# 25# @rx: since 5.0 26# 27# @avr: since 5.1 28# 29# @loongarch64: since 7.1 30# 31# .. note:: The resulting QMP strings can be appended to the 32# "qemu-system-" prefix to produce the corresponding QEMU 33# executable name. This is true even for "qemu-system-x86_64". 34# 35# Since: 3.0 36## 37{ 'enum' : 'SysEmuTarget', 38 'data' : [ 'aarch64', 'alpha', 'arm', 'avr', 'hppa', 'i386', 39 'loongarch64', 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', 40 'mips64el', 'mipsel', 'or1k', 'ppc', 41 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', 42 'sh4eb', 'sparc', 'sparc64', 'tricore', 43 'x86_64', 'xtensa', 'xtensaeb' ] } 44 45## 46# @S390CpuState: 47# 48# An enumeration of cpu states that can be assumed by a virtual S390 49# CPU 50# 51# Since: 2.12 52## 53{ 'enum': 'S390CpuState', 54 'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] } 55 56## 57# @CpuInfoS390: 58# 59# Additional information about a virtual S390 CPU 60# 61# @cpu-state: the virtual CPU's state 62# 63# @dedicated: the virtual CPU's dedication (since 8.2) 64# 65# @entitlement: the virtual CPU's entitlement (since 8.2) 66# 67# Since: 2.12 68## 69{ 'struct': 'CpuInfoS390', 70 'data': { 'cpu-state': 'S390CpuState', 71 '*dedicated': 'bool', 72 '*entitlement': 'S390CpuEntitlement' } } 73 74## 75# @CpuInfoFast: 76# 77# Information about a virtual CPU 78# 79# @cpu-index: index of the virtual CPU 80# 81# @qom-path: path to the CPU object in the QOM tree 82# 83# @thread-id: ID of the underlying host thread 84# 85# @props: properties associated with a virtual CPU, e.g. the socket id 86# 87# @target: the QEMU system emulation target, which determines which 88# additional fields will be listed (since 3.0) 89# 90# Since: 2.12 91## 92{ 'union' : 'CpuInfoFast', 93 'base' : { 'cpu-index' : 'int', 94 'qom-path' : 'str', 95 'thread-id' : 'int', 96 '*props' : 'CpuInstanceProperties', 97 'target' : 'SysEmuTarget' }, 98 'discriminator' : 'target', 99 'data' : { 's390x' : 'CpuInfoS390' } } 100 101## 102# @query-cpus-fast: 103# 104# Return information about all virtual CPUs. 105# 106# Since: 2.12 107# 108# .. qmp-example:: 109# 110# -> { "execute": "query-cpus-fast" } 111# <- { "return": [ 112# { 113# "thread-id": 25627, 114# "props": { 115# "core-id": 0, 116# "thread-id": 0, 117# "socket-id": 0 118# }, 119# "qom-path": "/machine/unattached/device[0]", 120# "target":"x86_64", 121# "cpu-index": 0 122# }, 123# { 124# "thread-id": 25628, 125# "props": { 126# "core-id": 0, 127# "thread-id": 0, 128# "socket-id": 1 129# }, 130# "qom-path": "/machine/unattached/device[2]", 131# "target":"x86_64", 132# "cpu-index": 1 133# } 134# ] 135# } 136## 137{ 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] } 138 139## 140# @CompatProperty: 141# 142# Property default values specific to a machine type, for use by 143# scripts/compare-machine-types. 144# 145# @qom-type: name of the QOM type to which the default applies 146# 147# @property: name of its property to which the default applies 148# 149# @value: the default value (machine-specific default can overwrite 150# the "default" default, to avoid this use -machine none) 151# 152# Since: 9.1 153## 154{ 'struct': 'CompatProperty', 155 'data': { 'qom-type': 'str', 156 'property': 'str', 157 'value': 'str' } } 158 159## 160# @MachineInfo: 161# 162# Information describing a machine. 163# 164# @name: the name of the machine 165# 166# @alias: an alias for the machine name 167# 168# @is-default: whether the machine is default 169# 170# @cpu-max: maximum number of CPUs supported by the machine type 171# (since 1.5) 172# 173# @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7) 174# 175# @numa-mem-supported: true if '-numa node,mem' option is supported by 176# the machine type and false otherwise (since 4.1) 177# 178# @deprecated: if true, the machine type is deprecated and may be 179# removed in future versions of QEMU according to the QEMU 180# deprecation policy (since 4.1) 181# 182# @default-cpu-type: default CPU model typename if none is requested 183# via the -cpu argument. (since 4.2) 184# 185# @default-ram-id: the default ID of initial RAM memory backend 186# (since 5.2) 187# 188# @acpi: machine type supports ACPI (since 8.0) 189# 190# @compat-props: The machine type's compatibility properties. Only 191# present when `query-machines` argument @compat-props is true. 192# (since 9.1) 193# 194# Features: 195# 196# @unstable: Member @compat-props is experimental. 197# 198# Since: 1.2 199## 200{ 'struct': 'MachineInfo', 201 'data': { 'name': 'str', '*alias': 'str', 202 '*is-default': 'bool', 'cpu-max': 'int', 203 'hotpluggable-cpus': 'bool', 'numa-mem-supported': 'bool', 204 'deprecated': 'bool', '*default-cpu-type': 'str', 205 '*default-ram-id': 'str', 'acpi': 'bool', 206 '*compat-props': { 'type': ['CompatProperty'], 207 'features': ['unstable'] } } } 208 209## 210# @query-machines: 211# 212# Return a list of supported machines 213# 214# @compat-props: if true, also return compatibility properties. 215# (default: false) (since 9.1) 216# 217# Features: 218# 219# @unstable: Argument @compat-props is experimental. 220# 221# Since: 1.2 222# 223# .. qmp-example:: 224# 225# -> { "execute": "query-machines", "arguments": { "compat-props": true } } 226# <- { "return": [ 227# { 228# "hotpluggable-cpus": true, 229# "name": "pc-q35-6.2", 230# "compat-props": [ 231# { 232# "qom-type": "virtio-mem", 233# "property": "unplugged-inaccessible", 234# "value": "off" 235# } 236# ], 237# "numa-mem-supported": false, 238# "default-cpu-type": "qemu64-x86_64-cpu", 239# "cpu-max": 288, 240# "deprecated": false, 241# "default-ram-id": "pc.ram" 242# }, 243# ... 244# } 245## 246{ 'command': 'query-machines', 247 'data': { '*compat-props': { 'type': 'bool', 248 'features': [ 'unstable' ] } }, 249 'returns': ['MachineInfo'] } 250 251## 252# @CurrentMachineParams: 253# 254# Information describing the running machine parameters. 255# 256# @wakeup-suspend-support: true if the machine supports wake up from 257# suspend 258# 259# Since: 4.0 260## 261{ 'struct': 'CurrentMachineParams', 262 'data': { 'wakeup-suspend-support': 'bool'} } 263 264## 265# @query-current-machine: 266# 267# Return information on the current virtual machine. 268# 269# Since: 4.0 270## 271{ 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' } 272 273## 274# @QemuTargetInfo: 275# 276# Information on the target configuration built into the QEMU binary. 277# 278# @arch: the target architecture 279# 280# Since: 1.2 281## 282{ 'struct': 'QemuTargetInfo', 283 'data': { 'arch': 'SysEmuTarget' } } 284 285## 286# @query-target: 287# 288# Return information about the target for this QEMU 289# 290# Since: 1.2 291## 292{ 'command': 'query-target', 'returns': 'QemuTargetInfo' } 293 294## 295# @UuidInfo: 296# 297# Guest UUID information (Universally Unique Identifier). 298# 299# @UUID: the UUID of the guest 300# 301# Since: 0.14 302# 303# .. note:: If no UUID was specified for the guest, the nil UUID (all 304# zeroes) is returned. 305## 306{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } 307 308## 309# @query-uuid: 310# 311# Query the guest UUID information. 312# 313# Since: 0.14 314# 315# .. qmp-example:: 316# 317# -> { "execute": "query-uuid" } 318# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } 319## 320{ 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true } 321 322## 323# @GuidInfo: 324# 325# GUID information. 326# 327# @guid: the globally unique identifier 328# 329# Since: 2.9 330## 331{ 'struct': 'GuidInfo', 'data': {'guid': 'str'} } 332 333## 334# @query-vm-generation-id: 335# 336# Show Virtual Machine Generation ID 337# 338# Since: 2.9 339## 340{ 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' } 341 342## 343# @system_reset: 344# 345# Performs a hard reset of a guest. 346# 347# Since: 0.14 348# 349# .. qmp-example:: 350# 351# -> { "execute": "system_reset" } 352# <- { "return": {} } 353## 354{ 'command': 'system_reset' } 355 356## 357# @system_powerdown: 358# 359# Requests that a guest perform a powerdown operation. 360# 361# Since: 0.14 362# 363# .. note:: A guest may or may not respond to this command. This 364# command returning does not indicate that a guest has accepted the 365# request or that it has shut down. Many guests will respond to 366# this command by prompting the user in some way. 367# 368# .. qmp-example:: 369# 370# -> { "execute": "system_powerdown" } 371# <- { "return": {} } 372## 373{ 'command': 'system_powerdown' } 374 375## 376# @system_wakeup: 377# 378# Wake up guest from suspend. If the guest has wake-up from suspend 379# support enabled (wakeup-suspend-support flag from 380# `query-current-machine`), wake-up guest from suspend if the guest is 381# in SUSPENDED state. Return an error otherwise. 382# 383# Since: 1.1 384# 385# .. note:: Prior to 4.0, this command does nothing in case the guest 386# isn't suspended. 387# 388# .. qmp-example:: 389# 390# -> { "execute": "system_wakeup" } 391# <- { "return": {} } 392## 393{ 'command': 'system_wakeup' } 394 395## 396# @LostTickPolicy: 397# 398# Policy for handling lost ticks in timer devices. Ticks end up 399# getting lost when, for example, the guest is paused. 400# 401# @discard: throw away the missed ticks and continue with future 402# injection normally. The guest OS will see the timer jump ahead 403# by a potentially quite significant amount all at once, as if the 404# intervening chunk of time had simply not existed; needless to 405# say, such a sudden jump can easily confuse a guest OS which is 406# not specifically prepared to deal with it. Assuming the guest 407# OS can deal correctly with the time jump, the time in the guest 408# and in the host should now match. 409# 410# @delay: continue to deliver ticks at the normal rate. The guest OS 411# will not notice anything is amiss, as from its point of view 412# time will have continued to flow normally. The time in the 413# guest should now be behind the time in the host by exactly the 414# amount of time during which ticks have been missed. 415# 416# @slew: deliver ticks at a higher rate to catch up with the missed 417# ticks. The guest OS will not notice anything is amiss, as from 418# its point of view time will have continued to flow normally. 419# Once the timer has managed to catch up with all the missing 420# ticks, the time in the guest and in the host should match. 421# 422# Since: 2.0 423## 424{ 'enum': 'LostTickPolicy', 425 'data': ['discard', 'delay', 'slew' ] } 426 427## 428# @inject-nmi: 429# 430# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or 431# all CPUs (ppc64). The command fails when the guest doesn't support 432# injecting. 433# 434# Since: 0.14 435# 436# .. note:: Prior to 2.1, this command was only supported for x86 and 437# s390 VMs. 438# 439# .. qmp-example:: 440# 441# -> { "execute": "inject-nmi" } 442# <- { "return": {} } 443## 444{ 'command': 'inject-nmi' } 445 446## 447# @KvmInfo: 448# 449# Information about support for KVM acceleration 450# 451# @enabled: true if KVM acceleration is active 452# 453# @present: true if KVM acceleration is built into this executable 454# 455# Since: 0.14 456## 457{ 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } 458 459## 460# @query-kvm: 461# 462# Return information about KVM acceleration 463# 464# Since: 0.14 465# 466# .. qmp-example:: 467# 468# -> { "execute": "query-kvm" } 469# <- { "return": { "enabled": true, "present": true } } 470## 471{ 'command': 'query-kvm', 'returns': 'KvmInfo' } 472 473## 474# @NumaOptionsType: 475# 476# @node: NUMA nodes configuration 477# 478# @dist: NUMA distance configuration (since 2.10) 479# 480# @cpu: property based CPU(s) to node mapping (Since: 2.10) 481# 482# @hmat-lb: memory latency and bandwidth information (Since: 5.0) 483# 484# @hmat-cache: memory side cache information (Since: 5.0) 485# 486# Since: 2.1 487## 488{ 'enum': 'NumaOptionsType', 489 'data': [ 'node', 'dist', 'cpu', 'hmat-lb', 'hmat-cache' ] } 490 491## 492# @NumaOptions: 493# 494# A discriminated record of NUMA options. (for OptsVisitor) 495# 496# @type: NUMA option type 497# 498# Since: 2.1 499## 500{ 'union': 'NumaOptions', 501 'base': { 'type': 'NumaOptionsType' }, 502 'discriminator': 'type', 503 'data': { 504 'node': 'NumaNodeOptions', 505 'dist': 'NumaDistOptions', 506 'cpu': 'NumaCpuOptions', 507 'hmat-lb': 'NumaHmatLBOptions', 508 'hmat-cache': 'NumaHmatCacheOptions' }} 509 510## 511# @NumaNodeOptions: 512# 513# Create a guest NUMA node. (for OptsVisitor) 514# 515# @nodeid: NUMA node ID (increase by 1 from 0 if omitted) 516# 517# @cpus: VCPUs belonging to this node (assign VCPUS round-robin if 518# omitted) 519# 520# @mem: memory size of this node; mutually exclusive with @memdev. 521# Equally divide total memory among nodes if both @mem and @memdev 522# are omitted. 523# 524# @memdev: memory backend object. If specified for one node, it must 525# be specified for all nodes. 526# 527# @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points 528# to the nodeid which has the memory controller responsible for 529# this NUMA node. This field provides additional information as 530# to the initiator node that is closest (as in directly attached) 531# to this node, and therefore has the best performance (since 5.0) 532# 533# Since: 2.1 534## 535{ 'struct': 'NumaNodeOptions', 536 'data': { 537 '*nodeid': 'uint16', 538 '*cpus': ['uint16'], 539 '*mem': 'size', 540 '*memdev': 'str', 541 '*initiator': 'uint16' }} 542 543## 544# @NumaDistOptions: 545# 546# Set the distance between 2 NUMA nodes. 547# 548# @src: source NUMA node. 549# 550# @dst: destination NUMA node. 551# 552# @val: NUMA distance from source node to destination node. When a 553# node is unreachable from another node, set the distance between 554# them to 255. 555# 556# Since: 2.10 557## 558{ 'struct': 'NumaDistOptions', 559 'data': { 560 'src': 'uint16', 561 'dst': 'uint16', 562 'val': 'uint8' }} 563 564## 565# @CXLFixedMemoryWindowOptions: 566# 567# Create a CXL Fixed Memory Window 568# 569# @size: Size of the Fixed Memory Window in bytes. Must be a multiple 570# of 256MiB. 571# 572# @interleave-granularity: Number of contiguous bytes for which 573# accesses will go to a given interleave target. Accepted values 574# [256, 512, 1k, 2k, 4k, 8k, 16k] 575# 576# @targets: Target root bridge IDs from -device ...,id=<ID> for each 577# root bridge. 578# 579# Since: 7.1 580## 581{ 'struct': 'CXLFixedMemoryWindowOptions', 582 'data': { 583 'size': 'size', 584 '*interleave-granularity': 'size', 585 'targets': ['str'] }} 586 587## 588# @CXLFMWProperties: 589# 590# List of CXL Fixed Memory Windows. 591# 592# @cxl-fmw: List of `CXLFixedMemoryWindowOptions` 593# 594# Since: 7.1 595## 596{ 'struct' : 'CXLFMWProperties', 597 'data': { 'cxl-fmw': ['CXLFixedMemoryWindowOptions'] } 598} 599 600## 601# @X86CPURegister32: 602# 603# A X86 32-bit register 604# 605# Since: 1.5 606## 607{ 'enum': 'X86CPURegister32', 608 'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] } 609 610## 611# @X86CPUFeatureWordInfo: 612# 613# Information about a X86 CPU feature word 614# 615# @cpuid-input-eax: Input EAX value for CPUID instruction for that 616# feature word 617# 618# @cpuid-input-ecx: Input ECX value for CPUID instruction for that 619# feature word 620# 621# @cpuid-register: Output register containing the feature bits 622# 623# @features: value of output register, containing the feature bits 624# 625# Since: 1.5 626## 627{ 'struct': 'X86CPUFeatureWordInfo', 628 'data': { 'cpuid-input-eax': 'int', 629 '*cpuid-input-ecx': 'int', 630 'cpuid-register': 'X86CPURegister32', 631 'features': 'int' } } 632 633## 634# @DummyForceArrays: 635# 636# Not used by QMP; hack to let us use X86CPUFeatureWordInfoList 637# internally 638# 639# Since: 2.5 640## 641{ 'struct': 'DummyForceArrays', 642 'data': { 'unused': ['X86CPUFeatureWordInfo'] } } 643 644## 645# @NumaCpuOptions: 646# 647# Option "-numa cpu" overrides default cpu to node mapping. It accepts 648# the same set of cpu properties as returned by 649# `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where 650# node-id could be used to override default node mapping. 651# 652# Since: 2.10 653## 654{ 'struct': 'NumaCpuOptions', 655 'base': 'CpuInstanceProperties', 656 'data' : {} } 657 658## 659# @HmatLBMemoryHierarchy: 660# 661# The memory hierarchy in the System Locality Latency and Bandwidth 662# Information Structure of HMAT (Heterogeneous Memory Attribute Table) 663# 664# For more information about `HmatLBMemoryHierarchy`, see chapter 665# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec. 666# 667# @memory: the structure represents the memory performance 668# 669# @first-level: first level of memory side cache 670# 671# @second-level: second level of memory side cache 672# 673# @third-level: third level of memory side cache 674# 675# Since: 5.0 676## 677{ 'enum': 'HmatLBMemoryHierarchy', 678 'data': [ 'memory', 'first-level', 'second-level', 'third-level' ] } 679 680## 681# @HmatLBDataType: 682# 683# Data type in the System Locality Latency and Bandwidth Information 684# Structure of HMAT (Heterogeneous Memory Attribute Table) 685# 686# For more information about `HmatLBDataType`, see chapter 5.2.27.4: 687# Table 5-146: Field "Data Type" of ACPI 6.3 spec. 688# 689# @access-latency: access latency (nanoseconds) 690# 691# @read-latency: read latency (nanoseconds) 692# 693# @write-latency: write latency (nanoseconds) 694# 695# @access-bandwidth: access bandwidth (Bytes per second) 696# 697# @read-bandwidth: read bandwidth (Bytes per second) 698# 699# @write-bandwidth: write bandwidth (Bytes per second) 700# 701# Since: 5.0 702## 703{ 'enum': 'HmatLBDataType', 704 'data': [ 'access-latency', 'read-latency', 'write-latency', 705 'access-bandwidth', 'read-bandwidth', 'write-bandwidth' ] } 706 707## 708# @NumaHmatLBOptions: 709# 710# Set the system locality latency and bandwidth information between 711# Initiator and Target proximity Domains. 712# 713# For more information about `NumaHmatLBOptions`, see chapter 5.2.27.4: 714# Table 5-146 of ACPI 6.3 spec. 715# 716# @initiator: the Initiator Proximity Domain. 717# 718# @target: the Target Proximity Domain. 719# 720# @hierarchy: the Memory Hierarchy. Indicates the performance of 721# memory or side cache. 722# 723# @data-type: presents the type of data, access/read/write latency or 724# hit latency. 725# 726# @latency: the value of latency from @initiator to @target proximity 727# domain, the latency unit is "ns(nanosecond)". 728# 729# @bandwidth: the value of bandwidth between @initiator and @target 730# proximity domain, the bandwidth unit is "Bytes per second". 731# 732# Since: 5.0 733## 734{ 'struct': 'NumaHmatLBOptions', 735 'data': { 736 'initiator': 'uint16', 737 'target': 'uint16', 738 'hierarchy': 'HmatLBMemoryHierarchy', 739 'data-type': 'HmatLBDataType', 740 '*latency': 'uint64', 741 '*bandwidth': 'size' }} 742 743## 744# @HmatCacheAssociativity: 745# 746# Cache associativity in the Memory Side Cache Information Structure 747# of HMAT 748# 749# For more information of `HmatCacheAssociativity`, see chapter 750# 5.2.27.5: Table 5-147 of ACPI 6.3 spec. 751# 752# @none: None (no memory side cache in this proximity domain, or cache 753# associativity unknown) 754# 755# @direct: Direct Mapped 756# 757# @complex: Complex Cache Indexing (implementation specific) 758# 759# Since: 5.0 760## 761{ 'enum': 'HmatCacheAssociativity', 762 'data': [ 'none', 'direct', 'complex' ] } 763 764## 765# @HmatCacheWritePolicy: 766# 767# Cache write policy in the Memory Side Cache Information Structure of 768# HMAT 769# 770# For more information of `HmatCacheWritePolicy`, see chapter 5.2.27.5: 771# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. 772# 773# @none: None (no memory side cache in this proximity domain, or cache 774# write policy unknown) 775# 776# @write-back: Write Back (WB) 777# 778# @write-through: Write Through (WT) 779# 780# Since: 5.0 781## 782{ 'enum': 'HmatCacheWritePolicy', 783 'data': [ 'none', 'write-back', 'write-through' ] } 784 785## 786# @NumaHmatCacheOptions: 787# 788# Set the memory side cache information for a given memory domain. 789# 790# For more information of `NumaHmatCacheOptions`, see chapter 5.2.27.5: 791# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. 792# 793# @node-id: the memory proximity domain to which the memory belongs. 794# 795# @size: the size of memory side cache in bytes. 796# 797# @level: the cache level described in this structure. 798# 799# @associativity: the cache associativity, 800# none/direct-mapped/complex(complex cache indexing). 801# 802# @policy: the write policy, none/write-back/write-through. 803# 804# @line: the cache line size in bytes. 805# 806# Since: 5.0 807## 808{ 'struct': 'NumaHmatCacheOptions', 809 'data': { 810 'node-id': 'uint32', 811 'size': 'size', 812 'level': 'uint8', 813 'associativity': 'HmatCacheAssociativity', 814 'policy': 'HmatCacheWritePolicy', 815 'line': 'uint16' }} 816 817## 818# @memsave: 819# 820# Save a portion of guest memory to a file. 821# 822# @val: the virtual address of the guest to start from 823# 824# @size: the size of memory region to save 825# 826# @filename: the file to save the memory to as binary data 827# 828# @cpu-index: the index of the virtual CPU to use for translating the 829# virtual address (defaults to CPU 0) 830# 831# Since: 0.14 832# 833# .. caution:: Errors were not reliably returned until 1.1. 834# 835# .. qmp-example:: 836# 837# -> { "execute": "memsave", 838# "arguments": { "val": 10, 839# "size": 100, 840# "filename": "/tmp/virtual-mem-dump" } } 841# <- { "return": {} } 842## 843{ 'command': 'memsave', 844 'data': { 845 'val': 'uint64', 846 'size': 'size', 847 'filename': 'str', 848 '*cpu-index': 'int' } } 849 850## 851# @pmemsave: 852# 853# Save a portion of guest physical memory to a file. 854# 855# @val: the physical address of the guest to start from 856# 857# @size: the size of memory region to save 858# 859# @filename: the file to save the memory to as binary data 860# 861# Since: 0.14 862# 863# .. caution:: Errors were not reliably returned until 1.1. 864# 865# .. qmp-example:: 866# 867# -> { "execute": "pmemsave", 868# "arguments": { "val": 10, 869# "size": 100, 870# "filename": "/tmp/physical-mem-dump" } } 871# <- { "return": {} } 872## 873{ 'command': 'pmemsave', 874 'data': { 875 'val': 'uint64', 876 'size': 'size', 877 'filename': 'str' } } 878 879## 880# @Memdev: 881# 882# Information about memory backend 883# 884# @id: backend's ID if backend has 'id' property (since 2.9) 885# 886# @size: memory backend size 887# 888# @merge: whether memory merge support is enabled 889# 890# @dump: whether memory backend's memory is included in a core dump 891# 892# @prealloc: whether memory was preallocated 893# 894# @share: whether memory is private to QEMU or shared (since 6.1) 895# 896# @reserve: whether swap space (or huge pages) was reserved if 897# applicable. This corresponds to the user configuration and not 898# the actual behavior implemented in the OS to perform the 899# reservation. For example, Linux will never reserve swap space 900# for shared file mappings. (since 6.1) 901# 902# @host-nodes: host nodes for its memory policy 903# 904# @policy: memory policy of memory backend 905# 906# Since: 2.1 907## 908{ 'struct': 'Memdev', 909 'data': { 910 '*id': 'str', 911 'size': 'size', 912 'merge': 'bool', 913 'dump': 'bool', 914 'prealloc': 'bool', 915 'share': 'bool', 916 '*reserve': 'bool', 917 'host-nodes': ['uint16'], 918 'policy': 'HostMemPolicy' }} 919 920## 921# @query-memdev: 922# 923# Return information for all memory backends. 924# 925# Since: 2.1 926# 927# .. qmp-example:: 928# 929# -> { "execute": "query-memdev" } 930# <- { "return": [ 931# { 932# "id": "mem1", 933# "size": 536870912, 934# "merge": false, 935# "dump": true, 936# "prealloc": false, 937# "share": false, 938# "host-nodes": [0, 1], 939# "policy": "bind" 940# }, 941# { 942# "size": 536870912, 943# "merge": false, 944# "dump": true, 945# "prealloc": true, 946# "share": false, 947# "host-nodes": [2, 3], 948# "policy": "preferred" 949# } 950# ] 951# } 952## 953{ 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true } 954 955## 956# @CpuInstanceProperties: 957# 958# Properties identifying a CPU. 959# 960# Which members are optional and which mandatory depends on the 961# architecture and board. 962# 963# For s390x see :ref:`cpu-topology-s390x`. 964# 965# The ids other than the node-id specify the position of the CPU 966# within the CPU topology (as defined by the machine property "smp", 967# thus see also type `SMPConfiguration`) 968# 969# @node-id: NUMA node ID the CPU belongs to 970# 971# @drawer-id: drawer number within CPU topology the CPU belongs to 972# (since 8.2) 973# 974# @book-id: book number within parent container the CPU belongs to 975# (since 8.2) 976# 977# @socket-id: socket number within parent container the CPU belongs to 978# 979# @die-id: die number within the parent container the CPU belongs to 980# (since 4.1) 981# 982# @cluster-id: cluster number within the parent container the CPU 983# belongs to (since 7.1) 984# 985# @module-id: module number within the parent container the CPU 986# belongs to (since 9.1) 987# 988# @core-id: core number within the parent container the CPU belongs to 989# 990# @thread-id: thread number within the core the CPU belongs to 991# 992# Since: 2.7 993## 994{ 'struct': 'CpuInstanceProperties', 995 # Keep these in sync with the properties `device_add` accepts 996 'data': { '*node-id': 'int', 997 '*drawer-id': 'int', 998 '*book-id': 'int', 999 '*socket-id': 'int', 1000 '*die-id': 'int', 1001 '*cluster-id': 'int', 1002 '*module-id': 'int', 1003 '*core-id': 'int', 1004 '*thread-id': 'int' 1005 } 1006} 1007 1008## 1009# @HotpluggableCPU: 1010# 1011# @type: CPU object type for usage with `device_add` command 1012# 1013# @props: list of properties to pass for hotplugging a CPU with 1014# `device_add` 1015# 1016# @vcpus-count: number of logical VCPU threads `HotpluggableCPU` 1017# provides 1018# 1019# @qom-path: link to existing CPU object if CPU is present or omitted 1020# if CPU is not present. 1021# 1022# .. note:: Management should be prepared to pass through additional 1023# properties with `device_add`. 1024# 1025# Since: 2.7 1026## 1027{ 'struct': 'HotpluggableCPU', 1028 'data': { 'type': 'str', 1029 'vcpus-count': 'int', 1030 'props': 'CpuInstanceProperties', 1031 '*qom-path': 'str' 1032 } 1033} 1034 1035## 1036# @query-hotpluggable-cpus: 1037# 1038# TODO: Better documentation; currently there is none. 1039# 1040# Since: 2.7 1041# 1042# .. qmp-example:: 1043# :annotated: 1044# 1045# For pseries machine type started with 1046# ``-smp 2,cores=2,maxcpus=4 -cpu POWER8``:: 1047# 1048# -> { "execute": "query-hotpluggable-cpus" } 1049# <- {"return": [ 1050# { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core", 1051# "vcpus-count": 1 }, 1052# { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", 1053# "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} 1054# ]} 1055# 1056# .. qmp-example:: 1057# :annotated: 1058# 1059# For pc machine type started with ``-smp 1,maxcpus=2``:: 1060# 1061# -> { "execute": "query-hotpluggable-cpus" } 1062# <- {"return": [ 1063# { 1064# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, 1065# "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} 1066# }, 1067# { 1068# "qom-path": "/machine/unattached/device[0]", 1069# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, 1070# "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} 1071# } 1072# ]} 1073# 1074# .. qmp-example:: 1075# :annotated: 1076# 1077# For s390x-virtio-ccw machine type started with 1078# ``-smp 1,maxcpus=2 -cpu qemu``:: 1079# 1080# -> { "execute": "query-hotpluggable-cpus" } 1081# <- {"return": [ 1082# { 1083# "type": "qemu-s390x-cpu", "vcpus-count": 1, 1084# "props": { "core-id": 1 } 1085# }, 1086# { 1087# "qom-path": "/machine/unattached/device[0]", 1088# "type": "qemu-s390x-cpu", "vcpus-count": 1, 1089# "props": { "core-id": 0 } 1090# } 1091# ]} 1092## 1093{ 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'], 1094 'allow-preconfig': true } 1095 1096## 1097# @set-numa-node: 1098# 1099# Runtime equivalent of '-numa' CLI option, available at preconfigure 1100# stage to configure numa mapping before initializing machine. 1101# 1102# Since: 3.0 1103## 1104{ 'command': 'set-numa-node', 'boxed': true, 1105 'data': 'NumaOptions', 1106 'allow-preconfig': true 1107} 1108 1109## 1110# @balloon: 1111# 1112# Request the balloon driver to change its balloon size. 1113# 1114# @value: the target logical size of the VM in bytes. We can deduce 1115# the size of the balloon using this formula: 1116# 1117# logical_vm_size = vm_ram_size - balloon_size 1118# 1119# From it we have: balloon_size = vm_ram_size - @value 1120# 1121# Errors: 1122# - If the balloon driver is enabled but not functional because 1123# the KVM kernel module cannot support it, KVMMissingCap 1124# - If no balloon device is present, DeviceNotActive 1125# 1126# .. note:: This command just issues a request to the guest. When it 1127# returns, the balloon size may not have changed. A guest can 1128# change the balloon size independent of this command. 1129# 1130# Since: 0.14 1131# 1132# .. qmp-example:: 1133# :annotated: 1134# 1135# :: 1136# 1137# -> { "execute": "balloon", "arguments": { "value": 536870912 } } 1138# <- { "return": {} } 1139# 1140# With a 2.5GiB guest this command inflated the ballon to 3GiB. 1141## 1142{ 'command': 'balloon', 'data': {'value': 'int'} } 1143 1144## 1145# @BalloonInfo: 1146# 1147# Information about the guest balloon device. 1148# 1149# @actual: the logical size of the VM in bytes. Formula used: 1150# logical_vm_size = vm_ram_size - balloon_size 1151# 1152# Since: 0.14 1153## 1154{ 'struct': 'BalloonInfo', 'data': {'actual': 'int' } } 1155 1156## 1157# @query-balloon: 1158# 1159# Return information about the balloon device. 1160# 1161# Errors: 1162# - If the balloon driver is enabled but not functional because 1163# the KVM kernel module cannot support it, KVMMissingCap 1164# - If no balloon device is present, DeviceNotActive 1165# 1166# Since: 0.14 1167# 1168# .. qmp-example:: 1169# 1170# -> { "execute": "query-balloon" } 1171# <- { "return": { 1172# "actual": 1073741824 1173# } 1174# } 1175## 1176{ 'command': 'query-balloon', 'returns': 'BalloonInfo' } 1177 1178## 1179# @BALLOON_CHANGE: 1180# 1181# Emitted when the guest changes the actual BALLOON level. This value 1182# is equivalent to the @actual field return by the `query-balloon` 1183# command 1184# 1185# @actual: the logical size of the VM in bytes. Formula used: 1186# logical_vm_size = vm_ram_size - balloon_size 1187# 1188# .. note:: This event is rate-limited. 1189# 1190# Since: 1.2 1191# 1192# .. qmp-example:: 1193# 1194# <- { "event": "BALLOON_CHANGE", 1195# "data": { "actual": 944766976 }, 1196# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } 1197## 1198{ 'event': 'BALLOON_CHANGE', 1199 'data': { 'actual': 'int' } } 1200 1201## 1202# @HvBalloonInfo: 1203# 1204# hv-balloon guest-provided memory status information. 1205# 1206# @committed: the amount of memory in use inside the guest plus the 1207# amount of the memory unusable inside the guest (ballooned out, 1208# offline, etc.) 1209# 1210# @available: the amount of the memory inside the guest available for 1211# new allocations ("free") 1212# 1213# Since: 8.2 1214## 1215{ 'struct': 'HvBalloonInfo', 1216 'data': { 'committed': 'size', 'available': 'size' } } 1217 1218## 1219# @query-hv-balloon-status-report: 1220# 1221# Return the hv-balloon driver data contained in the last received 1222# "STATUS" message from the guest. 1223# 1224# Errors: 1225# - If no hv-balloon device is present, guest memory status 1226# reporting is not enabled or no guest memory status report 1227# received yet, GenericError 1228# 1229# Since: 8.2 1230# 1231# .. qmp-example:: 1232# 1233# -> { "execute": "query-hv-balloon-status-report" } 1234# <- { "return": { 1235# "committed": 816640000, 1236# "available": 3333054464 1237# } 1238# } 1239## 1240{ 'command': 'query-hv-balloon-status-report', 'returns': 'HvBalloonInfo' } 1241 1242## 1243# @HV_BALLOON_STATUS_REPORT: 1244# 1245# Emitted when the hv-balloon driver receives a "STATUS" message from 1246# the guest. 1247# 1248# .. note:: This event is rate-limited. 1249# 1250# Since: 8.2 1251# 1252# .. qmp-example:: 1253# 1254# <- { "event": "HV_BALLOON_STATUS_REPORT", 1255# "data": { "committed": 816640000, "available": 3333054464 }, 1256# "timestamp": { "seconds": 1600295492, "microseconds": 661044 } } 1257## 1258{ 'event': 'HV_BALLOON_STATUS_REPORT', 1259 'data': 'HvBalloonInfo' } 1260 1261## 1262# @MemoryInfo: 1263# 1264# Actual memory information in bytes. 1265# 1266# @base-memory: size of "base" memory specified with command line 1267# option -m. 1268# 1269# @plugged-memory: size of memory that can be hot-unplugged. This 1270# field is omitted if target doesn't support memory hotplug (i.e. 1271# CONFIG_MEM_DEVICE not defined at build time). 1272# 1273# Since: 2.11 1274## 1275{ 'struct': 'MemoryInfo', 1276 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } } 1277 1278## 1279# @query-memory-size-summary: 1280# 1281# Return the amount of initially allocated and present hotpluggable 1282# (if enabled) memory in bytes. 1283# 1284# TODO: This line is a hack to separate the example from the body 1285# 1286# .. qmp-example:: 1287# 1288# -> { "execute": "query-memory-size-summary" } 1289# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } 1290# 1291# Since: 2.11 1292## 1293{ 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' } 1294 1295## 1296# @PCDIMMDeviceInfo: 1297# 1298# PCDIMMDevice state information 1299# 1300# @id: device's ID 1301# 1302# @addr: physical address, where device is mapped 1303# 1304# @size: size of memory that the device provides 1305# 1306# @slot: slot number at which device is plugged in 1307# 1308# @node: NUMA node number where device is plugged in 1309# 1310# @memdev: memory backend linked with device 1311# 1312# @hotplugged: true if device was hotplugged 1313# 1314# @hotpluggable: true if device if could be added/removed while 1315# machine is running 1316# 1317# Since: 2.1 1318## 1319{ 'struct': 'PCDIMMDeviceInfo', 1320 'data': { '*id': 'str', 1321 'addr': 'int', 1322 'size': 'int', 1323 'slot': 'int', 1324 'node': 'int', 1325 'memdev': 'str', 1326 'hotplugged': 'bool', 1327 'hotpluggable': 'bool' 1328 } 1329} 1330 1331## 1332# @VirtioPMEMDeviceInfo: 1333# 1334# VirtioPMEM state information 1335# 1336# @id: device's ID 1337# 1338# @memaddr: physical address in memory, where device is mapped 1339# 1340# @size: size of memory that the device provides 1341# 1342# @memdev: memory backend linked with device 1343# 1344# Since: 4.1 1345## 1346{ 'struct': 'VirtioPMEMDeviceInfo', 1347 'data': { '*id': 'str', 1348 'memaddr': 'size', 1349 'size': 'size', 1350 'memdev': 'str' 1351 } 1352} 1353 1354## 1355# @VirtioMEMDeviceInfo: 1356# 1357# VirtioMEMDevice state information 1358# 1359# @id: device's ID 1360# 1361# @memaddr: physical address in memory, where device is mapped 1362# 1363# @requested-size: the user requested size of the device 1364# 1365# @size: the (current) size of memory that the device provides 1366# 1367# @max-size: the maximum size of memory that the device can provide 1368# 1369# @block-size: the block size of memory that the device provides 1370# 1371# @node: NUMA node number where device is assigned to 1372# 1373# @memdev: memory backend linked with the region 1374# 1375# Since: 5.1 1376## 1377{ 'struct': 'VirtioMEMDeviceInfo', 1378 'data': { '*id': 'str', 1379 'memaddr': 'size', 1380 'requested-size': 'size', 1381 'size': 'size', 1382 'max-size': 'size', 1383 'block-size': 'size', 1384 'node': 'int', 1385 'memdev': 'str' 1386 } 1387} 1388 1389## 1390# @SgxEPCDeviceInfo: 1391# 1392# Sgx EPC state information 1393# 1394# @id: device's ID 1395# 1396# @memaddr: physical address in memory, where device is mapped 1397# 1398# @size: size of memory that the device provides 1399# 1400# @memdev: memory backend linked with device 1401# 1402# @node: the numa node (Since: 7.0) 1403# 1404# Since: 6.2 1405## 1406{ 'struct': 'SgxEPCDeviceInfo', 1407 'data': { '*id': 'str', 1408 'memaddr': 'size', 1409 'size': 'size', 1410 'node': 'int', 1411 'memdev': 'str' 1412 } 1413} 1414 1415## 1416# @HvBalloonDeviceInfo: 1417# 1418# hv-balloon provided memory state information 1419# 1420# @id: device's ID 1421# 1422# @memaddr: physical address in memory, where device is mapped 1423# 1424# @max-size: the maximum size of memory that the device can provide 1425# 1426# @memdev: memory backend linked with device 1427# 1428# Since: 8.2 1429## 1430{ 'struct': 'HvBalloonDeviceInfo', 1431 'data': { '*id': 'str', 1432 '*memaddr': 'size', 1433 'max-size': 'size', 1434 '*memdev': 'str' 1435 } 1436} 1437 1438## 1439# @MemoryDeviceInfoKind: 1440# 1441# @nvdimm: since 2.12 1442# 1443# @virtio-pmem: since 4.1 1444# 1445# @virtio-mem: since 5.1 1446# 1447# @sgx-epc: since 6.2. 1448# 1449# @hv-balloon: since 8.2. 1450# 1451# Since: 2.1 1452## 1453{ 'enum': 'MemoryDeviceInfoKind', 1454 'data': [ 'dimm', 'nvdimm', 'virtio-pmem', 'virtio-mem', 'sgx-epc', 1455 'hv-balloon' ] } 1456 1457## 1458# @PCDIMMDeviceInfoWrapper: 1459# 1460# @data: PCDIMMDevice state information 1461# 1462# Since: 2.1 1463## 1464{ 'struct': 'PCDIMMDeviceInfoWrapper', 1465 'data': { 'data': 'PCDIMMDeviceInfo' } } 1466 1467## 1468# @VirtioPMEMDeviceInfoWrapper: 1469# 1470# @data: VirtioPMEM state information 1471# 1472# Since: 2.1 1473## 1474{ 'struct': 'VirtioPMEMDeviceInfoWrapper', 1475 'data': { 'data': 'VirtioPMEMDeviceInfo' } } 1476 1477## 1478# @VirtioMEMDeviceInfoWrapper: 1479# 1480# @data: VirtioMEMDevice state information 1481# 1482# Since: 2.1 1483## 1484{ 'struct': 'VirtioMEMDeviceInfoWrapper', 1485 'data': { 'data': 'VirtioMEMDeviceInfo' } } 1486 1487## 1488# @SgxEPCDeviceInfoWrapper: 1489# 1490# @data: Sgx EPC state information 1491# 1492# Since: 6.2 1493## 1494{ 'struct': 'SgxEPCDeviceInfoWrapper', 1495 'data': { 'data': 'SgxEPCDeviceInfo' } } 1496 1497## 1498# @HvBalloonDeviceInfoWrapper: 1499# 1500# @data: hv-balloon provided memory state information 1501# 1502# Since: 8.2 1503## 1504{ 'struct': 'HvBalloonDeviceInfoWrapper', 1505 'data': { 'data': 'HvBalloonDeviceInfo' } } 1506 1507## 1508# @MemoryDeviceInfo: 1509# 1510# Union containing information about a memory device 1511# 1512# @type: memory device type 1513# 1514# Since: 2.1 1515## 1516{ 'union': 'MemoryDeviceInfo', 1517 'base': { 'type': 'MemoryDeviceInfoKind' }, 1518 'discriminator': 'type', 1519 'data': { 'dimm': 'PCDIMMDeviceInfoWrapper', 1520 'nvdimm': 'PCDIMMDeviceInfoWrapper', 1521 'virtio-pmem': 'VirtioPMEMDeviceInfoWrapper', 1522 'virtio-mem': 'VirtioMEMDeviceInfoWrapper', 1523 'sgx-epc': 'SgxEPCDeviceInfoWrapper', 1524 'hv-balloon': 'HvBalloonDeviceInfoWrapper' 1525 } 1526} 1527 1528## 1529# @SgxEPC: 1530# 1531# Sgx EPC cmdline information 1532# 1533# @memdev: memory backend linked with device 1534# 1535# @node: the numa node (Since: 7.0) 1536# 1537# Since: 6.2 1538## 1539{ 'struct': 'SgxEPC', 1540 'data': { 'memdev': 'str', 1541 'node': 'int' 1542 } 1543} 1544 1545## 1546# @SgxEPCProperties: 1547# 1548# SGX properties of machine types. 1549# 1550# @sgx-epc: list of ids of memory-backend-epc objects. 1551# 1552# Since: 6.2 1553## 1554{ 'struct': 'SgxEPCProperties', 1555 'data': { 'sgx-epc': ['SgxEPC'] } 1556} 1557 1558## 1559# @query-memory-devices: 1560# 1561# Lists available memory devices and their state 1562# 1563# Since: 2.1 1564# 1565# .. qmp-example:: 1566# 1567# -> { "execute": "query-memory-devices" } 1568# <- { "return": [ { "data": 1569# { "addr": 5368709120, 1570# "hotpluggable": true, 1571# "hotplugged": true, 1572# "id": "d1", 1573# "memdev": "/objects/memX", 1574# "node": 0, 1575# "size": 1073741824, 1576# "slot": 0}, 1577# "type": "dimm" 1578# } ] } 1579## 1580{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } 1581 1582## 1583# @MEMORY_DEVICE_SIZE_CHANGE: 1584# 1585# Emitted when the size of a memory device changes. Only emitted for 1586# memory devices that can actually change the size (e.g., virtio-mem 1587# due to guest action). 1588# 1589# @id: device's ID 1590# 1591# @size: the new size of memory that the device provides 1592# 1593# @qom-path: path to the device object in the QOM tree (since 6.2) 1594# 1595# .. note:: This event is rate-limited. 1596# 1597# Since: 5.1 1598# 1599# .. qmp-example:: 1600# 1601# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", 1602# "data": { "id": "vm0", "size": 1073741824, 1603# "qom-path": "/machine/unattached/device[2]" }, 1604# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } 1605## 1606{ 'event': 'MEMORY_DEVICE_SIZE_CHANGE', 1607 'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} } 1608 1609## 1610# @BootConfiguration: 1611# 1612# Schema for virtual machine boot configuration. 1613# 1614# @order: Boot order (a=floppy, c=hard disk, d=CD-ROM, n=network) 1615# 1616# @once: Boot order to apply on first boot 1617# 1618# @menu: Whether to show a boot menu 1619# 1620# @splash: The name of the file to be passed to the firmware as logo 1621# picture, if @menu is true. 1622# 1623# @splash-time: How long to show the logo picture, in milliseconds 1624# 1625# @reboot-timeout: Timeout before guest reboots after boot fails 1626# 1627# @strict: Whether to attempt booting from devices not included in the 1628# boot order 1629# 1630# Since: 7.1 1631## 1632{ 'struct': 'BootConfiguration', 'data': { 1633 '*order': 'str', 1634 '*once': 'str', 1635 '*menu': 'bool', 1636 '*splash': 'str', 1637 '*splash-time': 'int', 1638 '*reboot-timeout': 'int', 1639 '*strict': 'bool' } } 1640 1641## 1642# @SMPConfiguration: 1643# 1644# Schema for CPU topology configuration. A missing value lets QEMU 1645# figure out a suitable value based on the ones that are provided. 1646# 1647# The members other than @cpus and @maxcpus define a topology of 1648# containers. 1649# 1650# The ordering from highest/coarsest to lowest/finest is: @drawers, 1651# @books, @sockets, @dies, @clusters, @cores, @threads. 1652# 1653# Different architectures support different subsets of topology 1654# containers. 1655# 1656# For example, s390x does not have clusters and dies, and the socket 1657# is the parent container of cores. 1658# 1659# @cpus: number of virtual CPUs in the virtual machine 1660# 1661# @maxcpus: maximum number of hotpluggable virtual CPUs in the virtual 1662# machine 1663# 1664# @drawers: number of drawers in the CPU topology (since 8.2) 1665# 1666# @books: number of books in the CPU topology (since 8.2) 1667# 1668# @sockets: number of sockets per parent container 1669# 1670# @dies: number of dies per parent container 1671# 1672# @clusters: number of clusters per parent container (since 7.0) 1673# 1674# @modules: number of modules per parent container (since 9.1) 1675# 1676# @cores: number of cores per parent container 1677# 1678# @threads: number of threads per core 1679# 1680# Since: 6.1 1681## 1682{ 'struct': 'SMPConfiguration', 'data': { 1683 '*cpus': 'int', 1684 '*drawers': 'int', 1685 '*books': 'int', 1686 '*sockets': 'int', 1687 '*dies': 'int', 1688 '*clusters': 'int', 1689 '*modules': 'int', 1690 '*cores': 'int', 1691 '*threads': 'int', 1692 '*maxcpus': 'int' } } 1693 1694## 1695# @x-query-irq: 1696# 1697# Query interrupt statistics 1698# 1699# Features: 1700# 1701# @unstable: This command is meant for debugging. 1702# 1703# Returns: interrupt statistics 1704# 1705# Since: 6.2 1706## 1707{ 'command': 'x-query-irq', 1708 'returns': 'HumanReadableText', 1709 'features': [ 'unstable' ] } 1710 1711## 1712# @x-query-jit: 1713# 1714# Query TCG compiler statistics 1715# 1716# Features: 1717# 1718# @unstable: This command is meant for debugging. 1719# 1720# Returns: TCG compiler statistics 1721# 1722# Since: 6.2 1723## 1724{ 'command': 'x-query-jit', 1725 'returns': 'HumanReadableText', 1726 'if': 'CONFIG_TCG', 1727 'features': [ 'unstable' ] } 1728 1729## 1730# @x-query-numa: 1731# 1732# Query NUMA topology information 1733# 1734# Features: 1735# 1736# @unstable: This command is meant for debugging. 1737# 1738# Returns: topology information 1739# 1740# Since: 6.2 1741## 1742{ 'command': 'x-query-numa', 1743 'returns': 'HumanReadableText', 1744 'features': [ 'unstable' ] } 1745 1746## 1747# @x-query-ramblock: 1748# 1749# Query system ramblock information 1750# 1751# Features: 1752# 1753# @unstable: This command is meant for debugging. 1754# 1755# Returns: system ramblock information 1756# 1757# Since: 6.2 1758## 1759{ 'command': 'x-query-ramblock', 1760 'returns': 'HumanReadableText', 1761 'features': [ 'unstable' ] } 1762 1763## 1764# @x-query-roms: 1765# 1766# Query information on the registered ROMS 1767# 1768# Features: 1769# 1770# @unstable: This command is meant for debugging. 1771# 1772# Returns: registered ROMs 1773# 1774# Since: 6.2 1775## 1776{ 'command': 'x-query-roms', 1777 'returns': 'HumanReadableText', 1778 'features': [ 'unstable' ] } 1779 1780## 1781# @x-query-usb: 1782# 1783# Query information on the USB devices 1784# 1785# Features: 1786# 1787# @unstable: This command is meant for debugging. 1788# 1789# Returns: USB device information 1790# 1791# Since: 6.2 1792## 1793{ 'command': 'x-query-usb', 1794 'returns': 'HumanReadableText', 1795 'features': [ 'unstable' ] } 1796 1797## 1798# @SmbiosEntryPointType: 1799# 1800# @32: SMBIOS version 2.1 (32-bit) Entry Point 1801# 1802# @64: SMBIOS version 3.0 (64-bit) Entry Point 1803# 1804# @auto: Either 2.x or 3.x SMBIOS version, 2.x if configuration can be 1805# described by it and 3.x otherwise (since: 9.0) 1806# 1807# Since: 7.0 1808## 1809{ 'enum': 'SmbiosEntryPointType', 1810 'data': [ '32', '64', 'auto' ] } 1811 1812## 1813# @MemorySizeConfiguration: 1814# 1815# Schema for memory size configuration. 1816# 1817# @size: memory size in bytes 1818# 1819# @max-size: maximum hotpluggable memory size in bytes 1820# 1821# @slots: number of available memory slots for hotplug 1822# 1823# Since: 7.1 1824## 1825{ 'struct': 'MemorySizeConfiguration', 'data': { 1826 '*size': 'size', 1827 '*max-size': 'size', 1828 '*slots': 'uint64' } } 1829 1830## 1831# @dumpdtb: 1832# 1833# Save the FDT in dtb format. 1834# 1835# @filename: name of the dtb file to be created 1836# 1837# Since: 7.2 1838# 1839# .. qmp-example:: 1840# 1841# -> { "execute": "dumpdtb" } 1842# "arguments": { "filename": "fdt.dtb" } } 1843# <- { "return": {} } 1844## 1845{ 'command': 'dumpdtb', 1846 'data': { 'filename': 'str' }, 1847 'if': 'CONFIG_FDT' } 1848 1849## 1850# @x-query-interrupt-controllers: 1851# 1852# Query information on interrupt controller devices 1853# 1854# Features: 1855# 1856# @unstable: This command is meant for debugging. 1857# 1858# Returns: Interrupt controller devices information 1859# 1860# Since: 9.1 1861## 1862{ 'command': 'x-query-interrupt-controllers', 1863 'returns': 'HumanReadableText', 1864 'features': [ 'unstable' ]} 1865 1866## 1867# @dump-skeys: 1868# 1869# Dump the storage keys for an s390x guest 1870# 1871# @filename: the path to the file to dump to 1872# 1873# Since: 2.5 1874# 1875# .. qmp-example:: 1876# 1877# -> { "execute": "dump-skeys", 1878# "arguments": { "filename": "/tmp/skeys" } } 1879# <- { "return": {} } 1880## 1881{ 'command': 'dump-skeys', 1882 'data': { 'filename': 'str' } } 1883 1884## 1885# @CpuModelInfo: 1886# 1887# Virtual CPU model. 1888# 1889# A CPU model consists of the name of a CPU definition, to which delta 1890# changes are applied (e.g. features added/removed). Most magic 1891# values that an architecture might require should be hidden behind 1892# the name. However, if required, architectures can expose relevant 1893# properties. 1894# 1895# @name: the name of the CPU definition the model is based on 1896# 1897# @props: a dictionary of QOM properties to be applied 1898# 1899# Since: 2.8 1900## 1901{ 'struct': 'CpuModelInfo', 1902 'data': { 'name': 'str', 1903 '*props': 'any' } } 1904 1905## 1906# @CpuModelExpansionType: 1907# 1908# An enumeration of CPU model expansion types. 1909# 1910# @static: Expand to a static CPU model, a combination of a static 1911# base model name and property delta changes. As the static base 1912# model will never change, the expanded CPU model will be the 1913# same, independent of QEMU version, machine type, machine 1914# options, and accelerator options. Therefore, the resulting 1915# model can be used by tooling without having to specify a 1916# compatibility machine - e.g. when displaying the "host" model. 1917# The @static CPU models are migration-safe. 1918# 1919# @full: Expand all properties. The produced model is not guaranteed 1920# to be migration-safe, but allows tooling to get an insight and 1921# work with model details. 1922# 1923# .. note:: When a non-migration-safe CPU model is expanded in static 1924# mode, some features enabled by the CPU model may be omitted, 1925# because they can't be implemented by a static CPU model 1926# definition (e.g. cache info passthrough and PMU passthrough in 1927# x86). If you need an accurate representation of the features 1928# enabled by a non-migration-safe CPU model, use @full. If you 1929# need a static representation that will keep ABI compatibility 1930# even when changing QEMU version or machine-type, use @static (but 1931# keep in mind that some features may be omitted). 1932# 1933# Since: 2.8 1934## 1935{ 'enum': 'CpuModelExpansionType', 1936 'data': [ 'static', 'full' ] } 1937 1938## 1939# @CpuModelCompareResult: 1940# 1941# An enumeration of CPU model comparison results. The result is 1942# usually calculated using e.g. CPU features or CPU generations. 1943# 1944# @incompatible: If model A is incompatible to model B, model A is not 1945# guaranteed to run where model B runs and the other way around. 1946# 1947# @identical: If model A is identical to model B, model A is 1948# guaranteed to run where model B runs and the other way around. 1949# 1950# @superset: If model A is a superset of model B, model B is 1951# guaranteed to run where model A runs. There are no guarantees 1952# about the other way. 1953# 1954# @subset: If model A is a subset of model B, model A is guaranteed to 1955# run where model B runs. There are no guarantees about the other 1956# way. 1957# 1958# Since: 2.8 1959## 1960{ 'enum': 'CpuModelCompareResult', 1961 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } 1962 1963## 1964# @CpuModelBaselineInfo: 1965# 1966# The result of a CPU model baseline. 1967# 1968# @model: the baselined `CpuModelInfo`. 1969# 1970# Since: 2.8 1971## 1972{ 'struct': 'CpuModelBaselineInfo', 1973 'data': { 'model': 'CpuModelInfo' } } 1974 1975## 1976# @CpuModelCompareInfo: 1977# 1978# The result of a CPU model comparison. 1979# 1980# @result: The result of the compare operation. 1981# 1982# @responsible-properties: List of properties that led to the 1983# comparison result not being identical. 1984# 1985# @responsible-properties is a list of QOM property names that led to 1986# both CPUs not being detected as identical. For identical models, 1987# this list is empty. If a QOM property is read-only, that means 1988# there's no known way to make the CPU models identical. If the 1989# special property name "type" is included, the models are by 1990# definition not identical and cannot be made identical. 1991# 1992# Since: 2.8 1993## 1994{ 'struct': 'CpuModelCompareInfo', 1995 'data': { 'result': 'CpuModelCompareResult', 1996 'responsible-properties': ['str'] } } 1997 1998## 1999# @query-cpu-model-comparison: 2000# 2001# Compares two CPU models, @modela and @modelb, returning how they 2002# compare in a specific configuration. The results indicates how 2003# both models compare regarding runnability. This result can be 2004# used by tooling to make decisions if a certain CPU model will 2005# run in a certain configuration or if a compatible CPU model has 2006# to be created by baselining. 2007# 2008# Usually, a CPU model is compared against the maximum possible CPU 2009# model of a certain configuration (e.g. the "host" model for KVM). 2010# If that CPU model is identical or a subset, it will run in that 2011# configuration. 2012# 2013# The result returned by this command may be affected by: 2014# 2015# * QEMU version: CPU models may look different depending on the QEMU 2016# version. (Except for CPU models reported as "static" in 2017# `query-cpu-definitions`.) 2018# * machine-type: CPU model may look different depending on the 2019# machine-type. (Except for CPU models reported as "static" in 2020# `query-cpu-definitions`.) 2021# * machine options (including accelerator): in some architectures, 2022# CPU models may look different depending on machine and accelerator 2023# options. (Except for CPU models reported as "static" in 2024# `query-cpu-definitions`.) 2025# * "-cpu" arguments and global properties: arguments to the -cpu 2026# option and global properties may affect expansion of CPU models. 2027# Using `query-cpu-model-expansion` while using these is not advised. 2028# 2029# Some architectures may not support comparing CPU models. s390x 2030# supports comparing CPU models. 2031# 2032# @modela: description of the first CPU model to compare, referred to 2033# as "model A" in `CpuModelCompareResult` 2034# 2035# @modelb: description of the second CPU model to compare, referred to 2036# as "model B" in `CpuModelCompareResult` 2037# 2038# Returns: a `CpuModelCompareInfo` describing how both CPU models 2039# compare 2040# 2041# Errors: 2042# - if comparing CPU models is not supported by the target 2043# - if a model cannot be used 2044# - if a model contains an unknown cpu definition name, unknown 2045# properties or properties with wrong types. 2046# 2047# Since: 2.8 2048## 2049{ 'command': 'query-cpu-model-comparison', 2050 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 2051 'returns': 'CpuModelCompareInfo' } 2052 2053## 2054# @query-cpu-model-baseline: 2055# 2056# Baseline two CPU models, @modela and @modelb, creating a compatible 2057# third model. The created model will always be a static, 2058# migration-safe CPU model (see "static" CPU model expansion for 2059# details). 2060# 2061# This interface can be used by tooling to create a compatible CPU 2062# model out two CPU models. The created CPU model will be identical 2063# to or a subset of both CPU models when comparing them. Therefore, 2064# the created CPU model is guaranteed to run where the given CPU 2065# models run. 2066# 2067# The result returned by this command may be affected by: 2068# 2069# * QEMU version: CPU models may look different depending on the QEMU 2070# version. (Except for CPU models reported as "static" in 2071# `query-cpu-definitions`.) 2072# * machine-type: CPU model may look different depending on the 2073# machine-type. (Except for CPU models reported as "static" in 2074# `query-cpu-definitions`.) 2075# * machine options (including accelerator): in some architectures, 2076# CPU models may look different depending on machine and accelerator 2077# options. (Except for CPU models reported as "static" in 2078# `query-cpu-definitions`.) 2079# * "-cpu" arguments and global properties: arguments to the -cpu 2080# option and global properties may affect expansion of CPU models. 2081# Using `query-cpu-model-expansion` while using these is not advised. 2082# 2083# Some architectures may not support baselining CPU models. s390x 2084# supports baselining CPU models. 2085# 2086# @modela: description of the first CPU model to baseline 2087# 2088# @modelb: description of the second CPU model to baseline 2089# 2090# Returns: a `CpuModelBaselineInfo` describing the baselined CPU model 2091# 2092# Errors: 2093# - if baselining CPU models is not supported by the target 2094# - if a model cannot be used 2095# - if a model contains an unknown cpu definition name, unknown 2096# properties or properties with wrong types. 2097# 2098# Since: 2.8 2099## 2100{ 'command': 'query-cpu-model-baseline', 2101 'data': { 'modela': 'CpuModelInfo', 2102 'modelb': 'CpuModelInfo' }, 2103 'returns': 'CpuModelBaselineInfo' } 2104 2105## 2106# @CpuModelExpansionInfo: 2107# 2108# The result of a cpu model expansion. 2109# 2110# @model: the expanded `CpuModelInfo`. 2111# 2112# @deprecated-props: an optional list of properties that are flagged as 2113# deprecated by the CPU vendor. The list depends on the 2114# CpuModelExpansionType: "static" properties are a subset of the 2115# enabled-properties for the expanded model; "full" properties are 2116# a set of properties that are deprecated across all models for 2117# the architecture. (since: 10.1 -- since 9.1 on s390x --). 2118# 2119# Since: 2.8 2120## 2121{ 'struct': 'CpuModelExpansionInfo', 2122 'data': { 'model': 'CpuModelInfo', 2123 '*deprecated-props' : ['str'] } } 2124 2125## 2126# @query-cpu-model-expansion: 2127# 2128# Expands a given CPU model, @model, (or a combination of CPU model + 2129# additional options) to different granularities, specified by @type, 2130# allowing tooling to get an understanding what a specific CPU model 2131# looks like in QEMU under a certain configuration. 2132# 2133# This interface can be used to query the "host" CPU model. 2134# 2135# The data returned by this command may be affected by: 2136# 2137# * QEMU version: CPU models may look different depending on the QEMU 2138# version. (Except for CPU models reported as "static" in 2139# `query-cpu-definitions`.) 2140# * machine-type: CPU model may look different depending on the 2141# machine-type. (Except for CPU models reported as "static" in 2142# `query-cpu-definitions`.) 2143# * machine options (including accelerator): in some architectures, 2144# CPU models may look different depending on machine and accelerator 2145# options. (Except for CPU models reported as "static" in 2146# `query-cpu-definitions`.) 2147# * "-cpu" arguments and global properties: arguments to the -cpu 2148# option and global properties may affect expansion of CPU models. 2149# Using `query-cpu-model-expansion` while using these is not advised. 2150# 2151# Some architectures may not support all expansion types. s390x 2152# supports "full" and "static". Arm only supports "full". 2153# 2154# @model: description of the CPU model to expand 2155# 2156# @type: expansion type, specifying how to expand the CPU model 2157# 2158# Returns: a `CpuModelExpansionInfo` describing the expanded CPU model 2159# 2160# Errors: 2161# - if expanding CPU models is not supported 2162# - if the model cannot be expanded 2163# - if the model contains an unknown CPU definition name, unknown 2164# properties or properties with a wrong type 2165# - if an expansion type is not supported 2166# 2167# Since: 2.8 2168## 2169{ 'command': 'query-cpu-model-expansion', 2170 'data': { 'type': 'CpuModelExpansionType', 2171 'model': 'CpuModelInfo' }, 2172 'returns': 'CpuModelExpansionInfo' } 2173 2174## 2175# @CpuDefinitionInfo: 2176# 2177# Virtual CPU definition. 2178# 2179# @name: the name of the CPU definition 2180# 2181# @migration-safe: whether a CPU definition can be safely used for 2182# migration in combination with a QEMU compatibility machine when 2183# migrating between different QEMU versions and between hosts with 2184# different sets of (hardware or software) capabilities. If not 2185# provided, information is not available and callers should not 2186# assume the CPU definition to be migration-safe. (since 2.8) 2187# 2188# @static: whether a CPU definition is static and will not change 2189# depending on QEMU version, machine type, machine options and 2190# accelerator options. A static model is always migration-safe. 2191# (since 2.8) 2192# 2193# @unavailable-features: List of properties that prevent the CPU model 2194# from running in the current host. (since 2.8) 2195# 2196# @typename: Type name that can be used as argument to 2197# `device-list-properties`, to introspect properties configurable 2198# using -cpu or -global. (since 2.9) 2199# 2200# @alias-of: Name of CPU model this model is an alias for. The target 2201# of the CPU model alias may change depending on the machine type. 2202# Management software is supposed to translate CPU model aliases 2203# in the VM configuration, because aliases may stop being 2204# migration-safe in the future (since 4.1) 2205# 2206# @deprecated: If true, this CPU model is deprecated and may be 2207# removed in some future version of QEMU according to the QEMU 2208# deprecation policy. (since 5.2) 2209# 2210# @unavailable-features is a list of QOM property names that represent 2211# CPU model attributes that prevent the CPU from running. If the QOM 2212# property is read-only, that means there's no known way to make the 2213# CPU model run in the current host. Implementations that choose not 2214# to provide specific information return the property name "type". If 2215# the property is read-write, it means that it MAY be possible to run 2216# the CPU model in the current host if that property is changed. 2217# Management software can use it as hints to suggest or choose an 2218# alternative for the user, or just to generate meaningful error 2219# messages explaining why the CPU model can't be used. If 2220# @unavailable-features is an empty list, the CPU model is runnable 2221# using the current host and machine-type. If @unavailable-features 2222# is not present, runnability information for the CPU is not 2223# available. 2224# 2225# Since: 1.2 2226## 2227{ 'struct': 'CpuDefinitionInfo', 2228 'data': { 'name': 'str', 2229 '*migration-safe': 'bool', 2230 'static': 'bool', 2231 '*unavailable-features': [ 'str' ], 2232 'typename': 'str', 2233 '*alias-of' : 'str', 2234 'deprecated' : 'bool' } } 2235 2236## 2237# @query-cpu-definitions: 2238# 2239# Return a list of supported virtual CPU definitions 2240# 2241# Since: 1.2 2242## 2243{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] } 2244