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