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