1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4# This work is licensed under the terms of the GNU GPL, version 2 or later. 5# See the COPYING file in the top-level directory. 6 7## 8# @CpuModelInfo: 9# 10# Virtual CPU model. 11# 12# A CPU model consists of the name of a CPU definition, to which 13# delta changes are applied (e.g. features added/removed). Most magic values 14# that an architecture might require should be hidden behind the name. 15# However, if required, architectures can expose relevant properties. 16# 17# @name: the name of the CPU definition the model is based on 18# @props: a dictionary of QOM properties to be applied 19# 20# Since: 2.8 21## 22{ 'struct': 'CpuModelInfo', 23 'data': { 'name': 'str', 24 '*props': 'any' } } 25 26## 27# @CpuModelExpansionType: 28# 29# An enumeration of CPU model expansion types. 30# 31# @static: Expand to a static CPU model, a combination of a static base 32# model name and property delta changes. As the static base model will 33# never change, the expanded CPU model will be the same, independent of 34# QEMU version, machine type, machine options, and accelerator options. 35# Therefore, the resulting model can be used by tooling without having 36# to specify a compatibility machine - e.g. when displaying the "host" 37# model. The @static CPU models are migration-safe. 38 39# @full: Expand all properties. The produced model is not guaranteed to be 40# migration-safe, but allows tooling to get an insight and work with 41# model details. 42# 43# Note: When a non-migration-safe CPU model is expanded in static mode, some 44# features enabled by the CPU model may be omitted, because they can't be 45# implemented by a static CPU model definition (e.g. cache info passthrough and 46# PMU passthrough in x86). If you need an accurate representation of the 47# features enabled by a non-migration-safe CPU model, use @full. If you need a 48# static representation that will keep ABI compatibility even when changing QEMU 49# version or machine-type, use @static (but keep in mind that some features may 50# be omitted). 51# 52# Since: 2.8 53## 54{ 'enum': 'CpuModelExpansionType', 55 'data': [ 'static', 'full' ] } 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 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 88## 89{ 'struct': 'CpuModelBaselineInfo', 90 'data': { 'model': 'CpuModelInfo' }, 91 'if': '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 110## 111{ 'struct': 'CpuModelCompareInfo', 112 'data': { 'result': 'CpuModelCompareResult', 113 'responsible-properties': ['str'] }, 114 'if': '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 154## 155{ 'command': 'query-cpu-model-comparison', 156 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 157 'returns': 'CpuModelCompareInfo', 158 'if': '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 197## 198{ 'command': 'query-cpu-model-baseline', 199 'data': { 'modela': 'CpuModelInfo', 200 'modelb': 'CpuModelInfo' }, 201 'returns': 'CpuModelBaselineInfo', 202 'if': '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 212## 213{ 'struct': 'CpuModelExpansionInfo', 214 'data': { 'model': 'CpuModelInfo' }, 215 'if': { 'any': [ 'TARGET_S390X', 216 'TARGET_I386', 217 'TARGET_ARM' ] } } 218 219## 220# @query-cpu-model-expansion: 221# 222# Expands a given CPU model (or a combination of CPU model + additional options) 223# to different granularities, allowing tooling to get an understanding what a 224# specific CPU model looks like in QEMU under a certain configuration. 225# 226# This interface can be used to query the "host" CPU model. 227# 228# The data returned by this command may be affected by: 229# 230# * QEMU version: CPU models may look different depending on the QEMU version. 231# (Except for CPU models reported as "static" in query-cpu-definitions.) 232# * machine-type: CPU model may look different depending on the machine-type. 233# (Except for CPU models reported as "static" in query-cpu-definitions.) 234# * machine options (including accelerator): in some architectures, CPU models 235# may look different depending on machine and accelerator options. (Except for 236# CPU models reported as "static" in query-cpu-definitions.) 237# * "-cpu" arguments and global properties: arguments to the -cpu option and 238# global properties may affect expansion of CPU models. Using 239# query-cpu-model-expansion while using these is not advised. 240# 241# Some architectures may not support all expansion types. s390x supports 242# "full" and "static". Arm only supports "full". 243# 244# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is 245# not supported, if the model cannot be expanded, if the model contains 246# an unknown CPU definition name, unknown properties or properties 247# with a wrong type. Also returns an error if an expansion type is 248# not supported. 249# 250# Since: 2.8 251## 252{ 'command': 'query-cpu-model-expansion', 253 'data': { 'type': 'CpuModelExpansionType', 254 'model': 'CpuModelInfo' }, 255 'returns': 'CpuModelExpansionInfo', 256 'if': { 'any': [ 'TARGET_S390X', 257 'TARGET_I386', 258 'TARGET_ARM' ] } } 259 260## 261# @CpuDefinitionInfo: 262# 263# Virtual CPU definition. 264# 265# @name: the name of the CPU definition 266# 267# @migration-safe: whether a CPU definition can be safely used for 268# migration in combination with a QEMU compatibility machine 269# when migrating between different QEMU versions and between 270# hosts with different sets of (hardware or software) 271# capabilities. If not provided, information is not available 272# and callers should not assume the CPU definition to be 273# migration-safe. (since 2.8) 274# 275# @static: whether a CPU definition is static and will not change depending on 276# QEMU version, machine type, machine options and accelerator options. 277# A static model is always migration-safe. (since 2.8) 278# 279# @unavailable-features: List of properties that prevent 280# the CPU model from running in the current 281# host. (since 2.8) 282# @typename: Type name that can be used as argument to @device-list-properties, 283# to introspect properties configurable using -cpu or -global. 284# (since 2.9) 285# 286# @alias-of: Name of CPU model this model is an alias for. The target of the 287# CPU model alias may change depending on the machine type. 288# Management software is supposed to translate CPU model aliases 289# in the VM configuration, because aliases may stop being 290# migration-safe in the future (since 4.1) 291# 292# @deprecated: If true, this CPU model is deprecated and may be removed in 293# in some future version of QEMU according to the QEMU deprecation 294# policy. (since 5.2) 295# 296# @unavailable-features is a list of QOM property names that 297# represent CPU model attributes that prevent the CPU from running. 298# If the QOM property is read-only, that means there's no known 299# way to make the CPU model run in the current host. Implementations 300# that choose not to provide specific information return the 301# property name "type". 302# If the property is read-write, it means that it MAY be possible 303# to run the CPU model in the current host if that property is 304# changed. Management software can use it as hints to suggest or 305# choose an alternative for the user, or just to generate meaningful 306# error messages explaining why the CPU model can't be used. 307# If @unavailable-features is an empty list, the CPU model is 308# runnable using the current host and machine-type. 309# If @unavailable-features is not present, runnability 310# information for the CPU is not available. 311# 312# Since: 1.2 313## 314{ 'struct': 'CpuDefinitionInfo', 315 'data': { 'name': 'str', 316 '*migration-safe': 'bool', 317 'static': 'bool', 318 '*unavailable-features': [ 'str' ], 319 'typename': 'str', 320 '*alias-of' : 'str', 321 'deprecated' : 'bool' }, 322 'if': { 'any': [ 'TARGET_PPC', 323 'TARGET_ARM', 324 'TARGET_I386', 325 'TARGET_S390X', 326 'TARGET_MIPS', 327 'TARGET_LOONGARCH64' ] } } 328 329## 330# @query-cpu-definitions: 331# 332# Return a list of supported virtual CPU definitions 333# 334# Returns: a list of CpuDefInfo 335# 336# Since: 1.2 337## 338{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], 339 'if': { 'any': [ 'TARGET_PPC', 340 'TARGET_ARM', 341 'TARGET_I386', 342 'TARGET_S390X', 343 'TARGET_MIPS', 344 'TARGET_LOONGARCH64' ] } } 345