qemu/qapi/machine-target.json

1 # -*- Mode: Python -*-
5 # See the COPYING file in the top-level directory.
7 { 'include': 'machine-common.json' }
12 # Virtual CPU model.
14 # A CPU model consists of the name of a CPU definition, to which delta
20 # @name: the name of the CPU definition the model is based on
33 # An enumeration of CPU model expansion types.
35 # @static: Expand to a static CPU model, a combination of a static
36 #     base model name and property delta changes.  As the static base
37 #     model will never change, the expanded CPU model will be the
40 #     model can be used by tooling without having to specify a
41 #     compatibility machine - e.g. when displaying the "host" model.
42 #     The @static CPU models are migration-safe.
44 # @full: Expand all properties.  The produced model is not guaranteed
45 #     to be migration-safe, but allows tooling to get an insight and
46 #     work with model details.
48 # .. note:: When a non-migration-safe CPU model is expanded in static
49 #    mode, some features enabled by the CPU model may be omitted,
50 #    because they can't be implemented by a static CPU model
53 #    enabled by a non-migration-safe CPU model, use @full.  If you
55 #    even when changing QEMU version or machine-type, use @static (but
60 { 'enum': 'CpuModelExpansionType',
66 # An enumeration of CPU model comparison results.  The result is
69 # @incompatible: If model A is incompatible to model B, model A is not
70 #     guaranteed to run where model B runs and the other way around.
72 # @identical: If model A is identical to model B, model A is
73 #     guaranteed to run where model B runs and the other way around.
75 # @superset: If model A is a superset of model B, model B is
76 #     guaranteed to run where model A runs.  There are no guarantees
79 # @subset: If model A is a subset of model B, model A is guaranteed to
80 #     run where model B runs.  There are no guarantees about the other
85 { 'enum': 'CpuModelCompareResult',
91 # The result of a CPU model baseline.
93 # @model: the baselined CpuModelInfo.
98   'data': { 'model': 'CpuModelInfo' },
104 # The result of a CPU model comparison.
108 # @responsible-properties: List of properties that led to the
111 # @responsible-properties is a list of QOM property names that led to
113 # this list is empty.  If a QOM property is read-only, that means
122             'responsible-properties': ['str'] },
126 # @query-cpu-model-comparison:
131 # used by tooling to make decisions if a certain CPU model will
132 # run in a certain configuration or if a compatible CPU model has
135 # Usually, a CPU model is compared against the maximum possible CPU
136 # model of a certain configuration (e.g. the "host" model for KVM).
137 # If that CPU model is identical or a subset, it will run in that
144 #   query-cpu-definitions.)
145 # * machine-type: CPU model may look different depending on the
146 #   machine-type.  (Except for CPU models reported as "static" in
147 #   query-cpu-definitions.)
151 #   query-cpu-definitions.)
152 # * "-cpu" arguments and global properties: arguments to the -cpu
154 #   Using query-cpu-model-expansion while using these is not advised.
159 # @modela: description of the first CPU model to compare, referred to
160 #     as "model A" in CpuModelCompareResult
162 # @modelb: description of the second CPU model to compare, referred to
163 #     as "model B" in CpuModelCompareResult
169 #     - if comparing CPU models is not supported
170 #     - if a model cannot be used
171 #     - if a model contains an unknown cpu definition name, unknown
179 { 'command': 'query-cpu-model-comparison',
185 # @query-cpu-model-baseline:
188 # third model.  The created model will always be a static,
189 # migration-safe CPU model (see "static" CPU model expansion for
193 # model out two CPU models.  The created CPU model will be identical
195 # the created CPU model is guaranteed to run where the given CPU
202 #   query-cpu-definitions.)
203 # * machine-type: CPU model may look different depending on the
204 #   machine-type.  (Except for CPU models reported as "static" in
205 #   query-cpu-definitions.)
209 #   query-cpu-definitions.)
210 # * "-cpu" arguments and global properties: arguments to the -cpu
212 #   Using query-cpu-model-expansion while using these is not advised.
217 # @modela: description of the first CPU model to baseline
219 # @modelb: description of the second CPU model to baseline
221 # Returns: a CpuModelBaselineInfo describing the baselined CPU model
224 #     - if baselining CPU models is not supported
225 #     - if a model cannot be used
226 #     - if a model contains an unknown cpu definition name, unknown
234 { 'command': 'query-cpu-model-baseline',
243 # The result of a cpu model expansion.
245 # @model: the expanded CpuModelInfo.
247 # @deprecated-props: a list of properties that are flagged as
250 #     enabled-properties for the expanded model; "full" properties are
257   'data': { 'model': 'CpuModelInfo',
258             'deprecated-props' : { 'type': ['str'],
267 # @query-cpu-model-expansion:
269 # Expands a given CPU model, @model, (or a combination of CPU model +
271 # allowing tooling to get an understanding what a specific CPU model
274 # This interface can be used to query the "host" CPU model.
280 #   query-cpu-definitions.)
281 # * machine-type: CPU model may look different depending on the
282 #   machine-type.  (Except for CPU models reported as "static" in
283 #   query-cpu-definitions.)
287 #   query-cpu-definitions.)
288 # * "-cpu" arguments and global properties: arguments to the -cpu
290 #   Using query-cpu-model-expansion while using these is not advised.
295 # @model: description of the CPU model to expand
297 # @type: expansion type, specifying how to expand the CPU model
299 # Returns: a CpuModelExpansionInfo describing the expanded CPU model
302 #     - if expanding CPU models is not supported
303 #     - if the model cannot be expanded
304 #     - if the model contains an unknown CPU definition name, unknown
306 #     - if an expansion type is not supported
310 { 'command': 'query-cpu-model-expansion',
312             'model': 'CpuModelInfo' },
327 # @migration-safe: whether a CPU definition can be safely used for
332 #     assume the CPU definition to be migration-safe.  (since 2.8)
336 #     accelerator options.  A static model is always migration-safe.
339 # @unavailable-features: List of properties that prevent the CPU model
343 #     @device-list-properties, to introspect properties configurable
344 #     using -cpu or -global.  (since 2.9)
346 # @alias-of: Name of CPU model this model is an alias for.  The target
347 #     of the CPU model alias may change depending on the machine type.
348 #     Management software is supposed to translate CPU model aliases
350 #     migration-safe in the future (since 4.1)
352 # @deprecated: If true, this CPU model is deprecated and may be
356 # @unavailable-features is a list of QOM property names that represent
357 # CPU model attributes that prevent the CPU from running.  If the QOM
358 # property is read-only, that means there's no known way to make the
359 # CPU model run in the current host.  Implementations that choose not
361 # the property is read-write, it means that it MAY be possible to run
362 # the CPU model in the current host if that property is changed.
365 # messages explaining why the CPU model can't be used.  If
366 # @unavailable-features is an empty list, the CPU model is runnable
367 # using the current host and machine-type.  If @unavailable-features
375             '*migration-safe': 'bool',
377             '*unavailable-features': [ 'str' ],
379             '*alias-of' : 'str',
390 # @query-cpu-definitions:
398 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
415 { 'enum': 'S390CpuPolarization',
421 # @set-cpu-topology:
427 # @core-id: the vCPU ID to be moved
429 # @socket-id: destination socket to move the vCPU to
431 # @book-id: destination book to move the vCPU to
433 # @drawer-id: destination drawer to move the vCPU to
446 { 'command': 'set-cpu-topology',
448       'core-id': 'uint16',
449       '*socket-id': 'uint16',
450       '*book-id': 'uint16',
451       '*drawer-id': 'uint16',
483 # .. qmp-example::
485 #     <- { "event": "CPU_POLARIZATION_CHANGE",
510 # @query-s390x-cpu-polarization:
520 { 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo',