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