qga/qapi-schema: Reformat doc comments to conform to current conventions

[mirror_qemu.git] / qapi / machine-target.json

# -*- 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.

##
# @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
##
{ '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
##
{ '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, 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
##
{ 'command': 'query-cpu-model-comparison',
  'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
  'returns': 'CpuModelCompareInfo',
  'if': '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
##
{ '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' ] } }

##
# @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
##
{ 'command': 'query-cpu-model-expansion',
  'data': { 'type': 'CpuModelExpansionType',
            'model': 'CpuModelInfo' },
  'returns': 'CpuModelExpansionInfo',
  'if': { 'any': [ 'TARGET_S390X',
                   'TARGET_I386',
                   '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)
#
# @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' ] } }