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