mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
efceb7d2bd
qemu/qapi/machine-target.json
John Snow d461c27973 qapi: convert "Note" sections to plain rST 
We do not need a dedicated section for notes. By eliminating a specially
parsed section, these notes can be treated as normal rST paragraphs in
the new QMP reference manual, and can be placed and styled much more
flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of
the conversion, capitalize the first letter of each sentence and add
trailing punctuation where appropriate to ensure notes look sensible and
consistent in rendered HTML documentation. Markup is also re-aligned to
the de-facto standard of 3 spaces for directives.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and
update the QAPI parser to prohibit "Note" sections while suggesting a
new syntax. The exact formatting to use is a matter of taste, but a good
candidate is simply:

.. note:: lorem ipsum ...
   ... dolor sit amet ...
   ... consectetur adipiscing elit ...

... but there are other choices, too. The Sphinx readthedocs theme
offers theming for the following forms (capitalization unimportant); all
are adorned with a (!) symbol () in the title bar for rendered HTML
docs.

See
https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions
for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

   admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution"
directives. Several instances of "Notes:" have been converted to
merely ".. note::", or multiple ".. note::" where appropriate.
".. admonition:: notes" is used in a few places where we had an
ordered list of multiple notes that would not make sense as
standalone/separate admonitions.  Two "Note:" following "Example:"
have been turned into ordinary paragraphs within the example.

NOTE: Because qapidoc.py does not attempt to preserve source ordering of
sections, the conversion of Notes from a "tagged section" to an
"untagged section" means that rendering order for some notes *may
change* as a result of this patch. The forthcoming qapidoc.py rewrite
strictly preserves source ordering in the rendered documentation, so
this issue will be rectified in the new generator.

Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]
Message-ID: <20240626222128.406106-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message clarified slightly, period added to one more note]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06 08:58:24 +02:00

519 lines
17 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.
{ '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
#
# 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' ] }
}
Reference in New Issue View Git Blame Copy Permalink