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