]>
Commit | Line | Data |
---|---|---|
7f7b4e7a | 1 | # -*- Mode: Python -*- |
f7160f32 | 2 | # vim: filetype=python |
7f7b4e7a MA |
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 | # | |
9bc6e893 | 20 | # Since: 2.8 |
7f7b4e7a MA |
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 | |
26ec4e53 PM |
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). | |
7f7b4e7a | 51 | # |
9bc6e893 | 52 | # Since: 2.8 |
7f7b4e7a MA |
53 | ## |
54 | { 'enum': 'CpuModelExpansionType', | |
55 | 'data': [ 'static', 'full' ] } | |
56 | ||
7f7b4e7a MA |
57 | ## |
58 | # @CpuModelCompareResult: | |
59 | # | |
60 | # An enumeration of CPU model comparison results. The result is usually | |
61 | # calculated using e.g. CPU features or CPU generations. | |
62 | # | |
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. | |
65 | # | |
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. | |
68 | # | |
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. | |
71 | # | |
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. | |
74 | # | |
9bc6e893 | 75 | # Since: 2.8 |
7f7b4e7a MA |
76 | ## |
77 | { 'enum': 'CpuModelCompareResult', | |
78 | 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } | |
79 | ||
80 | ## | |
81 | # @CpuModelBaselineInfo: | |
82 | # | |
83 | # The result of a CPU model baseline. | |
84 | # | |
85 | # @model: the baselined CpuModelInfo. | |
86 | # | |
9bc6e893 | 87 | # Since: 2.8 |
7f7b4e7a MA |
88 | ## |
89 | { 'struct': 'CpuModelBaselineInfo', | |
90 | 'data': { 'model': 'CpuModelInfo' }, | |
8a9f1e1d | 91 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
92 | |
93 | ## | |
94 | # @CpuModelCompareInfo: | |
95 | # | |
96 | # The result of a CPU model comparison. | |
97 | # | |
98 | # @result: The result of the compare operation. | |
99 | # @responsible-properties: List of properties that led to the comparison result | |
100 | # not being identical. | |
101 | # | |
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 | |
104 | # list is empty. | |
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. | |
108 | # | |
9bc6e893 | 109 | # Since: 2.8 |
7f7b4e7a MA |
110 | ## |
111 | { 'struct': 'CpuModelCompareInfo', | |
112 | 'data': { 'result': 'CpuModelCompareResult', | |
113 | 'responsible-properties': ['str'] }, | |
8a9f1e1d | 114 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
115 | |
116 | ## | |
117 | # @query-cpu-model-comparison: | |
118 | # | |
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. | |
124 | # | |
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. | |
128 | # | |
129 | # The result returned by this command may be affected by: | |
130 | # | |
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. | |
141 | # | |
142 | # Some architectures may not support comparing CPU models. s390x supports | |
143 | # comparing CPU models. | |
144 | # | |
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 | |
148 | # with wrong types. | |
149 | # | |
150 | # Note: this command isn't specific to s390x, but is only implemented | |
26ec4e53 | 151 | # on this architecture currently. |
7f7b4e7a | 152 | # |
9bc6e893 | 153 | # Since: 2.8 |
7f7b4e7a MA |
154 | ## |
155 | { 'command': 'query-cpu-model-comparison', | |
156 | 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, | |
157 | 'returns': 'CpuModelCompareInfo', | |
8a9f1e1d | 158 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
159 | |
160 | ## | |
161 | # @query-cpu-model-baseline: | |
162 | # | |
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). | |
166 | # | |
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. | |
171 | # | |
172 | # The result returned by this command may be affected by: | |
173 | # | |
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. | |
184 | # | |
185 | # Some architectures may not support baselining CPU models. s390x supports | |
186 | # baselining CPU models. | |
187 | # | |
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 | |
191 | # with wrong types. | |
192 | # | |
193 | # Note: this command isn't specific to s390x, but is only implemented | |
26ec4e53 | 194 | # on this architecture currently. |
7f7b4e7a | 195 | # |
9bc6e893 | 196 | # Since: 2.8 |
7f7b4e7a MA |
197 | ## |
198 | { 'command': 'query-cpu-model-baseline', | |
199 | 'data': { 'modela': 'CpuModelInfo', | |
200 | 'modelb': 'CpuModelInfo' }, | |
201 | 'returns': 'CpuModelBaselineInfo', | |
8a9f1e1d | 202 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
203 | |
204 | ## | |
205 | # @CpuModelExpansionInfo: | |
206 | # | |
207 | # The result of a cpu model expansion. | |
208 | # | |
209 | # @model: the expanded CpuModelInfo. | |
210 | # | |
9bc6e893 | 211 | # Since: 2.8 |
7f7b4e7a MA |
212 | ## |
213 | { 'struct': 'CpuModelExpansionInfo', | |
214 | 'data': { 'model': 'CpuModelInfo' }, | |
8a9f1e1d MAL |
215 | 'if': { 'any': [ 'TARGET_S390X', |
216 | 'TARGET_I386', | |
217 | 'TARGET_ARM' ] } } | |
7f7b4e7a MA |
218 | |
219 | ## | |
220 | # @query-cpu-model-expansion: | |
221 | # | |
222 | # Expands a given CPU model (or a combination of CPU model + additional options) | |
223 | # to different granularities, allowing tooling to get an understanding what a | |
224 | # specific CPU model looks like in QEMU under a certain configuration. | |
225 | # | |
226 | # This interface can be used to query the "host" CPU model. | |
227 | # | |
228 | # The data returned by this command may be affected by: | |
229 | # | |
230 | # * QEMU version: CPU models may look different depending on the QEMU version. | |
231 | # (Except for CPU models reported as "static" in query-cpu-definitions.) | |
232 | # * machine-type: CPU model may look different depending on the machine-type. | |
233 | # (Except for CPU models reported as "static" in query-cpu-definitions.) | |
234 | # * machine options (including accelerator): in some architectures, CPU models | |
235 | # may look different depending on machine and accelerator options. (Except for | |
236 | # CPU models reported as "static" in query-cpu-definitions.) | |
237 | # * "-cpu" arguments and global properties: arguments to the -cpu option and | |
238 | # global properties may affect expansion of CPU models. Using | |
239 | # query-cpu-model-expansion while using these is not advised. | |
240 | # | |
241 | # Some architectures may not support all expansion types. s390x supports | |
e19afd56 | 242 | # "full" and "static". Arm only supports "full". |
7f7b4e7a MA |
243 | # |
244 | # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is | |
245 | # not supported, if the model cannot be expanded, if the model contains | |
246 | # an unknown CPU definition name, unknown properties or properties | |
247 | # with a wrong type. Also returns an error if an expansion type is | |
248 | # not supported. | |
249 | # | |
9bc6e893 | 250 | # Since: 2.8 |
7f7b4e7a MA |
251 | ## |
252 | { 'command': 'query-cpu-model-expansion', | |
253 | 'data': { 'type': 'CpuModelExpansionType', | |
254 | 'model': 'CpuModelInfo' }, | |
255 | 'returns': 'CpuModelExpansionInfo', | |
8a9f1e1d MAL |
256 | 'if': { 'any': [ 'TARGET_S390X', |
257 | 'TARGET_I386', | |
258 | 'TARGET_ARM' ] } } | |
7f7b4e7a MA |
259 | |
260 | ## | |
261 | # @CpuDefinitionInfo: | |
262 | # | |
263 | # Virtual CPU definition. | |
264 | # | |
265 | # @name: the name of the CPU definition | |
266 | # | |
267 | # @migration-safe: whether a CPU definition can be safely used for | |
268 | # migration in combination with a QEMU compatibility machine | |
269 | # when migrating between different QEMU versions and between | |
270 | # hosts with different sets of (hardware or software) | |
271 | # capabilities. If not provided, information is not available | |
272 | # and callers should not assume the CPU definition to be | |
273 | # migration-safe. (since 2.8) | |
274 | # | |
275 | # @static: whether a CPU definition is static and will not change depending on | |
276 | # QEMU version, machine type, machine options and accelerator options. | |
277 | # A static model is always migration-safe. (since 2.8) | |
278 | # | |
279 | # @unavailable-features: List of properties that prevent | |
280 | # the CPU model from running in the current | |
281 | # host. (since 2.8) | |
282 | # @typename: Type name that can be used as argument to @device-list-properties, | |
283 | # to introspect properties configurable using -cpu or -global. | |
284 | # (since 2.9) | |
285 | # | |
7d753f61 EH |
286 | # @alias-of: Name of CPU model this model is an alias for. The target of the |
287 | # CPU model alias may change depending on the machine type. | |
288 | # Management software is supposed to translate CPU model aliases | |
289 | # in the VM configuration, because aliases may stop being | |
290 | # migration-safe in the future (since 4.1) | |
291 | # | |
61ad65d0 RH |
292 | # @deprecated: If true, this CPU model is deprecated and may be removed in |
293 | # in some future version of QEMU according to the QEMU deprecation | |
294 | # policy. (since 5.2) | |
295 | # | |
7f7b4e7a MA |
296 | # @unavailable-features is a list of QOM property names that |
297 | # represent CPU model attributes that prevent the CPU from running. | |
298 | # If the QOM property is read-only, that means there's no known | |
299 | # way to make the CPU model run in the current host. Implementations | |
300 | # that choose not to provide specific information return the | |
301 | # property name "type". | |
302 | # If the property is read-write, it means that it MAY be possible | |
303 | # to run the CPU model in the current host if that property is | |
304 | # changed. Management software can use it as hints to suggest or | |
305 | # choose an alternative for the user, or just to generate meaningful | |
306 | # error messages explaining why the CPU model can't be used. | |
307 | # If @unavailable-features is an empty list, the CPU model is | |
308 | # runnable using the current host and machine-type. | |
309 | # If @unavailable-features is not present, runnability | |
310 | # information for the CPU is not available. | |
311 | # | |
9bc6e893 | 312 | # Since: 1.2 |
7f7b4e7a MA |
313 | ## |
314 | { 'struct': 'CpuDefinitionInfo', | |
315 | 'data': { 'name': 'str', | |
316 | '*migration-safe': 'bool', | |
317 | 'static': 'bool', | |
318 | '*unavailable-features': [ 'str' ], | |
7d753f61 | 319 | 'typename': 'str', |
61ad65d0 RH |
320 | '*alias-of' : 'str', |
321 | 'deprecated' : 'bool' }, | |
8a9f1e1d MAL |
322 | 'if': { 'any': [ 'TARGET_PPC', |
323 | 'TARGET_ARM', | |
324 | 'TARGET_I386', | |
325 | 'TARGET_S390X', | |
425876f5 XY |
326 | 'TARGET_MIPS', |
327 | 'TARGET_LOONGARCH64' ] } } | |
7f7b4e7a MA |
328 | |
329 | ## | |
330 | # @query-cpu-definitions: | |
331 | # | |
332 | # Return a list of supported virtual CPU definitions | |
333 | # | |
334 | # Returns: a list of CpuDefInfo | |
335 | # | |
9bc6e893 | 336 | # Since: 1.2 |
7f7b4e7a MA |
337 | ## |
338 | { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], | |
8a9f1e1d MAL |
339 | 'if': { 'any': [ 'TARGET_PPC', |
340 | 'TARGET_ARM', | |
341 | 'TARGET_I386', | |
342 | 'TARGET_S390X', | |
425876f5 XY |
343 | 'TARGET_MIPS', |
344 | 'TARGET_LOONGARCH64' ] } } |