Merge remote-tracking branch 'remotes/vivier2/tags/linux-user-for-6.2-pull-request...
[qemu.git] / qapi / machine-target.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
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.
6
7 ##
8 # @CpuModelInfo:
9 #
10 # Virtual CPU model.
11 #
12 # A CPU model consists of the name of a CPU definition, to which
13 # delta changes are applied (e.g. features added/removed). Most magic values
14 # that an architecture might require should be hidden behind the name.
15 # However, if required, architectures can expose relevant properties.
16 #
17 # @name: the name of the CPU definition the model is based on
18 # @props: a dictionary of QOM properties to be applied
19 #
20 # Since: 2.8
21 ##
22 { 'struct': 'CpuModelInfo',
23   'data': { 'name': 'str',
24             '*props': 'any' } }
25
26 ##
27 # @CpuModelExpansionType:
28 #
29 # An enumeration of CPU model expansion types.
30 #
31 # @static: Expand to a static CPU model, a combination of a static base
32 #          model name and property delta changes. As the static base model will
33 #          never change, the expanded CPU model will be the same, independent of
34 #          QEMU version, machine type, machine options, and accelerator options.
35 #          Therefore, the resulting model can be used by tooling without having
36 #          to specify a compatibility machine - e.g. when displaying the "host"
37 #          model. The @static CPU models are migration-safe.
38
39 # @full: Expand all properties. The produced model is not guaranteed to be
40 #        migration-safe, but allows tooling to get an insight and work with
41 #        model details.
42 #
43 # Note: When a non-migration-safe CPU model is expanded in static mode, some
44 #       features enabled by the CPU model may be omitted, because they can't be
45 #       implemented by a static CPU model definition (e.g. cache info passthrough and
46 #       PMU passthrough in x86). If you need an accurate representation of the
47 #       features enabled by a non-migration-safe CPU model, use @full. If you need a
48 #       static representation that will keep ABI compatibility even when changing QEMU
49 #       version or machine-type, use @static (but keep in mind that some features may
50 #       be omitted).
51 #
52 # Since: 2.8
53 ##
54 { 'enum': 'CpuModelExpansionType',
55   'data': [ 'static', 'full' ] }
56
57
58 ##
59 # @CpuModelCompareResult:
60 #
61 # An enumeration of CPU model comparison results. The result is usually
62 # calculated using e.g. CPU features or CPU generations.
63 #
64 # @incompatible: If model A is incompatible to model B, model A is not
65 #                guaranteed to run where model B runs and the other way around.
66 #
67 # @identical: If model A is identical to model B, model A is guaranteed to run
68 #             where model B runs and the other way around.
69 #
70 # @superset: If model A is a superset of model B, model B is guaranteed to run
71 #            where model A runs. There are no guarantees about the other way.
72 #
73 # @subset: If model A is a subset of model B, model A is guaranteed to run
74 #          where model B runs. There are no guarantees about the other way.
75 #
76 # Since: 2.8
77 ##
78 { 'enum': 'CpuModelCompareResult',
79   'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
80
81 ##
82 # @CpuModelBaselineInfo:
83 #
84 # The result of a CPU model baseline.
85 #
86 # @model: the baselined CpuModelInfo.
87 #
88 # Since: 2.8
89 ##
90 { 'struct': 'CpuModelBaselineInfo',
91   'data': { 'model': 'CpuModelInfo' },
92   'if': 'TARGET_S390X' }
93
94 ##
95 # @CpuModelCompareInfo:
96 #
97 # The result of a CPU model comparison.
98 #
99 # @result: The result of the compare operation.
100 # @responsible-properties: List of properties that led to the comparison result
101 #                          not being identical.
102 #
103 # @responsible-properties is a list of QOM property names that led to
104 # both CPUs not being detected as identical. For identical models, this
105 # list is empty.
106 # If a QOM property is read-only, that means there's no known way to make the
107 # CPU models identical. If the special property name "type" is included, the
108 # models are by definition not identical and cannot be made identical.
109 #
110 # Since: 2.8
111 ##
112 { 'struct': 'CpuModelCompareInfo',
113   'data': { 'result': 'CpuModelCompareResult',
114             'responsible-properties': ['str'] },
115   'if': 'TARGET_S390X' }
116
117 ##
118 # @query-cpu-model-comparison:
119 #
120 # Compares two CPU models, returning how they compare in a specific
121 # configuration. The results indicates how both models compare regarding
122 # runnability. This result can be used by tooling to make decisions if a
123 # certain CPU model will run in a certain configuration or if a compatible
124 # CPU model has to be created by baselining.
125 #
126 # Usually, a CPU model is compared against the maximum possible CPU model
127 # of a certain configuration (e.g. the "host" model for KVM). If that CPU
128 # model is identical or a subset, it will run in that configuration.
129 #
130 # The result returned by this command may be affected by:
131 #
132 # * QEMU version: CPU models may look different depending on the QEMU version.
133 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
134 # * machine-type: CPU model may look different depending on the machine-type.
135 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
136 # * machine options (including accelerator): in some architectures, CPU models
137 #   may look different depending on machine and accelerator options. (Except for
138 #   CPU models reported as "static" in query-cpu-definitions.)
139 # * "-cpu" arguments and global properties: arguments to the -cpu option and
140 #   global properties may affect expansion of CPU models. Using
141 #   query-cpu-model-expansion while using these is not advised.
142 #
143 # Some architectures may not support comparing CPU models. s390x supports
144 # comparing CPU models.
145 #
146 # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is
147 #          not supported, if a model cannot be used, if a model contains
148 #          an unknown cpu definition name, unknown properties or properties
149 #          with wrong types.
150 #
151 # Note: this command isn't specific to s390x, but is only implemented
152 #       on this architecture currently.
153 #
154 # Since: 2.8
155 ##
156 { 'command': 'query-cpu-model-comparison',
157   'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
158   'returns': 'CpuModelCompareInfo',
159   'if': 'TARGET_S390X' }
160
161 ##
162 # @query-cpu-model-baseline:
163 #
164 # Baseline two CPU models, creating a compatible third model. The created
165 # model will always be a static, migration-safe CPU model (see "static"
166 # CPU model expansion for details).
167 #
168 # This interface can be used by tooling to create a compatible CPU model out
169 # two CPU models. The created CPU model will be identical to or a subset of
170 # both CPU models when comparing them. Therefore, the created CPU model is
171 # guaranteed to run where the given CPU models run.
172 #
173 # The result returned by this command may be affected by:
174 #
175 # * QEMU version: CPU models may look different depending on the QEMU version.
176 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
177 # * machine-type: CPU model may look different depending on the machine-type.
178 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
179 # * machine options (including accelerator): in some architectures, CPU models
180 #   may look different depending on machine and accelerator options. (Except for
181 #   CPU models reported as "static" in query-cpu-definitions.)
182 # * "-cpu" arguments and global properties: arguments to the -cpu option and
183 #   global properties may affect expansion of CPU models. Using
184 #   query-cpu-model-expansion while using these is not advised.
185 #
186 # Some architectures may not support baselining CPU models. s390x supports
187 # baselining CPU models.
188 #
189 # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is
190 #          not supported, if a model cannot be used, if a model contains
191 #          an unknown cpu definition name, unknown properties or properties
192 #          with wrong types.
193 #
194 # Note: this command isn't specific to s390x, but is only implemented
195 #       on this architecture currently.
196 #
197 # Since: 2.8
198 ##
199 { 'command': 'query-cpu-model-baseline',
200   'data': { 'modela': 'CpuModelInfo',
201             'modelb': 'CpuModelInfo' },
202   'returns': 'CpuModelBaselineInfo',
203   'if': 'TARGET_S390X' }
204
205 ##
206 # @CpuModelExpansionInfo:
207 #
208 # The result of a cpu model expansion.
209 #
210 # @model: the expanded CpuModelInfo.
211 #
212 # Since: 2.8
213 ##
214 { 'struct': 'CpuModelExpansionInfo',
215   'data': { 'model': 'CpuModelInfo' },
216   'if': { 'any': [ 'TARGET_S390X',
217                    'TARGET_I386',
218                    'TARGET_ARM' ] } }
219
220 ##
221 # @query-cpu-model-expansion:
222 #
223 # Expands a given CPU model (or a combination of CPU model + additional options)
224 # to different granularities, allowing tooling to get an understanding what a
225 # specific CPU model looks like in QEMU under a certain configuration.
226 #
227 # This interface can be used to query the "host" CPU model.
228 #
229 # The data returned by this command may be affected by:
230 #
231 # * QEMU version: CPU models may look different depending on the QEMU version.
232 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
233 # * machine-type: CPU model  may look different depending on the machine-type.
234 #   (Except for CPU models reported as "static" in query-cpu-definitions.)
235 # * machine options (including accelerator): in some architectures, CPU models
236 #   may look different depending on machine and accelerator options. (Except for
237 #   CPU models reported as "static" in query-cpu-definitions.)
238 # * "-cpu" arguments and global properties: arguments to the -cpu option and
239 #   global properties may affect expansion of CPU models. Using
240 #   query-cpu-model-expansion while using these is not advised.
241 #
242 # Some architectures may not support all expansion types. s390x supports
243 # "full" and "static". Arm only supports "full".
244 #
245 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is
246 #          not supported, if the model cannot be expanded, if the model contains
247 #          an unknown CPU definition name, unknown properties or properties
248 #          with a wrong type. Also returns an error if an expansion type is
249 #          not supported.
250 #
251 # Since: 2.8
252 ##
253 { 'command': 'query-cpu-model-expansion',
254   'data': { 'type': 'CpuModelExpansionType',
255             'model': 'CpuModelInfo' },
256   'returns': 'CpuModelExpansionInfo',
257   'if': { 'any': [ 'TARGET_S390X',
258                    'TARGET_I386',
259                    'TARGET_ARM' ] } }
260
261 ##
262 # @CpuDefinitionInfo:
263 #
264 # Virtual CPU definition.
265 #
266 # @name: the name of the CPU definition
267 #
268 # @migration-safe: whether a CPU definition can be safely used for
269 #                  migration in combination with a QEMU compatibility machine
270 #                  when migrating between different QEMU versions and between
271 #                  hosts with different sets of (hardware or software)
272 #                  capabilities. If not provided, information is not available
273 #                  and callers should not assume the CPU definition to be
274 #                  migration-safe. (since 2.8)
275 #
276 # @static: whether a CPU definition is static and will not change depending on
277 #          QEMU version, machine type, machine options and accelerator options.
278 #          A static model is always migration-safe. (since 2.8)
279 #
280 # @unavailable-features: List of properties that prevent
281 #                        the CPU model from running in the current
282 #                        host. (since 2.8)
283 # @typename: Type name that can be used as argument to @device-list-properties,
284 #            to introspect properties configurable using -cpu or -global.
285 #            (since 2.9)
286 #
287 # @alias-of: Name of CPU model this model is an alias for.  The target of the
288 #            CPU model alias may change depending on the machine type.
289 #            Management software is supposed to translate CPU model aliases
290 #            in the VM configuration, because aliases may stop being
291 #            migration-safe in the future (since 4.1)
292 #
293 # @deprecated: If true, this CPU model is deprecated and may be removed in
294 #              in some future version of QEMU according to the QEMU deprecation
295 #              policy. (since 5.2)
296 #
297 # @unavailable-features is a list of QOM property names that
298 # represent CPU model attributes that prevent the CPU from running.
299 # If the QOM property is read-only, that means there's no known
300 # way to make the CPU model run in the current host. Implementations
301 # that choose not to provide specific information return the
302 # property name "type".
303 # If the property is read-write, it means that it MAY be possible
304 # to run the CPU model in the current host if that property is
305 # changed. Management software can use it as hints to suggest or
306 # choose an alternative for the user, or just to generate meaningful
307 # error messages explaining why the CPU model can't be used.
308 # If @unavailable-features is an empty list, the CPU model is
309 # runnable using the current host and machine-type.
310 # If @unavailable-features is not present, runnability
311 # information for the CPU is not available.
312 #
313 # Since: 1.2
314 ##
315 { 'struct': 'CpuDefinitionInfo',
316   'data': { 'name': 'str',
317             '*migration-safe': 'bool',
318             'static': 'bool',
319             '*unavailable-features': [ 'str' ],
320             'typename': 'str',
321             '*alias-of' : 'str',
322             'deprecated' : 'bool' },
323   'if': { 'any': [ 'TARGET_PPC',
324                    'TARGET_ARM',
325                    'TARGET_I386',
326                    'TARGET_S390X',
327                    'TARGET_MIPS' ] } }
328
329 ##
330 # @query-cpu-definitions:
331 #
332 # Return a list of supported virtual CPU definitions
333 #
334 # Returns: a list of CpuDefInfo
335 #
336 # Since: 1.2
337 ##
338 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
339   'if': { 'any': [ 'TARGET_PPC',
340                    'TARGET_ARM',
341                    'TARGET_I386',
342                    'TARGET_S390X',
343                    'TARGET_MIPS' ] } }