qapi/machine-target.json

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