1# -*- Mode: Python -*- 2## 3# = Introduction 4# 5# This document describes all commands currently supported by QMP. 6# 7# Most of the time their usage is exactly the same as in the user Monitor, this 8# means that any other document which also describe commands (the manpage, 9# QEMU's manual, etc) can and should be consulted. 10# 11# QMP has two types of commands: regular and query commands. Regular commands 12# usually change the Virtual Machine's state someway, while query commands just 13# return information. The sections below are divided accordingly. 14# 15# It's important to observe that all communication examples are formatted in 16# a reader-friendly way, so that they're easier to understand. However, in real 17# protocol usage, they're emitted as a single line. 18# 19# Also, the following notation is used to denote data flow: 20# 21# Example: 22# 23# | -> data issued by the Client 24# | <- Server data response 25# 26# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for 27# detailed information on the Server command and response formats. 28# 29# = Stability Considerations 30# 31# The current QMP command set (described in this file) may be useful for a 32# number of use cases, however it's limited and several commands have bad 33# defined semantics, specially with regard to command completion. 34# 35# These problems are going to be solved incrementally in the next QEMU releases 36# and we're going to establish a deprecation policy for badly defined commands. 37# 38# If you're planning to adopt QMP, please observe the following: 39# 40# 1. The deprecation policy will take effect and be documented soon, please 41# check the documentation of each used command as soon as a new release of 42# QEMU is available 43# 44# 2. DO NOT rely on anything which is not explicit documented 45# 46# 3. Errors, in special, are not documented. Applications should NOT check 47# for specific errors classes or data (it's strongly recommended to only 48# check for the "error" key) 49# 50## 51 52{ 'pragma': { 'doc-required': true } } 53 54# Whitelists to permit QAPI rule violations; think twice before you 55# add to them! 56{ 'pragma': { 57 # Commands allowed to return a non-dictionary: 58 'returns-whitelist': [ 59 'human-monitor-command', 60 'qom-get', 61 'query-migrate-cache-size', 62 'query-tpm-models', 63 'query-tpm-types', 64 'ringbuf-read' ], 65 'name-case-whitelist': [ 66 'ACPISlotType', # DIMM, visible through query-acpi-ospm-status 67 'CpuInfoMIPS', # PC, visible through query-cpu 68 'CpuInfoTricore', # PC, visible through query-cpu 69 'QapiErrorClass', # all members, visible through errors 70 'UuidInfo', # UUID, visible through query-uuid 71 'X86CPURegister32', # all members, visible indirectly through qom-get 72 'q_obj_CpuInfo-base' # CPU, visible through query-cpu 73 ] } } 74 75# Documentation generated with qapi2texi.py is in source order, with 76# included sub-schemas inserted at the first include directive 77# (subsequent include directives have no effect). To get a sane and 78# stable order, it's best to include each sub-schema just once, or 79# include it first in qapi-schema.json. 80 81{ 'include': 'qapi/common.json' } 82{ 'include': 'qapi/sockets.json' } 83{ 'include': 'qapi/run-state.json' } 84{ 'include': 'qapi/crypto.json' } 85{ 'include': 'qapi/block.json' } 86{ 'include': 'qapi/char.json' } 87{ 'include': 'qapi/net.json' } 88{ 'include': 'qapi/rocker.json' } 89{ 'include': 'qapi/tpm.json' } 90{ 'include': 'qapi/ui.json' } 91{ 'include': 'qapi/migration.json' } 92{ 'include': 'qapi/transaction.json' } 93{ 'include': 'qapi/trace.json' } 94{ 'include': 'qapi/introspect.json' } 95 96## 97# = Miscellanea 98## 99 100## 101# @qmp_capabilities: 102# 103# Enable QMP capabilities. 104# 105# Arguments: None. 106# 107# Example: 108# 109# -> { "execute": "qmp_capabilities" } 110# <- { "return": {} } 111# 112# Notes: This command is valid exactly when first connecting: it must be 113# issued before any other command will be accepted, and will fail once the 114# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt) 115# 116# Since: 0.13 117# 118## 119{ 'command': 'qmp_capabilities' } 120 121## 122# @VersionTriple: 123# 124# A three-part version number. 125# 126# @major: The major version number. 127# 128# @minor: The minor version number. 129# 130# @micro: The micro version number. 131# 132# Since: 2.4 133## 134{ 'struct': 'VersionTriple', 135 'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} } 136 137 138## 139# @VersionInfo: 140# 141# A description of QEMU's version. 142# 143# @qemu: The version of QEMU. By current convention, a micro 144# version of 50 signifies a development branch. A micro version 145# greater than or equal to 90 signifies a release candidate for 146# the next minor version. A micro version of less than 50 147# signifies a stable release. 148# 149# @package: QEMU will always set this field to an empty string. Downstream 150# versions of QEMU should set this to a non-empty string. The 151# exact format depends on the downstream however it highly 152# recommended that a unique name is used. 153# 154# Since: 0.14.0 155## 156{ 'struct': 'VersionInfo', 157 'data': {'qemu': 'VersionTriple', 'package': 'str'} } 158 159## 160# @query-version: 161# 162# Returns the current version of QEMU. 163# 164# Returns: A @VersionInfo object describing the current version of QEMU. 165# 166# Since: 0.14.0 167# 168# Example: 169# 170# -> { "execute": "query-version" } 171# <- { 172# "return":{ 173# "qemu":{ 174# "major":0, 175# "minor":11, 176# "micro":5 177# }, 178# "package":"" 179# } 180# } 181# 182## 183{ 'command': 'query-version', 'returns': 'VersionInfo' } 184 185## 186# @CommandInfo: 187# 188# Information about a QMP command 189# 190# @name: The command name 191# 192# Since: 0.14.0 193## 194{ 'struct': 'CommandInfo', 'data': {'name': 'str'} } 195 196## 197# @query-commands: 198# 199# Return a list of supported QMP commands by this server 200# 201# Returns: A list of @CommandInfo for all supported commands 202# 203# Since: 0.14.0 204# 205# Example: 206# 207# -> { "execute": "query-commands" } 208# <- { 209# "return":[ 210# { 211# "name":"query-balloon" 212# }, 213# { 214# "name":"system_powerdown" 215# } 216# ] 217# } 218# 219# Note: This example has been shortened as the real response is too long. 220# 221## 222{ 'command': 'query-commands', 'returns': ['CommandInfo'] } 223 224## 225# @LostTickPolicy: 226# 227# Policy for handling lost ticks in timer devices. 228# 229# @discard: throw away the missed tick(s) and continue with future injection 230# normally. Guest time may be delayed, unless the OS has explicit 231# handling of lost ticks 232# 233# @delay: continue to deliver ticks at the normal rate. Guest time will be 234# delayed due to the late tick 235# 236# @merge: merge the missed tick(s) into one tick and inject. Guest time 237# may be delayed, depending on how the OS reacts to the merging 238# of ticks 239# 240# @slew: deliver ticks at a higher rate to catch up with the missed tick. The 241# guest time should not be delayed once catchup is complete. 242# 243# Since: 2.0 244## 245{ 'enum': 'LostTickPolicy', 246 'data': ['discard', 'delay', 'merge', 'slew' ] } 247 248## 249# @add_client: 250# 251# Allow client connections for VNC, Spice and socket based 252# character devices to be passed in to QEMU via SCM_RIGHTS. 253# 254# @protocol: protocol name. Valid names are "vnc", "spice" or the 255# name of a character device (eg. from -chardev id=XXXX) 256# 257# @fdname: file descriptor name previously passed via 'getfd' command 258# 259# @skipauth: whether to skip authentication. Only applies 260# to "vnc" and "spice" protocols 261# 262# @tls: whether to perform TLS. Only applies to the "spice" 263# protocol 264# 265# Returns: nothing on success. 266# 267# Since: 0.14.0 268# 269# Example: 270# 271# -> { "execute": "add_client", "arguments": { "protocol": "vnc", 272# "fdname": "myclient" } } 273# <- { "return": {} } 274# 275## 276{ 'command': 'add_client', 277 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool', 278 '*tls': 'bool' } } 279 280## 281# @NameInfo: 282# 283# Guest name information. 284# 285# @name: The name of the guest 286# 287# Since: 0.14.0 288## 289{ 'struct': 'NameInfo', 'data': {'*name': 'str'} } 290 291## 292# @query-name: 293# 294# Return the name information of a guest. 295# 296# Returns: @NameInfo of the guest 297# 298# Since: 0.14.0 299# 300# Example: 301# 302# -> { "execute": "query-name" } 303# <- { "return": { "name": "qemu-name" } } 304# 305## 306{ 'command': 'query-name', 'returns': 'NameInfo' } 307 308## 309# @KvmInfo: 310# 311# Information about support for KVM acceleration 312# 313# @enabled: true if KVM acceleration is active 314# 315# @present: true if KVM acceleration is built into this executable 316# 317# Since: 0.14.0 318## 319{ 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } 320 321## 322# @query-kvm: 323# 324# Returns information about KVM acceleration 325# 326# Returns: @KvmInfo 327# 328# Since: 0.14.0 329# 330# Example: 331# 332# -> { "execute": "query-kvm" } 333# <- { "return": { "enabled": true, "present": true } } 334# 335## 336{ 'command': 'query-kvm', 'returns': 'KvmInfo' } 337 338## 339# @UuidInfo: 340# 341# Guest UUID information (Universally Unique Identifier). 342# 343# @UUID: the UUID of the guest 344# 345# Since: 0.14.0 346# 347# Notes: If no UUID was specified for the guest, a null UUID is returned. 348## 349{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } 350 351## 352# @query-uuid: 353# 354# Query the guest UUID information. 355# 356# Returns: The @UuidInfo for the guest 357# 358# Since: 0.14.0 359# 360# Example: 361# 362# -> { "execute": "query-uuid" } 363# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } 364# 365## 366{ 'command': 'query-uuid', 'returns': 'UuidInfo' } 367 368## 369# @EventInfo: 370# 371# Information about a QMP event 372# 373# @name: The event name 374# 375# Since: 1.2.0 376## 377{ 'struct': 'EventInfo', 'data': {'name': 'str'} } 378 379## 380# @query-events: 381# 382# Return a list of supported QMP events by this server 383# 384# Returns: A list of @EventInfo for all supported events 385# 386# Since: 1.2.0 387# 388# Example: 389# 390# -> { "execute": "query-events" } 391# <- { 392# "return": [ 393# { 394# "name":"SHUTDOWN" 395# }, 396# { 397# "name":"RESET" 398# } 399# ] 400# } 401# 402# Note: This example has been shortened as the real response is too long. 403# 404## 405{ 'command': 'query-events', 'returns': ['EventInfo'] } 406 407## 408# @CpuInfoArch: 409# 410# An enumeration of cpu types that enable additional information during 411# @query-cpus. 412# 413# Since: 2.6 414## 415{ 'enum': 'CpuInfoArch', 416 'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 'other' ] } 417 418## 419# @CpuInfo: 420# 421# Information about a virtual CPU 422# 423# @CPU: the index of the virtual CPU 424# 425# @current: this only exists for backwards compatibility and should be ignored 426# 427# @halted: true if the virtual CPU is in the halt state. Halt usually refers 428# to a processor specific low power mode. 429# 430# @qom_path: path to the CPU object in the QOM tree (since 2.4) 431# 432# @thread_id: ID of the underlying host thread 433# 434# @props: properties describing to which node/socket/core/thread 435# virtual CPU belongs to, provided if supported by board (since 2.10) 436# 437# @arch: architecture of the cpu, which determines which additional fields 438# will be listed (since 2.6) 439# 440# Since: 0.14.0 441# 442# Notes: @halted is a transient state that changes frequently. By the time the 443# data is sent to the client, the guest may no longer be halted. 444## 445{ 'union': 'CpuInfo', 446 'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool', 447 'qom_path': 'str', 'thread_id': 'int', 448 '*props': 'CpuInstanceProperties', 'arch': 'CpuInfoArch' }, 449 'discriminator': 'arch', 450 'data': { 'x86': 'CpuInfoX86', 451 'sparc': 'CpuInfoSPARC', 452 'ppc': 'CpuInfoPPC', 453 'mips': 'CpuInfoMIPS', 454 'tricore': 'CpuInfoTricore', 455 'other': 'CpuInfoOther' } } 456 457## 458# @CpuInfoX86: 459# 460# Additional information about a virtual i386 or x86_64 CPU 461# 462# @pc: the 64-bit instruction pointer 463# 464# Since: 2.6 465## 466{ 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } } 467 468## 469# @CpuInfoSPARC: 470# 471# Additional information about a virtual SPARC CPU 472# 473# @pc: the PC component of the instruction pointer 474# 475# @npc: the NPC component of the instruction pointer 476# 477# Since: 2.6 478## 479{ 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } } 480 481## 482# @CpuInfoPPC: 483# 484# Additional information about a virtual PPC CPU 485# 486# @nip: the instruction pointer 487# 488# Since: 2.6 489## 490{ 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } } 491 492## 493# @CpuInfoMIPS: 494# 495# Additional information about a virtual MIPS CPU 496# 497# @PC: the instruction pointer 498# 499# Since: 2.6 500## 501{ 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } } 502 503## 504# @CpuInfoTricore: 505# 506# Additional information about a virtual Tricore CPU 507# 508# @PC: the instruction pointer 509# 510# Since: 2.6 511## 512{ 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } } 513 514## 515# @CpuInfoOther: 516# 517# No additional information is available about the virtual CPU 518# 519# Since: 2.6 520# 521## 522{ 'struct': 'CpuInfoOther', 'data': { } } 523 524## 525# @query-cpus: 526# 527# Returns a list of information about each virtual CPU. 528# 529# Returns: a list of @CpuInfo for each virtual CPU 530# 531# Since: 0.14.0 532# 533# Example: 534# 535# -> { "execute": "query-cpus" } 536# <- { "return": [ 537# { 538# "CPU":0, 539# "current":true, 540# "halted":false, 541# "qom_path":"/machine/unattached/device[0]", 542# "arch":"x86", 543# "pc":3227107138, 544# "thread_id":3134 545# }, 546# { 547# "CPU":1, 548# "current":false, 549# "halted":true, 550# "qom_path":"/machine/unattached/device[2]", 551# "arch":"x86", 552# "pc":7108165, 553# "thread_id":3135 554# } 555# ] 556# } 557# 558## 559{ 'command': 'query-cpus', 'returns': ['CpuInfo'] } 560 561## 562# @IOThreadInfo: 563# 564# Information about an iothread 565# 566# @id: the identifier of the iothread 567# 568# @thread-id: ID of the underlying host thread 569# 570# @poll-max-ns: maximum polling time in ns, 0 means polling is disabled 571# (since 2.9) 572# 573# @poll-grow: how many ns will be added to polling time, 0 means that it's not 574# configured (since 2.9) 575# 576# @poll-shrink: how many ns will be removed from polling time, 0 means that 577# it's not configured (since 2.9) 578# 579# Since: 2.0 580## 581{ 'struct': 'IOThreadInfo', 582 'data': {'id': 'str', 583 'thread-id': 'int', 584 'poll-max-ns': 'int', 585 'poll-grow': 'int', 586 'poll-shrink': 'int' } } 587 588## 589# @query-iothreads: 590# 591# Returns a list of information about each iothread. 592# 593# Note: this list excludes the QEMU main loop thread, which is not declared 594# using the -object iothread command-line option. It is always the main thread 595# of the process. 596# 597# Returns: a list of @IOThreadInfo for each iothread 598# 599# Since: 2.0 600# 601# Example: 602# 603# -> { "execute": "query-iothreads" } 604# <- { "return": [ 605# { 606# "id":"iothread0", 607# "thread-id":3134 608# }, 609# { 610# "id":"iothread1", 611# "thread-id":3135 612# } 613# ] 614# } 615# 616## 617{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'] } 618 619## 620# @BalloonInfo: 621# 622# Information about the guest balloon device. 623# 624# @actual: the number of bytes the balloon currently contains 625# 626# Since: 0.14.0 627# 628## 629{ 'struct': 'BalloonInfo', 'data': {'actual': 'int' } } 630 631## 632# @query-balloon: 633# 634# Return information about the balloon device. 635# 636# Returns: @BalloonInfo on success 637# 638# If the balloon driver is enabled but not functional because the KVM 639# kernel module cannot support it, KvmMissingCap 640# 641# If no balloon device is present, DeviceNotActive 642# 643# Since: 0.14.0 644# 645# Example: 646# 647# -> { "execute": "query-balloon" } 648# <- { "return": { 649# "actual": 1073741824, 650# } 651# } 652# 653## 654{ 'command': 'query-balloon', 'returns': 'BalloonInfo' } 655 656## 657# @BALLOON_CHANGE: 658# 659# Emitted when the guest changes the actual BALLOON level. This value is 660# equivalent to the @actual field return by the 'query-balloon' command 661# 662# @actual: actual level of the guest memory balloon in bytes 663# 664# Note: this event is rate-limited. 665# 666# Since: 1.2 667# 668# Example: 669# 670# <- { "event": "BALLOON_CHANGE", 671# "data": { "actual": 944766976 }, 672# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } 673# 674## 675{ 'event': 'BALLOON_CHANGE', 676 'data': { 'actual': 'int' } } 677 678## 679# @PciMemoryRange: 680# 681# A PCI device memory region 682# 683# @base: the starting address (guest physical) 684# 685# @limit: the ending address (guest physical) 686# 687# Since: 0.14.0 688## 689{ 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} } 690 691## 692# @PciMemoryRegion: 693# 694# Information about a PCI device I/O region. 695# 696# @bar: the index of the Base Address Register for this region 697# 698# @type: 'io' if the region is a PIO region 699# 'memory' if the region is a MMIO region 700# 701# @size: memory size 702# 703# @prefetch: if @type is 'memory', true if the memory is prefetchable 704# 705# @mem_type_64: if @type is 'memory', true if the BAR is 64-bit 706# 707# Since: 0.14.0 708## 709{ 'struct': 'PciMemoryRegion', 710 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int', 711 '*prefetch': 'bool', '*mem_type_64': 'bool' } } 712 713## 714# @PciBusInfo: 715# 716# Information about a bus of a PCI Bridge device 717# 718# @number: primary bus interface number. This should be the number of the 719# bus the device resides on. 720# 721# @secondary: secondary bus interface number. This is the number of the 722# main bus for the bridge 723# 724# @subordinate: This is the highest number bus that resides below the 725# bridge. 726# 727# @io_range: The PIO range for all devices on this bridge 728# 729# @memory_range: The MMIO range for all devices on this bridge 730# 731# @prefetchable_range: The range of prefetchable MMIO for all devices on 732# this bridge 733# 734# Since: 2.4 735## 736{ 'struct': 'PciBusInfo', 737 'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int', 738 'io_range': 'PciMemoryRange', 739 'memory_range': 'PciMemoryRange', 740 'prefetchable_range': 'PciMemoryRange' } } 741 742## 743# @PciBridgeInfo: 744# 745# Information about a PCI Bridge device 746# 747# @bus: information about the bus the device resides on 748# 749# @devices: a list of @PciDeviceInfo for each device on this bridge 750# 751# Since: 0.14.0 752## 753{ 'struct': 'PciBridgeInfo', 754 'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} } 755 756## 757# @PciDeviceClass: 758# 759# Information about the Class of a PCI device 760# 761# @desc: a string description of the device's class 762# 763# @class: the class code of the device 764# 765# Since: 2.4 766## 767{ 'struct': 'PciDeviceClass', 768 'data': {'*desc': 'str', 'class': 'int'} } 769 770## 771# @PciDeviceId: 772# 773# Information about the Id of a PCI device 774# 775# @device: the PCI device id 776# 777# @vendor: the PCI vendor id 778# 779# Since: 2.4 780## 781{ 'struct': 'PciDeviceId', 782 'data': {'device': 'int', 'vendor': 'int'} } 783 784## 785# @PciDeviceInfo: 786# 787# Information about a PCI device 788# 789# @bus: the bus number of the device 790# 791# @slot: the slot the device is located in 792# 793# @function: the function of the slot used by the device 794# 795# @class_info: the class of the device 796# 797# @id: the PCI device id 798# 799# @irq: if an IRQ is assigned to the device, the IRQ number 800# 801# @qdev_id: the device name of the PCI device 802# 803# @pci_bridge: if the device is a PCI bridge, the bridge information 804# 805# @regions: a list of the PCI I/O regions associated with the device 806# 807# Notes: the contents of @class_info.desc are not stable and should only be 808# treated as informational. 809# 810# Since: 0.14.0 811## 812{ 'struct': 'PciDeviceInfo', 813 'data': {'bus': 'int', 'slot': 'int', 'function': 'int', 814 'class_info': 'PciDeviceClass', 'id': 'PciDeviceId', 815 '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo', 816 'regions': ['PciMemoryRegion']} } 817 818## 819# @PciInfo: 820# 821# Information about a PCI bus 822# 823# @bus: the bus index 824# 825# @devices: a list of devices on this bus 826# 827# Since: 0.14.0 828## 829{ 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} } 830 831## 832# @query-pci: 833# 834# Return information about the PCI bus topology of the guest. 835# 836# Returns: a list of @PciInfo for each PCI bus. Each bus is 837# represented by a json-object, which has a key with a json-array of 838# all PCI devices attached to it. Each device is represented by a 839# json-object. 840# 841# Since: 0.14.0 842# 843# Example: 844# 845# -> { "execute": "query-pci" } 846# <- { "return": [ 847# { 848# "bus": 0, 849# "devices": [ 850# { 851# "bus": 0, 852# "qdev_id": "", 853# "slot": 0, 854# "class_info": { 855# "class": 1536, 856# "desc": "Host bridge" 857# }, 858# "id": { 859# "device": 32902, 860# "vendor": 4663 861# }, 862# "function": 0, 863# "regions": [ 864# ] 865# }, 866# { 867# "bus": 0, 868# "qdev_id": "", 869# "slot": 1, 870# "class_info": { 871# "class": 1537, 872# "desc": "ISA bridge" 873# }, 874# "id": { 875# "device": 32902, 876# "vendor": 28672 877# }, 878# "function": 0, 879# "regions": [ 880# ] 881# }, 882# { 883# "bus": 0, 884# "qdev_id": "", 885# "slot": 1, 886# "class_info": { 887# "class": 257, 888# "desc": "IDE controller" 889# }, 890# "id": { 891# "device": 32902, 892# "vendor": 28688 893# }, 894# "function": 1, 895# "regions": [ 896# { 897# "bar": 4, 898# "size": 16, 899# "address": 49152, 900# "type": "io" 901# } 902# ] 903# }, 904# { 905# "bus": 0, 906# "qdev_id": "", 907# "slot": 2, 908# "class_info": { 909# "class": 768, 910# "desc": "VGA controller" 911# }, 912# "id": { 913# "device": 4115, 914# "vendor": 184 915# }, 916# "function": 0, 917# "regions": [ 918# { 919# "prefetch": true, 920# "mem_type_64": false, 921# "bar": 0, 922# "size": 33554432, 923# "address": 4026531840, 924# "type": "memory" 925# }, 926# { 927# "prefetch": false, 928# "mem_type_64": false, 929# "bar": 1, 930# "size": 4096, 931# "address": 4060086272, 932# "type": "memory" 933# }, 934# { 935# "prefetch": false, 936# "mem_type_64": false, 937# "bar": 6, 938# "size": 65536, 939# "address": -1, 940# "type": "memory" 941# } 942# ] 943# }, 944# { 945# "bus": 0, 946# "qdev_id": "", 947# "irq": 11, 948# "slot": 4, 949# "class_info": { 950# "class": 1280, 951# "desc": "RAM controller" 952# }, 953# "id": { 954# "device": 6900, 955# "vendor": 4098 956# }, 957# "function": 0, 958# "regions": [ 959# { 960# "bar": 0, 961# "size": 32, 962# "address": 49280, 963# "type": "io" 964# } 965# ] 966# } 967# ] 968# } 969# ] 970# } 971# 972# Note: This example has been shortened as the real response is too long. 973# 974## 975{ 'command': 'query-pci', 'returns': ['PciInfo'] } 976 977## 978# @quit: 979# 980# This command will cause the QEMU process to exit gracefully. While every 981# attempt is made to send the QMP response before terminating, this is not 982# guaranteed. When using this interface, a premature EOF would not be 983# unexpected. 984# 985# Since: 0.14.0 986# 987# Example: 988# 989# -> { "execute": "quit" } 990# <- { "return": {} } 991## 992{ 'command': 'quit' } 993 994## 995# @stop: 996# 997# Stop all guest VCPU execution. 998# 999# Since: 0.14.0 1000#
1001# Notes: This function will succeed even if the guest is already in the stopped 1002# state. In "inmigrate" state, it will ensure that the guest 1003# remains paused once migration finishes, as if the -S option was 1004# passed on the command line. 1005# 1006# Example: 1007# 1008# -> { "execute": "stop" } 1009# <- { "return": {} } 1010# 1011## 1012{ 'command': 'stop' } 1013 1014## 1015# @system_reset: 1016# 1017# Performs a hard reset of a guest. 1018# 1019# Since: 0.14.0 1020# 1021# Example: 1022# 1023# -> { "execute": "system_reset" } 1024# <- { "return": {} } 1025# 1026## 1027{ 'command': 'system_reset' } 1028 1029## 1030# @system_powerdown: 1031# 1032# Requests that a guest perform a powerdown operation. 1033# 1034# Since: 0.14.0 1035# 1036# Notes: A guest may or may not respond to this command. This command 1037# returning does not indicate that a guest has accepted the request or 1038# that it has shut down. Many guests will respond to this command by 1039# prompting the user in some way. 1040# Example: 1041# 1042# -> { "execute": "system_powerdown" } 1043# <- { "return": {} } 1044# 1045## 1046{ 'command': 'system_powerdown' } 1047 1048## 1049# @cpu: 1050# 1051# This command is a nop that is only provided for the purposes of compatibility. 1052# 1053# Since: 0.14.0 1054# 1055# Notes: Do not use this command. 1056## 1057{ 'command': 'cpu', 'data': {'index': 'int'} } 1058 1059## 1060# @cpu-add: 1061# 1062# Adds CPU with specified ID 1063# 1064# @id: ID of CPU to be created, valid values [0..max_cpus) 1065# 1066# Returns: Nothing on success 1067# 1068# Since: 1.5 1069# 1070# Example: 1071# 1072# -> { "execute": "cpu-add", "arguments": { "id": 2 } } 1073# <- { "return": {} } 1074# 1075## 1076{ 'command': 'cpu-add', 'data': {'id': 'int'} } 1077 1078## 1079# @memsave: 1080# 1081# Save a portion of guest memory to a file. 1082# 1083# @val: the virtual address of the guest to start from 1084# 1085# @size: the size of memory region to save 1086# 1087# @filename: the file to save the memory to as binary data 1088# 1089# @cpu-index: the index of the virtual CPU to use for translating the 1090# virtual address (defaults to CPU 0) 1091# 1092# Returns: Nothing on success 1093# 1094# Since: 0.14.0 1095# 1096# Notes: Errors were not reliably returned until 1.1 1097# 1098# Example: 1099# 1100# -> { "execute": "memsave", 1101# "arguments": { "val": 10, 1102# "size": 100, 1103# "filename": "/tmp/virtual-mem-dump" } } 1104# <- { "return": {} } 1105# 1106## 1107{ 'command': 'memsave', 1108 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} } 1109 1110## 1111# @pmemsave: 1112# 1113# Save a portion of guest physical memory to a file. 1114# 1115# @val: the physical address of the guest to start from 1116# 1117# @size: the size of memory region to save 1118# 1119# @filename: the file to save the memory to as binary data 1120# 1121# Returns: Nothing on success 1122# 1123# Since: 0.14.0 1124# 1125# Notes: Errors were not reliably returned until 1.1 1126# 1127# Example: 1128# 1129# -> { "execute": "pmemsave", 1130# "arguments": { "val": 10, 1131# "size": 100, 1132# "filename": "/tmp/physical-mem-dump" } } 1133# <- { "return": {} } 1134# 1135## 1136{ 'command': 'pmemsave', 1137 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} } 1138 1139## 1140# @cont: 1141# 1142# Resume guest VCPU execution. 1143# 1144# Since: 0.14.0 1145# 1146# Returns: If successful, nothing 1147# 1148# Notes: This command will succeed if the guest is currently running. It 1149# will also succeed if the guest is in the "inmigrate" state; in 1150# this case, the effect of the command is to make sure the guest 1151# starts once migration finishes, removing the effect of the -S 1152# command line option if it was passed. 1153# 1154# Example: 1155# 1156# -> { "execute": "cont" } 1157# <- { "return": {} } 1158# 1159## 1160{ 'command': 'cont' } 1161 1162## 1163# @system_wakeup: 1164# 1165# Wakeup guest from suspend. Does nothing in case the guest isn't suspended. 1166# 1167# Since: 1.1 1168# 1169# Returns: nothing. 1170# 1171# Example: 1172# 1173# -> { "execute": "system_wakeup" } 1174# <- { "return": {} } 1175# 1176## 1177{ 'command': 'system_wakeup' } 1178 1179## 1180# @inject-nmi: 1181# 1182# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64). 1183# The command fails when the guest doesn't support injecting. 1184# 1185# Returns: If successful, nothing 1186# 1187# Since: 0.14.0 1188# 1189# Note: prior to 2.1, this command was only supported for x86 and s390 VMs 1190# 1191# Example: 1192# 1193# -> { "execute": "inject-nmi" } 1194# <- { "return": {} } 1195# 1196## 1197{ 'command': 'inject-nmi' } 1198 1199## 1200# @balloon: 1201# 1202# Request the balloon driver to change its balloon size. 1203# 1204# @value: the target size of the balloon in bytes 1205# 1206# Returns: Nothing on success 1207# If the balloon driver is enabled but not functional because the KVM 1208# kernel module cannot support it, KvmMissingCap 1209# If no balloon device is present, DeviceNotActive 1210# 1211# Notes: This command just issues a request to the guest. When it returns, 1212# the balloon size may not have changed. A guest can change the balloon 1213# size independent of this command. 1214# 1215# Since: 0.14.0 1216# 1217# Example: 1218# 1219# -> { "execute": "balloon", "arguments": { "value": 536870912 } } 1220# <- { "return": {} } 1221# 1222## 1223{ 'command': 'balloon', 'data': {'value': 'int'} } 1224 1225## 1226# @human-monitor-command: 1227# 1228# Execute a command on the human monitor and return the output. 1229# 1230# @command-line: the command to execute in the human monitor 1231# 1232# @cpu-index: The CPU to use for commands that require an implicit CPU 1233# 1234# Returns: the output of the command as a string 1235# 1236# Since: 0.14.0 1237# 1238# Notes: This command only exists as a stop-gap. Its use is highly 1239# discouraged. The semantics of this command are not 1240# guaranteed: this means that command names, arguments and 1241# responses can change or be removed at ANY time. Applications 1242# that rely on long term stability guarantees should NOT 1243# use this command. 1244# 1245# Known limitations: 1246# 1247# * This command is stateless, this means that commands that depend 1248# on state information (such as getfd) might not work 1249# 1250# * Commands that prompt the user for data don't currently work 1251# 1252# Example: 1253# 1254# -> { "execute": "human-monitor-command", 1255# "arguments": { "command-line": "info kvm" } } 1256# <- { "return": "kvm support: enabled\r\n" } 1257# 1258## 1259{ 'command': 'human-monitor-command', 1260 'data': {'command-line': 'str', '*cpu-index': 'int'}, 1261 'returns': 'str' } 1262 1263## 1264# @ObjectPropertyInfo: 1265# 1266# @name: the name of the property 1267# 1268# @type: the type of the property. This will typically come in one of four 1269# forms: 1270# 1271# 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'. 1272# These types are mapped to the appropriate JSON type. 1273# 1274# 2) A child type in the form 'child<subtype>' where subtype is a qdev 1275# device type name. Child properties create the composition tree. 1276# 1277# 3) A link type in the form 'link<subtype>' where subtype is a qdev 1278# device type name. Link properties form the device model graph. 1279# 1280# Since: 1.2 1281## 1282{ 'struct': 'ObjectPropertyInfo', 1283 'data': { 'name': 'str', 'type': 'str' } } 1284 1285## 1286# @qom-list: 1287# 1288# This command will list any properties of a object given a path in the object 1289# model. 1290# 1291# @path: the path within the object model. See @qom-get for a description of 1292# this parameter. 1293# 1294# Returns: a list of @ObjectPropertyInfo that describe the properties of the 1295# object. 1296# 1297# Since: 1.2 1298## 1299{ 'command': 'qom-list', 1300 'data': { 'path': 'str' }, 1301 'returns': [ 'ObjectPropertyInfo' ] } 1302 1303## 1304# @qom-get: 1305# 1306# This command will get a property from a object model path and return the 1307# value. 1308# 1309# @path: The path within the object model. There are two forms of supported 1310# paths--absolute and partial paths. 1311# 1312# Absolute paths are derived from the root object and can follow child<> 1313# or link<> properties. Since they can follow link<> properties, they 1314# can be arbitrarily long. Absolute paths look like absolute filenames 1315# and are prefixed with a leading slash. 1316# 1317# Partial paths look like relative filenames. They do not begin 1318# with a prefix. The matching rules for partial paths are subtle but 1319# designed to make specifying objects easy. At each level of the 1320# composition tree, the partial path is matched as an absolute path. 1321# The first match is not returned. At least two matches are searched 1322# for. A successful result is only returned if only one match is 1323# found. If more than one match is found, a flag is return to 1324# indicate that the match was ambiguous. 1325# 1326# @property: The property name to read 1327# 1328# Returns: The property value. The type depends on the property 1329# type. child<> and link<> properties are returned as #str 1330# pathnames. All integer property types (u8, u16, etc) are 1331# returned as #int. 1332# 1333# Since: 1.2 1334## 1335{ 'command': 'qom-get', 1336 'data': { 'path': 'str', 'property': 'str' }, 1337 'returns': 'any' } 1338 1339## 1340# @qom-set: 1341# 1342# This command will set a property from a object model path. 1343# 1344# @path: see @qom-get for a description of this parameter 1345# 1346# @property: the property name to set 1347# 1348# @value: a value who's type is appropriate for the property type. See @qom-get 1349# for a description of type mapping. 1350# 1351# Since: 1.2 1352## 1353{ 'command': 'qom-set', 1354 'data': { 'path': 'str', 'property': 'str', 'value': 'any' } } 1355 1356## 1357# @change: 1358# 1359# This command is multiple commands multiplexed together. 1360# 1361# @device: This is normally the name of a block device but it may also be 'vnc'. 1362# when it's 'vnc', then sub command depends on @target 1363# 1364# @target: If @device is a block device, then this is the new filename. 1365# If @device is 'vnc', then if the value 'password' selects the vnc 1366# change password command. Otherwise, this specifies a new server URI 1367# address to listen to for VNC connections. 1368# 1369# @arg: If @device is a block device, then this is an optional format to open 1370# the device with. 1371# If @device is 'vnc' and @target is 'password', this is the new VNC 1372# password to set. See change-vnc-password for additional notes. 1373# 1374# Returns: Nothing on success. 1375# If @device is not a valid block device, DeviceNotFound 1376# 1377# Notes: This interface is deprecated, and it is strongly recommended that you 1378# avoid using it. For changing block devices, use 1379# blockdev-change-medium; for changing VNC parameters, use 1380# change-vnc-password. 1381# 1382# Since: 0.14.0 1383# 1384# Example: 1385# 1386# 1. Change a removable medium 1387# 1388# -> { "execute": "change", 1389# "arguments": { "device": "ide1-cd0", 1390# "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } } 1391# <- { "return": {} } 1392# 1393# 2. Change VNC password 1394# 1395# -> { "execute": "change", 1396# "arguments": { "device": "vnc", "target": "password", 1397# "arg": "foobar1" } } 1398# <- { "return": {} } 1399# 1400## 1401{ 'command': 'change', 1402 'data': {'device': 'str', 'target': 'str', '*arg': 'str'} } 1403 1404## 1405# @ObjectTypeInfo: 1406# 1407# This structure describes a search result from @qom-list-types 1408# 1409# @name: the type name found in the search 1410# 1411# @abstract: the type is abstract and can't be directly instantiated. 1412# Omitted if false. (since 2.10) 1413# 1414# @parent: Name of parent type, if any (since 2.10) 1415# 1416# Since: 1.1 1417## 1418{ 'struct': 'ObjectTypeInfo', 1419 'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } } 1420 1421## 1422# @qom-list-types: 1423# 1424# This command will return a list of types given search parameters 1425# 1426# @implements: if specified, only return types that implement this type name 1427# 1428# @abstract: if true, include abstract types in the results 1429# 1430# Returns: a list of @ObjectTypeInfo or an empty list if no results are found 1431# 1432# Since: 1.1 1433## 1434{ 'command': 'qom-list-types', 1435 'data': { '*implements': 'str', '*abstract': 'bool' }, 1436 'returns': [ 'ObjectTypeInfo' ] } 1437 1438## 1439# @DevicePropertyInfo: 1440# 1441# Information about device properties. 1442# 1443# @name: the name of the property 1444# @type: the typename of the property 1445# @description: if specified, the description of the property. 1446# (since 2.2) 1447# 1448# Since: 1.2 1449## 1450{ 'struct': 'DevicePropertyInfo', 1451 'data': { 'name': 'str', 'type': 'str', '*description': 'str' } } 1452 1453## 1454# @device-list-properties: 1455# 1456# List properties associated with a device. 1457# 1458# @typename: the type name of a device 1459# 1460# Returns: a list of DevicePropertyInfo describing a devices properties 1461# 1462# Since: 1.2 1463## 1464{ 'command': 'device-list-properties', 1465 'data': { 'typename': 'str'}, 1466 'returns': [ 'DevicePropertyInfo' ] } 1467 1468## 1469# @xen-set-global-dirty-log: 1470# 1471# Enable or disable the global dirty log mode. 1472# 1473# @enable: true to enable, false to disable. 1474# 1475# Returns: nothing 1476# 1477# Since: 1.3 1478# 1479# Example: 1480# 1481# -> { "execute": "xen-set-global-dirty-log", 1482# "arguments": { "enable": true } } 1483# <- { "return": {} } 1484# 1485## 1486{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } 1487 1488## 1489# @device_add: 1490# 1491# @driver: the name of the new device's driver 1492# 1493# @bus: the device's parent bus (device tree path) 1494# 1495# @id: the device's ID, must be unique 1496# 1497# Additional arguments depend on the type. 1498# 1499# Add a device. 1500# 1501# Notes: 1502# 1. For detailed information about this command, please refer to the 1503# 'docs/qdev-device-use.txt' file. 1504# 1505# 2. It's possible to list device properties by running QEMU with the 1506# "-device DEVICE,help" command-line argument, where DEVICE is the 1507# device's name 1508# 1509# Example: 1510# 1511# -> { "execute": "device_add", 1512# "arguments": { "driver": "e1000", "id": "net1", 1513# "bus": "pci.0", 1514# "mac": "52:54:00:12:34:56" } } 1515# <- { "return": {} } 1516# 1517# TODO: This command effectively bypasses QAPI completely due to its 1518# "additional arguments" business. It shouldn't have been added to 1519# the schema in this form. It should be qapified properly, or 1520# replaced by a properly qapified command. 1521# 1522# Since: 0.13 1523## 1524{ 'command': 'device_add', 1525 'data': {'driver': 'str', '*bus': 'str', '*id': 'str'}, 1526 'gen': false } # so we can get the additional arguments 1527 1528## 1529# @device_del: 1530# 1531# Remove a device from a guest 1532# 1533# @id: the device's ID or QOM path 1534# 1535# Returns: Nothing on success 1536# If @id is not a valid device, DeviceNotFound 1537# 1538# Notes: When this command completes, the device may not be removed from the 1539# guest. Hot removal is an operation that requires guest cooperation. 1540# This command merely requests that the guest begin the hot removal 1541# process. Completion of the device removal process is signaled with a 1542# DEVICE_DELETED event. Guest reset will automatically complete removal 1543# for all devices. 1544# 1545# Since: 0.14.0 1546# 1547# Example: 1548# 1549# -> { "execute": "device_del", 1550# "arguments": { "id": "net1" } } 1551# <- { "return": {} } 1552# 1553# -> { "execute": "device_del", 1554# "arguments": { "id": "/machine/peripheral-anon/device[0]" } } 1555# <- { "return": {} } 1556# 1557## 1558{ 'command': 'device_del', 'data': {'id': 'str'} } 1559 1560## 1561# @DEVICE_DELETED: 1562# 1563# Emitted whenever the device removal completion is acknowledged by the guest. 1564# At this point, it's safe to reuse the specified device ID. Device removal can 1565# be initiated by the guest or by HMP/QMP commands. 1566# 1567# @device: device name 1568# 1569# @path: device path 1570# 1571# Since: 1.5 1572# 1573# Example: 1574# 1575# <- { "event": "DEVICE_DELETED", 1576# "data": { "device": "virtio-net-pci-0", 1577# "path": "/machine/peripheral/virtio-net-pci-0" }, 1578# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 1579# 1580## 1581{ 'event': 'DEVICE_DELETED', 1582 'data': { '*device': 'str', 'path': 'str' } } 1583 1584## 1585# @DumpGuestMemoryFormat: 1586# 1587# An enumeration of guest-memory-dump's format. 1588# 1589# @elf: elf format 1590# 1591# @kdump-zlib: kdump-compressed format with zlib-compressed 1592# 1593# @kdump-lzo: kdump-compressed format with lzo-compressed 1594# 1595# @kdump-snappy: kdump-compressed format with snappy-compressed 1596# 1597# Since: 2.0 1598## 1599{ 'enum': 'DumpGuestMemoryFormat', 1600 'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy' ] } 1601 1602## 1603# @dump-guest-memory: 1604# 1605# Dump guest's memory to vmcore. It is a synchronous operation that can take 1606# very long depending on the amount of guest memory. 1607# 1608# @paging: if true, do paging to get guest's memory mapping. This allows 1609# using gdb to process the core file. 1610# 1611# IMPORTANT: this option can make QEMU allocate several gigabytes 1612# of RAM. This can happen for a large guest, or a 1613# malicious guest pretending to be large. 1614# 1615# Also, paging=true has the following limitations: 1616# 1617# 1. The guest may be in a catastrophic state or can have corrupted 1618# memory, which cannot be trusted 1619# 2. The guest can be in real-mode even if paging is enabled. For 1620# example, the guest uses ACPI to sleep, and ACPI sleep state 1621# goes in real-mode 1622# 3. Currently only supported on i386 and x86_64. 1623# 1624# @protocol: the filename or file descriptor of the vmcore. The supported 1625# protocols are: 1626# 1627# 1. file: the protocol starts with "file:", and the following 1628# string is the file's path. 1629# 2. fd: the protocol starts with "fd:", and the following string 1630# is the fd's name. 1631# 1632# @detach: if true, QMP will return immediately rather than 1633# waiting for the dump to finish. The user can track progress 1634# using "query-dump". (since 2.6). 1635# 1636# @begin: if specified, the starting physical address. 1637# 1638# @length: if specified, the memory size, in bytes. If you don't 1639# want to dump all guest's memory, please specify the start @begin 1640# and @length 1641# 1642# @format: if specified, the format of guest memory dump. But non-elf 1643# format is conflict with paging and filter, ie. @paging, @begin and 1644# @length is not allowed to be specified with non-elf @format at the 1645# same time (since 2.0) 1646# 1647# Note: All boolean arguments default to false 1648# 1649# Returns: nothing on success 1650# 1651# Since: 1.2 1652# 1653# Example: 1654# 1655# -> { "execute": "dump-guest-memory", 1656# "arguments": { "protocol": "fd:dump" } } 1657# <- { "return": {} } 1658# 1659## 1660{ 'command': 'dump-guest-memory', 1661 'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool', 1662 '*begin': 'int', '*length': 'int', 1663 '*format': 'DumpGuestMemoryFormat'} } 1664 1665## 1666# @DumpStatus: 1667# 1668# Describe the status of a long-running background guest memory dump. 1669# 1670# @none: no dump-guest-memory has started yet. 1671# 1672# @active: there is one dump running in background. 1673# 1674# @completed: the last dump has finished successfully. 1675# 1676# @failed: the last dump has failed. 1677# 1678# Since: 2.6 1679## 1680{ 'enum': 'DumpStatus', 1681 'data': [ 'none', 'active', 'completed', 'failed' ] } 1682 1683## 1684# @DumpQueryResult: 1685# 1686# The result format for 'query-dump'. 1687# 1688# @status: enum of @DumpStatus, which shows current dump status 1689# 1690# @completed: bytes written in latest dump (uncompressed) 1691# 1692# @total: total bytes to be written in latest dump (uncompressed) 1693# 1694# Since: 2.6 1695## 1696{ 'struct': 'DumpQueryResult', 1697 'data': { 'status': 'DumpStatus', 1698 'completed': 'int', 1699 'total': 'int' } } 1700 1701## 1702# @query-dump: 1703# 1704# Query latest dump status. 1705# 1706# Returns: A @DumpStatus object showing the dump status. 1707# 1708# Since: 2.6 1709# 1710# Example: 1711# 1712# -> { "execute": "query-dump" } 1713# <- { "return": { "status": "active", "completed": 1024000, 1714# "total": 2048000 } } 1715# 1716## 1717{ 'command': 'query-dump', 'returns': 'DumpQueryResult' } 1718 1719## 1720# @DUMP_COMPLETED: 1721# 1722# Emitted when background dump has completed 1723# 1724# @result: DumpQueryResult type described in qapi-schema.json. 1725# 1726# @error: human-readable error string that provides 1727# hint on why dump failed. Only presents on failure. The 1728# user should not try to interpret the error string. 1729# 1730# Since: 2.6 1731# 1732# Example: 1733# 1734# { "event": "DUMP_COMPLETED", 1735# "data": {"result": {"total": 1090650112, "status": "completed", 1736# "completed": 1090650112} } } 1737# 1738## 1739{ 'event': 'DUMP_COMPLETED' , 1740 'data': { 'result': 'DumpQueryResult', '*error': 'str' } } 1741 1742## 1743# @DumpGuestMemoryCapability: 1744# 1745# A list of the available formats for dump-guest-memory 1746# 1747# Since: 2.0 1748## 1749{ 'struct': 'DumpGuestMemoryCapability', 1750 'data': { 1751 'formats': ['DumpGuestMemoryFormat'] } } 1752 1753## 1754# @query-dump-guest-memory-capability: 1755# 1756# Returns the available formats for dump-guest-memory 1757# 1758# Returns: A @DumpGuestMemoryCapability object listing available formats for 1759# dump-guest-memory 1760# 1761# Since: 2.0 1762# 1763# Example: 1764# 1765# -> { "execute": "query-dump-guest-memory-capability" } 1766# <- { "return": { "formats": 1767# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } 1768# 1769## 1770{ 'command': 'query-dump-guest-memory-capability', 1771 'returns': 'DumpGuestMemoryCapability' } 1772 1773## 1774# @dump-skeys: 1775# 1776# Dump guest's storage keys 1777# 1778# @filename: the path to the file to dump to 1779# 1780# This command is only supported on s390 architecture. 1781# 1782# Since: 2.5 1783# 1784# Example: 1785# 1786# -> { "execute": "dump-skeys", 1787# "arguments": { "filename": "/tmp/skeys" } } 1788# <- { "return": {} } 1789# 1790## 1791{ 'command': 'dump-skeys', 1792 'data': { 'filename': 'str' } } 1793 1794## 1795# @object-add: 1796# 1797# Create a QOM object. 1798# 1799# @qom-type: the class name for the object to be created 1800# 1801# @id: the name of the new object 1802# 1803# @props: a dictionary of properties to be passed to the backend 1804# 1805# Returns: Nothing on success 1806# Error if @qom-type is not a valid class name 1807# 1808# Since: 2.0 1809# 1810# Example: 1811# 1812# -> { "execute": "object-add", 1813# "arguments": { "qom-type": "rng-random", "id": "rng1", 1814# "props": { "filename": "/dev/hwrng" } } } 1815# <- { "return": {} } 1816# 1817## 1818{ 'command': 'object-add', 1819 'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'} } 1820 1821## 1822# @object-del: 1823# 1824# Remove a QOM object. 1825# 1826# @id: the name of the QOM object to remove 1827# 1828# Returns: Nothing on success 1829# Error if @id is not a valid id for a QOM object 1830# 1831# Since: 2.0 1832# 1833# Example: 1834# 1835# -> { "execute": "object-del", "arguments": { "id": "rng1" } } 1836# <- { "return": {} } 1837# 1838## 1839{ 'command': 'object-del', 'data': {'id': 'str'} } 1840 1841## 1842# @getfd: 1843# 1844# Receive a file descriptor via SCM rights and assign it a name 1845# 1846# @fdname: file descriptor name 1847# 1848# Returns: Nothing on success 1849# 1850# Since: 0.14.0 1851# 1852# Notes: If @fdname already exists, the file descriptor assigned to 1853# it will be closed and replaced by the received file 1854# descriptor. 1855# 1856# The 'closefd' command can be used to explicitly close the 1857# file descriptor when it is no longer needed. 1858# 1859# Example: 1860# 1861# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } 1862# <- { "return": {} } 1863# 1864## 1865{ 'command': 'getfd', 'data': {'fdname': 'str'} } 1866 1867## 1868# @closefd: 1869# 1870# Close a file descriptor previously passed via SCM rights 1871# 1872# @fdname: file descriptor name 1873# 1874# Returns: Nothing on success 1875# 1876# Since: 0.14.0 1877# 1878# Example: 1879# 1880# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } 1881# <- { "return": {} } 1882# 1883## 1884{ 'command': 'closefd', 'data': {'fdname': 'str'} } 1885 1886## 1887# @MachineInfo: 1888# 1889# Information describing a machine. 1890# 1891# @name: the name of the machine 1892# 1893# @alias: an alias for the machine name 1894# 1895# @is-default: whether the machine is default 1896# 1897# @cpu-max: maximum number of CPUs supported by the machine type 1898# (since 1.5.0) 1899# 1900# @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0) 1901# 1902# Since: 1.2.0 1903## 1904{ 'struct': 'MachineInfo', 1905 'data': { 'name': 'str', '*alias': 'str', 1906 '*is-default': 'bool', 'cpu-max': 'int', 1907 'hotpluggable-cpus': 'bool'} } 1908 1909## 1910# @query-machines: 1911# 1912# Return a list of supported machines 1913# 1914# Returns: a list of MachineInfo 1915# 1916# Since: 1.2.0 1917## 1918{ 'command': 'query-machines', 'returns': ['MachineInfo'] } 1919 1920## 1921# @CpuDefinitionInfo: 1922# 1923# Virtual CPU definition. 1924# 1925# @name: the name of the CPU definition 1926# 1927# @migration-safe: whether a CPU definition can be safely used for 1928# migration in combination with a QEMU compatibility machine 1929# when migrating between different QMU versions and between 1930# hosts with different sets of (hardware or software) 1931# capabilities. If not provided, information is not available 1932# and callers should not assume the CPU definition to be 1933# migration-safe. (since 2.8) 1934# 1935# @static: whether a CPU definition is static and will not change depending on 1936# QEMU version, machine type, machine options and accelerator options. 1937# A static model is always migration-safe. (since 2.8) 1938# 1939# @unavailable-features: List of properties that prevent 1940# the CPU model from running in the current 1941# host. (since 2.8) 1942# @typename: Type name that can be used as argument to @device-list-properties, 1943# to introspect properties configurable using -cpu or -global. 1944# (since 2.9) 1945# 1946# @unavailable-features is a list of QOM property names that 1947# represent CPU model attributes that prevent the CPU from running. 1948# If the QOM property is read-only, that means there's no known 1949# way to make the CPU model run in the current host. Implementations 1950# that choose not to provide specific information return the 1951# property name "type". 1952# If the property is read-write, it means that it MAY be possible 1953# to run the CPU model in the current host if that property is 1954# changed. Management software can use it as hints to suggest or 1955# choose an alternative for the user, or just to generate meaningful 1956# error messages explaining why the CPU model can't be used. 1957# If @unavailable-features is an empty list, the CPU model is 1958# runnable using the current host and machine-type. 1959# If @unavailable-features is not present, runnability 1960# information for the CPU is not available. 1961# 1962# Since: 1.2.0 1963## 1964{ 'struct': 'CpuDefinitionInfo', 1965 'data': { 'name': 'str', '*migration-safe': 'bool', 'static': 'bool', 1966 '*unavailable-features': [ 'str' ], 'typename': 'str' } } 1967 1968## 1969# @MemoryInfo: 1970# 1971# Actual memory information in bytes. 1972# 1973# @base-memory: size of "base" memory specified with command line 1974# option -m. 1975# 1976# @plugged-memory: size of memory that can be hot-unplugged. This field 1977# is omitted if target doesn't support memory hotplug 1978# (i.e. CONFIG_MEM_HOTPLUG not defined on build time). 1979# 1980# Since: 2.11.0 1981## 1982{ 'struct': 'MemoryInfo', 1983 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } } 1984 1985## 1986# @query-memory-size-summary: 1987# 1988# Return the amount of initially allocated and present hotpluggable (if 1989# enabled) memory in bytes. 1990# 1991# Example: 1992# 1993# -> { "execute": "query-memory-size-summary" } 1994# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } 1995# 1996# Since: 2.11.0 1997## 1998{ 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' } 1999 2000##
2001# @query-cpu-definitions: 2002# 2003# Return a list of supported virtual CPU definitions 2004# 2005# Returns: a list of CpuDefInfo 2006# 2007# Since: 1.2.0 2008## 2009{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] } 2010 2011## 2012# @CpuModelInfo: 2013# 2014# Virtual CPU model. 2015# 2016# A CPU model consists of the name of a CPU definition, to which 2017# delta changes are applied (e.g. features added/removed). Most magic values 2018# that an architecture might require should be hidden behind the name. 2019# However, if required, architectures can expose relevant properties. 2020# 2021# @name: the name of the CPU definition the model is based on 2022# @props: a dictionary of QOM properties to be applied 2023# 2024# Since: 2.8.0 2025## 2026{ 'struct': 'CpuModelInfo', 2027 'data': { 'name': 'str', 2028 '*props': 'any' } } 2029 2030## 2031# @CpuModelExpansionType: 2032# 2033# An enumeration of CPU model expansion types. 2034# 2035# @static: Expand to a static CPU model, a combination of a static base 2036# model name and property delta changes. As the static base model will 2037# never change, the expanded CPU model will be the same, independant of 2038# independent of QEMU version, machine type, machine options, and 2039# accelerator options. Therefore, the resulting model can be used by 2040# tooling without having to specify a compatibility machine - e.g. when 2041# displaying the "host" model. static CPU models are migration-safe. 2042# 2043# @full: Expand all properties. The produced model is not guaranteed to be 2044# migration-safe, but allows tooling to get an insight and work with 2045# model details. 2046# 2047# Note: When a non-migration-safe CPU model is expanded in static mode, some 2048# features enabled by the CPU model may be omitted, because they can't be 2049# implemented by a static CPU model definition (e.g. cache info passthrough and 2050# PMU passthrough in x86). If you need an accurate representation of the 2051# features enabled by a non-migration-safe CPU model, use @full. If you need a 2052# static representation that will keep ABI compatibility even when changing QEMU 2053# version or machine-type, use @static (but keep in mind that some features may 2054# be omitted). 2055# 2056# Since: 2.8.0 2057## 2058{ 'enum': 'CpuModelExpansionType', 2059 'data': [ 'static', 'full' ] } 2060 2061 2062## 2063# @CpuModelExpansionInfo: 2064# 2065# The result of a cpu model expansion. 2066# 2067# @model: the expanded CpuModelInfo. 2068# 2069# Since: 2.8.0 2070## 2071{ 'struct': 'CpuModelExpansionInfo', 2072 'data': { 'model': 'CpuModelInfo' } } 2073 2074 2075## 2076# @query-cpu-model-expansion: 2077# 2078# Expands a given CPU model (or a combination of CPU model + additional options) 2079# to different granularities, allowing tooling to get an understanding what a 2080# specific CPU model looks like in QEMU under a certain configuration. 2081# 2082# This interface can be used to query the "host" CPU model. 2083# 2084# The data returned by this command may be affected by: 2085# 2086# * QEMU version: CPU models may look different depending on the QEMU version. 2087# (Except for CPU models reported as "static" in query-cpu-definitions.) 2088# * machine-type: CPU model may look different depending on the machine-type. 2089# (Except for CPU models reported as "static" in query-cpu-definitions.) 2090# * machine options (including accelerator): in some architectures, CPU models 2091# may look different depending on machine and accelerator options. (Except for 2092# CPU models reported as "static" in query-cpu-definitions.) 2093# * "-cpu" arguments and global properties: arguments to the -cpu option and 2094# global properties may affect expansion of CPU models. Using 2095# query-cpu-model-expansion while using these is not advised. 2096# 2097# Some architectures may not support all expansion types. s390x supports 2098# "full" and "static". 2099# 2100# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is 2101# not supported, if the model cannot be expanded, if the model contains 2102# an unknown CPU definition name, unknown properties or properties 2103# with a wrong type. Also returns an error if an expansion type is 2104# not supported. 2105# 2106# Since: 2.8.0 2107## 2108{ 'command': 'query-cpu-model-expansion', 2109 'data': { 'type': 'CpuModelExpansionType', 2110 'model': 'CpuModelInfo' }, 2111 'returns': 'CpuModelExpansionInfo' } 2112 2113## 2114# @CpuModelCompareResult: 2115# 2116# An enumeration of CPU model comparation results. The result is usually 2117# calculated using e.g. CPU features or CPU generations. 2118# 2119# @incompatible: If model A is incompatible to model B, model A is not 2120# guaranteed to run where model B runs and the other way around. 2121# 2122# @identical: If model A is identical to model B, model A is guaranteed to run 2123# where model B runs and the other way around. 2124# 2125# @superset: If model A is a superset of model B, model B is guaranteed to run 2126# where model A runs. There are no guarantees about the other way. 2127# 2128# @subset: If model A is a subset of model B, model A is guaranteed to run 2129# where model B runs. There are no guarantees about the other way. 2130# 2131# Since: 2.8.0 2132## 2133{ 'enum': 'CpuModelCompareResult', 2134 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } 2135 2136## 2137# @CpuModelCompareInfo: 2138# 2139# The result of a CPU model comparison. 2140# 2141# @result: The result of the compare operation. 2142# @responsible-properties: List of properties that led to the comparison result 2143# not being identical. 2144# 2145# @responsible-properties is a list of QOM property names that led to 2146# both CPUs not being detected as identical. For identical models, this 2147# list is empty. 2148# If a QOM property is read-only, that means there's no known way to make the 2149# CPU models identical. If the special property name "type" is included, the 2150# models are by definition not identical and cannot be made identical. 2151# 2152# Since: 2.8.0 2153## 2154{ 'struct': 'CpuModelCompareInfo', 2155 'data': {'result': 'CpuModelCompareResult', 2156 'responsible-properties': ['str'] 2157 } 2158} 2159 2160## 2161# @query-cpu-model-comparison: 2162# 2163# Compares two CPU models, returning how they compare in a specific 2164# configuration. The results indicates how both models compare regarding 2165# runnability. This result can be used by tooling to make decisions if a 2166# certain CPU model will run in a certain configuration or if a compatible 2167# CPU model has to be created by baselining. 2168# 2169# Usually, a CPU model is compared against the maximum possible CPU model 2170# of a certain configuration (e.g. the "host" model for KVM). If that CPU 2171# model is identical or a subset, it will run in that configuration. 2172# 2173# The result returned by this command may be affected by: 2174# 2175# * QEMU version: CPU models may look different depending on the QEMU version. 2176# (Except for CPU models reported as "static" in query-cpu-definitions.) 2177# * machine-type: CPU model may look different depending on the machine-type. 2178# (Except for CPU models reported as "static" in query-cpu-definitions.) 2179# * machine options (including accelerator): in some architectures, CPU models 2180# may look different depending on machine and accelerator options. (Except for 2181# CPU models reported as "static" in query-cpu-definitions.) 2182# * "-cpu" arguments and global properties: arguments to the -cpu option and 2183# global properties may affect expansion of CPU models. Using 2184# query-cpu-model-expansion while using these is not advised. 2185# 2186# Some architectures may not support comparing CPU models. s390x supports 2187# comparing CPU models. 2188# 2189# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is 2190# not supported, if a model cannot be used, if a model contains 2191# an unknown cpu definition name, unknown properties or properties 2192# with wrong types. 2193# 2194# Since: 2.8.0 2195## 2196{ 'command': 'query-cpu-model-comparison', 2197 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 2198 'returns': 'CpuModelCompareInfo' } 2199 2200## 2201# @CpuModelBaselineInfo: 2202# 2203# The result of a CPU model baseline. 2204# 2205# @model: the baselined CpuModelInfo. 2206# 2207# Since: 2.8.0 2208## 2209{ 'struct': 'CpuModelBaselineInfo', 2210 'data': { 'model': 'CpuModelInfo' } } 2211 2212## 2213# @query-cpu-model-baseline: 2214# 2215# Baseline two CPU models, creating a compatible third model. The created 2216# model will always be a static, migration-safe CPU model (see "static" 2217# CPU model expansion for details). 2218# 2219# This interface can be used by tooling to create a compatible CPU model out 2220# two CPU models. The created CPU model will be identical to or a subset of 2221# both CPU models when comparing them. Therefore, the created CPU model is 2222# guaranteed to run where the given CPU models run. 2223# 2224# The result returned by this command may be affected by: 2225# 2226# * QEMU version: CPU models may look different depending on the QEMU version. 2227# (Except for CPU models reported as "static" in query-cpu-definitions.) 2228# * machine-type: CPU model may look different depending on the machine-type. 2229# (Except for CPU models reported as "static" in query-cpu-definitions.) 2230# * machine options (including accelerator): in some architectures, CPU models 2231# may look different depending on machine and accelerator options. (Except for 2232# CPU models reported as "static" in query-cpu-definitions.) 2233# * "-cpu" arguments and global properties: arguments to the -cpu option and 2234# global properties may affect expansion of CPU models. Using 2235# query-cpu-model-expansion while using these is not advised. 2236# 2237# Some architectures may not support baselining CPU models. s390x supports 2238# baselining CPU models. 2239# 2240# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is 2241# not supported, if a model cannot be used, if a model contains 2242# an unknown cpu definition name, unknown properties or properties 2243# with wrong types. 2244# 2245# Since: 2.8.0 2246## 2247{ 'command': 'query-cpu-model-baseline', 2248 'data': { 'modela': 'CpuModelInfo', 2249 'modelb': 'CpuModelInfo' }, 2250 'returns': 'CpuModelBaselineInfo' } 2251 2252## 2253# @AddfdInfo: 2254# 2255# Information about a file descriptor that was added to an fd set. 2256# 2257# @fdset-id: The ID of the fd set that @fd was added to. 2258# 2259# @fd: The file descriptor that was received via SCM rights and 2260# added to the fd set. 2261# 2262# Since: 1.2.0 2263## 2264{ 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} } 2265 2266## 2267# @add-fd: 2268# 2269# Add a file descriptor, that was passed via SCM rights, to an fd set. 2270# 2271# @fdset-id: The ID of the fd set to add the file descriptor to. 2272# 2273# @opaque: A free-form string that can be used to describe the fd. 2274# 2275# Returns: @AddfdInfo on success 2276# 2277# If file descriptor was not received, FdNotSupplied 2278# 2279# If @fdset-id is a negative value, InvalidParameterValue 2280# 2281# Notes: The list of fd sets is shared by all monitor connections. 2282# 2283# If @fdset-id is not specified, a new fd set will be created. 2284# 2285# Since: 1.2.0 2286# 2287# Example: 2288# 2289# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } 2290# <- { "return": { "fdset-id": 1, "fd": 3 } } 2291# 2292## 2293{ 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'}, 2294 'returns': 'AddfdInfo' } 2295 2296## 2297# @remove-fd: 2298# 2299# Remove a file descriptor from an fd set. 2300# 2301# @fdset-id: The ID of the fd set that the file descriptor belongs to. 2302# 2303# @fd: The file descriptor that is to be removed. 2304# 2305# Returns: Nothing on success 2306# If @fdset-id or @fd is not found, FdNotFound 2307# 2308# Since: 1.2.0 2309# 2310# Notes: The list of fd sets is shared by all monitor connections. 2311# 2312# If @fd is not specified, all file descriptors in @fdset-id 2313# will be removed. 2314# 2315# Example: 2316# 2317# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } 2318# <- { "return": {} } 2319# 2320## 2321{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} } 2322 2323## 2324# @FdsetFdInfo: 2325# 2326# Information about a file descriptor that belongs to an fd set. 2327# 2328# @fd: The file descriptor value. 2329# 2330# @opaque: A free-form string that can be used to describe the fd. 2331# 2332# Since: 1.2.0 2333## 2334{ 'struct': 'FdsetFdInfo', 2335 'data': {'fd': 'int', '*opaque': 'str'} } 2336 2337## 2338# @FdsetInfo: 2339# 2340# Information about an fd set. 2341# 2342# @fdset-id: The ID of the fd set. 2343# 2344# @fds: A list of file descriptors that belong to this fd set. 2345# 2346# Since: 1.2.0 2347## 2348{ 'struct': 'FdsetInfo', 2349 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} } 2350 2351## 2352# @query-fdsets: 2353# 2354# Return information describing all fd sets. 2355# 2356# Returns: A list of @FdsetInfo 2357# 2358# Since: 1.2.0 2359# 2360# Note: The list of fd sets is shared by all monitor connections. 2361# 2362# Example: 2363# 2364# -> { "execute": "query-fdsets" } 2365# <- { "return": [ 2366# { 2367# "fds": [ 2368# { 2369# "fd": 30, 2370# "opaque": "rdonly:/path/to/file" 2371# }, 2372# { 2373# "fd": 24, 2374# "opaque": "rdwr:/path/to/file" 2375# } 2376# ], 2377# "fdset-id": 1 2378# }, 2379# { 2380# "fds": [ 2381# { 2382# "fd": 28 2383# }, 2384# { 2385# "fd": 29 2386# } 2387# ], 2388# "fdset-id": 0 2389# } 2390# ] 2391# } 2392# 2393## 2394{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] } 2395 2396## 2397# @TargetInfo: 2398# 2399# Information describing the QEMU target. 2400# 2401# @arch: the target architecture (eg "x86_64", "i386", etc) 2402# 2403# Since: 1.2.0 2404## 2405{ 'struct': 'TargetInfo', 2406 'data': { 'arch': 'str' } } 2407 2408## 2409# @query-target: 2410# 2411# Return information about the target for this QEMU 2412# 2413# Returns: TargetInfo 2414# 2415# Since: 1.2.0 2416## 2417{ 'command': 'query-target', 'returns': 'TargetInfo' } 2418 2419## 2420# @AcpiTableOptions: 2421# 2422# Specify an ACPI table on the command line to load. 2423# 2424# At most one of @file and @data can be specified. The list of files specified 2425# by any one of them is loaded and concatenated in order. If both are omitted, 2426# @data is implied. 2427# 2428# Other fields / optargs can be used to override fields of the generic ACPI 2429# table header; refer to the ACPI specification 5.0, section 5.2.6 System 2430# Description Table Header. If a header field is not overridden, then the 2431# corresponding value from the concatenated blob is used (in case of @file), or 2432# it is filled in with a hard-coded value (in case of @data). 2433# 2434# String fields are copied into the matching ACPI member from lowest address 2435# upwards, and silently truncated / NUL-padded to length. 2436# 2437# @sig: table signature / identifier (4 bytes) 2438# 2439# @rev: table revision number (dependent on signature, 1 byte) 2440# 2441# @oem_id: OEM identifier (6 bytes) 2442# 2443# @oem_table_id: OEM table identifier (8 bytes) 2444# 2445# @oem_rev: OEM-supplied revision number (4 bytes) 2446# 2447# @asl_compiler_id: identifier of the utility that created the table 2448# (4 bytes) 2449# 2450# @asl_compiler_rev: revision number of the utility that created the 2451# table (4 bytes) 2452# 2453# @file: colon (:) separated list of pathnames to load and 2454# concatenate as table data. The resultant binary blob is expected to 2455# have an ACPI table header. At least one file is required. This field 2456# excludes @data. 2457# 2458# @data: colon (:) separated list of pathnames to load and 2459# concatenate as table data. The resultant binary blob must not have an 2460# ACPI table header. At least one file is required. This field excludes 2461# @file. 2462# 2463# Since: 1.5 2464## 2465{ 'struct': 'AcpiTableOptions', 2466 'data': { 2467 '*sig': 'str', 2468 '*rev': 'uint8', 2469 '*oem_id': 'str', 2470 '*oem_table_id': 'str', 2471 '*oem_rev': 'uint32', 2472 '*asl_compiler_id': 'str', 2473 '*asl_compiler_rev': 'uint32', 2474 '*file': 'str', 2475 '*data': 'str' }} 2476 2477## 2478# @CommandLineParameterType: 2479# 2480# Possible types for an option parameter. 2481# 2482# @string: accepts a character string 2483# 2484# @boolean: accepts "on" or "off" 2485# 2486# @number: accepts a number 2487# 2488# @size: accepts a number followed by an optional suffix (K)ilo, 2489# (M)ega, (G)iga, (T)era 2490# 2491# Since: 1.5 2492## 2493{ 'enum': 'CommandLineParameterType', 2494 'data': ['string', 'boolean', 'number', 'size'] } 2495 2496## 2497# @CommandLineParameterInfo: 2498# 2499# Details about a single parameter of a command line option. 2500# 2501# @name: parameter name 2502# 2503# @type: parameter @CommandLineParameterType 2504# 2505# @help: human readable text string, not suitable for parsing. 2506# 2507# @default: default value string (since 2.1) 2508# 2509# Since: 1.5 2510## 2511{ 'struct': 'CommandLineParameterInfo', 2512 'data': { 'name': 'str', 2513 'type': 'CommandLineParameterType', 2514 '*help': 'str', 2515 '*default': 'str' } } 2516 2517## 2518# @CommandLineOptionInfo: 2519# 2520# Details about a command line option, including its list of parameter details 2521# 2522# @option: option name 2523# 2524# @parameters: an array of @CommandLineParameterInfo 2525# 2526# Since: 1.5 2527## 2528{ 'struct': 'CommandLineOptionInfo', 2529 'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } } 2530 2531## 2532# @query-command-line-options: 2533# 2534# Query command line option schema. 2535# 2536# @option: option name 2537# 2538# Returns: list of @CommandLineOptionInfo for all options (or for the given 2539# @option). Returns an error if the given @option doesn't exist. 2540# 2541# Since: 1.5 2542# 2543# Example: 2544# 2545# -> { "execute": "query-command-line-options", 2546# "arguments": { "option": "option-rom" } } 2547# <- { "return": [ 2548# { 2549# "parameters": [ 2550# { 2551# "name": "romfile", 2552# "type": "string" 2553# }, 2554# { 2555# "name": "bootindex", 2556# "type": "number" 2557# } 2558# ], 2559# "option": "option-rom" 2560# } 2561# ] 2562# } 2563# 2564## 2565{'command': 'query-command-line-options', 'data': { '*option': 'str' }, 2566 'returns': ['CommandLineOptionInfo'] } 2567 2568## 2569# @X86CPURegister32: 2570# 2571# A X86 32-bit register 2572# 2573# Since: 1.5 2574## 2575{ 'enum': 'X86CPURegister32', 2576 'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] } 2577 2578## 2579# @X86CPUFeatureWordInfo: 2580# 2581# Information about a X86 CPU feature word 2582# 2583# @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word 2584# 2585# @cpuid-input-ecx: Input ECX value for CPUID instruction for that 2586# feature word 2587# 2588# @cpuid-register: Output register containing the feature bits 2589# 2590# @features: value of output register, containing the feature bits 2591# 2592# Since: 1.5 2593## 2594{ 'struct': 'X86CPUFeatureWordInfo', 2595 'data': { 'cpuid-input-eax': 'int', 2596 '*cpuid-input-ecx': 'int', 2597 'cpuid-register': 'X86CPURegister32', 2598 'features': 'int' } } 2599 2600## 2601# @DummyForceArrays: 2602# 2603# Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally 2604# 2605# Since: 2.5 2606## 2607{ 'struct': 'DummyForceArrays', 2608 'data': { 'unused': ['X86CPUFeatureWordInfo'] } } 2609 2610 2611## 2612# @NumaOptionsType: 2613# 2614# @node: NUMA nodes configuration 2615# 2616# @dist: NUMA distance configuration (since 2.10) 2617# 2618# @cpu: property based CPU(s) to node mapping (Since: 2.10) 2619# 2620# Since: 2.1 2621## 2622{ 'enum': 'NumaOptionsType', 2623 'data': [ 'node', 'dist', 'cpu' ] } 2624 2625## 2626# @NumaOptions: 2627# 2628# A discriminated record of NUMA options. (for OptsVisitor) 2629# 2630# Since: 2.1 2631## 2632{ 'union': 'NumaOptions', 2633 'base': { 'type': 'NumaOptionsType' }, 2634 'discriminator': 'type', 2635 'data': { 2636 'node': 'NumaNodeOptions', 2637 'dist': 'NumaDistOptions', 2638 'cpu': 'NumaCpuOptions' }} 2639 2640## 2641# @NumaNodeOptions: 2642# 2643# Create a guest NUMA node. (for OptsVisitor) 2644# 2645# @nodeid: NUMA node ID (increase by 1 from 0 if omitted) 2646# 2647# @cpus: VCPUs belonging to this node (assign VCPUS round-robin 2648# if omitted) 2649# 2650# @mem: memory size of this node; mutually exclusive with @memdev. 2651# Equally divide total memory among nodes if both @mem and @memdev are 2652# omitted. 2653# 2654# @memdev: memory backend object. If specified for one node, 2655# it must be specified for all nodes. 2656# 2657# Since: 2.1 2658## 2659{ 'struct': 'NumaNodeOptions', 2660 'data': { 2661 '*nodeid': 'uint16', 2662 '*cpus': ['uint16'], 2663 '*mem': 'size', 2664 '*memdev': 'str' }} 2665 2666## 2667# @NumaDistOptions: 2668# 2669# Set the distance between 2 NUMA nodes. 2670# 2671# @src: source NUMA node. 2672# 2673# @dst: destination NUMA node. 2674# 2675# @val: NUMA distance from source node to destination node. 2676# When a node is unreachable from another node, set the distance 2677# between them to 255. 2678# 2679# Since: 2.10 2680## 2681{ 'struct': 'NumaDistOptions', 2682 'data': { 2683 'src': 'uint16', 2684 'dst': 'uint16', 2685 'val': 'uint8' }} 2686 2687## 2688# @NumaCpuOptions: 2689# 2690# Option "-numa cpu" overrides default cpu to node mapping. 2691# It accepts the same set of cpu properties as returned by 2692# query-hotpluggable-cpus[].props, where node-id could be used to 2693# override default node mapping. 2694# 2695# Since: 2.10 2696## 2697{ 'struct': 'NumaCpuOptions', 2698 'base': 'CpuInstanceProperties', 2699 'data' : {} } 2700 2701## 2702# @HostMemPolicy: 2703# 2704# Host memory policy types 2705# 2706# @default: restore default policy, remove any nondefault policy 2707# 2708# @preferred: set the preferred host nodes for allocation 2709# 2710# @bind: a strict policy that restricts memory allocation to the 2711# host nodes specified 2712# 2713# @interleave: memory allocations are interleaved across the set 2714# of host nodes specified 2715# 2716# Since: 2.1 2717## 2718{ 'enum': 'HostMemPolicy', 2719 'data': [ 'default', 'preferred', 'bind', 'interleave' ] } 2720 2721## 2722# @Memdev: 2723# 2724# Information about memory backend 2725# 2726# @id: backend's ID if backend has 'id' property (since 2.9) 2727# 2728# @size: memory backend size 2729# 2730# @merge: enables or disables memory merge support 2731# 2732# @dump: includes memory backend's memory in a core dump or not 2733# 2734# @prealloc: enables or disables memory preallocation 2735# 2736# @host-nodes: host nodes for its memory policy 2737# 2738# @policy: memory policy of memory backend 2739# 2740# Since: 2.1 2741## 2742{ 'struct': 'Memdev', 2743 'data': { 2744 '*id': 'str', 2745 'size': 'size', 2746 'merge': 'bool', 2747 'dump': 'bool', 2748 'prealloc': 'bool', 2749 'host-nodes': ['uint16'], 2750 'policy': 'HostMemPolicy' }} 2751 2752## 2753# @query-memdev: 2754# 2755# Returns information for all memory backends. 2756# 2757# Returns: a list of @Memdev. 2758# 2759# Since: 2.1 2760# 2761# Example: 2762# 2763# -> { "execute": "query-memdev" } 2764# <- { "return": [ 2765# { 2766# "id": "mem1", 2767# "size": 536870912, 2768# "merge": false, 2769# "dump": true, 2770# "prealloc": false, 2771# "host-nodes": [0, 1], 2772# "policy": "bind" 2773# }, 2774# { 2775# "size": 536870912, 2776# "merge": false, 2777# "dump": true, 2778# "prealloc": true, 2779# "host-nodes": [2, 3], 2780# "policy": "preferred" 2781# } 2782# ] 2783# } 2784# 2785## 2786{ 'command': 'query-memdev', 'returns': ['Memdev'] } 2787 2788## 2789# @PCDIMMDeviceInfo: 2790# 2791# PCDIMMDevice state information 2792# 2793# @id: device's ID 2794# 2795# @addr: physical address, where device is mapped 2796# 2797# @size: size of memory that the device provides 2798# 2799# @slot: slot number at which device is plugged in 2800# 2801# @node: NUMA node number where device is plugged in 2802# 2803# @memdev: memory backend linked with device 2804# 2805# @hotplugged: true if device was hotplugged 2806# 2807# @hotpluggable: true if device if could be added/removed while machine is running 2808# 2809# Since: 2.1 2810## 2811{ 'struct': 'PCDIMMDeviceInfo', 2812 'data': { '*id': 'str', 2813 'addr': 'int', 2814 'size': 'int', 2815 'slot': 'int', 2816 'node': 'int', 2817 'memdev': 'str', 2818 'hotplugged': 'bool', 2819 'hotpluggable': 'bool' 2820 } 2821} 2822 2823## 2824# @MemoryDeviceInfo: 2825# 2826# Union containing information about a memory device 2827# 2828# Since: 2.1 2829## 2830{ 'union': 'MemoryDeviceInfo', 'data': {'dimm': 'PCDIMMDeviceInfo'} } 2831 2832## 2833# @query-memory-devices: 2834# 2835# Lists available memory devices and their state 2836# 2837# Since: 2.1 2838# 2839# Example: 2840# 2841# -> { "execute": "query-memory-devices" } 2842# <- { "return": [ { "data": 2843# { "addr": 5368709120, 2844# "hotpluggable": true, 2845# "hotplugged": true, 2846# "id": "d1", 2847# "memdev": "/objects/memX", 2848# "node": 0, 2849# "size": 1073741824, 2850# "slot": 0}, 2851# "type": "dimm" 2852# } ] } 2853# 2854## 2855{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } 2856 2857## 2858# @MEM_UNPLUG_ERROR: 2859# 2860# Emitted when memory hot unplug error occurs. 2861# 2862# @device: device name 2863# 2864# @msg: Informative message 2865# 2866# Since: 2.4 2867# 2868# Example: 2869# 2870# <- { "event": "MEM_UNPLUG_ERROR" 2871# "data": { "device": "dimm1", 2872# "msg": "acpi: device unplug for unsupported device" 2873# }, 2874# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 2875# 2876## 2877{ 'event': 'MEM_UNPLUG_ERROR', 2878 'data': { 'device': 'str', 'msg': 'str' } } 2879 2880## 2881# @ACPISlotType: 2882# 2883# @DIMM: memory slot 2884# @CPU: logical CPU slot (since 2.7) 2885## 2886{ 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } 2887 2888## 2889# @ACPIOSTInfo: 2890# 2891# OSPM Status Indication for a device 2892# For description of possible values of @source and @status fields 2893# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec. 2894# 2895# @device: device ID associated with slot 2896# 2897# @slot: slot ID, unique per slot of a given @slot-type 2898# 2899# @slot-type: type of the slot 2900# 2901# @source: an integer containing the source event 2902# 2903# @status: an integer containing the status code 2904# 2905# Since: 2.1 2906## 2907{ 'struct': 'ACPIOSTInfo', 2908 'data' : { '*device': 'str', 2909 'slot': 'str', 2910 'slot-type': 'ACPISlotType', 2911 'source': 'int', 2912 'status': 'int' } } 2913 2914## 2915# @query-acpi-ospm-status: 2916# 2917# Return a list of ACPIOSTInfo for devices that support status 2918# reporting via ACPI _OST method. 2919# 2920# Since: 2.1 2921# 2922# Example: 2923# 2924# -> { "execute": "query-acpi-ospm-status" } 2925# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, 2926# { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, 2927# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, 2928# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} 2929# ]} 2930# 2931## 2932{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } 2933 2934## 2935# @ACPI_DEVICE_OST: 2936# 2937# Emitted when guest executes ACPI _OST method. 2938# 2939# @info: ACPIOSTInfo type as described in qapi-schema.json 2940# 2941# Since: 2.1 2942# 2943# Example: 2944# 2945# <- { "event": "ACPI_DEVICE_OST", 2946# "data": { "device": "d1", "slot": "0", 2947# "slot-type": "DIMM", "source": 1, "status": 0 } } 2948# 2949## 2950{ 'event': 'ACPI_DEVICE_OST', 2951 'data': { 'info': 'ACPIOSTInfo' } } 2952 2953## 2954# @rtc-reset-reinjection: 2955# 2956# This command will reset the RTC interrupt reinjection backlog. 2957# Can be used if another mechanism to synchronize guest time 2958# is in effect, for example QEMU guest agent's guest-set-time 2959# command. 2960# 2961# Since: 2.1 2962# 2963# Example: 2964# 2965# -> { "execute": "rtc-reset-reinjection" } 2966# <- { "return": {} } 2967# 2968## 2969{ 'command': 'rtc-reset-reinjection' } 2970 2971## 2972# @RTC_CHANGE: 2973# 2974# Emitted when the guest changes the RTC time. 2975# 2976# @offset: offset between base RTC clock (as specified by -rtc base), and 2977# new RTC clock value 2978# 2979# Note: This event is rate-limited. 2980# 2981# Since: 0.13.0 2982# 2983# Example: 2984# 2985# <- { "event": "RTC_CHANGE", 2986# "data": { "offset": 78 }, 2987# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } 2988# 2989## 2990{ 'event': 'RTC_CHANGE', 2991 'data': { 'offset': 'int' } } 2992 2993## 2994# @ReplayMode: 2995# 2996# Mode of the replay subsystem. 2997# 2998# @none: normal execution mode. Replay or record are not enabled. 2999# 3000# @record: record mode. All non-deterministic data is written into the
3001# replay log. 3002# 3003# @play: replay mode. Non-deterministic data required for system execution 3004# is read from the log. 3005# 3006# Since: 2.5 3007## 3008{ 'enum': 'ReplayMode', 3009 'data': [ 'none', 'record', 'play' ] } 3010 3011## 3012# @xen-load-devices-state: 3013# 3014# Load the state of all devices from file. The RAM and the block devices 3015# of the VM are not loaded by this command. 3016# 3017# @filename: the file to load the state of the devices from as binary 3018# data. See xen-save-devices-state.txt for a description of the binary 3019# format. 3020# 3021# Since: 2.7 3022# 3023# Example: 3024# 3025# -> { "execute": "xen-load-devices-state", 3026# "arguments": { "filename": "/tmp/resume" } } 3027# <- { "return": {} } 3028# 3029## 3030{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } 3031 3032## 3033# @GICCapability: 3034# 3035# The struct describes capability for a specific GIC (Generic 3036# Interrupt Controller) version. These bits are not only decided by 3037# QEMU/KVM software version, but also decided by the hardware that 3038# the program is running upon. 3039# 3040# @version: version of GIC to be described. Currently, only 2 and 3 3041# are supported. 3042# 3043# @emulated: whether current QEMU/hardware supports emulated GIC 3044# device in user space. 3045# 3046# @kernel: whether current QEMU/hardware supports hardware 3047# accelerated GIC device in kernel. 3048# 3049# Since: 2.6 3050## 3051{ 'struct': 'GICCapability', 3052 'data': { 'version': 'int', 3053 'emulated': 'bool', 3054 'kernel': 'bool' } } 3055 3056## 3057# @query-gic-capabilities: 3058# 3059# This command is ARM-only. It will return a list of GICCapability 3060# objects that describe its capability bits. 3061# 3062# Returns: a list of GICCapability objects. 3063# 3064# Since: 2.6 3065# 3066# Example: 3067# 3068# -> { "execute": "query-gic-capabilities" } 3069# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, 3070# { "version": 3, "emulated": false, "kernel": true } ] } 3071# 3072## 3073{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] } 3074 3075## 3076# @CpuInstanceProperties: 3077# 3078# List of properties to be used for hotplugging a CPU instance, 3079# it should be passed by management with device_add command when 3080# a CPU is being hotplugged. 3081# 3082# @node-id: NUMA node ID the CPU belongs to 3083# @socket-id: socket number within node/board the CPU belongs to 3084# @core-id: core number within socket the CPU belongs to 3085# @thread-id: thread number within core the CPU belongs to 3086# 3087# Note: currently there are 4 properties that could be present 3088# but management should be prepared to pass through other 3089# properties with device_add command to allow for future 3090# interface extension. This also requires the filed names to be kept in 3091# sync with the properties passed to -device/device_add. 3092# 3093# Since: 2.7 3094## 3095{ 'struct': 'CpuInstanceProperties', 3096 'data': { '*node-id': 'int', 3097 '*socket-id': 'int', 3098 '*core-id': 'int', 3099 '*thread-id': 'int' 3100 } 3101} 3102 3103## 3104# @HotpluggableCPU: 3105# 3106# @type: CPU object type for usage with device_add command 3107# @props: list of properties to be used for hotplugging CPU 3108# @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides 3109# @qom-path: link to existing CPU object if CPU is present or 3110# omitted if CPU is not present. 3111# 3112# Since: 2.7 3113## 3114{ 'struct': 'HotpluggableCPU', 3115 'data': { 'type': 'str', 3116 'vcpus-count': 'int', 3117 'props': 'CpuInstanceProperties', 3118 '*qom-path': 'str' 3119 } 3120} 3121 3122## 3123# @query-hotpluggable-cpus: 3124# 3125# Returns: a list of HotpluggableCPU objects. 3126# 3127# Since: 2.7 3128# 3129# Example: 3130# 3131# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8: 3132# 3133# -> { "execute": "query-hotpluggable-cpus" } 3134# <- {"return": [ 3135# { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core", 3136# "vcpus-count": 1 }, 3137# { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core", 3138# "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} 3139# ]}' 3140# 3141# For pc machine type started with -smp 1,maxcpus=2: 3142# 3143# -> { "execute": "query-hotpluggable-cpus" } 3144# <- {"return": [ 3145# { 3146# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, 3147# "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} 3148# }, 3149# { 3150# "qom-path": "/machine/unattached/device[0]", 3151# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, 3152# "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} 3153# } 3154# ]} 3155# 3156# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu 3157# (Since: 2.11): 3158# 3159# -> { "execute": "query-hotpluggable-cpus" } 3160# <- {"return": [ 3161# { 3162# "type": "qemu-s390x-cpu", "vcpus-count": 1, 3163# "props": { "core-id": 1 } 3164# }, 3165# { 3166# "qom-path": "/machine/unattached/device[0]", 3167# "type": "qemu-s390x-cpu", "vcpus-count": 1, 3168# "props": { "core-id": 0 } 3169# } 3170# ]} 3171# 3172## 3173{ 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'] } 3174 3175## 3176# @GuidInfo: 3177# 3178# GUID information. 3179# 3180# @guid: the globally unique identifier 3181# 3182# Since: 2.9 3183## 3184{ 'struct': 'GuidInfo', 'data': {'guid': 'str'} } 3185 3186## 3187# @query-vm-generation-id: 3188# 3189# Show Virtual Machine Generation ID 3190# 3191# Since 2.9 3192## 3193{ 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' } 3194 3195## 3196# @watchdog-set-action: 3197# 3198# Set watchdog action 3199# 3200# Since: 2.11 3201## 3202{ 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} } 3203