OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity
8a85b8ec3d
qemu-e2k/qapi/machine-target.json
Markus Armbruster a937b6aa73 qapi: Reformat doc comments to conform to current conventions 
Change

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #        do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description
indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces
to separate sentences.

To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3".  Finds no
differences.  Comparing with diff is not useful, as the reflown
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-18-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Acked-by: Lukas Straub <lukasstraub2@web.de>
[Straightforward conflicts in qapi/audio.json qapi/misc-target.json
qapi/run-state.json resolved]
2023-05-10 10:01:01 +02:00

364 lines
13 KiB
Python
Raw Blame History

# -*- 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' ] } }
Reference in New Issue View Git Blame Copy Permalink