xref: /openbmc/qemu/qapi/machine-target.json (revision 7200fb21)
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{ 'include': 'machine-common.json' }
8
9##
10# @CpuModelInfo:
11#
12# Virtual CPU model.
13#
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
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
20#
21# @props: a dictionary of QOM properties to be applied
22#
23# Since: 2.8
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#
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).
56#
57# Since: 2.8
58##
59{ 'enum': 'CpuModelExpansionType',
60  'data': [ 'static', 'full' ] }
61
62##
63# @CpuModelCompareResult:
64#
65# An enumeration of CPU model comparison results.  The result is
66# usually calculated using e.g. CPU features or CPU generations.
67#
68# @incompatible: If model A is incompatible to model B, model A is not
69#     guaranteed to run where model B runs and the other way around.
70#
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.
73#
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.
77#
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.
81#
82# Since: 2.8
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#
94# Since: 2.8
95##
96{ 'struct': 'CpuModelBaselineInfo',
97  'data': { 'model': 'CpuModelInfo' },
98  'if': 'TARGET_S390X' }
99
100##
101# @CpuModelCompareInfo:
102#
103# The result of a CPU model comparison.
104#
105# @result: The result of the compare operation.
106#
107# @responsible-properties: List of properties that led to the
108#     comparison result not being identical.
109#
110# @responsible-properties is a list of QOM property names that led to
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.
116#
117# Since: 2.8
118##
119{ 'struct': 'CpuModelCompareInfo',
120  'data': { 'result': 'CpuModelCompareResult',
121            'responsible-properties': ['str'] },
122  'if': 'TARGET_S390X' }
123
124##
125# @query-cpu-model-comparison:
126#
127# Compares two CPU models, returning how they compare in a specific
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.
132#
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.
137#
138# The result returned by this command may be affected by:
139#
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.
161#
162# Note: this command isn't specific to s390x, but is only implemented
163#     on this architecture currently.
164#
165# Since: 2.8
166##
167{ 'command': 'query-cpu-model-comparison',
168  'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
169  'returns': 'CpuModelCompareInfo',
170  'if': 'TARGET_S390X' }
171
172##
173# @query-cpu-model-baseline:
174#
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).
178#
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.
184#
185# The result returned by this command may be affected by:
186#
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.
208#
209# Note: this command isn't specific to s390x, but is only implemented
210#     on this architecture currently.
211#
212# Since: 2.8
213##
214{ 'command': 'query-cpu-model-baseline',
215  'data': { 'modela': 'CpuModelInfo',
216            'modelb': 'CpuModelInfo' },
217  'returns': 'CpuModelBaselineInfo',
218  'if': 'TARGET_S390X' }
219
220##
221# @CpuModelExpansionInfo:
222#
223# The result of a cpu model expansion.
224#
225# @model: the expanded CpuModelInfo.
226#
227# Since: 2.8
228##
229{ 'struct': 'CpuModelExpansionInfo',
230  'data': { 'model': 'CpuModelInfo' },
231  'if': { 'any': [ 'TARGET_S390X',
232                   'TARGET_I386',
233                   'TARGET_ARM',
234                   'TARGET_LOONGARCH64',
235                   'TARGET_RISCV' ] } }
236
237##
238# @query-cpu-model-expansion:
239#
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.
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#
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.
271#
272# Since: 2.8
273##
274{ 'command': 'query-cpu-model-expansion',
275  'data': { 'type': 'CpuModelExpansionType',
276            'model': 'CpuModelInfo' },
277  'returns': 'CpuModelExpansionInfo',
278  'if': { 'any': [ 'TARGET_S390X',
279                   'TARGET_I386',
280                   'TARGET_ARM',
281                   'TARGET_LOONGARCH64',
282                   'TARGET_RISCV' ] } }
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
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.
334#
335# Since: 1.2
336##
337{ 'struct': 'CpuDefinitionInfo',
338  'data': { 'name': 'str',
339            '*migration-safe': 'bool',
340            'static': 'bool',
341            '*unavailable-features': [ 'str' ],
342            'typename': 'str',
343            '*alias-of' : 'str',
344            'deprecated' : 'bool' },
345  'if': { 'any': [ 'TARGET_PPC',
346                   'TARGET_ARM',
347                   'TARGET_I386',
348                   'TARGET_S390X',
349                   'TARGET_MIPS',
350                   'TARGET_LOONGARCH64',
351                   'TARGET_RISCV' ] } }
352
353##
354# @query-cpu-definitions:
355#
356# Return a list of supported virtual CPU definitions
357#
358# Returns: a list of CpuDefinitionInfo
359#
360# Since: 1.2
361##
362{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
363  'if': { 'any': [ 'TARGET_PPC',
364                   'TARGET_ARM',
365                   'TARGET_I386',
366                   'TARGET_S390X',
367                   'TARGET_MIPS',
368                   'TARGET_LOONGARCH64',
369                   'TARGET_RISCV' ] } }
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}
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}
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}
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}
489