aboutsummaryrefslogtreecommitdiff
path: root/qapi/machine-target.json
blob: afc8c408945c9e3c36e439eb307787e4bd0d8adf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
# -*- Mode: Python -*-
# vim: filetype=python
#
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.

##
# @CpuModelInfo:
#
# Virtual CPU model.
#
# A CPU model consists of the name of a CPU definition, to which
# delta changes are applied (e.g. features added/removed). Most magic values
# that an architecture might require should be hidden behind the name.
# However, if required, architectures can expose relevant properties.
#
# @name: the name of the CPU definition the model is based on
# @props: a dictionary of QOM properties to be applied
#
# Since: 2.8
##
{ 'struct': 'CpuModelInfo',
  'data': { 'name': 'str',
            '*props': 'any' } }

##
# @CpuModelExpansionType:
#
# An enumeration of CPU model expansion types.
#
# @static: Expand to a static CPU model, a combination of a static base
#          model name and property delta changes. As the static base model will
#          never change, the expanded CPU model will be the same, independent of
#          QEMU version, machine type, machine options, and accelerator options.
#          Therefore, the resulting model can be used by tooling without having
#          to specify a compatibility machine - e.g. when displaying the "host"
#          model. The @static CPU models are migration-safe.

# @full: Expand all properties. The produced model is not guaranteed to be
#        migration-safe, but allows tooling to get an insight and work with
#        model details.
#
# Note: When a non-migration-safe CPU model is expanded in static mode, some
#       features enabled by the CPU model may be omitted, because they can't be
#       implemented by a static CPU model definition (e.g. cache info passthrough and
#       PMU passthrough in x86). If you need an accurate representation of the
#       features enabled by a non-migration-safe CPU model, use @full. If you need a
#       static representation that will keep ABI compatibility even when changing QEMU
#       version or machine-type, use @static (but keep in mind that some features may
#       be omitted).
#
# Since: 2.8
##
{ 'enum': 'CpuModelExpansionType',
  'data': [ 'static', 'full' ] }

