Merge tag 'pull-sp-20240412' of https://gitlab.com/rth7680/qemu into staging
[qemu/armbru.git] / qapi / machine-target.json
blob29e695aa06c21e2bf3a1d679d39726f67b376169
1 # -*- Mode: Python -*-
2 # vim: filetype=python
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.
7 { 'include': 'machine-common.json' }
9 ##
10 # @CpuModelInfo:
12 # Virtual CPU model.
14 # A CPU model consists of the name of a CPU definition, to which delta
15 # changes are applied (e.g. features added/removed). Most magic values
16 # that an architecture might require should be hidden behind the name.
17 # However, if required, architectures can expose relevant properties.
19 # @name: the name of the CPU definition the model is based on
21 # @props: a dictionary of QOM properties to be applied
23 # Since: 2.8
25 { 'struct': 'CpuModelInfo',
26   'data': { 'name': 'str',
27             '*props': 'any' } }
30 # @CpuModelExpansionType:
32 # An enumeration of CPU model expansion types.
34 # @static: Expand to a static CPU model, a combination of a static
35 #     base model name and property delta changes.  As the static base
36 #     model will never change, the expanded CPU model will be the
37 #     same, independent of QEMU version, machine type, machine
38 #     options, and accelerator options.  Therefore, the resulting
39 #     model can be used by tooling without having to specify a
40 #     compatibility machine - e.g. when displaying the "host" model.
41 #     The @static CPU models are migration-safe.
43 # @full: Expand all properties.  The produced model is not guaranteed
44 #     to be migration-safe, but allows tooling to get an insight and
45 #     work with model details.
47 # Note: When a non-migration-safe CPU model is expanded in static
48 #     mode, some features enabled by the CPU model may be omitted,
49 #     because they can't be implemented by a static CPU model
50 #     definition (e.g. cache info passthrough and PMU passthrough in
51 #     x86). If you need an accurate representation of the features
52 #     enabled by a non-migration-safe CPU model, use @full.  If you
53 #     need a static representation that will keep ABI compatibility
54 #     even when changing QEMU version or machine-type, use @static
55 #     (but keep in mind that some features may be omitted).
57 # Since: 2.8
59 { 'enum': 'CpuModelExpansionType',
60   'data': [ 'static', 'full' ] }
63 # @CpuModelCompareResult:
65 # An enumeration of CPU model comparison results.  The result is
66 # usually calculated using e.g. CPU features or CPU generations.
68 # @incompatible: If model A is incompatible to model B, model A is not
69 #     guaranteed to run where model B runs and the other way around.
71 # @identical: If model A is identical to model B, model A is
72 #     guaranteed to run where model B runs and the other way around.
74 # @superset: If model A is a superset of model B, model B is
75 #     guaranteed to run where model A runs.  There are no guarantees
76 #     about the other way.
78 # @subset: If model A is a subset of model B, model A is guaranteed to
79 #     run where model B runs.  There are no guarantees about the other
80 #     way.
82 # Since: 2.8
84 { 'enum': 'CpuModelCompareResult',
85   'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
88 # @CpuModelBaselineInfo:
90 # The result of a CPU model baseline.
92 # @model: the baselined CpuModelInfo.
94 # Since: 2.8
96 { 'struct': 'CpuModelBaselineInfo',
97   'data': { 'model': 'CpuModelInfo' },
98   'if': 'TARGET_S390X' }
101 # @CpuModelCompareInfo:
103 # The result of a CPU model comparison.
105 # @result: The result of the compare operation.
107 # @responsible-properties: List of properties that led to the
108 #     comparison result not being identical.
110 # @responsible-properties is a list of QOM property names that led to
111 # both CPUs not being detected as identical.  For identical models,
112 # this list is empty.  If a QOM property is read-only, that means
113 # there's no known way to make the CPU models identical.  If the
114 # special property name "type" is included, the models are by
115 # definition not identical and cannot be made identical.
117 # Since: 2.8
119 { 'struct': 'CpuModelCompareInfo',
120   'data': { 'result': 'CpuModelCompareResult',
121             'responsible-properties': ['str'] },
122   'if': 'TARGET_S390X' }
125 # @query-cpu-model-comparison:
127 # Compares two CPU models, @modela and @modelb, returning how they
128 # compare in a specific configuration.  The results indicates how
129 # both models compare regarding runnability.  This result can be
130 # used by tooling to make decisions if a certain CPU model will
131 # run in a certain configuration or if a compatible CPU model has
132 # to be created by baselining.
134 # Usually, a CPU model is compared against the maximum possible CPU
135 # model of a certain configuration (e.g. the "host" model for KVM).
136 # If that CPU model is identical or a subset, it will run in that
137 # configuration.
139 # The result returned by this command may be affected by:
141 # * QEMU version: CPU models may look different depending on the QEMU
142 #   version.  (Except for CPU models reported as "static" in
143 #   query-cpu-definitions.)
144 # * machine-type: CPU model may look different depending on the
145 #   machine-type.  (Except for CPU models reported as "static" in
146 #   query-cpu-definitions.)
147 # * machine options (including accelerator): in some architectures,
148 #   CPU models may look different depending on machine and accelerator
149 #   options.  (Except for CPU models reported as "static" in
150 #   query-cpu-definitions.)
151 # * "-cpu" arguments and global properties: arguments to the -cpu
152 #   option and global properties may affect expansion of CPU models.
153 #   Using query-cpu-model-expansion while using these is not advised.
155 # Some architectures may not support comparing CPU models.  s390x
156 # supports comparing CPU models.
158 # @modela: description of the first CPU model to compare, referred to as
159 #     "model A" in CpuModelCompareResult
161 # @modelb: description of the second CPU model to compare, referred to as
162 #     "model B" in CpuModelCompareResult
164 # Returns: a CpuModelCompareInfo describing how both CPU models
165 #     compare
167 # Errors:
168 #     - if comparing CPU models is not supported
169 #     - if a model cannot be used
170 #     - if a model contains an unknown cpu definition name, unknown
171 #       properties or properties with wrong types.
173 # Note: this command isn't specific to s390x, but is only implemented
174 #     on this architecture currently.
176 # Since: 2.8
178 { 'command': 'query-cpu-model-comparison',
179   'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
180   'returns': 'CpuModelCompareInfo',
181   'if': 'TARGET_S390X' }
184 # @query-cpu-model-baseline:
186 # Baseline two CPU models, @modela and @modelb, creating a compatible
187 # third model.  The created model will always be a static,
188 # migration-safe CPU model (see "static" CPU model expansion for details).
190 # This interface can be used by tooling to create a compatible CPU
191 # model out two CPU models.  The created CPU model will be identical
192 # to or a subset of both CPU models when comparing them.  Therefore,
193 # the created CPU model is guaranteed to run where the given CPU
194 # models run.
196 # The result returned by this command may be affected by:
198 # * QEMU version: CPU models may look different depending on the QEMU
199 #   version.  (Except for CPU models reported as "static" in
200 #   query-cpu-definitions.)
201 # * machine-type: CPU model may look different depending on the
202 #   machine-type.  (Except for CPU models reported as "static" in
203 #   query-cpu-definitions.)
204 # * machine options (including accelerator): in some architectures,
205 #   CPU models may look different depending on machine and accelerator
206 #   options.  (Except for CPU models reported as "static" in
207 #   query-cpu-definitions.)
208 # * "-cpu" arguments and global properties: arguments to the -cpu
209 #   option and global properties may affect expansion of CPU models.
210 #   Using query-cpu-model-expansion while using these is not advised.
212 # Some architectures may not support baselining CPU models.  s390x
213 # supports baselining CPU models.
215 # @modela: description of the first CPU model to baseline
217 # @modelb: description of the second CPU model to baseline
219 # Returns: a CpuModelBaselineInfo describing the baselined CPU model
221 # Errors:
222 #     - if baselining CPU models is not supported
223 #     - if a model cannot be used
224 #     - if a model contains an unknown cpu definition name, unknown
225 #       properties or properties with wrong types.
227 # Note: this command isn't specific to s390x, but is only implemented
228 #     on this architecture currently.
230 # Since: 2.8
232 { 'command': 'query-cpu-model-baseline',
233   'data': { 'modela': 'CpuModelInfo',
234             'modelb': 'CpuModelInfo' },
235   'returns': 'CpuModelBaselineInfo',
236   'if': 'TARGET_S390X' }
239 # @CpuModelExpansionInfo:
241 # The result of a cpu model expansion.
243 # @model: the expanded CpuModelInfo.
245 # Since: 2.8
247 { 'struct': 'CpuModelExpansionInfo',
248   'data': { 'model': 'CpuModelInfo' },
249   'if': { 'any': [ 'TARGET_S390X',
250                    'TARGET_I386',
251                    'TARGET_ARM',
252                    'TARGET_LOONGARCH64',
253                    'TARGET_RISCV' ] } }
256 # @query-cpu-model-expansion:
258 # Expands a given CPU model, @model, (or a combination of CPU model +
259 # additional options) to different granularities, specified by
260 # @type, allowing tooling to get an understanding what a specific
261 # CPU model looks like in QEMU under a certain configuration.
263 # This interface can be used to query the "host" CPU model.
265 # The data returned by this command may be affected by:
267 # * QEMU version: CPU models may look different depending on the QEMU
268 #   version.  (Except for CPU models reported as "static" in
269 #   query-cpu-definitions.)
270 # * machine-type: CPU model may look different depending on the
271 #   machine-type.  (Except for CPU models reported as "static" in
272 #   query-cpu-definitions.)
273 # * machine options (including accelerator): in some architectures,
274 #   CPU models may look different depending on machine and accelerator
275 #   options.  (Except for CPU models reported as "static" in
276 #   query-cpu-definitions.)
277 # * "-cpu" arguments and global properties: arguments to the -cpu
278 #   option and global properties may affect expansion of CPU models.
279 #   Using query-cpu-model-expansion while using these is not advised.
281 # Some architectures may not support all expansion types.  s390x
282 # supports "full" and "static". Arm only supports "full".
284 # @model: description of the CPU model to expand
286 # @type: expansion type, specifying how to expand the CPU model
288 # Returns: a CpuModelExpansionInfo describing the expanded CPU model
290 # Errors:
291 #     - if expanding CPU models is not supported
292 #     - if the model cannot be expanded
293 #     - if the model contains an unknown CPU definition name, unknown
294 #       properties or properties with a wrong type
295 #     - if an expansion type is not supported
297 # Since: 2.8
299 { 'command': 'query-cpu-model-expansion',
300   'data': { 'type': 'CpuModelExpansionType',
301             'model': 'CpuModelInfo' },
302   'returns': 'CpuModelExpansionInfo',
303   'if': { 'any': [ 'TARGET_S390X',
304                    'TARGET_I386',
305                    'TARGET_ARM',
306                    'TARGET_LOONGARCH64',
307                    'TARGET_RISCV' ] } }
310 # @CpuDefinitionInfo:
312 # Virtual CPU definition.
314 # @name: the name of the CPU definition
316 # @migration-safe: whether a CPU definition can be safely used for
317 #     migration in combination with a QEMU compatibility machine when
318 #     migrating between different QEMU versions and between hosts with
319 #     different sets of (hardware or software) capabilities.  If not
320 #     provided, information is not available and callers should not
321 #     assume the CPU definition to be migration-safe.  (since 2.8)
323 # @static: whether a CPU definition is static and will not change
324 #     depending on QEMU version, machine type, machine options and
325 #     accelerator options.  A static model is always migration-safe.
326 #     (since 2.8)
328 # @unavailable-features: List of properties that prevent the CPU model
329 #     from running in the current host.  (since 2.8)
331 # @typename: Type name that can be used as argument to
332 #     @device-list-properties, to introspect properties configurable
333 #     using -cpu or -global.  (since 2.9)
335 # @alias-of: Name of CPU model this model is an alias for.  The target
336 #     of the CPU model alias may change depending on the machine type.
337 #     Management software is supposed to translate CPU model aliases
338 #     in the VM configuration, because aliases may stop being
339 #     migration-safe in the future (since 4.1)
341 # @deprecated: If true, this CPU model is deprecated and may be
342 #     removed in in some future version of QEMU according to the QEMU
343 #     deprecation policy.  (since 5.2)
345 # @unavailable-features is a list of QOM property names that represent
346 # CPU model attributes that prevent the CPU from running.  If the QOM
347 # property is read-only, that means there's no known way to make the
348 # CPU model run in the current host.  Implementations that choose not
349 # to provide specific information return the property name "type". If
350 # the property is read-write, it means that it MAY be possible to run
351 # the CPU model in the current host if that property is changed.
352 # Management software can use it as hints to suggest or choose an
353 # alternative for the user, or just to generate meaningful error
354 # messages explaining why the CPU model can't be used.  If
355 # @unavailable-features is an empty list, the CPU model is runnable
356 # using the current host and machine-type.  If @unavailable-features
357 # is not present, runnability information for the CPU is not
358 # available.
360 # Since: 1.2
362 { 'struct': 'CpuDefinitionInfo',
363   'data': { 'name': 'str',
364             '*migration-safe': 'bool',
365             'static': 'bool',
366             '*unavailable-features': [ 'str' ],
367             'typename': 'str',
368             '*alias-of' : 'str',
369             'deprecated' : 'bool' },
370   'if': { 'any': [ 'TARGET_PPC',
371                    'TARGET_ARM',
372                    'TARGET_I386',
373                    'TARGET_S390X',
374                    'TARGET_MIPS',
375                    'TARGET_LOONGARCH64',
376                    'TARGET_RISCV' ] } }
379 # @query-cpu-definitions:
381 # Return a list of supported virtual CPU definitions
383 # Returns: a list of CpuDefinitionInfo
385 # Since: 1.2
387 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
388   'if': { 'any': [ 'TARGET_PPC',
389                    'TARGET_ARM',
390                    'TARGET_I386',
391                    'TARGET_S390X',
392                    'TARGET_MIPS',
393                    'TARGET_LOONGARCH64',
394                    'TARGET_RISCV' ] } }
397 # @CpuS390Polarization:
399 # An enumeration of CPU polarization that can be assumed by a virtual
400 # S390 CPU
402 # Since: 8.2
404 { 'enum': 'CpuS390Polarization',
405   'prefix': 'S390_CPU_POLARIZATION',
406   'data': [ 'horizontal', 'vertical' ],
407   'if': 'TARGET_S390X'
411 # @set-cpu-topology:
413 # Modify the topology by moving the CPU inside the topology tree, or
414 # by changing a modifier attribute of a CPU.  Absent values will not
415 # be modified.
417 # @core-id: the vCPU ID to be moved
419 # @socket-id: destination socket to move the vCPU to
421 # @book-id: destination book to move the vCPU to
423 # @drawer-id: destination drawer to move the vCPU to
425 # @entitlement: entitlement to set
427 # @dedicated: whether the provisioning of real to virtual CPU is
428 #     dedicated
430 # Features:
432 # @unstable: This command is experimental.
434 # Since: 8.2
436 { 'command': 'set-cpu-topology',
437   'data': {
438       'core-id': 'uint16',
439       '*socket-id': 'uint16',
440       '*book-id': 'uint16',
441       '*drawer-id': 'uint16',
442       '*entitlement': 'CpuS390Entitlement',
443       '*dedicated': 'bool'
444   },
445   'features': [ 'unstable' ],
446   'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] }
450 # @CPU_POLARIZATION_CHANGE:
452 # Emitted when the guest asks to change the polarization.
454 # The guest can tell the host (via the PTF instruction) whether the
455 # CPUs should be provisioned using horizontal or vertical
456 # polarization.
458 # On horizontal polarization the host is expected to provision all
459 # vCPUs equally.
461 # On vertical polarization the host can provision each vCPU
462 # differently.  The guest will get information on the details of the
463 # provisioning the next time it uses the STSI(15) instruction.
465 # @polarization: polarization specified by the guest
467 # Features:
469 # @unstable: This event is experimental.
471 # Since: 8.2
473 # Example:
475 #     <- { "event": "CPU_POLARIZATION_CHANGE",
476 #          "data": { "polarization": "horizontal" },
477 #          "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
479 { 'event': 'CPU_POLARIZATION_CHANGE',
480   'data': { 'polarization': 'CpuS390Polarization' },
481   'features': [ 'unstable' ],
482   'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] }
486 # @CpuPolarizationInfo:
488 # The result of a CPU polarization query.
490 # @polarization: the CPU polarization
492 # Since: 8.2
494 { 'struct': 'CpuPolarizationInfo',
495   'data': { 'polarization': 'CpuS390Polarization' },
496   'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] }
500 # @query-s390x-cpu-polarization:
502 # Features:
504 # @unstable: This command is experimental.
506 # Returns: the machine's CPU polarization
508 # Since: 8.2
510 { 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo',
511   'features': [ 'unstable' ],
512   'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] }