]>
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 | ||
a457c2ab PM |
7 | { 'include': 'machine-common.json' } |
8 | ||
7f7b4e7a MA |
9 | ## |
10 | # @CpuModelInfo: | |
11 | # | |
12 | # Virtual CPU model. | |
13 | # | |
a937b6aa MA |
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 | |
7f7b4e7a MA |
16 | # that an architecture might require should be hidden behind the name. |
17 | # However, if required, architectures can expose relevant properties. | |
18 | # | |
19 | # @name: the name of the CPU definition the model is based on | |
a937b6aa | 20 | # |
7f7b4e7a MA |
21 | # @props: a dictionary of QOM properties to be applied |
22 | # | |
9bc6e893 | 23 | # Since: 2.8 |
7f7b4e7a MA |
24 | ## |
25 | { 'struct': 'CpuModelInfo', | |
26 | 'data': { 'name': 'str', | |
27 | '*props': 'any' } } | |
28 | ||
29 | ## | |
30 | # @CpuModelExpansionType: | |
31 | # | |
32 | # An enumeration of CPU model expansion types. | |
33 | # | |
a937b6aa MA |
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. | |
42 | # | |
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. | |
46 | # | |
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). | |
7f7b4e7a | 56 | # |
9bc6e893 | 57 | # Since: 2.8 |
7f7b4e7a MA |
58 | ## |
59 | { 'enum': 'CpuModelExpansionType', | |
60 | 'data': [ 'static', 'full' ] } | |
61 | ||
7f7b4e7a MA |
62 | ## |
63 | # @CpuModelCompareResult: | |
64 | # | |
a937b6aa | 65 | # An enumeration of CPU model comparison results. The result is |
9e272073 | 66 | # usually calculated using e.g. CPU features or CPU generations. |
7f7b4e7a MA |
67 | # |
68 | # @incompatible: If model A is incompatible to model B, model A is not | |
a937b6aa | 69 | # guaranteed to run where model B runs and the other way around. |
7f7b4e7a | 70 | # |
a937b6aa MA |
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. | |
7f7b4e7a | 73 | # |
a937b6aa MA |
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. | |
7f7b4e7a | 77 | # |
a937b6aa MA |
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. | |
7f7b4e7a | 81 | # |
9bc6e893 | 82 | # Since: 2.8 |
7f7b4e7a MA |
83 | ## |
84 | { 'enum': 'CpuModelCompareResult', | |
85 | 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } | |
86 | ||
87 | ## | |
88 | # @CpuModelBaselineInfo: | |
89 | # | |
90 | # The result of a CPU model baseline. | |
91 | # | |
92 | # @model: the baselined CpuModelInfo. | |
93 | # | |
9bc6e893 | 94 | # Since: 2.8 |
7f7b4e7a MA |
95 | ## |
96 | { 'struct': 'CpuModelBaselineInfo', | |
97 | 'data': { 'model': 'CpuModelInfo' }, | |
8a9f1e1d | 98 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
99 | |
100 | ## | |
101 | # @CpuModelCompareInfo: | |
102 | # | |
103 | # The result of a CPU model comparison. | |
104 | # | |
105 | # @result: The result of the compare operation. | |
a937b6aa MA |
106 | # |
107 | # @responsible-properties: List of properties that led to the | |
108 | # comparison result not being identical. | |
7f7b4e7a MA |
109 | # |
110 | # @responsible-properties is a list of QOM property names that led to | |
a937b6aa MA |
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. | |
7f7b4e7a | 116 | # |
9bc6e893 | 117 | # Since: 2.8 |
7f7b4e7a MA |
118 | ## |
119 | { 'struct': 'CpuModelCompareInfo', | |
120 | 'data': { 'result': 'CpuModelCompareResult', | |
121 | 'responsible-properties': ['str'] }, | |
8a9f1e1d | 122 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
123 | |
124 | ## | |
125 | # @query-cpu-model-comparison: | |
126 | # | |
127 | # Compares two CPU models, returning how they compare in a specific | |
a937b6aa MA |
128 | # configuration. The results indicates how both models compare |
129 | # regarding runnability. This result can be used by tooling to make | |
130 | # decisions if a certain CPU model will run in a certain configuration | |
131 | # or if a compatible CPU model has to be created by baselining. | |
7f7b4e7a | 132 | # |
a937b6aa MA |
133 | # Usually, a CPU model is compared against the maximum possible CPU |
134 | # model of a certain configuration (e.g. the "host" model for KVM). | |
135 | # If that CPU model is identical or a subset, it will run in that | |
136 | # configuration. | |
7f7b4e7a MA |
137 | # |
138 | # The result returned by this command may be affected by: | |
139 | # | |
a937b6aa MA |
140 | # * QEMU version: CPU models may look different depending on the QEMU |
141 | # version. (Except for CPU models reported as "static" in | |
142 | # query-cpu-definitions.) | |
143 | # * machine-type: CPU model may look different depending on the | |
144 | # machine-type. (Except for CPU models reported as "static" in | |
145 | # query-cpu-definitions.) | |
146 | # * machine options (including accelerator): in some architectures, | |
147 | # CPU models may look different depending on machine and accelerator | |
148 | # options. (Except for CPU models reported as "static" in | |
149 | # query-cpu-definitions.) | |
150 | # * "-cpu" arguments and global properties: arguments to the -cpu | |
151 | # option and global properties may affect expansion of CPU models. | |
152 | # Using query-cpu-model-expansion while using these is not advised. | |
153 | # | |
154 | # Some architectures may not support comparing CPU models. s390x | |
155 | # supports comparing CPU models. | |
156 | # | |
157 | # Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU | |
158 | # models is not supported, if a model cannot be used, if a model | |
159 | # contains an unknown cpu definition name, unknown properties or | |
160 | # properties with wrong types. | |
7f7b4e7a MA |
161 | # |
162 | # Note: this command isn't specific to s390x, but is only implemented | |
a937b6aa | 163 | # on this architecture currently. |
7f7b4e7a | 164 | # |
9bc6e893 | 165 | # Since: 2.8 |
7f7b4e7a MA |
166 | ## |
167 | { 'command': 'query-cpu-model-comparison', | |
168 | 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, | |
169 | 'returns': 'CpuModelCompareInfo', | |
8a9f1e1d | 170 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
171 | |
172 | ## | |
173 | # @query-cpu-model-baseline: | |
174 | # | |
a937b6aa MA |
175 | # Baseline two CPU models, creating a compatible third model. The |
176 | # created model will always be a static, migration-safe CPU model (see | |
177 | # "static" CPU model expansion for details). | |
7f7b4e7a | 178 | # |
a937b6aa MA |
179 | # This interface can be used by tooling to create a compatible CPU |
180 | # model out two CPU models. The created CPU model will be identical | |
181 | # to or a subset of both CPU models when comparing them. Therefore, | |
182 | # the created CPU model is guaranteed to run where the given CPU | |
183 | # models run. | |
7f7b4e7a MA |
184 | # |
185 | # The result returned by this command may be affected by: | |
186 | # | |
a937b6aa MA |
187 | # * QEMU version: CPU models may look different depending on the QEMU |
188 | # version. (Except for CPU models reported as "static" in | |
189 | # query-cpu-definitions.) | |
190 | # * machine-type: CPU model may look different depending on the | |
191 | # machine-type. (Except for CPU models reported as "static" in | |
192 | # query-cpu-definitions.) | |
193 | # * machine options (including accelerator): in some architectures, | |
194 | # CPU models may look different depending on machine and accelerator | |
195 | # options. (Except for CPU models reported as "static" in | |
196 | # query-cpu-definitions.) | |
197 | # * "-cpu" arguments and global properties: arguments to the -cpu | |
198 | # option and global properties may affect expansion of CPU models. | |
199 | # Using query-cpu-model-expansion while using these is not advised. | |
200 | # | |
201 | # Some architectures may not support baselining CPU models. s390x | |
202 | # supports baselining CPU models. | |
203 | # | |
204 | # Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU | |
205 | # models is not supported, if a model cannot be used, if a model | |
206 | # contains an unknown cpu definition name, unknown properties or | |
207 | # properties with wrong types. | |
7f7b4e7a MA |
208 | # |
209 | # Note: this command isn't specific to s390x, but is only implemented | |
a937b6aa | 210 | # on this architecture currently. |
7f7b4e7a | 211 | # |
9bc6e893 | 212 | # Since: 2.8 |
7f7b4e7a MA |
213 | ## |
214 | { 'command': 'query-cpu-model-baseline', | |
215 | 'data': { 'modela': 'CpuModelInfo', | |
216 | 'modelb': 'CpuModelInfo' }, | |
217 | 'returns': 'CpuModelBaselineInfo', | |
8a9f1e1d | 218 | 'if': 'TARGET_S390X' } |
7f7b4e7a MA |
219 | |
220 | ## | |
221 | # @CpuModelExpansionInfo: | |
222 | # | |
223 | # The result of a cpu model expansion. | |
224 | # | |
225 | # @model: the expanded CpuModelInfo. | |
226 | # | |
9bc6e893 | 227 | # Since: 2.8 |
7f7b4e7a MA |
228 | ## |
229 | { 'struct': 'CpuModelExpansionInfo', | |
230 | 'data': { 'model': 'CpuModelInfo' }, | |
8a9f1e1d MAL |
231 | 'if': { 'any': [ 'TARGET_S390X', |
232 | 'TARGET_I386', | |
31f694b9 | 233 | 'TARGET_ARM', |
aeb2bc59 DHB |
234 | 'TARGET_LOONGARCH64', |
235 | 'TARGET_RISCV' ] } } | |
7f7b4e7a MA |
236 | |
237 | ## | |
238 | # @query-cpu-model-expansion: | |
239 | # | |
a937b6aa MA |
240 | # Expands a given CPU model (or a combination of CPU model + |
241 | # additional options) to different granularities, allowing tooling to | |
242 | # get an understanding what a specific CPU model looks like in QEMU | |
243 | # under a certain configuration. | |
7f7b4e7a MA |
244 | # |
245 | # This interface can be used to query the "host" CPU model. | |
246 | # | |
247 | # The data returned by this command may be affected by: | |
248 | # | |
a937b6aa MA |
249 | # * QEMU version: CPU models may look different depending on the QEMU |
250 | # version. (Except for CPU models reported as "static" in | |
251 | # query-cpu-definitions.) | |
252 | # * machine-type: CPU model may look different depending on the | |
253 | # machine-type. (Except for CPU models reported as "static" in | |
254 | # query-cpu-definitions.) | |
255 | # * machine options (including accelerator): in some architectures, | |
256 | # CPU models may look different depending on machine and accelerator | |
257 | # options. (Except for CPU models reported as "static" in | |
258 | # query-cpu-definitions.) | |
259 | # * "-cpu" arguments and global properties: arguments to the -cpu | |
260 | # option and global properties may affect expansion of CPU models. | |
261 | # Using query-cpu-model-expansion while using these is not advised. | |
262 | # | |
263 | # Some architectures may not support all expansion types. s390x | |
264 | # supports "full" and "static". Arm only supports "full". | |
265 | # | |
266 | # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU | |
267 | # models is not supported, if the model cannot be expanded, if the | |
268 | # model contains an unknown CPU definition name, unknown | |
269 | # properties or properties with a wrong type. Also returns an | |
270 | # error if an expansion type is not supported. | |
7f7b4e7a | 271 | # |
9bc6e893 | 272 | # Since: 2.8 |
7f7b4e7a MA |
273 | ## |
274 | { 'command': 'query-cpu-model-expansion', | |
275 | 'data': { 'type': 'CpuModelExpansionType', | |
276 | 'model': 'CpuModelInfo' }, | |
277 | 'returns': 'CpuModelExpansionInfo', | |
8a9f1e1d MAL |
278 | 'if': { 'any': [ 'TARGET_S390X', |
279 | 'TARGET_I386', | |
31f694b9 | 280 | 'TARGET_ARM', |
aeb2bc59 DHB |
281 | 'TARGET_LOONGARCH64', |
282 | 'TARGET_RISCV' ] } } | |
7f7b4e7a MA |
283 | |
284 | ## | |
285 | # @CpuDefinitionInfo: | |
286 | # | |
287 | # Virtual CPU definition. | |
288 | # | |
289 | # @name: the name of the CPU definition | |
290 | # | |
291 | # @migration-safe: whether a CPU definition can be safely used for | |
a937b6aa MA |
292 | # migration in combination with a QEMU compatibility machine when |
293 | # migrating between different QEMU versions and between hosts with | |
294 | # different sets of (hardware or software) capabilities. If not | |
295 | # provided, information is not available and callers should not | |
296 | # assume the CPU definition to be migration-safe. (since 2.8) | |
297 | # | |
298 | # @static: whether a CPU definition is static and will not change | |
299 | # depending on QEMU version, machine type, machine options and | |
300 | # accelerator options. A static model is always migration-safe. | |
301 | # (since 2.8) | |
302 | # | |
303 | # @unavailable-features: List of properties that prevent the CPU model | |
304 | # from running in the current host. (since 2.8) | |
305 | # | |
306 | # @typename: Type name that can be used as argument to | |
307 | # @device-list-properties, to introspect properties configurable | |
308 | # using -cpu or -global. (since 2.9) | |
309 | # | |
310 | # @alias-of: Name of CPU model this model is an alias for. The target | |
311 | # of the CPU model alias may change depending on the machine type. | |
312 | # Management software is supposed to translate CPU model aliases | |
313 | # in the VM configuration, because aliases may stop being | |
314 | # migration-safe in the future (since 4.1) | |
315 | # | |
316 | # @deprecated: If true, this CPU model is deprecated and may be | |
317 | # removed in in some future version of QEMU according to the QEMU | |
318 | # deprecation policy. (since 5.2) | |
319 | # | |
320 | # @unavailable-features is a list of QOM property names that represent | |
321 | # CPU model attributes that prevent the CPU from running. If the QOM | |
322 | # property is read-only, that means there's no known way to make the | |
323 | # CPU model run in the current host. Implementations that choose not | |
324 | # to provide specific information return the property name "type". If | |
325 | # the property is read-write, it means that it MAY be possible to run | |
326 | # the CPU model in the current host if that property is changed. | |
327 | # Management software can use it as hints to suggest or choose an | |
328 | # alternative for the user, or just to generate meaningful error | |
329 | # messages explaining why the CPU model can't be used. If | |
330 | # @unavailable-features is an empty list, the CPU model is runnable | |
331 | # using the current host and machine-type. If @unavailable-features | |
332 | # is not present, runnability information for the CPU is not | |
333 | # available. | |
7f7b4e7a | 334 | # |
9bc6e893 | 335 | # Since: 1.2 |
7f7b4e7a MA |
336 | ## |
337 | { 'struct': 'CpuDefinitionInfo', | |
338 | 'data': { 'name': 'str', | |
339 | '*migration-safe': 'bool', | |
340 | 'static': 'bool', | |
341 | '*unavailable-features': [ 'str' ], | |
7d753f61 | 342 | 'typename': 'str', |
61ad65d0 RH |
343 | '*alias-of' : 'str', |
344 | 'deprecated' : 'bool' }, | |
8a9f1e1d MAL |
345 | 'if': { 'any': [ 'TARGET_PPC', |
346 | 'TARGET_ARM', | |
347 | 'TARGET_I386', | |
348 | 'TARGET_S390X', | |
425876f5 | 349 | 'TARGET_MIPS', |
c0177f91 DHB |
350 | 'TARGET_LOONGARCH64', |
351 | 'TARGET_RISCV' ] } } | |
7f7b4e7a MA |
352 | |
353 | ## | |
354 | # @query-cpu-definitions: | |
355 | # | |
356 | # Return a list of supported virtual CPU definitions | |
357 | # | |
d93ed1bd | 358 | # Returns: a list of CpuDefinitionInfo |
7f7b4e7a | 359 | # |
9bc6e893 | 360 | # Since: 1.2 |
7f7b4e7a MA |
361 | ## |
362 | { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], | |
8a9f1e1d MAL |
363 | 'if': { 'any': [ 'TARGET_PPC', |
364 | 'TARGET_ARM', | |
365 | 'TARGET_I386', | |
366 | 'TARGET_S390X', | |
425876f5 | 367 | 'TARGET_MIPS', |
c0177f91 DHB |
368 | 'TARGET_LOONGARCH64', |
369 | 'TARGET_RISCV' ] } } | |
f4f54b58 PM |
370 | |
371 | ## | |
372 | # @CpuS390Polarization: | |
373 | # | |
374 | # An enumeration of CPU polarization that can be assumed by a virtual | |
375 | # S390 CPU | |
376 | # | |
377 | # Since: 8.2 | |
378 | ## | |
379 | { 'enum': 'CpuS390Polarization', | |
380 | 'prefix': 'S390_CPU_POLARIZATION', | |
381 | 'data': [ 'horizontal', 'vertical' ], | |
382 | 'if': 'TARGET_S390X' | |
383 | } | |
a457c2ab PM |
384 | |
385 | ## | |
386 | # @set-cpu-topology: | |
387 | # | |
388 | # Modify the topology by moving the CPU inside the topology tree, | |
389 | # or by changing a modifier attribute of a CPU. | |
390 | # Absent values will not be modified. | |
391 | # | |
392 | # @core-id: the vCPU ID to be moved | |
393 | # | |
394 | # @socket-id: destination socket to move the vCPU to | |
395 | # | |
396 | # @book-id: destination book to move the vCPU to | |
397 | # | |
398 | # @drawer-id: destination drawer to move the vCPU to | |
399 | # | |
400 | # @entitlement: entitlement to set | |
401 | # | |
402 | # @dedicated: whether the provisioning of real to virtual CPU is dedicated | |
403 | # | |
404 | # Features: | |
405 | # | |
406 | # @unstable: This command is experimental. | |
407 | # | |
408 | # Returns: Nothing on success. | |
409 | # | |
410 | # Since: 8.2 | |
411 | ## | |
412 | { 'command': 'set-cpu-topology', | |
413 | 'data': { | |
414 | 'core-id': 'uint16', | |
415 | '*socket-id': 'uint16', | |
416 | '*book-id': 'uint16', | |
417 | '*drawer-id': 'uint16', | |
418 | '*entitlement': 'CpuS390Entitlement', | |
419 | '*dedicated': 'bool' | |
420 | }, | |
421 | 'features': [ 'unstable' ], | |
422 | 'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] } | |
423 | } | |
1cfe52b7 PM |
424 | |
425 | ## | |
426 | # @CPU_POLARIZATION_CHANGE: | |
427 | # | |
428 | # Emitted when the guest asks to change the polarization. | |
429 | # | |
430 | # The guest can tell the host (via the PTF instruction) whether the | |
431 | # CPUs should be provisioned using horizontal or vertical polarization. | |
432 | # | |
433 | # On horizontal polarization the host is expected to provision all vCPUs | |
434 | # equally. | |
435 | # | |
436 | # On vertical polarization the host can provision each vCPU differently. | |
437 | # The guest will get information on the details of the provisioning | |
438 | # the next time it uses the STSI(15) instruction. | |
439 | # | |
440 | # @polarization: polarization specified by the guest | |
441 | # | |
442 | # Features: | |
443 | # | |
444 | # @unstable: This event is experimental. | |
445 | # | |
446 | # Since: 8.2 | |
447 | # | |
448 | # Example: | |
449 | # | |
450 | # <- { "event": "CPU_POLARIZATION_CHANGE", | |
451 | # "data": { "polarization": "horizontal" }, | |
452 | # "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } | |
453 | ## | |
454 | { 'event': 'CPU_POLARIZATION_CHANGE', | |
455 | 'data': { 'polarization': 'CpuS390Polarization' }, | |
456 | 'features': [ 'unstable' ], | |
457 | 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } | |
458 | } | |
154893a7 PM |
459 | |
460 | ## | |
461 | # @CpuPolarizationInfo: | |
462 | # | |
463 | # The result of a CPU polarization query. | |
464 | # | |
465 | # @polarization: the CPU polarization | |
466 | # | |
467 | # Since: 8.2 | |
468 | ## | |
469 | { 'struct': 'CpuPolarizationInfo', | |
470 | 'data': { 'polarization': 'CpuS390Polarization' }, | |
471 | 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } | |
472 | } | |
473 | ||
474 | ## | |
475 | # @query-s390x-cpu-polarization: | |
476 | # | |
477 | # Features: | |
478 | # | |
479 | # @unstable: This command is experimental. | |
480 | # | |
481 | # Returns: the machine's CPU polarization | |
482 | # | |
483 | # Since: 8.2 | |
484 | ## | |
485 | { 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo', | |
486 | 'features': [ 'unstable' ], | |
487 | 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } | |
488 | } |