qapi/machine-target.json

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