##
# @CpuModelCompareResult:
#
# An enumeration of CPU model comparison results. The result is usually
# calculated using e.g. CPU features or CPU generations.
#
# @incompatible: If model A is incompatible to model B, model A is not
#                guaranteed to run where model B runs and the other way around.
#
# @identical: If model A is identical to model B, model A is guaranteed to run
#             where model B runs and the other way around.
#
# @superset: If model A is a superset of model B, model B is guaranteed to run
#            where model A runs. There are no guarantees about the other way.
#
# @subset: If model A is a subset of model B, model A is guaranteed to run
#          where model B runs. There are no guarantees about the other way.
#
# Since: 2.8
##
{ 'enum': 'CpuModelCompareResult',
  'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }

##
# @CpuModelBaselineInfo:
#
# The result of a CPU model baseline.
#
# @model: the baselined CpuModelInfo.
#
# Since: 2.8
##
{ 'struct': 'CpuModelBaselineInfo',
  'data': { 'model': 'CpuModelInfo' },
  'if': 'TARGET_S390X' }

##
# @CpuModelCompareInfo:
#
# The result of a CPU model comparison.
#
# @result: The result of the compare operation.
# @responsible-properties: List of properties that led to the comparison result
#                          not being identical.
#
# @responsible-properties is a list of QOM property names that led to
# both CPUs not being detected as identical. For identical models, this
# list is empty.
# If a QOM property is read-only, that means there's no known way to make the
# CPU models identical. If the special property name "type" is included, the
# models are by definition not identical and cannot be made identical.
#
# Since: 2.8
##
{ 'struct': 'CpuModelCompareInfo',
  'data': { 'result': 'CpuModelCompareResult',
            'responsible-properties': ['str'] },
  'if': 'TARGET_S390X' }

##
# @query-cpu-model-comparison:
#
# Compares two CPU models, returning how they compare in a specific
# configuration. The results indicates how both models compare regarding
# runnability. This result can be used by tooling to make decisions if a
# certain CPU model will run in a certain configuration or if a compatible
# CPU model has to be created by baselining.
#
# Usually, a CPU model is compared against the maximum possible CPU model
# of a certain configuration (e.g. the "host" model for KVM). If that CPU
# model is identical or a subset, it will run in that configuration.
#
# The result returned by this command may be affected by:
#
# * QEMU version: CPU models may look different depending on the QEMU version.
#   (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the machine-type.
#   (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine options (including accelerator): in some architectures, CPU models
#   may look different depending on machine and accelerator options. (Except for
#   CPU models reported as "static" in query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu option and
#   global properties may affect expansion of CPU models. Using
#   query-cpu-model-expansion while using these is not advised.
#
# Some architectures may not support comparing CPU models. s390x supports
# comparing CPU models.
#
# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
#          not supported, if a model cannot be used, if a model contains
#          an unknown cpu definition name, unknown properties or properties
#          with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
#       on this architecture currently.
#
# Since: 2.8
##
{ 'command': 'query-cpu-model-comparison',
  'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
  'returns': 'CpuModelCompareInfo',
  'if': 'TARGET_S390X' }

##
# @query-cpu-model-baseline:
#
# Baseline two CPU models, creating a compatible third model. The created
# model will always be a static, migration-safe CPU model (see "static"
# CPU model expansion for details).
#
# This interface can be used by tooling to create a compatible CPU model out
# two CPU models. The created CPU model will be identical to or a subset of
# both CPU models when comparing them. Therefore, the created CPU model is
# guaranteed to run where the given CPU models run.
#
# The result returned by this command may be affected by:
#
# * QEMU version: CPU models may look different depending on the QEMU version.
#   (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine-type: CPU model may look different depending on the machine-type.
#   (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine options (including accelerator): in some architectures, CPU models
#   may look different depending on machine and accelerator options. (Except for
#   CPU models reported as "static" in query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu option and
#   global properties may affect expansion of CPU models. Using
#   query-cpu-model-expansion while using these is not advised.
#
# Some architectures may not support baselining CPU models. s390x supports
# baselining CPU models.
#
# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
#          not supported, if a model cannot be used, if a model contains
#          an unknown cpu definition name, unknown properties or properties
#          with wrong types.
#
# Note: this command isn't specific to s390x, but is only implemented
#       on this architecture currently.
#
# Since: 2.8
##
{ 'command': 'query-cpu-model-baseline',
  'data': { 'modela': 'CpuModelInfo',
            'modelb': 'CpuModelInfo' },
  'returns': 'CpuModelBaselineInfo',
  'if': 'TARGET_S390X' }

##
# @CpuModelExpansionInfo:
#
# The result of a cpu model expansion.
#
# @model: the expanded CpuModelInfo.
#
# Since: 2.8
##
{ 'struct': 'CpuModelExpansionInfo',
  'data': { 'model': 'CpuModelInfo' },
  'if': { 'any': [ 'TARGET_S390X',
                   'TARGET_I386',
                   'TARGET_ARM' ] } }

##
# @query-cpu-model-expansion:
#
# Expands a given CPU model (or a combination of CPU model + additional options)
# to different granularities, allowing tooling to get an understanding what a
# specific CPU model looks like in QEMU under a certain configuration.
#
# This interface can be used to query the "host" CPU model.
#
# The data returned by this command may be affected by:
#
# * QEMU version: CPU models may look different depending on the QEMU version.
#   (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine-type: CPU model  may look different depending on the machine-type.
#   (Except for CPU models reported as "static" in query-cpu-definitions.)
# * machine options (including accelerator): in some architectures, CPU models
#   may look different depending on machine and accelerator options. (Except for
#   CPU models reported as "static" in query-cpu-definitions.)
# * "-cpu" arguments and global properties: arguments to the -cpu option and
#   global properties may affect expansion of CPU models. Using
#   query-cpu-model-expansion while using these is not advised.
#
# Some architectures may not support all expansion types. s390x supports
# "full" and "static". Arm only supports "full".
#
# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
#          not supported, if the model cannot be expanded, if the model contains
#          an unknown CPU definition name, unknown properties or properties
#          with a wrong type. Also returns an error if an expansion type is
#          not supported.
#
# Since: 2.8
##
{ 'command': 'query-cpu-model-expansion',
  'data': { 'type': 'CpuModelExpansionType',
            'model': 'CpuModelInfo' },
  'returns': 'CpuModelExpansionInfo',
  'if': { 'any': [ 'TARGET_S390X',
                   'TARGET_I386',
                   'TARGET_ARM' ] } }

##
# @CpuDefinitionInfo:
#
# Virtual CPU definition.
#
# @name: the name of the CPU definition
#
# @migration-safe: whether a CPU definition can be safely used for
#                  migration in combination with a QEMU compatibility machine
#                  when migrating between different QEMU versions and between
#                  hosts with different sets of (hardware or software)
#                  capabilities. If not provided, information is not available
#                  and callers should not assume the CPU definition to be
#                  migration-safe. (since 2.8)
#
# @static: whether a CPU definition is static and will not change depending on
#          QEMU version, machine type, machine options and accelerator options.
#          A static model is always migration-safe. (since 2.8)
#
# @unavailable-features: List of properties that prevent
#                        the CPU model from running in the current
#                        host. (since 2.8)
# @typename: Type name that can be used as argument to @device-list-properties,
#            to introspect properties configurable using -cpu or -global.
#            (since 2.9)
#
# @alias-of: Name of CPU model this model is an alias for.  The target of the
#            CPU model alias may change depending on the machine type.
#            Management software is supposed to translate CPU model aliases
#            in the VM configuration, because aliases may stop being
#            migration-safe in the future (since 4.1)
#
# @deprecated: If true, this CPU model is deprecated and may be removed in
#              in some future version of QEMU according to the QEMU deprecation
#              policy. (since 5.2)
#
# @unavailable-features is a list of QOM property names that
# represent CPU model attributes that prevent the CPU from running.
# If the QOM property is read-only, that means there's no known
# way to make the CPU model run in the current host. Implementations
# that choose not to provide specific information return the
# property name "type".
# If the property is read-write, it means that it MAY be possible
# to run the CPU model in the current host if that property is
# changed. Management software can use it as hints to suggest or
# choose an alternative for the user, or just to generate meaningful
# error messages explaining why the CPU model can't be used.
# If @unavailable-features is an empty list, the CPU model is
# runnable using the current host and machine-type.
# If @unavailable-features is not present, runnability
# information for the CPU is not available.
#
# Since: 1.2
##
{ 'struct': 'CpuDefinitionInfo',
  'data': { 'name': 'str',
            '*migration-safe': 'bool',
            'static': 'bool',
            '*unavailable-features': [ 'str' ],
            'typename': 'str',
            '*alias-of' : 'str',
            'deprecated' : 'bool' },
  'if': { 'any': [ 'TARGET_PPC',
                   'TARGET_ARM',
                   'TARGET_I386',
                   'TARGET_S390X',
                   'TARGET_MIPS',
                   'TARGET_LOONGARCH64',
                   'TARGET_RISCV' ] } }

##
# @query-cpu-definitions:
#
# Return a list of supported virtual CPU definitions
#
# Returns: a list of CpuDefinitionInfo
#
# Since: 1.2
##
{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
  'if': { 'any': [ 'TARGET_PPC',
                   'TARGET_ARM',
                   'TARGET_I386',
                   'TARGET_S390X',
                   'TARGET_MIPS',
                   'TARGET_LOONGARCH64',
                   'TARGET_RISCV' ] } }