qapi/machine.json

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