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