qapi/machine.json: Fix missing newline in doc comment
[qemu.git] / qapi / machine.json
1 # -*- Mode: Python -*-
2 #
3 # This work is licensed under the terms of the GNU GPL, version 2 or later.
4 # See the COPYING file in the top-level directory.
5
6 ##
7 # = Machines
8 ##
9
10 ##
11 # @SysEmuTarget:
12 #
13 # The comprehensive enumeration of QEMU system emulation ("softmmu")
14 # targets. Run "./configure --help" in the project root directory, and
15 # look for the *-softmmu targets near the "--target-list" option. The
16 # individual target constants are not documented here, for the time
17 # being.
18 #
19 # @rx: since 5.0
20 # @avr: since 5.1
21 #
22 # Notes: The resulting QMP strings can be appended to the "qemu-system-"
23 #        prefix to produce the corresponding QEMU executable name. This
24 #        is true even for "qemu-system-x86_64".
25 #
26 # Since: 3.0
27 ##
28 { 'enum' : 'SysEmuTarget',
29   'data' : [ 'aarch64', 'alpha', 'arm', 'avr', 'cris', 'hppa', 'i386', 'lm32',
30              'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64',
31              'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc',
32              'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4',
33              'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
34              'x86_64', 'xtensa', 'xtensaeb' ] }
35
36 ##
37 # @CpuInfoArch:
38 #
39 # An enumeration of cpu types that enable additional information during
40 # @query-cpus and @query-cpus-fast.
41 #
42 # @s390: since 2.12
43 #
44 # @riscv: since 2.12
45 #
46 # Since: 2.6
47 ##
48 { 'enum': 'CpuInfoArch',
49   'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 's390', 'riscv', 'other' ] }
50
51 ##
52 # @CpuInfo:
53 #
54 # Information about a virtual CPU
55 #
56 # @CPU: the index of the virtual CPU
57 #
58 # @current: this only exists for backwards compatibility and should be ignored
59 #
60 # @halted: true if the virtual CPU is in the halt state.  Halt usually refers
61 #          to a processor specific low power mode.
62 #
63 # @qom_path: path to the CPU object in the QOM tree (since 2.4)
64 #
65 # @thread_id: ID of the underlying host thread
66 #
67 # @props: properties describing to which node/socket/core/thread
68 #         virtual CPU belongs to, provided if supported by board (since 2.10)
69 #
70 # @arch: architecture of the cpu, which determines which additional fields
71 #        will be listed (since 2.6)
72 #
73 # Since: 0.14.0
74 #
75 # Notes: @halted is a transient state that changes frequently.  By the time the
76 #        data is sent to the client, the guest may no longer be halted.
77 ##
78 { 'union': 'CpuInfo',
79   'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool',
80            'qom_path': 'str', 'thread_id': 'int',
81            '*props': 'CpuInstanceProperties', 'arch': 'CpuInfoArch' },
82   'discriminator': 'arch',
83   'data': { 'x86': 'CpuInfoX86',
84             'sparc': 'CpuInfoSPARC',
85             'ppc': 'CpuInfoPPC',
86             'mips': 'CpuInfoMIPS',
87             'tricore': 'CpuInfoTricore',
88             's390': 'CpuInfoS390',
89             'riscv': 'CpuInfoRISCV' } }
90
91 ##
92 # @CpuInfoX86:
93 #
94 # Additional information about a virtual i386 or x86_64 CPU
95 #
96 # @pc: the 64-bit instruction pointer
97 #
98 # Since: 2.6
99 ##
100 { 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } }
101
102 ##
103 # @CpuInfoSPARC:
104 #
105 # Additional information about a virtual SPARC CPU
106 #
107 # @pc: the PC component of the instruction pointer
108 #
109 # @npc: the NPC component of the instruction pointer
110 #
111 # Since: 2.6
112 ##
113 { 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } }
114
115 ##
116 # @CpuInfoPPC:
117 #
118 # Additional information about a virtual PPC CPU
119 #
120 # @nip: the instruction pointer
121 #
122 # Since: 2.6
123 ##
124 { 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } }
125
126 ##
127 # @CpuInfoMIPS:
128 #
129 # Additional information about a virtual MIPS CPU
130 #
131 # @PC: the instruction pointer
132 #
133 # Since: 2.6
134 ##
135 { 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } }
136
137 ##
138 # @CpuInfoTricore:
139 #
140 # Additional information about a virtual Tricore CPU
141 #
142 # @PC: the instruction pointer
143 #
144 # Since: 2.6
145 ##
146 { 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } }
147
148 ##
149 # @CpuInfoRISCV:
150 #
151 # Additional information about a virtual RISCV CPU
152 #
153 # @pc: the instruction pointer
154 #
155 # Since 2.12
156 ##
157 { 'struct': 'CpuInfoRISCV', 'data': { 'pc': 'int' } }
158
159 ##
160 # @CpuS390State:
161 #
162 # An enumeration of cpu states that can be assumed by a virtual
163 # S390 CPU
164 #
165 # Since: 2.12
166 ##
167 { 'enum': 'CpuS390State',
168   'prefix': 'S390_CPU_STATE',
169   'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] }
170
171 ##
172 # @CpuInfoS390:
173 #
174 # Additional information about a virtual S390 CPU
175 #
176 # @cpu-state: the virtual CPU's state
177 #
178 # Since: 2.12
179 ##
180 { 'struct': 'CpuInfoS390', 'data': { 'cpu-state': 'CpuS390State' } }
181
182 ##
183 # @query-cpus:
184 #
185 # Returns a list of information about each virtual CPU.
186 #
187 # This command causes vCPU threads to exit to userspace, which causes
188 # a small interruption to guest CPU execution. This will have a negative
189 # impact on realtime guests and other latency sensitive guest workloads.
190 #
191 # Features:
192 # @deprecated: This command is deprecated, because it interferes with
193 #     the guest.  Use 'query-cpus-fast' instead to avoid the vCPU
194 #     interruption.
195 #
196 # Returns: a list of @CpuInfo for each virtual CPU
197 #
198 # Since: 0.14.0
199 #
200 # Example:
201 #
202 # -> { "execute": "query-cpus" }
203 # <- { "return": [
204 #          {
205 #             "CPU":0,
206 #             "current":true,
207 #             "halted":false,
208 #             "qom_path":"/machine/unattached/device[0]",
209 #             "arch":"x86",
210 #             "pc":3227107138,
211 #             "thread_id":3134
212 #          },
213 #          {
214 #             "CPU":1,
215 #             "current":false,
216 #             "halted":true,
217 #             "qom_path":"/machine/unattached/device[2]",
218 #             "arch":"x86",
219 #             "pc":7108165,
220 #             "thread_id":3135
221 #          }
222 #       ]
223 #    }
224 #
225 ##
226 { 'command': 'query-cpus', 'returns': ['CpuInfo'],
227   'features': [ 'deprecated' ] }
228
229 ##
230 # @CpuInfoFast:
231 #
232 # Information about a virtual CPU
233 #
234 # @cpu-index: index of the virtual CPU
235 #
236 # @qom-path: path to the CPU object in the QOM tree
237 #
238 # @thread-id: ID of the underlying host thread
239 #
240 # @props: properties describing to which node/socket/core/thread
241 #         virtual CPU belongs to, provided if supported by board
242 #
243 # @arch: base architecture of the cpu
244 #
245 # @target: the QEMU system emulation target, which determines which
246 #          additional fields will be listed (since 3.0)
247 #
248 # Features:
249 # @deprecated: Member @arch is deprecated.  Use @target instead.
250 #
251 # Since: 2.12
252 #
253 ##
254 { 'union'         : 'CpuInfoFast',
255   'base'          : { 'cpu-index'    : 'int',
256                       'qom-path'     : 'str',
257                       'thread-id'    : 'int',
258                       '*props'       : 'CpuInstanceProperties',
259                       'arch'         : { 'type': 'CpuInfoArch',
260                                          'features': [ 'deprecated' ] },
261                       'target'       : 'SysEmuTarget' },
262   'discriminator' : 'target',
263   'data'          : { 's390x'        : 'CpuInfoS390' } }
264
265 ##
266 # @query-cpus-fast:
267 #
268 # Returns information about all virtual CPUs. This command does not
269 # incur a performance penalty and should be used in production
270 # instead of query-cpus.
271 #
272 # Returns: list of @CpuInfoFast
273 #
274 # Since: 2.12
275 #
276 # Example:
277 #
278 # -> { "execute": "query-cpus-fast" }
279 # <- { "return": [
280 #         {
281 #             "thread-id": 25627,
282 #             "props": {
283 #                 "core-id": 0,
284 #                 "thread-id": 0,
285 #                 "socket-id": 0
286 #             },
287 #             "qom-path": "/machine/unattached/device[0]",
288 #             "arch":"x86",
289 #             "target":"x86_64",
290 #             "cpu-index": 0
291 #         },
292 #         {
293 #             "thread-id": 25628,
294 #             "props": {
295 #                 "core-id": 0,
296 #                 "thread-id": 0,
297 #                 "socket-id": 1
298 #             },
299 #             "qom-path": "/machine/unattached/device[2]",
300 #             "arch":"x86",
301 #             "target":"x86_64",
302 #             "cpu-index": 1
303 #         }
304 #     ]
305 # }
306 ##
307 { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
308
309 ##
310 # @cpu-add:
311 #
312 # Adds CPU with specified ID.
313 #
314 # @id: ID of CPU to be created, valid values [0..max_cpus)
315 #
316 # Features:
317 # @deprecated: This command is deprecated.  Use `device_add` instead.
318 #     See the `query-hotpluggable-cpus` command for details.
319 #
320 # Returns: Nothing on success
321 #
322 # Since: 1.5
323 #
324 # Example:
325 #
326 # -> { "execute": "cpu-add", "arguments": { "id": 2 } }
327 # <- { "return": {} }
328 #
329 ##
330 { 'command': 'cpu-add', 'data': {'id': 'int'},
331   'features': [ 'deprecated' ] }
332
333 ##
334 # @MachineInfo:
335 #
336 # Information describing a machine.
337 #
338 # @name: the name of the machine
339 #
340 # @alias: an alias for the machine name
341 #
342 # @is-default: whether the machine is default
343 #
344 # @cpu-max: maximum number of CPUs supported by the machine type
345 #           (since 1.5.0)
346 #
347 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
348 #
349 # @numa-mem-supported: true if '-numa node,mem' option is supported by
350 #                      the machine type and false otherwise (since 4.1)
351 #
352 # @deprecated: if true, the machine type is deprecated and may be removed
353 #              in future versions of QEMU according to the QEMU deprecation
354 #              policy (since 4.1.0)
355 #
356 # @default-cpu-type: default CPU model typename if none is requested via
357 #                    the -cpu argument. (since 4.2)
358 #
359 # Since: 1.2.0
360 ##
361 { 'struct': 'MachineInfo',
362   'data': { 'name': 'str', '*alias': 'str',
363             '*is-default': 'bool', 'cpu-max': 'int',
364             'hotpluggable-cpus': 'bool',  'numa-mem-supported': 'bool',
365             'deprecated': 'bool', '*default-cpu-type': 'str' } }
366
367 ##
368 # @query-machines:
369 #
370 # Return a list of supported machines
371 #
372 # Returns: a list of MachineInfo
373 #
374 # Since: 1.2.0
375 ##
376 { 'command': 'query-machines', 'returns': ['MachineInfo'] }
377
378 ##
379 # @CurrentMachineParams:
380 #
381 # Information describing the running machine parameters.
382 #
383 # @wakeup-suspend-support: true if the machine supports wake up from
384 #                          suspend
385 #
386 # Since: 4.0
387 ##
388 { 'struct': 'CurrentMachineParams',
389   'data': { 'wakeup-suspend-support': 'bool'} }
390
391 ##
392 # @query-current-machine:
393 #
394 # Return information on the current virtual machine.
395 #
396 # Returns: CurrentMachineParams
397 #
398 # Since: 4.0
399 ##
400 { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
401
402 ##
403 # @TargetInfo:
404 #
405 # Information describing the QEMU target.
406 #
407 # @arch: the target architecture
408 #
409 # Since: 1.2.0
410 ##
411 { 'struct': 'TargetInfo',
412   'data': { 'arch': 'SysEmuTarget' } }
413
414 ##
415 # @query-target:
416 #
417 # Return information about the target for this QEMU
418 #
419 # Returns: TargetInfo
420 #
421 # Since: 1.2.0
422 ##
423 { 'command': 'query-target', 'returns': 'TargetInfo' }
424
425 ##
426 # @NumaOptionsType:
427 #
428 # @node: NUMA nodes configuration
429 #
430 # @dist: NUMA distance configuration (since 2.10)
431 #
432 # @cpu: property based CPU(s) to node mapping (Since: 2.10)
433 #
434 # @hmat-lb: memory latency and bandwidth information (Since: 5.0)
435 #
436 # @hmat-cache: memory side cache information (Since: 5.0)
437 #
438 # Since: 2.1
439 ##
440 { 'enum': 'NumaOptionsType',
441   'data': [ 'node', 'dist', 'cpu', 'hmat-lb', 'hmat-cache' ] }
442
443 ##
444 # @NumaOptions:
445 #
446 # A discriminated record of NUMA options. (for OptsVisitor)
447 #
448 # Since: 2.1
449 ##
450 { 'union': 'NumaOptions',
451   'base': { 'type': 'NumaOptionsType' },
452   'discriminator': 'type',
453   'data': {
454     'node': 'NumaNodeOptions',
455     'dist': 'NumaDistOptions',
456     'cpu': 'NumaCpuOptions',
457     'hmat-lb': 'NumaHmatLBOptions',
458     'hmat-cache': 'NumaHmatCacheOptions' }}
459
460 ##
461 # @NumaNodeOptions:
462 #
463 # Create a guest NUMA node. (for OptsVisitor)
464 #
465 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
466 #
467 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin
468 #         if omitted)
469 #
470 # @mem: memory size of this node; mutually exclusive with @memdev.
471 #       Equally divide total memory among nodes if both @mem and @memdev are
472 #       omitted.
473 #
474 # @memdev: memory backend object.  If specified for one node,
475 #          it must be specified for all nodes.
476 #
477 # @initiator: defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145,
478 #             points to the nodeid which has the memory controller
479 #             responsible for this NUMA node. This field provides
480 #             additional information as to the initiator node that
481 #             is closest (as in directly attached) to this node, and
482 #             therefore has the best performance (since 5.0)
483 #
484 # Since: 2.1
485 ##
486 { 'struct': 'NumaNodeOptions',
487   'data': {
488    '*nodeid': 'uint16',
489    '*cpus':   ['uint16'],
490    '*mem':    'size',
491    '*memdev': 'str',
492    '*initiator': 'uint16' }}
493
494 ##
495 # @NumaDistOptions:
496 #
497 # Set the distance between 2 NUMA nodes.
498 #
499 # @src: source NUMA node.
500 #
501 # @dst: destination NUMA node.
502 #
503 # @val: NUMA distance from source node to destination node.
504 #       When a node is unreachable from another node, set the distance
505 #       between them to 255.
506 #
507 # Since: 2.10
508 ##
509 { 'struct': 'NumaDistOptions',
510   'data': {
511    'src': 'uint16',
512    'dst': 'uint16',
513    'val': 'uint8' }}
514
515 ##
516 # @X86CPURegister32:
517 #
518 # A X86 32-bit register
519 #
520 # Since: 1.5
521 ##
522 { 'enum': 'X86CPURegister32',
523   'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
524
525 ##
526 # @X86CPUFeatureWordInfo:
527 #
528 # Information about a X86 CPU feature word
529 #
530 # @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
531 #
532 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
533 #                   feature word
534 #
535 # @cpuid-register: Output register containing the feature bits
536 #
537 # @features: value of output register, containing the feature bits
538 #
539 # Since: 1.5
540 ##
541 { 'struct': 'X86CPUFeatureWordInfo',
542   'data': { 'cpuid-input-eax': 'int',
543             '*cpuid-input-ecx': 'int',
544             'cpuid-register': 'X86CPURegister32',
545             'features': 'int' } }
546
547 ##
548 # @DummyForceArrays:
549 #
550 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
551 #
552 # Since: 2.5
553 ##
554 { 'struct': 'DummyForceArrays',
555   'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
556
557 ##
558 # @NumaCpuOptions:
559 #
560 # Option "-numa cpu" overrides default cpu to node mapping.
561 # It accepts the same set of cpu properties as returned by
562 # query-hotpluggable-cpus[].props, where node-id could be used to
563 # override default node mapping.
564 #
565 # Since: 2.10
566 ##
567 { 'struct': 'NumaCpuOptions',
568    'base': 'CpuInstanceProperties',
569    'data' : {} }
570
571 ##
572 # @HmatLBMemoryHierarchy:
573 #
574 # The memory hierarchy in the System Locality Latency and Bandwidth
575 # Information Structure of HMAT (Heterogeneous Memory Attribute Table)
576 #
577 # For more information about @HmatLBMemoryHierarchy, see chapter
578 # 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
579 #
580 # @memory: the structure represents the memory performance
581 #
582 # @first-level: first level of memory side cache
583 #
584 # @second-level: second level of memory side cache
585 #
586 # @third-level: third level of memory side cache
587 #
588 # Since: 5.0
589 ##
590 { 'enum': 'HmatLBMemoryHierarchy',
591   'data': [ 'memory', 'first-level', 'second-level', 'third-level' ] }
592
593 ##
594 # @HmatLBDataType:
595 #
596 # Data type in the System Locality Latency and Bandwidth
597 # Information Structure of HMAT (Heterogeneous Memory Attribute Table)
598 #
599 # For more information about @HmatLBDataType, see chapter
600 # 5.2.27.4: Table 5-146:  Field "Data Type" of ACPI 6.3 spec.
601 #
602 # @access-latency: access latency (nanoseconds)
603 #
604 # @read-latency: read latency (nanoseconds)
605 #
606 # @write-latency: write latency (nanoseconds)
607 #
608 # @access-bandwidth: access bandwidth (Bytes per second)
609 #
610 # @read-bandwidth: read bandwidth (Bytes per second)
611 #
612 # @write-bandwidth: write bandwidth (Bytes per second)
613 #
614 # Since: 5.0
615 ##
616 { 'enum': 'HmatLBDataType',
617   'data': [ 'access-latency', 'read-latency', 'write-latency',
618             'access-bandwidth', 'read-bandwidth', 'write-bandwidth' ] }
619
620 ##
621 # @NumaHmatLBOptions:
622 #
623 # Set the system locality latency and bandwidth information
624 # between Initiator and Target proximity Domains.
625 #
626 # For more information about @NumaHmatLBOptions, see chapter
627 # 5.2.27.4: Table 5-146 of ACPI 6.3 spec.
628 #
629 # @initiator: the Initiator Proximity Domain.
630 #
631 # @target: the Target Proximity Domain.
632 #
633 # @hierarchy: the Memory Hierarchy. Indicates the performance
634 #             of memory or side cache.
635 #
636 # @data-type: presents the type of data, access/read/write
637 #             latency or hit latency.
638 #
639 # @latency: the value of latency from @initiator to @target
640 #           proximity domain, the latency unit is "ns(nanosecond)".
641 #
642 # @bandwidth: the value of bandwidth between @initiator and @target
643 #             proximity domain, the bandwidth unit is
644 #             "Bytes per second".
645 #
646 # Since: 5.0
647 ##
648 { 'struct': 'NumaHmatLBOptions',
649     'data': {
650     'initiator': 'uint16',
651     'target': 'uint16',
652     'hierarchy': 'HmatLBMemoryHierarchy',
653     'data-type': 'HmatLBDataType',
654     '*latency': 'uint64',
655     '*bandwidth': 'size' }}
656
657 ##
658 # @HmatCacheAssociativity:
659 #
660 # Cache associativity in the Memory Side Cache Information Structure
661 # of HMAT
662 #
663 # For more information of @HmatCacheAssociativity, see chapter
664 # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
665 #
666 # @none: None (no memory side cache in this proximity domain,
667 #              or cache associativity unknown)
668 #
669 # @direct: Direct Mapped
670 #
671 # @complex: Complex Cache Indexing (implementation specific)
672 #
673 # Since: 5.0
674 ##
675 { 'enum': 'HmatCacheAssociativity',
676   'data': [ 'none', 'direct', 'complex' ] }
677
678 ##
679 # @HmatCacheWritePolicy:
680 #
681 # Cache write policy in the Memory Side Cache Information Structure
682 # of HMAT
683 #
684 # For more information of @HmatCacheWritePolicy, see chapter
685 # 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
686 #
687 # @none: None (no memory side cache in this proximity domain,
688 #        or cache write policy unknown)
689 #
690 # @write-back: Write Back (WB)
691 #
692 # @write-through: Write Through (WT)
693 #
694 # Since: 5.0
695 ##
696 { 'enum': 'HmatCacheWritePolicy',
697   'data': [ 'none', 'write-back', 'write-through' ] }
698
699 ##
700 # @NumaHmatCacheOptions:
701 #
702 # Set the memory side cache information for a given memory domain.
703 #
704 # For more information of @NumaHmatCacheOptions, see chapter
705 # 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
706 #
707 # @node-id: the memory proximity domain to which the memory belongs.
708 #
709 # @size: the size of memory side cache in bytes.
710 #
711 # @level: the cache level described in this structure.
712 #
713 # @associativity: the cache associativity,
714 #                 none/direct-mapped/complex(complex cache indexing).
715 #
716 # @policy: the write policy, none/write-back/write-through.
717 #
718 # @line: the cache Line size in bytes.
719 #
720 # Since: 5.0
721 ##
722 { 'struct': 'NumaHmatCacheOptions',
723   'data': {
724    'node-id': 'uint32',
725    'size': 'size',
726    'level': 'uint8',
727    'associativity': 'HmatCacheAssociativity',
728    'policy': 'HmatCacheWritePolicy',
729    'line': 'uint16' }}
730
731 ##
732 # @HostMemPolicy:
733 #
734 # Host memory policy types
735 #
736 # @default: restore default policy, remove any nondefault policy
737 #
738 # @preferred: set the preferred host nodes for allocation
739 #
740 # @bind: a strict policy that restricts memory allocation to the
741 #        host nodes specified
742 #
743 # @interleave: memory allocations are interleaved across the set
744 #              of host nodes specified
745 #
746 # Since: 2.1
747 ##
748 { 'enum': 'HostMemPolicy',
749   'data': [ 'default', 'preferred', 'bind', 'interleave' ] }
750
751 ##
752 # @Memdev:
753 #
754 # Information about memory backend
755 #
756 # @id: backend's ID if backend has 'id' property (since 2.9)
757 #
758 # @size: memory backend size
759 #
760 # @merge: enables or disables memory merge support
761 #
762 # @dump: includes memory backend's memory in a core dump or not
763 #
764 # @prealloc: enables or disables memory preallocation
765 #
766 # @host-nodes: host nodes for its memory policy
767 #
768 # @policy: memory policy of memory backend
769 #
770 # Since: 2.1
771 ##
772 { 'struct': 'Memdev',
773   'data': {
774     '*id':        'str',
775     'size':       'size',
776     'merge':      'bool',
777     'dump':       'bool',
778     'prealloc':   'bool',
779     'host-nodes': ['uint16'],
780     'policy':     'HostMemPolicy' }}
781
782 ##
783 # @query-memdev:
784 #
785 # Returns information for all memory backends.
786 #
787 # Returns: a list of @Memdev.
788 #
789 # Since: 2.1
790 #
791 # Example:
792 #
793 # -> { "execute": "query-memdev" }
794 # <- { "return": [
795 #        {
796 #          "id": "mem1",
797 #          "size": 536870912,
798 #          "merge": false,
799 #          "dump": true,
800 #          "prealloc": false,
801 #          "host-nodes": [0, 1],
802 #          "policy": "bind"
803 #        },
804 #        {
805 #          "size": 536870912,
806 #          "merge": false,
807 #          "dump": true,
808 #          "prealloc": true,
809 #          "host-nodes": [2, 3],
810 #          "policy": "preferred"
811 #        }
812 #      ]
813 #    }
814 #
815 ##
816 { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
817
818 ##
819 # @CpuInstanceProperties:
820 #
821 # List of properties to be used for hotplugging a CPU instance,
822 # it should be passed by management with device_add command when
823 # a CPU is being hotplugged.
824 #
825 # @node-id: NUMA node ID the CPU belongs to
826 # @socket-id: socket number within node/board the CPU belongs to
827 # @die-id: die number within node/board the CPU belongs to (Since 4.1)
828 # @core-id: core number within die the CPU belongs to
829 # @thread-id: thread number within core the CPU belongs to
830 #
831 # Note: currently there are 5 properties that could be present
832 #       but management should be prepared to pass through other
833 #       properties with device_add command to allow for future
834 #       interface extension. This also requires the filed names to be kept in
835 #       sync with the properties passed to -device/device_add.
836 #
837 # Since: 2.7
838 ##
839 { 'struct': 'CpuInstanceProperties',
840   'data': { '*node-id': 'int',
841             '*socket-id': 'int',
842             '*die-id': 'int',
843             '*core-id': 'int',
844             '*thread-id': 'int'
845   }
846 }
847
848 ##
849 # @HotpluggableCPU:
850 #
851 # @type: CPU object type for usage with device_add command
852 # @props: list of properties to be used for hotplugging CPU
853 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
854 # @qom-path: link to existing CPU object if CPU is present or
855 #            omitted if CPU is not present.
856 #
857 # Since: 2.7
858 ##
859 { 'struct': 'HotpluggableCPU',
860   'data': { 'type': 'str',
861             'vcpus-count': 'int',
862             'props': 'CpuInstanceProperties',
863             '*qom-path': 'str'
864           }
865 }
866
867 ##
868 # @query-hotpluggable-cpus:
869 #
870 # TODO: Better documentation; currently there is none.
871 #
872 # Returns: a list of HotpluggableCPU objects.
873 #
874 # Since: 2.7
875 #
876 # Example:
877 #
878 # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
879 #
880 # -> { "execute": "query-hotpluggable-cpus" }
881 # <- {"return": [
882 #      { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
883 #        "vcpus-count": 1 },
884 #      { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
885 #        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
886 #    ]}'
887 #
888 # For pc machine type started with -smp 1,maxcpus=2:
889 #
890 # -> { "execute": "query-hotpluggable-cpus" }
891 # <- {"return": [
892 #      {
893 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
894 #         "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
895 #      },
896 #      {
897 #         "qom-path": "/machine/unattached/device[0]",
898 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
899 #         "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
900 #      }
901 #    ]}
902 #
903 # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
904 # (Since: 2.11):
905 #
906 # -> { "execute": "query-hotpluggable-cpus" }
907 # <- {"return": [
908 #      {
909 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
910 #         "props": { "core-id": 1 }
911 #      },
912 #      {
913 #         "qom-path": "/machine/unattached/device[0]",
914 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
915 #         "props": { "core-id": 0 }
916 #      }
917 #    ]}
918 #
919 ##
920 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
921              'allow-preconfig': true }
922
923 ##
924 # @set-numa-node:
925 #
926 # Runtime equivalent of '-numa' CLI option, available at
927 # preconfigure stage to configure numa mapping before initializing
928 # machine.
929 #
930 # Since 3.0
931 ##
932 { 'command': 'set-numa-node', 'boxed': true,
933   'data': 'NumaOptions',
934   'allow-preconfig': true
935 }