14b48aaab9
Use the no-option form of ".. qmp-example::" to convert any Examples
that do not have any form of caption or explanation whatsoever. Note
that in a few cases, example sections are split into two or more
separate example blocks. This is only done stylistically to create a
delineation between two or more logically independent examples.
See commit-3: "docs/qapidoc: create qmp-example directive", for a
detailed explanation of this custom directive syntax.
See commit+3: "qapi: remove "Example" doc section" for a detailed
explanation of why.
Note: an empty "TODO" line was added to announce-self to keep the
example from floating up into the body; this will be addressed more
rigorously in the new qapidoc generator.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-7-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Markup fixed in one place]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
519 lines
17 KiB
Python
519 lines
17 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2 or later.
|
|
# See the COPYING file in the top-level directory.
|
|
|
|
{ 'include': 'machine-common.json' }
|
|
|
|
##
|
|
# @CpuModelInfo:
|
|
#
|
|
# Virtual CPU model.
|
|
#
|
|
# A CPU model consists of the name of a CPU definition, to which delta
|
|
# changes are applied (e.g. features added/removed). Most magic values
|
|
# that an architecture might require should be hidden behind the name.
|
|
# However, if required, architectures can expose relevant properties.
|
|
#
|
|
# @name: the name of the CPU definition the model is based on
|
|
#
|
|
# @props: a dictionary of QOM properties to be applied
|
|
#
|
|
# @deprecated-props: a list of properties that are flagged as deprecated
|
|
# by the CPU vendor. These props are a subset of the full model's
|
|
# definition list of properties. (since 9.1)
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'struct': 'CpuModelInfo',
|
|
'data': { 'name': 'str',
|
|
'*props': 'any',
|
|
'*deprecated-props': ['str'] } }
|
|
|
|
##
|
|
# @CpuModelExpansionType:
|
|
#
|
|
# An enumeration of CPU model expansion types.
|
|
#
|
|
# @static: Expand to a static CPU model, a combination of a static
|
|
# base model name and property delta changes. As the static base
|
|
# model will never change, the expanded CPU model will be the
|
|
# same, independent of QEMU version, machine type, machine
|
|
# options, and accelerator options. Therefore, the resulting
|
|
# model can be used by tooling without having to specify a
|
|
# compatibility machine - e.g. when displaying the "host" model.
|
|
# The @static CPU models are migration-safe.
|
|
#
|
|
# @full: Expand all properties. The produced model is not guaranteed
|
|
# to be migration-safe, but allows tooling to get an insight and
|
|
# work with model details.
|
|
#
|
|
# .. note:: When a non-migration-safe CPU model is expanded in static
|
|
# mode, some features enabled by the CPU model may be omitted,
|
|
# because they can't be implemented by a static CPU model definition
|
|
# (e.g. cache info passthrough and PMU passthrough in x86). If you
|
|
# need an accurate representation of the features enabled by a
|
|
# non-migration-safe CPU model, use @full. If you need a static
|
|
# representation that will keep ABI compatibility even when changing
|
|
# QEMU version or machine-type, use @static (but keep in mind that
|
|
# some features may be omitted).
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'enum': 'CpuModelExpansionType',
|
|
'data': [ 'static', 'full' ] }
|
|
|
|
##
|
|
# @CpuModelCompareResult:
|
|
#
|
|
# An enumeration of CPU model comparison results. The result is
|
|
# usually calculated using e.g. CPU features or CPU generations.
|
|
#
|
|
# @incompatible: If model A is incompatible to model B, model A is not
|
|
# guaranteed to run where model B runs and the other way around.
|
|
#
|
|
# @identical: If model A is identical to model B, model A is
|
|
# guaranteed to run where model B runs and the other way around.
|
|
#
|
|
# @superset: If model A is a superset of model B, model B is
|
|
# guaranteed to run where model A runs. There are no guarantees
|
|
# about the other way.
|
|
#
|
|
# @subset: If model A is a subset of model B, model A is guaranteed to
|
|
# run where model B runs. There are no guarantees about the other
|
|
# way.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'enum': 'CpuModelCompareResult',
|
|
'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
|
|
|
|
##
|
|
# @CpuModelBaselineInfo:
|
|
#
|
|
# The result of a CPU model baseline.
|
|
#
|
|
# @model: the baselined CpuModelInfo.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'struct': 'CpuModelBaselineInfo',
|
|
'data': { 'model': 'CpuModelInfo' },
|
|
'if': 'TARGET_S390X' }
|
|
|
|
##
|
|
# @CpuModelCompareInfo:
|
|
#
|
|
# The result of a CPU model comparison.
|
|
#
|
|
# @result: The result of the compare operation.
|
|
#
|
|
# @responsible-properties: List of properties that led to the
|
|
# comparison result not being identical.
|
|
#
|
|
# @responsible-properties is a list of QOM property names that led to
|
|
# both CPUs not being detected as identical. For identical models,
|
|
# this list is empty. If a QOM property is read-only, that means
|
|
# there's no known way to make the CPU models identical. If the
|
|
# special property name "type" is included, the models are by
|
|
# definition not identical and cannot be made identical.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'struct': 'CpuModelCompareInfo',
|
|
'data': { 'result': 'CpuModelCompareResult',
|
|
'responsible-properties': ['str'] },
|
|
'if': 'TARGET_S390X' }
|
|
|
|
##
|
|
# @query-cpu-model-comparison:
|
|
#
|
|
# Compares two CPU models, @modela and @modelb, returning how they
|
|
# compare in a specific configuration. The results indicates how
|
|
# both models compare regarding runnability. This result can be
|
|
# used by tooling to make decisions if a certain CPU model will
|
|
# run in a certain configuration or if a compatible CPU model has
|
|
# to be created by baselining.
|
|
#
|
|
# Usually, a CPU model is compared against the maximum possible CPU
|
|
# model of a certain configuration (e.g. the "host" model for KVM).
|
|
# If that CPU model is identical or a subset, it will run in that
|
|
# configuration.
|
|
#
|
|
# The result returned by this command may be affected by:
|
|
#
|
|
# * QEMU version: CPU models may look different depending on the QEMU
|
|
# version. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * machine-type: CPU model may look different depending on the
|
|
# machine-type. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * machine options (including accelerator): in some architectures,
|
|
# CPU models may look different depending on machine and accelerator
|
|
# options. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * "-cpu" arguments and global properties: arguments to the -cpu
|
|
# option and global properties may affect expansion of CPU models.
|
|
# Using query-cpu-model-expansion while using these is not advised.
|
|
#
|
|
# Some architectures may not support comparing CPU models. s390x
|
|
# supports comparing CPU models.
|
|
#
|
|
# @modela: description of the first CPU model to compare, referred to as
|
|
# "model A" in CpuModelCompareResult
|
|
#
|
|
# @modelb: description of the second CPU model to compare, referred to as
|
|
# "model B" in CpuModelCompareResult
|
|
#
|
|
# Returns: a CpuModelCompareInfo describing how both CPU models
|
|
# compare
|
|
#
|
|
# Errors:
|
|
# - if comparing CPU models is not supported
|
|
# - if a model cannot be used
|
|
# - if a model contains an unknown cpu definition name, unknown
|
|
# properties or properties with wrong types.
|
|
#
|
|
# .. note:: This command isn't specific to s390x, but is only
|
|
# implemented on this architecture currently.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'command': 'query-cpu-model-comparison',
|
|
'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
|
|
'returns': 'CpuModelCompareInfo',
|
|
'if': 'TARGET_S390X' }
|
|
|
|
##
|
|
# @query-cpu-model-baseline:
|
|
#
|
|
# Baseline two CPU models, @modela and @modelb, creating a compatible
|
|
# third model. The created model will always be a static,
|
|
# migration-safe CPU model (see "static" CPU model expansion for details).
|
|
#
|
|
# This interface can be used by tooling to create a compatible CPU
|
|
# model out two CPU models. The created CPU model will be identical
|
|
# to or a subset of both CPU models when comparing them. Therefore,
|
|
# the created CPU model is guaranteed to run where the given CPU
|
|
# models run.
|
|
#
|
|
# The result returned by this command may be affected by:
|
|
#
|
|
# * QEMU version: CPU models may look different depending on the QEMU
|
|
# version. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * machine-type: CPU model may look different depending on the
|
|
# machine-type. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * machine options (including accelerator): in some architectures,
|
|
# CPU models may look different depending on machine and accelerator
|
|
# options. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * "-cpu" arguments and global properties: arguments to the -cpu
|
|
# option and global properties may affect expansion of CPU models.
|
|
# Using query-cpu-model-expansion while using these is not advised.
|
|
#
|
|
# Some architectures may not support baselining CPU models. s390x
|
|
# supports baselining CPU models.
|
|
#
|
|
# @modela: description of the first CPU model to baseline
|
|
#
|
|
# @modelb: description of the second CPU model to baseline
|
|
#
|
|
# Returns: a CpuModelBaselineInfo describing the baselined CPU model
|
|
#
|
|
# Errors:
|
|
# - if baselining CPU models is not supported
|
|
# - if a model cannot be used
|
|
# - if a model contains an unknown cpu definition name, unknown
|
|
# properties or properties with wrong types.
|
|
#
|
|
# .. note:: This command isn't specific to s390x, but is only
|
|
# implemented on this architecture currently.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'command': 'query-cpu-model-baseline',
|
|
'data': { 'modela': 'CpuModelInfo',
|
|
'modelb': 'CpuModelInfo' },
|
|
'returns': 'CpuModelBaselineInfo',
|
|
'if': 'TARGET_S390X' }
|
|
|
|
##
|
|
# @CpuModelExpansionInfo:
|
|
#
|
|
# The result of a cpu model expansion.
|
|
#
|
|
# @model: the expanded CpuModelInfo.
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'struct': 'CpuModelExpansionInfo',
|
|
'data': { 'model': 'CpuModelInfo' },
|
|
'if': { 'any': [ 'TARGET_S390X',
|
|
'TARGET_I386',
|
|
'TARGET_ARM',
|
|
'TARGET_LOONGARCH64',
|
|
'TARGET_RISCV' ] } }
|
|
|
|
##
|
|
# @query-cpu-model-expansion:
|
|
#
|
|
# Expands a given CPU model, @model, (or a combination of CPU model +
|
|
# additional options) to different granularities, specified by
|
|
# @type, allowing tooling to get an understanding what a specific
|
|
# CPU model looks like in QEMU under a certain configuration.
|
|
#
|
|
# This interface can be used to query the "host" CPU model.
|
|
#
|
|
# The data returned by this command may be affected by:
|
|
#
|
|
# * QEMU version: CPU models may look different depending on the QEMU
|
|
# version. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * machine-type: CPU model may look different depending on the
|
|
# machine-type. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * machine options (including accelerator): in some architectures,
|
|
# CPU models may look different depending on machine and accelerator
|
|
# options. (Except for CPU models reported as "static" in
|
|
# query-cpu-definitions.)
|
|
# * "-cpu" arguments and global properties: arguments to the -cpu
|
|
# option and global properties may affect expansion of CPU models.
|
|
# Using query-cpu-model-expansion while using these is not advised.
|
|
#
|
|
# Some architectures may not support all expansion types. s390x
|
|
# supports "full" and "static". Arm only supports "full".
|
|
#
|
|
# @model: description of the CPU model to expand
|
|
#
|
|
# @type: expansion type, specifying how to expand the CPU model
|
|
#
|
|
# Returns: a CpuModelExpansionInfo describing the expanded CPU model
|
|
#
|
|
# Errors:
|
|
# - if expanding CPU models is not supported
|
|
# - if the model cannot be expanded
|
|
# - if the model contains an unknown CPU definition name, unknown
|
|
# properties or properties with a wrong type
|
|
# - if an expansion type is not supported
|
|
#
|
|
# Since: 2.8
|
|
##
|
|
{ 'command': 'query-cpu-model-expansion',
|
|
'data': { 'type': 'CpuModelExpansionType',
|
|
'model': 'CpuModelInfo' },
|
|
'returns': 'CpuModelExpansionInfo',
|
|
'if': { 'any': [ 'TARGET_S390X',
|
|
'TARGET_I386',
|
|
'TARGET_ARM',
|
|
'TARGET_LOONGARCH64',
|
|
'TARGET_RISCV' ] } }
|
|
|
|
##
|
|
# @CpuDefinitionInfo:
|
|
#
|
|
# Virtual CPU definition.
|
|
#
|
|
# @name: the name of the CPU definition
|
|
#
|
|
# @migration-safe: whether a CPU definition can be safely used for
|
|
# migration in combination with a QEMU compatibility machine when
|
|
# migrating between different QEMU versions and between hosts with
|
|
# different sets of (hardware or software) capabilities. If not
|
|
# provided, information is not available and callers should not
|
|
# assume the CPU definition to be migration-safe. (since 2.8)
|
|
#
|
|
# @static: whether a CPU definition is static and will not change
|
|
# depending on QEMU version, machine type, machine options and
|
|
# accelerator options. A static model is always migration-safe.
|
|
# (since 2.8)
|
|
#
|
|
# @unavailable-features: List of properties that prevent the CPU model
|
|
# from running in the current host. (since 2.8)
|
|
#
|
|
# @typename: Type name that can be used as argument to
|
|
# @device-list-properties, to introspect properties configurable
|
|
# using -cpu or -global. (since 2.9)
|
|
#
|
|
# @alias-of: Name of CPU model this model is an alias for. The target
|
|
# of the CPU model alias may change depending on the machine type.
|
|
# Management software is supposed to translate CPU model aliases
|
|
# in the VM configuration, because aliases may stop being
|
|
# migration-safe in the future (since 4.1)
|
|
#
|
|
# @deprecated: If true, this CPU model is deprecated and may be
|
|
# removed in in some future version of QEMU according to the QEMU
|
|
# deprecation policy. (since 5.2)
|
|
#
|
|
# @unavailable-features is a list of QOM property names that represent
|
|
# CPU model attributes that prevent the CPU from running. If the QOM
|
|
# property is read-only, that means there's no known way to make the
|
|
# CPU model run in the current host. Implementations that choose not
|
|
# to provide specific information return the property name "type". If
|
|
# the property is read-write, it means that it MAY be possible to run
|
|
# the CPU model in the current host if that property is changed.
|
|
# Management software can use it as hints to suggest or choose an
|
|
# alternative for the user, or just to generate meaningful error
|
|
# messages explaining why the CPU model can't be used. If
|
|
# @unavailable-features is an empty list, the CPU model is runnable
|
|
# using the current host and machine-type. If @unavailable-features
|
|
# is not present, runnability information for the CPU is not
|
|
# available.
|
|
#
|
|
# Since: 1.2
|
|
##
|
|
{ 'struct': 'CpuDefinitionInfo',
|
|
'data': { 'name': 'str',
|
|
'*migration-safe': 'bool',
|
|
'static': 'bool',
|
|
'*unavailable-features': [ 'str' ],
|
|
'typename': 'str',
|
|
'*alias-of' : 'str',
|
|
'deprecated' : 'bool' },
|
|
'if': { 'any': [ 'TARGET_PPC',
|
|
'TARGET_ARM',
|
|
'TARGET_I386',
|
|
'TARGET_S390X',
|
|
'TARGET_MIPS',
|
|
'TARGET_LOONGARCH64',
|
|
'TARGET_RISCV' ] } }
|
|
|
|
##
|
|
# @query-cpu-definitions:
|
|
#
|
|
# Return a list of supported virtual CPU definitions
|
|
#
|
|
# Returns: a list of CpuDefinitionInfo
|
|
#
|
|
# Since: 1.2
|
|
##
|
|
{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
|
|
'if': { 'any': [ 'TARGET_PPC',
|
|
'TARGET_ARM',
|
|
'TARGET_I386',
|
|
'TARGET_S390X',
|
|
'TARGET_MIPS',
|
|
'TARGET_LOONGARCH64',
|
|
'TARGET_RISCV' ] } }
|
|
|
|
##
|
|
# @CpuS390Polarization:
|
|
#
|
|
# An enumeration of CPU polarization that can be assumed by a virtual
|
|
# S390 CPU
|
|
#
|
|
# Since: 8.2
|
|
##
|
|
{ 'enum': 'CpuS390Polarization',
|
|
'prefix': 'S390_CPU_POLARIZATION',
|
|
'data': [ 'horizontal', 'vertical' ],
|
|
'if': 'TARGET_S390X'
|
|
}
|
|
|
|
##
|
|
# @set-cpu-topology:
|
|
#
|
|
# Modify the topology by moving the CPU inside the topology tree, or
|
|
# by changing a modifier attribute of a CPU. Absent values will not
|
|
# be modified.
|
|
#
|
|
# @core-id: the vCPU ID to be moved
|
|
#
|
|
# @socket-id: destination socket to move the vCPU to
|
|
#
|
|
# @book-id: destination book to move the vCPU to
|
|
#
|
|
# @drawer-id: destination drawer to move the vCPU to
|
|
#
|
|
# @entitlement: entitlement to set
|
|
#
|
|
# @dedicated: whether the provisioning of real to virtual CPU is
|
|
# dedicated
|
|
#
|
|
# Features:
|
|
#
|
|
# @unstable: This command is experimental.
|
|
#
|
|
# Since: 8.2
|
|
##
|
|
{ 'command': 'set-cpu-topology',
|
|
'data': {
|
|
'core-id': 'uint16',
|
|
'*socket-id': 'uint16',
|
|
'*book-id': 'uint16',
|
|
'*drawer-id': 'uint16',
|
|
'*entitlement': 'CpuS390Entitlement',
|
|
'*dedicated': 'bool'
|
|
},
|
|
'features': [ 'unstable' ],
|
|
'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] }
|
|
}
|
|
|
|
##
|
|
# @CPU_POLARIZATION_CHANGE:
|
|
#
|
|
# Emitted when the guest asks to change the polarization.
|
|
#
|
|
# The guest can tell the host (via the PTF instruction) whether the
|
|
# CPUs should be provisioned using horizontal or vertical
|
|
# polarization.
|
|
#
|
|
# On horizontal polarization the host is expected to provision all
|
|
# vCPUs equally.
|
|
#
|
|
# On vertical polarization the host can provision each vCPU
|
|
# differently. The guest will get information on the details of the
|
|
# provisioning the next time it uses the STSI(15) instruction.
|
|
#
|
|
# @polarization: polarization specified by the guest
|
|
#
|
|
# Features:
|
|
#
|
|
# @unstable: This event is experimental.
|
|
#
|
|
# Since: 8.2
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# <- { "event": "CPU_POLARIZATION_CHANGE",
|
|
# "data": { "polarization": "horizontal" },
|
|
# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
|
|
##
|
|
{ 'event': 'CPU_POLARIZATION_CHANGE',
|
|
'data': { 'polarization': 'CpuS390Polarization' },
|
|
'features': [ 'unstable' ],
|
|
'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] }
|
|
}
|
|
|
|
##
|
|
# @CpuPolarizationInfo:
|
|
#
|
|
# The result of a CPU polarization query.
|
|
#
|
|
# @polarization: the CPU polarization
|
|
#
|
|
# Since: 8.2
|
|
##
|
|
{ 'struct': 'CpuPolarizationInfo',
|
|
'data': { 'polarization': 'CpuS390Polarization' },
|
|
'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] }
|
|
}
|
|
|
|
##
|
|
# @query-s390x-cpu-polarization:
|
|
#
|
|
# Features:
|
|
#
|
|
# @unstable: This command is experimental.
|
|
#
|
|
# Returns: the machine's CPU polarization
|
|
#
|
|
# Since: 8.2
|
|
##
|
|
{ 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo',
|
|
'features': [ 'unstable' ],
|
|
'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] }
|
|
}
|