i386/cpu: Consolidate die-id validity in smp context
[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 { 'include': 'common.json' }
11
12 ##
13 # @CpuInfoArch:
14 #
15 # An enumeration of cpu types that enable additional information during
16 # @query-cpus and @query-cpus-fast.
17 #
18 # @s390: since 2.12
19 #
20 # @riscv: since 2.12
21 #
22 # Since: 2.6
23 ##
24 { 'enum': 'CpuInfoArch',
25   'data': ['x86', 'sparc', 'ppc', 'mips', 'tricore', 's390', 'riscv', 'other' ] }
26
27 ##
28 # @CpuInfo:
29 #
30 # Information about a virtual CPU
31 #
32 # @CPU: the index of the virtual CPU
33 #
34 # @current: this only exists for backwards compatibility and should be ignored
35 #
36 # @halted: true if the virtual CPU is in the halt state.  Halt usually refers
37 #          to a processor specific low power mode.
38 #
39 # @qom_path: path to the CPU object in the QOM tree (since 2.4)
40 #
41 # @thread_id: ID of the underlying host thread
42 #
43 # @props: properties describing to which node/socket/core/thread
44 #         virtual CPU belongs to, provided if supported by board (since 2.10)
45 #
46 # @arch: architecture of the cpu, which determines which additional fields
47 #        will be listed (since 2.6)
48 #
49 # Since: 0.14.0
50 #
51 # Notes: @halted is a transient state that changes frequently.  By the time the
52 #        data is sent to the client, the guest may no longer be halted.
53 ##
54 { 'union': 'CpuInfo',
55   'base': {'CPU': 'int', 'current': 'bool', 'halted': 'bool',
56            'qom_path': 'str', 'thread_id': 'int',
57            '*props': 'CpuInstanceProperties', 'arch': 'CpuInfoArch' },
58   'discriminator': 'arch',
59   'data': { 'x86': 'CpuInfoX86',
60             'sparc': 'CpuInfoSPARC',
61             'ppc': 'CpuInfoPPC',
62             'mips': 'CpuInfoMIPS',
63             'tricore': 'CpuInfoTricore',
64             's390': 'CpuInfoS390',
65             'riscv': 'CpuInfoRISCV' } }
66
67 ##
68 # @CpuInfoX86:
69 #
70 # Additional information about a virtual i386 or x86_64 CPU
71 #
72 # @pc: the 64-bit instruction pointer
73 #
74 # Since: 2.6
75 ##
76 { 'struct': 'CpuInfoX86', 'data': { 'pc': 'int' } }
77
78 ##
79 # @CpuInfoSPARC:
80 #
81 # Additional information about a virtual SPARC CPU
82 #
83 # @pc: the PC component of the instruction pointer
84 #
85 # @npc: the NPC component of the instruction pointer
86 #
87 # Since: 2.6
88 ##
89 { 'struct': 'CpuInfoSPARC', 'data': { 'pc': 'int', 'npc': 'int' } }
90
91 ##
92 # @CpuInfoPPC:
93 #
94 # Additional information about a virtual PPC CPU
95 #
96 # @nip: the instruction pointer
97 #
98 # Since: 2.6
99 ##
100 { 'struct': 'CpuInfoPPC', 'data': { 'nip': 'int' } }
101
102 ##
103 # @CpuInfoMIPS:
104 #
105 # Additional information about a virtual MIPS CPU
106 #
107 # @PC: the instruction pointer
108 #
109 # Since: 2.6
110 ##
111 { 'struct': 'CpuInfoMIPS', 'data': { 'PC': 'int' } }
112
113 ##
114 # @CpuInfoTricore:
115 #
116 # Additional information about a virtual Tricore CPU
117 #
118 # @PC: the instruction pointer
119 #
120 # Since: 2.6
121 ##
122 { 'struct': 'CpuInfoTricore', 'data': { 'PC': 'int' } }
123
124 ##
125 # @CpuInfoRISCV:
126 #
127 # Additional information about a virtual RISCV CPU
128 #
129 # @pc: the instruction pointer
130 #
131 # Since 2.12
132 ##
133 { 'struct': 'CpuInfoRISCV', 'data': { 'pc': 'int' } }
134
135 ##
136 # @CpuS390State:
137 #
138 # An enumeration of cpu states that can be assumed by a virtual
139 # S390 CPU
140 #
141 # Since: 2.12
142 ##
143 { 'enum': 'CpuS390State',
144   'prefix': 'S390_CPU_STATE',
145   'data': [ 'uninitialized', 'stopped', 'check-stop', 'operating', 'load' ] }
146
147 ##
148 # @CpuInfoS390:
149 #
150 # Additional information about a virtual S390 CPU
151 #
152 # @cpu-state: the virtual CPU's state
153 #
154 # Since: 2.12
155 ##
156 { 'struct': 'CpuInfoS390', 'data': { 'cpu-state': 'CpuS390State' } }
157
158 ##
159 # @query-cpus:
160 #
161 # Returns a list of information about each virtual CPU.
162 #
163 # This command causes vCPU threads to exit to userspace, which causes
164 # a small interruption to guest CPU execution. This will have a negative
165 # impact on realtime guests and other latency sensitive guest workloads.
166 # It is recommended to use @query-cpus-fast instead of this command to
167 # avoid the vCPU interruption.
168 #
169 # Returns: a list of @CpuInfo for each virtual CPU
170 #
171 # Since: 0.14.0
172 #
173 # Example:
174 #
175 # -> { "execute": "query-cpus" }
176 # <- { "return": [
177 #          {
178 #             "CPU":0,
179 #             "current":true,
180 #             "halted":false,
181 #             "qom_path":"/machine/unattached/device[0]",
182 #             "arch":"x86",
183 #             "pc":3227107138,
184 #             "thread_id":3134
185 #          },
186 #          {
187 #             "CPU":1,
188 #             "current":false,
189 #             "halted":true,
190 #             "qom_path":"/machine/unattached/device[2]",
191 #             "arch":"x86",
192 #             "pc":7108165,
193 #             "thread_id":3135
194 #          }
195 #       ]
196 #    }
197 #
198 # Notes: This interface is deprecated (since 2.12.0), and it is strongly
199 #        recommended that you avoid using it. Use @query-cpus-fast to
200 #        obtain information about virtual CPUs.
201 #
202 ##
203 { 'command': 'query-cpus', 'returns': ['CpuInfo'] }
204
205 ##
206 # @CpuInfoFast:
207 #
208 # Information about a virtual CPU
209 #
210 # @cpu-index: index of the virtual CPU
211 #
212 # @qom-path: path to the CPU object in the QOM tree
213 #
214 # @thread-id: ID of the underlying host thread
215 #
216 # @props: properties describing to which node/socket/core/thread
217 #         virtual CPU belongs to, provided if supported by board
218 #
219 # @arch: base architecture of the cpu; deprecated since 3.0.0 in favor
220 #        of @target
221 #
222 # @target: the QEMU system emulation target, which determines which
223 #          additional fields will be listed (since 3.0)
224 #
225 # Since: 2.12
226 #
227 ##
228 { 'union'         : 'CpuInfoFast',
229   'base'          : { 'cpu-index'    : 'int',
230                       'qom-path'     : 'str',
231                       'thread-id'    : 'int',
232                       '*props'       : 'CpuInstanceProperties',
233                       'arch'         : 'CpuInfoArch',
234                       'target'       : 'SysEmuTarget' },
235   'discriminator' : 'target',
236   'data'          : { 's390x'        : 'CpuInfoS390' } }
237
238 ##
239 # @query-cpus-fast:
240 #
241 # Returns information about all virtual CPUs. This command does not
242 # incur a performance penalty and should be used in production
243 # instead of query-cpus.
244 #
245 # Returns: list of @CpuInfoFast
246 #
247 # Since: 2.12
248 #
249 # Example:
250 #
251 # -> { "execute": "query-cpus-fast" }
252 # <- { "return": [
253 #         {
254 #             "thread-id": 25627,
255 #             "props": {
256 #                 "core-id": 0,
257 #                 "thread-id": 0,
258 #                 "socket-id": 0
259 #             },
260 #             "qom-path": "/machine/unattached/device[0]",
261 #             "arch":"x86",
262 #             "target":"x86_64",
263 #             "cpu-index": 0
264 #         },
265 #         {
266 #             "thread-id": 25628,
267 #             "props": {
268 #                 "core-id": 0,
269 #                 "thread-id": 0,
270 #                 "socket-id": 1
271 #             },
272 #             "qom-path": "/machine/unattached/device[2]",
273 #             "arch":"x86",
274 #             "target":"x86_64",
275 #             "cpu-index": 1
276 #         }
277 #     ]
278 # }
279 ##
280 { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] }
281
282 ##
283 # @cpu-add:
284 #
285 # Adds CPU with specified ID.
286 #
287 # @id: ID of CPU to be created, valid values [0..max_cpus)
288 #
289 # Returns: Nothing on success
290 #
291 # Since: 1.5
292 #
293 # Note: This command is deprecated.  The `device_add` command should be
294 #       used instead.  See the `query-hotpluggable-cpus` command for
295 #       details.
296 #
297 # Example:
298 #
299 # -> { "execute": "cpu-add", "arguments": { "id": 2 } }
300 # <- { "return": {} }
301 #
302 ##
303 { 'command': 'cpu-add', 'data': {'id': 'int'} }
304
305 ##
306 # @MachineInfo:
307 #
308 # Information describing a machine.
309 #
310 # @name: the name of the machine
311 #
312 # @alias: an alias for the machine name
313 #
314 # @is-default: whether the machine is default
315 #
316 # @cpu-max: maximum number of CPUs supported by the machine type
317 #           (since 1.5.0)
318 #
319 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
320 #
321 # Since: 1.2.0
322 ##
323 { 'struct': 'MachineInfo',
324   'data': { 'name': 'str', '*alias': 'str',
325             '*is-default': 'bool', 'cpu-max': 'int',
326             'hotpluggable-cpus': 'bool'} }
327
328 ##
329 # @query-machines:
330 #
331 # Return a list of supported machines
332 #
333 # Returns: a list of MachineInfo
334 #
335 # Since: 1.2.0
336 ##
337 { 'command': 'query-machines', 'returns': ['MachineInfo'] }
338
339 ##
340 # @CurrentMachineParams:
341 #
342 # Information describing the running machine parameters.
343 #
344 # @wakeup-suspend-support: true if the machine supports wake up from
345 #                          suspend
346 #
347 # Since: 4.0
348 ##
349 { 'struct': 'CurrentMachineParams',
350   'data': { 'wakeup-suspend-support': 'bool'} }
351
352 ##
353 # @query-current-machine:
354 #
355 # Return information on the current virtual machine.
356 #
357 # Returns: CurrentMachineParams
358 #
359 # Since: 4.0
360 ##
361 { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
362
363 ##
364 # @NumaOptionsType:
365 #
366 # @node: NUMA nodes configuration
367 #
368 # @dist: NUMA distance configuration (since 2.10)
369 #
370 # @cpu: property based CPU(s) to node mapping (Since: 2.10)
371 #
372 # Since: 2.1
373 ##
374 { 'enum': 'NumaOptionsType',
375   'data': [ 'node', 'dist', 'cpu' ] }
376
377 ##
378 # @NumaOptions:
379 #
380 # A discriminated record of NUMA options. (for OptsVisitor)
381 #
382 # Since: 2.1
383 ##
384 { 'union': 'NumaOptions',
385   'base': { 'type': 'NumaOptionsType' },
386   'discriminator': 'type',
387   'data': {
388     'node': 'NumaNodeOptions',
389     'dist': 'NumaDistOptions',
390     'cpu': 'NumaCpuOptions' }}
391
392 ##
393 # @NumaNodeOptions:
394 #
395 # Create a guest NUMA node. (for OptsVisitor)
396 #
397 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
398 #
399 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin
400 #         if omitted)
401 #
402 # @mem: memory size of this node; mutually exclusive with @memdev.
403 #       Equally divide total memory among nodes if both @mem and @memdev are
404 #       omitted.
405 #
406 # @memdev: memory backend object.  If specified for one node,
407 #          it must be specified for all nodes.
408 #
409 # Since: 2.1
410 ##
411 { 'struct': 'NumaNodeOptions',
412   'data': {
413    '*nodeid': 'uint16',
414    '*cpus':   ['uint16'],
415    '*mem':    'size',
416    '*memdev': 'str' }}
417
418 ##
419 # @NumaDistOptions:
420 #
421 # Set the distance between 2 NUMA nodes.
422 #
423 # @src: source NUMA node.
424 #
425 # @dst: destination NUMA node.
426 #
427 # @val: NUMA distance from source node to destination node.
428 #       When a node is unreachable from another node, set the distance
429 #       between them to 255.
430 #
431 # Since: 2.10
432 ##
433 { 'struct': 'NumaDistOptions',
434   'data': {
435    'src': 'uint16',
436    'dst': 'uint16',
437    'val': 'uint8' }}
438
439 ##
440 # @X86CPURegister32:
441 #
442 # A X86 32-bit register
443 #
444 # Since: 1.5
445 ##
446 { 'enum': 'X86CPURegister32',
447   'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
448
449 ##
450 # @X86CPUFeatureWordInfo:
451 #
452 # Information about a X86 CPU feature word
453 #
454 # @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
455 #
456 # @cpuid-input-ecx: Input ECX value for CPUID instruction for that
457 #                   feature word
458 #
459 # @cpuid-register: Output register containing the feature bits
460 #
461 # @features: value of output register, containing the feature bits
462 #
463 # Since: 1.5
464 ##
465 { 'struct': 'X86CPUFeatureWordInfo',
466   'data': { 'cpuid-input-eax': 'int',
467             '*cpuid-input-ecx': 'int',
468             'cpuid-register': 'X86CPURegister32',
469             'features': 'int' } }
470
471 ##
472 # @DummyForceArrays:
473 #
474 # Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally
475 #
476 # Since: 2.5
477 ##
478 { 'struct': 'DummyForceArrays',
479   'data': { 'unused': ['X86CPUFeatureWordInfo'] } }
480
481 ##
482 # @NumaCpuOptions:
483 #
484 # Option "-numa cpu" overrides default cpu to node mapping.
485 # It accepts the same set of cpu properties as returned by
486 # query-hotpluggable-cpus[].props, where node-id could be used to
487 # override default node mapping.
488 #
489 # Since: 2.10
490 ##
491 { 'struct': 'NumaCpuOptions',
492    'base': 'CpuInstanceProperties',
493    'data' : {} }
494
495 ##
496 # @HostMemPolicy:
497 #
498 # Host memory policy types
499 #
500 # @default: restore default policy, remove any nondefault policy
501 #
502 # @preferred: set the preferred host nodes for allocation
503 #
504 # @bind: a strict policy that restricts memory allocation to the
505 #        host nodes specified
506 #
507 # @interleave: memory allocations are interleaved across the set
508 #              of host nodes specified
509 #
510 # Since: 2.1
511 ##
512 { 'enum': 'HostMemPolicy',
513   'data': [ 'default', 'preferred', 'bind', 'interleave' ] }
514
515 ##
516 # @Memdev:
517 #
518 # Information about memory backend
519 #
520 # @id: backend's ID if backend has 'id' property (since 2.9)
521 #
522 # @size: memory backend size
523 #
524 # @merge: enables or disables memory merge support
525 #
526 # @dump: includes memory backend's memory in a core dump or not
527 #
528 # @prealloc: enables or disables memory preallocation
529 #
530 # @host-nodes: host nodes for its memory policy
531 #
532 # @policy: memory policy of memory backend
533 #
534 # Since: 2.1
535 ##
536 { 'struct': 'Memdev',
537   'data': {
538     '*id':        'str',
539     'size':       'size',
540     'merge':      'bool',
541     'dump':       'bool',
542     'prealloc':   'bool',
543     'host-nodes': ['uint16'],
544     'policy':     'HostMemPolicy' }}
545
546 ##
547 # @query-memdev:
548 #
549 # Returns information for all memory backends.
550 #
551 # Returns: a list of @Memdev.
552 #
553 # Since: 2.1
554 #
555 # Example:
556 #
557 # -> { "execute": "query-memdev" }
558 # <- { "return": [
559 #        {
560 #          "id": "mem1",
561 #          "size": 536870912,
562 #          "merge": false,
563 #          "dump": true,
564 #          "prealloc": false,
565 #          "host-nodes": [0, 1],
566 #          "policy": "bind"
567 #        },
568 #        {
569 #          "size": 536870912,
570 #          "merge": false,
571 #          "dump": true,
572 #          "prealloc": true,
573 #          "host-nodes": [2, 3],
574 #          "policy": "preferred"
575 #        }
576 #      ]
577 #    }
578 #
579 ##
580 { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true }
581
582 ##
583 # @CpuInstanceProperties:
584 #
585 # List of properties to be used for hotplugging a CPU instance,
586 # it should be passed by management with device_add command when
587 # a CPU is being hotplugged.
588 #
589 # @node-id: NUMA node ID the CPU belongs to
590 # @socket-id: socket number within node/board the CPU belongs to
591 # @die-id: die number within node/board the CPU belongs to (Since 4.1)
592 # @core-id: core number within die the CPU belongs to# @thread-id: thread number within core the CPU belongs to
593 #
594 # Note: currently there are 5 properties that could be present
595 # but management should be prepared to pass through other
596 # properties with device_add command to allow for future
597 # interface extension. This also requires the filed names to be kept in
598 # sync with the properties passed to -device/device_add.
599 #
600 # Since: 2.7
601 ##
602 { 'struct': 'CpuInstanceProperties',
603   'data': { '*node-id': 'int',
604             '*socket-id': 'int',
605             '*die-id': 'int',
606             '*core-id': 'int',
607             '*thread-id': 'int'
608   }
609 }
610
611 ##
612 # @HotpluggableCPU:
613 #
614 # @type: CPU object type for usage with device_add command
615 # @props: list of properties to be used for hotplugging CPU
616 # @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
617 # @qom-path: link to existing CPU object if CPU is present or
618 #            omitted if CPU is not present.
619 #
620 # Since: 2.7
621 ##
622 { 'struct': 'HotpluggableCPU',
623   'data': { 'type': 'str',
624             'vcpus-count': 'int',
625             'props': 'CpuInstanceProperties',
626             '*qom-path': 'str'
627           }
628 }
629
630 ##
631 # @query-hotpluggable-cpus:
632 #
633 # TODO: Better documentation; currently there is none.
634 #
635 # Returns: a list of HotpluggableCPU objects.
636 #
637 # Since: 2.7
638 #
639 # Example:
640 #
641 # For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
642 #
643 # -> { "execute": "query-hotpluggable-cpus" }
644 # <- {"return": [
645 #      { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
646 #        "vcpus-count": 1 },
647 #      { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
648 #        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
649 #    ]}'
650 #
651 # For pc machine type started with -smp 1,maxcpus=2:
652 #
653 # -> { "execute": "query-hotpluggable-cpus" }
654 # <- {"return": [
655 #      {
656 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
657 #         "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
658 #      },
659 #      {
660 #         "qom-path": "/machine/unattached/device[0]",
661 #         "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
662 #         "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
663 #      }
664 #    ]}
665 #
666 # For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
667 # (Since: 2.11):
668 #
669 # -> { "execute": "query-hotpluggable-cpus" }
670 # <- {"return": [
671 #      {
672 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
673 #         "props": { "core-id": 1 }
674 #      },
675 #      {
676 #         "qom-path": "/machine/unattached/device[0]",
677 #         "type": "qemu-s390x-cpu", "vcpus-count": 1,
678 #         "props": { "core-id": 0 }
679 #      }
680 #    ]}
681 #
682 ##
683 { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'],
684              'allow-preconfig': true }
685
686 ##
687 # @set-numa-node:
688 #
689 # Runtime equivalent of '-numa' CLI option, available at
690 # preconfigure stage to configure numa mapping before initializing
691 # machine.
692 #
693 # Since 3.0
694 ##
695 { 'command': 'set-numa-node', 'boxed': true,
696   'data': 'NumaOptions',
697   'allow-preconfig': true
698 }