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{ 'include': 'machine-common.json' } 8 9## 10# @CpuModelInfo: 11# 12# Virtual CPU model. 13# 14# A CPU model consists of the name of a CPU definition, to which delta 15# changes are applied (e.g. features added/removed). Most magic values 16# that an architecture might require should be hidden behind the name. 17# However, if required, architectures can expose relevant properties. 18# 19# @name: the name of the CPU definition the model is based on 20# 21# @props: a dictionary of QOM properties to be applied 22# 23# @deprecated-props: a list of properties that are flagged as deprecated 24# by the CPU vendor. These properties are either a subset of the 25# properties enabled on the CPU model, or a set of properties 26# deprecated across all models for the architecture. 27# 28# Since: 2.8 29## 30{ 'struct': 'CpuModelInfo', 31 'data': { 'name': 'str', 32 '*props': 'any', 33 '*deprecated-props': ['str'] } } 34 35## 36# @CpuModelExpansionType: 37# 38# An enumeration of CPU model expansion types. 39# 40# @static: Expand to a static CPU model, a combination of a static 41# base model name and property delta changes. As the static base 42# model will never change, the expanded CPU model will be the 43# same, independent of QEMU version, machine type, machine 44# options, and accelerator options. Therefore, the resulting 45# model can be used by tooling without having to specify a 46# compatibility machine - e.g. when displaying the "host" model. 47# The @static CPU models are migration-safe. 48# 49# @full: Expand all properties. The produced model is not guaranteed 50# to be migration-safe, but allows tooling to get an insight and 51# work with model details. 52# 53# .. note:: When a non-migration-safe CPU model is expanded in static 54# mode, some features enabled by the CPU model may be omitted, 55# because they can't be implemented by a static CPU model definition 56# (e.g. cache info passthrough and PMU passthrough in x86). If you 57# need an accurate representation of the features enabled by a 58# non-migration-safe CPU model, use @full. If you need a static 59# representation that will keep ABI compatibility even when changing 60# QEMU version or machine-type, use @static (but keep in mind that 61# some features may be omitted). 62# 63# Since: 2.8 64## 65{ 'enum': 'CpuModelExpansionType', 66 'data': [ 'static', 'full' ] } 67 68## 69# @CpuModelCompareResult: 70# 71# An enumeration of CPU model comparison results. The result is 72# usually calculated using e.g. CPU features or CPU generations. 73# 74# @incompatible: If model A is incompatible to model B, model A is not 75# guaranteed to run where model B runs and the other way around. 76# 77# @identical: If model A is identical to model B, model A is 78# guaranteed to run where model B runs and the other way around. 79# 80# @superset: If model A is a superset of model B, model B is 81# guaranteed to run where model A runs. There are no guarantees 82# about the other way. 83# 84# @subset: If model A is a subset of model B, model A is guaranteed to 85# run where model B runs. There are no guarantees about the other 86# way. 87# 88# Since: 2.8 89## 90{ 'enum': 'CpuModelCompareResult', 91 'data': [ 'incompatible', 'identical', 'superset', 'subset' ] } 92 93## 94# @CpuModelBaselineInfo: 95# 96# The result of a CPU model baseline. 97# 98# @model: the baselined CpuModelInfo. 99# 100# Since: 2.8 101## 102{ 'struct': 'CpuModelBaselineInfo', 103 'data': { 'model': 'CpuModelInfo' }, 104 'if': 'TARGET_S390X' } 105 106## 107# @CpuModelCompareInfo: 108# 109# The result of a CPU model comparison. 110# 111# @result: The result of the compare operation. 112# 113# @responsible-properties: List of properties that led to the 114# comparison result not being identical. 115# 116# @responsible-properties is a list of QOM property names that led to 117# both CPUs not being detected as identical. For identical models, 118# this list is empty. If a QOM property is read-only, that means 119# there's no known way to make the CPU models identical. If the 120# special property name "type" is included, the models are by 121# definition not identical and cannot be made identical. 122# 123# Since: 2.8 124## 125{ 'struct': 'CpuModelCompareInfo', 126 'data': { 'result': 'CpuModelCompareResult', 127 'responsible-properties': ['str'] }, 128 'if': 'TARGET_S390X' } 129 130## 131# @query-cpu-model-comparison: 132# 133# Compares two CPU models, @modela and @modelb, returning how they 134# compare in a specific configuration. The results indicates how 135# both models compare regarding runnability. This result can be 136# used by tooling to make decisions if a certain CPU model will 137# run in a certain configuration or if a compatible CPU model has 138# to be created by baselining. 139# 140# Usually, a CPU model is compared against the maximum possible CPU 141# model of a certain configuration (e.g. the "host" model for KVM). 142# If that CPU model is identical or a subset, it will run in that 143# configuration. 144# 145# The result returned by this command may be affected by: 146# 147# * QEMU version: CPU models may look different depending on the QEMU 148# version. (Except for CPU models reported as "static" in 149# query-cpu-definitions.) 150# * machine-type: CPU model may look different depending on the 151# machine-type. (Except for CPU models reported as "static" in 152# query-cpu-definitions.) 153# * machine options (including accelerator): in some architectures, 154# CPU models may look different depending on machine and accelerator 155# options. (Except for CPU models reported as "static" in 156# query-cpu-definitions.) 157# * "-cpu" arguments and global properties: arguments to the -cpu 158# option and global properties may affect expansion of CPU models. 159# Using query-cpu-model-expansion while using these is not advised. 160# 161# Some architectures may not support comparing CPU models. s390x 162# supports comparing CPU models. 163# 164# @modela: description of the first CPU model to compare, referred to as 165# "model A" in CpuModelCompareResult 166# 167# @modelb: description of the second CPU model to compare, referred to as 168# "model B" in CpuModelCompareResult 169# 170# Returns: a CpuModelCompareInfo describing how both CPU models 171# compare 172# 173# Errors: 174# - if comparing CPU models is not supported 175# - if a model cannot be used 176# - if a model contains an unknown cpu definition name, unknown 177# properties or properties with wrong types. 178# 179# .. note:: This command isn't specific to s390x, but is only 180# implemented on this architecture currently. 181# 182# Since: 2.8 183## 184{ 'command': 'query-cpu-model-comparison', 185 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 186 'returns': 'CpuModelCompareInfo', 187 'if': 'TARGET_S390X' } 188 189## 190# @query-cpu-model-baseline: 191# 192# Baseline two CPU models, @modela and @modelb, creating a compatible 193# third model. The created model will always be a static, 194# migration-safe CPU model (see "static" CPU model expansion for details). 195# 196# This interface can be used by tooling to create a compatible CPU 197# model out two CPU models. The created CPU model will be identical 198# to or a subset of both CPU models when comparing them. Therefore, 199# the created CPU model is guaranteed to run where the given CPU 200# models run. 201# 202# The result returned by this command may be affected by: 203# 204# * QEMU version: CPU models may look different depending on the QEMU 205# version. (Except for CPU models reported as "static" in 206# query-cpu-definitions.) 207# * machine-type: CPU model may look different depending on the 208# machine-type. (Except for CPU models reported as "static" in 209# query-cpu-definitions.) 210# * machine options (including accelerator): in some architectures, 211# CPU models may look different depending on machine and accelerator 212# options. (Except for CPU models reported as "static" in 213# query-cpu-definitions.) 214# * "-cpu" arguments and global properties: arguments to the -cpu 215# option and global properties may affect expansion of CPU models. 216# Using query-cpu-model-expansion while using these is not advised. 217# 218# Some architectures may not support baselining CPU models. s390x 219# supports baselining CPU models. 220# 221# @modela: description of the first CPU model to baseline 222# 223# @modelb: description of the second CPU model to baseline 224# 225# Returns: a CpuModelBaselineInfo describing the baselined CPU model 226# 227# Errors: 228# - if baselining CPU models is not supported 229# - if a model cannot be used 230# - if a model contains an unknown cpu definition name, unknown 231# properties or properties with wrong types. 232# 233# .. note:: This command isn't specific to s390x, but is only 234# implemented on this architecture currently. 235# 236# Since: 2.8 237## 238{ 'command': 'query-cpu-model-baseline', 239 'data': { 'modela': 'CpuModelInfo', 240 'modelb': 'CpuModelInfo' }, 241 'returns': 'CpuModelBaselineInfo', 242 'if': 'TARGET_S390X' } 243 244## 245# @CpuModelExpansionInfo: 246# 247# The result of a cpu model expansion. 248# 249# @model: the expanded CpuModelInfo. 250# 251# Since: 2.8 252## 253{ 'struct': 'CpuModelExpansionInfo', 254 'data': { 'model': 'CpuModelInfo' }, 255 'if': { 'any': [ 'TARGET_S390X', 256 'TARGET_I386', 257 'TARGET_ARM', 258 'TARGET_LOONGARCH64', 259 'TARGET_RISCV' ] } } 260 261## 262# @query-cpu-model-expansion: 263# 264# Expands a given CPU model, @model, (or a combination of CPU model + 265# additional options) to different granularities, specified by 266# @type, allowing tooling to get an understanding what a specific 267# CPU model looks like in QEMU under a certain configuration. 268# 269# This interface can be used to query the "host" CPU model. 270# 271# The data returned by this command may be affected by: 272# 273# * QEMU version: CPU models may look different depending on the QEMU 274# version. (Except for CPU models reported as "static" in 275# query-cpu-definitions.) 276# * machine-type: CPU model may look different depending on the 277# machine-type. (Except for CPU models reported as "static" in 278# query-cpu-definitions.) 279# * machine options (including accelerator): in some architectures, 280# CPU models may look different depending on machine and accelerator 281# options. (Except for CPU models reported as "static" in 282# query-cpu-definitions.) 283# * "-cpu" arguments and global properties: arguments to the -cpu 284# option and global properties may affect expansion of CPU models. 285# Using query-cpu-model-expansion while using these is not advised. 286# 287# Some architectures may not support all expansion types. s390x 288# supports "full" and "static". Arm only supports "full". 289# 290# @model: description of the CPU model to expand 291# 292# @type: expansion type, specifying how to expand the CPU model 293# 294# Returns: a CpuModelExpansionInfo describing the expanded CPU model 295# 296# Errors: 297# - if expanding CPU models is not supported 298# - if the model cannot be expanded 299# - if the model contains an unknown CPU definition name, unknown 300# properties or properties with a wrong type 301# - if an expansion type is not supported 302# 303# Since: 2.8 304## 305{ 'command': 'query-cpu-model-expansion', 306 'data': { 'type': 'CpuModelExpansionType', 307 'model': 'CpuModelInfo' }, 308 'returns': 'CpuModelExpansionInfo', 309 'if': { 'any': [ 'TARGET_S390X', 310 'TARGET_I386', 311 'TARGET_ARM', 312 'TARGET_LOONGARCH64', 313 'TARGET_RISCV' ] } } 314 315## 316# @CpuDefinitionInfo: 317# 318# Virtual CPU definition. 319# 320# @name: the name of the CPU definition 321# 322# @migration-safe: whether a CPU definition can be safely used for 323# migration in combination with a QEMU compatibility machine when 324# migrating between different QEMU versions and between hosts with 325# different sets of (hardware or software) capabilities. If not 326# provided, information is not available and callers should not 327# assume the CPU definition to be migration-safe. (since 2.8) 328# 329# @static: whether a CPU definition is static and will not change 330# depending on QEMU version, machine type, machine options and 331# accelerator options. A static model is always migration-safe. 332# (since 2.8) 333# 334# @unavailable-features: List of properties that prevent the CPU model 335# from running in the current host. (since 2.8) 336# 337# @typename: Type name that can be used as argument to 338# @device-list-properties, to introspect properties configurable 339# using -cpu or -global. (since 2.9) 340# 341# @alias-of: Name of CPU model this model is an alias for. The target 342# of the CPU model alias may change depending on the machine type. 343# Management software is supposed to translate CPU model aliases 344# in the VM configuration, because aliases may stop being 345# migration-safe in the future (since 4.1) 346# 347# @deprecated: If true, this CPU model is deprecated and may be 348# removed in in some future version of QEMU according to the QEMU 349# deprecation policy. (since 5.2) 350# 351# @unavailable-features is a list of QOM property names that represent 352# CPU model attributes that prevent the CPU from running. If the QOM 353# property is read-only, that means there's no known way to make the 354# CPU model run in the current host. Implementations that choose not 355# to provide specific information return the property name "type". If 356# the property is read-write, it means that it MAY be possible to run 357# the CPU model in the current host if that property is changed. 358# Management software can use it as hints to suggest or choose an 359# alternative for the user, or just to generate meaningful error 360# messages explaining why the CPU model can't be used. If 361# @unavailable-features is an empty list, the CPU model is runnable 362# using the current host and machine-type. If @unavailable-features 363# is not present, runnability information for the CPU is not 364# available. 365# 366# Since: 1.2 367## 368{ 'struct': 'CpuDefinitionInfo', 369 'data': { 'name': 'str', 370 '*migration-safe': 'bool', 371 'static': 'bool', 372 '*unavailable-features': [ 'str' ], 373 'typename': 'str', 374 '*alias-of' : 'str', 375 'deprecated' : 'bool' }, 376 'if': { 'any': [ 'TARGET_PPC', 377 'TARGET_ARM', 378 'TARGET_I386', 379 'TARGET_S390X', 380 'TARGET_MIPS', 381 'TARGET_LOONGARCH64', 382 'TARGET_RISCV' ] } } 383 384## 385# @query-cpu-definitions: 386# 387# Return a list of supported virtual CPU definitions 388# 389# Returns: a list of CpuDefinitionInfo 390# 391# Since: 1.2 392## 393{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], 394 'if': { 'any': [ 'TARGET_PPC', 395 'TARGET_ARM', 396 'TARGET_I386', 397 'TARGET_S390X', 398 'TARGET_MIPS', 399 'TARGET_LOONGARCH64', 400 'TARGET_RISCV' ] } } 401 402## 403# @CpuS390Polarization: 404# 405# An enumeration of CPU polarization that can be assumed by a virtual 406# S390 CPU 407# 408# Since: 8.2 409## 410{ 'enum': 'CpuS390Polarization', 411 'prefix': 'S390_CPU_POLARIZATION', 412 'data': [ 'horizontal', 'vertical' ], 413 'if': 'TARGET_S390X' 414} 415 416## 417# @set-cpu-topology: 418# 419# Modify the topology by moving the CPU inside the topology tree, or 420# by changing a modifier attribute of a CPU. Absent values will not 421# be modified. 422# 423# @core-id: the vCPU ID to be moved 424# 425# @socket-id: destination socket to move the vCPU to 426# 427# @book-id: destination book to move the vCPU to 428# 429# @drawer-id: destination drawer to move the vCPU to 430# 431# @entitlement: entitlement to set 432# 433# @dedicated: whether the provisioning of real to virtual CPU is 434# dedicated 435# 436# Features: 437# 438# @unstable: This command is experimental. 439# 440# Since: 8.2 441## 442{ 'command': 'set-cpu-topology', 443 'data': { 444 'core-id': 'uint16', 445 '*socket-id': 'uint16', 446 '*book-id': 'uint16', 447 '*drawer-id': 'uint16', 448 '*entitlement': 'CpuS390Entitlement', 449 '*dedicated': 'bool' 450 }, 451 'features': [ 'unstable' ], 452 'if': { 'all': [ 'TARGET_S390X' , 'CONFIG_KVM' ] } 453} 454 455## 456# @CPU_POLARIZATION_CHANGE: 457# 458# Emitted when the guest asks to change the polarization. 459# 460# The guest can tell the host (via the PTF instruction) whether the 461# CPUs should be provisioned using horizontal or vertical 462# polarization. 463# 464# On horizontal polarization the host is expected to provision all 465# vCPUs equally. 466# 467# On vertical polarization the host can provision each vCPU 468# differently. The guest will get information on the details of the 469# provisioning the next time it uses the STSI(15) instruction. 470# 471# @polarization: polarization specified by the guest 472# 473# Features: 474# 475# @unstable: This event is experimental. 476# 477# Since: 8.2 478# 479# .. qmp-example:: 480# 481# <- { "event": "CPU_POLARIZATION_CHANGE", 482# "data": { "polarization": "horizontal" }, 483# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } 484## 485{ 'event': 'CPU_POLARIZATION_CHANGE', 486 'data': { 'polarization': 'CpuS390Polarization' }, 487 'features': [ 'unstable' ], 488 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } 489} 490 491## 492# @CpuPolarizationInfo: 493# 494# The result of a CPU polarization query. 495# 496# @polarization: the CPU polarization 497# 498# Since: 8.2 499## 500{ 'struct': 'CpuPolarizationInfo', 501 'data': { 'polarization': 'CpuS390Polarization' }, 502 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } 503} 504 505## 506# @query-s390x-cpu-polarization: 507# 508# Features: 509# 510# @unstable: This command is experimental. 511# 512# Returns: the machine's CPU polarization 513# 514# Since: 8.2 515## 516{ 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo', 517 'features': [ 'unstable' ], 518 'if': { 'all': [ 'TARGET_S390X', 'CONFIG_KVM' ] } 519} 520