# -*- 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
+# 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
+# Since: 2.8
##
{ 'struct': 'CpuModelInfo',
'data': { 'name': 'str',
#
# 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
+# @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.
+# 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.
+# 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.
+# @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.
+# @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.
+# @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
+# Since: 2.8
##
{ 'enum': 'CpuModelCompareResult',
'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
#
# @model: the baselined CpuModelInfo.
#
-# Since: 2.8.0
+# Since: 2.8
##
{ 'struct': 'CpuModelBaselineInfo',
'data': { 'model': 'CpuModelInfo' },
- 'if': 'defined(TARGET_S390X)' }
+ '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: 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.
+# 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
+# Since: 2.8
##
{ 'struct': 'CpuModelCompareInfo',
'data': { 'result': 'CpuModelCompareResult',
'responsible-properties': ['str'] },
- 'if': 'defined(TARGET_S390X)' }
+ '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.
+# 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.
+# 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.
+# * 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.
+# on this architecture currently.
#
-# Since: 2.8.0
+# Since: 2.8
##
{ 'command': 'query-cpu-model-comparison',
'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
'returns': 'CpuModelCompareInfo',
- 'if': 'defined(TARGET_S390X)' }
+ '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).
+# 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.
+# 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.
+# * 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.
+# on this architecture currently.
#
-# Since: 2.8.0
+# Since: 2.8
##
{ 'command': 'query-cpu-model-baseline',
'data': { 'modela': 'CpuModelInfo',
'modelb': 'CpuModelInfo' },
'returns': 'CpuModelBaselineInfo',
- 'if': 'defined(TARGET_S390X)' }
+ 'if': 'TARGET_S390X' }
##
# @CpuModelExpansionInfo:
#
# @model: the expanded CpuModelInfo.
#
-# Since: 2.8.0
+# Since: 2.8
##
{ 'struct': 'CpuModelExpansionInfo',
'data': { 'model': 'CpuModelInfo' },
- 'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
+ 'if': { 'any': [ 'TARGET_S390X',
+ 'TARGET_I386',
+ 'TARGET_ARM',
+ 'TARGET_LOONGARCH64',
+ 'TARGET_RISCV' ] } }
##
# @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.
+# 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
+# * 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': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' }
+ 'if': { 'any': [ 'TARGET_S390X',
+ 'TARGET_I386',
+ 'TARGET_ARM',
+ 'TARGET_LOONGARCH64',
+ 'TARGET_RISCV' ] } }
##
# @CpuDefinitionInfo:
# @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
+# 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',
'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)' }
+ '*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 CpuDefInfo
+# Returns: a list of CpuDefinitionInfo
#
-# Since: 1.2.0
+# Since: 1.2
##
{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
- 'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' }
+ '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.
+#
+# Returns: Nothing on success.
+#
+# 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' ] }
+}
projects / mirror_qemu.git / blobdiff