1# -*- Mode: Python -*- 2# 3# This work is licensed under the terms of the GNU GPL, version 2 or later. 4# See the COPYING file in the top-level directory. 5 6## 7# @CpuModelInfo: 8# 9# Virtual CPU model. 10# 11# A CPU model consists of the name of a CPU definition, to which 12# delta changes are applied (e.g. features added/removed). Most magic values 13# that an architecture might require should be hidden behind the name. 14# However, if required, architectures can expose relevant properties. 15# 16# @name: the name of the CPU definition the model is based on 17# @props: a dictionary of QOM properties to be applied 18# 19# Since: 2.8.0 20## 21{ 'struct': 'CpuModelInfo', 22 'data': { 'name': 'str', 23 '*props': 'any' } } 24 25## 26# @CpuModelExpansionType: 27# 28# An enumeration of CPU model expansion types. 29# 30# @static: Expand to a static CPU model, a combination of a static base 31# model name and property delta changes. As the static base model will 32# never change, the expanded CPU model will be the same, independent of 33# QEMU version, machine type, machine options, and accelerator options. 34# Therefore, the resulting model can be used by tooling without having 35# to specify a compatibility machine - e.g. when displaying the "host" 36# model. The @static CPU models are migration-safe. 37 38# @full: Expand all properties. The produced model is not guaranteed to be 39# migration-safe, but allows tooling to get an insight and work with 40# model details. 41# 42# Note: When a non-migration-safe CPU model is expanded in static mode, some 43# features enabled by the CPU model may be omitted, because they can't be 44# implemented by a static CPU model definition (e.g. cache info passthrough and 45# PMU passthrough in x86). If you need an accurate representation of the 46# features enabled by a non-migration-safe CPU model, use @full. If you need a 47# static representation that will keep ABI compatibility even when changing QEMU 48# version or machine-type, use @static (but keep in mind that some features may 49# be omitted). 50# 51# Since: 2.8.0 52## 53{ 'enum': 'CpuModelExpansionType', 54 'data': [ 'static', 'full' ] } 55 56 57## 58# @CpuModelCompareResult: 59# 60# An enumeration of CPU model comparison results. The result is usually 61# calculated using e.g. CPU features or CPU generations. 62# 63# @incompatible: If model A is incompatible to model B, model A is not 64# guaranteed to run where model B runs and the other way around. 65# 66# @identical: If model A is identical to model B, model A is guaranteed to run 67# where model B runs and the other way around. 68# 69# @superset: If model A is a superset of model B, model B is guaranteed to run 70# where model A runs. There are no guarantees about the other way. 71# 72# @subset: If model A is a subset of model B, model A is guaranteed to run 73# where model B runs. There are no guarantees about the other way. 74# 75# Since: 2.8.0 76## 77{ 'enum': 'CpuModelCompareResult', 78 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } 79 80## 81# @CpuModelBaselineInfo: 82# 83# The result of a CPU model baseline. 84# 85# @model: the baselined CpuModelInfo. 86# 87# Since: 2.8.0 88## 89{ 'struct': 'CpuModelBaselineInfo', 90 'data': { 'model': 'CpuModelInfo' }, 91 'if': 'defined(TARGET_S390X)' } 92 93## 94# @CpuModelCompareInfo: 95# 96# The result of a CPU model comparison. 97# 98# @result: The result of the compare operation. 99# @responsible-properties: List of properties that led to the comparison result 100# not being identical. 101# 102# @responsible-properties is a list of QOM property names that led to 103# both CPUs not being detected as identical. For identical models, this 104# list is empty. 105# If a QOM property is read-only, that means there's no known way to make the 106# CPU models identical. If the special property name "type" is included, the 107# models are by definition not identical and cannot be made identical. 108# 109# Since: 2.8.0 110## 111{ 'struct': 'CpuModelCompareInfo', 112 'data': { 'result': 'CpuModelCompareResult', 113 'responsible-properties': ['str'] }, 114 'if': 'defined(TARGET_S390X)' } 115 116## 117# @query-cpu-model-comparison: 118# 119# Compares two CPU models, returning how they compare in a specific 120# configuration. The results indicates how both models compare regarding 121# runnability. This result can be used by tooling to make decisions if a 122# certain CPU model will run in a certain configuration or if a compatible 123# CPU model has to be created by baselining. 124# 125# Usually, a CPU model is compared against the maximum possible CPU model 126# of a certain configuration (e.g. the "host" model for KVM). If that CPU 127# model is identical or a subset, it will run in that configuration. 128# 129# The result returned by this command may be affected by: 130# 131# * QEMU version: CPU models may look different depending on the QEMU version. 132# (Except for CPU models reported as "static" in query-cpu-definitions.) 133# * machine-type: CPU model may look different depending on the machine-type. 134# (Except for CPU models reported as "static" in query-cpu-definitions.) 135# * machine options (including accelerator): in some architectures, CPU models 136# may look different depending on machine and accelerator options. (Except for 137# CPU models reported as "static" in query-cpu-definitions.) 138# * "-cpu" arguments and global properties: arguments to the -cpu option and 139# global properties may affect expansion of CPU models. Using 140# query-cpu-model-expansion while using these is not advised. 141# 142# Some architectures may not support comparing CPU models. s390x supports 143# comparing CPU models. 144# 145# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU models is 146# not supported, if a model cannot be used, if a model contains 147# an unknown cpu definition name, unknown properties or properties 148# with wrong types. 149# 150# Note: this command isn't specific to s390x, but is only implemented 151# on this architecture currently. 152# 153# Since: 2.8.0 154## 155{ 'command': 'query-cpu-model-comparison', 156 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 157 'returns': 'CpuModelCompareInfo', 158 'if': 'defined(TARGET_S390X)' } 159 160## 161# @query-cpu-model-baseline: 162# 163# Baseline two CPU models, creating a compatible third model. The created 164# model will always be a static, migration-safe CPU model (see "static" 165# CPU model expansion for details). 166# 167# This interface can be used by tooling to create a compatible CPU model out 168# two CPU models. The created CPU model will be identical to or a subset of 169# both CPU models when comparing them. Therefore, the created CPU model is 170# guaranteed to run where the given CPU models run. 171# 172# The result returned by this command may be affected by: 173# 174# * QEMU version: CPU models may look different depending on the QEMU version. 175# (Except for CPU models reported as "static" in query-cpu-definitions.) 176# * machine-type: CPU model may look different depending on the machine-type. 177# (Except for CPU models reported as "static" in query-cpu-definitions.) 178# * machine options (including accelerator): in some architectures, CPU models 179# may look different depending on machine and accelerator options. (Except for 180# CPU models reported as "static" in query-cpu-definitions.) 181# * "-cpu" arguments and global properties: arguments to the -cpu option and 182# global properties may affect expansion of CPU models. Using 183# query-cpu-model-expansion while using these is not advised. 184# 185# Some architectures may not support baselining CPU models. s390x supports 186# baselining CPU models. 187# 188# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU models is 189# not supported, if a model cannot be used, if a model contains 190# an unknown cpu definition name, unknown properties or properties 191# with wrong types. 192# 193# Note: this command isn't specific to s390x, but is only implemented 194# on this architecture currently. 195# 196# Since: 2.8.0 197## 198{ 'command': 'query-cpu-model-baseline', 199 'data': { 'modela': 'CpuModelInfo', 200 'modelb': 'CpuModelInfo' }, 201 'returns': 'CpuModelBaselineInfo', 202 'if': 'defined(TARGET_S390X)' } 203 204## 205# @CpuModelExpansionInfo: 206# 207# The result of a cpu model expansion. 208# 209# @model: the expanded CpuModelInfo. 210# 211# Since: 2.8.0 212## 213{ 'struct': 'CpuModelExpansionInfo', 214 'data': { 'model': 'CpuModelInfo' }, 215 'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' } 216 217## 218# @query-cpu-model-expansion: 219# 220# Expands a given CPU model (or a combination of CPU model + additional options) 221# to different granularities, allowing tooling to get an understanding what a 222# specific CPU model looks like in QEMU under a certain configuration. 223# 224# This interface can be used to query the "host" CPU model. 225# 226# The data returned by this command may be affected by: 227# 228# * QEMU version: CPU models may look different depending on the QEMU version. 229# (Except for CPU models reported as "static" in query-cpu-definitions.) 230# * machine-type: CPU model may look different depending on the machine-type. 231# (Except for CPU models reported as "static" in query-cpu-definitions.) 232# * machine options (including accelerator): in some architectures, CPU models 233# may look different depending on machine and accelerator options. (Except for 234# CPU models reported as "static" in query-cpu-definitions.) 235# * "-cpu" arguments and global properties: arguments to the -cpu option and 236# global properties may affect expansion of CPU models. Using 237# query-cpu-model-expansion while using these is not advised. 238# 239# Some architectures may not support all expansion types. s390x supports 240# "full" and "static". Arm only supports "full". 241# 242# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is 243# not supported, if the model cannot be expanded, if the model contains 244# an unknown CPU definition name, unknown properties or properties 245# with a wrong type. Also returns an error if an expansion type is 246# not supported. 247# 248# Since: 2.8.0 249## 250{ 'command': 'query-cpu-model-expansion', 251 'data': { 'type': 'CpuModelExpansionType', 252 'model': 'CpuModelInfo' }, 253 'returns': 'CpuModelExpansionInfo', 254 'if': 'defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM)' } 255 256## 257# @CpuDefinitionInfo: 258# 259# Virtual CPU definition. 260# 261# @name: the name of the CPU definition 262# 263# @migration-safe: whether a CPU definition can be safely used for 264# migration in combination with a QEMU compatibility machine 265# when migrating between different QEMU versions and between 266# hosts with different sets of (hardware or software) 267# capabilities. If not provided, information is not available 268# and callers should not assume the CPU definition to be 269# migration-safe. (since 2.8) 270# 271# @static: whether a CPU definition is static and will not change depending on 272# QEMU version, machine type, machine options and accelerator options. 273# A static model is always migration-safe. (since 2.8) 274# 275# @unavailable-features: List of properties that prevent 276# the CPU model from running in the current 277# host. (since 2.8) 278# @typename: Type name that can be used as argument to @device-list-properties, 279# to introspect properties configurable using -cpu or -global. 280# (since 2.9) 281# 282# @alias-of: Name of CPU model this model is an alias for. The target of the 283# CPU model alias may change depending on the machine type. 284# Management software is supposed to translate CPU model aliases 285# in the VM configuration, because aliases may stop being 286# migration-safe in the future (since 4.1) 287# 288# @unavailable-features is a list of QOM property names that 289# represent CPU model attributes that prevent the CPU from running. 290# If the QOM property is read-only, that means there's no known 291# way to make the CPU model run in the current host. Implementations 292# that choose not to provide specific information return the 293# property name "type". 294# If the property is read-write, it means that it MAY be possible 295# to run the CPU model in the current host if that property is 296# changed. Management software can use it as hints to suggest or 297# choose an alternative for the user, or just to generate meaningful 298# error messages explaining why the CPU model can't be used. 299# If @unavailable-features is an empty list, the CPU model is 300# runnable using the current host and machine-type. 301# If @unavailable-features is not present, runnability 302# information for the CPU is not available. 303# 304# Since: 1.2.0 305## 306{ 'struct': 'CpuDefinitionInfo', 307 'data': { 'name': 'str', 308 '*migration-safe': 'bool', 309 'static': 'bool', 310 '*unavailable-features': [ 'str' ], 311 'typename': 'str', 312 '*alias-of' : 'str' }, 313 'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' } 314 315## 316# @query-cpu-definitions: 317# 318# Return a list of supported virtual CPU definitions 319# 320# Returns: a list of CpuDefInfo 321# 322# Since: 1.2.0 323## 324{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], 325 'if': 'defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) || defined(TARGET_S390X) || defined(TARGET_MIPS)' } 326