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 ##
   8 # @CpuModelInfo:
   9 #
  10 # Virtual CPU model.
  11 #
  12 # A CPU model consists of the name of a CPU definition, to which delta
  13 # changes are applied (e.g. features added/removed). Most magic values
  14 # that an architecture might require should be hidden behind the name.
  15 # However, if required, architectures can expose relevant properties.
  16 #
  17 # @name: the name of the CPU definition the model is based on
  18 #
  19 # @props: a dictionary of QOM properties to be applied
  20 #
  21 # Since: 2.8
  22 ##
  23 { 'struct': 'CpuModelInfo',
  24   'data': { 'name': 'str',
  25             '*props': 'any' } }
  26
  27 ##
  28 # @CpuModelExpansionType:
  29 #
  30 # An enumeration of CPU model expansion types.
  31 #
  32 # @static: Expand to a static CPU model, a combination of a static
  33 #     base model name and property delta changes.  As the static base
  34 #     model will never change, the expanded CPU model will be the
  35 #     same, independent of QEMU version, machine type, machine
  36 #     options, and accelerator options.  Therefore, the resulting
  37 #     model can be used by tooling without having to specify a
  38 #     compatibility machine - e.g. when displaying the "host" model.
  39 #     The @static CPU models are migration-safe.
  40 #
  41 # @full: Expand all properties.  The produced model is not guaranteed
  42 #     to be migration-safe, but allows tooling to get an insight and
  43 #     work with model details.
  44 #
  45 # Note: When a non-migration-safe CPU model is expanded in static
  46 #     mode, some features enabled by the CPU model may be omitted,
  47 #     because they can't be implemented by a static CPU model
  48 #     definition (e.g. cache info passthrough and PMU passthrough in
  49 #     x86). If you need an accurate representation of the features
  50 #     enabled by a non-migration-safe CPU model, use @full.  If you
  51 #     need a static representation that will keep ABI compatibility
  52 #     even when changing QEMU version or machine-type, use @static
  53 #     (but keep in mind that some features may be omitted).
  54 #
  55 # Since: 2.8
  56 ##
  57 { 'enum': 'CpuModelExpansionType',
  58   'data': [ 'static', 'full' ] }
  59
  60 ##
  61 # @CpuModelCompareResult:
  62 #
  63 # An enumeration of CPU model comparison results.  The result is
  64 # usually calculated using e.g. CPU features or CPU generations.
  65 #
  66 # @incompatible: If model A is incompatible to model B, model A is not
  67 #     guaranteed to run where model B runs and the other way around.
  68 #
  69 # @identical: If model A is identical to model B, model A is
  70 #     guaranteed to run where model B runs and the other way around.
  71 #
  72 # @superset: If model A is a superset of model B, model B is
  73 #     guaranteed to run where model A runs.  There are no guarantees
  74 #     about the other way.
  75 #
  76 # @subset: If model A is a subset of model B, model A is guaranteed to
  77 #     run where model B runs.  There are no guarantees about the other
  78 #     way.
  79 #
  80 # Since: 2.8
  81 ##
  82 { 'enum': 'CpuModelCompareResult',
  83   'data': [ 'incompatible', 'identical', 'superset', 'subset' ] }
  84
  85 ##
  86 # @CpuModelBaselineInfo:
  87 #
  88 # The result of a CPU model baseline.
  89 #
  90 # @model: the baselined CpuModelInfo.
  91 #
  92 # Since: 2.8
  93 ##
  94 { 'struct': 'CpuModelBaselineInfo',
  95   'data': { 'model': 'CpuModelInfo' },
  96   'if': 'TARGET_S390X' }
  97
  98 ##
  99 # @CpuModelCompareInfo:
 100 #
 101 # The result of a CPU model comparison.
 102 #
 103 # @result: The result of the compare operation.
 104 #
 105 # @responsible-properties: List of properties that led to the
 106 #     comparison result not being identical.
 107 #
 108 # @responsible-properties is a list of QOM property names that led to
 109 # both CPUs not being detected as identical.  For identical models,
 110 # this list is empty.  If a QOM property is read-only, that means
 111 # there's no known way to make the CPU models identical.  If the
 112 # special property name "type" is included, the models are by
 113 # definition not identical and cannot be made identical.
 114 #
 115 # Since: 2.8
 116 ##
 117 { 'struct': 'CpuModelCompareInfo',
 118   'data': { 'result': 'CpuModelCompareResult',
 119             'responsible-properties': ['str'] },
 120   'if': 'TARGET_S390X' }
 121
 122 ##
 123 # @query-cpu-model-comparison:
 124 #
 125 # Compares two CPU models, returning how they compare in a specific
 126 # configuration.  The results indicates how both models compare
 127 # regarding runnability.  This result can be used by tooling to make
 128 # decisions if a certain CPU model will run in a certain configuration
 129 # or if a compatible CPU model has to be created by baselining.
 130 #
 131 # Usually, a CPU model is compared against the maximum possible CPU
 132 # model of a certain configuration (e.g. the "host" model for KVM).
 133 # If that CPU model is identical or a subset, it will run in that
 134 # configuration.
 135 #
 136 # The result returned by this command may be affected by:
 137 #
 138 # * QEMU version: CPU models may look different depending on the QEMU
 139 #   version.  (Except for CPU models reported as "static" in
 140 #   query-cpu-definitions.)
 141 # * machine-type: CPU model may look different depending on the
 142 #   machine-type.  (Except for CPU models reported as "static" in
 143 #   query-cpu-definitions.)
 144 # * machine options (including accelerator): in some architectures,
 145 #   CPU models may look different depending on machine and accelerator
 146 #   options.  (Except for CPU models reported as "static" in
 147 #   query-cpu-definitions.)
 148 # * "-cpu" arguments and global properties: arguments to the -cpu
 149 #   option and global properties may affect expansion of CPU models.
 150 #   Using query-cpu-model-expansion while using these is not advised.
 151 #
 152 # Some architectures may not support comparing CPU models.  s390x
 153 # supports comparing CPU models.
 154 #
 155 # Returns: a CpuModelBaselineInfo.  Returns an error if comparing CPU
 156 #     models is not supported, if a model cannot be used, if a model
 157 #     contains an unknown cpu definition name, unknown properties or
 158 #     properties with wrong types.
 159 #
 160 # Note: this command isn't specific to s390x, but is only implemented
 161 #     on this architecture currently.
 162 #
 163 # Since: 2.8
 164 ##
 165 { 'command': 'query-cpu-model-comparison',
 166   'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' },
 167   'returns': 'CpuModelCompareInfo',
 168   'if': 'TARGET_S390X' }
 169
 170 ##
 171 # @query-cpu-model-baseline:
 172 #
 173 # Baseline two CPU models, creating a compatible third model.  The
 174 # created model will always be a static, migration-safe CPU model (see
 175 # "static" CPU model expansion for details).
 176 #
 177 # This interface can be used by tooling to create a compatible CPU
 178 # model out two CPU models.  The created CPU model will be identical
 179 # to or a subset of both CPU models when comparing them.  Therefore,
 180 # the created CPU model is guaranteed to run where the given CPU
 181 # models run.
 182 #
 183 # The result returned by this command may be affected by:
 184 #
 185 # * QEMU version: CPU models may look different depending on the QEMU
 186 #   version.  (Except for CPU models reported as "static" in
 187 #   query-cpu-definitions.)
 188 # * machine-type: CPU model may look different depending on the
 189 #   machine-type.  (Except for CPU models reported as "static" in
 190 #   query-cpu-definitions.)
 191 # * machine options (including accelerator): in some architectures,
 192 #   CPU models may look different depending on machine and accelerator
 193 #   options.  (Except for CPU models reported as "static" in
 194 #   query-cpu-definitions.)
 195 # * "-cpu" arguments and global properties: arguments to the -cpu
 196 #   option and global properties may affect expansion of CPU models.
 197 #   Using query-cpu-model-expansion while using these is not advised.
 198 #
 199 # Some architectures may not support baselining CPU models.  s390x
 200 # supports baselining CPU models.
 201 #
 202 # Returns: a CpuModelBaselineInfo.  Returns an error if baselining CPU
 203 #     models is not supported, if a model cannot be used, if a model
 204 #     contains an unknown cpu definition name, unknown properties or
 205 #     properties with wrong types.
 206 #
 207 # Note: this command isn't specific to s390x, but is only implemented
 208 #     on this architecture currently.
 209 #
 210 # Since: 2.8
 211 ##
 212 { 'command': 'query-cpu-model-baseline',
 213   'data': { 'modela': 'CpuModelInfo',
 214             'modelb': 'CpuModelInfo' },
 215   'returns': 'CpuModelBaselineInfo',
 216   'if': 'TARGET_S390X' }
 217
 218 ##
 219 # @CpuModelExpansionInfo:
 220 #
 221 # The result of a cpu model expansion.
 222 #
 223 # @model: the expanded CpuModelInfo.
 224 #
 225 # Since: 2.8
 226 ##
 227 { 'struct': 'CpuModelExpansionInfo',
 228   'data': { 'model': 'CpuModelInfo' },
 229   'if': { 'any': [ 'TARGET_S390X',
 230                    'TARGET_I386',
 231                    'TARGET_ARM' ] } }
 232
 233 ##
 234 # @query-cpu-model-expansion:
 235 #
 236 # Expands a given CPU model (or a combination of CPU model +
 237 # additional options) to different granularities, allowing tooling to
 238 # get an understanding what a specific CPU model looks like in QEMU
 239 # under a certain configuration.
 240 #
 241 # This interface can be used to query the "host" CPU model.
 242 #
 243 # The data returned by this command may be affected by:
 244 #
 245 # * QEMU version: CPU models may look different depending on the QEMU
 246 #   version.  (Except for CPU models reported as "static" in
 247 #   query-cpu-definitions.)
 248 # * machine-type: CPU model may look different depending on the
 249 #   machine-type.  (Except for CPU models reported as "static" in
 250 #   query-cpu-definitions.)
 251 # * machine options (including accelerator): in some architectures,
 252 #   CPU models may look different depending on machine and accelerator
 253 #   options.  (Except for CPU models reported as "static" in
 254 #   query-cpu-definitions.)
 255 # * "-cpu" arguments and global properties: arguments to the -cpu
 256 #   option and global properties may affect expansion of CPU models.
 257 #   Using query-cpu-model-expansion while using these is not advised.
 258 #
 259 # Some architectures may not support all expansion types.  s390x
 260 # supports "full" and "static". Arm only supports "full".
 261 #
 262 # Returns: a CpuModelExpansionInfo.  Returns an error if expanding CPU
 263 #     models is not supported, if the model cannot be expanded, if the
 264 #     model contains an unknown CPU definition name, unknown
 265 #     properties or properties with a wrong type.  Also returns an
 266 #     error if an expansion type is not supported.
 267 #
 268 # Since: 2.8
 269 ##
 270 { 'command': 'query-cpu-model-expansion',
 271   'data': { 'type': 'CpuModelExpansionType',
 272             'model': 'CpuModelInfo' },
 273   'returns': 'CpuModelExpansionInfo',
 274   'if': { 'any': [ 'TARGET_S390X',
 275                    'TARGET_I386',
 276                    'TARGET_ARM' ] } }
 277
 278 ##
 279 # @CpuDefinitionInfo:
 280 #
 281 # Virtual CPU definition.
 282 #
 283 # @name: the name of the CPU definition
 284 #
 285 # @migration-safe: whether a CPU definition can be safely used for
 286 #     migration in combination with a QEMU compatibility machine when
 287 #     migrating between different QEMU versions and between hosts with
 288 #     different sets of (hardware or software) capabilities.  If not
 289 #     provided, information is not available and callers should not
 290 #     assume the CPU definition to be migration-safe.  (since 2.8)
 291 #
 292 # @static: whether a CPU definition is static and will not change
 293 #     depending on QEMU version, machine type, machine options and
 294 #     accelerator options.  A static model is always migration-safe.
 295 #     (since 2.8)
 296 #
 297 # @unavailable-features: List of properties that prevent the CPU model
 298 #     from running in the current host.  (since 2.8)
 299 #
 300 # @typename: Type name that can be used as argument to
 301 #     @device-list-properties, to introspect properties configurable
 302 #     using -cpu or -global.  (since 2.9)
 303 #
 304 # @alias-of: Name of CPU model this model is an alias for.  The target
 305 #     of the CPU model alias may change depending on the machine type.
 306 #     Management software is supposed to translate CPU model aliases
 307 #     in the VM configuration, because aliases may stop being
 308 #     migration-safe in the future (since 4.1)
 309 #
 310 # @deprecated: If true, this CPU model is deprecated and may be
 311 #     removed in in some future version of QEMU according to the QEMU
 312 #     deprecation policy.  (since 5.2)
 313 #
 314 # @unavailable-features is a list of QOM property names that represent
 315 # CPU model attributes that prevent the CPU from running.  If the QOM
 316 # property is read-only, that means there's no known way to make the
 317 # CPU model run in the current host.  Implementations that choose not
 318 # to provide specific information return the property name "type". If
 319 # the property is read-write, it means that it MAY be possible to run
 320 # the CPU model in the current host if that property is changed.
 321 # Management software can use it as hints to suggest or choose an
 322 # alternative for the user, or just to generate meaningful error
 323 # messages explaining why the CPU model can't be used.  If
 324 # @unavailable-features is an empty list, the CPU model is runnable
 325 # using the current host and machine-type.  If @unavailable-features
 326 # is not present, runnability information for the CPU is not
 327 # available.
 328 #
 329 # Since: 1.2
 330 ##
 331 { 'struct': 'CpuDefinitionInfo',
 332   'data': { 'name': 'str',
 333             '*migration-safe': 'bool',
 334             'static': 'bool',
 335             '*unavailable-features': [ 'str' ],
 336             'typename': 'str',
 337             '*alias-of' : 'str',
 338             'deprecated' : 'bool' },
 339   'if': { 'any': [ 'TARGET_PPC',
 340                    'TARGET_ARM',
 341                    'TARGET_I386',
 342                    'TARGET_S390X',
 343                    'TARGET_MIPS',
 344                    'TARGET_LOONGARCH64',
 345                    'TARGET_RISCV' ] } }
 346
 347 ##
 348 # @query-cpu-definitions:
 349 #
 350 # Return a list of supported virtual CPU definitions
 351 #
 352 # Returns: a list of CpuDefinitionInfo
 353 #
 354 # Since: 1.2
 355 ##
 356 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
 357   'if': { 'any': [ 'TARGET_PPC',
 358                    'TARGET_ARM',
 359                    'TARGET_I386',
 360                    'TARGET_S390X',
 361                    'TARGET_MIPS',
 362                    'TARGET_LOONGARCH64',
 363                    'TARGET_RISCV' ] } }