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.
11 # A CPU model consists of the name of a CPU definition, to which
12 # delta changes are applied (e.g. features added/removed). Most magic values
13 # that an architecture might require should be hidden behind the name.
14 # However, if required, architectures can expose relevant properties.
16 # @name: the name of the CPU definition the model is based on
17 # @props: a dictionary of QOM properties to be applied
21 { 'struct': 'CpuModelInfo',
22 'data': { 'name': 'str',
26 # @CpuModelExpansionType:
28 # An enumeration of CPU model expansion types.
30 # @static: Expand to a static CPU model, a combination of a static base
31 # model name and property delta changes. As the static base model will
32 # never change, the expanded CPU model will be the same, independent of
33 # QEMU version, machine type, machine options, and accelerator options.
34 # Therefore, the resulting model can be used by tooling without having
35 # to specify a compatibility machine - e.g. when displaying the "host"
36 # model. The @static CPU models are migration-safe.
38 # @full: Expand all properties. The produced model is not guaranteed to be
39 # migration-safe, but allows tooling to get an insight and work with
42 # Note: When a non-migration-safe CPU model is expanded in static mode, some
43 # features enabled by the CPU model may be omitted, because they can't be
44 # implemented by a static CPU model definition (e.g. cache info passthrough and
45 # PMU passthrough in x86). If you need an accurate representation of the
46 # features enabled by a non-migration-safe CPU model, use @full. If you need a
47 # static representation that will keep ABI compatibility even when changing QEMU
48 # version or machine-type, use @static (but keep in mind that some features may
53 { 'enum': 'CpuModelExpansionType',
54 'data': [ 'static', 'full' ] }
58 # @CpuModelCompareResult:
60 # An enumeration of CPU model comparison results. The result is usually
61 # calculated using e.g. CPU features or CPU generations.
63 # @incompatible: If model A is incompatible to model B, model A is not
64 # guaranteed to run where model B runs and the other way around.
66 # @identical: If model A is identical to model B, model A is guaranteed to run
67 # where model B runs and the other way around.
69 # @superset: If model A is a superset of model B, model B is guaranteed to run
70 # where model A runs. There are no guarantees about the other way.
72 # @subset: If model A is a subset of model B, model A is guaranteed to run
73 # where model B runs. There are no guarantees about the other way.
77 { 'enum': 'CpuModelCompareResult',
78 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
81 # @CpuModelBaselineInfo:
83 # The result of a CPU model baseline.
85 # @model: the baselined CpuModelInfo.
89 { 'struct': 'CpuModelBaselineInfo',
90 'data': { 'model': 'CpuModelInfo' },
91 'if': 'defined(TARGET_S390X)' }
94 # @CpuModelCompareInfo:
96 # The result of a CPU model comparison.
98 # @result: The result of the compare operation.
99 # @responsible-properties: List of properties that led to the comparison result
100 # not being identical.
102 # @responsible-properties is a list of QOM property names that led to
103 # both CPUs not being detected as identical. For identical models, this
105 # If a QOM property is read-only, that means there's no known way to make the
106 # CPU models identical. If the special property name "type" is included, the
107 # models are by definition not identical and cannot be made identical.
111 { 'struct': 'CpuModelCompareInfo',
112 'data': { 'result': 'CpuModelCompareResult',
113 'responsible-properties': ['str'] },
114 'if': 'defined(TARGET_S390X)' }
117 # @query-cpu-model-comparison:
119 # Compares two CPU models, returning how they compare in a specific
120 # configuration. The results indicates how both models compare regarding
121 # runnability. This result can be used by tooling to make decisions if a
122 # certain CPU model will run in a certain configuration or if a compatible
123 # CPU model has to be created by baselining.
125 # Usually, a CPU model is compared against the maximum possible CPU model
126 # of a certain configuration (e.g. the "host" model for KVM). If that CPU
127 # model is identical or a subset, it will run in that configuration.
129 # The result returned by this command may be affected by:
131 # * QEMU version: CPU models may look different depending on the QEMU version.
132 # (Except for CPU models reported as "static" in query-cpu-definitions.)
133 # * machine-type: CPU model may look different depending on the machine-type.
134 # (Except for CPU models reported as "static" in query-cpu-definitions.)
135 # * machine options (including accelerator): in some architectures, CPU models
136 # may look different depending on machine and accelerator options. (Except for
137 # CPU models reported as "static" in query-cpu-definitions.)
138 # * "-cpu" arguments and global properties: arguments to the -cpu option and
139 # global properties may affect expansion of CPU models. Using
140 # query-cpu-model-expansion while using these is not advised.
142 # Some architectures may not support comparing CPU models. s390x supports
143 # comparing CPU models.
145 # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
146 # not supported, if a model cannot be used, if a model contains
147 # an unknown cpu definition name, unknown properties or properties
150 # Note: this command isn't specific to s390x, but is only implemented
151 # on this architecture currently.
155 { 'command': 'query-cpu-model-comparison',
156 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
157 'returns': 'CpuModelCompareInfo',
158 'if': 'defined(TARGET_S390X)' }
161 # @query-cpu-model-baseline:
163 # Baseline two CPU models, creating a compatible third model. The created
164 # model will always be a static, migration-safe CPU model (see "static"
165 # CPU model expansion for details).
167 # This interface can be used by tooling to create a compatible CPU model out
168 # two CPU models. The created CPU model will be identical to or a subset of
169 # both CPU models when comparing them. Therefore, the created CPU model is
170 # guaranteed to run where the given CPU models run.
172 # The result returned by this command may be affected by:
174 # * QEMU version: CPU models may look different depending on the QEMU version.
175 # (Except for CPU models reported as "static" in query-cpu-definitions.)
176 # * machine-type: CPU model may look different depending on the machine-type.
177 # (Except for CPU models reported as "static" in query-cpu-definitions.)
178 # * machine options (including accelerator): in some architectures, CPU models
179 # may look different depending on machine and accelerator options. (Except for
180 # CPU models reported as "static" in query-cpu-definitions.)
181 # * "-cpu" arguments and global properties: arguments to the -cpu option and
182 # global properties may affect expansion of CPU models. Using
183 # query-cpu-model-expansion while using these is not advised.
185 # Some architectures may not support baselining CPU models. s390x supports
186 # baselining CPU models.
188 # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
189 # not supported, if a model cannot be used, if a model contains
190 # an unknown cpu definition name, unknown properties or properties
193 # Note: this command isn't specific to s390x, but is only implemented
194 # on this architecture currently.
198 { 'command': 'query-cpu-model-baseline',
199 'data': { 'modela': 'CpuModelInfo',
200 'modelb': 'CpuModelInfo' },
201 'returns': 'CpuModelBaselineInfo',
202 'if': 'defined(TARGET_S390X)' }
205 # @CpuModelExpansionInfo:
207 # The result of a cpu model expansion.
209 # @model: the expanded CpuModelInfo.
213 { 'struct': 'CpuModelExpansionInfo',
214 'data': { 'model': 'CpuModelInfo' },
215 'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
218 # @query-cpu-model-expansion:
220 # Expands a given CPU model (or a combination of CPU model + additional options)
221 # to different granularities, allowing tooling to get an understanding what a
222 # specific CPU model looks like in QEMU under a certain configuration.
224 # This interface can be used to query the "host" CPU model.
226 # The data returned by this command may be affected by:
228 # * QEMU version: CPU models may look different depending on the QEMU version.
229 # (Except for CPU models reported as "static" in query-cpu-definitions.)
230 # * machine-type: CPU model may look different depending on the machine-type.
231 # (Except for CPU models reported as "static" in query-cpu-definitions.)
232 # * machine options (including accelerator): in some architectures, CPU models
233 # may look different depending on machine and accelerator options. (Except for
234 # CPU models reported as "static" in query-cpu-definitions.)
235 # * "-cpu" arguments and global properties: arguments to the -cpu option and
236 # global properties may affect expansion of CPU models. Using
237 # query-cpu-model-expansion while using these is not advised.
239 # Some architectures may not support all expansion types. s390x supports
240 # "full" and "static". Arm only supports "full".
242 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
243 # not supported, if the model cannot be expanded, if the model contains
244 # an unknown CPU definition name, unknown properties or properties
245 # with a wrong type. Also returns an error if an expansion type is
250 { 'command': 'query-cpu-model-expansion',
251 'data': { 'type': 'CpuModelExpansionType',
252 'model': 'CpuModelInfo' },
253 'returns': 'CpuModelExpansionInfo',
254 'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
257 # @CpuDefinitionInfo:
259 # Virtual CPU definition.
261 # @name: the name of the CPU definition
263 # @migration-safe: whether a CPU definition can be safely used for
264 # migration in combination with a QEMU compatibility machine
265 # when migrating between different QEMU versions and between
266 # hosts with different sets of (hardware or software)
267 # capabilities. If not provided, information is not available
268 # and callers should not assume the CPU definition to be
269 # migration-safe. (since 2.8)
271 # @static: whether a CPU definition is static and will not change depending on
272 # QEMU version, machine type, machine options and accelerator options.
273 # A static model is always migration-safe. (since 2.8)
275 # @unavailable-features: List of properties that prevent
276 # the CPU model from running in the current
278 # @typename: Type name that can be used as argument to @device-list-properties,
279 # to introspect properties configurable using -cpu or -global.
282 # @alias-of: Name of CPU model this model is an alias for. The target of the
283 # CPU model alias may change depending on the machine type.
284 # Management software is supposed to translate CPU model aliases
285 # in the VM configuration, because aliases may stop being
286 # migration-safe in the future (since 4.1)
288 # @unavailable-features is a list of QOM property names that
289 # represent CPU model attributes that prevent the CPU from running.
290 # If the QOM property is read-only, that means there's no known
291 # way to make the CPU model run in the current host. Implementations
292 # that choose not to provide specific information return the
293 # property name "type".
294 # If the property is read-write, it means that it MAY be possible
295 # to run the CPU model in the current host if that property is
296 # changed. Management software can use it as hints to suggest or
297 # choose an alternative for the user, or just to generate meaningful
298 # error messages explaining why the CPU model can't be used.
299 # If @unavailable-features is an empty list, the CPU model is
300 # runnable using the current host and machine-type.
301 # If @unavailable-features is not present, runnability
302 # information for the CPU is not available.
306 { 'struct': 'CpuDefinitionInfo',
307 'data': { 'name': 'str',
308 '*migration-safe': 'bool',
310 '*unavailable-features': [ 'str' ],
312 '*alias-of' : 'str' },
313 'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }
316 # @query-cpu-definitions:
318 # Return a list of supported virtual CPU definitions
320 # Returns: a list of CpuDefInfo
324 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
325 'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }