26ec4e53f2
The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.
Make the doc comments more strongly consistent about indentation
for multiline constructs like:
@arg: description line 1
description line 2
Returns: line one
line 2
so that there is always exactly one space after the colon, and
subsequent lines align with the first.
This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace). This does mean that we end up with some
over-length lines.
Note that when the documentation for an argument fits on a single
line like this:
@arg: one line only
then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
326 lines
13 KiB
Python
326 lines
13 KiB
Python
# -*- Mode: 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.
|
|
|
|
##
|
|
# @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
|
|
#
|
|
# Since: 2.8.0
|
|
##
|
|
{ 'struct': 'CpuModelInfo',
|
|
'data': { 'name': 'str',
|
|
'*props': 'any' } }
|
|
|
|
##
|
|
# @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.0
|
|
##
|
|
{ '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.0
|
|
##
|
|
{ 'enum': 'CpuModelCompareResult',
|
|
'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
|
|
|
|
##
|
|
# @CpuModelBaselineInfo:
|
|
#
|
|
# The result of a CPU model baseline.
|
|
#
|
|
# @model: the baselined CpuModelInfo.
|
|
#
|
|
# Since: 2.8.0
|
|
##
|
|
{ 'struct': 'CpuModelBaselineInfo',
|
|
'data': { 'model': 'CpuModelInfo' },
|
|
'if': 'defined(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.0
|
|
##
|
|
{ 'struct': 'CpuModelCompareInfo',
|
|
'data': { 'result': 'CpuModelCompareResult',
|
|
'responsible-properties': ['str'] },
|
|
'if': 'defined(TARGET_S390X)' }
|
|
|
|
##
|
|
# @query-cpu-model-comparison:
|
|
#
|
|
# Compares two CPU models, 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.
|
|
#
|
|
# Returns: a CpuModelBaselineInfo. Returns an error 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.0
|
|
##
|
|
{ 'command': 'query-cpu-model-comparison',
|
|
'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
|
|
'returns': 'CpuModelCompareInfo',
|
|
'if': 'defined(TARGET_S390X)' }
|
|
|
|
##
|
|
# @query-cpu-model-baseline:
|
|
#
|
|
# Baseline two CPU models, 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.
|
|
#
|
|
# Returns: a CpuModelBaselineInfo. Returns an error 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.0
|
|
##
|
|
{ 'command': 'query-cpu-model-baseline',
|
|
'data': { 'modela': 'CpuModelInfo',
|
|
'modelb': 'CpuModelInfo' },
|
|
'returns': 'CpuModelBaselineInfo',
|
|
'if': 'defined(TARGET_S390X)' }
|
|
|
|
##
|
|
# @CpuModelExpansionInfo:
|
|
#
|
|
# The result of a cpu model expansion.
|
|
#
|
|
# @model: the expanded CpuModelInfo.
|
|
#
|
|
# Since: 2.8.0
|
|
##
|
|
{ 'struct': 'CpuModelExpansionInfo',
|
|
'data': { 'model': 'CpuModelInfo' },
|
|
'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
|
|
|
|
##
|
|
# @query-cpu-model-expansion:
|
|
#
|
|
# Expands a given CPU model (or a combination of CPU model + additional options)
|
|
# to different granularities, 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".
|
|
#
|
|
# Returns: a CpuModelExpansionInfo. Returns an error 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. Also returns an error if an expansion type is
|
|
# not supported.
|
|
#
|
|
# Since: 2.8.0
|
|
##
|
|
{ 'command': 'query-cpu-model-expansion',
|
|
'data': { 'type': 'CpuModelExpansionType',
|
|
'model': 'CpuModelInfo' },
|
|
'returns': 'CpuModelExpansionInfo',
|
|
'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
|
|
|
|
##
|
|
# @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)
|
|
#
|
|
# @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.0
|
|
##
|
|
{ 'struct': 'CpuDefinitionInfo',
|
|
'data': { 'name': 'str',
|
|
'*migration-safe': 'bool',
|
|
'static': 'bool',
|
|
'*unavailable-features': [ 'str' ],
|
|
'typename': 'str',
|
|
'*alias-of' : 'str' },
|
|
'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }
|
|
|
|
##
|
|
# @query-cpu-definitions:
|
|
#
|
|
# Return a list of supported virtual CPU definitions
|
|
#
|
|
# Returns: a list of CpuDefInfo
|
|
#
|
|
# Since: 1.2.0
|
|
##
|
|
{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
|
|
'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }
|