machine-target.json (13862B)
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 # @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 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 88 ## 89 { 'struct': 'CpuModelBaselineInfo', 90 'data': { 'model': 'CpuModelInfo' }, 91 'if': '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 110 ## 111 { 'struct': 'CpuModelCompareInfo', 112 'data': { 'result': 'CpuModelCompareResult', 113 'responsible-properties': ['str'] }, 114 'if': '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 154 ## 155 { 'command': 'query-cpu-model-comparison', 156 'data': { 'modela': 'CpuModelInfo', 'modelb': 'CpuModelInfo' }, 157 'returns': 'CpuModelCompareInfo', 158 'if': '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 197 ## 198 { 'command': 'query-cpu-model-baseline', 199 'data': { 'modela': 'CpuModelInfo', 200 'modelb': 'CpuModelInfo' }, 201 'returns': 'CpuModelBaselineInfo', 202 'if': '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 212 ## 213 { 'struct': 'CpuModelExpansionInfo', 214 'data': { 'model': 'CpuModelInfo' }, 215 'if': { 'any': [ 'TARGET_S390X', 216 'TARGET_I386', 217 'TARGET_ARM' ] } } 218 219 ## 220 # @query-cpu-model-expansion: 221 # 222 # Expands a given CPU model (or a combination of CPU model + additional options) 223 # to different granularities, allowing tooling to get an understanding what a 224 # specific CPU model looks like in QEMU under a certain configuration. 225 # 226 # This interface can be used to query the "host" CPU model. 227 # 228 # The data returned by this command may be affected by: 229 # 230 # * QEMU version: CPU models may look different depending on the QEMU version. 231 # (Except for CPU models reported as "static" in query-cpu-definitions.) 232 # * machine-type: CPU model may look different depending on the machine-type. 233 # (Except for CPU models reported as "static" in query-cpu-definitions.) 234 # * machine options (including accelerator): in some architectures, CPU models 235 # may look different depending on machine and accelerator options. (Except for 236 # CPU models reported as "static" in query-cpu-definitions.) 237 # * "-cpu" arguments and global properties: arguments to the -cpu option and 238 # global properties may affect expansion of CPU models. Using 239 # query-cpu-model-expansion while using these is not advised. 240 # 241 # Some architectures may not support all expansion types. s390x supports 242 # "full" and "static". Arm only supports "full". 243 # 244 # Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU models is 245 # not supported, if the model cannot be expanded, if the model contains 246 # an unknown CPU definition name, unknown properties or properties 247 # with a wrong type. Also returns an error if an expansion type is 248 # not supported. 249 # 250 # Since: 2.8 251 ## 252 { 'command': 'query-cpu-model-expansion', 253 'data': { 'type': 'CpuModelExpansionType', 254 'model': 'CpuModelInfo' }, 255 'returns': 'CpuModelExpansionInfo', 256 'if': { 'any': [ 'TARGET_S390X', 257 'TARGET_I386', 258 'TARGET_ARM' ] } } 259 260 ## 261 # @CpuDefinitionInfo: 262 # 263 # Virtual CPU definition. 264 # 265 # @name: the name of the CPU definition 266 # 267 # @migration-safe: whether a CPU definition can be safely used for 268 # migration in combination with a QEMU compatibility machine 269 # when migrating between different QEMU versions and between 270 # hosts with different sets of (hardware or software) 271 # capabilities. If not provided, information is not available 272 # and callers should not assume the CPU definition to be 273 # migration-safe. (since 2.8) 274 # 275 # @static: whether a CPU definition is static and will not change depending on 276 # QEMU version, machine type, machine options and accelerator options. 277 # A static model is always migration-safe. (since 2.8) 278 # 279 # @unavailable-features: List of properties that prevent 280 # the CPU model from running in the current 281 # host. (since 2.8) 282 # @typename: Type name that can be used as argument to @device-list-properties, 283 # to introspect properties configurable using -cpu or -global. 284 # (since 2.9) 285 # 286 # @alias-of: Name of CPU model this model is an alias for. The target of the 287 # CPU model alias may change depending on the machine type. 288 # Management software is supposed to translate CPU model aliases 289 # in the VM configuration, because aliases may stop being 290 # migration-safe in the future (since 4.1) 291 # 292 # @deprecated: If true, this CPU model is deprecated and may be removed in 293 # in some future version of QEMU according to the QEMU deprecation 294 # policy. (since 5.2) 295 # 296 # @unavailable-features is a list of QOM property names that 297 # represent CPU model attributes that prevent the CPU from running. 298 # If the QOM property is read-only, that means there's no known 299 # way to make the CPU model run in the current host. Implementations 300 # that choose not to provide specific information return the 301 # property name "type". 302 # If the property is read-write, it means that it MAY be possible 303 # to run the CPU model in the current host if that property is 304 # changed. Management software can use it as hints to suggest or 305 # choose an alternative for the user, or just to generate meaningful 306 # error messages explaining why the CPU model can't be used. 307 # If @unavailable-features is an empty list, the CPU model is 308 # runnable using the current host and machine-type. 309 # If @unavailable-features is not present, runnability 310 # information for the CPU is not available. 311 # 312 # Since: 1.2 313 ## 314 { 'struct': 'CpuDefinitionInfo', 315 'data': { 'name': 'str', 316 '*migration-safe': 'bool', 317 'static': 'bool', 318 '*unavailable-features': [ 'str' ], 319 'typename': 'str', 320 '*alias-of' : 'str', 321 'deprecated' : 'bool' }, 322 'if': { 'any': [ 'TARGET_PPC', 323 'TARGET_ARM', 324 'TARGET_I386', 325 'TARGET_S390X', 326 'TARGET_MIPS', 327 'TARGET_LOONGARCH64' ] } } 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', 344 'TARGET_LOONGARCH64' ] } }